Match (Fastlane): gestione certificati e configurazione nello sviluppo iOS

Cos'è Match (Fastlane)?

Match (Fastlane) è un componente dell'ecosistema Fastlane progettato per la gestione centralizzata dei certificati Code Signing e dei Profili di Provisioning per lo sviluppo iOS. Risolve il problema della sincronizzazione delle firme tra i membri del team e automatizza la configurazione dei certificati nei pipeline CI/CD senza intervento dello sviluppatore.

Senza Match, ogni membro del team genera manualmente i certificati tramite Xcode o Apple Developer Portal, causando conflitti durante il build su macchine diverse. Il Code Signing è il processo di firma digitale dell'app iOS che ne conferma l'autenticità e l'integrità prima dell'installazione sul dispositivo dell'utente.

Secondo la documentazione Apple Developer (2025), una configurazione errata dei certificati è una delle cause più frequenti di rifiuto durante l'invio di un'app all'App Store. Match verifica automaticamente la validità dei certificati e avvisa sulle scadenze imminenti, riducendo il rischio di rifiuto del build nella fase di verifica Apple.

Utilizza Match in qualsiasi progetto con due o più sviluppatori o con un pipeline CI/CD: riduce il tempo di configurazione dell'ambiente per un nuovo membro del team da 30 minuti a un singolo comando nel terminale.

Come funziona Match: repository Git crittografato

L'architettura di Match si basa sul concetto di un'unica fonte di verità per tutti i certificati del team iOS. Invece dell'archiviazione locale nel portachiavi di ogni sviluppatore, Match raggruppa i certificati in un unico repository Git con crittografia di ogni file prima del salvataggio.

Il processo si compone di tre fasi. Nella fase di inizializzazione, Match genera tutti i certificati e profili necessari tramite l'API di Apple Developer Portal. Ogni file viene crittografato con l'algoritmo AES-256 utilizzando una chiave basata su una frase segreta utente. I file crittografati vengono salvati in un repository Git e sincronizzati con il server remoto tramite le operazioni Git standard push e pull.

Architettura di crittografia dei certificati

Match utilizza una combinazione di OpenSSL e una frase segreta utente per crittografare certificati e profili. La chiave di accesso viene impostata tramite la variabile d'ambiente MATCH_PASSWORD e non viene archiviata nel repository, escludendo qualsiasi fuga anche in caso di compromissione del server Git o accesso pubblico al repository.

Quando si richiede un certificato, Match scarica il file crittografato dal repository, lo decrittografa localmente usando la frase segreta e lo installa nel portachiavi della macchina corrente. Al termine del build, i certificati possono essere rimossi dal portachiavi per rispettare le politiche di sicurezza dell'ambiente aziendale, impedendo l'uso di certificati obsoleti nei build successivi.

Ogni certificato viene salvato con un nome contenente l'identificatore dell'app, il tipo di profilo e la data di creazione. Questa struttura consente a Match di gestire le versioni dei certificati e, se necessario, di tornare a uno stato precedente tramite i comandi Git standard revert e reset. Ciò è particolarmente utile in caso di cancellazione accidentale o sovrascrittura di un profilo.

Configurazione e impostazione di Match

L'installazione di Match viene eseguita insieme a Fastlane tramite il gestore pacchetti Ruby: gem install fastlane. Dopo l'installazione, inizializza il repository dei certificati con il comando fastlane match init, che crea un repository Git vuoto e genera un file Matchfile con un template di configurazione di base.

# Inizializzazione repository Match
fastlane match init

Configurazione tramite Matchfile

Il file Matchfile contiene tutti i parametri di connessione al repository dei certificati: URL del repository Git, tipo di profilo predefinito, identificatori delle app e credenziali Apple Developer. Esempio di configurazione tipica per un team di cinque sviluppatori:

# Matchfile configuration
git_url("https://github.com/company/certificates.git")
type(:development)
app_identifier(["com.company.app", "com.company.app.extension"])
username("developer@company.com")
team_id("TEAM123456")
git_branch("main")

Il parametro type determina il tipo di profili: :development per il debug sui dispositivi degli sviluppatori, :appstore per la pubblicazione sull'App Store, :adhoc per i test su dispositivi esterni ed :enterprise per la distribuzione interna In-House al di fuori dell'App Store. Ogni tipo crea una directory separata nel repository, consentendo di organizzare i profili per scenario di build target.

Match supporta diversi metodi di autenticazione su Apple Developer Portal: autenticazione a due fattori tramite Apple ID, password specifica per l'app (App-Specific Password) e chiavi API App Store Connect. Per CI/CD si consiglia di utilizzare le chiavi API: non richiedono l'inserimento interattivo del codice di conferma e non bloccano i build automatici in caso di cambio dispositivo dello sviluppatore.

Generazione e sincronizzazione dei profili

Dopo aver configurato Matchfile, esegui il comando fastlane match development o fastlane match appstore per generare e sincronizzare i profili. Match crea o aggiorna automaticamente i certificati tramite l'API di Apple Developer Portal e li salva nel repository. Apple Developer Portal è l'interfaccia web di Apple per gestire certificati, identificatori di app e l'elenco dei dispositivi autorizzati degli sviluppatori.

Al primo avvio, Match richiede una frase segreta per crittografare il repository. Questa frase deve essere salvata nel gestore dei segreti CI/CD (GitHub Actions Secrets, GitLab CI Variables o Jenkins Credentials) e trasmessa tramite la variabile d'ambiente MATCH_PASSWORD. Senza di essa, Match non può decrittografare i certificati su altre macchine o nell'ambiente CI.

Comandi principali di Match per la gestione dei certificati

L'interfaccia di Match è composta da un insieme di comandi per creare, aggiornare, sincronizzare ed eliminare certificati e profili. Ogni comando corrisponde a un'azione specifica nel ciclo di vita del Code Signing, dalla generazione alla pulizia completa del repository.

Comandi per il lavoro quotidiano

Il comando fastlane match development scarica o crea certificati e profili Development per il debug sui dispositivi locali. Un profilo di provisioning è un documento digitale Apple che collega il certificato dello sviluppatore all'identificatore dell'app e all'elenco dei dispositivi autorizzati all'installazione.

Per la pubblicazione sull'App Store si utilizza fastlane match appstore che genera certificati Distribution e profili AppStore. Il comando fastlane match adhoc crea profili per i test su dispositivi esterni, mentre fastlane match enterprise per le app aziendali In-House.

# Creazione profili Development per il debug
fastlane match development

# Creazione profili AppStore per la release
fastlane match appstore

# Importazione certificati manuali esistenti
fastlane match import

Il comando fastlane match import consente di aggiungere al repository certificati già esistenti, utile durante la migrazione dalla gestione manuale a Match. Il parametro --readonly blocca qualsiasi modifica al repository, essenziale per l'ambiente CI dove il pipeline non deve creare o eliminare automaticamente certificati e profili.

Per una pulizia completa del repository si usa il comando fastlane match nuke. Elimina tutti i certificati dal repository Git, da Apple Developer Portal e dalla macchina locale: è un reset completo dello stato del Code Signing per il progetto. Il comando viene utilizzato solo in caso di conflitti critici o durante il passaggio a un nuovo account Apple Developer.

Integrazione di Match nel pipeline CI/CD

L'integrazione CI/CD è uno dei principali vantaggi di Match. Nei pipeline GitHub Actions, GitLab CI, Bitrise o Jenkins, Match scarica e installa automaticamente i certificati corretti senza intervento dello sviluppatore. Ciò consente di realizzare un build e una firma completamente automatizzati di un'app iOS, dal commit all'IPA finale.

Una configurazione tipica per GitHub Actions include l'installazione di Fastlane, l'impostazione della variabile MATCH_PASSWORD e l'esecuzione di Match con il flag --readonly. GitHub Actions è la piattaforma CI/CD di GitHub che automatizza il build, il test e la pubblicazione del codice in base agli eventi del repository.

# Installazione di Fastlane nell'ambiente CI
gem install fastlane --no-document

# Esecuzione di Match in modalità sola lettura senza diritto di modifica
fastlane match development --readonly

Prima di eseguire Match in CI, è necessario configurare l'accesso al repository dei certificati. Fastlane lo clona automaticamente in base al parametro git_url dal Matchfile. L'accesso al repository viene configurato tramite una chiave SSH o un personal access token aggiunto ai segreti del sistema CI, garantendo che i certificati non vengano compromessi tramite accesso pubblico.

Configura le variabili d'ambiente MATCH_PASSWORD e FASTLANE_APPLE_API_KEY nei segreti del tuo provider CI. La chiave API App Store Connect consente a Match di autenticarsi su Apple Developer Portal senza autenticazione a due fattori, eliminando le richieste interattive nei build automatici e prevenendo il blocco del pipeline.

Errori comuni nell'uso di Match

Anche con una configurazione corretta di Match, possono verificarsi errori legati alla scadenza dei certificati, ai conflitti di profili o a una configurazione errata dell'ambiente. La diagnostica dei problemi di Match si basa sull'analisi dei log dei comandi e sulla verifica dello stato aggiornato del repository Git dei certificati.

L'errore più frequente “You need to provide a password for Match” si verifica quando la variabile d'ambiente MATCH_PASSWORD non è impostata sulla macchina o nell'ambiente CI. Soluzione: aggiungi MATCH_PASSWORD alle variabili d'ambiente di sistema o trasmetti la password tramite il parametro --keychain_password all'esecuzione del comando Match.

Il secondo problema più comune è il conflitto di certificati durante l'aggiunta di un nuovo dispositivo a un profilo AdHoc. Si risolve con il comando fastlane match adhoc --force che ricrea i profili tenendo conto dei nuovi dispositivi. I certificati Apple Developer sono validi per un anno, dopodiché i build che li utilizzano vengono rifiutati da App Store Connect. Match avvisa della scadenza 30 giorni prima della scadenza.

In caso di errore “Multiple matches found for...”, nel repository sono presenti più versioni dello stesso certificato. Utilizza il comando fastlane match nuke per una pulizia completa del repository e l'eliminazione di tutti i certificati da Apple Developer Portal. Dopo la pulizia, esegui una generazione da zero, garantendo uno stato coerente dei profili senza duplicati o versioni in conflitto.