Dans sa documentation, fastlane recommande le mode readonly pour l’intégration continue : si la récupération des éléments de signature échoue, ne recréez pas immédiatement les certificats. Distinguez d’abord l’accès au dépôt privé, le secret de déchiffrement et l’autorisation du compte Apple, puis contrôlez le certificat, sa clé privée et le profil. En CI comme sur un Mac distant sans surveillance, réservez les opérations d’écriture aux personnes autorisées.

Cet article s’adresse aux développeurs qui déploient fastlane match sur un nouveau Mac distant et ne parviennent pas à récupérer les éléments de signature.
Il concerne aussi les petites équipes qui partagent un dépôt de certificats et doivent limiter les droits d’écriture.
Vous y trouverez une méthode de diagnostic pour une migration vers un Mac ou un environnement CI.

Commencez par identifier l’étape qui échoue

Un message général tel que « clone failed » ou « signing certificate not found » ne suffit pas à localiser la panne. fastlane match peut atteindre le dépôt sans réussir à déchiffrer les fichiers. Il peut aussi récupérer les éléments, mais ne pas rendre disponible une identité de signature utilisable par Xcode. Chaque cas relève d’une couche différente et appelle un contrôle différent.

Avant de modifier l’environnement, repérez la dernière opération réussie dans la sortie fastlane. Vérifiez si l’échec arrive au moment d’établir la connexion au stockage, de lire son contenu, de déchiffrer les certificats ou de préparer la signature. Les chemins, noms d’utilisateur, identifiants de dépôt et détails d’erreur doivent être masqués avant tout partage de journal.

Ce que vous observez Couche à examiner Vérification initiale
Refus de connexion ou dépôt introuvable Identité Git et autorisation du dépôt Tester l’accès avec le même compte et le même mode d’authentification que fastlane
Le dépôt est atteint, mais les éléments ne sont pas déchiffrés Secret de chiffrement de match Contrôler l’injection du secret et le nom de la variable utilisée
Les éléments sont récupérés, mais la signature échoue Certificat, clé privée, profil et trousseau Vérifier que l’identité complète et le profil correspondent au projet
L’échec apparaît pendant une vérification Apple Compte développeur et autorisation Distinguer la validation du compte de l’absence d’un fichier de signature local

Un test Git ne prouve pas que le secret de match est correct. À l’inverse, une erreur de déchiffrement n’indique pas nécessairement un problème de clé SSH. Gardez ces vérifications séparées : vous éviterez de changer plusieurs secrets à la fois et de rendre le diagnostic plus difficile.

Sur un nouveau Mac distant, vérifiez l’identité Git réelle

Comment distinguer un refus d’authentification Git d’un mot de passe match incorrect ?
Si la connexion au dépôt privé est refusée avant que son contenu soit accessible, examinez l’identité Git et ses autorisations. Si Git accède au dépôt, mais que les fichiers chiffrés ne peuvent pas être ouverts, examinez plutôt le secret de match. Ces deux identifiants remplissent des fonctions différentes : l’un autorise l’accès au stockage, l’autre déchiffre les éléments qu’il contient.

Commencez par confirmer le mode de stockage réellement configuré : connexion SSH, URL HTTPS avec identifiant approprié, ou autre backend prévu dans le projet. N’effectuez pas le test depuis votre session personnelle si le build est exécuté sous un autre compte système. Sur une machine distante, le trousseau SSH, les variables d’environnement et les identifiants enregistrés peuvent être propres à l’utilisateur qui lance le processus.

Pour un dépôt Git, la commande git ls-remote affiche les références visibles sur le dépôt distant. Exécutez-la avec l’URL masquée dans tout extrait partagé et avec l’identité prévue pour la tâche. Si la commande échoue, la panne se situe vraisemblablement avant la lecture ou le déchiffrement des fichiers. Si elle réussit, cela confirme seulement que cette identité peut consulter les références visibles ; ce n’est pas la preuve que match peut déchiffrer les éléments ou signer l’application.

En mode SSH, vérifiez quelle clé est effectivement proposée à la connexion, plutôt que de supposer que la clé de votre ordinateur local a été copiée sur le Mac distant. La procédure de test de connexion SSH documentée par GitHub permet de contrôler l’identité présentée. Si le dépôt utilise une clé de déploiement, contrôlez aussi son association au bon dépôt et les droits qui lui sont accordés ; la documentation sur les clés de déploiement décrit ce mécanisme.

Environnement qui lance le build Identité et secret à contrôler Erreur à ne pas confondre
Mac distant lancé sous votre compte Clé SSH ou identifiant HTTPS de cette session Les accès configurés sur votre poste habituel ne sont pas nécessairement disponibles
Tâche automatisée sur le Mac Compte système, environnement et méthode d’injection des secrets Un test réussi dans le terminal interactif ne valide pas automatiquement la tâche planifiée
GitHub Actions Secret disponible pour le contexte d’exécution du workflow et identité autorisée sur le dépôt de signature Un secret absent ou inaccessible à ce workflow n’est pas une erreur de déchiffrement confirmée
Développeurs d’une équipe Droits attribués à chaque identité utilisée Partager un compte personnel ne clarifie ni l’accès ni la responsabilité

Pour un déploiement sensible, ne rendez pas public le dépôt de signature et ne remplacez pas un droit manquant par le partage d’un mot de passe personnel. Rétablissez l’accès pour l’identité du build, dans le périmètre requis. Si vous utilisez les secrets de GitHub Actions, vérifiez qu’ils sont disponibles dans le contexte réel du workflow et ne les affichez pas dans les journaux.

Lorsque le dépôt est accessible, contrôlez le secret de déchiffrement

La réussite de git ls-remote ou d’un clonage ne valide pas le secret configuré pour match. Une fois le dépôt accessible, une erreur de lecture des éléments chiffrés oriente vers le secret de déchiffrement, son injection dans l’environnement et le nom de la variable effectivement utilisé par la configuration.

Sur le Mac distant, comparez la configuration de la tâche avec celle du projet, sans imprimer la valeur secrète dans le terminal ou dans le journal du build. Vérifiez que le secret est transmis au processus fastlane qui exécute le lane, et pas uniquement à une session de terminal ouverte à la main. Pour une tâche automatisée, une variable définie dans votre profil interactif peut ne pas exister dans l’environnement du processus qui démarre le build.

En CI, inspectez les références aux secrets et leur portée, sans en afficher le contenu. Confirmez que le workflow concerné reçoit le secret attendu et que la configuration fastlane lit bien le même nom de variable. Un changement récent de nom, une tâche de publication déclenchée dans un contexte différent ou une configuration locale non reproduite dans la CI peuvent expliquer la divergence.

Ne placez jamais le secret de match dans le dépôt, dans une commande conservée dans l’historique ou dans un journal consultable. Si vous suspectez une valeur erronée, corrigez sa source dans votre gestionnaire de secrets, puis relancez le contrôle sans exposer la valeur. Modifiez une seule couche à la fois : vous saurez ainsi si la correction a rétabli le déchiffrement sans toucher aux autorisations Git ni aux certificats.

Si match récupère les fichiers, examinez la chaîne de signature

Pourquoi Xcode ne trouve-t-il toujours pas le certificat après une récupération réussie ?
Parce que la récupération et la disponibilité d’une identité exploitable ne sont pas la même chose. Une identité de signature doit réunir un certificat et la clé privée correspondante ; Apple explique le rôle de ces éléments dans la signature de code. Contrôlez donc le trousseau utilisé par le processus de compilation et la présence de la clé privée associée, pas uniquement celle d’un certificat.

Sur le Mac distant, identifiez le trousseau visé par le build. Une ouverture de session graphique peut avoir accès à un trousseau déverrouillé alors qu’un processus automatisé s’exécute dans un autre contexte. Comparez le compte qui lance fastlane, le trousseau interrogé et les paramètres de signature du projet. Si le certificat apparaît sans sa clé privée associée, l’identité ne peut pas remplir le rôle attendu pour signer.

Examinez ensuite le profil de provisionnement. Il doit correspondre à l’application et aux conditions de signature du build, notamment à l’identifiant d’application et aux capacités requises par le projet. La documentation Apple sur les conditions associées aux profils de provisionnement aide à examiner cet accord. Si le profil est obsolète ou ne correspond pas à la configuration, consultez le processus Apple pour modifier, télécharger ou supprimer un profil, puis choisissez une correction compatible avec les règles de l’équipe.

Une validation du compte développeur Apple qui échoue n’est pas la même panne qu’une clé privée manquante dans le trousseau. Avant de régénérer un certificat, déterminez si l’échec survient pendant une opération liée au compte, au moment de charger les éléments ou lors de la signature locale. Recréer ou révoquer un certificat sans connaître les dépendances peut affecter d’autres builds ou membres de l’équipe, sans réparer la cause initiale.

Dans une équipe ou en CI, séparez lecture et écriture

fastlane indique que le mode readonly convient à la CI : l’automatisation peut récupérer les éléments de signature sans être autorisée à en créer ou modifier. Le choix de ce mode réduit les changements involontaires dans le dépôt partagé. Une opération d’écriture doit rester un acte explicite, réalisé par une personne disposant de l’autorisation requise selon le processus de l’équipe.

Répartissez les responsabilités avant de corriger le workflow. La personne qui développe l’application a besoin des accès prévus pour son travail, mais ne doit pas nécessairement administrer le dépôt de signature. La personne qui maintient ce dépôt gère les autorisations et les opérations d’écriture. La personne qui entretient la CI configure l’identité d’exécution et les secrets nécessaires, sans les exposer dans les journaux.

Pour GitHub Actions, vérifiez aussi la disponibilité réelle des secrets pour le contexte qui lance le workflow. Le guide officiel sur la portée et les contraintes des secrets Actions vous aide à confirmer qu’un secret existe bien là où il est attendu. Si la tâche automatise uniquement une compilation ou une archive, préférez une lecture seule. Si une rotation ou une création est nécessaire, confiez cette action à la personne habilitée, en suivant le processus convenu, plutôt que d’élargir les droits d’écriture de tous les builds.

Choisissez votre prochain contrôle selon les indices disponibles :

  • Si le test Git n’atteint pas le dépôt, corrigez l’identité ou l’autorisation de lecture. Ne touchez pas au secret de déchiffrement tant que l’accès n’est pas établi.
  • Si le dépôt est lisible mais que les fichiers chiffrés restent inutilisables, vérifiez la valeur injectée et le nom de la variable de match. Ne créez pas de nouveau certificat pour traiter cette erreur.
  • Si les éléments sont récupérés et déchiffrés, mais que Xcode ne signe pas, examinez le couple certificat-clé privée, le trousseau et le profil associé au projet.
  • Si seul un contrôle du compte Apple échoue, vérifiez l’autorisation et le contexte de ce contrôle. Ne concluez pas à une panne Git ou à l’absence d’un certificat sans indice correspondant.
  • Si l’exécution est non interactive, ou si le build est lancé par une CI, conservez readonly pour les récupérations courantes. Réservez les écritures aux responsables désignés.

Après correction, validez un vrai build avant de clore l’incident

Une commande de récupération réussie ne prouve pas que votre application peut être signée, archivée et remise à l’équipe de publication. Validez la chaîne par étapes, en conservant une preuve pour chaque résultat. Cela vous permet d’identifier précisément le point encore bloquant si l’incident réapparaît.

Commencez par confirmer que le processus d’exécution atteint le dépôt avec l’identité prévue. Ne copiez pas les informations d’authentification dans le compte rendu : consignez uniquement le résultat du contrôle et le contexte concerné. Vérifiez ensuite que match récupère et déchiffre les éléments sans afficher de secret.

Contrôlez l’identité disponible dans le trousseau effectivement utilisé par le build. Vérifiez la présence du certificat et de sa clé privée associée, puis confirmez que le profil de provisionnement convient à l’application et à ses capacités. Notez séparément les résultats : dépôt accessible, éléments déchiffrés, identité reconnue et profil adapté. Cette séparation évite de qualifier de « réparée » une chaîne qui ne fonctionne qu’à moitié.

Enfin, lancez une compilation avec les paramètres et l’identité de signature réellement prévus pour la livraison. Validez l’archive attendue et son résultat de signature dans l’environnement cible. Une compilation sans signature, un simple accès au dépôt ou la présence d’un certificat dans le trousseau ne remplace pas cette preuve de bout en bout.

Avant de révoquer, remplacer ou supprimer un élément du trousseau, recherchez les projets et workflows qui en dépendent. Confirmez qui peut effectuer la modification, préservez les éléments nécessaires au retour arrière selon les règles de votre équipe et documentez le résultat. Une révocation précipitée peut élargir l’incident à des builds qui fonctionnaient jusque-là.

Si le blocage vient du manque d’un environnement macOS utilisable pour les compilations signées, plutôt que d’une panne de match, vous pouvez examiner les options de Mac distant proposées par MACCOME. Par rapport à un Mac local déjà saturé, à une machine Windows ou Linux qui ne fournit pas l’environnement Xcode nécessaire, ou à un poste éteint quand le build doit tourner, un Mac distant peut offrir un environnement de compilation accessible sans acheter une machine dédiée. Il ne remplace toutefois pas une politique de secrets correcte et ne convient pas forcément à un usage lourd et permanent ou à un besoin d’accès physique. Si vos builds sont ponctuels, choisissez une formule selon leur fréquence réelle ; pour un environnement à maintenir dans la durée, comparez aussi le coût total d’un achat et les besoins d’exploitation. Vous pouvez consulter les informations MACCOME en français avant de décider si la location correspond à votre chaîne de signature.