Match (Fastlane) : gestion des certificats iOS et configuration de développement

Qu'est-ce que Match (Fastlane) ?

Match (Fastlane) est un composant de l'écosystème Fastlane conçu pour la gestion centralisée des certificats Code Signing et des Profils de Provisioning pour le développement iOS. Il résout le problème de synchronisation des signatures entre les membres de l'équipe et automatise la configuration des certificats dans les pipelines CI/CD sans intervention du développeur.

Sans Match, chaque membre de l'équipe génère manuellement des certificats via Xcode ou le portail Apple Developer, ce qui entraîne des conflits lors du build sur différentes machines. Le Code Signing est le processus de signature numérique d'une application iOS qui confirme son authenticité et son intégrité avant l'installation sur l'appareil de l'utilisateur.

Selon la documentation Apple Developer (2025), une configuration incorrecte des certificats est l'une des causes les plus fréquentes de rejet lors de la soumission d'une application sur l'App Store. Match vérifie automatiquement la validité des certificats et avertit des dates d'expiration, réduisant ainsi le risque de rejet du build lors de la phase de vérification Apple.

Utilisez Match dans tout projet avec deux développeurs ou plus ou avec un pipeline CI/CD. Cela réduit le temps de configuration de l'environnement d'un nouveau membre de l'équipe de 30 minutes à une seule commande dans le terminal.

Comment fonctionne Match : dépôt Git chiffré

L'architecture de Match repose sur le concept d'une source de vérité unique pour tous les certificats de l'équipe iOS. Au lieu d'un stockage local dans le trousseau de chaque développeur, Match regroupe les certificats dans un seul dépôt Git avec chiffrement de chaque fichier avant enregistrement.

Le processus comprend trois étapes. Lors de l'initialisation, Match génère tous les certificats et profils nécessaires via l'API du portail Apple Developer. Chaque fichier est chiffré avec l'algorithme AES-256 en utilisant une clé basée sur une phrase de passe utilisateur. Les fichiers chiffrés sont enregistrés dans un dépôt Git et synchronisés avec le serveur distant via les opérations Git standard push et pull.

Architecture de chiffrement des certificats

Match utilise une combinaison d'OpenSSL et d'une phrase de passe utilisateur pour chiffrer les certificats et profils. La clé d'accès est définie via la variable d'environnement MATCH_PASSWORD et n'est pas stockée dans le dépôt, ce qui exclut toute fuite même en cas de compromission du serveur Git ou d'accès public au dépôt.

Lors de la demande d'un certificat, Match télécharge le fichier chiffré depuis le dépôt, le déchiffre localement avec la phrase de passe et l'installe dans le Trousseau de la machine actuelle. Une fois le build terminé, les certificats peuvent être supprimés du Trousseau pour respecter les politiques de sécurité de l'environnement d'entreprise, empêchant ainsi l'utilisation de certificats obsolètes dans les builds suivants.

Chaque certificat est enregistré avec un nom contenant l'identifiant de l'application, le type de profil et la date de création. Cette structure permet à Match de gérer les versions des certificats et, si nécessaire, de revenir à un état antérieur via les commandes Git standard revert et reset. C'est particulièrement utile en cas de suppression accidentelle ou d'écrasement d'un profil.

Configuration et paramétrage de Match

L'installation de Match s'effectue avec Fastlane via le gestionnaire de paquets Ruby : gem install fastlane. Après l'installation, initialisez le dépôt de certificats avec la commande fastlane match init, qui crée un dépôt Git vide et génère un fichier Matchfile avec un modèle de configuration de base.

# Initialisation du dépôt Match
fastlane match init

Configuration via Matchfile

Le fichier Matchfile contient tous les paramètres de connexion au dépôt de certificats : URL du dépôt Git, type de profil par défaut, identifiants d'application et identifiants Apple Developer. Exemple de configuration typique pour une équipe de cinq développeurs :

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

Le paramètre type détermine le type de profils : :development pour le débogage sur les appareils des développeurs, :appstore pour la publication sur l'App Store, :adhoc pour les tests sur des appareils externes et :enterprise pour la distribution interne In-House en dehors de l'App Store. Chaque type crée un répertoire séparé dans le dépôt, permettant d'organiser les profils par scénario de build cible.

Match prend en charge plusieurs méthodes d'authentification sur le portail Apple Developer : authentification à deux facteurs via Apple ID, mot de passe spécifique à l'application (App-Specific Password) et clés API App Store Connect. Pour le CI/CD, il est recommandé d'utiliser les clés API. Elles ne nécessitent pas de saisie interactive de code de confirmation et ne bloquent pas les builds automatisés en cas de changement d'appareil du développeur.

Génération et synchronisation des profils

Après la configuration du Matchfile, exécutez la commande fastlane match development ou fastlane match appstore pour générer et synchroniser les profils. Match crée ou met automatiquement à jour les certificats via l'API du portail Apple Developer et les enregistre dans le dépôt. Le portail Apple Developer est l'interface web d'Apple pour gérer les certificats, les identifiants d'application et la liste des appareils autorisés des développeurs.

Lors du premier lancement, Match demande une phrase de passe pour chiffrer le dépôt. Cette phrase doit être enregistrée dans le gestionnaire de secrets CI/CD (GitHub Actions Secrets, GitLab CI Variables ou Jenkins Credentials) et transmise via la variable d'environnement MATCH_PASSWORD. Sans elle, Match ne peut pas déchiffrer les certificats sur d'autres machines ou dans l'environnement CI.

Commandes principales de Match pour la gestion des certificats

L'interface de Match se compose d'un ensemble de commandes pour créer, mettre à jour, synchroniser et supprimer des certificats et profils. Chaque commande correspond à une action spécifique du cycle de vie du Code Signing, de la génération au nettoyage complet du dépôt.

Commandes pour le travail quotidien

La commande fastlane match development télécharge ou crée des certificats et profils Development pour le débogage sur les appareils locaux. Un profil de provisionnement est un document numérique Apple qui lie le certificat du développeur à l'identifiant de l'application et à la liste des appareils autorisés à installer l'application.

Pour la publication sur l'App Store, utilisez fastlane match appstore qui génère des certificats Distribution et des profils AppStore. La commande fastlane match adhoc crée des profils pour les tests sur des appareils externes, et fastlane match enterprise pour les applications d'entreprise In-House.

# Création de profils Development pour le débogage
fastlane match development

# Création de profils AppStore pour la release
fastlane match appstore

# Importation de certificats manuels existants
fastlane match import

La commande fastlane match import permet d'ajouter au dépôt des certificats déjà existants, utile lors de la migration de la gestion manuelle vers Match. Le paramètre --readonly bloque toute modification du dépôt, ce qui est essentiel pour l'environnement CI où le pipeline ne doit pas créer ou supprimer automatiquement des certificats et profils.

Pour un nettoyage complet du dépôt, utilisez la commande fastlane match nuke. Elle supprime tous les certificats du dépôt Git, du portail Apple Developer et de la machine locale. C'est une réinitialisation complète de l'état du Code Signing pour le projet. Cette commande est utilisée uniquement en cas de conflits critiques ou lors du passage à un nouveau compte Apple Developer.

Intégration de Match dans un pipeline CI/CD

L'intégration CI/CD est l'un des principaux avantages de Match. Dans les pipelines GitHub Actions, GitLab CI, Bitrise ou Jenkins, Match télécharge et installe automatiquement les certificats corrects sans intervention du développeur. Cela permet de réaliser un build et une signature entièrement automatisés d'une application iOS, du commit à l'IPA final.

Une configuration typique pour GitHub Actions comprend l'installation de Fastlane, la configuration de la variable MATCH_PASSWORD et l'exécution de Match avec le drapeau --readonly. GitHub Actions est la plateforme CI/CD de GitHub qui automatise le build, le test et la publication du code en fonction des événements du dépôt.

# Installation de Fastlane dans l'environnement CI
gem install fastlane --no-document

# Exécution de Match en mode lecture seule sans droit de modification
fastlane match development --readonly

Avant d'exécuter Match dans le CI, vous devez configurer l'accès au dépôt de certificats. Fastlane le clone automatiquement en fonction du paramètre git_url du Matchfile. L'accès au dépôt est configuré via une clé SSH ou un personal access token ajouté aux secrets du système CI. Cela garantit que les certificats ne seront pas compromis via un accès public.

Configurez les variables d'environnement MATCH_PASSWORD et FASTLANE_APPLE_API_KEY dans les secrets de votre fournisseur CI. La clé API App Store Connect permet à Match de s'authentifier sur le portail Apple Developer sans authentification à deux facteurs, ce qui élimine les demandes interactives dans les builds automatisés et évite le blocage du pipeline.

Erreurs courantes lors de l'utilisation de Match

Même avec une configuration correcte de Match, des erreurs peuvent survenir liées à l'expiration des certificats, aux conflits de profils ou à une configuration incorrecte de l'environnement. Le diagnostic des problèmes de Match repose sur l'analyse des logs de commande et la vérification de l'état actuel du dépôt Git des certificats.

L'erreur la plus fréquente, “You need to provide a password for Match”, se produit lorsque la variable d'environnement MATCH_PASSWORD n'est pas définie sur la machine ou dans l'environnement CI. Solution : ajoutez MATCH_PASSWORD aux variables d'environnement du système ou transmettez le mot de passe via le paramètre --keychain_password lors de l'exécution de la commande Match.

Le deuxième problème le plus courant est le conflit de certificats lors de l'ajout d'un nouvel appareil à un profil AdHoc. Il se résout avec la commande fastlane match adhoc --force qui recrée les profils en tenant compte des nouveaux appareils. Les certificats Apple Developer sont valables un an, après quoi tout build utilisant ces certificats est rejeté par App Store Connect. Match avertit de l'expiration 30 jours avant la date limite.

En cas d'erreur “Multiple matches found for...”, plusieurs versions d'un même certificat sont présentes dans le dépôt. Utilisez la commande fastlane match nuke pour un nettoyage complet du dépôt et la suppression de tous les certificats du portail Apple Developer. Après le nettoyage, effectuez une génération à partir de zéro, ce qui garantit un état cohérent des profils sans doublons ni versions conflictuelles.