Fastfile: суть, структура та налаштування автоматизації в мобільній розробці

Що таке Fastfile и для чого он потрібен

Fastfile — це главный конфігураційний файл Fastlane, написанный на мовою Ruby и размещаемый в директорії fastlane в корені проекту. Он определяет все сценарії автоматизації (lanes) для збірки, тестування, подписи кода и доставки приложения. Fastfile замінює десятки bash скриптів, Makefile и ручных инструкций єдиним декларативним описом CI/CD пайплайну.

Необходимость в Fastfile возникает, когда проект требует повторяемых сборок на разных машинах разработчиков и CI/CD серверах. Вместо того чтобы каждый разработчик настраивал окружение вручную, Fastfile фиксирует все шаги в коде, который можно версионировать в Git, ревьювить и переиспользовать между проектуми. Единый Fastfile гарантирует, что сборка на машине разработчика идентична сборке на CI/CD сервере.

Fastfile поддерживает платформы через директиву default_platform. В одном Fastfile можно описывать сценарії для iOS, Android и macOS, группируя их в блоки platform :ios и platform :android. Это особенно удобно для кросс-платформенных проектов, где iOS и Android збірки имеют общую логику деплоя, но разные инструменты збірки.

Структура Fastfile: lanes, actions и параметры

Fastfile состоит из трёх основных элементов: объявление платформы (default_platform), определение lanes и настройка вспомогательных функций. Каждый lane начинается с ключевого слова lane, за которым следует имя сценария (символ Ruby), тело с послідовністю actions и блоки обработки помилок error, success или ensure.

Actions в Fastfile — це вызовы встроенных функций Fastlane с параметрами в виде Hash. Например, gym(scheme: 'App', export_method: 'app-store') запускует сборку iOS приложения с указанными параметрами. Каждый action возвращает результат, который можно сохранить в переменную и использовать в последующих actions — це позволяет строить условную логику внутри lane.

Fastfile поддерживает змінні окружения через стандартный механизм ENV в Ruby. Чувствительные данные (пароли, токены, ключи) не должны храниться в Fastfile — используйте змінні окружения CI/CD системы или файл .env, который добавлен в .gitignore. Fastlane автоматически загружает .env файлы из директорії fastlane при запуске.

Appfile и Matchfile

Вместе с Fastfile в директорії fastlane располагаются дополнительные конфигурационные файлы. Appfile містить идентификаторы приложения (app_identifier), Apple ID и Team ID — эти данные автоматически подставляются во все actions, избавляя от повторения в каждом lane. Matchfile хранит настройки для match: URL Git репозитория, тип профилей и ключ шифрования.

Разделение конфигурации на несколько файлов упрощает поддержку проектов с разными окружениями. Например, для staging и production можно создать отдельные ветки в репозитории Matchfile или переопределять параметры через змінні окружения в CI/CD системе.

# Базова структура Fastfile
default_platform(:ios)

lane :build_and_test do
  cocoapods
  scan(scheme: 'App', devices: ['iPhone 15'])
  gym(scheme: 'App')
end

lane :deploy do
  match(type: 'appstore')
  build_and_test
  pilot(skip_waiting_for_build_processing: true)
end

Синтаксис Fastfile: написання lanes

Синтаксис Fastfile основан на Ruby DSL (Domain Specific Language), специально разработанном для читаемости сценариев автоматизації. Lane объявляется через конструкцию lane :name do ... end, где name — це символ Ruby, который становится командой fastlane name для запуску из терминала или CI/CD системы.

Внутри lane можно использовать условные операторы Ruby: if, unless, case для ветвления логики. Также доступны циклы each и while для обработки массивов значень. Fastlane предоставляет специальные методы before_all, after_all и error блоки для обработки событий жизненного цикла lane.

Параметри lane передаются через options хэш. При запуске fastlane build --option_name value значение попадает в options[:option_name] внутри lane. Можно задать значения по умолчанию через optional: true и type валидацию для контроля типов передаваемых параметров.

# Lane з параметрами та умовною логікою
lane :build do |options|
  scheme = options[:scheme] || 'App'
  export_method = options[:export_method] || 'development'

  match(type: export_method)

  if export_method == 'appstore'
    gym(scheme: scheme, export_method: 'app-store')
    pilot(skip_waiting_for_build_processing: true)
  else
    gym(scheme: scheme, export_method: export_method)
  end
end

Приклад Fastfile для iOS доставки

Полноценный Fastfile для iOS проекту включает lanes для установки зависимостей, тестування, збірки и деплоя в TestFlight и App Store. Рассмотрим пример, который покрывает типовой CI/CD процесс от коммита до публикации в TestFlight для внутреннего тестування.

# Fastfile для iOS CI/CD доставки
default_platform(:ios)

before_all do
  cocoapods(try_repo_update_on_error: true)
  setup_travis if ENV['TRAVIS']
end

lane :tests do
  scan(
    scheme: 'App',
    devices: ['iPhone 15', 'iPad Pro 12.9'],
    output_directory: './test_reports'
  )
end

lane :build_appstore do
  match(type: 'appstore', readonly: true)
  gym(
    scheme: 'App',
    export_method: 'app-store',
    include_bitcode: true
  )
end

lane :deploy_testflight do
  build_appstore
  pilot(
    skip_waiting_for_build_processing: true,
    distribute_external: false
  )
  slack(
    message: 'Білд завантажено в TestFlight для внутрішнього тестування'
  )
end

В цем примере before_all блок выполняется перед каждым lane и устанавливает зависимости. Lane tests запускует UI и Unit тесты на двух устройствах. Lane build_appstore подписывает код через match и собирает IPA с bitcode. Lane deploy_testflight комбинирует все шаги для полной доставки.

Деплой с несколькими таргетами

Проекты с несколькими таргетами (основное приложение, watchOS, widget, Notification Service Extension) требуют отдельных lanes для каждого таргета. В Fastfile можно создать универсальный lane :deploy_target, который принимает имя схемы и путь к билду как параметр. Это позволяет запускуть деплой для всех расширений через fastlane deploy_target scheme:Widget.

Для организации нескольких таргетов используйте массив схем и цикл each внутри lane. Fastlane поддерживает параллельную сборку нескольких схем через флаг parallel: true, что сокращает общее время CI/CD пайплайну для застосунків с расширениями.

Приклад Fastfile для Android збірки

Fastfile для Android проекту использует gradle action для запуску задач Gradle и supply action для публикации в Google Play. В отличие от iOS, Android не требует match, но использует Keystore для подписи, который хранится вне репозитория и передаётся через змінні окружения.

# Fastfile для Android CI/CD збірки
default_platform(:android)

lane :build_release do
  gradle(task: 'clean')
  gradle(task: 'bundleRelease')
  gradle(task: 'assembleRelease')
end

lane :deploy_internal do
  build_release
  supply(
    track: 'internal',
    aab: 'app/build/outputs/bundle/release/app-release.aab',
    release_status: 'completed'
  )
end

Для подписи Android приложения настройте signingConfigs в build.gradle и передайте Keystore параметры через змінні окружения: ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS и ANDROID_KEY_PASSWORD. Fastlane автоматически использует системный apksigner для подписи собранного AAB или APK.

Подпись Android в Fastfile

Для настройки подписи Android в Fastfile используйте action sign_android или полагайтесь на signingConfigs в build.gradle. Fastlane интегрируется с apksigner через Gradle — передача флага SIGNING_CONFIG в gradle task активирует подпись с параметрами из переменных окружения. Это позволяет подписывать AAB файлы перед загрузкой в Google Play Console.

Для безопасного хранения Keystore в CI/CD используйте Base64 кодировку и змінні окружения. Fastlane поддерживает action setup_keystore, который декодирует Keystore из переменной и сохраняет во временный файл на этапе before_all. После завершения lane временный файл автоматически удаляется для предотвращения утечки сертификатов.

Использование private lanes и групп

Private lanes (закрытые сценарії) — це lanes, которые не могут быть вызваны напрямую из командной строки, но доступны для вызова из інших lanes внутри Fastfile. Private lane объявляется через конструкцию private_lane :name do ... end и используется для инкапсуляции повторяющихся шагов, которые не имеют смысла как самостоятельные сценарії.

Private lanes идеально подходят для группировки повторяющейся логики: установка зависимостей, настройка окружения, отправка уведомлений. Например, можно создать private lane :setup_signing, который викликається из нескольких lanes деплоя, но не должен быть доступен для прямого запуску разработчиком, чтобы избежать помилок.

# Private lane та групування
default_platform(:ios)

private_lane :setup_signing do |options|
  match(
    type: options[:type],
    readonly: true,
    verbose: false
  )
end

lane :beta do
  setup_signing(type: 'adhoc')
  gym(export_method: 'ad-hoc')
  pilot(distribute_external: true)
end

lane :release do
  setup_signing(type: 'appstore')
  gym(export_method: 'app-store')
  deliver(
    force: true,
    submit_for_review: true
  )
end

Группировка lanes через platform блоки позволяет разделять сценарії для iOS и Android в одном Fastfile. Конструкция platform :ios do ... end и platform :android do ... end изолирует lanes соответствующей платформы, а общие private lanes можно вынести за пределы платформенных блоков для переиспользования.

Передача параметров в lanes

Механизм параметров Fastfile позволяет делать lanes гибкими и переиспользуемыми. Параметри передаются при запуске через командную строку: fastlane build scheme:App export_method:appstore. Внутри lane значения доступны через options хэш, который передаётся в блок lane в качестве аргумента.

Fastlane поддерживает типизированные параметры с валидацией через OptionalHash. Можно задать тип значения (String, Boolean, Integer), значение по умолчанию и описание для автогенерации документации. Также доступны environment variables как альтернативный способ передачи параметров, что удобно для CI/CD систем.

# Параметри з валідацією типів
lane :build do |options|
  gym(
    scheme: options[:scheme],
    export_method: options[:export_method] || 'development',
    include_bitcode: options[:include_bitcode] || false,
    output_name: options[:output_name]
  )
  slack(message: "Сборка #{options[:scheme]} завершена")
end

# Запуск: fastlane build scheme:MyApp export_method:appstore

Рекомендуется использовать значения по умолчанию для всех необязательных параметров, чтобы lane можно было запустить без явного указания каждого аргумента. Для обязательных параметров проверяйте наличие значения в начале lane и прерывайте выполнение с понятным сообщением об ошибке через UI.user_error!.