Migration Jenkins Java 21 : mise à niveau des nœuds Mac en 2026

Pourquoi l’ordre de migration détermine la continuité des builds

Le scénario d’échec le plus coûteux est souvent le suivant : le contrôleur est mis à niveau avec succès, mais les anciens Mac Agent ne parviennent plus à démarrer ou à négocier leur connexion. Le contrôleur paraît sain, tandis que les tâches restent en attente, que les étiquettes de nœuds ne trouvent plus de capacité et que les équipes iOS découvrent la panne au moment d’une livraison.

La difficulté vient du fait que quatre éléments différents sont souvent désignés sous le nom de « Java » :

• la JVM du contrôleur Jenkins ;
• la JVM du processus Agent sur le Mac ;
• le JDK utilisé par le projet compilé ;
• les outils Apple, notamment Xcode et xcodebuild.

Ces composants ne doivent pas être mis à niveau comme un bloc unique. Jenkins confirme que la JVM de l’agent et le JDK utilisé par une tâche de construction peuvent être gérés séparément. Cette distinction permet donc à un agent exécuté avec Java 21 de continuer à lancer un projet qui exige encore une version plus ancienne, à condition que le pipeline sélectionne explicitement cette version.

Trois coûts cachés doivent être intégrés à la préparation :

1. Le coût d’indisponibilité : un nœud qui reste en ligne dans Jenkins n’est pas nécessairement capable de lancer l’agent avec la JVM attendue.
2. Le coût d’attribution : une défaillance peut venir de la connexion Agent, d’un plugin, du JDK du projet, des droits macOS ou de la chaîne de signature.
3. Le coût de retour arrière : restaurer le contrôleur ne suffit pas si les paramètres de démarrage, les variables JAVA_HOME, les étiquettes et le routage des tâches ont déjà changé.

Les plugins doivent être contrôlés individuellement. La page du plugin Versions Node Monitors, par exemple, permet de surveiller la version Java déclarée par les nœuds ; elle ne remplace toutefois pas un essai de connexion et un build réel.

Première étape : établir l’inventaire avant la fenêtre de maintenance

Le jour du lancement, l’équipe plateforme doit figer un état lisible de l’environnement. L’inventaire ne doit pas se limiter à la version visible dans l’interface Jenkins : il doit également conserver le mode de démarrage de chaque agent, ses étiquettes et les tâches qui lui sont attribuées.

Pour chaque Mac, relevez :

• la version de macOS et l’architecture matérielle ;
• la version de Java utilisée par le processus Agent ;
• le chemin réel de l’exécutable Java ;
• le mode de connexion : SSH, agent lancé par service, lancement manuel ou autre mécanisme ;
• les étiquettes Jenkins et les tâches de publication associées ;
• la version de Xcode, les outils en ligne de commande, les certificats et l’accès au trousseau ;
• le répertoire de travail, les variables d’environnement et les paramètres de redémarrage.

La documentation Jenkins consacrée aux nœuds doit servir de référence pour contrôler la configuration déclarée dans le contrôleur. La commande locale suivante suffit pour confirmer le binaire réellement appelé, sans transformer la phase d’inventaire en audit inutilement large :

command -v java
java -version
echo "$JAVA_HOME"

Exemple de sortie à conserver dans le dossier de migration :

/Library/Java/JavaVirtualMachines/.../Contents/Home/bin/java
openjdk version "21" ...
JAVA_HOME=/Library/Java/JavaVirtualMachines/.../Contents/Home

Le chemin exact est plus important que la seule valeur affichée dans une interface. Un service macOS peut utiliser un environnement différent de celui d’une session interactive ; un JAVA_HOME correct dans le terminal ne prouve donc pas que le processus Agent l’utilise.

Faut-il mettre à niveau l’agent avant le contrôleur Jenkins ?
Oui, dans une migration vers Java 21 menée avec une contrainte de continuité. L’agent pilote doit être préparé et validé avant le changement du contrôleur, car cette séquence révèle les problèmes de chemin Java, de lancement, de permissions et de reconnexion alors que l’ancien chemin de production reste disponible.

Deuxième étape : préparer les plugins et la possibilité de revenir en arrière

Avant toute modification, l’équipe doit enregistrer la version du contrôleur, la liste des plugins et les dépendances critiques. Les plugins de pipeline, d’authentification, de gestion des identifiants et d’intégration avec les systèmes de dépôt méritent une vérification séparée, car une migration Java peut révéler une incompatibilité qui n’apparaît pas lors d’un simple redémarrage.

Le guide officiel de mise à niveau vers Jenkins 2.555 doit être rapproché de la version effectivement visée, et non d’une version supposée. Le dossier de retour arrière doit contenir :

• une sauvegarde cohérente de la configuration du contrôleur ;
• la liste des versions de plugins avant migration ;
• les paramètres de lancement de chaque Mac Agent ;
• les anciennes valeurs de JAVA_HOME ;
• les étiquettes et règles de routage ;
• un exemple de build réussi avant changement ;
• l’identité du responsable pouvant réactiver l’ancien chemin.

Le retour arrière ne désigne pas une seule opération. Il peut concerner le contrôleur, la JVM de l’agent, les plugins ou le routage des tâches. Une équipe qui ne précise pas cette séparation risque de restaurer le contrôleur tout en laissant les agents dans un état incompatible.

Pendant cette phase, il faut aussi définir un test de régression court : connexion de l’agent, exécution d’une tâche non destructive, redémarrage du Mac, reconnexion automatique et récupération des journaux. La documentation Jenkins sur l’utilisation des agents fournit le cadre général de connexion ; les détails du lancement sur macOS doivent être vérifiés dans l’environnement réel.

Troisième étape : installer Java 21 sur un Mac Agent isolé

Le premier Mac sélectionné ne doit pas être le seul nœud capable de signer une version de production. Il doit posséder une étiquette dédiée, ne recevoir aucune tâche critique par défaut et rester observable pendant toute la période d’essai.

Comment forcer un Mac Agent à utiliser Java 21 ?
Le chemin Java doit être défini dans le mécanisme qui lance effectivement l’agent, puis contrôlé dans les informations du nœud Jenkins. Selon le mode retenu, cela peut passer par JAVA_HOME, par le chemin absolu du binaire Java dans la commande de lancement ou par la configuration du service macOS. Il ne faut pas supposer qu’une installation de Java 21 modifie automatiquement le processus déjà actif.

Exemple minimal de vérification avant lancement :

export JAVA_HOME="/chemin/vers/JavaVirtualMachines/.../Contents/Home"
"$JAVA_HOME/bin/java" -version

Exemple de contrôle côté Jenkins :

Agent connecté
JVM détectée : Java 21
Étiquette : macos-java21-pilote

Le chemin affiché ici est un exemple de structure ; il doit être remplacé par le chemin présent sur le Mac concerné. Après le lancement, contrôlez successivement :

• l’enregistrement de l’agent ;
• l’exécution d’une tâche de diagnostic ;
• la déconnexion volontaire puis la reconnexion ;
• le redémarrage du Mac ;
• la reconnexion automatique après redémarrage ;
• la version JVM remontée par Jenkins.

Un Mac peut être « en ligne » tout en étant inutilisable pour une tâche donnée. Les permissions du compte de service, l’accès au trousseau, les dossiers de travail et les variables héritées doivent être testés avec le même compte que celui du véritable agent.

Quatrième étape : dissocier Java du projet et valider la chaîne Xcode

Un Agent exécuté avec Java 21 peut-il encore construire un ancien projet Java ?
Oui, si le pipeline sélectionne le JDK du projet indépendamment de la JVM de l’agent. Le changement à éviter consiste à remplacer globalement toutes les variables Java du Mac, puis à découvrir qu’un outil de compilation, un script ou une dépendance attend une version différente.

La séparation doit être visible dans la configuration :

• Java 21 sert au processus Agent ;
• le JDK du projet est choisi par l’outil Jenkins, une variable contrôlée ou le script de build ;
• Xcode est sélectionné explicitement pour les tâches Apple ;
• les scripts ne déduisent pas silencieusement leur version à partir du Java de l’agent.

La première vraie tâche doit reproduire le parcours d’une livraison, sans utiliser immédiatement les certificats de production. Elle doit inclure la récupération du code, la restauration des dépendances, la compilation, les tests et la génération d’un artefact de validation. Pour les outils Apple, la référence Apple sur les outils en ligne de commande Xcode aide à distinguer l’installation de Xcode de la sélection active des outils.

La séquence de validation doit également observer :

• le répertoire de travail réellement utilisé ;
• les droits d’accès au trousseau ;
• la présence des profils et certificats nécessaires ;
• l’état de xcode-select ;
• les journaux du plugin et du script ;
• la différence entre échec de connexion, échec Java, échec du projet et échec Apple.

La signature de production doit rester sur un nœud contrôlé pendant l’essai. Les règles Apple relatives à la création de code signé pour macOS rappellent que la signature constitue une étape distincte de la simple compilation. Pour un pipeline iOS, le test initial peut donc utiliser un artefact non distribué ou des identifiants non productifs, puis être promu après validation des permissions.

Cinquième étape : mettre à niveau le contrôleur et transférer les tâches par lots

Lorsque l’agent pilote a passé les contrôles, l’équipe peut planifier la fenêtre du contrôleur. La version cible, les plugins et la JVM du contrôleur doivent être traités selon le guide de mise à niveau Jenkins, tandis que les Mac non migrés doivent conserver une route explicite vers leur environnement antérieur.

La bascule doit suivre une progression observable :

1. mettre à niveau le contrôleur après validation du pilote ;
2. maintenir les étiquettes des nœuds non migrés ou suspendre leur routage ;
3. envoyer d’abord les tâches de compilation et de test sans publication ;
4. vérifier la reconnexion et les résultats ;
5. transférer ensuite les tâches d’archivage ;
6. ne déplacer les tâches de signature et de publication qu’après une nouvelle validation.

Le point essentiel est de ne pas confondre « contrôleur redémarré » avec « migration terminée ». Chaque lot doit être jugé sur un build réel, une reconnexion et la capacité à revenir à la route précédente. Une tâche qui s’exécute une seule fois ne démontre pas qu’un agent récupérera correctement après une interruption ou un redémarrage non interactif.

Pour approfondir la préparation opérationnelle, la liste de contrôle de mise en production d’un nœud Mac Jenkins peut compléter l’inventaire, notamment pour les règles de routage, les permissions et la surveillance des agents.

Sixième étape : organiser le retour arrière lorsqu’un nœud devient hors ligne

Que faire si un Mac Agent devient hors ligne après la mise à niveau Jenkins ?
Il faut d’abord isoler le nœud de la file de tâches, puis identifier la couche en cause avant de restaurer. Vérifiez le journal du service, le chemin Java utilisé par le processus et la version JVM déclarée dans Jenkins. Si le contrôleur est fonctionnel mais que l’agent ne démarre plus, la première action de retour consiste généralement à rétablir le chemin Java et les paramètres de lancement connus, sans modifier simultanément les plugins et la configuration du contrôleur.

Un ordre de diagnostic reproductible évite les restaurations aveugles :

ps aux | grep -i agent
command -v java
"$JAVA_HOME/bin/java" -version

Ensuite, contrôlez dans Jenkins si le nœud est simplement déconnecté, si le processus se termine immédiatement ou si la connexion est refusée. Les preuves à conserver sont le journal de lancement, l’heure de la dernière connexion, l’étiquette du nœud et le résultat de la dernière tâche.

Le retour arrière peut alors prendre l’une de ces formes :

• réactiver l’ancien agent sur un nœud non modifié ;
• restaurer le chemin Java précédent sur le pilote ;
• retirer temporairement l’étiquette Java 21 du routage ;
• restaurer la configuration du contrôleur si la régression vient de cette couche ;
• suspendre les publications jusqu’à ce que la signature et le trousseau soient validés.

La procédure officielle de gestion des nœuds Jenkins doit être utilisée pour désactiver proprement un nœud et éviter l’affectation de nouvelles tâches pendant l’analyse.

Septième étape : déployer plusieurs Mac Agent sans migration simultanée

Comment migrer plusieurs Mac Agent vers Java 21 sans créer une panne collective ?
Classez les nœuds par fonction et par risque, puis transférez-les progressivement en conservant au moins une route de secours non migrée tant que les tâches critiques n’ont pas été validées. Les Mac utilisés pour les tests et les builds ordinaires doivent précéder les nœuds de signature, de publication et de traitement audio ou vidéo.

Une politique de lots utile distingue :

• les agents de test non productifs ;
• les agents de compilation iOS ;
• les agents qui archivent les applications ;
• les agents qui signent ou publient ;
• les agents utilisés pour des workflows créatifs, audio, vidéo ou design.

Cette séparation est importante, car un changement de JVM peut être sans effet sur la compilation mais modifier le lancement d’un script, l’accès à un trousseau ou le comportement d’un service de session. Les tâches de design automatisé et de traitement vidéo doivent également être testées si elles utilisent des applications macOS ou des extensions qui ne fonctionnent pas comme un simple appel xcodebuild.

Pendant la première période d’exploitation, catégorisez chaque incident : agent hors ligne, reconnexion absente, plugin, JDK du projet, Xcode, permission, trousseau ou artefact. Une augmentation apparente des échecs ne peut pas être attribuée à Java 21 sans cette classification.

La capacité de secours doit être décidée avant la fenêtre. Si l’entreprise ne possède aucun Mac isolable et que le seul nœud disponible signe les versions de production, l’ajout temporaire d’un Mac distant peut être plus prudent qu’une modification sur place. Une architecture de haute disponibilité et de retour arrière pour serveur de build Mac aide à examiner cette option sans mélanger la migration logicielle avec l’achat immédiat d’un parc permanent.

Grille de décision avant le transfert de production

La grille suivante transforme la préparation en autorisation explicite. Un seul élément critique non validé doit maintenir le nœud dans le pilote ou dans l’ancien groupe de routage.

• [ ] Le contrôleur, les plugins critiques et les chemins de restauration sont documentés.
• [ ] Chaque Mac possède une version Java Agent vérifiée avec java -version.
• [ ] Le processus Agent utilise explicitement Java 21 et non une valeur héritée d’une session interactive.
• [ ] Le nœud pilote se reconnecte après une déconnexion et après un redémarrage du Mac.
• [ ] Le JDK du projet est sélectionné séparément de la JVM de l’agent.
• [ ] Une tâche réelle couvre récupération, dépendances, build, tests et artefact.
• [ ] Xcode, les outils en ligne de commande, le trousseau et les permissions ont été contrôlés.
• [ ] Les tâches de signature utilisent une route contrôlée et des identifiants adaptés à la phase de test.
• [ ] Les étiquettes empêchent l’envoi d’une tâche vers un agent non migré de façon involontaire.
• [ ] Un opérateur sait rétablir l’ancien chemin sans restaurer toute la plateforme.
• [ ] Un Mac de secours ou une capacité temporaire existe si le nœud de production ne peut pas être arrêté.

Comparer les états de migration et le risque opérationnel

Jenkins précise la nouvelle exigence de Java pour le contrôleur et les agents à partir de LTS 2.555.1 dans sa documentation de support ; le tableau ne doit donc pas être interprété comme une garantie de compatibilité de chaque plugin. Cette compatibilité doit être confirmée dans les pages de plugins et dans les essais de l’entreprise.

Choisir entre modification immédiate et Mac de capacité temporaire

Pour une capacité temporaire, NodeMini peut être évalué comme fournisseur d’un nœud Mac distant séparé de la production, à condition de confirmer avant commande les accès, la période nécessaire, les contraintes de signature et la compatibilité de la chaîne Xcode. La location ne remplace pas une politique de sauvegarde ni une validation de sécurité ; elle fournit surtout une machine indépendante lorsque le parc actuel ne permet pas de tester sans toucher à la production.

Après la migration : établir une base de référence durable

La fin de la fenêtre ne doit pas être déclarée après le premier build vert. Durant la première semaine d’exploitation, l’équipe doit suivre les déconnexions, les reconnexions, les redémarrages sans session interactive, les erreurs de plugins, les échecs Xcode et les écarts entre les différents Mac Agent. Ces conclusions doivent rester factuelles : aucune amélioration de performance, de délai de récupération ou de taux d’échec ne doit être annoncée sans mesure interne documentée.

Le résultat attendu est une base de référence versionnée qui associe :

• la JVM de l’agent et son chemin de démarrage ;
• le JDK de chaque famille de projets ;
• la version Xcode et la sélection des outils ;
• les plugins validés ;
• les étiquettes et règles de routage ;
• les droits du compte de service ;
• le comportement après redémarrage ;
• la procédure de retour arrière.

Les équipes qui prévoient aussi l’évaluation de la SLA et des capacités de récupération d’un Mac distant doivent demander des preuves adaptées à leur chaîne Jenkins : accès administrateur, redémarrage, récupération, isolement des identifiants et possibilité de retirer le nœud du routage. Une capacité distante n’est pertinente que si elle s’intègre au plan de reprise réel.

L’ancienne approche — mettre à niveau le contrôleur unique, conserver des Mac Agent sous une JVM non vérifiée et espérer que Xcode continuera de signer — cumule trois défauts : elle concentre le risque sur la production, rend le diagnostic ambigu entre Jenkins et macOS, et ne laisse aucune machine disponible pour un retour arrière propre. Pour une équipe qui ne peut pas interrompre son seul Mac de publication, louer temporairement un Mac avec NodeMini peut donc offrir une meilleure marge de test et de récupération qu’une modification directe du nœud critique. La décision reste conditionnée par la validation des accès, des permissions et de la chaîne Xcode ; si les builds sont permanents et lourdement sollicités, l’achat d’une infrastructure dédiée peut demeurer plus rationnel à long terme.