Le pipeline reste en attente, alors que l’agent semble connecté et que la machine distante répond encore en SSH.
La solution la plus rapide consiste à isoler un Mac Apple Silicon conforme aux exigences officielles, à déployer d’abord un Buildkite self-hosted agent pour une compilation en ligne de commande, puis à ajouter Simulator, signature et redémarrage uniquement après validation de chaque étape. Au 31 août 2026, Xcode 27 doit encore être traité comme une chaîne bêta : ne le mélangez pas avec votre environnement de production stable. Consultez les notes de version officielles de Xcode 27 Beta avant de commencer.
Cette procédure s’adresse à vous si vous migrez des compilations iOS ou macOS depuis un poste local vers Buildkite, si vous maintenez un nœud Mac distant disponible en continu, ou si vous validez Xcode 27 Beta tout en conservant une chaîne stable séparée. Elle est moins adaptée à une équipe qui exige des interfaces matérielles physiques ou une charge de compilation constante sans interruption administrative.
Point d’arrêt important : si le modèle de Mac, la version de macOS ou l’association avec Xcode 27 ne respecte pas les exigences Apple publiées, arrêtez la configuration. Un agent connecté n’est pas la preuve qu’un environnement de compilation est compatible.
SECTION 01 La décision à prendre avant la première connexion
Un nœud distant peut recevoir les tâches Buildkite sans exposer inutilement de port entrant. Le plan de contrôle distribue les travaux, le processus Agent les réclame par une connexion sortante, et le Mac exécute les commandes avec les droits du compte qui l’héberge. Cette séparation réduit la surface réseau, mais elle ne corrige ni une mauvaise gestion des secrets ni une version Xcode incohérente.
Avant toute installation, vérifiez les trois éléments suivants dans la documentation Apple :
- le matériel Apple Silicon réellement disponible ;
- la version de macOS requise par Xcode 27 ;
- les SDK, simulateurs et problèmes connus correspondant à la révision de Xcode installée.
La page Apple consacrée aux exigences système de Xcode doit servir de référence, et non une image de machine ou une ancienne note interne. La bêta peut évoluer ; figez donc une version explicitement identifiée dans vos scripts et conservez une machine stable pour les livraisons déjà acceptées.
Définissez ensuite la portée du nœud. Une compilation avec xcodebuild en mode non interactif n’a pas les mêmes contraintes qu’un test d’interface avec Simulator ou qu’une publication nécessitant une clé privée. Pour ce guide, les charges sont séparées ainsi :
- Compilation en ligne de commande : résolution des dépendances, compilation, tests unitaires et génération de résultats ;
- Tests graphiques : démarrage d’une session utilisateur, accès à Simulator, exécution et collecte des résultats ;
- Signature et publication : accès contrôlé au trousseau, aux certificats, aux profils et aux identifiants de l’équipe.
Cette classification déterminera le Cluster, la Queue, les étiquettes de l’agent et les comptes autorisés.
SECTION 02 Première étape : préparer un nœud isolé et observable
Créez un compte macOS réservé à l’agent. Il ne doit pas être votre compte administrateur quotidien ni celui utilisé pour consulter des données personnelles. Accordez-lui uniquement les permissions nécessaires à la compilation ; l’accès au trousseau de signature sera ajouté plus tard, sur un nœud ou une étape distincte.
Notez avant installation :
- le nom d’hôte du Mac ;
- l’architecture renvoyée par
uname -m; - le chemin réel de
xcodebuild; - la version de macOS ;
- la version exacte de Xcode 27 ;
- l’espace disponible pour les sources, les dépendances, les journaux et les artefacts.
N’écrivez pas ces valeurs de mémoire dans un script définitif. Faites-les produire par une tâche de diagnostic et archivez la sortie. Vous pourrez ainsi distinguer une erreur de routage Buildkite d’un mauvais environnement de développement.
Le service Buildkite doit être installé suivant la procédure macOS actuelle de la documentation officielle d’installation de l’Agent. Cette page précise le compte d’exécution, le mécanisme de lancement et les emplacements à confirmer sur la machine ; ne supposez donc pas qu’un chemin trouvé dans un exemple correspond à votre installation.
SECTION 03 Première heure : enregistrer l’agent et contrôler le routage
Installez l’Agent sous le compte dédié, puis rattachez-le au Cluster et à la Queue prévus pour ce nœud. Le fonctionnement officiel des agents autohébergés explique que l’Agent prend les tâches auprès du service de contrôle ; il n’est pas nécessaire d’ouvrir au hasard un accès entrant vers le Mac distant.
Employez des valeurs fictives dans les exemples et dans vos notes :
export BUILDKITE_AGENT_TOKEN="<JETON_AGENT_DEDIE>"
export BUILDKITE_QUEUE="<QUEUE_XCODE_27_ISOLEE>"
export BUILDKITE_HOSTNAME="<NOM_HOTE_MAC_DISTANT>"
Le jeton ne doit apparaître ni dans le dépôt, ni dans une commande copiée dans un ticket, ni dans les journaux de compilation. Utilisez le mécanisme de stockage de secrets prévu par votre organisation, limitez la portée du jeton et prévoyez sa rotation. Les règles de création et d’utilisation des files d’agents doivent être appliquées avant d’envoyer un projet réel.
Lancez ensuite une tâche minimale, sans dépendance et sans certificat :
printf 'system=%s\n' "$(sw_vers -productVersion)"
printf 'arch=%s\n' "$(uname -m)"
printf 'xcodebuild=%s\n' "$(xcode-select -p)"
Le résultat attendu n’est pas seulement une sortie correcte. Vous devez prouver que la tâche a été exécutée sur le Mac prévu, dans la Queue prévue, avec le compte prévu. Ajoutez l’hôte, l’architecture et le chemin des outils aux artefacts de diagnostic, sans jamais y inclure le jeton.
Si la tâche est attribuée à un autre nœud, si la Queue reste vide ou si l’Agent apparaît en ligne sans prendre le travail, arrêtez-vous ici. Corrigez les étiquettes, la Queue, les autorisations de code d’accès et la configuration de l’Agent avant d’ajouter Xcode.
SECTION 04 Buildkite Agent peut-il être installé sur un Mac distant ?
Oui, à condition que le Mac distant soit réellement administrable, que l’Agent s’exécute sous un compte maîtrisé et que la connexion sortante nécessaire au service soit autorisée. Buildkite documente explicitement l’installation d’agents autohébergés sur macOS ; cette confirmation ne garantit toutefois ni la compatibilité de votre projet, ni la performance de sa compilation, ni la disponibilité de Simulator.
La distance géographique ajoute surtout des contraintes d’exploitation :
- une session SSH peut se couper alors que le processus de compilation continue ;
- une interface graphique peut ne pas être ouverte pour le compte de l’Agent ;
- le temps de transfert du dépôt et des artefacts dépend de votre liaison réseau ;
- un redémarrage peut restaurer le système mais pas la session utilisateur attendue ;
- un nœud partagé peut exposer des fichiers temporaires ou des caches à la tâche suivante.
C’est pourquoi vous devez distinguer l’accessibilité du Mac, la connexion de l’Agent et la réussite d’une vraie tâche Xcode. Trois signaux différents exigent trois vérifications différentes.
SECTION 05 Deuxième étape : faire passer un projet réel en ligne de commande
Configurez pour le compte de l’Agent un accès minimal au dépôt. La documentation Buildkite sur l’accès au code doit guider le choix entre identité machine, clé gérée et autre méthode approuvée. Évitez une clé personnelle permanente : elle complique la révocation et élargit le périmètre en cas de fuite.
Dans la pipeline, sélectionnez explicitement Xcode 27 au lieu de dépendre de la sélection interactive laissée par un ancien utilisateur :
sudo xcode-select --switch "<CHEMIN_XCODE_27>"
xcodebuild -version
Ne lancez cette modification avec sudo que si votre procédure d’administration le prévoit ; une mauvaise sélection globale peut perturber d’autres tâches sur le même Mac. Une alternative plus sûre consiste à utiliser le chemin explicite de l’outil dans la commande ou à réserver le nœud à cette version.
Validez le projet selon une progression observable :
- récupérer le code avec l’identité de la pipeline ;
- résoudre les dépendances sans invite interactive ;
- compiler la cible choisie ;
- exécuter les tests unitaires ;
- produire un fichier de résultats et un artefact identifiable.
Chaque commande doit conserver son code de sortie, son journal et le chemin de son résultat. Un script qui masque une erreur puis publie un fichier vide n’est pas une validation. Dans votre pipeline, séparez les étapes de préparation, de compilation, de test et d’archivage afin de voir précisément où l’environnement diverge du poste local.
Le premier succès doit être reproductible. Relancez la même tâche dans un espace de travail nettoyé, puis comparez les versions de macOS, Xcode, SDK et dépendances. La présence de caches peut accélérer une deuxième exécution, mais elle peut aussi dissimuler une dépendance manquante.
SECTION 06 Comment indiquer Xcode 27 comme nœud de construction Buildkite ?
Attribuez au nœud des étiquettes explicites, par exemple une étiquette d’architecture Apple Silicon, une étiquette de version Xcode et une étiquette indiquant qu’il s’agit d’un environnement bêta. Dans la pipeline, exigez la combinaison correspondant à la tâche au lieu d’envoyer toute compilation macOS vers une Queue générale.
Un modèle conceptuel peut ressembler à ceci :
agents:
queue: "<QUEUE_XCODE_27_ISOLEE>"
xcode: "27-beta"
architecture: "apple-silicon"
Adaptez la syntaxe à la configuration exacte de votre pipeline et ne copiez pas ces valeurs fictives en production. Le point essentiel est le routage vérifiable : une tâche Xcode 27 ne doit pas tomber par défaut sur le nœud stable, et une tâche de publication ne doit pas être routée vers un agent de test.
Gardez une Queue séparée pour Xcode stable. Si une modification de bêta casse la résolution des dépendances ou un SDK, vous devez pouvoir revenir à la Queue stable sans réinstaller toute la flotte. La version bêta est un périmètre de validation, pas une raison pour remplacer immédiatement un outil de production.
SECTION 07 Troisième étape : n’ajouter Simulator qu’après la compilation
Un nœud de compilation purement textuelle n’a pas besoin d’une session graphique permanente. Si votre projet ne réalise que des tests unitaires et des archives sans interface, n’ajoutez pas la complexité d’un bureau connecté, d’un état de session et d’un parc de simulateurs.
Si les tests d’interface sont nécessaires, vérifiez d’abord que le compte de l’Agent dispose d’une session macOS utilisable, que le runtime requis est installé et que le périphérique simulé apparaît dans la liste visible par ce même compte. Exécutez le contrôle depuis la tâche Buildkite, pas depuis votre session personnelle :
xcrun simctl list devices
xcodebuild test \
-scheme "<SCHEMA_TEST>" \
-destination 'platform=iOS Simulator,name=<APPAREIL_SIMULE>,OS=<VERSION_RUNTIME>'
La disponibilité d’un runtime dépend de la version installée de Xcode 27 et des exigences Apple documentées. Reportez-vous aux notes de version Xcode 27 pour les restrictions et problèmes connus avant d’interpréter un échec.
Votre test minimal doit démontrer quatre choses : Simulator démarre, l’application s’installe, le test s’exécute, puis les résultats sont collectés et l’espace temporaire est nettoyé. Un test Simulator réussi ne prouve pas que le matériel réel, la notification distante ou la publication signée fonctionneront.
SECTION 08 Quatrième étape : séparer compilation, signature et publication
La signature est une frontière de sécurité, pas une variable d’environnement à ajouter à la fin d’un script. Maintenez la compilation et les tests ordinaires dans une Queue ou un compte qui ne peut pas utiliser les certificats de publication. Réservez l’étape signée à une tâche contrôlée, déclenchée selon les règles de votre dépôt.
Vérifiez les éléments suivants avec des identifiants fictifs dans vos exemples :
- nom du certificat :
<CERTIFICAT_IOS_DISTRIBUTION>; - identifiant d’équipe :
<TEAM_ID>; - profil de provisioning :
<PROFIL_SIGNATURE>; - mot de passe du trousseau :
<MOT_DE_PASSE_TROUSSEAU>.
Les discussions et ressources Apple sur la gestion des certificats de signature rappellent les difficultés liées au trousseau, aux profils et aux sessions non interactives. Testez donc explicitement le déverrouillage contrôlé, l’accès à la clé privée et la sélection du profil sous le compte de l’Agent.
N’inscrivez aucun secret dans le dépôt ou la ligne de commande persistante. Effacez les fichiers temporaires après usage, limitez les permissions du répertoire de travail et empêchez une tâche de demande de tirage d’accéder au trousseau de production. Si vous ne pouvez pas démontrer cette séparation, laissez la publication hors de ce nœud.
SECTION 09 Cinquième étape : rendre l’Agent persistant après redémarrage
Le lancement automatique doit être géré par launchd selon la procédure macOS documentée par Buildkite et les principes Apple de création de tâches launchd. Confirmez le compte propriétaire, le fichier de configuration, le chemin du journal et le répertoire de travail effectivement utilisés ; ne concluez pas à partir d’un ancien fichier de service.
Effectuez un redémarrage contrôlé, puis observez la récupération dans cet ordre :
- le Mac accepte à nouveau une connexion d’administration ;
- le compte de l’Agent retrouve l’état de session requis ;
- le service launchd démarre le processus avec la bonne configuration ;
- l’Agent réapparaît dans la Queue attendue ;
- une vraie compilation Xcode s’exécute et produit ses artefacts.
Si seul le processus Agent est vivant mais que la session graphique, le trousseau ou Simulator reste inutilisable, le nœud n’est pas opérationnel pour les tâches concernées. Pour cette raison, ne corrigez pas un redémarrage en ajoutant immédiatement plusieurs processus Agent : vous risqueriez de créer une concurrence sur le répertoire de travail, DerivedData, Simulator ou le trousseau.
SECTION 10 La vérification de mise en production
À l’issue de la première journée, faites une revue par résultats plutôt que par impressions. Utilisez cette liste comme seuil de décision :
- [ ] Le Mac respecte les exigences Apple vérifiées pour macOS et Xcode 27.
- [ ] L’Agent utilise un compte dédié et un jeton stocké hors du dépôt.
- [ ] La Queue Xcode 27 est isolée de la chaîne stable.
- [ ] Une tâche minimale confirme l’hôte, l’architecture et le chemin des outils.
- [ ] Un projet réel se clone, se compile, teste et produit un résultat exploitable.
- [ ] Les variables interactives du poste personnel ne sont pas nécessaires.
- [ ] Simulator est validé uniquement si le projet en a besoin.
- [ ] Le compte de test ne peut pas lire les secrets de publication.
- [ ] Une tâche signée fonctionne avec des certificats et profils contrôlés.
- [ ] Après redémarrage, la session, launchd, la Queue et une vraie tâche reviennent.
- [ ] Les journaux, caches et espaces de travail ont une règle de nettoyage.
- [ ] Une version stable reste disponible comme itinéraire de retour.
Les conclusions doivent rester limitées à ce que vous avez démontré. Une compilation réussie justifie un usage de compilation ; elle ne justifie pas automatiquement les tests graphiques. Un test Simulator réussi ne justifie pas l’accès aux certificats. Un Agent visible dans l’interface ne justifie aucune de ces deux affirmations.
SECTION 11 Quelle solution choisir pour un Mac CI durable ?
Un Mac local convient lorsque vous contrôlez physiquement la machine, acceptez qu’elle soit indisponible pendant une maintenance et n’avez pas besoin de plusieurs environnements séparés. Un Mac mini placé dans vos locaux donne davantage de contrôle matériel, mais vous devez assurer l’alimentation, le réseau, les sauvegardes, les mises à jour, l’accès distant et le remplacement en cas de panne.
Un Mac distant loué devient plus pertinent lorsque vous devez tester rapidement Xcode 27 sans acheter une machine dédiée, isoler une Queue bêta ou conserver un nœud accessible pendant vos horaires de développement. Vous devez néanmoins demander des informations vérifiables sur l’architecture, la version de macOS, le mode d’accès administrateur, la réinstallation et la reprise après redémarrage. Pour comparer les modalités disponibles, consultez la présentation française de VPSNIX et examinez les options de location Mac et leurs tarifs avant de transférer des secrets.
Le modèle actuel — poste local partagé, machine personnelle laissée allumée ou serveur Linux adapté par contournement — présente souvent quatre défauts concrets : il mélange les versions Xcode, il dépend d’une session humaine, il rend la signature trop accessible et il ne fournit pas de chemin de reprise documenté après redémarrage. Une location Mac chez VPSNIX peut offrir un environnement distant plus approprié pour une validation temporaire, un nœud Apple Silicon isolé ou une chaîne CI qui doit rester disponible sans immobiliser immédiatement votre propre matériel. Commencez par appliquer la liste d’acceptation ci-dessus ; si le nœud passe la compilation, Simulator, la signature et la reprise, vous aurez une base technique pour décider d’un usage régulier plutôt qu’une simple promesse d’agent « en ligne ».