Jenkins macOS Agent offline: Remote-Knoten 2026 prüfen

Jenkins dokumentiert für Inbound Agents den TCP-Port 50000 als Standardwert, sofern dieser Dienst aktiviert und nicht anders konfiguriert ist (Jenkins-Dokumentation zu Diensten und Ports). Wenn Ihr Jenkins macOS Agent offline erscheint, obwohl SSH noch funktioniert, sollten Sie deshalb nicht sofort den Knoten neu installieren. Prüfen Sie die Fehlerkette in dieser Reihenfolge: Jenkins-Disposition und Queue, Verbindungskanal, Java-Agent-Prozess, macOS-Sitzung und anschließend Arbeitsumgebung und Xcode. Ein einmaliger Prozessfehler lässt sich meist reparieren. Bei wiederholten Abbrüchen oder ständig driftender Umgebung ist Isolation mit anschließendem Neuaufbau oder ein zusätzlicher Remote Mac die belastbarere Entscheidung.

Für Sie ist dieser Artikel gedacht, wenn Sie Jenkins- und Remote-Mac-Buildknoten im täglichen Betrieb betreuen und die Wiederherstellungszeit verkürzen müssen. Er richtet sich außerdem an Entwickler für Xcode-Automatisierung sowie Plattformverantwortliche, die einen dauerhaft verfügbaren macOS-CI-Knoten sauber abnehmen wollen.

Fehlergrenze vor der Reparatur

„Offline“ beschreibt in Jenkins nicht jede Ursache eines fehlgeschlagenen Builds. Trennen Sie zunächst drei Zustände:

Der Knoten ist tatsächlich nicht verbunden.
Der Knoten ist online, erhält aber wegen Queue-, Label- oder Executor-Regeln keinen Auftrag.
Der Auftrag startet, scheitert jedoch an Workspace, Xcode, Berechtigungen oder Signierungsressourcen.

Öffnen Sie zuerst die Knotenseite im Controller und sichern Sie den Zeitpunkt der letzten erfolgreichen Ausführung. Notieren Sie die genaue Fehlermeldung, den Namen des Knotens, das verwendete Label und die konfigurierte Launch Method. Verwenden Sie für Hostnamen, Benutzer, Secrets und Schlüssel nur Platzhalter wie <CONTROLLER_HOST>, <AGENT_USER> und <AGENT_SECRET> in Ihrer Dokumentation.

Danach vergleichen Sie drei Quellen:

Controller-Log und Ereigniszeitpunkt.
Jenkins-Agent-Log auf dem Mac.
Prozess- und Systemstatus des Remote Mac.

Ein explizit durch einen Administrator stillgelegter Knoten ist anders zu behandeln als ein verlorener Handshake. Ebenso ist eine leere Queue mit einem falschen Label kein Verbindungsproblem. Die Jenkins-Dokumentation zu Knoten, Executors und Agent-Verbindungen beschreibt diese Trennung und sollte bei der Interpretation der Statusanzeige die Referenz bleiben.

Typische Fehlersignale

Beobachtung	Wahrscheinlichere Grenze	Erster Nachweis
SSH funktioniert, Jenkins bleibt offline	Jenkins-Transport, Secret, Java-Prozess oder Controller-Adresse	Launch Method, Agent-Log und Prozessliste
Knoten ist online, Auftrag bleibt in der Queue	Label, Executor, Knotenmodus oder fehlende Ressource	Queue-Grund und Label-Match
Auftrag startet, aber Xcode-Befehl scheitert	Benutzerkontext, Toolchain, Workspace oder Signierung	Xcode-Pfad und Build-Log
Nach Neustart bleibt der Knoten offline	Startkontext, launchd-Konfiguration oder Berechtigung	launchd- und Agent-Protokolle

Die häufigste Fehlentscheidung ist der sofortige Neuaufbau. Er löscht dabei oft die Beweise: den letzten Exit-Code, den alten Workspace-Zustand, die ursprüngliche Java-Umgebung und den Zeitpunkt des Netzwerkabbruchs.

Verbindungskanäle und Netzwerkpfad

SSH ist nicht automatisch die Jenkins-Verbindung. Bei einer SSH-Launch-Method verbindet sich der Controller per SSH zum Mac und startet dort den Agent-Prozess. Bei einem Inbound Agent baut der Agent die Verbindung zum Controller auf. WebSocket verwendet wiederum einen anderen Transportpfad. Die Jenkins-Anleitung zu Agents ist deshalb für die konkrete Launch Method maßgeblich.

Prüfen Sie den Pfad in dieser Reihenfolge:

Ermitteln Sie, welche Controller-Adresse in der Knotenkonfiguration steht. Nach einem Controller-Umzug kann DNS weiterhin auf den alten Host zeigen.
Prüfen Sie die Namensauflösung aus der Perspektive des Remote Mac. Ein DNS-Test vom eigenen Arbeitsplatz beweist nicht, dass der Buildknoten denselben Resolver verwendet.
Kontrollieren Sie Proxy, Firewall und ausgehende Regeln. Für einen Inbound Agent ist besonders relevant, ob der konfigurierte TCP-Agent-Listener tatsächlich erreichbar ist. Der in Jenkins dokumentierte Standardwert 50000 gilt nicht, wenn Ihre Installation einen anderen Port festlegt oder den Listener deaktiviert.
Überprüfen Sie Zertifikate und die Controller-URL, wenn WebSocket oder HTTPS eingesetzt wird.
Lesen Sie den Agent-Log auf Verbindungsabbruch, Authentifizierungsfehler, TLS-Fehler und Timeout. Schreiben Sie nicht nur „offline“ in das Ticket.

Verwechseln Sie drei Dinge nicht: den SSH-Dienst des macOS-Systems, den SSH-Dienst des Jenkins-Controllers und den Jenkins-Agent-Transport. Apple beschreibt Remote Login auf dem Mac als Systemdienst für entfernte Anmeldungen. Das bestätigt nicht, dass der Jenkins-Agent-Kanal funktioniert.

Nach einer Korrektur brauchen Sie mehr als eine erfolgreiche Anmeldung. Beobachten Sie den stabilen Handshake, die fortlaufende Verbindung und eine Wiederanmeldung nach einem kontrollierten Controller-Neustart. Wenn nur der erste Start funktioniert, ist die Ursache noch nicht behoben.

Java-Prozess und Agent-Start

Ein Jenkins Agent kann offline werden, obwohl die Netzwerkverbindung intakt ist, wenn der lokale Java-Prozess beendet wurde. Melden Sie sich mit dem vorgesehenen Agent-Benutzer an und prüfen Sie den Prozesskontext:

ps aux | grep -i '[j]ava'

Suchen Sie im Agent-Log nach Exit-Code, Standardfehler und dem vollständigen Startaufruf. Achten Sie besonders auf:

eine nicht mehr passende agent.jar;
einen ungültigen oder veralteten Startparameter;
ein geändertes Secret;
einen falschen Benutzer oder ein nicht lesbares Arbeitsverzeichnis;
einen vom System beendeten Prozess;
eine Java-Laufzeit, die von der aktuellen Jenkins-Version nicht unterstützt wird.

Die zulässige Java-Laufzeit ist keine Konstante, die Sie aus einem alten Runbook übernehmen sollten. Prüfen Sie vor jeder Änderung die aktuelle Jenkins Java Support Policy. Das gilt besonders nach einem Jenkins-LTS-Upgrade. Installieren Sie nicht einfach eine zweite Java-Version und ändern Sie global den Pfad. Ermitteln Sie zuerst, welche Laufzeit der Agent tatsächlich verwendet:

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

Wenn der Prozess nicht läuft, starten Sie ihn zunächst einmal kontrolliert mit den in der Knotenkonfiguration dokumentierten Parametern. Secret, Hostname und Benutzer bleiben Platzhalter. Kopieren Sie keine Zugangsdaten in Logs oder Tickets. Wenn der manuelle Start funktioniert, der Prozess aber nach Abmeldung verschwindet, liegt der nächste Fehlerbereich im macOS-Sitzungskontext und nicht bei Java.

Reparatur oder Isolation

Befund	Reparatur am bestehenden Knoten	Isolation und Neuaufbau
Einmaliger Java-Abbruch, Umgebung unverändert	Prozess kontrolliert starten und Ursache dokumentieren	Noch nicht erforderlich
Secret oder Controller-Adresse geändert	Knotenkonfiguration und sicheren Startpfad aktualisieren	Sinnvoll, wenn mehrere Parameter unklar sind
Wiederholter Exit ohne stabile Ursache	Nicht durch weitere Startskripte kaschieren	Knoten aus der Produktion nehmen
Java- oder Toolchain-Drift nach mehreren Änderungen	Nur mit dokumentierter Zielumgebung korrigieren	Sauberen Referenzknoten aufbauen
Signierungszustand oder Benutzerkontext unklar	Produktionsaufträge pausieren	Separaten macOS-CI-Knoten verwenden

Ein stabiler Jenkins Agent braucht einen nachvollziehbaren Startpfad. Wenn niemand sagen kann, welcher Benutzer, welche Java-Laufzeit und welche Umgebungsvariablen verwendet werden, ist der Knoten bereits ein Wartungsrisiko.

macOS-Sitzung und dauerhafter Start

Ein über SSH gestarteter Prozess beweist nicht, dass der Agent nach Abmeldung, VNC-Trennung oder einem Neustart weiterläuft. macOS unterscheidet Benutzer- und Systemkontext. Dateirechte, Schlüsselbundzugriff, Umgebungsvariablen und der Zeitpunkt des Starts können sich dadurch ändern.

Prüfen Sie zuerst, welchem Benutzer der Jenkins Agent gehört:

ps -o user,pid,ppid,command -ax | grep -i '[j]ava'

Kontrollieren Sie anschließend das Arbeitsverzeichnis und die Berechtigungen:

ls -ld <AGENT_ROOT>
ls -la <AGENT_ROOT>

Die automatische Startmechanik muss zur tatsächlichen Bereitstellung passen. Prüfen Sie deshalb die vorhandenen launchd-Einträge und deren Protokolle, statt ein allgemeines plist-Muster in die Umgebung zu kopieren. Ein nicht verifiziertes Template kann den falschen Benutzer, den falschen Pfad oder eine ungeeignete Session voraussetzen.

Führen Sie danach diese Tests getrennt aus:

Agent manuell starten und Verbindung im Controller beobachten.
SSH-Sitzung beenden und prüfen, ob der Agent unabhängig weiterläuft.
VNC- oder Websitzung trennen, ohne den Prozess manuell neu zu starten.
Mac kontrolliert neu starten.
Nach dem Neustart prüfen, ob der erwartete Benutzer, das Arbeitsverzeichnis und der Agent-Prozess vorhanden sind.
Einen kleinen Jenkins-Auftrag ohne interaktive Eingabe ausführen.

Wenn ein Signierungsprozess einen entsperrten Schlüsselbund oder eine grafische Sitzung erwartet, behandeln Sie das als eigene Produktionsvoraussetzung. Ein dauerhaft laufender Agent ist nicht automatisch ein sicherer Signierungsagent. Trennen Sie Build-, Test- und Signierungsrechte, und dokumentieren Sie, welche Geheimnisse der Prozessbenutzer lesen darf.

Online-Status und Xcode-Arbeitsumgebung

Ein grüner Online-Status bedeutet nur, dass Jenkins den Knoten als verbunden betrachtet. Der Knoten kann trotzdem keine Xcode-Aufträge ausführen. Prüfen Sie deshalb Remote Root Directory, freien Speicher, Workspace-Rechte, Labels und Executors, bevor Sie die Toolchain untersuchen.

Ein häufiger Fall sieht so aus: Der Knoten ist online, ein Auftrag mit dem Label macos-signing bleibt jedoch in der Queue. Die Ursache kann ein fehlendes Label, ein belegter Executor oder ein Knotenmodus sein, der keine neuen Aufgaben annimmt. Lesen Sie den Queue-Grund vollständig. „Agent online“ ist keine Aussage darüber, ob die Ressourcenanforderung des Auftrags erfüllt wird.

Im Agent-Kontext prüfen Sie die Xcode-Auswahl und die Command-Line-Tools:

xcode-select --print-path
xcodebuild -version

Die Apple-Dokumentation zur Konfiguration der Command-Line-Tools beschreibt, wie die aktive Auswahl ermittelt und geändert wird. Für einen neuen oder zurückgesetzten Knoten kann außerdem eine Initialisierung fehlen; die offiziellen Hinweise zur Installation der Xcode Command-Line-Tools sind dafür die belastbare Referenz.

Prüfen Sie die Variablen nicht in Ihrer interaktiven SSH-Shell, sondern in einem Jenkins-Auftrag. PATH, HOME, DEVELOPER_DIR und Schlüsselbundzugriff können dort anders aussehen. Ein diagnostischer Auftrag sollte mindestens Folgendes protokollieren, ohne Geheimnisse auszugeben:

id
pwd
echo "$HOME"
xcode-select --print-path
xcodebuild -version
df -h

Für die Abnahme benötigen Sie drei getrennte Minimalaufträge:

Kompilierung: Das Projekt wird mit der vorgesehenen Xcode-Auswahl gebaut.
Test: Ein reproduzierbarer Testlauf erzeugt ein auswertbares Ergebnis. Apple erklärt die Auswertung von Xcode-Testresultaten.
Signierung: Ein nicht veröffentlichtes Testartefakt wird mit den vorgesehenen Profilen und Zertifikaten signiert. Die Apple-Anleitung für signierten Code grenzt diesen Schritt von einem bloßen Shell-Erfolg ab.

Ein echo OK im Workspace ist daher kein Xcode-CI-Nachweis. Erst wenn alle drei Ebenen im selben Agent-Benutzerkontext funktionieren, ist der Knoten für produktive Apple-Plattform-Aufträge plausibel einsatzbereit.

Abnahme-Checkliste für den Remote Mac

Verwenden Sie diese Liste nach jeder Reparatur. Ein nicht erfüllter Punkt bleibt ein offener Fehler, auch wenn das Jenkins-Symbol wieder grün ist.

[ ] Controller-Adresse, Launch Method und Knotenlabel sind dokumentiert.
[ ] Der tatsächliche Jenkins-Agent-Prozess läuft unter dem vorgesehenen Benutzer.
[ ] Java-Version und Java-Pfad entsprechen der aktuell geprüften Jenkins-Unterstützung.
[ ] Agent-Log und Controller-Log zeigen keinen neuen Verbindungs- oder Authentifizierungsfehler.
[ ] Remote Root Directory ist vorhanden und für den Agent-Benutzer beschreibbar.
[ ] Ein Auftrag mit dem vorgesehenen Label wird nicht nur angenommen, sondern gestartet.
[ ] xcode-select --print-path zeigt die erwartete Toolchain.
[ ] Ein echter Kompilierungslauf endet erfolgreich.
[ ] Ein Testlauf erzeugt verwertbare Testresultate.
[ ] Ein isolierter Signierungstest nutzt den korrekten Benutzer- und Schlüsselbundkontext.
[ ] Abmeldung, VNC-Trennung und Mac-Neustart wurden ohne manuelles Nachstarten geprüft.
[ ] Eine kurze Netzwerkunterbrechung und ein Controller-Neustart wurden dokumentiert.
[ ] Secrets und private Schlüssel erscheinen nicht in Konsolen- oder Agent-Logs.
[ ] Bei wiederholtem Fehler ist der Knoten für Produktionsjobs isoliert.

Diese Reihenfolge verhindert, dass Sie Verbindungsprobleme mit Xcode-Skripten überdecken. Sie schafft außerdem ein reproduzierbares Übergabeprotokoll zwischen DevOps, Entwicklung und Release Engineering.

FAQ zur Jenkins-macOS-Fehlersuche

Warum ist der Jenkins macOS Agent offline, obwohl SSH noch funktioniert?

SSH und die Jenkins-Agent-Verbindung sind getrennte Kanäle. Eine erfolgreiche SSH-Anmeldung beweist nur, dass Remote Login und Netzwerkzugriff funktionieren. Prüfen Sie deshalb den tatsächlich verwendeten Launch Method, den Agent-Prozess, die Controller-Adresse, Zertifikate und mögliche Firewall- oder Proxy-Regeln. Erst ein stabiler Jenkins-Handshake und ein erfolgreicher Testauftrag bestätigen die Wiederherstellung.

Was hilft, wenn der Jenkins macOS Agent nach einem Neustart nicht automatisch online kommt?

Untersuchen Sie zuerst den Benutzerkontext, die Startumgebung und die für diesen Mac eingerichtete automatische Startmechanik. Ein manuell über SSH gestarteter Prozess kann nach Abmeldung oder Neustart verschwinden. Prüfen Sie die system- und benutzerbezogenen launchd-Protokolle, Dateiberechtigungen sowie den Agent-Startfehler. Testen Sie danach Abmeldung, Neustart und unbeaufsichtigte Wiederverbindung separat.

Wie lässt sich ein online angezeigter Jenkins Agent mit wartenden Xcode-Aufträgen prüfen?

Vergleichen Sie die Labels des Auftrags mit den Labels des Knotens und kontrollieren Sie die Zahl verfügbarer Executors. Danach prüfen Sie Remote Root Directory, freien Speicher, Workspace-Berechtigungen sowie die Xcode-Auswahl im Kontext des Agent-Benutzers. Ein einfacher Shell-Auftrag reicht nicht als Abnahme: Kompilierung, Tests und Signierung benötigen jeweils einen eigenen Minimaltest.

Soll ein Jenkins Agent auf einem Remote Mac per SSH oder als Inbound Agent laufen?

Die Entscheidung hängt von Ihrer Betriebsform ab. SSH passt, wenn der Controller den Mac zuverlässig erreichen und den Agent-Prozess starten darf. Eine eingehende Verbindung ist sinnvoll, wenn der Mac selbst die Verbindung zum Controller aufbauen soll, etwa hinter restriktiven Netzwerkregeln. Dokumentieren Sie Launch Method, Zugangsdaten und Wiederanlaufverhalten; mischen Sie die Kanäle nicht bei der Fehlersuche.

Woran erkennt man, dass ein Jenkins macOS-Buildknoten wieder produktionsbereit ist?

Der Knoten muss nicht nur als online erscheinen. Er muss einen Auftrag mit passendem Label annehmen, den Workspace beschreiben können, die erwartete Xcode-Version und Command-Line-Tools verwenden, Tests ausführen und eine kontrollierte Signierungsaufgabe abschließen. Wiederholen Sie die Prüfung nach Controller-Neustart, Mac-Neustart, kurzer Netzwerkunterbrechung und längerer Leerlaufzeit. Jede manuelle Intervention gehört ins Abnahmeprotokoll.

Wenn Ihr bestehender Knoten nach dieser Prüfung weiterhin nur durch manuelle Eingriffe stabil bleibt, ist weiteres Skripting selten die beste langfristige Lösung. Ein eigener Mac mini kann bei dauerhaft hoher Auslastung und notwendiger physischer Infrastruktur sinnvoll sein, bindet Sie aber an Beschaffung, Wartung, Stromversorgung und einen einzelnen Ausfallpunkt. Ein virtueller macOS-Ansatz bringt zusätzlich Fragen zu Kompatibilität, Signierung und zulässiger Betriebsumgebung mit sich.

Für wechselnde Projekte, Testzweige oder einen zusätzlichen Xcode-CI-Knoten ist ein gemieteter Remote Mac oft einfacher zu ersetzen und getrennt neu zu starten. Sie können zunächst die Mac-Mietpreise von VpsMesh mit den laufenden Kosten Ihres bestehenden Knotens vergleichen. Wenn Sie eine vollständig berechtigte, dauerhaft erreichbare Umgebung ohne eigene Hardware bereitstellen müssen, finden Sie den Einstieg über die Remote-Mac-Übersicht von VpsMesh. Entscheidend bleibt: Mieten Sie nicht als Ersatz für eine ungeprüfte Diagnose, sondern als kontrollierte Option, wenn der alte Jenkins macOS Agent wiederholt offline geht oder seine Xcode-Umgebung nicht mehr reproduzierbar ist.