Échec de signature fastlane match : liste de contrôle 2026 sur Mac distant

Le journal affiche « No signing certificate » ou « No profiles for… », alors que l’Archive fonctionne encore sur votre Mac local.

La solution la plus rapide consiste à ne pas lancer match nuke : vérifiez d’abord, dans l’ordre, l’accès et le déchiffrement du dépôt, l’identité complète dans le trousseau, le Provisioning Profile et ses entitlements, puis la configuration CI en readonly. Ne faites tourner ou ne recréez les actifs qu’après avoir établi qu’ils sont réellement expirés ou irrécupérables.

Cette liste s’adresse à vous si vous exécutez fastlane match sur un Mac distant et que l’Archive signale soudainement une identité absente. Elle convient également aux petites équipes dont la publication automatisée échoue sans intervention, ainsi qu’aux développeurs iOS ou macOS qui centralisent progressivement leurs certificats et profils.

Le calendrier de diagnostic

Traitez l’incident comme une suite de jalons, et non comme une commande unique à exécuter dans l’urgence. L’objectif est de conserver une preuve exploitable avant de modifier un actif de signature.

Jalon 1 — conserver les preuves

Avant tout nettoyage, archivez le journal CI et le journal de construction en remplaçant systématiquement les secrets par des valeurs telles que <JETON_CI>, <MOT_DE_PASSE_MATCH> ou <ADRESSE_DEPOT_SIGNATURE>.

Conservez notamment :

• le message exact renvoyé par match, codesign, xcodebuild ou l’étape d’export ;
• le code de sortie de chaque commande ;
• le nom du Scheme, la Configuration et la destination utilisés ;
• le Bundle ID, le Team ID et le nom de la cible ;
• les réglages de signature effectivement transmis à la construction ;
• le type de fichier attendu : certificat, clé privée, identité complète ou profil.

Ne publiez jamais dans un artefact CI un jeton, une clé de déploiement, un mot de passe de chiffrement, une donnée de stockage ou une clé privée. Le dépôt du code source et le dépôt des actifs de signature peuvent avoir des droits, des méthodes d’authentification et des propriétaires différents.

Jalon 2 — classer l’échec

Votre première décision doit porter sur la couche en panne :

1. Actifs non récupérés : le dépôt est inaccessible, le segment demandé n’existe pas ou le déchiffrement échoue.
2. Actifs mal installés : le certificat est présent, mais la clé privée manque ou se trouve dans un autre trousseau.
3. Actifs non sélectionnés : le profil est installé, mais la cible utilise un autre Bundle ID, une autre Configuration ou un autre profil.
4. Signature rejetée après construction : l’identité et le profil semblent présents, mais les entitlements, l’équipe, la distribution ou la validation finale ne correspondent pas.

Cette séparation reprend la logique de dépannage recommandée dans la documentation fastlane consacrée aux erreurs de signature. Un message comme « No signing certificate » ne prouve donc pas, à lui seul, qu’un nouveau certificat est nécessaire.

Les quatre points d’entrée à tester sont l’accès au dépôt, l’inventaire du trousseau, l’inspection du profil et une Archive minimale avec la même cible. Évitez de mélanger ces tests avec une nouvelle génération d’actifs : sinon vous perdez la possibilité de savoir quelle modification a résolu, ou aggravé, le problème.

Le dépôt et le déchiffrement

Un échec de fastlane match avant l’installation des actifs doit être traité comme un problème de stockage ou de secret, pas comme une panne de Xcode.

Accès Git, stockage d’objets et configuration d’équipe

Selon votre configuration, match peut utiliser un dépôt Git ou un stockage d’objets. Dans les deux cas, contrôlez séparément :

• l’adresse exacte du dépôt ou du compartiment ;
• la branche ou le préfixe d’environnement attendu ;
• la méthode d’authentification du processus CI ;
• les permissions de lecture et d’écriture ;
• le Team ID et l’identifiant d’application demandés ;
• le secret utilisé pour déchiffrer les actifs.

Le fait que le dépôt du projet soit cloné correctement ne signifie pas que le dépôt de signature est accessible. Un jeton peut être valide pour le code source mais absent, limité ou expiré pour les certificats. La documentation officielle de match distingue précisément le stockage, le chiffrement et les paramètres transmis à l’action.

Que faire lorsque fastlane match ne trouve pas le certificat de signature ?

Commencez par exécuter le diagnostic avec le même compte de service que celui de la tâche CI. Vérifiez que le dépôt attendu est bien celui qui contient l’actif de l’équipe concernée, puis contrôlez le déchiffrement avec <MOT_DE_PASSE_MATCH> sans l’imprimer. Si la récupération échoue avant toute opération sur le trousseau, corrigez les identifiants ou la configuration de stockage ; ne révoquez pas encore le certificat.

Vérification isolée des secrets

Pour éviter les faux positifs, faites valider séparément chaque secret :

• une lecture du dépôt de signature sans afficher son contenu sensible ;
• une authentification au stockage avec une permission strictement nécessaire ;
• une lecture de la variable de déchiffrement sans l’inclure dans le journal ;
• une confirmation du Team ID et du Bundle ID transmis à la lane ;
• un contrôle de la branche ou du chemin logique utilisé par l’environnement distant.

Dans les scripts, remplacez les valeurs réelles par des variables protégées :

export MATCH_PASSWORD="<MOT_DE_PASSE_MATCH>"
export MATCH_GIT_URL="<ADRESSE_DEPOT_SIGNATURE>"
export MATCH_GIT_BRANCH="<BRANCHE_SIGNATURE>"
export APP_IDENTIFIER="<BUNDLE_ID>"
export TEAM_ID="<TEAM_ID>"

Ces lignes illustrent uniquement le principe. Elles ne doivent pas être copiées avec des secrets réels dans un fichier versionné. Pour connaître les options réellement prises en charge par votre version installée, comparez votre lane avec la référence officielle de l’action match.

Le trousseau et l’identité complète

La présence d’un fichier de certificat ne suffit pas à signer une application. Apple décrit l’identité de signature comme l’association exploitable entre le certificat et sa clé privée ; un certificat importé seul ne fournit donc pas nécessairement une identité utilisable. La documentation Apple sur la distribution vers des appareils enregistrés rappelle le rôle de cette chaîne dans la signature d’une application.

Certificat, clé privée et identité

Inspectez le trousseau ciblé sans exposer de contenu secret. Le test doit répondre à trois questions :

• le certificat Apple Distribution ou le certificat adapté à votre tâche est-il présent ?
• sa clé privée associée est-elle présente dans le même environnement ?
• le processus CI peut-il utiliser cette association sans dialogue graphique ?

Si le certificat existe mais que la clé privée est absente, vous n’avez pas une identité de signature complète. Importer à nouveau le certificat public ne recréera pas la clé privée. À l’inverse, une clé privée présente dans un trousseau différent peut rester invisible pour la commande ou l’utilisateur qui exécute l’Archive.

Utilisez des commandes d’inventaire avec des placeholders et redirigez la sortie vers un artefact privé :

security find-identity -v -p codesigning "<CHEMIN_TROUSSEAU>"
security list-keychains -d user
security find-certificate -a "<CHEMIN_TROUSSEAU>"

Les chemins sont volontairement génériques : leur emplacement et le trousseau actif varient selon l’utilisateur, la version de macOS, la méthode d’exécution et la version de l’outil. Confirmez donc le chemin utilisé par votre agent avant d’ajouter un paramètre permanent.

Redémarrage, déverrouillage et processus sans interface

Un Mac distant peut réussir une première construction dans une session interactive, puis échouer après un redémarrage. Le symptôme indique souvent une différence de session ou de trousseau déverrouillé, et non une modification du certificat.

Vérifiez le comportement après redémarrage dans cet ordre :

1. le compte de construction est-il le même qu’avant le redémarrage ?
2. le trousseau attendu est-il encore enregistré parmi les trousseaux accessibles ?
3. le processus CI peut-il le déverrouiller selon la politique prévue ?
4. une fenêtre ou une confirmation interactive bloque-t-elle l’accès ?
5. les autorisations accordées au processus sont-elles limitées au trousseau nécessaire ?

N’accordez pas par défaut un accès illimité à tous les éléments du trousseau et ne transformez pas une connexion interactive permanente en solution de production. Cette méthode masque la cause et rend la reprise après redémarrage plus fragile. La documentation fastlane sur l’intégration continue doit servir de base à votre séparation entre secrets CI, installation des actifs et construction.

Comment rétablir un trousseau impossible à déverrouiller après le redémarrage du Mac distant ?

Reproduisez d’abord l’échec avec le compte du processus non interactif, puis vérifiez le trousseau, sa méthode de déverrouillage et la disponibilité des variables protégées. Si le trousseau a été remplacé ou si la clé privée n’est plus récupérable, réinstallez les actifs depuis le dépôt de signature approuvé. Ne supprimez pas les trousseaux existants avant d’avoir exporté les informations nécessaires et confirmé qu’un autre chemin de récupération est disponible.

Le profil et les réglages de cible

Lorsque les actifs sont bien récupérés et que l’identité complète apparaît dans le trousseau, l’étape suivante est le rapprochement entre la cible et son Provisioning Profile.

Les dimensions à comparer

Examinez le profil utilisé par l’Archive et comparez-le à la cible sur les dimensions suivantes :

• Bundle ID exact ;
• Team ID ;
• type de profil : développement, ad hoc, distribution ou autre usage attendu ;
• certificat autorisé par le profil ;
• entitlements présents et réellement demandés ;
• Configuration et Scheme ;
• destination d’export.

Apple décrit la structure interne d’un Provisioning Profile dans la note technique TN3125 sur la signature de code. Cette référence est utile pour distinguer une identité de signature d’un profil : les deux objets sont liés, mais ils ne se remplacent pas.

Un profil peut être présent sur le disque et pourtant inutilisable pour la cible. Il peut également être valide pour l’application principale mais inadapté à une extension, à un service de notification ou à une cible de partage. Contrôlez chaque cible séparément, surtout si plusieurs applications utilisent un dépôt de signature commun.

Plusieurs Bundle ID et plusieurs cibles

Comment organiser plusieurs Bundle ID avec fastlane match ?

Traitez chaque identifiant comme une relation explicite entre une application, une cible, un type de profil et une identité. Dans votre configuration, ne vous contentez pas d’un nom générique tel que « production ». Documentez plutôt l’association entre <BUNDLE_ID_PRINCIPAL>, <BUNDLE_ID_EXTENSION>, les profils correspondants et la lane qui les consomme.

Avec plusieurs applications, une erreur de mapping peut installer un profil parfaitement valide, mais pour le mauvais identifiant. L’Archive échoue alors plus loin, donnant l’impression que le certificat est défectueux. Votre inventaire doit relier :

• l’application principale ;
• chaque extension ;
• le profil attendu par cible ;
• la Configuration concernée ;
• l’identité Apple Distribution utilisée ;
• la tâche d’export ou de publication.

Pour les profils absents, invalides ou supprimés, utilisez les outils de gestion de compte Apple afin de vérifier leur état avant toute nouvelle création. La page Apple consacrée à la modification, au téléchargement et à la suppression des profils constitue la référence appropriée. Les emplacements locaux et le comportement d’installation peuvent dépendre de la version de Xcode et de fastlane : ne figez pas un chemin trouvé dans un ancien agent sans le valider sur votre environnement actuel.

Le contraste entre local et distant

Un succès dans Xcode sur votre poste ne prouve pas que la tâche distante possède les mêmes entrées. Le poste local peut utiliser la signature automatique, un trousseau déjà déverrouillé, un Scheme différent ou des profils téléchargés depuis une session précédente.

Comparaison des environnements

Comparez explicitement les éléments suivants :

• version et chemin de l’outil Xcode actif ;
• compte utilisateur de construction ;
• Scheme et Configuration ;
• destination de l’Archive ;
• réglages CODE_SIGN_STYLE, équipe et identité ;
• profil transmis à l’export ;
• variables protégées et secrets disponibles ;
• commit exact du projet ;
• étape match exécutée avant la construction.

Sur le Mac distant, affichez uniquement les valeurs non sensibles nécessaires à la comparaison :

xcode-select -p
xcodebuild -version
xcodebuild -showBuildSettings \
  -workspace "<ESPACE_TRAVAIL>" \
  -scheme "<SCHEME>" \
  -configuration "<CONFIGURATION>"

Ne remplacez pas les placeholders par des informations réelles dans un article de support ou un journal public. L’objectif est de comparer l’environnement, pas de divulguer votre identifiant d’équipe ou votre architecture de publication.

Le rôle de readonly

Que faire lorsque match readonly ne trouve pas le Provisioning Profile ?

Considérez readonly comme une politique de consommation, non comme une capacité d’administration. La tâche peut installer ou utiliser les actifs déjà présents dans le stockage autorisé, mais elle ne doit pas être supposée capable de créer ou de renouveler ce qui manque. Si le profil n’existe pas, porte un mauvais Bundle ID ou n’est plus valide, une tâche en lecture seule doit échouer afin d’éviter une modification silencieuse de l’état de signature.

La réparation doit être effectuée dans un contexte administrateur contrôlé, puis les actifs validés dans le dépôt approuvé. Après cette étape, relancez la CI en readonly. Cette séparation réduit le risque qu’un agent de publication modifie les actifs pendant une panne.

La stratégie de réparation

Votre choix dépend de la couche confirmée, pas du texte le plus alarmant dans le journal.

Correction locale

Corrigez sur place lorsque l’actif est encore valide et que la panne vient :

• d’un jeton ou d’une permission de stockage ;
• d’un mauvais dépôt ou d’une mauvaise branche ;
• d’une variable de déchiffrement absente ;
• d’un trousseau non ciblé ;
• d’un mauvais mapping de Bundle ID ;
• d’une Configuration ou d’un export mal sélectionné.

Après chaque correction, relancez uniquement le diagnostic concerné. Ne changez pas simultanément le certificat, le profil et les réglages du projet.

Rotation contrôlée

Passez à une rotation lorsque le certificat ou le profil est expiré, révoqué, associé à une permission devenue invalide, ou clairement impossible à utiliser. Avant l’opération, consignez les relations entre certificats, profils, applications, extensions et tâches de publication.

La rotation doit être testée avec une branche non urgente. Faites une Archive, un export et une validation avant de toucher au flux de publication principal. Une nouvelle identité sans profil correspondant ne résout pas la chaîne complète.

Reconstruction exceptionnelle

Un certificat expiré impose-t-il l’exécution de match nuke ?

Non. Une expiration ne suffit pas à justifier cette commande. Commencez par une rotation ciblée et vérifiez l’impact sur les applications et profils concernés. La documentation officielle de match nuke indique qu’une telle opération agit sur les certificats et profils gérés : elle peut donc affecter plusieurs chaînes de distribution, pas seulement la cible qui échoue.

N’envisagez une reconstruction globale que si les actifs sont réellement irrécupérables, que l’étendue de l’impact est documentée et qu’un plan de recréation a été validé. Conservez une copie sécurisée des informations de référence et identifiez les applications, extensions et flux de publication touchés. Une reconstruction précipitée transforme souvent une panne d’une cible en incident de publication généralisé.

La grille de décision avant modification

Utilisez cette comparaison avant de choisir une action. Elle évite de traiter une panne d’accès comme une panne de certificat.

Le jalon d’acceptation après réparation

Ne considérez pas l’incident terminé parce que match s’est achevé sans erreur. La chaîne doit être validée par une construction représentative.

Procédez ainsi :

1. choisissez le même commit que celui qui échouait ;
2. exécutez match avant l’action de construction ;
3. utilisez le même Scheme et la même Configuration ;
4. lancez une Archive sur le Mac distant ;
5. exportez avec les options prévues pour la distribution ;
6. inspectez la signature et les entitlements ;
7. effectuez une validation avant l’envoi réel ;
8. redémarrez l’environnement si le problème concernait la persistance du trousseau ;
9. répétez l’Archive avec le processus non interactif ;
10. conservez le journal démasqué des secrets comme preuve de restauration.

Pour encadrer cette procédure, vous pouvez consulter notre guide de validation d’un environnement CI sur Mac distant. Si votre incident révèle une migration mal documentée, utilisez une liste de contrôle interne reliant chaque certificat, profil, application et tâche de publication. Pour les équipes qui enchaînent ensuite la publication, consultez séparément une documentation consacrée à l’automatisation fastlane et à la livraison TestFlight : elle ne remplace pas le diagnostic de signature présenté ici.

Le critère le plus utile est la répétition après redémarrage : une Archive et un export doivent fonctionner sans connexion graphique improvisée, avec les mêmes secrets protégés et le même compte de construction. Si seule votre session interactive réussit, la chaîne n’est pas encore fiable.

Si vos échecs viennent d’une machine temporaire réinitialisée, d’un trousseau qui ne persiste pas ou de tâches interrompues, le problème n’est pas seulement fastlane match : c’est la continuité de l’environnement. Un poste local peut conserver silencieusement une clé privée et un profil, tandis qu’un agent recréé perd ces éléments ; une infrastructure partagée peut en outre mélanger les comptes, les chemins et les permissions. Dans ce cas, louer un Mac distant VMSPIN pour un cycle de test non urgent permet de vérifier la chaîne sur une machine conservée dans le temps, avec un redémarrage comme véritable condition d’acceptation, plutôt que de conclure après une seule Archive interactive. Consultez les options de location de Mac distant VMSPIN seulement après avoir défini votre scénario de validation ; pour une charge lourde et permanente ou un besoin d’accès physique à des périphériques, l’achat et l’administration d’un Mac dédié peuvent rester plus adaptés.