Fastfile: istota, struktura i konfiguracja automatyzacji w programowaniu mobilnym

Czym jest Fastfile i do czego służy

Fastfile — to główny plik konfiguracyjny Fastlane, napisany w języku Ruby i umieszczany w katalogu fastlane w głównym katalogu projektu. Określa wszystkie scenariusze automatyzacji (lanes) do budowania, testowania, podpisywania kodu i dostarczania aplikacji. Fastfile zastępuje dziesiątki skryptów bash, Makefile i ręcznych instrukcji pojedynczym deklaratywnym opisem potoku CI/CD.

Potrzeba Fastfile pojawia się, gdy projekt wymaga powtarzalnych kompilacji na różnych maszynach deweloperów i serwerach CI/CD. Zamiast każdy deweloper ręcznie konfigurował środowisko, Fastfile zapisuje wszystkie kroki w kodzie, który można wersjonować w Git, przeglądać i ponownie wykorzystywać między projektami. Jeden Fastfile gwarantuje, że kompilacja na maszynie dewelopera jest identyczna z kompilacją na serwerze CI/CD.

Fastfile obsługuje platformy przez dyrektywę default_platform. W jednym Fastfile można opisywać scenariusze dla iOS, Android i macOS, grupując je w bloki platform :ios i platform :android. Jest to szczególnie wygodne dla projektów wieloplatformowych, gdzie kompilacje iOS i Android mają wspólną logikę wdrożenia, ale różne narzędzia kompilacji.

Struktura Fastfile: lanes, actions i parametry

Fastfile składa się z trzech głównych elementów: deklaracja platformy (default_platform), definicja lanes i konfiguracja funkcji pomocniczych. Każdy lane zaczyna się od słowa kluczowego lane, po którym następuje nazwa scenariusza (symbol Ruby), ciało z sekwencją actions i bloki obsługi błędów error, success lub ensure.

Actions w Fastfile — to wywołania wbudowanych funkcji Fastlane z parametrami w formie Hash. Na przykład gym(scheme: 'App', export_method: 'app-store') uruchamia kompilację aplikacji iOS z określonymi parametrami. Każdy action zwraca wynik, który można zapisać w zmiennej i użyć w kolejnych actions — umożliwia to budowanie logiki warunkowej wewnątrz lane.

Fastfile obsługuje zmienne środowiskowe przez standardowy mechanizm ENV w Ruby. Wrażliwe dane (hasła, tokeny, klucze) nie powinny być przechowywane w Fastfile — używaj zmiennych środowiskowych systemu CI/CD lub pliku .env, który jest dodany do .gitignore. Fastlane automatycznie ładuje pliki .env z katalogu fastlane podczas uruchamiania.

Appfile i Matchfile

Razem z Fastfile w katalogu fastlane znajdują się dodatkowe pliki konfiguracyjne. Appfile zawiera identyfikatory aplikacji (app_identifier), Apple ID i Team ID — te dane są automatycznie podstawiane we wszystkich actions, eliminując powtarzanie w każdym lane. Matchfile przechowuje ustawienia dla match: URL repozytorium Git, typ profilów i klucz szyfrowania.

Podział konfiguracji na wiele plików ułatwia obsługę projektów z różnymi środowiskami. Na przykład dla staging i production można utworzyć osobne gałęzie w repozytorium Matchfile lub nadpisywać parametry przez zmienne środowiskowe w systemie CI/CD.

# Podstawowa struktura 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

Składnia Fastfile: pisanie lanes

Składnia Fastfile opiera się na Ruby DSL (Domain Specific Language), specjalnie zaprojektowanym dla czytelności scenariuszy automatyzacji. Lane jest deklarowany przez konstrukcję lane :name do ... end, gdzie name to symbol Ruby, który staje się poleceniem fastlane name do uruchomienia z terminala lub systemu CI/CD.

Wewnątrz lane można używać operatorów warunkowych Ruby: if, unless, case do rozgałęziania logiki. Dostępne są także pętle each i while do przetwarzania tablic wartości. Fastlane udostępnia specjalne metody before_all, after_all i bloki error do obsługi zdarzeń cyklu życia lane.

Parametry lane są przekazywane przez options hash. Przy uruchomieniu fastlane build --option_name value wartość trafia do options[:option_name] wewnątrz lane. Można ustawić wartości domyślne przez optional: true i walidację type do kontroli typów przekazywanych parametrów.

# Lane z parametrami i logiką warunkową
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

Przykład Fastfile dla iOS dostarczania

Pełnowartościowy Fastfile dla projektu iOS zawiera lanes do instalowania zależności, testowania, kompilacji i wdrożenia do TestFlight i App Store. Rozważmy przykład, który obejmuje typowy proces CI/CD od commita do publikacji w TestFlight do testów wewnętrznych.

# Fastfile dla iOS CI/CD dostarczania
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: 'Build przesłany do TestFlight do testów wewnętrznych'
  )
end

W tym przykładzie blok before_all jest wykonywany przed każdym lane i instaluje zależności. Lane tests uruchamia testy UI i jednostkowe na dwóch urządzeniach. Lane build_appstore podpisuje kod przez match i buduje IPA z bitcode. Lane deploy_testflight łączy wszystkie kroki do pełnego wdrożenia.

Wdrożenie z wieloma targetami

Projekty z wieloma targetami (główna aplikacja, watchOS, widget, Notification Service Extension) wymagają osobnych lanes dla każdego targetu. W Fastfile można utworzyć uniwersalny lane :deploy_target, który przyjmuje nazwę schematu i ścieżkę do kompilacji jako parametr. Umożliwia to uruchamianie wdrożenia dla wszystkich rozszerzeń przez fastlane deploy_target scheme:Widget.

Do organizacji wielu targetów użyj tablicy schematów i pętli each wewnątrz lane. Fastlane obsługuje równoległe kompilowanie wielu schematów przez flagę parallel: true, co skraca całkowity czas potoku CI/CD dla aplikacji z rozszerzeniami.

Przykład Fastfile dla Android budowania

Fastfile dla projektu Android używa gradle action do uruchamiania zadań Gradle i supply action do publikacji w Google Play. W przeciwieństwie do iOS, Android nie wymaga match, ale używa Keystore do podpisu, który jest przechowywany poza repozytorium i przekazywany przez zmienne środowiskowe.

# Fastfile dla Android CI/CD budowania
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

Do podpisu Android aplikacji skonfiguruj signingConfigs w build.gradle i przekaż parametry Keystore przez zmienne środowiskowe: ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS i ANDROID_KEY_PASSWORD. Fastlane automatycznie używa systemowego apksigner do podpisu skompilowanego AAB lub APK.

Podpis Android w Fastfile

Do konfiguracji podpisu Android w Fastfile użyj action sign_android lub polegaj na signingConfigs w build.gradle. Fastlane integruje się z apksigner przez Gradle — przekazanie flagi SIGNING_CONFIG w gradle task aktywuje podpis z parametrami ze zmiennych środowiskowych. Umożliwia to podpisywanie plików AAB przed przesłaniem do Google Play Console.

Do bezpiecznego przechowywania Keystore w CI/CD używaj kodowania Base64 i zmiennych środowiskowych. Fastlane obsługuje action setup_keystore, który dekoduje Keystore ze zmiennej i zapisuje do pliku tymczasowego na etapie before_all. Po zakończeniu lane plik tymczasowy jest automatycznie usuwany, aby zapobiec wyciekowi certyfikatów.

Używanie private lanes i grup

Private lanes (scenariusze zamknięte) — to lanes, które nie mogą być wywołane bezpośrednio z wiersza poleceń, ale są dostępne do wywołania z innych lanes wewnątrz Fastfile. Private lane jest deklarowany przez konstrukcję private_lane :name do ... end i służy do enkapsulacji powtarzalnych kroków, które nie mają sensu jako samodzielne scenariusze.

Private lanes idealnie nadają się do grupowania powtarzalnej logiki: instalacja zależności, konfiguracja środowiska, wysyłanie powiadomień. Na przykład można utworzyć private lane :setup_signing, który jest wywoływany z kilku lanes wdrożenia, ale nie powinien być dostępny do bezpośredniego uruchamiania przez dewelopera, aby uniknąć błędów.

# Private lane i grupowanie
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

Grupowanie lanes przez bloki platform pozwala rozdzielić scenariusze dla iOS i Android w jednym Fastfile. Konstrukcja platform :ios do ... end i platform :android do ... end izoluje lanes odpowiedniej platformy, a wspólne private lanes można wynieść poza bloki platform do ponownego wykorzystania.

Przekazywanie parametrów do lanes

Mechanizm parametrów Fastfile pozwala czynić lanes elastycznymi i wielokrotnego użytku. Parametry są przekazywane podczas uruchamiania przez wiersz poleceń: fastlane build scheme:App export_method:appstore. Wewnątrz lane wartości są dostępne przez options hash, który jest przekazywany do bloku lane jako argument.

Fastlane obsługuje parametry typowane z walidacją przez OptionalHash. Można ustawić typ wartości (String, Boolean, Integer), wartość domyślną i opis do automatycznego generowania dokumentacji. Dostępne są także environment variables jako alternatywny sposób przekazywania parametrów, co jest wygodne dla systemów CI/CD.

# Parametry z walidacją typów
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: "Budowa #{options[:scheme]} zakończona")
end

# Uruchomienie: fastlane build scheme:MyApp export_method:appstore

Zaleca się używanie wartości domyślnych dla wszystkich opcjonalnych parametrów, aby lane można było uruchomić bez jawnego określania każdego argumentu. Dla obowiązkowych parametrów sprawdzaj obecność wartości na początku lane i przerywaj wykonanie z czytelnym komunikatem błędu przez UI.user_error!.