Dépendances privées SwiftPM : guide de configuration d’un Mac distant en 2026

Le choix gagnant est une configuration où les dépendances privées SwiftPM utilisent une clé de dépôt dédiée, un fichier Package.resolved versionné et le compte macOS qui exécute réellement la construction. Cette méthode convient si l’archivage doit fonctionner sans session Xcode ouverte, après une déconnexion SSH ou après le redémarrage du Mac distant.

Cet article s’adresse aux développeurs indépendants qui migrent un projet avec des paquets Swift privés vers un environnement distant. Il convient aussi aux petites équipes utilisant xcodebuild, une tâche planifiée ou une chaîne de signature et d’archivage sans interface graphique.

Le point de départ : construire sans confondre Xcode et automatisation

Un cas revient souvent. Xcode construit le projet depuis une session graphique, mais la tâche lancée en arrière-plan n’arrive pas à récupérer un paquet privé. Le poste semble correctement configuré. Pourtant, les deux opérations ne s’exécutent pas nécessairement avec le même utilisateur, le même trousseau, les mêmes variables d’environnement ou le même agent SSH.

La première décision est donc organisationnelle avant d’être technique : identifier le compte macOS chargé d’exécuter Xcode, xcodebuild ou le planificateur. Les clés SSH, le fichier known_hosts et la configuration Git doivent être accessibles dans l’environnement de ce compte, pas seulement dans celui du développeur qui s’est connecté en VNC.

Apple indique également que les environnements d’intégration continue doivent recevoir les identifiants nécessaires aux paquets privés et conserver les versions résolues. La documentation officielle sur la construction de paquets Swift en intégration continue décrit cette séparation entre projet, authentification et environnement de build dans les workflows CI Swift.

Les limites les plus coûteuses sont rarement visibles au premier lancement :

• une clé privée installée dans le mauvais compte fonctionne en VNC, mais échoue dans une tâche planifiée ;
• une URL Git en HTTPS peut demander une authentification interactive alors que le job ne possède aucun terminal ;
• un dépôt accessible aujourd’hui peut changer d’autorisation sans que le projet révèle immédiatement la cause ;
• un Package.resolved absent ou ignoré permet à l’environnement distant de sélectionner une version différente de celle testée localement ;
• un hôte SSH non validé bloque la récupération avant même que SwiftPM puisse examiner la version du paquet ;
• une clé de développement donnant accès à plusieurs dépôts augmente le périmètre d’un éventuel incident.

Pour un projet audio, vidéo ou de design qui dépend de bibliothèques privées lourdes, cette distinction est particulièrement importante. Une archive qui échoue après plusieurs phases de compilation ne doit pas être diagnostiquée comme un simple problème réseau. La récupération des paquets doit être validée en premier.

Le périmètre d’accès : dépendances privées et comptes séparés

Avant toute connexion au Mac distant, il faut dresser l’inventaire des dépendances directes et transitives. Le manifeste du projet révèle les paquets déclarés directement ; leurs propres manifestes peuvent introduire d’autres dépôts privés. Chaque URL doit être associée à un dépôt précis et à un propriétaire d’accès identifiable.

La règle de base est la suivante : la clé utilisée par la construction doit lire les dépôts nécessaires, mais ne doit pas hériter des droits de publication, d’administration ou de signature d’une identité personnelle. La plateforme de dépôt doit recevoir la clé publique correspondante selon son mécanisme d’accès. La clé privée reste sur le Mac distant et ne doit apparaître ni dans le projet, ni dans un script versionné, ni dans l’historique du terminal.

Le compte de construction doit aussi être distinct du compte utilisé pour administrer la machine lorsque cela est possible. Cette séparation ne rend pas la chaîne invulnérable, mais elle limite les conséquences d’une erreur de script ou d’une rotation de clé oubliée.

Élément	Configuration recommandée	Risque si l’élément est partagé
Compte macOS de construction	Compte déterminé, utilisé par xcodebuild et les tâches automatiques	La clé se trouve dans le profil d’un autre utilisateur
Clé SSH	Clé dédiée aux dépôts privés, avec accès de lecture minimal	Une compromission ouvre l’accès à tous les projets personnels
known_hosts	Fichier géré par le compte de construction après validation de l’hôte	Le job bloque ou contourne la vérification SSH
Package.resolved	Fichier contrôlé et versionné avec le projet	Les versions peuvent évoluer sans revue
Certificats de signature	Stockage et droits séparés des accès Git	Une clé de dépôt devient indirectement une clé de publication

La documentation de GitHub sur la création d’une clé SSH et son ajout à l’agent rappelle le principe général : générer une identité distincte, la charger dans l’agent lorsque c’est nécessaire et enregistrer la clé publique auprès du service concerné. Les commandes exactes doivent être adaptées au fournisseur de dépôt et au compte macOS réellement employé.

Attention. Une clé privée ne doit jamais être remplacée par un jeton copié dans une commande ou une variable enregistrée en clair. Si une information d’authentification apparaît dans l’historique du shell ou dans un journal de build, la procédure doit s’arrêter et la clé concernée doit être révoquée.

La migration initiale : de la base locale au Mac distant

La migration doit commencer par une référence reproductible. Une construction réussie sur le poste local ne suffit pas, car elle peut dépendre d’un cache, d’un agent SSH déjà chargé ou d’une connexion Xcode persistante.

Conservez d’abord le Package.resolved associé au projet et notez les révisions observées. Apple documente la fonction de ce fichier dans les workflows d’intégration continue : il sert à préserver les versions résolues plutôt qu’à laisser chaque environnement choisir de nouvelles versions. Le fichier doit donc être traité comme une partie contrôlée du projet, non comme un artefact temporaire.

La documentation Apple sur les dépendances d’un paquet Swift doit servir de référence pour vérifier les déclarations de dépendance et leurs contraintes de version. Cette étape permet de distinguer une mauvaise autorisation Git d’un conflit de versions.

La séquence recommandée est la suivante :

• récupérer la branche et le fichier Package.resolved dans un répertoire de travail propre ;
• confirmer que les URL des paquets privés utilisent un mode d’accès compatible avec l’environnement, notamment les URL Git fondées sur SSH lorsque c’est le choix retenu ;
• installer la clé publique dans les dépôts concernés ;
• placer la configuration SSH et known_hosts dans le profil du compte de construction ;
• tester la lecture d’un dépôt privé sans lancer Xcode ;
• supprimer toute dépendance implicite à une session graphique avant de passer à la résolution SwiftPM.

Pour tester la connexion, le fournisseur du dépôt peut proposer une commande SSH dédiée. Les résultats doivent être interprétés avec prudence : un test positif prouve l’authentification auprès de l’hôte, mais ne prouve pas encore que toutes les URL du projet, tous les dépôts transitifs et toutes les branches nécessaires sont accessibles. Les indications officielles sur le test d’une connexion SSH détaillent cette première vérification.

La résolution isolée : avant le compilateur et l’archive

La première résolution SwiftPM doit être exécutée seule. Cette discipline réduit le diagnostic à trois familles : authentification, validation de l’hôte et résolution de versions. Si la compilation est lancée immédiatement, les messages d’erreur mélangent souvent récupération, génération de projets et compilation de cibles.

Dans le répertoire du projet, exécutez la commande de résolution prévue par le workflow, par exemple l’option -resolvePackageDependencies lorsqu’elle est utilisée avec xcodebuild. La documentation Apple sur la construction en ligne de commande explique le rôle des options de construction et la nécessité d’indiquer explicitement le projet ou l’espace de travail approprié.

Le fragment minimal doit rester adapté au projet :

xcodebuild \
  -workspace VotreProjet.xcworkspace \
  -scheme VotreScheme \
  -resolvePackageDependencies

Les noms de fichier et de schéma ci-dessus sont des emplacements à remplacer, pas des valeurs universelles. Il ne faut pas ajouter de paramètres d’authentification dans le projet pour « faire fonctionner » la récupération. L’authentification doit rester dans le compte, l’agent et la configuration SSH qui exécuteront réellement le job.

Observez ensuite quatre éléments :

• le compte macOS qui a lancé la commande ;
• l’URL de chaque dépôt privé contacté ;
• la présence ou l’absence d’une demande interactive ;
• le contenu de Package.resolved après la résolution.

Si la commande demande un mot de passe, refuse l’hôte ou ne trouve pas un dépôt, le processus doit s’arrêter. Il ne faut pas passer à l’archive en espérant que Xcode corrigera l’accès. De même, désactiver la vérification de l’hôte peut masquer un problème de confiance et transformer une panne explicite en défaut de sécurité.

Le choix du diagnostic : session graphique ou compte réel

Le tableau suivant sert à décider quand avancer. Il ne remplace pas les journaux, mais évite de conclure trop vite après un test VNC réussi.

Observation	Interprétation probable	Action avant de continuer
Xcode récupère le paquet, le job échoue	Profils, agents ou trousseaux différents	Rejouer la résolution avec le compte du job
L’hôte SSH est refusé	known_hosts absent, incorrect ou non lisible	Valider l’hôte dans le profil de construction
Le paquet est trouvé, mais la version change	Package.resolved absent, ignoré ou modifié	Restaurer le fichier contrôlé et revoir la mise à jour
Le dépôt n’est pas trouvé malgré une clé valide	URL ou autorisation du dépôt incorrecte	Tester chaque dépôt privé requis
La résolution passe, l’archive échoue	Problème distinct de compilation, signature ou export	Conserver les logs de résolution et diagnostiquer l’archive séparément

Les options de gestion du code source de xcodebuild ne doivent être ajoutées qu’en réponse à un besoin identifié : proxy Git, réécriture d’URL ou configuration SSH avancée. Ajouter des paramètres au hasard rend le workflow plus difficile à relire et peut cacher la vraie différence entre le poste local et le Mac distant.

La première archive : même utilisateur, même répertoire

Après une résolution propre, exécutez une construction réelle avec le même utilisateur, le même répertoire de travail et la même méthode que la tâche future. Une archive lancée depuis Xcode alors que la tâche utilisera xcodebuild ne constitue pas une validation suffisante.

La construction doit permettre de confirmer trois résultats séparés :

• les paquets privés sont résolus depuis les dépôts attendus ;
• les cibles de l’application et des paquets compilent avec la configuration prévue ;
• l’archive est produite dans l’emplacement défini par le workflow.

Les chemins utilisés dans les scripts doivent être explicites et stables. Évitez les répertoires temporaires dépendant d’une session VNC ou d’un répertoire courant implicite. Les journaux doivent conserver la commande, le compte d’exécution, la branche, l’état de Package.resolved et le code d’échec, sans imprimer de secret.

Pour l’archivage et l’export, utilisez la documentation Apple sur la création de code signé pour la distribution. La récupération des paquets privés et la signature ne sont pas le même domaine de confiance. Le fait qu’un compte puisse lire un dépôt ne doit pas lui donner automatiquement accès aux certificats ou aux profils de publication.

Un projet de design ou d’application multimédia peut nécessiter des ressources volumineuses, des extensions ou plusieurs cibles. La résolution doit rester un contrôle distinct, car une archive longue ne doit pas être relancée simplement pour découvrir que la clé SSH n’était pas chargée.

L’exécution sans présence : agent, trousseau et variables

Une tâche planifiée ne bénéficie pas forcément des éléments initialisés lors d’une connexion interactive. C’est la principale différence entre « cela fonctionne dans une fenêtre SSH » et « cela fonctionne chaque nuit ».

Il faut vérifier le comportement de la clé dans trois situations : après fermeture de la connexion SSH, sans session VNC et lors d’une exécution planifiée. Chaque situation doit utiliser le même compte de construction. Si la clé est protégée par une phrase secrète, l’agent doit être géré selon une méthode compatible avec l’exécution attendue. Les recommandations officielles sur les phrases secrètes des clés SSH et l’agent expliquent les compromis entre protection de la clé et disponibilité de l’agent.

Le job doit comporter des arrêts explicites :

• arrêt si la clé attendue n’est pas disponible ;
• arrêt si la vérification de l’hôte échoue ;
• arrêt si un dépôt privé renvoie une erreur d’autorisation ;
• arrêt si Package.resolved est absent ou modifié sans revue ;
• arrêt si la résolution passe mais que l’archive ne respecte pas le schéma attendu.

La documentation de configuration du Mac distant doit également indiquer qui peut administrer la machine et comment récupérer l’accès. Pour une procédure de connexion ou de changement de compte, les ressources d’aide de ProxyMac peuvent compléter la documentation interne du projet. Elles ne remplacent pas la séparation des droits dans le dépôt.

Le redémarrage : test de dépendance cachée

Le redémarrage est un test de reproductibilité, pas une formalité. Avant de le lancer, sauvegardez les journaux de résolution et l’état du dépôt. Après le redémarrage, reconnectez-vous avec le compte prévu, vérifiez que la configuration SSH est bien lisible, puis relancez la résolution depuis un répertoire de travail recréé.

La validation doit couvrir le chemin complet :

• récupération du code ;
• lecture de Package.resolved ;
• accès aux dépôts privés ;
• résolution sans intervention ;
• compilation ;
• archivage ;
• conservation d’un journal exploitable.

Si le processus fonctionne uniquement après l’ouverture de Xcode, l’authentification repose probablement sur un état interactif non documenté. Si la résolution réussit uniquement grâce à un cache, la construction n’est pas encore démontrée sur une base propre. Le cache peut accélérer un workflow, mais il ne doit pas être la seule preuve que les identifiants et les versions sont corrects.

Lorsqu’un paquet privé doit évoluer, modifiez la dépendance volontairement, mettez à jour Package.resolved, examinez les changements, puis lancez une construction de contrôle. Une mise à jour automatique pendant l’archivage introduit une variable difficile à rattacher à un commit applicatif.

Enfin, prévoyez une revue après chaque changement de compte de construction, de clé SSH, de dépôt, de version Xcode ou de méthode de planification. Les clés inutilisées doivent être retirées du dépôt. Les accès de signature doivent être réexaminés séparément. La page de confidentialité de ProxyMac peut servir de point de référence pour les questions de traitement des données liées à l’environnement hébergé, tandis que les règles d’accès au code doivent rester définies par l’équipe.

Le choix d’hébergement pour une construction reproductible

Un Mac local garde l’avantage lorsqu’un développeur doit manipuler directement un appareil, tester un périphérique audio ou travailler plusieurs heures avec le simulateur. En revanche, il impose l’achat, la maintenance, la sauvegarde et la disponibilité permanente de la machine.

Un service CI géré peut réduire l’administration, mais ses contraintes d’accès aux paquets privés, à la signature, aux scripts et aux environnements personnalisés doivent être vérifiées avant migration. Un Mac distant conserve un macOS réel, un compte de construction contrôlable et une possibilité de diagnostic plus proche du poste local. Il faut toutefois accepter la responsabilité de la configuration SSH, du trousseau, des mises à jour et de la surveillance du job.

Pour un indépendant, la décision peut suivre cette règle :

• choisissez le Mac local si les tests matériels et l’usage interactif dominent ;
• choisissez un service CI si le projet s’adapte à ses contraintes et que la personnalisation du système reste limitée ;
• choisissez un Mac distant si le projet doit conserver un environnement macOS accessible, exécuter xcodebuild à la demande et disposer d’une machine persistante sans achat immédiat.

Les dépendances privées SwiftPM ne deviennent pas fiables par le seul fait d’être déplacées sur un autre ordinateur. La fiabilité vient de l’association entre un compte connu, une clé dédiée, un hôte validé, un Package.resolved contrôlé et une procédure de résolution testée hors interface graphique.

Si le projet doit d’abord être éprouvé dans un environnement court, louer un Mac auprès de ProxyMac permet de réaliser une résolution à froid, une archive et un redémarrage avant de décider d’un hébergement durable. Cette approche est moins pertinente pour une charge lourde et stable qui justifie l’achat d’un matériel dédié, ou pour un workflow nécessitant des interfaces physiques en permanence. Dans les autres cas, elle évite de financer une machine locale avant d’avoir vérifié que le dépôt privé, la signature et l’automatisation fonctionnent ensemble.