Que faire si Xcode Cloud ne parvient pas à récupérer des dépendances privées ? Guide de dépannage 2026

Symptôme : Xcode Cloud échoue en récupérant une dépendance privée, mais le message ne suffit pas à établir la cause.
Réponse rapide : repérez d’abord si l’échec survient au clonage, à la résolution des dépendances ou pendant un script ; corrigez ensuite l’accès ou la configuration correspondant à cette étape. Une dépendance privée ne vous oblige pas, à elle seule, à quitter Xcode Cloud.

Ce guide s’adresse aux ingénieurs qui entretiennent des flux Xcode Cloud et doivent localiser un problème d’accès à un dépôt.
Il est également destiné aux responsables de packages Swift, de sous-modules Git et de dépendances réparties entre plusieurs dépôts.
Les responsables IT qui évaluent l’environnement d’exécution y trouveront des critères concrets pour décider si un Mac autogéré mérite d’être étudié.

Le rapport de compilation comme point de départ

Ne commencez pas par modifier les réglages d’authentification au hasard. Un message mentionnant un dépôt privé peut correspondre à un dépôt principal non connecté, à un package inaccessible, à un sous-module oublié ou à un script qui tente de télécharger un outil. Ce sont des problèmes différents, même si leur effet visible — une compilation interrompue — se ressemble.

Ouvrez le rapport de la compilation qui a échoué et relevez la première étape en erreur, le dépôt ou le fichier concerné, ainsi que le message immédiatement précédent. Une erreur de clonage oriente vers l’accès au code source ; un message de résolution Swift vers le package et son état verrouillé ; une sortie de script non nulle vers l’étape personnalisée. Le premier message d’échec est un indice à vérifier, pas une preuve suffisante de la cause.

Apple décrit plusieurs dépendances externes susceptibles d’intervenir dans un flux, notamment des dépôts privés et des outils nécessaires au projet. Si le flux ne peut pas les atteindre ou les préparer, la compilation peut échouer. La documentation Apple sur la préparation des dépendances et leur accès dans Xcode Cloud permet de distinguer les cas documentés des hypothèses à vérifier dans votre projet.

Avant de relancer, notez le commit compilé, la cible concernée et l’étape en erreur. Cette trace vous évitera de comparer un essai à un état différent du dépôt ou de conclure trop vite qu’un changement d’autorisation a résolu le problème.

Les dépôts privés et leurs autorisations

Pour un Swift Package privé, identifiez d’abord le dépôt qui héberge le package ; ne vous limitez pas au dépôt de l’application. Dans la configuration du projet, relevez l’URL de la dépendance et le commit concerné, puis vérifiez que la connexion utilisée par Xcode Cloud correspond bien au service et au dépôt effectivement sollicités. Apple documente la connexion aux services de gestion de code dans ses instructions de configuration de la gestion des sources.

Si le rapport de compilation présente une demande d’autorisation pour un dépôt nouvellement utilisé, suivez cette invite et confirmez que le dépôt affiché correspond à celui qui a échoué. Relancez ensuite le flux sur le même commit. Une compilation réussie après cette étape renforce l’hypothèse d’un accès manquant ; elle ne démontre pas que les autres dépendances privées du projet sont autorisées.

Le même raisonnement s’applique aux sous-modules Git. Vérifiez l’URL inscrite dans la configuration du sous-module, puis déterminez si elle pointe vers la même instance de forge que le code principal. Si le sous-module est hébergé ailleurs, l’accès au dépôt principal ne suffit pas à prouver que le sous-module est récupérable. La documentation Apple sur les connexions aux dépôts est le bon repère pour vérifier les services et accès réellement configurés.

Plusieurs instances de forge

Une entreprise peut utiliser plusieurs instances d’un même service, par exemple une instance interne en plus d’une instance hébergée, ou répartir ses dépôts entre plusieurs services. Ne confondez pas ces cas : l’existence d’une connexion à un service ne confirme pas automatiquement que chaque instance et chaque dépôt requis sont accessibles.

Dressez une petite carte des dépendances du flux : dépôt de l’application, packages Swift, sous-modules et dépôts consultés par les scripts. Pour chacun, consignez l’URL, l’instance et l’étape où l’accès est nécessaire. Si une compilation ultérieure signale une instance non connectée, utilisez l’invite présentée par Xcode Cloud pour poursuivre l’autorisation, puis vérifiez avec une nouvelle compilation. Cette procédure concerne l’accès aux dépôts du flux ; elle ne remplace pas un audit général des comptes ou des droits de toute l’organisation.

L’état de résolution et le fichier Package.resolved

Quand la récupération semble réussir, mais que le résultat diffère de l’environnement local, examinez Package.resolved. Vérifiez d’abord si le fichier attendu existe à l’emplacement pertinent pour le projet ou l’espace de travail, puis s’il a été ajouté au dépôt et s’il est présent dans le commit compilé par Xcode Cloud. Un fichier visible sur le poste d’un développeur mais absent du commit utilisé par le flux ne peut pas servir de référence à ce flux.

Comparez les révisions verrouillées dans le fichier avec l’état de dépendances attendu par l’équipe. Si la compilation échoue après une mise à jour de package, vérifiez également si le changement de résolution a été validé avec le code concerné. Les recommandations Apple pour les workflows d’intégration continue utilisant des packages Swift précisent le rôle du fichier de résolution dans la reproductibilité de la compilation.

Évitez de forcer une résolution automatique comme remède par défaut. Cela peut masquer une divergence entre l’état de dépendances voulu et celui effectivement compilé, ou introduire des révisions différentes de celles testées par l’équipe. Commencez par établir si le fichier manque, s’il est au mauvais emplacement ou si le commit n’inclut pas le changement attendu. Ne le régénérez qu’après avoir déterminé quel état doit être partagé.

Les outils tiers et les scripts personnalisés

Les projets peuvent utiliser CocoaPods, Carthage ou des outils internes pour préparer leurs dépendances. Le fait qu’un outil fonctionne sur le poste d’un développeur ne garantit pas qu’il soit présent, configuré ou accessible dans l’environnement de compilation. Contrôlez la méthode d’installation, les fichiers de verrouillage suivis par Git et les commandes réellement exécutées par le flux. Si un script télécharge un outil, vérifiez aussi que son URL et son accès réseau sont disponibles depuis l’environnement concerné.

Les scripts personnalisés peuvent préparer des dépendances ou effectuer des opérations avant ou après l’appel à xcodebuild. Apple documente trois points d’exécution nommés ci_post_clone.sh, ci_pre_xcodebuild.sh et ci_post_xcodebuild.sh, ainsi que leur emplacement attendu dans le dossier ci_scripts. Vérifiez que le nom et le chemin respectent ces conventions, que le script est bien suivi par Git et qu’il se termine avec un code de sortie cohérent. La référence Apple sur les scripts de compilation personnalisés décrit ces conventions et les moments où les scripts sont exécutés.

Évitez de supposer qu’un script dispose de privilèges d’administrateur ou qu’il retrouve un état présent sur le Mac d’un développeur. Si l’installation d’un outil exige une action spécifique, confirmez que le flux peut l’effectuer dans son environnement prévu, puis rendez cette préparation explicite. Un script réussi localement mais absent du commit, ou dépendant d’un fichier non versionné, ne constitue pas une procédure reproductible.

Variables, réseau et secrets

Pour chaque script, listez les variables requises, les fichiers attendus, les accès réseau nécessaires et le traitement des informations sensibles. Vérifiez si la variable est définie dans le contexte approprié et si son nom correspond à celui utilisé par le script. La référence Apple des variables d’environnement et la documentation du contexte des workflows Xcode Cloud permettent de vérifier les variables exposées et leur contexte.

Si une variable liée à un proxy ou à un réseau privé manque, ne concluez pas immédiatement à une panne générale d’accès réseau : cherchez d’abord quel hôte le script essaie de joindre, à quel moment, et quel message apparaît dans les journaux. Examinez également les sorties de commandes avant de partager un rapport. Un script peut afficher accidentellement une valeur sensible ; masquez les secrets dans vos diagnostics et évitez de les écrire dans les journaux.

Parcours de vérification avant toute migration

Suivez cette séquence, en conservant le même commit lorsque vous comparez les résultats. Elle permet d’isoler le problème sans déplacer toute la chaîne CI dès le premier échec.

• [ ] Identifiez dans le rapport la première étape en erreur : clonage, dépendances, script ou compilation Xcode.
• [ ] Relevez le dépôt, le package, le sous-module ou l’outil directement associé au message.
• [ ] Vérifiez l’URL réelle, la forge et l’instance pour chaque dépôt requis, pas seulement pour le dépôt principal.
• [ ] Confirmez que la demande d’autorisation éventuelle concerne le dépôt signalé, puis relancez le flux après l’avoir traitée.
• [ ] Contrôlez que Package.resolved est au bon emplacement, versionné et présent dans le commit testé.
• [ ] Vérifiez les fichiers de verrouillage et la préparation des outils utilisés par le projet.
• [ ] Pour chaque script, examinez le nom, le chemin, les fichiers requis, les variables utilisées et le code de sortie.
• [ ] Comparez le résultat d’une nouvelle compilation au même commit avant de modifier d’autres paramètres.

Après ces vérifications, vous devriez pouvoir formuler une hypothèse testable : « l’instance du dépôt n’est pas autorisée », « le commit ne contient pas l’état de résolution attendu » ou « le script ne peut pas atteindre son outil ». Si le rapport reste ambigu, créez un essai minimal qui conserve la dépendance ou le script suspect, et ne change qu’un élément à la fois. Cette méthode aide à séparer une panne d’accès d’un problème de configuration sans attribuer une cause certaine à un message générique.

Critères d’évaluation d’un Mac autogéré

Ne migrez pas parce qu’un package est privé : Xcode Cloud peut fonctionner avec des dépendances privées lorsque les accès et la préparation nécessaires sont configurés. Évaluez un autre environnement seulement si un besoin identifié — par exemple l’accès à un réseau d’entreprise, à un outil qui ne peut pas être préparé dans le flux, ou à un état d’exécution contrôlé par votre équipe — reste insatisfait après vérification des possibilités documentées.

Avant cette décision, établissez le besoin exact : quel dépôt ou service doit être atteint, quel outil doit être exécuté, quel mécanisme d’accès est requis et quelle contrainte empêche le flux actuel de le faire. Si le motif se résume à un dépôt nouvellement ajouté ou à un fichier de résolution absent, corrigez d’abord cette configuration. Pour organiser cette étude, vous pouvez consulter notre page sur le choix entre différentes approches Mac et les questions fréquentes sur l’accès aux environnements Mac.

Une comparaison sérieuse doit aussi prendre en compte les contraintes que Xcode Cloud ne vous impose pas de gérer directement : administration de l’hôte, mises à jour des outils, secrets, accès réseau et disponibilité de l’environnement. Un Mac dédié ou loué ne résout pas par lui-même une URL erronée, un secret absent ou un Package.resolved non validé ; il faut encore configurer et maintenir ces éléments. En revanche, si votre besoin porte précisément sur un réseau ou une chaîne d’outils que vous devez contrôler, un Mac distant peut devenir une option à tester sur un cas représentatif.

Questions fréquentes

Où vérifier l’accès à un Swift Package privé ?

Commencez par le rapport de compilation, puis vérifiez la connexion à la forge qui héberge le package. L’autorisation du dépôt de l’application ne prouve pas celle du dépôt de dépendance. Si une invite d’accès apparaît, confirmez qu’elle correspond au bon dépôt et relancez le flux après autorisation. La documentation Apple sur les dépendances disponibles pour Xcode Cloud décrit le modèle à contrôler.

Comment autoriser un sous-module Git privé ?

Relevez l’URL du sous-module dans la configuration Git, puis identifiez l’instance de forge qui héberge réellement le dépôt. Vérifiez séparément sa connexion et son accès dans Xcode Cloud, surtout si le sous-module n’est pas sur la même instance que le dépôt principal. Une nouvelle compilation permet ensuite de vérifier si l’étape de clonage passe ; ne déduisez pas que tous les sous-modules sont accessibles à partir du seul succès du dépôt principal.

Que vérifier lorsque plusieurs instances de forge sont utilisées ?

Séparez les dépôts par service et par instance, puis vérifiez chaque accès requis par le flux. Une connexion déjà établie peut ne pas couvrir une autre instance. Si un rapport ultérieur indique qu’un dépôt reste inaccessible, suivez l’invite d’autorisation associée à cette compilation. Testez ensuite avec le même commit : vous pourrez ainsi vérifier que l’accès nouvellement configuré correspond bien à la dépendance signalée.

Quel est l’effet d’un Package.resolved absent ou non validé ?

L’équipe peut perdre l’état de résolution qu’elle souhaitait partager entre le développement local et le flux CI. Vérifiez le chemin attendu pour votre projet, l’historique Git et le commit réellement compilé. Une absence dans le commit ne se corrige pas nécessairement en forçant une nouvelle résolution : commencez par établir quelle version des dépendances doit être reproductible, puis suivez les recommandations Apple pour votre type de workflow.

Si votre diagnostic révèle qu’un accès réseau d’entreprise ou un outil doit fonctionner dans un environnement contrôlé par votre équipe, plutôt que dans les limites de votre workflow actuel, évaluez ce besoin sur un dépôt et une compilation représentatifs avant de changer de CI. Une location de Mac auprès de zshmac peut alors vous permettre de tester un environnement macOS distant ; elle ne garantit pas, à elle seule, l’accès à votre réseau privé ni la compatibilité avec vos scripts, que vous devrez valider. Consultez les environnements Mac proposés par zshmac pour déterminer si cette piste mérite un essai.

Questions fréquentes