Gym (Fastlane): що це таке, збірка IPA та автоматизація в розробці додатків

Що таке Gym (Fastlane)?

Gym (Fastlane) — це компонент екосистеми Fastlane, який забезпечує збірку iOS-додатків у формат IPA через єдину команду термінала. Він абстрагує складний процес виклику xcodebuild з десятками флагів та надає розробнику простий інтерфейс з розумними значеннями за замовчуванням.

У Xcode для збірки IPA потрібно відкрити проект, вибрати схему, налаштувати Archive та Export, вказати метод поширення та дочекатися завершення. Автоматизація збірки через Gym усунає ручні кроки та гарантує, що кожна збірка виконується з однаковими параметрами — це критично для предбачуваності CI/CD пайплайну.

За даними SwiftLee (2024), команди, які використовують Gym для збірки, витрачають на 40% менше часу на налаштування релізного процесу порівняно з ручним експортом через Xcode Organizer. Gym також генерує детальні логи збірки із зазначенням кожного кроку xcodebuild, що полегшує налагодження невдалих білдів та аналіз помилок компіляції.

Використовуйте Gym в будь-якому iOS-проекті, який потребує регулярної збірки IPA для тестування або публікації — це єдиний спосіб гарантувати ідентичну конфігурацію збірки на всіх машинах команди.

Як Gym збирає IPA: процес та параметри

Процес збірки IPA через Gym

Збірка IPA через Gym складається з трьох послідовних етапів: архівування проекту через xcodebuild, експорт архіву в бінарний пакет та пакування у формат IPA з підписом. Gym автоматично визначає тип проекту (single target або workspace) та обирає коректний метод збірки.

На етапі архівування Gym запускає xcodebuild archive з параметрами схеми та конфігурації, вказаними в проекті. Після успішного створення архіву .xcarchive Gym запускає xcodebuild -exportArchive з вибраним методом експорту. Експорт IPA — це процес перетворення архіву .xcarchive в інсталяційний файл .ipa з усіма необхідними ресурсами та підписами.

Параметри експорту збірки

Метод експорту визначає тип Provisioning Profile, який буде використано для підпису IPA. Gym підтримує чотири методи: development для налагодження на пристроях розробників, app-store для публікації в App Store, ad-hoc для бета-тестування на обмеженій кількості пристроїв та enterprise для корпоративного поширення.

Додаткові параметри включають вказівку export_options_plist для точного налаштування експорту, вилучення Swift overlay для зменшення розміру IPA та керування біткодом. Gym також підтримує збірку для симулятора через флаг --skip_package_ipa, що корисно для швидкої перевірки коду без повного експорту.

# Базовая сборка IPA через Gym
fastlane gym --workspace "MyApp.xcworkspace" --scheme "MyApp"

# Сборка с указанием метода экспорта
fastlane gym --export_method app-store

# Сборка только архива без экспорта IPA
fastlane gym --skip_package_ipa

Налаштування Gym через Gymfile

Gymfile — це конфігураційний файл Fastlane, який зберігає всі параметри збірки в структурованому Ruby-форматі. На відміну від передачі флагів через командний рядок, Gymfile дозволяє зафіксувати конфігурацію в репозиторії та гарантувати, що всі розробники та CI використовують ідентичні налаштування збірки.

# Gymfile — конфигурация сборки
workspace("MyApp.xcworkspace")
scheme("MyApp")
export_method(:app-store)
configuration("Release")
output_directory("./build")
output_name("MyApp.ipa")
include_symbols(true)
include_bitcode(false)

Параметр export_method в Gymfile відповідає типам профілів з Apple Developer Portal. Для релізів App Store використовується :app-store, для тестування — :development або :ad-hoc. Параметр configuration визначає конфігурацію збірки: Release для релізів або Debug для налагоджувальних версій.

Параметр include_bitcode керує включенням біткоду в IPA. Apple вимагав біткод для додатків watchOS та tvOS, але для iOS цей параметр можна вимкнути для зменшення розміру бінарного файлу. include_symbols включає файли символьного налагодження .dSYM, необхідні для символізації креш-логів з App Store Connect або сторонніх сервісів моніторингу.

Додаткові параметри Gymfile включають export_options_plist для кастомного plist-файлу експорту, silent для пригнічення зайвого виведення в логах та build_path для вказівки тимчасової директорії збірки. Ці параметри корисні при інтеграції Gym в складні CI/CD пайплайни з особливими вимогами до артефактів.

Команди Gym для збірки додатків

Інтерфейс команд Gym включає базові параметри для типових сценаріїв збірки та розширені флаги для точного налаштування поведінки. Більшість параметрів можна передати як через командний рядок, так і через Gymfile, причому аргументи командного рядка мають пріоритет над файлом конфігурації.

Команда fastlane gym без параметрів використовує налаштування з Gymfile або автоматично визначає проект в поточній директорії. Для проектів з кількома таргетами потрібно вказувати --scheme та --workspace для коректного вибору цільової конфігурації збірки.

Типові команди збірки

Для швидкої налагоджувальної збірки використовується fastlane gym --export_method development — вона збирає IPA з Development-профілем для встановлення на пристроях розробників. Збірка IPA для App Store потребує флага --export_method app-store та використання Distribution-сертифіката, який повинен бути попередньо налаштований в Match або Keychain.

# Сборка для App Store с кастомным именем
fastlane gym --export_method app-store --output_name "Release_1.0.ipa"

# Сборка с очисткой перед архивацией
fastlane gym --clean --configuration Debug

# Сборка для симулятора без IPA
fastlane gym --skip_package_ipa --destination "generic/platform=iOS Simulator"

Флаг --clean видаляє тимчасові файли попередньої збірки перед запуском, що запобігає використанню застарілого кешу та гарантує чистий білд. Флаг --destination дозволяє вказати цільову платформу для збірки: iOS Simulator, iOS Device або macOS Catalyst.

Інтеграція Gym в CI/CD пайплайн

Інтеграція Gym з CI/CD — стандартна практика для команд iOS-розробників, які прагнуть до неперервної поставки. Gym запускається в пайплайнах GitHub Actions, GitLab CI, Bitrise або Jenkins після етапу тестування та перед відправкою до TestFlight або App Store.

Типовий пайплайн iOS CI/CD включає: клонування репозиторії, встановлення залежностей через CocoaPods або SPM, налаштування сертифікатів через Match, збірку IPA через Gym та завантаження через Pilot або Deliver. GitLab CI — це система неперервної інтеграції від GitLab, яка дозволяє запускати збірки при кожному пуші в репозиторій.

# Пример шага сборки в GitLab CI
fastlane gym --scheme "MyApp" \
      --export_method app-store \
      --output_directory "$CI_PROJECT_DIR/build"
      
# Сохранение IPA как артефакта сборки
cp "build/MyApp.ipa" "$CI_PROJECT_DIR/artifacts/"

Для коректної роботи Gym в CI необхідно налаштувати доступ xcodebuild до Keychain з сертифікатами. Це робиться через команду security unlock-keychain перед запуском Gym. Якщо використовується Match, сертифікати встановлюються автоматично і окреме налаштування Keychain не потрібне — Match сам створює тимчасову зв’язку ключів для збірки.

Після успішної збірки IPA він може бути переданий в наступні кроки пайплайну: завантаження в TestFlight через Pilot або відправка в App Store Connect через Deliver. Налаштуйте змінні середовища CI-системи для зберігання облікових даних Apple Developer, включно FASTLANE_APPLE_API_KEY та MATCH_PASSWORD, щоб всі етапи пайплайну працювали без інтерактивного введення.

Типові помилки збірки Gym

При використанні Gym розробники часто стикаються з помилками, пов’язаними з невірною конфігурацією xcodebuild, відсутністю сертифікатів або несумісністю версій Xcode. Діагностика помилок Gym починається з аналізу повного логу збірки, який виводиться в консоль після кожної команди.

Помилка « error: No matching provisioning profiles found » вказує на відсутність підходящого Provisioning Profile для вибраного методу експорту. Рішення: переконайтеся, що Match або Keychain містить коректний профіль для вказаного export_method. Provisioning Profile повинен відповідати ідентифікатору додатка та типу сертифіката (Development або Distribution) для успішного підпису IPA.

Помилка « error: Signing for requires a development team » виникає, коли в проекті не вказано команду розробки. Рішення: додайте DEVELOPMENT_TEAM в конфігурацію збірки проекту або вкажіть team_id в Gymfile через параметр export_team_id. Це особливо актуально для проектів, які працюють з кількома обліковими записами Apple Developer.

При помилці « error: Multiple commands produce... » виникає конфлікт вихідних файлів між різними таргетами в workspace. Рішення: налаштуйте унікальні шляхи виведення для кожного таргета в Build Settings проекту Xcode або використовуйте нову систему збірки, яка увімкнена за замовчуванням в Xcode 14 та новіших версіях. Gym підтримує обидва варіанти через флаг --use_legacy_build_system.