Fastfile: esența, structura și configurarea automatizării în dezvoltarea mobilă

Ce este Fastfile și de ce este necesar

Fastfile — este principalul fișier de configurare Fastlane, scris în limbajul Ruby și plasat în directorul fastlane din rădăcina proiectului. Acesta definește toate scenariile de automatizare (lanes) pentru construirea, testarea, semnarea codului și livrarea aplicației. Fastfile înlocuiește zeci de scripturi bash, Makefile și instrucțiuni manuale cu o singură descriere declarativă a pipeline-ului CI/CD.

Necesitatea Fastfile apare atunci când proiectul necesită construiri repetabile pe diferite mașini ale dezvoltatorilor și servere CI/CD. În loc ca fiecare dezvoltator să configureze manual mediul, Fastfile înregistrează toți pașii în cod care poate fi versionat în Git, revizuit și reutilizat între proiecte. Un singur Fastfile garantează că construirea pe mașina dezvoltatorului este identică cu construirea pe serverul CI/CD.

Fastfile suportă platforme prin directiva default_platform. Într-un singur Fastfile se pot descrie scenarii pentru iOS, Android și macOS, grupându-le în blocuri platform :ios și platform :android. Acest lucru este deosebit de convenabil pentru proiecte cross-platform, unde construirile iOS și Android au logică comună de deploy, dar instrumente de construire diferite.

Structura Fastfile: lanes, actions și parametri

Fastfile constă din trei elemente principale: declarația platformei (default_platform), definirea lanes și configurarea funcțiilor auxiliare. Fiecare lane începe cu cuvântul cheie lane, urmat de numele scenariului (simbol Ruby), corpul cu secvența de actions și blocuri de gestionare a erorilor error, success sau ensure.

Actions în Fastfile — sunt apeluri ale funcțiilor încorporate Fastlane cu parametri sub formă de Hash. De exemplu, gym(scheme: 'App', export_method: 'app-store') lansează construirea aplicației iOS cu parametrii specificați. Fiecare action returnează un rezultat care poate fi salvat într-o variabilă și utilizat în acțiunile următoare — acest lucru permite construirea logicii condiționale în interiorul lane.

Fastfile suportă variabile de mediu prin mecanismul standard ENV în Ruby. Datele sensibile (parole, token-uri, chei) nu trebuie stocate în Fastfile — folosiți variabile de mediu ale sistemului CI/CD sau fișierul .env care este adăugat în .gitignore. Fastlane încarcă automat fișierele .env din directorul fastlane la pornire.

Appfile și Matchfile

Împreună cu Fastfile, în directorul fastlane se află fișiere de configurare suplimentare. Appfile conține identificatorii aplicației (app_identifier), Apple ID și Team ID — aceste date sunt substituite automat în toate acțiunile, eliminând repetarea în fiecare lane. Matchfile stochează setările pentru match: URL-ul repository-ului Git, tipul profilelor și cheia de criptare.

Împărțirea configurației în mai multe fișiere simplifică întreținerea proiectelor cu medii diferite. De exemplu, pentru staging și production se pot crea ramuri separate în repository-ul Matchfile sau se pot suprascrie parametrii prin variabile de mediu în sistemul CI/CD.

# Structura de bază 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

Sintaxa Fastfile: scrierea lanes

Sintaxa Fastfile se bazează pe Ruby DSL (Domain Specific Language), special conceput pentru lizibilitatea scenariilor de automatizare. Lane este declarat prin construcția lane :name do ... end, unde name este un simbol Ruby care devine comanda fastlane name pentru lansare din terminal sau sistem CI/CD.

În interiorul lane se pot folosi operatori condiționali Ruby: if, unless, case pentru ramificarea logicii. De asemenea, sunt disponibile buclele each și while pentru procesarea array-urilor de valori. Fastlane oferă metode speciale before_all, after_all și blocuri error pentru gestionarea evenimentelor ciclului de viață al lane.

Parametrii lane sunt transmiși prin hash-ul options. La lansarea fastlane build --option_name value, valoarea ajunge în options[:option_name] în interiorul lane. Se pot seta valori implicite prin optional: true și validare type pentru controlul tipurilor parametrilor transmiși.

# Lane cu parametri și logică condițională
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

Exemplu Fastfile pentru livrare iOS

Un Fastfile complet pentru un proiect iOS include lanes pentru instalarea dependințelor, testare, construire și deploy în TestFlight și App Store. Să examinăm un exemplu care acoperă procesul tipic CI/CD de la commit până la publicarea în TestFlight pentru testare internă.

# Fastfile pentru livrare CI/CD iOS
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-ul a fost încărcat în TestFlight pentru testare internă'
  )
end

În acest exemplu, blocul before_all se execută înainte de fiecare lane și instalează dependințele. Lane tests lansează testele UI și unitare pe două dispozitive. Lane build_appstore semnează codul prin match și construiește IPA cu bitcode. Lane deploy_testflight combină toți pașii pentru livrarea completă.

Deploy cu mai multe targeturi

Proiectele cu mai multe targeturi (aplicația principală, watchOS, widget, Notification Service Extension) necesită lanes separate pentru fiecare target. În Fastfile se poate crea un lane universal :deploy_target care primește numele schemei și calea către build ca parametru. Acest lucru permite lansarea deploy-ului pentru toate extensiile prin fastlane deploy_target scheme:Widget.

Pentru organizarea mai multor targeturi, folosiți un array de scheme și bucla each în interiorul lane. Fastlane suportă construirea paralelă a mai multor scheme prin flag-ul parallel: true, ceea ce reduce timpul total al pipeline-ului CI/CD pentru aplicații cu extensii.

Exemplu Fastfile pentru construire Android

Fastfile pentru un proiect Android folosește gradle action pentru lansarea sarcinilor Gradle și supply action pentru publicarea în Google Play. Spre deosebire de iOS, Android nu necesită match, dar folosește Keystore pentru semnare, care este stocat în afara repository-ului și transmis prin variabile de mediu.

# Fastfile pentru construire CI/CD Android
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

Pentru semnarea Android a aplicației, configurați signingConfigs în build.gradle și transmiteți parametrii Keystore prin variabile de mediu: ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS și ANDROID_KEY_PASSWORD. Fastlane folosește automat apksigner-ul sistemului pentru semnarea AAB sau APK construit.

Semnarea Android în Fastfile

Pentru configurarea semnării Android în Fastfile, folosiți action sign_android sau bazați-vă pe signingConfigs în build.gradle. Fastlane se integrează cu apksigner prin Gradle — transmiterea flag-ului SIGNING_CONFIG în gradle task activează semnarea cu parametrii din variabilele de mediu. Acest lucru permite semnarea fișierelor AAB înainte de încărcarea în Google Play Console.

Pentru stocarea sigură a Keystore în CI/CD, folosiți codificarea Base64 și variabilele de mediu. Fastlane suportă action setup_keystore, care decodifică Keystore-ul din variabilă și îl salvează într-un fișier temporar în etapa before_all. După finalizarea lane, fișierul temporar este șters automat pentru a preveni scurgerea certificatelor.

Utilizarea private lanes și grupurilor

Private lanes (scenarii private) — sunt lanes care nu pot fi apelate direct din linia de comandă, dar sunt disponibile pentru apel din alte lanes în interiorul Fastfile. Private lane este declarat prin construcția private_lane :name do ... end și este utilizat pentru încapsularea pașilor repetitivi care nu au sens ca scenarii independente.

Private lanes sunt ideale pentru gruparea logicii repetitive: instalarea dependințelor, configurarea mediului, trimiterea notificărilor. De exemplu, se poate crea un private lane :setup_signing care este apelat din mai multe lanes de deploy, dar nu ar trebui să fie disponibil pentru lansare directă de către dezvoltator pentru a evita erorile.

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

Gruparea lanes prin blocuri platform permite separarea scenariilor pentru iOS și Android într-un singur Fastfile. Construcția platform :ios do ... end și platform :android do ... end izolează lanes platformei corespunzătoare, iar private lanes comune pot fi scoase în afara blocurilor platform pentru reutilizare.

Transmiterea parametrilor către lanes

Mecanismul parametrilor Fastfile permite ca lanes să fie flexibile și reutilizabile. Parametrii sunt transmiși la lansare prin linia de comandă: fastlane build scheme:App export_method:appstore. În interiorul lane, valorile sunt disponibile prin hash-ul options care este transmis blocului lane ca argument.

Fastlane suportă parametri tipizați cu validare prin OptionalHash. Se poate seta tipul valorii (String, Boolean, Integer), valoarea implicită și descrierea pentru generarea automată a documentației. De asemenea, sunt disponibile variabilele de mediu ca metodă alternativă de transmitere a parametrilor, ceea ce este convenabil pentru sistemele CI/CD.

# Parametri cu validare de tipuri
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: "Construirea #{options[:scheme]} finalizată")
end

# Lansare: fastlane build scheme:MyApp export_method:appstore

Se recomandă utilizarea valorilor implicite pentru toți parametrii opționali, astfel încât lane să poată fi lansat fără specificarea explicită a fiecărui argument. Pentru parametrii obligatorii, verificați prezența valorii la începutul lane și întrerupeți execuția cu un mesaj de eroare clar prin UI.user_error!.