Pilot (Fastlane): kulcsfogalmak, TestFlight és build-ek kezelése mobil projektekhez

Mi az a Pilot (Fastlane)?

Pilot (Fastlane) — a Fastlane ökoszisztéma egy komponense a TestFlight-tal — az Apple mobilalkalmazások béta tesztelésére szolgáló platformjával — való munka automatizálására. A Pilot átveszi az összes rutin műveletet: build-ek feltöltése, tesztelők hozzáadása, csoportok kezelése és build-ek állapotának nyomon követése.

Pilot nélkül a béta verzió terjesztési folyamata így néz ki: a fejlesztő manuálisan megnyitja az App Store Connect-et, kiválasztja az alkalmazást, feltölti az IPA-t az Xcode Organizer-en keresztül, beállítja a tesztelői csoportot és elküldi a meghívókat. TestFlight — az Apple szolgáltatása az alkalmazások béta verzióinak tesztelők közötti terjesztésére az App Store-ban történő hivatalos megjelenés előtt.

Az App Store Connect Help (2025) szerint a külső tesztelőknek a build első telepítése előtt át kell esniük a Beta App Review folyamaton — ez 1 és 48 óra közötti időt vesz igénybe. A Pilot automatikusan nyomon követi a felülvizsgálat állapotát, és értesíti a csapatot, amikor a build készen áll a külső tesztelői csoportok számára történő terjesztésre.

Használja a Pilot-ot minden olyan projektben, ahol rendszeres béta build-ek tesztelőknek történő szállítására van szükség — ez a szabványos eszköz az iOS alkalmazások CI/CD pipeline-jaihoz, amely kiszámítható szállítási folyamatot biztosít.

A Pilot fő funkciói a TestFlight-hoz

A Pilot funkcionalitása lefedi a béta build-ek kezelésének teljes életciklusát: a bináris fájl feltöltésétől a tesztelők új verzióról való értesítéséig. Minden funkció külön parancsként van megvalósítva kiszámítható viselkedéssel és minden lépés részletes naplózásával.

Build-ek feltöltése a TestFlight-ba

A fastlane pilot upload parancs feltölti az IPA fájlt az App Store Connect-be, és új build-et hoz létre a TestFlight-ban. A Pilot automatikusan ellenőrzi a bináris fájl érvényességét, a verzió és az alkalmazásazonosító egyezését. App Store Connect — az Apple platformja az alkalmazások kezelésére, beleértve a build-ek feltöltését, metaadatokat, analitikát és értékesítési jelentéseket.

A feltöltés után a Pilot vár a bináris fájl Apple általi feldolgozására — a folyamat 5 és 30 perc között tart a build méretétől függően. A várakozás alatt a Pilot egy folyamatjelző sávot jelenít meg a feldolgozás aktuális állapotával kapcsolatos információkkal: Processing, Validating vagy Ready. Sikeres feldolgozás után a build elérhetővé válik a tesztelői csoportokhoz való hozzárendeléshez.

Tesztelői csoportok kezelése

A Pilot támogatja mind a belső, mind a külső tesztelői csoportok kezelését. Belső tesztelők — az Ön Apple Developer csapatának tagjai, akik azonnal hozzáférést kapnak a build-ekhez, a Beta App Review elvégzése nélkül. Külső tesztelők — e-mailben meghívott felhasználók, akiknek az első telepítés előtt szükségük van a felülvizsgálat jóváhagyására.

A fastlane pilot add parancs új tesztelőket ad hozzá a csoporthoz e-mail vagy Apple ID alapján. A Pilot automatikusan elküldi a meghívókat, és ellenőrzi, hogy a tesztelő elfogadta-e a meghívót. Tömeges hozzáadáshoz átadhatja az e-mailek listáját egy fájlból a --testers_file_path paraméteren keresztül, ami kényelmes a tesztelői csoport kezdeti összeállításakor, amikor száz résztvevőről van szó.

# Új build feltöltése a TestFlight-ba
fastlane pilot upload --ipa "build/MyApp.ipa"

# Tesztelő hozzáadása a csoporthoz
fastlane pilot add --email "tester@company.com" \
      --groups "QA Team"

A Pilot beállítása és konfigurációja

A Pilot konfigurációja nem igényel külön konfigurációs fájlt — a beállítások az Appfile-on (megosztott Fastlane fájl) vagy parancssori argumentumokon keresztül kerülnek átadásra. A fő paraméterek közé tartozik az alkalmazás apple_id-je, app_identifier, team_id és a hitelesítő adatok az App Store Connect API eléréséhez.

Hitelesítéshez a Pilot az App Store Connect API Key-t (ajánlott módszer) vagy az Apple ID kétfaktoros hitelesítést használja. App Store Connect API Key — egy hozzáférési kulcs, amely az App Store Connect-ben jön létre, és lehetővé teszi az API-val való interakciót a jelszó és a megerősítő kód interaktív megadása nélkül.

# Appfile — a Fastlane általános konfigurációja
app_identifier("com.company.app")
apple_id("developer@company.com")
team_id("TEAM123456")

# Környezeti változók a Pilot-hoz
# APP_STORE_CONNECT_API_KEY_PATH=/path/to/key.p8

Az app_identifier paraméter határozza meg az alkalmazás Bundle Identifier-jét, amelynek meg kell egyeznie az Xcode projektben és az App Store Connect-ben megadott azonosítóval. Az apple_id paraméter a kétfaktoros séma szerinti hitelesítéshez, a team_id pedig a fejlesztői csapat kiválasztásához használatos, ha a fiók több Apple Developer csapathoz van kapcsolva.

A Pilot működéséhez be kell állítani az App Store Connect API Key-t a CI/CD környezetben. A kulcs az App Store Connect → Users and Access → Keys → Generate API Key menüpontban jön létre. Mentse el a .p8 fájlt a CI rendszer titkai közé, és adja meg a hozzá vezető útvonalat a APP_STORE_CONNECT_API_KEY_PATH környezeti változón vagy a --api_key_path paraméteren keresztül a Pilot parancsokban.

Pilot parancsok a build-ek kezeléséhez

A Pilot parancskészlete lefedi a TestFlight-tal való munka összes forgatókönyvét: build-ek feltöltése, tesztelők kezelése, állapotok megtekintése és metaadatok nyomon követése. Minden parancs strukturált JSON kimenetet ad vissza a további feldolgozáshoz CI/CD szkriptekben.

Build-ek állapotának megtekintése

A fastlane pilot builds parancs megjeleníti az alkalmazás összes build-jének listáját verzióval, feldolgozási állapottal és feltöltési dátummal. A build állapota a következők egyike lehet: Processing — az Apple feldolgozza a bináris fájlt, Ready — a build elérhető a terjesztéshez, Rejected — a build elutasításra került érvényesítési hibák miatt.

# Az összes build listájának megtekintése a TestFlight-ban
fastlane pilot builds

# Build hozzárendelése a tesztelői csoporthoz
fastlane pilot distribute --build_number 42 \
      --groups "QA Team" --notify

# Adott build információinak megtekintése
fastlane pilot build_info --build_number 42

A fastlane pilot distribute parancs hozzárendeli a build-et a megadott tesztelői csoportokhoz, és értesítéseket küld. A --notify paraméter bekapcsolja az e-mail értesítések küldését a tesztelőknek az új elérhető build-ről — ez kritikus fontosságú a béta tesztelők bevonásához a tesztelési folyamatba és a visszajelzés felgyorsításához.

A build metaadatainak kezeléséhez a --changelog paramétert használjuk, amely az új verzió változásainak leírását adja meg. Ez a szöveg jelenik meg a tesztelőknek a tesztelési meghívóban a TestFlight alkalmazásban. Javasolt a legfontosabb változtatások, javított hibák és új funkciók megadása minden build-ben.

A Pilot integrációja a CI/CD pipeline-ba

Pilot a CI/CD-ben — az iOS alkalmazás szállítási pipeline-jának utolsó szakasza. Miután a Gym felépítette az IPA-t, és a tesztek sikeresen lefutottak, a Pilot feltölti a build-et a TestFlight-ba, és elosztja a tesztelői csoportok között. Ez lehetővé teszi a QA csapatok számára, hogy néhány perccel a repository-ba történő commit után megkapják az alkalmazás új verzióját.

Egy tipikus iOS CI/CD pipeline a következő sorrendet tartalmazza: Match (tanúsítványok), Gym (IPA felépítése), Pilot (feltöltés a TestFlight-ba és terjesztés). Minden szakasz az előzőtől függ, ami garantálja, hogy csak érvényes és aláírt build-ek kerüljenek a tesztelőkhöz.

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

A skip_waiting paraméter az upload parancsban lehetővé teszi, hogy ne várjuk meg a bináris fájl Apple általi feldolgozásának befejezését a CI feladat keretében — a Pilot elküldi a feltöltési kérelmet, megkapja a build azonosítóját, és befejezi a munkát. Ez felgyorsítja a pipeline-t, mivel a feldolgozás akár 30 percig is tarthat, ami nem vész kárba a CI futóban való várakozással.

A Pilot CI-ben való megfelelő működéséhez be kell állítani az App Store Connect API kulcsot. Mentse el a .p8 kulcsfájlt a CI rendszer biztonságos tárolójában, és adja át az útvonalat a APP_STORE_CONNECT_API_KEY_PATH környezeti változón keresztül. A Pilot ezt a kulcsot használja az API-ban történő hitelesítéshez kétfaktoros hitelesítés nélkül, ami kritikus fontosságú az automatikus forgatókönyvekhez.

Gyakori problémák a Pilot használatakor

A Pilot használatakor a fejlesztők leggyakrabban hitelesítési hibákkal, az alkalmazás helytelen konfigurációjával és a bináris fájlok Apple általi feldolgozásának problémáival találkoznak. A problémák diagnosztizálása a Pilot esetében a build állapotának ellenőrzésével kezdődik az App Store Connect-ben a pilot builds parancson keresztül.

A «Your app is not available for testing in TestFlight» hiba akkor fordul elő, ha az alkalmazás nincs beállítva tesztelésre az App Store Connect-ben. Megoldás: nyissa meg a TestFlight szakaszt az App Store Connect-ben, aktiválja a tesztelést az alkalmazáshoz, és győződjön meg arról, hogy az Export Compliance megfelelően van kitöltve az Ön titkosítási típusához.

A «Missing iOS Distribution signing identity» hiba a Distribution tanúsítvány hiányát jelzi a Keychain-ben. Megoldás: futtassa a Match-et a megfelelő tanúsítvány betöltéséhez a Pilot meghívása előtt. A Distribution tanúsítvány eltér a Development-től — a TestFlight-on vagy App Store-on keresztül terjesztésre szánt build-ek aláírására szolgál.

A «Invalid Provisioning Profile» hiba esetén a build helytelen profilt tartalmaz a kiválasztott exportálási módszerhez. Megoldás: ellenőrizze, hogy a Gym a Match-ben lévő profil típusának megfelelő export_method-ot használja. Ha a build fejlesztői profillal készült, a Pilot nem tudja feltölteni a TestFlight-ba — app-store vagy ad-hoc profil szükséges.