Match (Fastlane): wat is het, certificaatbeheer en configuratie in ontwikkeling

Wat is Match (Fastlane)?

Match (Fastlane) — is een component van het Fastlane-ecosysteem, bedoeld voor gecentraliseerd beheer van Code Signing-certificaten en Provisioning Profiles voor iOS-ontwikkeling. Het lost het probleem van handsynchronisatie tussen teamleden op en automatiseert de configuratie van certificaten in CI/CD-pijplijnen zonder tussenkomst van de ontwikkelaar.

Zonder Match genereert elk teamlid handmatig certificaten via Xcode of Apple Developer Portal, wat leidt tot conflicten bij het bouwen op verschillende machines. Code Signing — is het proces van het digitaal ondertekenen van een iOS-applicatie, die het auteurschap en de integriteit bevestigt voordat deze op het apparaat van de gebruiker wordt geïnstalleerd.

Volgens Apple Developer Documentation (2025) is onjuiste configuratie van certificaten een van de meest voorkomende oorzaken van afwijzing bij het indienen van een app in de App Store. Match controleert automatisch de geldigheid van certificaten en waarschuwt voor verlopende vervaldata, waardoor het risico op afwijzing van de build in de Apple-verificatiefase wordt verminderd.

Gebruik Match in elk project met twee of meer ontwikkelaars of met een CI/CD-pijplijn — dit vermindert de tijd voor het instellen van de omgeving voor een nieuw teamlid van 30 minuten tot één opdracht in de terminal.

Hoe werkt Match: versleutelde Git-opslag

Match-architectuur is gebaseerd op het concept van een enige bron van waarheid voor alle certificaten van het iOS-team. In plaats van lokale opslag in de keychain van elke ontwikkelaar, verenigt Match certificaten in een enkele Git-repository met versleuteling van elk bestand voor opslag.

Het proces bestaat uit drie fasen. In de initialisatiefase genereert Match alle benodigde certificaten en profielen via de Apple Developer Portal API. Elk bestand wordt versleuteld met het AES-256-algoritme met een sleutel die is gevormd op basis van een gebruikerswachtwoordzin. Versleutelde bestanden worden opgeslagen in de Git-repository en gesynchroniseerd met de externe server via standaard Git push- en pull-bewerkingen.

Architectuur van certificaatversleuteling

Match gebruikt een combinatie van OpenSSL en een gebruikerswachtwoordzin voor het versleutelen van certificaten en profielen. De toegangssleutel wordt ingesteld via de omgevingsvariabele MATCH_PASSWORD en wordt niet opgeslagen in de repository, wat lekkage uitsluit, zelfs bij compromittering van de Git-server of openbare toegang tot de repository.

Bij het aanvragen van een certificaat laadt Match het versleutelde bestand uit de repository, ontsleutelt het lokaal met de wachtwoordzin en installeert het in de Keychain van de huidige machine. Na voltooiing van de build kunnen certificaten uit de Keychain worden verwijderd om te voldoen aan beveiligingsbeleid van de bedrijfsomgeving — dit voorkomt het gebruik van verouderde certificaten in volgende builds.

Elk certificaat wordt opgeslagen met een naam die de applicatie-ID, het profieltype en de aanmaakdatum bevat. Deze structuur stelt Match in staat om certificaatversies te beheren en indien nodig terug te keren naar een eerdere staat via standaard Git-commando’s revert en reset. Dit is vooral handig bij het per ongeluk verwijderen of overschrijven van een profiel.

Installatie en configuratie van Match

Match wordt geïnstalleerd samen met Fastlane via de Ruby-pakketbeheerder: gem install fastlane. Na installatie moet de certificaatopslag worden geïnitialiseerd met het commando fastlane match init, dat een lege Git-repository maakt en een Matchfile genereert met een sjabloon voor basisinstellingen.

# Match-repository initialiseren
fastlane match init

Configuratie via Matchfile

Het Matchfile bevat alle parameters voor verbinding met de certificaatopslag: URL van de Git-repository, standaard profieltype, applicatie-ID’s en Apple Developer-inloggegevens. Een voorbeeld van een typische configuratie voor een team van vijf ontwikkelaars:

# 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")

De parameter type bepaalt het profieltype: :development voor foutopsporing op ontwikkelaarsapparaten, :appstore voor publicatie in de App Store, :adhoc voor testen op externe apparaten en :enterprise voor bedrijfsdistributie In-House buiten de App Store. Elk type maakt een aparte map aan in de repository, waardoor profielen kunnen worden georganiseerd op doelbuildscenario’s.

Match ondersteunt meerdere authenticatiemethoden in Apple Developer Portal: tweefactorauthenticatie via Apple ID, App-Specific Password en API-sleutels van App Store Connect API. Voor CI/CD wordt het gebruik van API-sleutels aanbevolen — deze vereisen geen interactieve invoer van een bevestigingscode en blokkeren geautomatiseerde builds niet bij het wisselen van ontwikkelaarsapparaat.

Genereren en synchroniseren van profielen

Na het configureren van het Matchfile wordt het commando fastlane match development of fastlane match appstore uitgevoerd om profielen te genereren en te synchroniseren. Match maakt of werkt automatisch certificaten bij via de Apple Developer Portal API en slaat ze op in de repository. Apple Developer Portal — is de webinterface van Apple voor het beheren van certificaten, applicatie-ID’s en de lijst met toegestane ontwikkelaarsapparaten.

Bij de eerste start vraagt Match om een wachtwoordzin voor het versleutelen van de repository. Deze zin moet worden opgeslagen in de CI/CD-geheimenbeheerder (GitHub Actions Secrets, GitLab CI Variables of Jenkins Credentials) en worden doorgegeven via de omgevingsvariabele MATCH_PASSWORD. Zonder dit kan Match de certificaten niet ontsleutelen op andere machines of in de CI-omgeving.

Basis Match-commando’s voor certificaatbeheer

De Match-interface bestaat uit een reeks commando’s voor het maken, bijwerken, synchroniseren en verwijderen van certificaten en profielen. Elk commando komt overeen met een specifieke actie in de levenscyclus van Code Signing: van genereren tot volledige opschoning van de repository.

Commando’s voor dagelijks gebruik

Het commando fastlane match development laadt of maakt Development-certificaten en -profielen voor foutopsporing op lokale apparaten. Provisioning Profile — is een digitaal Apple-document dat het ontwikkelaarscertificaat koppelt aan de applicatie-ID en de lijst met apparaten die zijn toegestaan voor installatie.

Voor publicatie in de App Store wordt fastlane match appstore gebruikt — dit genereert Distribution-certificaten en AppStore-profielen. Het commando fastlane match adhoc maakt profielen voor testen op externe apparaten, en fastlane match enterprise — voor bedrijfsapplicaties In-House.

# Development-profielen aanmaken voor foutopsporing
fastlane match development

# AppStore-profielen aanmaken voor publicatie
fastlane match appstore

# Bestaande handmatig gemaakte certificaten importeren
fastlane match import

Het commando fastlane match import maakt het mogelijk om bestaande certificaten aan de repository toe te voegen — handig bij migratie van handmatig beheer naar Match. De parameter --readonly blokkeert alle wijzigingen in de repository, wat cruciaal is voor de CI-omgeving, waar de pijplijn geen certificaten en profielen automatisch mag maken of verwijderen.

Voor volledige opschoning van de repository wordt het commando fastlane match nuke gebruikt. Het verwijdert alle certificaten uit de Git-repository, Apple Developer Portal en van de lokale machine — een volledige reset van de Code Signing-status voor het project. Het commando wordt alleen toegepast bij kritieke conflicten of bij overstap naar een nieuw Apple Developer-account.

Match integreren in CI/CD-pijplijn

CI/CD-integratie van Match — een van de belangrijkste voordelen van het hulpmiddel. In de pijplijn van GitHub Actions, GitLab CI, Bitrise of Jenkins laadt en installeert Match automatisch de juiste certificaten zonder tussenkomst van de ontwikkelaar. Dit maakt volledig geautomatiseerd bouwen en ondertekenen van iOS-applicaties mogelijk, van commit tot de uiteindelijke IPA.

Een typische configuratie voor GitHub Actions omvat het installeren van Fastlane, het instellen van de MATCH_PASSWORD-variabele en het starten van Match met de vlag --readonly. GitHub Actions — is een CI/CD-platform van GitHub dat het bouwen, testen en publiceren van code automatiseert op basis van gebeurtenissen in de repository.

# Fastlane installeren in CI-omgeving
gem install fastlane --no-document

# Match starten in read-only modus zonder wijzigingsrechten
fastlane match development --readonly

Voordat Match in CI wordt gestart, moet de toegang tot de certificaatopslag worden geconfigureerd. Fastlane kloont automatisch de repository op basis van de parameter git_url uit het Matchfile. Toegang tot de repository wordt geconfigureerd via een SSH-sleutel of personal access token, die worden toegevoegd aan de geheimen van het CI-systeem — dit garandeert dat certificaten niet worden gecompromitteerd via openbare toegang.

Configureer de omgevingsvariabelen MATCH_PASSWORD en FASTLANE_APPLE_API_KEY in de geheimen van uw CI-provider. De App Store Connect API-sleutel stelt Match in staat om te authenticeren in Apple Developer Portal zonder tweefactorauthenticatie, wat interactieve verzoeken in geautomatiseerde builds uitsluit en blokkering van de pijplijn voorkomt.

Veelvoorkomende fouten bij het werken met Match

Zelfs bij correcte configuratie van Match kunnen er fouten optreden die verband houden met verlopen certificaten, profielconflicten of onjuiste omgevingsconfiguratie. Probleemdiagnose van Match is gebaseerd op analyse van commando-logboeken en controle van de Git-repository van certificaten op actualiteit.

De meest voorkomende fout — «You need to provide a password for Match» — treedt op wanneer de omgevingsvariabele MATCH_PASSWORD niet is ingesteld op de machine of in de CI-omgeving. Oplossing: voeg MATCH_PASSWORD toe aan de omgevingsvariabelen van het systeem of geef het wachtwoord door via de parameter --keychain_password bij het starten van het Match-commando.

Het tweede meest voorkomende probleem is certificaatconflict bij het toevoegen van een nieuw apparaat aan een AdHoc-profiel. Dit wordt opgelost met het commando fastlane match adhoc --force, dat profielen opnieuw aanmaakt rekening houdend met nieuwe apparaten. Apple Developer-certificaten zijn een jaar geldig, waarna een build die ze gebruikt wordt afgewezen door App Store Connect. Match waarschuwt voor vervaldatum 30 dagen voor het einde van de termijn.

Bij de fout «Multiple matches found for...» zijn er meerdere versies van hetzelfde certificaat in de repository aanwezig. Gebruik het commando fastlane match nuke voor volledige opschoning van de repository en verwijdering van alle certificaten uit Apple Developer Portal. Na opschoning voert u een generatie vanaf nul uit — dit garandeert een consistente staat van profielen zonder duplicaten en conflicterende versies.