Échec de récupération d’un Swift Package privé avec Xcode 27 sur Mac distant ? Guide de correction 2026

Commencez par vérifier le compte macOS qui exécute réellement la tâche CI, puis ses clés SSH et son fichier known_hosts ; contrôlez ensuite Package.resolved et l’URL du dépôt privé. Ne désactivez pas la vérification d’hôte et ne videz pas les caches avant d’avoir identifié à quelle étape la récupération échoue.

Cette méthode concerne les développeurs qui compilent un projet Xcode 27 sur Mac distant avec des dépendances Swift privées. Elle s’adresse aussi aux équipes DevOps qui administrent les comptes de compilation et aux responsables qui déplacent une compilation locale vers un environnement distant.

Un message indiquant qu’un package est introuvable ne désigne pas nécessairement une version absente. La résolution peut échouer parce que le compte du processus ne peut pas lire le dépôt, parce que la clé d’hôte n’est pas approuvée, parce que l’URL de dépendance ne correspond pas à la configuration SSH ou parce que la version demandée n’existe plus. Traiter ces causes comme un seul problème conduit souvent à modifier les mauvais réglages.

Reproduisez d’abord l’échec sans changer le dépôt : utilisez le même commit, le même schéma de compilation et la même commande que dans la tâche CI. Comparez ensuite le journal du Mac local et celui du Mac distant, en repérant la première étape qui diverge. La différence entre « authentification refusée » et « version non résolue » est déterminante : une clé correctement chargée ne corrige pas un verrou de dépendance obsolète, et un fichier de verrouillage correct ne donne pas accès à un dépôt privé.

Pour Xcode 27, vérifiez également que la version précise utilisée et le système installé figurent dans les informations officielles d’Apple. La disponibilité, l’état de publication et les exigences système doivent être confirmés à partir des notes de version officielles de Xcode 27 et de la page des exigences système de Xcode. Ne déduisez pas la compatibilité d’un nœud à partir d’un autre : deux machines portant le même nom de produit peuvent différer par leur système, leur installation de Xcode ou leur configuration de compte.

Une session SSH ouverte par un administrateur et un processus lancé par un agent CI ne partagent pas nécessairement le même environnement. Le processus peut avoir un autre utilisateur, un autre répertoire personnel et une autre configuration. Apple indique que les identifiants nécessaires aux dépendances privées doivent être disponibles pour le compte macOS qui exécute la tâche CI ; les clés SSH et known_hosts doivent donc être configurés dans cet environnement, et non simplement dans une session d’administration.

Avant de toucher aux clés, consignez l’identité et l’environnement du processus. Dans une étape temporaire de diagnostic, utilisez notamment :

whoami
echo "$HOME"
env | grep -E '^(HOME|SSH_AUTH_SOCK)='

Ces commandes ne doivent pas servir à imprimer des secrets. Elles permettent de confirmer si le processus dispose du répertoire personnel attendu et, lorsqu’un agent SSH est utilisé, si la variable qui désigne son socket existe. Apple décrit les limites de l’utilisation d’un agent SSH dans sa note technique sur SSH agent. Pour le comportement des options SSH et des fichiers de configuration, consultez aussi le manuel de configuration du client OpenSSH.

Vérifiez ensuite l’accès au dépôt avec le même compte, en lecture seule, avant de relancer une compilation complète. Si la commande Git échoue déjà dans ce contexte, la résolution Swift n’est pas le premier problème à corriger.

• [ ] Le compte qui lance le travail CI est identifié.
• [ ] Son répertoire personnel correspond à celui attendu.
• [ ] La clé ou l’agent SSH est accessible à ce compte, sans apparaître dans les journaux.
• [ ] L’accès au dépôt est limité aux projets nécessaires.
• [ ] Un test Git en lecture seule confirme l’accès avant l’appel à Xcode.

Un accès administratif général n’est pas un substitut à des identifiants adaptés à l’exécution. Quand un hébergeur de dépôts propose des clés de déploiement, choisissez une portée en lecture seule si le travail n’a pas besoin d’écrire dans le dépôt ; les recommandations sur les clés de déploiement en lecture seule décrivent ce principe de moindre privilège.

Un échec d’authentification et un échec de vérification de l’hôte peuvent se produire avant la même opération de récupération, mais ils n’ont pas la même cause. Le premier indique que le dépôt n’accepte pas les identifiants présentés, ou que ceux-ci ne sont pas disponibles. Le second signifie que le client SSH ne peut pas confirmer l’identité de la machine distante selon sa configuration locale.

Examinez le fichier known_hosts du compte CI, pas celui d’un compte ouvert manuellement. Vérifiez aussi que l’URL de la dépendance utilise bien le type d’adresse prévu par la configuration SSH : une adresse SSH et une adresse HTTPS peuvent solliciter des identifiants différents. Ne copiez pas une empreinte trouvée dans un message d’erreur sans la vérifier indépendamment. Les empreintes de clés SSH publiées par le fournisseur du dépôt permettent de contrôler la valeur de référence ; la documentation sur l’erreur de vérification de clé d’hôte aide à interpréter ce type de refus.

Désactiver StrictHostKeyChecking peut masquer le symptôme, mais transforme l’acceptation de l’hôte en choix moins sûr. Si une exception temporaire est indispensable pour diagnostiquer un environnement isolé, documentez son périmètre, n’y injectez pas de secret de production et prévoyez son retrait avant la reprise des compilations normales.

Ajoutez l’hôte attendu dans le known_hosts du compte qui exécute la tâche, après vérification de son empreinte par une source fiable. Si les connexions passent par une règle SSH particulière ou un hôte intermédiaire, contrôlez aussi la configuration effective et les options de proxy. Évitez de modifier simultanément la clé, l’URL et la politique de vérification : vous ne sauriez plus quelle correction a supprimé l’échec.

Le gestionnaire de paquets Swift utilise les déclarations du projet et les informations de résolution pour sélectionner les versions. Apple recommande de valider le fichier Package.resolved approprié au projet dans le contrôle de versions ; lorsqu’un appel direct à xcodebuild doit respecter les versions verrouillées, la documentation CI d’Apple indique de désactiver la résolution automatique des dépendances. Consultez les consignes Apple pour construire des projets utilisant des Swift Packages en intégration continue avant de figer la commande de votre pipeline.

Vérifiez que le fichier suivi par le dépôt est celui associé au projet ou à l’espace de travail réellement compilé. Dans une organisation comportant plusieurs cibles, espaces de travail ou configurations, un fichier présent à un emplacement ne garantit pas que la commande de CI consomme ce même état. Comparez également l’adresse du package inscrite dans les déclarations avec la forme accessible au compte du nœud. Une URL correcte sur le poste d’un développeur peut être inutilisable par le processus distant si elle suppose une clé personnelle ou une règle SSH locale absente.

Ne mettez pas à jour les dépendances pour « réparer » une erreur d’accès : cela modifie le résultat attendu et peut introduire une différence de versions sans régler l’authentification. À l’inverse, si l’accès SSH fonctionne mais que la version verrouillée n’est plus disponible ou que le fichier de verrouillage ne correspond pas au projet, traitez ce problème comme un écart de résolution, puis validez le changement de dépendance séparément.

Une configuration Git utilisateur peut contenir des réécritures d’URL, des règles SSH ou un proxy que le compte CI ne possède pas. Xcode et xcodebuild peuvent donc résoudre une adresse dans un contexte différent de celui d’un terminal administrateur. Commencez par relever la commande exacte, son environnement, les réglages Git visibles depuis le compte d’exécution et les messages produits pendant la résolution ; ne supposez pas que tous les chemins Git se comportent de manière identique.

Examinez en particulier les réécritures d’URL configurées dans Git et les blocs Host du fichier SSH. Une règle locale peut transformer silencieusement l’adresse d’un dépôt ; une règle limitée à un compte ne sera pas active pour un autre. Si une compilation ne passe que par un proxy, vérifiez que le processus CI reçoit les paramètres nécessaires sans afficher de jeton ni de mot de passe dans ses journaux.

Ne testez une variante faisant appel au Git système que si les journaux ou la configuration montrent une différence pertinente. Conservez alors la commande initiale, les sorties de résolution et les versions sélectionnées avant et après l’essai. Ne changez pas en même temps la configuration Git, la source des identifiants et le réglage de résolution Swift : une modification à la fois rend le diagnostic vérifiable.

Après une correction, reprenez le même commit et le même environnement de travail propre avec le compte réel du service. Conservez les sorties de résolution, les versions de dépendances observées et l’étape précise où la récupération aboutit ou échoue. Un succès obtenu depuis une session de dépannage ne suffit pas à valider la chaîne CI si celle-ci utilise un autre compte.

Pour un appel direct à xcodebuild, le principe de commande suivant est à adapter au projet et aux options de compilation déjà en place :

xcodebuild -resolvePackageDependencies \
  -disableAutomaticPackageResolution \
  -project MonProjet.xcodeproj

Confirmez que cette commande correspond à l’organisation du dépôt et à la version de Xcode installée, puis exécutez également la compilation habituelle. L’option de résolution automatique désactivée vise à respecter les dépendances verrouillées ; elle ne répare ni une clé absente ni une empreinte d’hôte incorrecte. Si vous utilisez un espace de travail ou une autre forme de projet, ajustez les options plutôt que de copier la commande sans contrôle.

• [ ] L’essai a lieu sous le compte CI, avec un espace de travail propre.
• [ ] Le commit et la commande sont identiques à ceux du cas défaillant.
• [ ] Les identifiants disposent seulement des droits de lecture requis.
• [ ] L’empreinte de l’hôte est vérifiée et la politique SSH reste active.
• [ ] Les dépendances obtenues correspondent au verrou attendu.
• [ ] Le journal indique quelle couche a été corrigée.

Choisissez ensuite entre correction du compte et isolement du nœud selon les conditions suivantes :

• Si le compte d’exécution est stable et peut recevoir des identifiants minimaux, corrigez sa configuration SSH et rejouez la compilation avant d’élargir l’intervention.
• Si plusieurs tâches partagent le même compte et qu’il est impossible de limiter proprement leurs accès aux dépôts, séparez les comptes d’exécution ou isolez les tâches sensibles.
• Si les identifiants et known_hosts sont corrects mais que les versions divergent, corrigez le fichier de verrouillage ou le mode de résolution, sans renouveler les clés.
• Si la version du système ou de Xcode n’est pas confirmée compatible, validez d’abord le couple Xcode-macOS à l’aide des pages officielles, puis relancez le test.
• Si l’échec ne se reproduit plus sous le compte CI avec le même commit, consignez les preuves et surveillez la tâche normale avant de supprimer les traces de diagnostic.

Pour choisir entre les environnements de compilation, comparez les critères qui déterminent réellement le risque et la charge d’administration, plutôt que de partir du seul message d’erreur :

Pourquoi un package privé fonctionne-t-il localement, mais pas sur le Mac distant ?
La session locale utilise peut-être une clé SSH, un agent ou une configuration Git propres à son utilisateur. Le processus CI distant peut fonctionner sous un autre compte, sans ces éléments. Identifiez d’abord le compte et comparez l’étape exacte de l’échec ; cela permet de séparer un problème d’accès d’une URL ou d’une version incorrecte.

Comment faire en sorte que xcodebuild utilise la configuration SSH du compte CI ?
Lancez le processus depuis le service ou sous le compte qui exécute réellement les travaux, puis testez l’accès SSH et Git dans ce même contexte. Vérifiez le répertoire personnel, les fichiers de configuration et, le cas échéant, l’agent disponible. Une configuration présente uniquement dans le compte d’un administrateur ne devient pas automatiquement accessible à xcodebuild.

Pourquoi les versions diffèrent-elles malgré un Package.resolved validé ?
Assurez-vous que le fichier suivi est celui du projet compilé et que l’adresse du package est accessible dans le contexte CI. Un refus d’accès n’est pas une nouvelle résolution de version. Si l’objectif est de respecter les dépendances verrouillées avec xcodebuild, vérifiez le réglage de résolution recommandé par Apple avant toute mise à jour du fichier.

Où installer la clé SSH et known_hosts pour un package privé ?
Dans le compte macOS qui exécute la tâche CI, avec des droits restreints aux dépôts requis. Vérifiez l’empreinte de l’hôte à partir d’une source fiable avant de l’ajouter, puis testez l’accès sans afficher de secret. N’utilisez pas la désactivation de la vérification d’hôte comme solution permanente, même si elle permet de faire disparaître le message d’erreur.

Un poste de travail local facilite le dépannage interactif, mais il ne garantit pas la disponibilité continue d’un nœud de compilation et peut mélanger des identifiants personnels aux secrets d’équipe. Un environnement généraliste non macOS ne remplace pas un système macOS lorsque le projet dépend des outils Apple, tandis qu’un nœud partagé mal isolé peut transformer une erreur de clé en problème d’accès trop large. Pour un test ponctuel, conservez le poste déjà disponible si son environnement est reproductible ; pour une tâche CI régulière, privilégiez un compte maîtrisé et un accès minimal.

Si le problème vient de l’absence d’un nœud macOS contrôlable plutôt que d’un défaut du dépôt, examinez la présentation des environnements Mac distants de JEXCLOUD avant de décider de déplacer vos travaux. La location d’un Mac distant peut offrir un environnement de compilation plus adapté qu’un poste partagé pour tester une chaîne CI ou isoler un projet ; elle ne convient pas forcément à une charge durablement intensive ni à un besoin de périphériques physiques. Comparez les exigences de votre pipeline, les règles de gestion des secrets et les conditions de location dans les offres Mac de JEXCLOUD, puis testez d’abord l’accès aux dépendances avec le compte d’exécution prévu.