Commencez par identifier le compte macOS qui exécute réellement le Runner et l’état du trousseau auquel ce compte accède ; vérifiez ensuite l’identité de signature et le profil correspondant. Si Xcode signe depuis une session locale mais que l’archive échoue dans GitHub Actions, ne concluez pas que le certificat est défectueux avant d’avoir comparé ces contextes.
Ce guide s’adresse aux développeurs iOS et macOS qui doivent expliquer un écart entre leur poste et la CI.
Il concerne aussi les ingénieurs DevOps responsables d’un Runner Mac auto-hébergé et les personnes qui administrent les certificats de publication.
Chaque rôle dispose ici d’indices à recueillir, de limites de responsabilité et d’une prochaine étape à transmettre.
[ SECTION_01 ] La signature échoue à une frontière précise, pas à un endroit abstrait
Un message de signature apparaît souvent à la fin d’un long travail de compilation. Cela ne signifie pas que le certificat est la cause. La compilation peut s’arrêter avant la création de l’archive, échouer au choix de l’identité, manquer d’accès à une clé privée ou rejeter un profil qui ne correspond pas à la cible.
Pour éviter les changements au hasard, partez d’une exécution identifiable : même commit, même schéma, même cible et mêmes paramètres de signature pour la comparaison locale et la CI. Dans les journaux, notez la dernière étape réussie, la première erreur liée à la signature et la commande de construction exécutée. Ne masquez pas les lignes précédentes : elles peuvent montrer qu’une mauvaise configuration a sélectionné une autre cible.
Les journaux et procédures de diagnostic des Runners auto-hébergés permettent de distinguer un problème de service ou d’exécution d’un problème propre au projet. La première transmission doit donc contenir des observations, pas une hypothèse telle que « le certificat a expiré ».
[ SECTION_02 ] Les développeurs établissent d’abord la cohérence du projet
La personne qui connaît le projet vérifie le schéma utilisé par le Workflow, la cible réellement archivée et le mode de signature prévu. Une compilation lancée localement avec un autre schéma n’est pas une comparaison suffisante. Les paramètres de construction exposés par la référence des réglages Xcode aident à retrouver les valeurs qui influencent la signature et l’identification de l’application.
Il faut ensuite distinguer la signature automatique de la signature manuelle. Dans le premier cas, les réglages du projet et l’environnement Xcode déterminent les ressources employées. Dans le second, le Workflow ou les paramètres du projet peuvent désigner explicitement une identité et un profil. Changer de méthode sans l’avoir documenté rend les résultats difficiles à interpréter.
Le développeur compare notamment l’identifiant de l’application, l’équipe, la configuration de construction et le profil attendu. Les valeurs sensibles ou propres au dépôt restent masquées dans les rapports : utilisez des formes telles que [BUNDLE_ID], [TEAM_ID] et [PROFIL], jamais des identifiants réels accompagnés de secrets. La documentation Apple sur la construction et l’exécution d’une application décrit le lien entre la configuration du projet et le processus de construction.
| Observation comparée | Indice en faveur du projet | Indice en faveur du Runner | Force de l’indice |
|---|---|---|---|
| Le même commit sélectionne des cibles différentes | Schéma ou paramètres différents | Le Workflow invoque une autre commande que celle attendue | Forte |
| L’identité ou le profil sélectionné diffère | Réglages de signature différents | Le contexte CI ne voit pas les mêmes ressources | Moyenne |
| La compilation s’arrête avant l’archive | Erreur de cible ou de configuration | Outil ou environnement d’exécution différent | Moyenne |
| Le projet est cohérent, mais la clé reste inaccessible | Peu probable sans écart de réglage | Compte, trousseau ou service à examiner | Forte |
Le tableau sert à orienter la transmission, non à prouver une cause à lui seul. Un indice fort doit être confirmé dans le journal de construction et dans l’environnement qui a réellement exécuté le travail.
[ SECTION_03 ] Les responsables DevOps vérifient le compte effectif et le trousseau macOS
Une connexion SSH réussie prouve que l’utilisateur SSH peut ouvrir une session ; elle ne prouve pas que le processus du Runner travaille sous ce même compte. Un Runner lancé comme service peut avoir un contexte différent de celui d’un terminal interactif. C’est pourquoi il faut relever le compte effectif depuis le Workflow ou les journaux, puis le comparer au compte attendu dans l’exploitation.
Pour un Runner géré par launchd, consignez le mode de lancement, l’état du service et les journaux associés. La documentation GitHub sur la configuration de l’application Runner décrit la gestion de l’application ; la procédure de diagnostic GitHub complète ces vérifications lorsque le service ne démarre pas ou ne produit pas les journaux attendus.
Le contrôle du trousseau doit, lui aussi, être effectué depuis le contexte du travail CI. Il faut déterminer si ce compte voit le trousseau requis et si l’accès à la clé privée est possible au moment de la signature. Un essai dans le terminal d’un administrateur ou dans une session de bureau ne remplace pas ce contrôle. Le résultat utile est une comparaison : compte du Workflow, trousseau accessible, état observé et résultat de l’opération de signature, sans exposer le contenu du trousseau.
Cette séparation explique un cas fréquent : la signature fonctionne dans Xcode localement, tandis que GitHub Actions ne trouve pas l’identité ou ne peut pas l’utiliser. Le projet peut être correctement réglé ; c’est le processus CI qui n’a pas accès aux mêmes ressources. À l’inverse, si le Runner et le trousseau sont conformes, l’enquête doit revenir aux réglages du projet et au profil sélectionné, plutôt que d’accorder des droits supplémentaires.
[ SECTION_04 ] Les administrateurs de signature distinguent certificat, clé et profil
Une identité visible n’est pas automatiquement utilisable par le processus. La documentation Apple présente les identités de signature comme des identifiants employés par les opérations de sécurité ; l’équipe doit donc vérifier la disponibilité de l’identité et de la clé privée correspondante dans le contexte d’exécution. La présence d’un certificat seul n’atteste pas l’accès complet nécessaire à la signature.
La note technique d’Apple sur les certificats de signature de code permet d’approfondir la composition et le rôle des certificats. Elle ne remplace pas la vérification sur le Runner : l’administrateur doit confirmer que les éléments attendus sont présents et utilisables par le compte concerné, sans copier une clé privée dans les journaux ou dans un dépôt.
Le profil de provisionnement mérite une vérification distincte. Il doit correspondre à l’application, à l’équipe et à l’usage visé. Un profil qui ne convient pas à la cible peut faire échouer la signature même si le trousseau et l’identité sont accessibles. Pour une distribution donnée, confrontez les caractéristiques attendues à la documentation Apple sur la création d’un profil App Store.
| Élément examiné | Ce que sa présence permet de conclure | Ce qu’elle ne permet pas de conclure | Responsable de la vérification |
|---|---|---|---|
| Certificat | Un certificat correspondant est disponible dans l’environnement observé | Que le processus CI peut utiliser la clé privée | Administration des signatures |
| Identité de signature | Une identité apparaît dans le contexte testé | Que le profil convient à la cible ou à la distribution | Administration et DevOps |
| Clé privée | Le matériel nécessaire peut être accessible dans le contexte contrôlé | Que les autorisations sont appropriées pour tous les travaux | Sécurité et administration |
| Profil de provisionnement | Un profil peut être sélectionné | Que son application, son équipe et son usage concordent avec la cible | Développement et publication |
Avant toute importation ou rotation, consignez la ressource modifiée, la raison, l’approbateur et la procédure de retour arrière. Si une identité fonctionne pour d’autres travaux, la remplacer sans preuve peut transformer une panne circonscrite en incident de publication. Le bon ordre est de comparer, d’isoler l’écart, puis de modifier l’élément démontré en cause.
[ SECTION_05 ] La sécurité réduit l’exposition sans élargir les privilèges
Les secrets de signature ne doivent pas devenir accessibles à des travaux qui n’en ont pas besoin. Les personnes responsables examinent quels dépôts et quels déclencheurs peuvent atteindre le Runner, quelles tâches reçoivent des données sensibles et qui peut modifier le Workflow. La documentation GitHub sur l’utilisation sécurisée des actions donne le cadre à consulter pour limiter l’exposition des secrets et évaluer les risques liés aux tâches exécutées.
Lorsque plusieurs projets partagent un hôte, une panne de signature peut aussi révéler une frontière de confiance mal définie. Cela ne justifie pas de désactiver les contrôles ni d’accorder un accès général au trousseau. Il faut plutôt restreindre le routage des travaux, limiter les comptes autorisés à déclencher les tâches de publication et documenter les changements avec leur périmètre et leur retour arrière.
La personne chargée de la sécurité n’a pas à diagnostiquer chaque paramètre Xcode. Elle doit pouvoir répondre à trois questions : quel travail peut atteindre les secrets, quel compte exécute ce travail et quelle équipe autorise l’accès ? Si la réponse reste incertaine, suspendre le travail de signature ou l’isoler est plus défendable que d’élargir les droits pour faire disparaître le message d’erreur.
[ SECTION_06 ] Les questions fréquentes précisent les vérifications à transmettre
Pourquoi Xcode local signe-t-il alors que GitHub Actions ne trouve pas l’identité ?
Une session Xcode peut accéder à un compte et à un trousseau différents de ceux du Runner. Comparez d’abord le compte effectif et le trousseau observés dans le Workflow avec ceux de la session locale. Si ces éléments concordent, examinez ensuite le schéma, la cible, les paramètres de signature et le profil sélectionné. Cette séquence évite de renouveler un certificat avant d’avoir établi que la CI utilise le même contexte.
Une connexion SSH réussie prouve-t-elle que le Runner peut signer ?
Non. Elle prouve que la session SSH peut accéder à l’hôte, pas que le service Runner s’exécute sous le même compte ou possède le même accès au trousseau. Faites produire au Workflow des observations sans secret sur son contexte, puis rapprochez-les des journaux et du mode de lancement du service. Évitez de laisser des clés, certificats privés ou valeurs secrètes apparaître dans la sortie.
Comment repérer le compte macOS et le trousseau réellement utilisés ?
La vérification doit être produite par le travail CI lui-même, et non déduite du compte connecté en SSH. Relevez le compte effectif, les trousseaux accessibles et l’état observé au moment du travail ; comparez ces éléments aux journaux du Runner et à sa configuration de service. Si une session interactive donne un résultat différent, transmettez précisément cet écart à l’équipe d’exploitation.
Une identité visible suffit-elle si Xcode refuse encore la signature ?
Non : il reste à vérifier l’accès à la clé privée et la compatibilité du profil avec la cible. Contrôlez l’identifiant de l’application, l’équipe et l’usage du profil, puis confirmez que la tâche de signature est exécutée par le compte attendu. Une fois ces éléments cohérents, relancez une archive complète dans un Workflow propre ; un simple succès de compilation ne valide pas la signature.
[ SECTION_07 ] La publication n’est rétablie qu’après un archivage reproductible
La validation doit reproduire le chemin réel de publication, depuis une exécution propre du Workflow jusqu’à l’inspection du résultat archivé. Une CI qui est en ligne, une compilation réussie ou une identité visible ne suffisent pas : elles ne démontrent pas à elles seules que l’archive est signée comme prévu.
La vérification s’organise en étapes transmissibles :
- [ ] Le commit, le schéma, la cible et les paramètres de signature correspondent à ceux attendus pour la publication.
- [ ] Le Workflow identifie le compte macOS réellement utilisé, sans se reposer sur le compte de la session SSH.
- [ ] Le Runner exécute le travail dans un contexte confirmé par ses journaux et, s’il s’agit d’un service, par son état de fonctionnement.
- [ ] Le trousseau requis est accessible depuis ce contexte et l’identité peut être utilisée avec sa clé privée.
- [ ] Le profil correspond à l’application, à l’équipe et à l’usage de distribution prévus.
- [ ] Aucun secret n’apparaît dans les journaux et les autorisations du travail de signature restent limitées.
- [ ] Une archive issue d’un Workflow propre a été inspectée et la procédure peut être répétée.
- [ ] Les modifications apportées aux certificats, profils, comptes ou autorisations ont un responsable et une méthode de retour arrière.
Si un point reste non vérifié, le responsable de publication ne devrait pas considérer la chaîne réparée. En cas de contexte instable ou de privilèges impossibles à limiter, isolez le travail de signature et rétablissez un environnement maîtrisé avant de réautoriser une publication. Ce seuil d’acceptation sépare une correction reproductible d’un succès ponctuel impossible à expliquer.
[ SECTION_08 ] Choisir un Runner maîtrisable plutôt que masquer l’écart
Une machine déjà partagée peut sembler commode, mais elle crée des coûts opérationnels peu visibles : compte d’exécution ambigu, trousseau difficile à attribuer, travaux concurrents et accès aux secrets plus difficiles à délimiter. À l’inverse, un hôte dédié demande une gestion explicite du cycle de vie, des accès et des mises à jour. Le choix dépend donc moins du message d’erreur que de la capacité de l’équipe à maintenir une frontière claire entre travaux de confiance et tâches ordinaires.
Un Mac local reste pertinent lorsque l’équipe a besoin d’un accès physique, d’interfaces matérielles ou d’une station de développement utilisée en continu. Pour un nœud CI ponctuel ou une capacité distante, il est possible de comparer l’exploitation interne à un Mac accessible à distance ; la présentation des solutions Mac de NOVAKVM permet d’examiner cette piste sans remplacer la validation technique de la chaîne de signature. Un achat matériel peut aussi mieux convenir à une charge stable et durable ; le guide de commande du Mac mini de NOVAKVM constitue une autre voie à évaluer selon le mode d’exploitation souhaité.
Une fois le diagnostic établi, évitez de conserver une solution temporaire qui élargit les privilèges ou dépend d’une session interactive. Si le problème vient du contexte d’exécution et qu’un environnement macOS disponible à distance répond mieux au besoin, évaluez un nœud séparé avec des accès explicites et une procédure de réception fondée sur l’archive réelle. NOVAKVM peut être envisagé pour ce besoin de capacité distante ; si l’équipe dispose déjà d’un Mac adapté, d’un accès physique indispensable ou d’une charge permanente qu’elle sait exploiter, conserver l’infrastructure existante peut rester le meilleur choix.