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. Зовнішні тестувальники — це користувачі, запрошені через email, яким потрібне схвалення рев'ю перед першим встановленням.

Команда fastlane pilot add додає нових тестувальників у групу за email або Apple ID. Pilot автоматично надсилає запрошення та перевіряє, чи прийняв тестувальник інвайт. Для масового додавання можна передати список email з файлу через параметр --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 вмикає надсилання email-сповіщень тестувальникам про нову доступну збірку — це критично для залучення бета-тестерів у процес тестування та прискорення зворотного зв'язку.

Для керування метаданими збірки використовується параметр --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-раннері.

Для коректної роботи 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 профіль.