GitLab Runner macOS nach Neustart offline? Reparaturleitfaden für Unternehmen 2026

„Mac erreichbar, Runner offline“ beschreibt keinen einzelnen Fehler. Wir trennen vier Zustände:

1. Der Mac ist eingeschaltet und im Netzwerk erreichbar.
2. Das Startvolume ist entsperrt.
3. Das dedizierte CI-Konto besitzt eine aktive Benutzersitzung.
4. Der GitLab Runner ist in dieser Sitzung geladen und kann Aufträge ausführen.

Diese Zustände können unabhängig voneinander auseinanderfallen. Ein Gerät kann auf Ping oder über Remote Login antworten, obwohl FileVault noch auf eine Entsperrung wartet. Ebenso kann ein Benutzer angemeldet sein, während der LaunchAgent nicht geladen wurde. Ein Runner kann im GitLab-Portal online erscheinen, aber beim Xcode-Build an Keychain oder Simulator scheitern.

Der erste Fehlerfall, den wir in der Praxis untersuchen, lautet deshalb nicht „Installation defekt“. Er lautet: „Welche Schicht ist nach dem Neustart zuletzt wiederhergestellt worden?“

GitLab dokumentiert die macOS-Installation und den Dienstbetrieb in der offiziellen macOS-Anleitung für GitLab Runner. Diese Dokumentation bildet den Startpunkt. Eine Neuinstallation vor der Zustandsprüfung kann dagegen zusätzliche Konfigurationsdateien, falsche Benutzerzuordnungen und neue system_id-Verwechslungen erzeugen.

Schnellaufnahme vor jeder Änderung

Melden Sie sich, soweit möglich, mit dem vorgesehenen CI-Konto an und erfassen Sie:

• den aktuell angemeldeten Benutzernamen;
• den Status des GitLab Runner-Prozesses;
• den Pfad der Runner-Konfiguration;
• den geladenen LaunchAgent;
• die Verbindung zum GitLab-Projekt oder zur Runner-Gruppe;
• den Status der Login-Keychain;
• den letzten Fehlerzeitpunkt aus der kontrollierten Dienstprotokollierung.

Diese Aufnahme muss vor einer Reparatur gespeichert werden. Sonst ist später nicht mehr nachvollziehbar, ob ein Fehler durch die ursprüngliche Umgebung oder durch die Reparatur entstanden ist.

Der wichtigste Architekturpunkt ist der Ausführungskontext. Auf macOS wird GitLab Runner in der unterstützten Variante als Benutzerprozess über einen LaunchAgent betrieben. Ein LaunchAgent gehört zur Benutzersitzung. Apple beschreibt die Unterschiede zwischen benutzerbezogenen Agents und systemweiten Daemons in der Dokumentation zu Launchd-Daemons und Agents.

Das hat für einen CI-Knoten vier konkrete Folgen:

• Der Runner muss unter dem vorgesehenen CI-Konto installiert sein.
• Die Konfigurationsdatei muss diesem Konto zugeordnet sein.
• Der LaunchAgent muss in dessen Benutzerkontext geladen werden.
• Die Sitzung muss die Voraussetzungen für Keychain, Xcode und gegebenenfalls Simulator erfüllen.

Ein häufiger Fehlversuch besteht darin, den Runner unter einem Administratorkonto zu installieren und später anzunehmen, das CI-Konto werde dieselbe Konfiguration verwenden. Ein zweiter Fehler entsteht, wenn ein Administrator denselben Runner mehrfach unter verschiedenen Konten einrichtet. Danach existieren möglicherweise mehrere Agent-Dateien, Konfigurationen und Identitäten. Das GitLab-Portal zeigt dann nicht zwingend den Prozess, den die verantwortliche Person gerade prüft.

Kein unbegründeter Wechsel zu LaunchDaemon

Ein LaunchDaemon klingt zunächst nach einer Lösung für „Start beim Booten“. Für einen macOS-Buildknoten ist das jedoch kein gleichwertiger Ersatz. Ein systemweiter Daemon besitzt einen anderen Sicherheits- und Sitzungsrahmen. Er erhält nicht automatisch die Login-Keychain, die grafische Benutzerumgebung oder den Simulator-Kontext des CI-Kontos.

Die Apple-Erklärung zu launchd-Aufträgen hilft bei der Einordnung: Nicht nur der Startzeitpunkt, sondern der Ausführungskontext bestimmt das Verhalten. Wir ändern deshalb nicht einfach den Diensttyp, um die Anzeige „offline“ schneller zu beseitigen. Wir reparieren zuerst den vorgesehenen LaunchAgent.

Minimalprüfung der richtigen Identität

Die Prüfung sollte unter dem vorgesehenen Konto erfolgen. Entscheidend sind nicht viele Befehle, sondern die richtige Reihenfolge:

1. whoami bestätigt das aktive Konto.
2. id zeigt Gruppen und Berechtigungen.
3. Der Status des Runner-Dienstes bestätigt, ob der Agent geladen ist.
4. Der Konfigurationspfad zeigt, ob die erwartete Identität verwendet wird.
5. Ein kontrollierter Status- oder Verbindungscheck bestätigt die Registrierung.

Die Befehle müssen in einem Wartungsfenster ausgeführt und ihre Ausgabe darf keine Token, privaten Schlüssel oder geschützten Variablen enthalten. GitLab weist in seinen Hinweisen zur Runner-Fehlerbehebung auf den sorgfältigen Umgang mit Diagnoseinformationen hin. Vollständige Debug-Protokolle gehören nicht ungefiltert in ein zentrales Logsystem.

FileVault verändert die Annahme „Neustart führt automatisch zur CI-Sitzung“. Ist das Startvolume verschlüsselt, muss es zunächst entsperrt werden. Die Apple-Dokumentation zur FileVault-Verwaltung beschreibt den Schutz des Startvolumes und die Rolle autorisierter Entsperrungsdaten.

Automatische Anmeldung ist dabei kein neutraler Schalter. Apple weist in der Dokumentation zur automatischen Anmeldung darauf hin, dass Sicherheitskonfigurationen wie FileVault diese Funktion beeinflussen können. Das Unternehmen muss daher eine bewusste Entscheidung treffen:

• Wiederherstellbarkeit priorisieren: Eine kontrollierte, überwachte Anmeldestrategie wird vorgesehen. Die Entsperrung und die Anmeldung erhalten klare Verantwortliche und Audit-Nachweise.
• Schutz des Startvolumes priorisieren: FileVault bleibt aktiv, aber nach einem Neustart wird ein manueller oder anderweitig kontrollierter Entsperrschritt eingeplant. Der Runner gilt bis dahin nicht als produktionsbereit.
• Beides ohne Prozessänderung erwarten: Diese Annahme ist nicht belastbar und darf nicht als Betriebsmodell dokumentiert werden.

Remote Login kann bei der Diagnose helfen, ersetzt aber nicht die Benutzersitzung. Die Apple-Anleitung zu Remote Login sollte gemeinsam mit Netzwerkregeln, Geräteverwaltung und dem Notfallprozess geprüft werden.

Achtung: Ein gespeichertes Entsperrpasswort im Ticket, in einer Pipeline-Variable oder in einem ungeschützten Runbook ist kein Wiederherstellungskonzept. Verwenden Sie ein kontrolliertes Wiederherstellungskonto, begrenzen Sie den Zugriff und dokumentieren Sie jede Entsperrung.

Der Online-Status ist nur die erste technische Schranke. Nach einer Wiederanmeldung muss separat geprüft werden, ob der Knoten tatsächlich produktionsfähige Aufgaben ausführen kann.

Wir unterscheiden vier Tests:

1. Einfaches Skript: Der Runner nimmt einen Auftrag an und schreibt einen erwarteten Status zurück.
2. Xcode-Build: Die vorgesehene Xcode-Umgebung wird geladen und ein reproduzierbarer Build gestartet.
3. Simulator: Nur wenn die Pipeline Simulatoren benötigt, wird ein Start- und Testvorgang ausgeführt.
4. Codesignatur: Die für den Release-Prozess vorgesehene Identität und Keychain werden geprüft.

Diese Reihenfolge verhindert, dass ein vollständiger Release-Lauf mehrere Ursachen gleichzeitig verdeckt. Ein erfolgreiches Shell-Skript beweist weder, dass Xcode verfügbar ist, noch dass die Signaturidentität entsperrt werden kann.

Besonders wichtig ist die Trennung der Speicherorte:

• Die Login-Keychain gehört zur Benutzersitzung.
• Die System-Keychain ist kein Ersatz für eine entsperrte Login-Keychain.
• Das CI-Konto ist nicht automatisch identisch mit dem Konto, das Zertifikate ursprünglich importiert hat.
• Eine im Projekt konfigurierte Signierungsidentität kann nach einem Neustart fehlen, obwohl der Runner online ist.

Für die Auftragszuordnung prüfen wir zusätzlich Runner-Tags, geschützte Branches und den Geltungsbereich auf Projekt- oder Gruppenebene. Die GitLab-Dokumentation zu Runner-Konfiguration und Tags erklärt, wie Tags die Zuordnung beeinflussen. Ein nicht passender Tag kann wie ein Offline-Problem wirken, obwohl der Prozess korrekt verbunden ist.

Warum startet der Runner nicht automatisch?

Der typische Grund ist nicht fehlende Software, sondern ein fehlender Benutzerkontext. Der Mac ist gestartet, das CI-Konto aber nicht angemeldet oder der LaunchAgent wurde in dieser Sitzung nicht geladen. Prüfen Sie deshalb zuerst Konto, Sitzung, Agent und Konfigurationspfad. Eine neue Registrierung beseitigt weder eine blockierte FileVault-Entsperrung noch eine falsche Benutzerzuordnung.

Ist eine Anmeldung für macOS Runner erforderlich?

Für das dokumentierte LaunchAgent-Modell ist die Sitzung des zugewiesenen Benutzers Bestandteil der Ausführung. Das betrifft nicht nur den Prozessstatus. Xcode, Login-Keychain und grafische Werkzeuge greifen ebenfalls auf diesen Kontext zurück. Ein Knoten ohne geeignete Sitzung darf daher nicht allein wegen einer erreichbaren Netzwerkverbindung als produktionsfähig gelten.

Ist LaunchDaemon eine bessere Lösung?

Nein, nicht als pauschale Reparatur. Ein LaunchDaemon verschiebt den Prozess in den Systemkontext und kann dadurch genau die Benutzerdienste entfernen, die ein iOS-Build benötigt. Bevor ein Unternehmen vom unterstützten Modell abweicht, muss es die Auswirkungen auf Keychain, Simulator, Signierung, Rechte und Auditierung nachweisen. In den meisten Fällen ist die Korrektur des LaunchAgent risikoärmer.

Wie wird FileVault in den Wiederherstellungsprozess einbezogen?

FileVault muss vor dem Runner betrachtet werden. Zuerst wird das Startvolume entsperrt, danach entsteht die Benutzersitzung, anschließend kann der LaunchAgent geladen werden. Die Organisation benötigt dafür einen kontrollierten Zugriffspfad, ein dokumentiertes Wiederherstellungskonto und einen Audit-Nachweis. Automatische Anmeldung darf nicht stillschweigend als Ausgleich für eine nicht geklärte FileVault-Strategie dienen.

Was bedeutet „online“, wenn Keychain nicht funktioniert?

Der Runner kann mit dem Dienst verbunden sein und trotzdem keinen Release-Auftrag ausführen. Ein Online-Signal bestätigt vor allem die Verbindung und Registrierung. Erst getrennte Tests für Skript, Xcode, Simulator und Codesignatur zeigen die tatsächliche Nutzbarkeit. Falls nur die Signatur scheitert, untersuchen Sie die Login-Keychain und die Identität des CI-Kontos, nicht zuerst die Netzwerkverbindung.

Wenn mehrere Personen einen Runner reparieren, entstehen leicht parallele Zustände. Ein alter LaunchAgent läuft weiter, während eine neue Konfiguration unter einem anderen Konto registriert wird. Das GitLab-Portal kann dann einen anderen Runner anzeigen als der lokale Prozess.

Prüfen Sie deshalb:

• Gibt es mehr als eine Runner-Konfiguration auf dem Mac?
• Gehören alle Agent-Dateien zum vorgesehenen CI-Konto?
• Stimmen Runner-Name, Tags und Projektbereich überein?
• Existieren alte Registrierungen, die nicht mehr verwendet werden?
• Ist ein geschützter Branch nur einem anderen Runner zugewiesen?
• Wurde eine Pipeline wegen fehlender Tags nicht an diesen Knoten geroutet?

Entfernen Sie alte Einträge erst nach einer Sicherung der aktuellen Konfiguration und einer Freigabe durch den Verantwortlichen. Eine vorschnelle Bereinigung kann einen funktionierenden Ersatzpfad löschen.

Die folgende Liste ist der eigentliche Abnahmetest. Jeder Punkt braucht ein Datum, eine verantwortliche Person und einen Beleg.

• [ ] Das dedizierte CI-Konto ist dokumentiert und nicht mit einem persönlichen Administratorkonto vermischt.
• [ ] Die aktuelle Runner-Konfiguration ist gesichert und dem richtigen Projekt- oder Gruppenbereich zugeordnet.
• [ ] Der LaunchAgent ist im Benutzerkontext geladen.
• [ ] Ein Neustart wurde mit dem vorgesehenen Netzwerkpfad geprüft.
• [ ] Der Status der FileVault-Entsperrung ist dokumentiert.
• [ ] Die Wiederherstellung ohne Vor-Ort-Einsatz ist entweder bewiesen oder ausdrücklich ausgeschlossen.
• [ ] Remote Login ist nur für die vorgesehenen Administratoren freigeschaltet und protokolliert.
• [ ] Ein einfaches CI-Skript läuft nach der Wiederherstellung erfolgreich.
• [ ] Ein reproduzierbarer Xcode-Build läuft unter dem vorgesehenen CI-Konto.
• [ ] Simulator-Tests wurden separat geprüft, falls sie zur Pipeline gehören.
• [ ] Login-Keychain, System-Keychain und Signierungsidentität sind getrennt dokumentiert.
• [ ] Runner-Tags, geschützte Branches und Gruppenbereiche routen Aufträge korrekt.
• [ ] Debug-Protokolle enthalten keine Tokens, Zertifikatsinhalte oder geschützten Variablen.
• [ ] Ein Fehlerfall mit deaktiviertem Konto wurde kontrolliert getestet.
• [ ] Für den Ausfall des primären Mac existiert eine freigegebene Ersatzentscheidung.

Ein geplanter Neustart reicht als Test nicht aus. Ergänzen Sie mindestens einen kontrollierten Test nach unerwarteter Stromunterbrechung und einen Test nach Entzug des CI-Kontos. Die Ergebnisse müssen zeigen, ob das Unternehmen den Knoten tatsächlich wiederherstellen kann oder nur den Normalfall kennt.

Ein einzelner Mac kann für kleinere Buildvolumen genügen, wenn die Wiederherstellung nach jedem Neustart beherrscht wird. Er ist jedoch kein belastbarer Produktionspfad, wenn FileVault-Entsperrung, Benutzeranmeldung oder Keychain-Freigabe regelmäßig manuell erfolgen müssen.

Vor einer zusätzlichen Kapazität sollten Sie drei Fragen beantworten:

• Kann der primäre Knoten nach einem Neustart ohne lokale Anwesenheit wieder einen echten Xcode-Auftrag annehmen?
• Sind Signierungsdaten auf einem Ersatzknoten kontrolliert und getrennt verfügbar?
• Kann die Pipeline bei Ausfall korrekt auf einen zweiten Runner mit passenden Tags wechseln?

Falls eine Antwort „nein“ lautet, ist ein isolierter Ersatzknoten sinnvoller als weitere Reparaturversuche am Einzelgerät. Für wechselnde Kapazitätsanforderungen kann ein Remote-Mac-Angebot von MESHLAUNCH als zusätzlicher Prüfpunkt dienen. Die konkrete Eignung muss anhand von Zugriff, Verantwortungsgrenzen, Datenhaltung und Wiederherstellungstests bewertet werden. Für eine eigene Beschaffungsentscheidung können Sie außerdem die verfügbaren Mac-mini-Konfigurationen von MESHLAUNCH mit dem bestehenden Betriebskonzept abgleichen.

Die richtige Reihenfolge bleibt unverändert: erst Benutzerkontext und LaunchAgent, dann FileVault und Sitzung, danach Keychain und Build, zuletzt die Kapazitätsentscheidung.

Wenn die derzeitige Lösung bei jedem Neustart eine Person vor dem Mac, eine nicht dokumentierte Passwortübergabe oder eine manuelle Signaturreparatur benötigt, ist sie als langfristiger Produktionsknoten zu fragil. Ein selbst beschaffter Mac bindet Kapital und braucht zusätzlich Ersatzhardware, Wartung und einen getesteten Zugriffspfad. Ein unkontrollierter Remote-Ansatz verschiebt diese Risiken lediglich in Berechtigungen und Wiederherstellung. Für einen zeitlich begrenzten Bedarf, einen getrennten Ersatzknoten oder eine überprüfbare CI-Kapazität kann die Miete eines Remote Mac von MESHLAUNCH die praktischere Variante sein — vorausgesetzt, die Abnahme umfasst dieselben Benutzer-, FileVault-, Keychain- und Neustarttests wie der eigene Knoten.