Ce guide concerne les responsables plateforme qui ajoutent une capacité iOS ou macOS à TeamCity, les équipes IT qui transforment un Mac mini en nœud partagé et les décideurs qui comparent plusieurs Mac distants.

Vous y trouverez une méthode de diagnostic par domaine de blocage, plutôt qu’une simple succession de commandes d’installation. L’objectif est de produire des preuves d’acceptation exploitables lors d’un audit, d’un incident ou d’une extension de capacité.

Dernière mise à jour : 30 août 2026. Les points relatifs à TeamCity On-Premises 2026.1, à TeamCity Cloud 2026.2, au démarrage des agents et à Xcode ont été vérifiés à partir des documentations officielles indiquées dans cet article.

Dans un déploiement de l’agent de build macOS TeamCity 2026.1, le premier risque est une base d’exécution incompatible. Un agent peut être joignable tout en étant inutilisable pour une compilation iOS.

Java 21 sépare l’agent du projet compilé

TeamCity On-Premises 2026.1 requiert Java 21 pour l’exécution concernée de la plateforme et de ses composants. Cette exigence doit être vérifiée sur l’hôte avant l’enregistrement, avec la page des exigences système de la version déployée, et non déduite de la version Java utilisée par votre application.

Consultez les exigences système officielles de TeamCity pour confirmer la version applicable à votre serveur et à vos agents. La distinction est importante :

• le JDK de l’agent sert à lancer le processus TeamCity ;
• le JDK utilisé par un projet peut être sélectionné séparément dans sa configuration de build ;
• une pipeline Android, serveur ou outil interne peut donc demander un autre JDK sans justifier l’exécution de l’agent avec ce même JDK ;
• JAVA_HOME doit pointer vers le JDK réellement utilisé par le service de l’agent, pas vers une installation choisie par défaut dans une session graphique.

Sur l’hôte macOS, conservez la sortie de contrôle, le chemin du JDK et l’identité du compte de service. Un exemple minimal suffit :

java -version
echo "$JAVA_HOME"

Ces deux lignes ne prouvent pas à elles seules que le service lancé par launchd voit le même environnement. Il faut donc aussi vérifier les variables présentes dans la configuration du service et dans le journal de l’agent.

Apple Silicon et espace de travail doivent figurer dans la fiche d’actif

Un Mac équipé d’Apple Silicon ne garantit ni la compatibilité de tous les outils ni la disponibilité du bon Xcode. Votre fiche d’actif doit au minimum identifier :

• l’architecture du processeur ;
• la version de macOS ;
• les versions complètes de Xcode installées ;
• l’emplacement du répertoire de travail TeamCity ;
• le compte propriétaire du processus ;
• le volume disponible pour les sources, les dépendances, les archives et les journaux ;
• le mode de connexion réseau vers le serveur TeamCity.

L’espace disque n’est pas qu’une caractéristique matérielle. Une compilation qui fonctionne sur un projet vide peut échouer lorsque les dépendances, les symboles d’archive ou les données de simulateur s’accumulent. Définissez une règle d’exploitation : nettoyage automatique, seuil d’alerte et procédure de retrait du nœud si le volume disponible devient insuffisant.

Pourquoi faut-il éviter root ?

Un agent de production ne devrait pas fonctionner sous root. Un script de build compromis, une dépendance mal contrôlée ou une commande de nettoyage trop large pourrait alors agir sur l’ensemble du système.

Créez un compte macOS dédié, sans usage interactif quotidien, avec les droits strictement nécessaires. Les opérations d’initialisation qui exigent des privilèges administrateur — installation du logiciel, création du service, réglage des permissions ou préparation d’un trousseau — doivent être effectuées temporairement par un administrateur. Le processus TeamCity, lui, doit ensuite retrouver la propriété de son répertoire et fonctionner avec le compte de service.

Cette séparation facilite aussi la réponse aux incidents : vous pouvez supprimer les fichiers du compte de build sans toucher aux comptes d’administration, aux outils de supervision ou aux autres environnements présents sur l’hôte.

L’état « Connected » indique une communication, pas une autorisation complète, une capacité de build ni une route réseau saine dans les deux sens. Trois contrôles doivent être menés ensemble : configuration locale, statut serveur et journaux.

serverUrl, jeton et proxy doivent raconter la même histoire

Lors de l’installation, vérifiez l’URL du serveur, le nom fixe de l’agent et le jeton d’autorisation. N’utilisez pas un nom généré différemment après chaque reprovisionnement : un nom stable facilite l’association au bon Agent Pool, la lecture des historiques et le remplacement contrôlé d’un hôte.

Les instructions officielles de configuration des agents décrivent les propriétés à utiliser. Conservez la configuration dans un emplacement contrôlé, limitez les droits de lecture et ne placez jamais le jeton dans un script partagé ou dans une sortie de pipeline.

Avec un proxy inverse, contrôlez simultanément :

• la résolution du nom du serveur depuis le Mac ;
• la négociation HTTPS ;
• le chemin public réellement utilisé par l’agent ;
• les en-têtes et règles de proxy qui pourraient interrompre la connexion persistante ;
• les restrictions de sortie du réseau hébergeant le Mac.

Le modèle à retenir est celui d’un agent qui initie sa communication vers le serveur. Il ne faut donc pas ouvrir inutilement une administration entrante vers le Mac. En revanche, les règles de sortie, le proxy et l’inspection TLS doivent autoriser les échanges nécessaires.

Les preuves d’enregistrement sont indispensables

Ne validez pas le nœud depuis la console uniquement. Archivez plutôt :

• le journal local de l’agent au moment de l’enregistrement ;
• le statut d’autorisation côté serveur ;
• le nom exact de l’agent ;
• l’Agent Pool auquel il appartient ;
• les paramètres détectés par TeamCity ;
• les événements de proxy ou de pare-feu ;
• le résultat d’une tâche de diagnostic lancée sur le nœud.

Les paramètres prédéfinis des agents TeamCity permettent de vérifier les valeurs exposées à la pipeline. Comparez ces informations avec l’inventaire macOS. Une divergence entre le chemin détecté, l’architecture ou le compte d’exécution explique souvent pourquoi le tableau de bord paraît sain alors que le build sélectionne mal le nœud.

TeamCity Cloud et On-Premises ne doivent pas être confondus

TeamCity Cloud 2026.2 possède ses propres indications pour installer et démarrer un agent. Elles sont utiles pour comprendre le mécanisme de démarrage documenté côté Cloud, mais elles ne permettent pas de conclure qu’une fonction ou un comportement est identique dans TeamCity On-Premises 2026.1.

Pour votre dossier de mise en production, rattachez chaque décision à la documentation de l’édition réellement utilisée. Cette discipline évite de copier une propriété de démarrage Cloud dans un déploiement On-Premises, puis de traiter l’écart comme une panne aléatoire.

Le routage Xcode doit être prouvé à trois niveaux : la demande de la tâche, les paramètres déclarés par le nœud et la sortie réelle des outils. Si un seul niveau diverge, l’agent ne doit pas recevoir une archive de production.

Xcode complet n’est pas équivalent aux outils de ligne de commande

Les outils de ligne de commande fournissent des exécutables utiles, mais ils ne remplacent pas automatiquement une installation complète de Xcode pour une pipeline iOS ou macOS. La documentation Apple sur la référence des outils de ligne de commande Xcode doit être utilisée pour distinguer ce qui est disponible sur l’hôte.

Vérifiez notamment :

xcode-select -p
xcodebuild -version

Puis contrôlez que le chemin correspond à une installation complète autorisée pour le projet. Un hôte qui ne possède que les outils de ligne de commande ne doit pas être présenté comme un Mac de build iOS prêt pour la publication.

Une version ou plusieurs versions : deux stratégies différentes

Pour une seule version de Xcode, xcode-select peut définir le chemin actif du système. Cette solution est simple, mais elle ne doit pas être modifiée silencieusement par une pipeline concurrente.

Pour plusieurs versions, déclarez explicitement le chemin de Xcode et exposez-le comme paramètre d’agent. Les exigences de l’agent peuvent ensuite orienter une tâche vers le bon nœud. Les exigences d’agent TeamCity expliquent le principe de filtrage par paramètres ; appliquez-le à l’édition et à la configuration réellement exploitées.

Dans la configuration de la tâche, faites correspondre :

• la version de Xcode demandée par le projet ;
• le paramètre publié par l’agent ;
• le chemin effectivement utilisé par xcodebuild ;
• l’architecture attendue par les dépendances ;
• la destination de test ou d’archivage.

La documentation TeamCity relative au runner Xcode précise les éléments à configurer. Pour une pipeline audio, vidéo ou design qui produit une application macOS avec des outils auxiliaires, ajoutez aussi les vérifications propres aux extensions, aux plug-ins et aux ressources signées. La présence d’un Xcode correct ne valide pas automatiquement ces composants.

Le diagnostic d’un agent en ligne sans build Xcode

Commencez par examiner les exigences non satisfaites, puis le journal de la tâche. Ne réinstallez pas immédiatement l’agent. Les causes fréquentes sont un paramètre absent, une version de Xcode mal déclarée, un chemin inaccessible au compte de service ou une architecture incompatible avec une dépendance.

Le diagnostic doit répondre à une question précise : la tâche n’est-elle pas envoyée au nœud, ou bien démarre-t-elle avant d’échouer dans Xcode ? Ces deux incidents n’ont pas la même correction. Le premier concerne le routage TeamCity ; le second concerne l’environnement de build.

Un Agent Pool n’est pas une frontière de sécurité suffisante. Les builds exécutés sur un même agent peuvent partager des fichiers, des caches, des processus ou des éléments de l’environnement. La décision d’utiliser un nœud partagé doit donc dépendre du niveau de confiance des projets.

Séparez les classes de tâches

Ne placez pas dans le même nœud de publication :

• des demandes de fusion provenant de contributeurs non approuvés ;
• des tests ordinaires sans signature ;
• des builds de validation utilisant des secrets temporaires ;
• des archives de production avec certificats et profils de provisioning.

Les recommandations TeamCity sur les Agent Pools servent à organiser l’affectation des projets. Pour une isolation forte, associez toutefois le pool à des hôtes dédiés, à des comptes distincts et à des règles de secret adaptées.

Contrôlez le checkout, le cache et le trousseau

Pour chaque pipeline, documentez le répertoire de checkout et vérifiez qu’il ne recouvre pas celui d’une autre tâche. Un nettoyage complet doit être testé, pas simplement activé dans l’interface. Comparez le contenu avant et après le build, y compris les fichiers cachés, les archives et les journaux.

Pour la signature :

1. créez un trousseau temporaire appartenant au compte de build ;
2. importez uniquement les certificats nécessaires à la tâche ;
3. limitez son utilisation aux processus attendus ;
4. lancez l’archive ou le test signé ;
5. supprimez les identités et le trousseau à la fin ;
6. vérifiez dans le journal qu’aucun secret n’a été copié dans l’espace de travail.

Un nettoyage déclaré mais non vérifié ne constitue pas une preuve d’isolation. Pour une tâche de publication, conservez la liste des identités avant et après exécution, ainsi que la différence des répertoires de travail. Les projets non fiables doivent revenir vers un agent distinct, même si leur durée de build est faible.

Un Mac distant peut-il devenir un nœud de production ?

Oui, si le Mac distant est traité comme une ressource dédiée et si vous pouvez démontrer la maîtrise de l’accès, du compte de service, du stockage, des secrets, du redémarrage et de la capacité. Non, si l’environnement est partagé sans séparation vérifiable ou si une intervention manuelle est nécessaire après chaque panne.

Un Mac distant peut être pertinent pour commencer un pilote TeamCity, absorber une demande temporaire de build ou réserver une capacité Apple Silicon sans immobiliser immédiatement un parc local. Vous pouvez examiner les options de Mac distant KVMNODE dans le cadre de cette comparaison, mais la décision doit rester fondée sur le dossier de validation, pas sur la seule disponibilité de la machine.

Un agent qui fonctionne uniquement après ouverture de session par un technicien n’est pas un nœud autonome. Le test doit couvrir le démarrage du service, la reconnexion TeamCity, la première invocation de Xcode, l’accès au trousseau et la remontée d’une alerte en cas d’échec.

Distinguez le mécanisme documenté de votre objectif opérationnel

Les instructions de démarrage peuvent varier entre TeamCity On-Premises 2026.1 et TeamCity Cloud 2026.2. La documentation officielle du démarrage des agents ne doit donc pas être transposée sans vérification à votre édition.

Sur macOS, contrôlez les points suivants :

• le fichier de service appartient au bon administrateur ;
• le processus final s’exécute sous le compte de build ;
• les chemins absolus sont utilisés ;
• JAVA_HOME est disponible dans le contexte de service ;
• les répertoires et journaux sont accessibles ;
• le service ne dépend pas d’une interface graphique ouverte ;
• la reconnexion est visible dans le journal et dans la console TeamCity.

Le lancement automatique peut demander une configuration spécifique au système. Si le flux officiel ou votre configuration impose une session utilisateur, indiquez-le comme une limite. Ne placez pas alors ce Mac dans un pool de publication sans surveillance.

Testez une panne simulée

Effectuez un redémarrage planifié et notez l’heure. Vérifiez ensuite, dans cet ordre, la présence du processus, la connexion de l’agent, la visibilité des paramètres Xcode, l’accès au trousseau temporaire et l’exécution d’une tâche représentative.

Répétez le scénario après une interruption réseau contrôlée si votre politique l’autorise. Le résultat attendu n’est pas seulement « l’agent revient en ligne ». Il doit aussi redevenir sélectionnable, retrouver son environnement prévu et échouer proprement si une dépendance critique manque.

Pour une procédure plus large, vous pouvez rattacher ce contrôle à un guide de mise en service d’un nœud de build Mac, puis conserver vos propres journaux comme preuve d’exploitation.

Un projet vide ne mesure pas la capacité utile d’un nœud. Utilisez une pipeline représentative comprenant une compilation, des tests de simulateur, une archive et, si nécessaire, une signature contrôlée. Les tâches doivent provenir de vos projets réels, avec leurs dépendances et leurs règles de cache.

Les critères d’admission

Évaluez les éléments suivants séparément :

• sélection correcte du nœud selon la version de Xcode ;
• absence de mélange entre espaces de travail ;
• suppression effective des certificats temporaires ;
• reconnexion après redémarrage ;
• journal exploitable en cas d’échec ;
• capacité à recevoir une nouvelle tâche sans intervention ;
• comportement lorsqu’un second nœud doit prendre le relais ;
• évolution de la file d’attente pendant une charge représentative.

Ne transformez pas une moyenne de durée de build en promesse de performance. La durée dépend du projet, des dépendances, des tests, des archives et des caches. Votre conclusion doit s’appuyer sur les tâches réellement soumises, les heures de début et de fin, les erreurs et les conditions de l’hôte.

Outil de décision pour la mise en production

Cochez chaque condition uniquement lorsque vous disposez d’une preuve conservée dans le dossier d’exploitation :

• [ ] Java 21 est confirmé dans le contexte réel du service, et non seulement dans une session administrateur.
• [ ] L’agent fonctionne sous un compte macOS dédié et non root.
• [ ] Le nom de l’agent, son serverUrl, son autorisation et son Agent Pool sont documentés.
• [ ] Le proxy, le HTTPS et les journaux prouvent une connexion stable vers le serveur.
• [ ] Le chemin Xcode, la version demandée par la tâche et la sortie xcodebuild sont cohérents.
• [ ] Le répertoire de checkout, les caches et le nettoyage ont été vérifiés sur une tâche représentative.
• [ ] Les certificats, profils et trousseaux temporaires sont supprimés après une tâche signée.
• [ ] Le Mac redémarre, reconnecte l’agent et accepte une tâche sans ouverture de session manuelle.
• [ ] Une pipeline réelle a exécuté compilation, tests, archive et signature selon le périmètre prévu.
• [ ] Une procédure de retrait, de remplacement ou de reprise par un autre nœud est testée.

Appliquez ensuite ces conditions :

• Si toutes les cases critiques sont cochées, placez l’agent dans un pool de production limité au périmètre validé.
• Si Java, Xcode ou l’autorisation échoue, maintenez le nœud hors production et corrigez la base avant tout nouvel essai.
• Si l’isolation des secrets ou des espaces de travail échoue, réservez un Mac dédié aux tâches signées et interdisez les projets non fiables.
• Si le redémarrage exige une intervention, classez le nœud comme capacité de secours surveillée, pas comme infrastructure de publication autonome.
• Si la file d’attente dépasse vos seuils internes ou si le relais n’est pas démontré, ajoutez un second nœud avant d’augmenter le périmètre.
• Si les preuves de capacité sont encore insuffisantes, restez en pilote et ne concluez ni à la stabilité ni à la rentabilité.

Les essais doivent refléter vos usages métiers

Ajoutez au moins une tâche représentative de chaque profil important : application iOS, application macOS, test de simulateur, archive signée et, lorsque cela existe, projet audio, vidéo ou design utilisant des ressources volumineuses et des extensions.

Enregistrez les heures de début et de fin, le nom du nœud, la version de Xcode, le résultat de la signature et l’état du répertoire après nettoyage. Ces éléments sont plus utiles pour planifier une capacité que le résultat d’un projet vide.

Un parc local offre la maîtrise physique et peut être préférable pour une charge stable, un accès à des périphériques spécifiques ou des contraintes internes de conservation. Il implique cependant l’achat initial, le remplacement du matériel, le stockage, l’alimentation, le réseau, la supervision et la gestion des incidents sur site.

La location distante apporte une mise à disposition plus progressive et facilite le pilote d’un agent isolé. Elle ne supprime pas les contrôles : vous devez toujours vérifier la latence vers le serveur TeamCity, la confidentialité des sources, le mode d’accès administratif, la conservation des journaux et la procédure de restitution.

Pour un premier nœud Apple Silicon, comparez donc deux plans :

• Mac local : préférable si vous avez déjà l’espace, l’alimentation, le réseau, les compétences d’exploitation et une charge durablement prévisible ;
• Mac distant KVMNODE : pertinent si vous devez tester rapidement un agent dédié, éviter un achat immédiat ou ajouter une capacité temporaire sans modifier votre parc physique.

Le défaut du Mac local est souvent sous-estimé : une panne matérielle ou une maintenance immobilise le nœud jusqu’à l’intervention sur site. Le défaut du Mac distant est différent : une dépendance au réseau et au prestataire exige une procédure de secours documentée. Pour cette raison, commencez par un pilote isolé, mesurez vos vraies pipelines, puis choisissez une capacité hebdomadaire, mensuelle ou plus longue selon les preuves de charge et de redondance.

Un agent TeamCity 2026.1 « connecté » n’est donc pas encore un agent de production. En exigeant Java 21, un routage Xcode explicite, une séparation des signatures, une reprise sans session manuelle et une validation par pipeline réelle, vous évitez de transformer un Mac partagé mal contrôlé en point unique de défaillance.

Si vous utilisez actuellement un Mac mini local partagé, ses limites sont généralement concrètes : capacité immobilisée même lorsque la demande baisse, intervention physique lors d’une panne et risque de mélange entre les projets. Une infrastructure distante mal cadrée présenterait, de son côté, une dépendance réseau et une isolation incertaine. Après validation du dossier, un nœud distant dédié KVMNODE permet de tester la route TeamCity, Xcode, la signature et la reprise avec une capacité séparée, avant de décider d’un engagement plus long.

Commencez par une seule machine isolée et par une pipeline réelle. Lorsque la base est stable, choisissez une capacité hebdomadaire, mensuelle ou plus longue selon la file d’attente, la redondance démontrée et vos exigences de publication.