Jenkins-Java-21-Migration: Mac-Knoten 2026 aktualisieren

Zielgruppe und Wochenplan

Diese Anleitung richtet sich an Plattformteams, die noch Jenkins-Controller oder Mac Agent mit Java 17 betreiben. Sie ist für IT-Verantwortliche gedacht, die ein Jenkins-LTS-Upgrade ohne Unterbrechung der iOS-Auslieferung planen.

Auch Infrastrukturverantwortliche ohne Reserve-Mac, isolierte Testumgebung oder verlässliche Fernwartung sollten den Ablauf lesen: Fehlt eine dieser Rückfallebenen, ist ein direktes Upgrade des einzigen Produktionsknotens kein belastbarer Plan.

Diese Woche sollte das Team den aktuellen Controller, alle Plugins, Mac Agents, Startmethoden, Java-Versionen, Labels und Produktionsabhängigkeiten erfassen. Danach wird ein einzelner Mac für den Pilotbetrieb aus dem normalen Job-Routing genommen. Die offizielle Java-Support-Policy von Jenkins dient als Entscheidungsgrundlage, nicht der bloße Status „online“ im Jenkins-UI.

Migrationsstart mit Bestandsaufnahme

Seit Jenkins LTS 2.555.1 müssen Controller-JVM und Agent-JVM laut der im Projekt festgelegten Support-Grenze Java 21 oder Java 25 verwenden. Daraus folgt nicht, dass jedes Projekt ebenfalls auf Java 21 umgestellt werden muss. Jenkins unterscheidet die Laufzeit des Controllers, die Laufzeit eines Agents und das JDK, mit dem ein Build kompiliert wird.

Für jeden Bestandteil sollte eine eigene Zeile im Migrationsprotokoll stehen:

• Controller-Version und aktuell verwendete JVM;
• Ziel-LTS und geplanter Upgrade-Pfad;
• Plugin-Versionen, insbesondere Pipeline-, Authentifizierungs-, Credential- und Knotenverwaltungs-Plugins;
• Mac Agent mit Hostname, Label, Betriebssystem, CPU-Architektur und Startmethode;
• Java-Version und exakter Java-Pfad des Agent-Prozesses;
• separat ausgewähltes Projekt-JDK;
• Xcode-Version, Command-Line-Tools, Keychain-Zugriff und Signaturrolle;
• Jobs, die nur auf einem bestimmten Knoten oder einer bestimmten Architektur laufen.

Der Unterschied zwischen „Java ist auf dem Mac installiert“ und „der Agent verwendet Java 21“ ist wesentlich. Ein LaunchDaemon, SSH-Start oder ein eigenes Shell-Skript kann einen anderen PATH erhalten als eine interaktive Sitzung. Deshalb muss die effektive Laufzeit im Agent-Prozess und nicht nur mit einem Terminalbefehl geprüft werden.

Für die Knotenverwaltung sollten Labels, Executors, Umgebungsvariablen und Startparameter exportiert oder zumindest revisionssicher dokumentiert werden. Jenkins beschreibt in der offiziellen Dokumentation zur Knotenverwaltung, welche Eigenschaften für die Verwaltung und Zuordnung von Agents relevant sind.

Upgrade-Baseline vor dem Wartungsfenster

Vor jeder Änderung braucht das Team einen Zustand, der wiederhergestellt werden kann. Dazu gehören die Controller-Konfiguration, Plugin-Liste, Credentials-Referenzen, Job-Routing, Agent-Labels und die bisherige Java-Startdefinition. Geheimnisse selbst gehören nicht in ein unverschlüsseltes Protokoll; dokumentiert werden sollten nur Name, Zweck, Zugriffspfad und Wiederherstellungsverantwortung.

Die Rückfallplanung wird in drei unabhängige Ebenen geteilt:

1. Controller: vorherige Jenkins-LTS, Konfigurationssicherung und kontrollierter Start;
2. Agent: bisheriger Java-Pfad, Startparameter, Dienstdefinition und Zugangsmethode;
3. Routing: Labels oder Queue-Regeln, mit denen Jobs auf nicht migrierte Knoten gelenkt werden.

Diese Trennung verhindert, dass bei einem Fehler gleichzeitig Controller, Agent-Laufzeit und Produktionsrouting geändert werden. Der Jenkins Upgrade Guide für die 2.555-Linie sollte unmittelbar vor der Planung auf Hinweise zu Zielversion, Java-Anforderung und bekannten Änderungen geprüft werden.

Die Pluginprüfung darf nicht auf Kern-Plugins beschränkt bleiben. Ein Agent kann sich verbinden, während ein Pipeline-Schritt, ein Credential-Binding oder ein Knotenmonitor nach dem Upgrade fehlschlägt. Für Versionserkennung und Knoteninformationen kann zusätzlich die Dokumentation des Versions Node Monitors herangezogen werden. Eine erfolgreiche Pluginauflösung ist jedoch kein Ersatz für eine reale Pipeline.

Isolierter Mac Agent als Pilot

Der erste Mac Agent wird aus produktiven Signatur- und Release-Routen entfernt, erhält aber dieselben relevanten Systembedingungen wie ein späterer Produktionsknoten. Ein künstlich vereinfachter Test mit einem leeren Job liefert keine ausreichende Aussage über Xcode, Credentials, Arbeitsverzeichnisse oder Neustartverhalten.

Der Pilot läuft in dieser Reihenfolge:

1. Unterstützte Java-21-Laufzeit auf dem Mac installieren und den exakten Installationspfad festhalten.
2. Agent-Startdefinition so ändern, dass JAVA_HOME oder der direkte Java-Pfad eindeutig auf Java 21 zeigt.
3. Agent neu starten und im Jenkins-System sowie in der Prozessumgebung die tatsächlich verwendete JVM prüfen.
4. Verbindung trennen und wiederherstellen, ohne die Knotenidentität oder Labels zu verändern.
5. Mac kontrolliert neu starten und prüfen, ob der Agent automatisch wieder online kommt.
6. Einen nicht veröffentlichenden, aber repräsentativen Xcode-Job ausführen.
7. Ergebnis, Logauszüge, Wiederverbindungszeit und Fehlerursache im Migrationsprotokoll festhalten.

Ein minimales Prüfkommando kann dabei helfen, die Laufzeit am vorgesehenen Pfad sichtbar zu machen:

"$JAVA_HOME/bin/java" -version

Beispiel einer erwarteten Form der Ausgabe:

openjdk version "21.x"

Die konkrete Patch-Version und Distribution müssen aus der freigegebenen Unternehmensinstallation stammen. Das Beispiel ist kein Nachweis für eine bestimmte Distribution oder Plugin-Kompatibilität.

Für die Agent-Kommunikation gelten zusätzlich die Jenkins-Vorgaben zur Verwendung von Agents. Wichtig ist die Überprüfung des laufenden Prozesses: Eine Shell kann Java 21 melden, während der als Dienst gestartete Agent weiterhin eine ältere Laufzeit verwendet.

Projekt-JDK und Agent-JVM getrennt halten

Die häufigste Fehlkonfiguration besteht darin, die Java-21-Anforderung des Agents mit einer Modernisierung aller Java-Builds gleichzusetzen. Ein Projekt kann weiterhin ein älteres JDK benötigen, etwa wegen Compiler-Kompatibilität, Gradle- oder Maven-Einstellungen oder einer noch nicht geprüften Abhängigkeit.

Die sichere Trennung sieht so aus:

• Agent-JVM: startet den Jenkins Agent und hält die Verbindung zum Controller;
• Projekt-JDK: wird über Jenkins Tool-Konfiguration, ein kontrolliertes Environment oder das Build-Skript ausgewählt;
• Xcode-Toolchain: liefert Compiler, Simulator- und Signaturwerkzeuge für Apple-Plattformen;
• Shell-Umgebung: muss pro Job nachvollziehbar sein und darf nicht ungeprüft global überschrieben werden.

Im Log sollte der Build deshalb die verwendete Java-Laufzeit und die Xcode-Werkzeuge getrennt ausweisen. Der Teamverantwortliche kann dann erkennen, ob ein Fehler bei der Agent-Verbindung, beim Projekt-JDK oder bei Xcode entstanden ist.

Für Xcode-Aufgaben gehören mindestens Quellcodeabruf, Dependency-Wiederherstellung, Build, Tests und ein kontrollierter Artefakt-Upload in die Prüfkette. Die verfügbaren Command-Line-Tools und ihre Aufrufbedingungen sind in der Apple-Referenz zu Xcode Command Line Tools beschrieben.

Produktive Signaturen bleiben während des Piloten auf einem kontrollierten Knoten. Für die erste Runde eignen sich nichtproduktive Credentials, ein schreibgeschützter Validierungslauf oder ein Build ohne Veröffentlichung. Das reduziert nicht automatisch jedes Risiko: Keychain-Rechte, Benutzerkontext, Arbeitsverzeichnis und Entsperrungszustand müssen trotzdem realitätsnah geprüft werden. Die Anforderungen an signierten Code sind in Apples Dokumentation zur Code-Signierung nachzulesen.

Controller-Upgrade und gestaffelte Umschaltung

Erst wenn der Pilot-Agent wieder verbunden war, einen Mac-Neustart überstanden hat und eine repräsentative Xcode-Pipeline erfolgreich durchlief, beginnt das Controller-Fenster. Vorher werden die Ziel-LTS, die Plugin-Liste und die Java-Anforderung nochmals gegen den aktuellen Jenkins-Upgrade Guide abgeglichen.

Während des Fensters wird eine Doppelspur eingerichtet:

• nicht migrierte Agents behalten ein klar erkennbares Label;
• produktive Jobs werden zunächst nicht automatisch auf alle Knoten verteilt;
• nicht veröffentlichende Jobs werden zuerst auf die geprüfte Java-21-Gruppe gelenkt;
• Archivierungs-, Signatur- und Release-Jobs folgen erst nach zusätzlicher Kontrolle;
• ein einzelner Fehler stoppt die nächste Welle, statt sofort die gesamte Flotte umzustellen.

Die Route sollte nicht nur anhand des Online-Status bewertet werden. Ein Agent kann online erscheinen, aber beim ersten Neustart, beim Zugriff auf eine Credential-Datei oder bei der Xcode-Ausführung ausfallen. Nach jeder Welle werden deshalb mindestens Verbindung, realer Build, Wiederverbindung und Rückfallpfad geprüft.

Ein Rückfall bedeutet nicht automatisch, den gesamten Controller zurückzustufen. Wenn nur ein Agent mit der neuen Laufzeit nicht startet, wird zunächst dieser Knoten aus dem Routing genommen und mit der dokumentierten alten Startdefinition wiederhergestellt. Wenn ein Plugin- oder Controllerfehler vorliegt, wird anhand der Baseline entschieden, ob eine kontrollierte Controller-Wiederherstellung erforderlich ist.

Erste Betriebswoche und Abnahmekriterien

In der ersten Woche wird aus dem erfolgreichen Pilot kein allgemeines Versprechen, sondern eine verbindliche Knoten-Baseline. Für jeden freigegebenen Mac Agent werden Java-Pfad, Agent-Startmethode, Labels, Xcode-Umgebung, Projekt-JDK-Auswahl und Neustartverhalten festgehalten.

Die folgende Liste ist als Freigabewerkzeug gedacht:

• [ ] Controller-Version, Ziel-LTS und JVM-Version sind dokumentiert.
• [ ] Jeder Mac Agent besitzt einen bekannten Java-Pfad und eine bekannte Startmethode.
• [ ] Agent-JVM und Projekt-JDK sind in Konfiguration und Build-Log getrennt erkennbar.
• [ ] Kern-, Pipeline-, Authentifizierungs- und Credential-Plugins wurden gegen die Zielversion geprüft.
• [ ] Ein isolierter Mac Agent verbindet sich mit Java 21 und bleibt nach einem kontrollierten Neustart erreichbar.
• [ ] Eine echte Xcode-Pipeline durchläuft Abruf, Abhängigkeiten, Build und Tests.
• [ ] Signatur- und Keychain-Zugriffe sind auf kontrollierten Knoten verifiziert.
• [ ] Für jeden migrierten Knoten existieren Labels für Umschaltung und Rückfall.
• [ ] Ein nicht migrierter Knoten oder eine andere Wiederherstellungsoption ist tatsächlich verfügbar.
• [ ] Die erste Produktionswelle wurde nach einem erfolgreichen Testlauf ausdrücklich freigegeben.
• [ ] Offline-, Reconnect-, Plugin- und Build-Fehler werden getrennt klassifiziert.

Fehlt ein isolierter Pilot oder eine nutzbare Rückfallkapazität, sollte das Team nicht auf dem einzigen Produktions-Mac experimentieren. Ein zusätzlicher, zeitweise gemieteter Mac kann in diesem Fall als separate Grauzone dienen. Die Entscheidung hängt nicht nur von der Java-Version ab, sondern davon, ob ein fehlerhafter Agent aus dem Produktionsrouting entfernt werden kann, ohne die Veröffentlichung zu blockieren.

Für die organisatorische Vorbereitung kann das Team die vorhandene Mac-Bestellübersicht für Unternehmen als Ausgangspunkt für die Bewertung zusätzlicher Mac-Kapazität heranziehen. Für die technische Freigabe bleiben jedoch die Jenkins- und Apple-Quellen sowie die eigenen Testprotokolle maßgeblich.

Optionen für Pilot und Rückfall

Die Tabelle ersetzt keine Kapazitätsprüfung. Ein zusätzlicher Knoten hilft nur, wenn Labels, Credentials, Arbeitsverzeichnisse und Xcode-Toolchain reproduzierbar eingerichtet werden können. Für eine längerfristige Entscheidung sollten außerdem DSGVO-Anforderungen, Datenaufbewahrung, Zugriff aus dem Unternehmensnetz und die vertragliche Wiederherstellung geprüft werden.

Wenn der Jenkins-Knoten bereits produktiv betrieben wird, sollte die Mac-Kapazität für einen kontrollierten Test getrennt von der späteren Dauerarchitektur bewertet werden. Eine temporäre Umgebung ist vor allem dann sinnvoll, wenn sie nicht vorschnell als Ersatz für eine dauerhaft benötigte Hochlast-Infrastruktur eingeplant wird.

Häufige Fehlentscheidungen

Ein Controller-Upgrade vor dem Agent-Test ist die riskanteste Abkürzung. Selbst wenn Jenkins startet, können ältere Agents die Verbindung verlieren oder beim erneuten Start eine nicht unterstützte JVM verwenden.

Ebenso problematisch ist eine globale Änderung von JAVA_HOME für alle Jobs. Dadurch kann ein Projekt unbemerkt mit Java 21 kompiliert werden, obwohl nur die Agent-Kommunikation migriert werden sollte. Die Build-Konfiguration muss deshalb den Projekt-JDK-Pfad ausdrücklich setzen.

Ein weiterer Fehler ist der Test mit einem trivialen Job. Er bestätigt weder Keychain-Berechtigungen noch Xcode-Abhängigkeiten, Codesignierung, Artefakt-Upload oder Neustartverhalten. Für die Freigabe zählt mindestens ein repräsentativer Ablauf mit nachvollziehbarer Fehlerzuordnung.

Schließlich ist „online“ kein Stabilitätsnachweis. Erst wiederholte Verbindungen, ein kontrollierter Host-Neustart und mehrere Routing-Wellen zeigen, ob die Migration unter den Bedingungen des unbeaufsichtigten Betriebs tragfähig ist.

FAQ zur Jenkins-Java-21-Migration

Die wichtigsten Sonderfälle sind: Agent zuerst testen, Java 21 im Dienstpfad explizit setzen, Projekt-JDK unabhängig halten, Rückfallobjekte getrennt sichern und Mac Agents in kleinen Wellen umschalten. Die ausführlichen Antworten stehen in den ausklappbaren FAQ-Daten dieser Seite.

Die bestehende Lösung ohne zusätzliche Reserve hat vier typische Nachteile: Ein einziger produktiver Mac lässt keinen sicheren Pilotbetrieb zu, ein Controller-Upgrade kann mehrere Jobs gleichzeitig blockieren, die Wiederherstellung hängt von manueller Fernwartung ab und die Xcode-Signaturpipeline besitzt keine Ausweichroute. Wenn die Hardware nicht kurzfristig erweitert werden kann, kann NodeMini für einen zeitlich begrenzten, unabhängigen Mac Agent als Java-21-Grauzone geprüft werden. Erst nach erfolgreicher Migration sollte entschieden werden, ob eine dauerhafte eigene Beschaffung oder eine längerfristige Mietkapazität wirtschaftlich und organisatorisch besser passt.