Fastfile: essenza, struttura e configurazione dell’automazione nello sviluppo mobile

Cos’è Fastfile e perché serve

Fastfile è il file di configurazione principale di Fastlane, scritto in Ruby e collocato nella directory fastlane nella radice del progetto. Definisce tutti gli script di automazione (lanes) per il build, il testing, la firma del codice e la distribuzione dell’app. Fastfile sostituisce decine di script bash, Makefile e istruzioni manuali con un’unica descrizione dichiarativa della pipeline CI/CD.

La necessità di Fastfile sorge quando il progetto richiede build riproducibili su macchine diverse di sviluppatori e server CI/CD. Invece di far configurare manualmente l’ambiente a ogni sviluppatore, Fastfile fissa tutti i passaggi in codice versionabile in Git, revisionabile e riutilizzabile tra progetti. Un unico Fastfile garantisce che il build sulla macchina dello sviluppatore sia identico a quello sul server CI/CD.

Fastfile supporta piattaforme tramite la direttiva default_platform. In un singolo Fastfile si possono descrivere script per iOS, Android e macOS, raggruppandoli in blocchi platform :ios e platform :android. Ciò è particolarmente utile per progetti cross-platform in cui iOS e Android condividono la logica di deploy ma hanno strumenti di build diversi.

Struttura di Fastfile: lanes, actions e parametri

Fastfile è composto da tre elementi principali: dichiarazione della piattaforma (default_platform), definizione delle lanes e configurazione delle funzioni ausiliarie. Ogni lane inizia con la parola chiave lane, seguita dal nome dello script (simbolo Ruby), dal corpo con la sequenza di actions e dai blocchi di gestione degli errori error, success o ensure.

Actions in Fastfile sono chiamate alle funzioni integrate di Fastlane con parametri in formato Hash. Ad esempio, gym(scheme: 'App', export_method: 'app-store') avvia il build dell’app iOS con i parametri specificati. Ogni action restituisce un risultato che può essere salvato in una variabile e utilizzato nelle action successive — ciò permette di costruire logica condizionale all’interno della lane.

Fastfile supporta variabili d’ambiente tramite il meccanismo standard ENV di Ruby. I dati sensibili (password, token, chiavi) non vanno memorizzati in Fastfile — utilizzate le variabili d’ambiente del sistema CI/CD o il file .env aggiunto a .gitignore. Fastlane carica automaticamente i file .env dalla directory fastlane all’avvio.

Appfile e Matchfile

Insieme a Fastfile nella directory fastlane si trovano file di configurazione aggiuntivi. Appfile contiene gli identificatori dell’app (app_identifier), l’Apple ID e il Team ID — questi dati vengono automaticamente inseriti in tutte le action, evitando ripetizioni in ogni lane. Matchfile memorizza le impostazioni per match: URL del repository Git, tipo di profili e chiave di crittografia.

La suddivisione della configurazione in più file semplifica la manutenzione di progetti con ambienti diversi. Ad esempio, per staging e production si possono creare rami separati nel repository Matchfile o sovrascrivere i parametri tramite variabili d’ambiente nel sistema CI/CD.

# Struttura di base del 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

Sintassi di Fastfile: scrivere lanes

La sintassi di Fastfile si basa su Ruby DSL (Domain Specific Language), appositamente progettato per la leggibilità degli script di automazione. Una lane si dichiara con la costruzione lane :name do ... end, dove name è un simbolo Ruby che diventa il comando fastlane name per l’esecuzione da terminale o sistema CI/CD.

All’interno di una lane si possono usare operatori condizionali Ruby: if, unless, case per ramificare la logica. Sono disponibili anche i cicli each e while per elaborare array di valori. Fastlane fornisce metodi speciali before_all, after_all e blocchi error per gestire gli eventi del ciclo di vita della lane.

I parametri della lane vengono passati tramite l’hash options. Eseguendo fastlane build --option_name value, il valore finisce in options[:option_name] all’interno della lane. Si possono impostare valori predefiniti con optional: true e validazione del tipo per controllare i tipi dei parametri passati.

# Lane con parametri e logica condizionale
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

Esempio di Fastfile per iOS

Un Fastfile completo per un progetto iOS include lanes per installare dipendenze, testare, compilare e distribuire su TestFlight e App Store. Consideriamo un esempio che copre il tipico processo CI/CD dal commit alla pubblicazione su TestFlight per il testing interno.

# Fastfile per 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: 'Il build è stato caricato su TestFlight per il testing interno'
  )
end

In questo esempio, il blocco before_all viene eseguito prima di ogni lane e installa le dipendenze. La lane tests esegue test UI e Unit su due dispositivi. La lane build_appstore firma il codice tramite match e genera IPA con bitcode. La lane deploy_testflight combina tutti i passaggi per una distribuzione completa.

Deploy con più target

I progetti con più target (app principale, watchOS, widget, Notification Service Extension) richiedono lane separate per ogni target. In Fastfile si può creare una lane universale :deploy_target che accetta il nome dello schema e il percorso del build come parametro. Ciò permette di eseguire il deploy per tutte le estensioni con fastlane deploy_target scheme:Widget.

Per organizzare più target, usate un array di schemi e un ciclo each all’interno della lane. Fastlane supporta la compilazione parallela di più schemi tramite il flag parallel: true, riducendo il tempo totale della pipeline CI/CD per app con estensioni.

Esempio di Fastfile per Android

Fastfile per un progetto Android utilizza gradle action per eseguire task Gradle e supply action per pubblicare su Google Play. A differenza di iOS, Android non richiede match ma usa Keystore per la firma, memorizzato fuori dal repository e passato tramite variabili d’ambiente.

# Fastfile per 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

Per la firma Android dell’app, configurate signingConfigs in build.gradle e passate i parametri Keystore tramite variabili d’ambiente: ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS e ANDROID_KEY_PASSWORD. Fastlane utilizza automaticamente apksigner di sistema per firmare l’AAB o APK compilato.

Firma Android in Fastfile

Per configurare la firma Android in Fastfile, usate l’action sign_android o affidatevi a signingConfigs in build.gradle. Fastlane si integra con apksigner tramite Gradle — il passaggio del flag SIGNING_CONFIG nel task gradle attiva la firma con i parametri dalle variabili d’ambiente. Ciò permette di firmare i file AAB prima del caricamento su Google Play Console.

Per la memorizzazione sicura del Keystore in CI/CD, usate la codifica Base64 e variabili d’ambiente. Fastlane supporta l’action setup_keystore che decodifica il Keystore dalla variabile e lo salva in un file temporaneo nella fase before_all. Al termine della lane, il file temporaneo viene automaticamente eliminato per prevenire la fuga di certificati.

Utilizzo di private lanes e gruppi

Private lanes (script privati) sono lanes che non possono essere chiamate direttamente dalla riga di comando ma sono accessibili da altre lanes all’interno del Fastfile. Una private lane si dichiara con la costruzione private_lane :name do ... end e viene usata per incapsulare passaggi ripetitivi che non hanno senso come script autonomi.

Le private lanes sono ideali per raggruppare logiche ripetitive: installazione dipendenze, configurazione ambiente, invio notifiche. Ad esempio, si può creare una private lane :setup_signing chiamata da più lane di deploy ma non accessibile per l’esecuzione diretta dallo sviluppatore per evitare errori.

# Private lane e raggruppamento
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

Raggruppamento lanes tramite blocchi platform permette di separare gli script per iOS e Android in un unico Fastfile. La costruzione platform :ios do ... end e platform :android do ... end isola le lanes della rispettiva piattaforma, mentre le private lanes comuni possono essere collocate fuori dai blocchi di piattaforma per il riutilizzo.

Passaggio di parametri alle lanes

Il meccanismo dei parametri di Fastfile rende le lanes flessibili e riutilizzabili. I parametri vengono passati all’esecuzione tramite riga di comando: fastlane build scheme:App export_method:appstore. All’interno della lane, i valori sono accessibili tramite l’hash options passato al blocco lane come argomento.

Fastlane supporta parametri tipizzati con validazione tramite OptionalHash. Si può impostare il tipo di valore (String, Boolean, Integer), il valore predefinito e una descrizione per la generazione automatica della documentazione. Sono disponibili anche variabili d’ambiente come metodo alternativo di passaggio parametri, comodo per sistemi CI/CD.

# Parametri con validazione dei tipi
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: "Build #{options[:scheme]} completata")
end

# Esecuzione: fastlane build scheme:MyApp export_method:appstore

Si raccomanda di usare valori predefiniti per tutti i parametri opzionali in modo che la lane possa essere eseguita senza specificare ogni argomento. Per i parametri obbligatori, verificate la presenza del valore all’inizio della lane e interrompete l’esecuzione con un messaggio di errore chiaro tramite UI.user_error!.