Pilot (Fastlane): klíčové pojmy, TestFlight a správa buildů pro mobilní projekty

Co je Pilot (Fastlane)?

Pilot (Fastlane) — je komponenta ekosystému Fastlane pro automatizaci práce s TestFlight — platformou Apple pro beta testování mobilních aplikací. Pilot přebírá všechny rutinní operace: nahrávání buildů, přidávání testerů, správu skupin a sledování stavu buildů.

Bez Pilotu vypadá proces distribuce beta verze takto: vývojář ručně otevře App Store Connect, vybere aplikaci, nahraje IPA přes Xcode Organizer, nakonfiguruje skupinu testerů a odešle pozvánky. TestFlight — je služba Apple pro distribuci beta verzí aplikací mezi testery před oficiálním vydáním v App Store.

Podle App Store Connect Help (2025), externí testeři musí projít procesem Beta App Review před první instalací buildu — to trvá 1 až 48 hodin. Pilot automaticky sleduje stav revize a informuje tým o připravenosti buildu k distribuci mezi externí skupiny testerů.

Používejte Pilot v jakémkoli projektu, kde je vyžadováno pravidelné doručování beta buildů testerům — je to standardní nástroj pro CI/CD pipeline iOS aplikací, zajišťující předvídatelný proces doručování.

Hlavní funkce Pilotu pro TestFlight

Funkcionalita Pilotu pokrývá celý životní cyklus správy beta buildů: od nahrání binárního souboru až po upozornění testerů na novou verzi. Každá funkce je implementována jako samostatný příkaz s předvídatelným chováním a podrobným logováním každého kroku.

Nahrávání buildů do TestFlight

Příkaz fastlane pilot upload nahraje IPA soubor do App Store Connect a vytvoří nový build v TestFlight. Pilot automaticky kontroluje platnost binárního souboru, shodu verze a identifikátoru aplikace. App Store Connect — je platforma Apple pro správu aplikací, včetně nahrávání buildů, metadat, analýzy a prodejních zpráv.

Po nahrání Pilot čeká na zpracování binárního souboru stranou Apple — proces trvá 5 až 30 minut v závislosti na velikosti buildu. Během čekání Pilot zobrazuje ukazatel průběhu s informací o aktuálním stavu zpracování: Processing, Validating nebo Ready. Po úspěšném zpracování je build k dispozici pro přiřazení skupinám testerů.

Správa skupin testerů

Pilot podporuje správu interních i externích skupin testerů. Interní testeři — jsou členové vašeho Apple Developer týmu, kteří získají přístup k buildům okamžitě, bez absolvování Beta App Review. Externí testeři — jsou uživatelé pozvaní e-mailem, kteří vyžadují schválení revize před první instalací.

Příkaz fastlane pilot add přidává nové testery do skupiny e-mailem nebo Apple ID. Pilot automaticky odesílá pozvánky a kontroluje, zda tester pozvánku přijal. Pro hromadné přidání můžete předat seznam e-mailů ze souboru pomocí parametru --testers_file_path, což je vhodné při počátečním sestavování skupiny testerů se stovkami účastníků.

# Nahrání nového buildu do TestFlight
fastlane pilot upload --ipa "build/MyApp.ipa"

# Přidání testera do skupiny
fastlane pilot add --email "tester@company.com" \
      --groups "QA Team"

Nastavení a konfigurace Pilotu

Konfigurace Pilotu nevyžaduje samostatný konfigurační soubor — nastavení se předávají přes Appfile (sdílený soubor Fastlane) nebo argumenty příkazového řádku. Hlavní parametry zahrnují apple_id aplikace, app_identifier, team_id a přihlašovací údaje pro přístup k App Store Connect API.

Pro autentizaci Pilot používá App Store Connect API Key (doporučený způsob) nebo dvoufaktorovou autentizaci Apple ID. App Store Connect API Key — je přístupový klíč generovaný v App Store Connect, který umožňuje interakci s API bez interaktivního zadávání hesla a potvrzovacího kódu.

# Appfile — obecná konfigurace Fastlane
app_identifier("com.company.app")
apple_id("developer@company.com")
team_id("TEAM123456")

# Proměnné prostředí pro Pilot
# APP_STORE_CONNECT_API_KEY_PATH=/path/to/key.p8

Parametr app_identifier určuje Bundle Identifier aplikace, který se musí shodovat s identifikátorem uvedeným v projektu Xcode a App Store Connect. Parametr apple_id se používá pro autentizaci ve dvoufaktorovém schématu a team_id — pro výběr vývojářského týmu, pokud je účet propojen s několika týmy Apple Developer.

Pro fungování Pilotu je nutné nakonfigurovat App Store Connect API Key v prostředí CI/CD. Klíč se generuje v App Store Connect → Users and Access → Keys → Generate API Key. Uložte .p8 soubor do tajemství CI systému a uveďte cestu k němu pomocí proměnné prostředí APP_STORE_CONNECT_API_KEY_PATH nebo parametru --api_key_path v příkazech Pilotu.

Příkazy Pilotu pro správu buildů

Sada příkazů Pilotu pokrývá všechny scénáře práce s TestFlight: nahrávání buildů, správa testerů, zobrazení stavů a sledování metadat. Každý příkaz vrací strukturovaný JSON výstup pro další zpracování v CI/CD skriptech.

Zobrazení stavů buildů

Příkaz fastlane pilot builds zobrazuje seznam všech buildů aplikace s uvedením verze, stavu zpracování a data nahrání. Stav buildu může být jeden z: Processing — Apple zpracovává binární soubor, Ready — build je k dispozici pro distribuci, Rejected — build byl zamítnut kvůli chybám validace.

# Zobrazení seznamu všech buildů v TestFlight
fastlane pilot builds

# Přiřazení buildu skupině testerů
fastlane pilot distribute --build_number 42 \
      --groups "QA Team" --notify

# Zobrazení informací o konkrétním buildu
fastlane pilot build_info --build_number 42

Příkaz fastlane pilot distribute přiřazuje build určeným skupinám testerů a odesílá oznámení. Parametr --notify zapíná odesílání e-mailových oznámení testerům o novém dostupném buildu — to je klíčové pro zapojení beta testerů do procesu testování a urychlení zpětné vazby.

Pro správu metadat buildu se používá parametr --changelog, který nastavuje text popisu změn v nové verzi. Tento text se zobrazuje testerům v pozvánce k testování v aplikaci TestFlight. Doporučuje se uvádět klíčové změny, opravené chyby a nové funkce v každém buildu.

Integrace Pilotu do CI/CD pipeline

Pilot v CI/CD — je závěrečná fáze pipeline doručování iOS aplikace. Poté, co Gym sestaví IPA a testy jsou úspěšné, Pilot nahraje build do TestFlight a distribuuje jej do skupin testerů. To umožňuje QA týmům získat novou verzi aplikace několik minut po commitu do repozitáře.

Typická iOS CI/CD pipeline zahrnuje sekvenci: Match (certifikáty), Gym (sestavení IPA), Pilot (nahrání do TestFlight a distribuce). Každá fáze závisí na předchozí, což zaručuje doručení pouze platných a podepsaných buildů testerům.

# Kompletní pipeline v Fastfile
lane :beta do
    match(type: :appstore)
    gym(scheme: "MyApp", export_method: "app-store")
    pilot("build/MyApp.ipa", groups: ["QA", "PM"])
end

Parametr skip_waiting v příkazu upload umožňuje nečekat na dokončení zpracování binárního souboru Applem v rámci CI úlohy — Pilot odešle požadavek na nahrání, obdrží identifikátor buildu a ukončí práci. To urychluje pipeline, protože zpracování může trvat až 30 minut, které se neztrácí čekáním v CI runneru.

Pro správnou funkci Pilotu v CI je nutné nakonfigurovat API klíč App Store Connect. Uložte .p8 soubor klíče do zabezpečeného úložiště CI systému a předejte cestu pomocí proměnné prostředí APP_STORE_CONNECT_API_KEY_PATH. Pilot používá tento klíč pro autentizaci v API bez dvoufaktorové autentizace, což je klíčové pro automatické scénáře.

Typické problémy při práci s Pilotem

Při používání Pilotu se vývojáři nejčastěji setkávají s chybami autentizace, nesprávnou konfigurací aplikace a problémy se zpracováním binárních souborů Applem. Diagnostika problémů Pilotu začíná kontrolou stavu buildu v App Store Connect pomocí příkazu pilot builds.

Chyba «Your app is not available for testing in TestFlight» nastává, když aplikace není nakonfigurována pro testování v App Store Connect. Řešení: otevřete sekci TestFlight v App Store Connect, aktivujte testování pro aplikaci a ujistěte se, že Export Compliance je správně vyplněn pro váš typ šifrování.

Chyba «Missing iOS Distribution signing identity» ukazuje na chybějící Distribution certifikát v Keychain. Řešení: spusťte Match pro načtení správného certifikátu před voláním Pilotu. Distribution certifikát se liší od Development — používá se pro podepisování buildů určených k distribuci přes TestFlight nebo App Store.

Při chybě «Invalid Provisioning Profile» build obsahuje nesprávný profil pro vybranou metodu exportu. Řešení: zkontrolujte, že Gym používá správný export_method odpovídající typu profilu v Match. Pokud byl build sestaven s vývojovým profilem, Pilot jej nebude moci nahrát do TestFlight — je vyžadován app-store nebo ad-hoc profil.