Fastfile: lényege, felépítése és az automatizálás beállítása a mobilfejlesztésben

Mi az a Fastfile és miért van rá szükség

A Fastfile a Fastlane fő konfigurációs fájlja, Ruby nyelven íródott, és a projekt gyökerében lévő fastlane könyvtárban található. Meghatározza az összes automatizálási forgatókönyvet (lanes) az alkalmazás összeállításához, teszteléséhez, kód aláírásához és szállításához. A Fastfile tucatnyi bash szkriptet, Makefile-t és kézi utasítást vált ki egyetlen deklaratív CI/CD csővezeték leírással.

A Fastfile-ra akkor van szükség, ha a projekt ismételhető összeállításokat igényel különböző fejlesztői gépeken és CI/CD szervereken. Ahelyett, hogy minden fejlesztő manuálisan állítaná be a környezetet, a Fastfile rögzíti az összes lépést kódban, amely verziókezelhető Git-ben, áttekinthető és újrafelhasználható projektek között. Az egységes Fastfile garantálja, hogy a fejlesztői gépen készült összeállítás megegyezik a CI/CD szerveren készülttel.

A Fastfile támogatja a platformokat a default_platform direktíván keresztül. Egy Fastfile-ban leírhatók iOS, Android és macOS forgatókönyvek, platform :ios és platform :android blokkokba csoportosítva. Ez különösen hasznos a platformok közötti projekteknél, ahol az iOS és Android összeállítások közös telepítési logikával rendelkeznek, de eltérő összeállítási eszközöket használnak.

A Fastfile felépítése: lanes, actions és paraméterek

A Fastfile három fő elemből áll: a platform deklarációja (default_platform), a lanes definíciók és segédfüggvények beállításai. Minden lane a lane kulcsszóval kezdődik, amelyet a forgatókönyv neve (Ruby szimbólum), a műveletsorozatot tartalmazó törzs és hibakezelő blokkok (error, success vagy ensure) követnek.

A Fastfile actions a Fastlane beépített függvényeinek hívásai Hash formátumú paraméterekkel. Például a gym(scheme: 'App', export_method: 'app-store') elindítja az iOS alkalmazás összeállítását a megadott paraméterekkel. Minden action visszaad egy eredményt, amely változóban tárolható és felhasználható a későbbi actions-ökben – ez lehetővé teszi a feltételes logika építését a lane-en belül.

A Fastfile támogatja a környezeti változókat a szabványos Ruby ENV mechanizmuson keresztül. Érzékeny adatok (jelszavak, tokenek, kulcsok) nem tárolandók a Fastfile-ban – használjon környezeti változókat a CI/CD rendszerből vagy .env fájlt, amely hozzá van adva a .gitignore-hoz. A Fastlane automatikusan betölti a .env fájlokat a fastlane könyvtárból indításkor.

Appfile és Matchfile

A Fastfile mellett a fastlane könyvtárban további konfigurációs fájlok találhatók. Az Appfile tartalmazza az alkalmazás azonosítóit (app_identifier), Apple ID-t és Team ID-t – ezek az adatok automatikusan bekerülnek az összes action-be, kiküszöbölve az ismétlést minden lane-ben. A Matchfile tárolja a match beállításait: a Git repository URL-jét, a profilok típusát és a titkosítási kulcsot.

A konfiguráció több fájlra bontása leegyszerűsíti a különböző környezetekkel rendelkező projektek karbantartását. Például staging és production környezetekhez külön ágak hozhatók létre a Matchfile repository-ban, vagy a paraméterek felülírhatók környezeti változókkal a CI/CD rendszerben.

# Fastfile alapszerkezet
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 szintaxis: lanes írása

A Fastfile szintaxisa a Ruby DSL-en (Domain Specific Language) alapul, amelyet kifejezetten az automatizálási forgatókönyvek olvashatóságára terveztek. A lane a lane :név do ... end szerkezettel deklarálódik, ahol a név egy Ruby szimbólum, amely fastlane név parancsként válik elérhetővé a terminálból vagy CI/CD rendszerből történő indításhoz.

A lane-en belül használhatók Ruby feltételes operátorok: if, unless, case a logika elágaztatásához. Ezen kívül elérhetők az each és while ciklusok értéktömbök feldolgozásához. A Fastlane speciális before_all, after_all és error blokkokat biztosít a lane életciklus eseményeinek kezelésére.

A lane paraméterei az options hash-en keresztül adódnak át. A fastlane build --option_name value indításakor az érték az options[:option_name]-be kerül a lane-en belül. Alapértelmezett értékek adhatók meg az optional: true és a type validáció segítségével az átadott paraméterek típusának ellenőrzéséhez.

# Lane paraméterekkel és feltételes logikával
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 példa iOS szállításhoz

Egy teljes körű Fastfile iOS projekthez tartalmaz lanes-eket a függőségek telepítéséhez, teszteléshez, összeállításhoz és a TestFlight-ba, illetve App Store-ba történő telepítéshez. Tekintsünk egy példát, amely lefedi a tipikus CI/CD folyamatot a commit-tól a TestFlight-ban történő belső tesztelésre történő publikálásig.

# Fastfile iOS CI/CD szállításhoz
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: 'Az összeállítás feltöltve a TestFlight-ba belső teszteléshez'
  )
end

Ebben a példában a before_all blokk minden lane előtt végrehajtódik és telepíti a függőségeket. A tests lane elindítja az UI és Unit teszteket két eszközön. A build_appstore lane aláírja a kódot a match segítségével és összeállítja az IPA-t bitcode-dal. A deploy_testflight lane kombinálja az összes lépést a teljes szállításhoz.

Telepítés több célalkalmazással

A több célalkalmazással rendelkező projektek (fő alkalmazás, watchOS, widget, Notification Service Extension) külön lanes-eket igényelnek minden célalkalmazáshoz. A Fastfile-ban létrehozható egy univerzális :deploy_target lane, amely paraméterként fogadja a séma nevét és az összeállítás elérési útját. Ez lehetővé teszi a telepítés futtatását az összes bővítményhez a fastlane deploy_target scheme:Widget parancson keresztül.

Több célalkalmazás szervezéséhez használjon sémák tömbjét és egy each ciklust a lane-en belül. A Fastlane támogatja több séma párhuzamos összeállítását a parallel: true kapcsolón keresztül, ami csökkenti a CI/CD csővezeték teljes idejét bővítményekkel rendelkező alkalmazások esetén.

Fastfile példa Android összeállításhoz

Az Android projekt Fastfile-ja a gradle action-t használja a Gradle feladatok indításához és a supply action-t a Google Play-re történő publikáláshoz. Az iOS-szel ellentétben az Android nem igényel match-et, de Keystore-ot használ az aláíráshoz, amely a repository-n kívül tárolódik és környezeti változókon keresztül adódik át.

# Fastfile Android CI/CD összeállításhoz
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

Az Android aláíráshoz állítsa be a signingConfigs-ot a build.gradle-ben és adja át a Keystore paramétereket környezeti változókon keresztül: ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS és ANDROID_KEY_PASSWORD. A Fastlane automatikusan használja a rendszer apksigner-jét az összeállított AAB vagy APK aláírásához.

Android aláírás a Fastfile-ban

Az Android aláírás beállításához a Fastfile-ban használja a sign_android action-t vagy támaszkodjon a build.gradle signingConfigs-ára. A Fastlane integrálódik az apksigner-rel a Gradle-en keresztül – a SIGNING_CONFIG kapcsoló átadása a gradle feladatnak aktiválja az aláírást a környezeti változók paramétereivel. Ez lehetővé teszi az AAB fájlok aláírását a Google Play Console-ba történő feltöltés előtt.

A Keystore biztonságos tárolásához CI/CD-ben használjon Base64 kódolást és környezeti változókat. A Fastlane támogatja a setup_keystore action-t, amely dekódolja a Keystore-t a változóból és egy ideiglenes fájlba menti a before_all szakaszban. A lane befejezése után az ideiglenes fájl automatikusan törlésre kerül a tanúsítványok kiszivárgásának megakadályozása érdekében.

Private lanes és csoportok használata

A private lanes (zárt forgatókönyvek) olyan lanes-ek, amelyek nem hívhatók meg közvetlenül a parancssorból, de elérhetők más lanes-ekből a Fastfile-on belül. A private lane a private_lane :név do ... end szerkezettel deklarálódik, és ismétlődő lépek beágyazására szolgál, amelyek önálló forgatókönyvként nem értelmezhetők.

A private lanes ideálisak az ismétlődő logika csoportosítására: függőségek telepítése, környezet beállítása, értesítések küldése. Például létrehozható egy :setup_signing private lane, amelyet több telepítési lane hív meg, de nem lehet közvetlenül elindítani a fejlesztő által a hibák elkerülése érdekében.

# Private lane és csoportosítás
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

A lanes csoportosítása platform blokkokon keresztül lehetővé teszi az iOS és Android forgatókönyvek szétválasztását egy Fastfile-ban. A platform :ios do ... end és platform :android do ... end szerkezet elkülöníti az adott platform lanes-eit, míg a közös private lanes kiemelhető a platform blokkokon kívülre az újrafelhasználhatóság érdekében.

Paraméterek átadása a lanes-eknek

A Fastfile paraméter mechanizmusa lehetővé teszi a lanes-ek rugalmassá és újrafelhasználhatóvá tételét. A paraméterek a parancssoron keresztül adódnak át indításkor: fastlane build scheme:App export_method:appstore. A lane-en belül az értékek az options hash-en keresztül érhetők el, amely argumentumként kerül átadásra a lane blokknak.

A Fastlane támogatja a típusos paramétereket validációval az OptionalHash segítségével. Megadható az érték típusa (String, Boolean, Integer), alapértelmezett érték és leírás a dokumentáció automatikus generálásához. Ezen kívül elérhetők környezeti változók is a paraméterátadás alternatív módjaként, ami kényelmes a CI/CD rendszerek számára.

# Paraméterek típusvalidációval
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: "A(z) #{options[:scheme]} buildje befejeződött")
end

# Indítás: fastlane build scheme:MyApp export_method:appstore

Ajánlott alapértelmezett értékek használata minden nem kötelező paraméterhez, hogy a lane argumentumok explicit megadása nélkül is indítható legyen. A kötelező paraméterek esetén ellenőrizze az érték meglétét a lane elején, és szakítsa meg a végrehajtást egy érthető hibaüzenettel a UI.user_error! segítségével.