Agent macOS Jenkins déconnecté : diagnostic du nœud distant en 2026

Une connexion SSH réussie ne prouve pas que Jenkins peut exécuter une tâche : la documentation Jenkins distingue le nœud, l’agent et le canal de communication qui relie l’agent au contrôleur (documentation officielle sur les agents Jenkins). Si votre agent macOS Jenkins est déconnecté, ne réinstallez donc pas immédiatement le nœud. Cette semaine, commencez par isoler le problème dans cet ordre : planification Jenkins, réseau, processus Java, session macOS, puis outils Xcode. Réparez localement une panne ponctuelle ; isolez et reconstruisez le nœud si les déconnexions ou la dérive d’environnement se répètent.

À qui s’adresse ce diagnostic

Ce guide est destiné aux ingénieurs DevOps qui administrent Jenkins et un Mac distant de construction et veulent réduire le temps de rétablissement d’un agent hors ligne.

Il concerne également les développeurs qui exécutent des compilations, tests ou signatures Xcode, ainsi que les responsables de plateforme qui souhaitent définir une vraie procédure d’acceptation pour un nœud macOS CI toujours disponible.

Le premier tri évite un faux diagnostic

Le symptôme « agent hors ligne » recouvre plusieurs situations. Un nœud peut être réellement déconnecté, volontairement marqué hors ligne, ou parfaitement connecté mais incapable d’accepter la tâche demandée. Dans ce dernier cas, le problème vient souvent d’une étiquette, d’un exécuteur, d’un répertoire racine ou d’une règle de planification.

Avant toute modification, conservez :

l’heure locale et l’heure affichée par le contrôleur ;
le message exact visible dans la page du nœud ;
la raison d’une éventuelle mise hors ligne ;
la cause de blocage affichée dans la file d’attente ;
les dernières lignes du journal du nœud ;
l’état du processus Agent sur le Mac distant ;
le nom du travail, son étiquette et le type de tâche attendu.

La page de gestion des nœuds Jenkins permet de distinguer les informations du nœud, les exécuteurs et les journaux de connexion (guide officiel de gestion des nœuds). Cette séparation est essentielle. Une tâche en attente avec un agent marqué en ligne n’est pas une panne réseau démontrée.

Le cas qui trompe le plus souvent

Vous ouvrez une session SSH sur le Mac. Le système répond, le disque est accessible et un simple echo fonctionne. Pourtant, Jenkins affiche le nœud hors ligne ou refuse une tâche Xcode.

Dans ce cas, SSH a seulement prouvé que le service Remote Login macOS accepte votre connexion. Il n’a pas prouvé que le canal Jenkins est établi, que le processus Java appartient au bon utilisateur, que le secret est valide ou que l’environnement graphique et les outils de développement sont disponibles. Apple décrit séparément l’activation et l’usage de Remote Login dans sa documentation officielle (guide Apple sur Remote Login).

La connexion Jenkins doit être examinée comme un canal distinct

Ne mélangez pas trois éléments :

la connexion SSH que vous utilisez pour administrer macOS ;
le service SSH éventuellement utilisé par le lancement de l’agent Jenkins ;
le transport Jenkins entre le contrôleur et l’agent.

Ces chemins peuvent avoir des adresses, des règles de filtrage et des identifiants différents. Une modification de DNS, de proxy, de certificat, de pare-feu ou d’adresse du contrôleur peut interrompre Jenkins tout en laissant votre accès administrateur intact.

Le mode de lancement détermine la vérification à effectuer :

Lancement par SSH : vérifiez l’hôte cible, l’utilisateur, la clé ou le moyen d’authentification, le chemin du Java exécutable et l’accès au répertoire de travail.
Connexion entrante : vérifiez que le Mac peut joindre l’adresse du contrôleur et que le secret actuel correspond à celui attendu par le nœud.
WebSocket : examinez la compatibilité du chemin HTTP(S), du proxy inverse et des certificats, au lieu de tester uniquement un port SSH.
Agent Listener TCP : vérifiez le port effectivement configuré dans Jenkins et son exposition réseau. Jenkins documente les services exposés et les ports d’agent ; ne déduisez pas un port à partir d’une ancienne installation (documentation Jenkins sur les services et ports).

Après correction, recherchez trois preuves : une négociation complète sans erreur, un état qui reste en ligne pendant l’observation et une reconnexion automatique après redémarrage du contrôleur. Une seule reconnexion manuelle ne valide pas la chaîne.

Les symptômes orientent vers la bonne couche

Symptôme observé	Preuve à recueillir	Couche probablement en cause	Action immédiate
SSH fonctionne, Jenkins reste hors ligne	Journal du nœud et statut du processus Agent	Transport Jenkins ou processus Java	Comparer le mode de lancement, l’adresse du contrôleur et le secret
Nœud en ligne, tâche en attente	Cause de la file, étiquette et exécuteurs	Planification Jenkins	Corriger l’étiquette, le nombre d’exécuteurs ou l’état du nœud
Agent disparaît après fermeture de session	Contexte utilisateur et journaux launchd	Session macOS et démarrage permanent	Vérifier le mécanisme réellement installé, sans copier un modèle non validé
Compilation simple réussie, signature échouée	Chemin Xcode, trousseaux et utilisateur effectif	Outils et ressources de signature	Tester séparément compilation, tests et signature
Déconnexion après une coupure réseau	Temps de reconnexion et intervention nécessaire	Tolérance du transport ou supervision	Répéter le test, puis définir un seuil d’isolement

Le processus Java et Jenkins Agent doivent être inspectés sur le Mac

Connectez-vous au Mac avec le même compte que celui utilisé par l’agent, autant que possible. Vérifiez ensuite :

si le processus Agent existe encore ;
son parent et son utilisateur ;
ses arguments de démarrage ;
son code de sortie lorsqu’il s’arrête ;
sa sortie standard et sa sortie d’erreur ;
l’accès à agent.jar ou au composant équivalent réellement utilisé ;
la date de modification des fichiers de lancement ;
les messages indiquant une clé, un secret ou une adresse invalide.

Ne remplacez pas automatiquement l’agent par un fichier téléchargé depuis une URL ancienne. La compatibilité dépend de la version Jenkins réellement exécutée et de la politique Java en vigueur. Consultez la politique officielle de prise en charge de Java par Jenkins au moment du diagnostic, puis relevez la version du contrôleur et le runtime Java présent sur le Mac.

Trois erreurs sont souvent confondues :

un agent Java qui ne démarre plus ;
un agent démarré avec des paramètres obsolètes ;
un agent lancé correctement mais rejeté par le contrôleur.

Le journal Jenkins permet de les séparer. Un échec avant l’ouverture du canal indique plutôt le runtime, le fichier ou la commande. Une fermeture après la négociation oriente davantage vers l’authentification, le secret, la compatibilité ou une terminaison du processus.

Évitez aussi de masquer l’erreur avec une boucle de relance infinie. Elle peut transformer un problème de configuration en succession de processus orphelins. Capturez d’abord la commande effective et son erreur, corrigez ensuite une seule variable à la fois.

Le redémarrage macOS révèle les défauts de persistance

Un lancement manuel depuis SSH est un test utile, mais incomplet. Il s’exécute dans votre shell, avec votre environnement, vos variables et votre session. Après une fermeture de terminal, une déconnexion VNC ou un redémarrage, l’agent peut ne plus disposer du même contexte.

Contrôlez les points suivants :

le compte propriétaire du processus ;
l’existence et les permissions du répertoire de travail ;
le chemin absolu vers Java et les scripts ;
les variables nécessaires à Xcode ;
le mécanisme launchd réellement déployé ;
les journaux du système et du service ;
le moment exact où l’agent est censé démarrer ;
les droits d’accès au trousseau et aux certificats.

Ne fournissez pas un fichier plist générique sans connaître la méthode d’installation, le compte et la version de macOS. Deux déploiements apparemment identiques peuvent utiliser des contextes launchd différents. La bonne procédure consiste à lire la configuration existante, vérifier son propriétaire, lancer un test contrôlé, puis observer le journal après déconnexion et redémarrage.

La réparation est acceptable si le processus revient sans intervention, si le canal Jenkins se rétablit et si le même utilisateur retrouve ses outils. Si vous devez vous reconnecter en SSH et relancer une commande à chaque redémarrage, le nœud n’est pas prêt pour une chaîne Xcode CI durable.

Un agent en ligne ne garantit pas un environnement de construction utilisable

La disponibilité affichée dans Jenkins ne valide pas le disque, le répertoire racine, les étiquettes ou les outils. Commencez par comparer la tâche à la définition du nœud :

l’étiquette demandée existe-t-elle exactement ?
le nœud possède-t-il un exécuteur libre ?
le répertoire racine est-il accessible par l’utilisateur de l’agent ?
l’espace disponible permet-il de créer un espace de travail ?
les permissions ont-elles changé après une restauration ou un déplacement ?
le projet demande-t-il un outil ou une ressource absente de ce nœud ?

Pour Xcode, vérifiez le chemin sélectionné pour les outils de ligne de commande et l’installation attendue. Apple documente la configuration de ce chemin dans les réglages des outils de ligne de commande Xcode, ainsi que leur installation dans la documentation dédiée aux Command Line Tools.

Le test doit utiliser le même utilisateur et le même contexte que l’agent. Une commande lancée dans votre session interactive peut voir un PATH, un trousseau ou une variable différente. C’est particulièrement important pour les projets audio, vidéo et design : une chaîne qui compile un module Swift peut encore échouer lorsqu’elle doit produire une archive, accéder à une ressource graphique ou signer un livrable.

L’acceptation doit séparer compilation, tests et signature

Vérification	Ce qu’elle démontre	Ce qu’elle ne démontre pas
Commande shell minimale dans le répertoire de travail	Agent capable d’exécuter une commande et d’écrire localement	Disponibilité d’Xcode ou des certificats
Compilation du projet avec le chemin Xcode attendu	Outils, dépendances et environnement de compilation cohérents	Résultat des tests ou capacité de distribuer
Exécution d’une vraie suite de tests	Simulateur ou destination, dépendances et rapport exploitables	Validité des identités de signature
Création d’une archive signée	Accès au trousseau, certificats, profils et réglages de distribution	Résilience après redémarrage ou coupure réseau
Relance après redémarrage et interruption réseau	Persistance et reconnexion du nœud	Absence de dérive future de l’environnement

Apple décrit la lecture des résultats de test dans sa documentation Xcode sur l’exécution et l’interprétation des tests. La signature doit être vérifiée comme une étape distincte, notamment pour une archive destinée à la distribution ; consultez les instructions Apple sur le code signé et archivé.

La liste de validation transforme le dépannage en preuve

Utilisez cette liste sur le nœud concerné. Cochez chaque élément avec un résultat observable, et non avec une impression générale.

[ ] Le statut du nœud, la cause de file et le dernier travail réussi ont été capturés.
[ ] Les journaux du contrôleur et du nœud ont été exportés autour du même incident.
[ ] Le mode de lancement réellement configuré est identifié.
[ ] Le chemin réseau Jenkins a été testé séparément de Remote Login macOS.
[ ] Le processus Agent, son utilisateur, ses arguments et son code de sortie sont connus.
[ ] La version Jenkins et le runtime Java ont été comparés à la politique officielle actuelle.
[ ] Le secret, la clé et l’adresse du contrôleur ont été contrôlés sans les exposer dans un ticket.
[ ] Le répertoire racine et le workspace sont accessibles au compte de l’agent.
[ ] Les étiquettes et les exécuteurs permettent réellement la planification.
[ ] Le chemin Xcode attendu est sélectionné dans le contexte de l’agent.
[ ] Une compilation réelle a réussi.
[ ] Une tâche de test a produit un résultat exploitable.
[ ] La signature a été testée séparément si le nœud distribue des artefacts.
[ ] Le nœud revient après redémarrage sans lancement manuel.
[ ] Une interruption réseau ne laisse pas le nœud faussement disponible.
[ ] Les erreurs récurrentes ont un seuil documenté d’isolement ou de reconstruction.

Cette méthode évite de déclarer le nœud « rétabli » après un simple redémarrage du processus. Elle produit aussi les éléments nécessaires à une comparaison entre réparation et remplacement.

Réparer, reconstruire ou ajouter un Mac distant

Situation après diagnostic	Décision recommandée	Pourquoi
Incident unique, processus arrêté, environnement inchangé	Réparer sur place	Le coût opérationnel d’une reconstruction dépasserait probablement le bénéfice
Secret ou paramètre de connexion incorrect	Corriger puis refaire la validation complète	La disponibilité réseau seule ne suffit pas
Déconnexions répétées malgré un transport stable	Isoler le nœud	Les relances masquent une cause persistante
Outils, certificats ou permissions dérivent régulièrement	Reconstruire avec une procédure documentée	La reproductibilité devient plus importante que la conservation du nœud
Un seul Mac porte toutes les tâches de publication	Ajouter un nœud indépendant	Une panne unique ne doit pas bloquer toute la chaîne
Besoin de matériel Apple ou d’une session macOS persistante sans achat immédiat	Évaluer un Mac distant dédié	Le nœud peut être redémarré et administré séparément

La reconstruction ne doit pas être le premier réflexe. Elle efface parfois les preuves : journal de sortie, état du trousseau, erreur de permission ou cause de déconnexion. Conservez les éléments avant de réinitialiser.

En revanche, un nœud qui perd régulièrement ses certificats, change d’outil Xcode ou nécessite une intervention après chaque redémarrage crée une dette de maintenance. Dans ce cas, documentez la sortie, retirez temporairement le nœud de la planification et préparez un environnement propre. Si la capacité doit rester disponible pendant cette opération, un second Mac distant pour les charges de développement peut servir de cible indépendante, à condition de lui appliquer les mêmes tests d’acceptation.

FAQ : les décisions qui reviennent en exploitation

Pourquoi Jenkins indique-t-il un agent macOS hors ligne alors que la connexion SSH fonctionne ?

SSH vérifie seulement l’accès au système macOS. Jenkins utilise ensuite son propre canal de transport, son agent Java, ses identifiants et sa configuration de nœud. Un pare-feu, un secret modifié, un processus arrêté ou une adresse de contrôleur obsolète peut donc laisser SSH opérationnel tout en maintenant l’agent Jenkins hors ligne.

Comment faire revenir automatiquement un agent Jenkins en ligne après le redémarrage du Mac ?

Vérifiez d’abord quel utilisateur et quel contexte de session lancent réellement l’agent. Un démarrage manuel dans SSH ne prouve pas qu’un mécanisme macOS persistera après un redémarrage ou une fermeture de session. Contrôlez la configuration launchd réellement déployée, ses journaux, les permissions et la disponibilité du répertoire de travail.

Que vérifier lorsqu’un agent Jenkins est en ligne mais qu’une tâche Xcode reste en attente ?

Comparez les étiquettes demandées par la tâche avec celles du nœud, puis vérifiez les exécuteurs disponibles, le répertoire racine et les permissions. Examinez aussi la sélection des outils de ligne de commande Xcode et l’utilisateur effectif de l’agent. Un test shell réussi ne suffit pas pour valider une compilation ou une signature.

Vaut-il mieux utiliser SSH ou une connexion entrante pour un agent Jenkins sur un Mac distant ?

Le choix dépend de la topologie réseau et du mode de lancement retenu. SSH convient si le contrôleur peut atteindre le service Remote Login du Mac et gérer ses identifiants. Une connexion entrante ou WebSocket peut être préférable lorsque le Mac établit lui-même la liaison vers le contrôleur. Ne confondez jamais SSH système et transport Jenkins.

Comment confirmer qu’un nœud macOS Jenkins est vraiment rétabli ?

Ne vous contentez pas de l’étiquette « en ligne ». Vérifiez une reconnexion durable, l’exécution d’une tâche sur le bon nœud, l’accès au répertoire de travail, la version d’outils Xcode attendue et une tâche de test adaptée à la signature si nécessaire. Répétez ensuite les essais après redémarrage, interruption réseau et période d’inactivité.

Ce que le choix du Mac distant change pour votre CI

Si votre nœud actuel est un Mac partagé, une machine personnelle ou une instance difficile à redémarrer, vous subissez généralement trois défauts : accès physique limité, contexte utilisateur difficile à reproduire et dépendance à une seule machine pour les compilations ou signatures. Les solutions virtualisées ajoutent parfois des écarts avec le matériel Apple réel, tandis qu’un serveur Linux ne fournit pas l’environnement Xcode requis.

Après avoir mesuré les pannes avec la méthode ci-dessus, comparez le coût d’une réparation permanente avec celui d’un nœud isolé et administrable. La location d’un Mac mini pour votre environnement CI est à examiner si vous avez besoin d’un Mac distant accessible par SSH, VNC ou console web, avec des droits complets et une capacité de redémarrage indépendante. Pour une équipe qui veut standardiser son matériel de build plutôt que prolonger un nœud instable, vous pouvez aussi consulter les options de commande d’un Mac mini distant.

Louer n’est toutefois pas le meilleur choix pour une charge lourde permanente, un besoin de conservation à très long terme ou l’utilisation d’interfaces physiques particulières. Pour des tests temporaires, une extension de capacité, un nœud de secours ou une validation Xcode sans achat immédiat, VpsMesh peut offrir un environnement Mac plus simple à isoler, redémarrer et soumettre à cette procédure d’acceptation.