Configurare fastlane su un server di build Mac dedicato

Cosa ti serve prima

• Un Mac con Xcode, accesso amministratore e Homebrew.
• Un agente CI su quel Mac: GitHub Actions, GitLab, Buildkite, Jenkins o CircleCI.
• Un account App Store Connect con il diritto di creare API key.
• Un repo Git privato per match, oppure un bucket Google Cloud o S3.

1. Installa fastlane

La documentazione di fastlane, letta a ottobre 2026, preferisce Bundler. Supporta Ruby 3.2 o successivo e preferisce 3.3 o successivo. Sconsiglia il Ruby di sistema di macOS. Installa un Ruby recente con un version manager come rbenv. Poi aggiungi un Gemfile al progetto:

source "https://rubygems.org"

gem "fastlane"

gem install bundler
bundle update
git add Gemfile Gemfile.lock

Bundler fissa la versione di fastlane in Gemfile.lock. Ogni macchina e ogni esecuzione della CI usa la stessa. Eseguilo come bundle exec fastlane.

Su un solo server di build la strada più semplice è Homebrew. Porta con sé il suo Ruby:

brew install fastlane

Scegli una sola strada per progetto. Mescolarle è il modo in cui due versioni di fastlane finiscono sulla stessa macchina.

2. Crea una API key di App Store Connect

fastlane consiglia le API key al posto dei login con Apple ID: nessuna richiesta a due fattori, più velocità, più affidabilità. In App Store Connect apri Users and Access, poi Integrations, poi App Store Connect API. Crea una Team Key. fastlane fa notare che le chiamate di provisioning richiedono una team key. Assegnale il ruolo minimo che funziona. Annota l’Issuer ID e il Key ID. Scarica subito il file .p8, perché Apple permette di scaricarlo una sola volta.

mkdir -p ~/.appstoreconnect
mv ~/Downloads/AuthKey_ABC123XYZ.p8 ~/.appstoreconnect/
chmod 600 ~/.appstoreconnect/AuthKey_ABC123XYZ.p8

Tieni la chiave sul Mac di build o nell’archivio dei secret della tua CI. Non metterla mai in un commit.

3. Configura match una volta, da una macchina di sviluppo

bundle exec fastlane match init
bundle exec fastlane match development
bundle exec fastlane match appstore

match init chiede dove salvare i certificati e scrive un Matchfile. I due comandi successivi creano certificati e profili e li salvano, cifrati, in quell’archivio. Scegli una passphrase robusta. La CI la legge dalla variabile MATCH_PASSWORD.

fastlane consiglia la modalità readonly su ogni sistema di CI. Così la CI scarica solo ciò che esiste e non crea né revoca mai nulla.

4. Scrivi le lane

default_platform(:ios)

platform :ios do
  lane :test do
    run_tests(
      scheme: "MyApp",
      devices: ["iPhone 17"],
      result_bundle: true
    )
  end

  lane :beta do
    setup_ci
    api_key = app_store_connect_api_key(
      key_id: ENV["ASC_KEY_ID"],
      issuer_id: ENV["ASC_ISSUER_ID"],
      key_filepath: ENV["ASC_KEY_PATH"]
    )
    match(type: "appstore", readonly: is_ci, api_key: api_key)
    increment_build_number(
      build_number: latest_testflight_build_number(api_key: api_key) + 1
    )
    build_app(scheme: "MyApp")
    upload_to_testflight(api_key: api_key, skip_waiting_for_build_processing: true)
  end
end

setup_ci crea un portachiavi temporaneo, passa match in readonly e imposta i percorsi dei log e dei risultati dei test. Agisce solo quando fastlane rileva un’esecuzione in CI. Se la tua non viene rilevata, passa force: true. Saltare l’elaborazione della build fa finire prima il job, ma fastlane avverte che salta anche la distribuzione ai tester esterni.

5. Chiamalo dalla CI

Ogni sistema di CI esegue le stesse righe di shell. Salva i secret nella tua CI, non nel repo.

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
bundle install
bundle exec fastlane beta
# needs MATCH_PASSWORD, ASC_KEY_ID, ASC_ISSUER_ID and ASC_KEY_PATH set as CI secrets

Su GitHub Actions queste righe vanno in uno step run, con i secret passati come env. Un Mac MacRun ha già installato il software del runner di GitHub Actions. La nostra guida alla configurazione iOS su GitHub Actions mostra un workflow completo. Su GitLab, Buildkite o CircleCI, metti le stesse righe nello script del job. Su Jenkins usa uno step sh.

Come sopravvive ai riavvii

fastlane non è un servizio. Gira dentro il job del tuo agente CI. A dover sopravvivere a un riavvio sono l’agente e la sua sessione utente. Configura l’agente come LaunchAgent con login automatico, come nelle nostre guide a GitLab Runner e Buildkite. Il portachiavi temporaneo di setup_ci viene ricreato a ogni esecuzione. Un portachiavi di login bloccato dopo un riavvio non può fermarlo.

Errori comuni e soluzioni

Sono documentati da fastlane.

• Strani errori di codifica o crash in CI. fastlane ha bisogno di una locale UTF-8. Imposta LANG e LC_ALL a en_US.UTF-8.
• Il job si blocca su una richiesta a due fattori. Usa la API key. Con un Apple ID, imposta SPACESHIP_ONLY_ALLOW_INTERACTIVE_2FA così fallisce subito.
• match prova a creare nuovi certificati in CI. Usa readonly, oppure chiama prima setup_ci.
• match non riesce a clonare il suo repo. GitHub non accetta la stessa deploy key su due repo. Usa un account macchina in sola lettura, oppure git_private_key, oppure MATCH_GIT_BASIC_AUTHORIZATION.
• I profili sono installati ma Xcode non li vede. Xcode 16 ha spostato la cartella dei profili. fastlane segue la versione di Xcode selezionata, quindi esegui xcode_select prima di match sulle macchine con due Xcode.

Perché un Mac dedicato aiuta

build_app e run_tests sono build Xcode. Su una macchina che conserva la DerivedData e le gem installate sono molto più veloci. Nel nostro benchmark sull’app iOS di Wikipedia con Xcode 26.6, una build pulita ha richiesto 86 secondi su un M6. Ne ha richiesti 183 su un runner macos-26 ospitato da GitHub. Un job dopo una piccola modifica ha richiesto 27 secondi a caldo, contro 269 da zero.

Quando non ti serve un server di build

Se pubblichi su TestFlight una volta a settimana, un runner in hosting o Xcode Cloud richiede meno lavoro. Vedi la nostra guida alle alternative a Xcode Cloud per quel compromesso. Considera anche cosa MacRun non fa. Non gestiamo la firma del codice per te. Esegui match tu stesso, come in questa pagina. E non offriamo uno SLA.

Pronto per un server di build? I prezzi elencano ogni taglio, e la documentazione di configurazione mostra come collegarti.