La référence Apple de xcodebuild documente une action dédiée, -resolvePackageDependencies, pour résoudre les dépendances avant la compilation (référence des outils en ligne de commande Xcode). Si cette étape échoue à distance, vérifiez d’abord l’URL réellement utilisée, le compte macOS qui exécute la tâche et la source des identifiants ; contrôlez ensuite que Package.resolved est bien suivi par le dépôt. Xcode Cloud et une CI autogérée n’emploient pas le même parcours d’autorisation.
Ce guide s’adresse aux développeurs indépendants dont le projet fonctionne localement mais échoue en résolvant un package privé sur un Mac distant.
Il concerne aussi les personnes qui administrent xcodebuild ou un exécuteur macOS, ainsi que les petites équipes qui viennent de connecter une dépendance privée à Xcode Cloud.
Identifier l’étape qui échoue avant de toucher aux identifiants
Un statut final « échec de compilation » ne prouve pas que le problème vient d’un jeton ou d’une clé SSH. Dans le journal, cherchez la première erreur pertinente et établissez si elle survient pendant l’accès au dépôt, la résolution de version ou la compilation Swift. Apple distingue le flux de résolution et de construction dans sa documentation sur les workflows CI pour les packages Swift.
Exécutez l’enquête depuis le même point d’entrée que la tâche défaillante : le même projet ou espace de travail, le même schéma, le même répertoire de travail et, surtout, le même compte macOS. Si vous testez depuis une session graphique alors que le serveur de compilation lance xcodebuild sous un autre compte, vous ne vérifiez pas les mêmes clés, configuration Git ni agent SSH.
Votre machine locale résout le package, mais pas le Mac distant : quelle différence vérifier en premier ?
Comparez l’identité et le contexte d’exécution, pas seulement le contenu du projet. Un terminal local peut disposer d’une clé chargée dans ssh-agent, d’un accès au trousseau ou d’une configuration Git personnelle absente du compte qui lance la tâche distante. Le fait que le projet s’ouvre ou compile sur votre poste ne démontre donc pas que le processus distant peut authentifier sa connexion.
Relevez aussi le premier message d’erreur, sans le réduire à une étiquette générale. Un refus d’accès au dépôt, un hôte introuvable, une référence de version absente et une erreur du compilateur Swift ne désignent pas la même couche. Le diagnostic change selon que l’échec apparaît avant ou après le téléchargement des sources.
Comparer les deux parcours d’autorisation
Le tableau ci-dessous sert à choisir le bon chemin de vérification, pas à comparer les performances de deux services. Les appréciations sont des notes d’adéquation éditoriales : elles indiquent si le parcours convient à ce type de contrôle, et non un résultat de benchmark.
| Critère de diagnostic | Mac autogéré | Xcode Cloud |
|---|---|---|
| Où vérifier l’accès privé | Compte d’exécution, configuration Git, clé SSH et vérification de l’hôte | Connexion et autorisation SCM prévues pour le workflow |
| Premier élément à confirmer | L’identité utilisée par xcodebuild et l’URL du dépôt | L’autorisation accordée à la source de contrôle de versions |
| Configuration à ne pas transposer | Ne pas supposer que la session interactive fournit les identifiants à la tâche CI | Ne pas recopier mécaniquement la clé et l’agent SSH du Mac autogéré |
| Adéquation à un diagnostic où vous contrôlez l’hôte | 5/5 : accès direct au compte et à la configuration, sous réserve de vos droits d’administration | 3/5 : les contrôles se font dans le parcours Xcode Cloud, pas dans un compte shell que vous gérez |
Vérifier l’URL et l’accès réseau
Dans Package.swift, le projet Xcode et les informations de résolution, repérez la source déclarée pour chaque package privé. Apple décrit les déclarations de dépendances dans sa référence des packages Swift. Comparez cette source à celle réellement demandée par le processus distant : adresse SSH ou HTTPS, chemin du dépôt et référence attendue.
Ne remplacez pas une adresse SSH par une adresse HTTPS comme remède automatique. Ce changement peut modifier le mécanisme d’authentification sans corriger un dépôt inaccessible, un chemin incorrect ou une règle réseau qui bloque la connexion. Vérifiez séparément ces trois conditions :
- Le nom d’hôte est résolu et le serveur est joignable depuis la machine de compilation.
- Le chemin correspond au dépôt privé attendu et le compte possède les droits nécessaires.
- La branche, l’étiquette ou la révision demandée existe et reste accessible avec cette URL.
Étape 1 : établir le compte et la provenance des identifiants
Sur un Mac autogéré, identifiez le compte système qui lance réellement xcodebuild. Pour une tâche exécutée par un agent, une tâche planifiée ou un service, ne déduisez pas son identité à partir du compte connecté à l’interface graphique. Faites exécuter les vérifications dans le contexte réel du travail, en respectant les règles d’administration de votre environnement.
Vérifiez ensuite où se trouve la configuration Git pertinente et si le compte de tâche peut la lire. Une commande telle que git config --show-origin --get-regexp 'url\..\.insteadof|credential\..' peut aider à repérer une règle ou un fournisseur configuré, à condition de ne pas publier sa sortie si elle révèle des informations internes. La configuration Git de votre compte personnel n’est pas automatiquement celle d’un autre utilisateur macOS.
Comment faire en sorte que xcodebuild utilise une clé SSH sur un Mac autogéré ?
La clé doit être accessible au compte qui exécute la tâche, et non uniquement à votre session interactive. Vérifiez le chargement de l’agent SSH dans ce contexte, les permissions du fichier, la présence d’une entrée d’hôte connue et l’accès effectif au dépôt avec l’identité attendue. N’assouplissez pas la vérification de l’hôte pour contourner une erreur : il faut établir l’identité du serveur par une source de confiance avant d’ajouter ou de modifier une entrée known_hosts.
Effectuez le test d’accès sans afficher la clé privée ni un jeton. Si l’environnement utilise une clé temporaire, prévoyez son injection et son retrait dans le mécanisme secret de votre CI ; évitez de la copier dans le dépôt, dans un script suivi par Git, dans une URL ou dans une sortie de compilation. Les options précises dépendent du mode de lancement et de la politique de sécurité de l’exécuteur : documentez la provenance de l’identifiant et le compte auquel il est destiné.
Étape 2 : traiter Xcode Cloud selon son propre mécanisme
Xcode Cloud ne doit pas être diagnostiqué comme un Mac autogéré auquel on se connecterait pour inspecter un fichier ~/.ssh/config. Pour un package privé, suivez le parcours d’autorisation SCM prévu pour ce service et vérifiez que l’autorisation porte sur le bon dépôt et sur le projet concerné. La procédure Apple de connexion à la source de code décrit le flux correspondant.
Où accorder l’accès à un package privé dans Xcode Cloud ?
Commencez par les réglages d’accès à la gestion du code source et des dépendances de Xcode Cloud, puis vérifiez que le fournisseur connecté et le dépôt privé sont bien inclus dans l’autorisation attendue. Confirmez le résultat dans le journal du workflow, sans chercher à réutiliser une clé personnelle provenant d’un Mac de développement. Les intitulés et emplacements d’interface peuvent évoluer ; confirmez-les dans la documentation Apple correspondant à la version utilisée plutôt que d’appliquer une capture d’écran ancienne.
Si l’autorisation paraît correcte mais que le journal indique toujours un refus, vérifiez l’identité associée à la connexion, l’accès au dépôt et l’URL déclarée par le projet. Ne modifiez pas simultanément l’autorisation, l’adresse et la version du package : sinon, vous ne pourrez pas savoir quel changement a résolu l’incident.
Étape 3 : contrôler Package.resolved et la reproductibilité
Package.resolved permet de fixer les révisions choisies pour les dépendances dans un contexte de construction CI ; Apple le présente dans ses [recommandations CI pour les packages Swift](https://developer.apple.com/documentation/xcode/building-swift-packages-or-apps-that-use-them-in-continuous-integration-workflows?v=1.1.1). Vérifiez que le fichier attendu par votre projet est présent au bon emplacement et suivi par le contrôle de versions. Son emplacement dépend de la structure du projet et du mode de construction : ne supposez pas qu’un fichier trouvé sur votre poste est nécessairement celui lu par le workflow distant.
L’absence de Package.resolved peut-elle faire choisir d’autres dépendances à distance ?
Oui, le résultat peut différer si le contexte distant résout les contraintes sans le verrouillage que vous attendiez. Comparez les révisions résolues dans le journal ou dans les artefacts de la tâche avec celles de votre branche. Si elles ne correspondent pas, corrigez le suivi du fichier ou le contexte de résolution avant de modifier les contraintes des packages.
L’objectif n’est pas de forcer une résolution automatique pour faire disparaître l’erreur. Une nouvelle résolution ne corrigera ni une autorisation manquante ni un dépôt inaccessible ; elle peut aussi masquer une divergence entre la version testée localement et celle obtenue en CI. Si vous envisagez d’utiliser le comportement de Git de macOS plutôt qu’un comportement fourni par Xcode, vérifiez d’abord les recommandations Apple applicables à votre flux et à votre version d’outils.
Étape 4 : vérifier les secrets avant de relancer
Avant de changer une clé, un jeton, une configuration Git partagée ou un cache, identifiez l’étendue du changement et prévoyez un retour arrière. Un cache peut accélérer une résolution ultérieure, mais son nettoyage ne remplace pas la preuve que l’URL, les droits et la révision sont corrects. Si vous le purgez, notez ce qui est supprimé et vérifiez ensuite que le comportement reproduit celui de la tâche de production.
Cherchez les secrets dans les scripts suivis, les variables écrites dans des fichiers, les sorties de commandes et les journaux déjà produits. Si un secret a pu être exposé, ne vous contentez pas d’effacer la ligne visible : prévoyez sa révocation ou son remplacement, vérifiez où il a été diffusé et testez les accès avec le nouvel identifiant. Réduisez les droits accordés au strict nécessaire pour lire les dépôts requis par la compilation.
La rotation peut elle-même interrompre les tâches qui dépendent d’une ancienne valeur. Préparez donc l’ordre des opérations : mettre à jour le mécanisme de stockage sécurisé, vérifier le compte et le dépôt concernés, relancer une tâche contrôlée, puis révoquer l’ancien secret lorsqu’il n’est plus utilisé. Ne placez jamais un jeton dans l’URL du dépôt pour éviter de configurer correctement l’authentification.
Liste de contrôle avant une nouvelle compilation
- [ ] J’ai identifié la première erreur dans le journal, et non seulement le statut final de la tâche.
- [ ] J’ai relevé l’URL du dépôt et confirmé le nom d’hôte, le chemin ainsi que la référence demandée.
- [ ] J’ai confirmé le compte macOS qui lance réellement
xcodebuild. - [ ] Sur un Mac autogéré, j’ai testé l’accès au dépôt sous ce compte et vérifié la disponibilité de la clé, de l’agent SSH et de l’hôte connu.
- [ ] Dans Xcode Cloud, j’ai vérifié l’autorisation SCM propre à ce flux au lieu de copier une configuration SSH locale.
- [ ] J’ai contrôlé que le
Package.resolvedattendu existe, est suivi et correspond aux révisions voulues. - [ ] J’ai vérifié qu’aucun secret n’apparaît dans le dépôt, l’URL, les scripts ou les journaux.
- [ ] J’ai relancé une tâche depuis le même point d’entrée et le même contexte que la construction de production.
Choisir l’environnement selon la cause
Si l’échec vient d’un droit manquant sur le dépôt ou d’une révision absente, changer de machine ne corrigera pas la cause. Si, en revanche, vous confirmez que l’accès fonctionne et que le verrouillage est cohérent, mais que le Mac autogéré manque d’un compte de construction isolé, d’une configuration SSH maîtrisée ou d’une disponibilité adaptée à vos tâches, évaluez séparément l’environnement d’exécution.
L’autohébergement vous donne le contrôle direct sur le compte, les outils et les secrets, mais vous devez aussi maintenir l’hôte, protéger ses identifiants et éviter que la configuration d’un utilisateur interactif soit confondue avec celle de la CI. Xcode Cloud évite l’administration d’un hôte macOS, mais son autorisation des dépendances suit son propre parcours et ne se transpose pas en configuration shell libre. Un Mac local évite une partie de cette séparation, tout en mobilisant une machine et son stockage pour les constructions qui doivent tourner hors de votre session de travail.
Si la cause est propre à l’hôte autogéré et que vous souhaitez isoler le rôle de la machine sans acheter immédiatement un Mac dédié, vous pouvez examiner les options de Mac distant de MACGPU et vérifier si elles correspondent à votre mode d’accès et d’administration. Une location ne dispense pas de configurer des identifiants sûrs et ne convient pas forcément à un usage durable à forte charge ou à un besoin d’interfaces physiques locales ; elle peut toutefois éviter de réserver un Mac acheté à un seul rôle de compilation. Pour comparer un environnement distant avec votre flux actuel, consultez également la présentation des Mac disponibles, puis retenez cette solution seulement si le contrôle du compte et des secrets répond à vos exigences de construction.