Votre pipeline passe au vert, mais le projet Xcode échoue dès qu’il faut accéder à une signature, à une dépendance privée ou à un service interne.

La solution la plus rapide consiste à déployer CircleCI Machine Runner 3 sur un Mac distant uniquement lorsque vous devez contrôler l’environnement Xcode, le réseau ou les identifiants de signature. Pour les tâches standardisées qui n’exigent pas ce contrôle, conservez l’exécuteur géré. Un nœud en ligne ne doit entrer en production qu’après validation du routage, de la compilation Xcode, de la reprise après redémarrage et du nettoyage de l’espace de travail.

Cet article s’adresse à trois profils :

  • vous maintenez des pipelines CircleCI iOS ou macOS et devez figer votre chaîne d’outils ;
  • vous êtes ingénieur DevOps et devez relier la CI à des dépôts privés, des signatures ou un réseau interne ;
  • vous administrez les droits, les mises à jour et la récupération d’un nœud Mac distant.

Dernière mise à jour : 29 août 2026. Les informations relatives à l’installation et au fonctionnement sont vérifiées à partir de la documentation officielle de CircleCI sur les exécuteurs Runner, de la configuration de Machine Runner 3 et de la documentation Apple consacrée aux outils de ligne de commande Xcode.

01

Le bon choix commence avant l’installation

Un CircleCI self-hosted runner n’est pas automatiquement préférable à un exécuteur macOS géré. Il vous donne surtout la maîtrise du poste qui exécute la tâche. Cette maîtrise a une contrepartie : vous devez maintenir le compte système, les versions d’outils, les journaux, les certificats, les mises à jour et le nettoyage.

Le déploiement de CircleCI Machine Runner 3 sur un Mac distant est pertinent lorsque votre tâche doit :

  • utiliser une version précise de Xcode ou des outils Apple déjà installés ;
  • accéder à des dépendances privées, à un registre interne ou à un service non exposé publiquement ;
  • manipuler une chaîne de signature que vous voulez isoler d’autres projets ;
  • conserver un environnement macOS ARM cohérent pour des tests liés à Apple Silicon ;
  • lancer des outils audio, vidéo ou de design qui ne sont pas disponibles dans un environnement Linux classique.

La documentation de CircleCI décrit Runner comme un modèle dans lequel les tâches sont exécutées sur votre propre infrastructure. Le job utilise donc les logiciels et les réglages présents sur le nœud, au lieu de repartir d’un environnement entièrement contrôlé par l’exécuteur géré. Vérifiez ce fonctionnement dans la présentation du modèle Runner avant d’ouvrir un accès au réseau interne.

Les trois options à départager

Exécuteur géré

  • moins de maintenance du système hôte ;
  • environnement plus facile à remplacer ;
  • contrôle limité sur les certificats, les dépendances locales et le réseau privé ;
  • risque de devoir réinstaller des outils ou réadapter le pipeline lorsqu’une version précise est nécessaire.

Mac distant autogéré

  • contrôle direct de Xcode, des caches, du trousseau et des outils auxiliaires ;
  • accès possible à un réseau privé selon votre architecture ;
  • responsabilité complète sur les droits, les mises à jour et les incidents ;
  • nécessité de prouver que le nœud revient dans un état propre après chaque tâche.

Double voie

Conservez les tâches génériques sur l’exécuteur géré et routez uniquement les compilations Apple vers le Mac distant. C’est généralement le meilleur compromis pour une équipe qui veut introduire un nœud macOS de manière progressive, sans transformer chaque job en opération d’administration.

Outil de décision

  • Si le job exige Xcode, une dépendance privée ou une signature contrôlée, choisissez un resource class dédié sur le Mac distant.
  • Si le job ne dépend que d’outils reproductibles et d’un réseau public, revenez à l’exécuteur géré.
  • Si seuls les jobs de publication utilisent des certificats, séparez le build de la signature au lieu d’exposer les secrets à toutes les tâches.
  • Si le projet doit rester disponible après une coupure ou un redémarrage planifié, n’autorisez la production qu’après un test de reprise complet.
  • Si vous ne pouvez pas supprimer ou renouveler les identifiants sans accès administrateur documenté, arrêtez le déploiement et corrigez d’abord le modèle de permissions.
02

Première étape : préparer un nœud qui ne mélange pas les responsabilités

Avant de télécharger Runner, préparez le Mac comme un nœud de construction, pas comme un poste de travail partagé. Le compte qui exécute les tâches ne doit pas être votre compte personnel ni un compte disposant de privilèges administratifs sans nécessité.

Créez un compte d’exécution dédié, par exemple <runner-user>. Le nom est volontairement fictif : remplacez-le par votre convention interne sans copier un nom de compte réel dans un dépôt public. Vérifiez ensuite les points suivants :

  • le compte peut lire le projet et écrire dans son espace de travail ;
  • il peut accéder aux outils nécessaires, mais pas aux répertoires personnels d’autres utilisateurs ;
  • les journaux ne contiennent pas de jetons, de mots de passe ou de contenu de trousseau ;
  • les caches sont séparés des fichiers de signature ;
  • les répertoires temporaires peuvent être supprimés après un échec.

Cette séparation limite trois coûts souvent sous-estimés. Un compte trop large augmente l’impact d’un script compromis. Un répertoire de travail réutilisé peut injecter un artefact d’un job dans le suivant. Enfin, un cache mal conçu peut conserver un paquet privé ou un fichier de configuration au-delà de sa durée utile.

Définissez également un nom de nœud explicite, par exemple <mac-node-name>, et un chemin de travail tel que <runner-work-directory>. Ne supposez pas que le chemin utilisé par votre session graphique sera disponible dans un job non interactif. Le PATH, le trousseau et les variables d’environnement doivent être testés depuis le même compte que celui qui exécutera Runner.

03

Deuxième étape : créer le namespace et le resource class

Le routage CircleCI ne se résume pas à enregistrer un ordinateur. Vous devez créer un namespace, définir un resource class et associer le nœud à cette classe. La référence officielle des resource classes explique cette relation et les paramètres attendus.

Utilisez des valeurs fictives pendant la préparation :

  • namespace : <namespace-name> ;
  • resource class : <namespace-name>/<mac-resource-class> ;
  • jeton : <resource-class-token> ;
  • nœud : <mac-node-name>.

Le resource class doit exprimer une capacité ou une fonction, pas l’identité d’une personne. Une classe comme <namespace-name>/ios-signing indique une contrainte opérationnelle. Elle vaut mieux qu’un nom ambigu associé à un développeur ou à un emplacement temporaire.

Le jeton de resource class ne doit jamais être écrit dans .circleci/config.yml, un script versionné ou une commande visible dans les journaux. Stockez-le dans le mécanisme de secrets prévu par votre organisation. Documentez qui peut le faire tourner, où il peut être révoqué et quelle procédure permet de réenregistrer le nœud.

Dans le fichier de configuration CircleCI, le job doit demander explicitement la classe prévue. Le principe ressemble à ceci, avec des valeurs de remplacement :

jobs:
  build-ios:
    machine: true
    resource_class: <namespace-name>/<mac-resource-class>
    steps:
      - checkout
      - run: xcodebuild -version

Ne copiez pas cet extrait comme une preuve de déploiement terminé. La syntaxe finale, les paramètres d’exécution et l’installation doivent être comparés à la documentation de configuration de Machine Runner 3 le jour de l’installation.

04

Troisième étape : installer Machine Runner 3 sur le Mac

CircleCI confirme l’installation de Machine Runner 3 sur macOS selon son guide dédié. La procédure couvre également les conditions propres au système Apple et doit rester votre source pour la commande d’installation, le chemin de configuration et le mode de lancement. Consultez directement le guide officiel d’installation sur macOS plutôt que de reprendre une commande trouvée dans un ancien article.

La séquence de travail peut être suivie ainsi :

  • ouvrez une session d’administration uniquement pour préparer le système ;
  • installez le composant avec la méthode indiquée par CircleCI ;
  • choisissez le compte <runner-user> pour l’exécution ;
  • renseignez le nom <mac-node-name>, le répertoire <runner-work-directory> et le champ d’authentification demandé ;
  • contrôlez les attributs de sécurité du programme téléchargé ;
  • démarrez Runner avec le mécanisme recommandé par la documentation ;
  • vérifiez le processus local, l’inventaire Runner et les journaux.

macOS peut bloquer un binaire téléchargé en raison de sa signature, de sa notarisation ou de l’attribut de quarantaine. Ne désactivez pas globalement les protections du système pour contourner ce problème. Identifiez le fichier concerné, confirmez son origine dans la documentation officielle et appliquez uniquement la procédure supportée.

L’état « en ligne » dans la console CircleCI est un signal utile, mais insuffisant. Un nœud peut être visible et ne pas pouvoir exécuter le job demandé. L’environnement peut avoir un PATH incomplet, un répertoire non accessible ou un service lancé sous le mauvais utilisateur. La documentation de diagnostic des Runner autogérés fournit les contrôles à effectuer lorsque le processus ne reçoit pas de tâche.

05

Les questions Apple Silicon, Xcode et resource class à vérifier

Machine Runner 3 fonctionne-t-il sur un Mac Apple Silicon ?

La documentation CircleCI confirme la prise en charge de l’installation macOS selon son périmètre publié. Pour un Mac Apple Silicon, ne déduisez pas la compatibilité du seul fait que macOS démarre correctement. Vérifiez la méthode d’installation actuelle, l’architecture des outils utilisés et les dépendances qui pourraient encore nécessiter une couche de compatibilité.

Le test utile consiste à exécuter, sous <runner-user>, les commandes d’identification prévues par votre équipe, puis à lancer un projet jetable. Contrôlez notamment l’architecture des outils de compilation, les plugins et les gestionnaires de dépendances. Une tâche qui fonctionne dans votre session graphique peut échouer lorsque le job est lancé sans interface utilisateur.

Comment le resource class dirige-t-il un job vers le Mac distant ?

Le job doit demander la valeur complète <namespace-name>/<mac-resource-class>. Le nœud enregistré doit appartenir à cette classe. Si la demande ne correspond pas exactement, CircleCI peut laisser la tâche en attente ou la diriger vers un autre environnement selon votre configuration.

Créez un job de test dont la seule fonction est d’afficher l’identité du nœud, la version de macOS et la version de Xcode. Utilisez un projet jetable, sans certificat de publication. Le résultat attendu est une preuve lisible dans le journal : le job a été pris par le Mac prévu, avec le compte attendu et le chemin de travail attendu.

06

Quatrième étape : valider Xcode dans une tâche non interactive

Un Xcode CI fiable commence par un test minimal. Ne lancez pas directement une archive de production. Vous devez d’abord démontrer que le nœud sait préparer, compiler et tester un projet qui ne contient aucun secret de publication.

Sous le compte d’exécution, vérifiez les éléments suivants :

  • le répertoire de développement sélectionné correspond à l’outil attendu ;
  • les Command Line Tools sont installés ;
  • xcodebuild est accessible sans ouverture de session graphique ;
  • les certificats de développement non sensibles, si nécessaires au test, sont correctement visibles ;
  • les dépendances Swift Package Manager, CocoaPods ou autres sont accessibles ;
  • le résultat et le code de sortie sont conservés dans les artefacts.

Apple documente l’installation des Command Line Tools pour Xcode ainsi que la sélection de l’outil actif dans les réglages des outils en ligne de commande. Appuyez-vous sur ces pages pour vérifier l’état du poste, sans inventer un chemin local dans votre pipeline.

Un test pertinent contient au minimum :

  • une récupération du code ;
  • une résolution des dépendances ;
  • une compilation ;
  • une exécution de tests ;
  • une conservation du journal et du paquet de résultat ;
  • une suppression contrôlée du workspace.

Pour les projets audio, vidéo ou de design, ajoutez un contrôle spécifique. Un projet peut compiler mais échouer lorsqu’un plugin, une ressource média ou un outil de conversion est absent du compte d’exécution. Testez ces éléments dans une tâche isolée avant de les mélanger avec la signature.

07

Cinquième étape : séparer compilation, signature et publication

La signature est le point où un simple nœud de construction devient une surface de risque. Ne donnez pas à chaque job l’accès au trousseau, aux profils de provisioning ou aux clés privées.

Séparez au moins les responsabilités suivantes :

Job de compilation

  • code source ;
  • dépendances ;
  • outils Xcode ;
  • tests ;
  • aucun secret de publication.

Job de signature

  • resource class plus restrictif ;
  • compte ou répertoire dédié ;
  • accès limité aux certificats nécessaires ;
  • journaux inspectés pour éviter l’exposition d’identifiants.

Job de publication

  • approbation de votre organisation ;
  • accès au service de distribution ;
  • artefacts provenant du job précédent ;
  • procédure de révocation documentée.

Cette séparation ne remplace pas le modèle de sécurité de CircleCI. Elle l’applique à votre architecture locale. Consultez les recommandations de sécurité et confirmez le comportement des secrets avant de choisir entre un trousseau temporaire, un trousseau dédié ou une autre méthode approuvée par votre équipe.

Préparez une récupération avant d’importer un certificat. Vous devez savoir qui peut révoquer le jeton, supprimer le trousseau, reconstruire le compte et réenregistrer le nœud. Une réinstallation destructive sans copie de la configuration ni accès administrateur disponible peut prolonger l’interruption au lieu de résoudre l’incident.

08

Sixième étape : tester le redémarrage et la continuité

Le dernier contrôle se déroule après un redémarrage planifié du Mac. Il permet de distinguer un poste simplement joignable d’un véritable macOS build node.

Avant le redémarrage, enregistrez :

  • l’état du processus Runner ;
  • le chemin de configuration ;
  • la présence du nœud dans l’inventaire ;
  • le resource class associé ;
  • l’état du dernier job ;
  • la méthode d’accès d’administration, par SSH, VNC ou console distante.

Après le redémarrage, vérifiez dans cet ordre :

  • le compte d’exécution et le service Runner démarrent correctement ;
  • le nœud réapparaît dans l’inventaire ;
  • un job sans signature est accepté ;
  • Xcode est accessible sans intervention graphique ;
  • le workspace est nettoyé après le job ;
  • un second job ne récupère aucun fichier du premier ;
  • les journaux restent disponibles sans divulguer de secret.

La page de résolution des problèmes de connexion des Runner autogérés est utile si le processus local fonctionne mais que le nœud ne reçoit aucune tâche. Vérifiez séparément le réseau sortant, le jeton, l’association au resource class et les permissions du compte. Ne concluez pas à une panne Xcode avant d’avoir éliminé ces causes.

Ajoutez ensuite un test de concurrence adapté à votre nœud. Si plusieurs jobs partagent le même répertoire, le même cache ou le même trousseau, vous devez prouver que les fichiers temporaires et les artefacts sont isolés. Si ce n’est pas démontré, limitez le parallélisme et documentez cette contrainte au lieu de la masquer.

09

Les limites à accepter avant la mise en production

Un Mac distant apporte une expérience macOS complète, mais il ne supprime pas les contraintes d’exploitation.

  • Une connexion SSH fonctionnelle ne garantit pas que le job possède le même PATH que votre terminal interactif.
  • Un nœud disponible ne garantit pas que la version active de Xcode correspond au projet.
  • Un cache persistant peut accélérer une compilation, mais il peut aussi conserver des dépendances obsolètes ou des données privées.
  • Une signature réussie sur un projet de test ne prouve pas que le compte de publication est correctement isolé.
  • Une installation manuelle peut fonctionner aujourd’hui et échouer après une mise à jour si la procédure de démarrage n’est pas documentée.

Pour cette raison, consignez les versions, le compte, les chemins, les resource classes, les propriétaires de secrets et la procédure de retour arrière. Refaites l’acceptation après toute modification de l’installation Runner, du système macOS, de Xcode, du trousseau ou de la configuration réseau.

Si vous devez d’abord vérifier le format du nœud et son coût sur la durée du projet, comparez les tarifs de location de Mac mini. Pour une équipe qui veut tester une chaîne complète avant de déplacer un pipeline critique, une commande de Mac mini pour un environnement distant permet de planifier cette étape séparément de la production.

10

Quand le Mac distant devient le choix le plus raisonnable

L’exécuteur géré reste préférable pour les jobs courts, reproductibles et sans accès particulier. En revanche, un poste local unique devient fragile lorsque plusieurs personnes attendent une compilation, lorsque le Mac doit rester disponible hors des horaires de bureau ou lorsque la signature ne doit pas être mélangée aux tâches quotidiennes.

Acheter un Mac mini donne un contrôle physique et peut être pertinent pour une charge stable à long terme. Il faut toutefois gérer l’achat, le remplacement, l’alimentation, la connectivité, les mises à jour et l’accès distant. Un serveur Linux ou une machine virtuelle macOS ne remplace pas toujours un hôte Mac réel pour Xcode, les périphériques Apple, certains plugins audio ou les outils créatifs de vidéo et de design.

La location d’un Mac distant chez VpsMesh est surtout intéressante pour un déploiement progressif : vous pouvez isoler un projet, éprouver le redémarrage, mesurer la propreté des workspaces et décider ensuite si le nœud mérite de porter la publication. Si votre charge est permanente, très lourde et nécessite un accès physique à un périphérique, l’achat d’un Mac dédié peut rester plus cohérent.

Votre pipeline actuel présente généralement trois défauts dans ce scénario : il dépend d’un poste local indisponible lorsque son utilisateur est absent, il mélange parfois compilation et secrets de signature, et il ne fournit pas toujours une procédure claire de reprise après redémarrage. Un Mac distant administré comme un nœud CircleCI corrige ces points seulement si vous conservez l’isolation et les tests décrits ici. Commencez par une tâche sans signature, validez le routage et le nettoyage, puis choisissez la durée de location adaptée à votre cycle de livraison via les options Mac de VpsMesh.