Pilot (Fastlane): ключови понятия, TestFlight и управление на билдове за мобилни проекти

Какво е Pilot (Fastlane)?

Pilot (Fastlane) — е компонент на екосистемата Fastlane за автоматизиране на работата с TestFlight — платформата на Apple за бета тестване на мобилни приложения. Pilot поема всички рутинни операции: качване на билдове, добавяне на тестери, управление на групи и проследяване на статус на билдове.

Без Pilot процесът на разпространение на бета версия изглежда така: разработчикът ръчно отваря App Store Connect, избира приложението, качва IPA чрез Xcode Organizer, конфигурира група от тестери и изпраща покани. TestFlight — е услугата на Apple за разпространение на бета версии на приложения сред тестери преди официалното пускане в App Store.

Според App Store Connect Help (2025), външните тестери трябва да преминат през процеса Beta App Review преди първото инсталиране на билд — това отнема от 1 до 48 часа. Pilot автоматично проследява статуса на ревюто и уведомява екипа, когато билдът е готов за разпространение сред външни групи тестери.

Използвайте Pilot във всеки проект, където се изисква редовна доставка на бета билдове до тестери — това е стандартният инструмент за CI/CD пайплайнове на iOS приложения, осигуряващ предвидим процес на доставка.

Основни функции на Pilot за TestFlight

Функционалността на Pilot обхваща пълния жизнен цикъл на управление на бета билдове: от качване на бинарния файл до уведомяване на тестери за нова версия. Всяка функция е реализирана като отделна команда с предвидимо поведение и подробно логване на всяка стъпка.

Качване на билдове в TestFlight

Командата fastlane pilot upload качва IPA файла в App Store Connect и създава нов билд в TestFlight. Pilot автоматично проверява валидността на бинарния файл, съответствието на версията и идентификатора на приложението. App Store Connect — е платформата на Apple за управление на приложения, включително качване на билдове, метаданни, анализи и отчети за продажби.

След качване Pilot изчаква обработка на бинарния файл от страна на Apple — процесът отнема от 5 до 30 минути в зависимост от размера на билда. По време на изчакване Pilot показва лента за напредък с информация за текущия статус на обработка: Processing, Validating или Ready. След успешна обработка билдът става достъпен за назначаване на групи тестери.

Управление на групи от тестери

Pilot поддържа управление както на вътрешни, така и на външни групи тестери. Вътрешните тестери — са членове на вашия екип Apple Developer, които получават достъп до билдове незабавно, без да преминават през Beta App Review. Външните тестери — са потребители, поканени чрез имейл, които се нуждаят от одобрение на ревю преди първото инсталиране.

Командата fastlane pilot add добавя нови тестери в група чрез имейл или Apple ID. Pilot автоматично изпраща покани и проверява дали тестерът е приел поканата. За масово добавяне можете да предадете списък с имейли от файл чрез параметъра --testers_file_path, което е удобно при първоначално събиране на група тестери със стотици участници.

# Качване на нов билд в TestFlight
fastlane pilot upload --ipa "build/MyApp.ipa"

# Добавяне на тестер в група
fastlane pilot add --email "tester@company.com" \
      --groups "QA Team"

Настройка и конфигурация на Pilot

Конфигурацията на Pilot не изисква отделен конфигурационен файл — настройките се предават чрез Appfile (общ файл на Fastlane) или аргументи на командния ред. Основните параметри включват apple_id на приложението, app_identifier, team_id и идентификационни данни за достъп до App Store Connect API.

За удостоверяване Pilot използва App Store Connect API Key (препоръчителен начин) или двуфакторно удостоверяване на Apple ID. App Store Connect API Key — е ключ за достъп, който се генерира в App Store Connect и позволява взаимодействие с API без интерактивно въвеждане на парола и код за потвърждение.

# Appfile — обща конфигурация на Fastlane
app_identifier("com.company.app")
apple_id("developer@company.com")
team_id("TEAM123456")

# Променливи на средата за Pilot
# APP_STORE_CONNECT_API_KEY_PATH=/path/to/key.p8

Параметърът app_identifier определя Bundle Identifier на приложението, който трябва да съвпада с идентификатора, посочен в Xcode проекта и App Store Connect. Параметърът apple_id се използва за удостоверяване в двуфакторната схема, а team_id — за избор на екип за разработка, ако акаунтът е свързан с няколко екипа Apple Developer.

За работа на Pilot е необходимо да се конфигурира App Store Connect API Key в CI/CD средата. Ключът се генерира в App Store Connect → Users and Access → Keys → Generate API Key. Запазете .p8 файла в тайните на CI системата и посочете пътя към него чрез променливата на средата APP_STORE_CONNECT_API_KEY_PATH или параметъра --api_key_path в командите на Pilot.

Команди на Pilot за управление на билдове

Наборът от команди на Pilot покрива всички сценарии за работа с TestFlight: качване на билдове, управление на тестери, преглед на статуси и проследяване на метаданни. Всяка команда връща структуриран JSON изход за по-нататъшна обработка в CI/CD скриптове.

Преглед на статуси на билдове

Командата fastlane pilot builds показва списък на всички билдове на приложението с версия, статус на обработка и дата на качване. Статусът на билд може да бъде един от: Processing — Apple обработва бинарния файл, Ready — билдът е достъпен за разпространение, Rejected — билдът е отхвърлен поради грешки при валидиране.

# Преглед на списък на всички билдове в TestFlight
fastlane pilot builds

# Назначаване на билд на група тестери
fastlane pilot distribute --build_number 42 \
      --groups "QA Team" --notify

# Преглед на информация за конкретен билд
fastlane pilot build_info --build_number 42

Командата fastlane pilot distribute назначава билда на посочените групи тестери и изпраща известия. Параметърът --notify включва изпращане на имейл известия до тестери за нов наличен билд — това е критично за ангажиране на бета тестери в процеса на тестване и ускоряване на обратната връзка.

За управление на метаданни на билд се използва параметърът --changelog, който задава текст на описанието на промените в новата версия. Този текст се показва на тестери в поканата за тестване в приложението TestFlight. Препоръчва се да се посочват ключови промени, поправени грешки и нови функции във всеки билд.

Интеграция на Pilot в CI/CD пайплайн

Pilot в CI/CD — е финалният етап от пайплайна за доставка на iOS приложение. След като Gym изгради IPA и тестовете са преминати, Pilot качва билда в TestFlight и го разпределя по групи тестери. Това позволява на QA екипите да получават новата версия на приложението няколко минути след комит в хранилището.

Типичният iOS CI/CD пайплайн включва последователността: Match (сертификати), Gym (изграждане на IPA), Pilot (качване в TestFlight и разпределение). Всеки етап зависи от предходния, което гарантира доставка само на валидни и подписани билдове до тестери.

# Пълен пайплайн във Fastfile
lane :beta do
    match(type: :appstore)
    gym(scheme: "MyApp", export_method: "app-store")
    pilot("build/MyApp.ipa", groups: ["QA", "PM"])
end

Параметърът skip_waiting в командата upload позволява да не се изчаква завършването на обработката на бинарния файл от Apple в рамките на CI задачата — Pilot изпраща заявка за качване, получава идентификатора на билда и приключва работа. Това ускорява пайплайна, тъй като обработката може да отнеме до 30 минути, които не се губят в чакане в CI runner.

За правилната работа на Pilot в CI е необходимо да се конфигурира API ключът на App Store Connect. Запазете .p8 ключовия файл в защитеното хранилище на CI системата и предайте пътя чрез променливата на средата APP_STORE_CONNECT_API_KEY_PATH. Pilot използва този ключ за удостоверяване в API без двуфакторно удостоверяване, което е критично за автоматични сценарии.

Типични проблеми при работа с Pilot

При използване на Pilot разработчиците най-често се сблъскват с грешки при удостоверяване, неправилна конфигурация на приложението и проблеми с обработката на бинарни файлове от Apple. Диагностиката на проблеми на Pilot започва с проверка на статуса на билд в App Store Connect чрез командата pilot builds.

Грешката «Your app is not available for testing in TestFlight» възниква, когато приложението не е конфигурирано за тестване в App Store Connect. Решение: отворете раздела TestFlight в App Store Connect, активирайте тестването за приложението и се уверете, че Export Compliance е попълнен правилно за вашия тип криптиране.

Грешката «Missing iOS Distribution signing identity» показва липса на Distribution сертификат в Keychain. Решение: стартирайте Match за зареждане на правилния сертификат преди извикване на Pilot. Distribution сертификатът се различава от Development — използва се за подписване на билдове, предназначени за разпространение чрез TestFlight или App Store.

При грешка «Invalid Provisioning Profile» билдът съдържа неправилен профил за избрания метод на експорт. Решение: проверете дали Gym използва правилния export_method, съответстващ на типа профил в Match. Ако билдът е изграден с development профил, Pilot няма да може да го качи в TestFlight — изисква се app-store или ad-hoc профил.