Die Pipeline wartet, aber GitLab zeigt keinen verfügbaren macOS Runner.

Schnellste Prüfung: Melden Sie das vorgesehene Benutzerkonto am Mac an und kontrollieren Sie, ob dessen LaunchAgent läuft und der Runner GitLab erreicht. Ein macOS Runner läuft als benutzerbezogener LaunchAgent und hängt von der angemeldeten Benutzersitzung ab. Aktivieren Sie die automatische Anmeldung nicht reflexartig: Sie verändert die Sicherheitsgrenze des Macs.

Dieser Leitfaden ist für Sie, wenn Sie auf Reisen einen Remote-Mac für iOS-Builds betreiben und nach einem Neustart keine Aufträge mehr angenommen werden.
Er hilft Ihnen auch, wenn Sie als unabhängiger Entwickler Simulatoren oder Signierumgebungen benötigen.
Als kleines Team können Sie damit entscheiden, ob Sie den selbst verwalteten Runner weiter betreiben oder einen Ausweichweg brauchen.

GitLab macOS Runner nach Neustart offline: zuerst den Fehlerort bestimmen

„Kein Runner verfügbar“ bedeutet nicht automatisch, dass der Runner-Dienst auf dem Mac ausgefallen ist. Die Pipeline kann auch wegen nicht passender Tags, fehlender Projektzuordnung oder einer Einschränkung bei geschützten Aufträgen warten. Trennen Sie deshalb die Frage „Ist der Runner erreichbar?“ von „Darf und kann er diesen Auftrag ausführen?“.

Prüfen Sie in dieser Reihenfolge:

  1. Öffnen Sie in GitLab die Runner-Ansicht des Projekts und prüfen Sie, ob der betreffende Runner dort verfügbar ist und ob er dem richtigen Projekt- oder Gruppenbereich zugeordnet wurde.
  2. Vergleichen Sie die Tags des Auftrags mit den Tags, die dem Runner zugewiesen sind. Ein Auftrag mit Anforderungen, die der Runner nicht erfüllt, wird nicht an ihn vergeben. Die GitLab-Dokumentation zum Abgleich von Runner-Tags und Aufträgen beschreibt diese Zuordnung.
  3. Kontrollieren Sie, ob der Auftrag geschützt ist und ob der Runner geschützte Aufträge übernehmen darf.
  4. Erst wenn die Zuordnung plausibel ist, untersuchen Sie den Mac selbst.

Die Runner-API führt im Statusfeld konkrete Zustände wie „online“, „offline“, „stale“, „never_contacted“ und „paused“. Diese Zustände helfen, eine fehlende Verbindung von einer Pause oder einer noch nie erfolgten Verbindung zu unterscheiden. Sie belegen jedoch nicht, dass ein Xcode-Build erfolgreich wäre. Nutzen Sie dafür die Beschreibung des Runner-Status in der GitLab-API.

Wenn die Pipeline keinen Runner findet

Öffnen Sie den wartenden Auftrag und lesen Sie die angezeigten Anforderungen. Stimmen die Tags nicht überein, ändern Sie nicht zuerst den Dienst auf dem Mac: Korrigieren Sie die Tags im Auftrag oder richten Sie den Runner passend ein. Ist der Runner im Projekt nicht sichtbar, überprüfen Sie Registrierung und Bereich. Die GitLab-Anleitung zu Runner-Befehlen hilft, lokale Verwaltungsbefehle von der Zuweisung in GitLab zu unterscheiden.

Ein häufiger Denkfehler: Ein Runner kann auf dem Mac laufen und trotzdem keinen Auftrag erhalten. Umgekehrt sagt eine sichtbare Runner-Konfiguration nicht aus, dass auf dem Host gerade ein funktionierender Prozess läuft.

Wenn der Mac startet, aber der Runner-Dienst fehlt

GitLab dokumentiert für macOS den Start des Runners als benutzerbezogenen LaunchAgent. Das ist kein systemweiter LaunchDaemon. Ein LaunchAgent gehört zur Sitzung eines Benutzers; ein LaunchDaemon wird systemweit verwaltet und ist nicht dasselbe Ausführungsmodell. Verwechseln Sie die beiden nicht, wenn Sie eine Anleitung für einen anderen Diensttyp übernehmen. Die offizielle Installationsanleitung für GitLab Runner unter macOS beschreibt den vorgesehenen Startmechanismus und dessen Sitzungsabhängigkeit.

Prüfen Sie auf dem Mac mit dem Konto, unter dem der Runner eingerichtet wurde:

  1. Melden Sie sich an der grafischen macOS-Sitzung dieses Kontos an.
  2. Rufen Sie den in Ihrer Installation vorgesehenen Status- oder Verwaltungsbefehl auf. Die möglichen Befehle und ihre Wirkung finden Sie in der Referenz zu GitLab-Runner-Befehlen.
  3. Prüfen Sie, ob der LaunchAgent für dieses Konto geladen ist und ob der Runner-Prozess läuft.
  4. Sehen Sie in den Runner- und Systemprotokollen nach, ob der Start fehlschlägt oder die Verbindung zu GitLab nicht hergestellt wird.
  5. Kontrollieren Sie anschließend in GitLab, ob der Status nach einer erneuten Kontaktaufnahme aktualisiert wird.

Startet der Dienst nach der Anmeldung, war der fehlende oder nicht aktive Benutzerkontext wahrscheinlich entscheidend. Bleibt der Dienst aus, prüfen Sie den Installationspfad, die Einrichtung des LaunchAgents und die Protokolle, statt wiederholt die gesamte Maschine neu zu starten.

Wichtig ist die Trennung der Ereignisse. Ein Neustart beendet die vorherige Sitzung und startet macOS neu. Eine Abmeldung beendet die Benutzersitzung, während die Maschine weiterläuft. Das Schließen einer SSH-Verbindung ist dagegen nicht automatisch dasselbe wie eine Abmeldung der grafischen Sitzung. Welche Prozesse weiterlaufen, hängt davon ab, wie sie gestartet wurden. Leiten Sie aus einem erfolgreichen SSH-Test daher nicht ab, dass der LaunchAgent nach einer Abmeldung weiter verfügbar ist.

Nach Abmeldung wieder offline: den Sitzungsbezug gezielt testen

Ein Runner kann nach einer Anmeldung erreichbar sein und nach der Abmeldung desselben Kontos verschwinden. Prüfen Sie, ob der Prozess tatsächlich an die Benutzersitzung gebunden ist und ob die Abmeldung mit dem beobachteten Zeitpunkt des Offline-Status zusammenfällt. Beobachten Sie dabei sowohl den lokalen Dienststatus als auch die Runner-Ansicht in GitLab.

Für eine aussagekräftige Diagnose ändern Sie jeweils nur eine Bedingung:

  • Lassen Sie den Mac laufen und melden Sie das Runner-Konto ab. Prüfen Sie anschließend, ob der Runner noch erreichbar ist.
  • Melden Sie dasselbe Konto erneut an und kontrollieren Sie, ob der LaunchAgent gestartet wird.
  • Trennen Sie eine SSH-Verbindung, ohne die grafische Sitzung abzumelden. Vergleichen Sie diesen Zustand getrennt mit einer echten Abmeldung.

So erkennen Sie, ob Ihr Problem an der Benutzeranmeldung, am Agent-Start oder an der Verbindung zu GitLab hängt. Ersetzen Sie diese Prüfung nicht durch eine Vermutung anhand eines einzelnen Neustarts.

Beispiel: Sie sind unterwegs, öffnen vom iPad aus eine SSH-Verbindung und sehen den Runner online. Später wird die Sitzung am Mac abgemeldet; die nächste Pipeline bleibt liegen. In diesem Fall ist der SSH-Zugang nicht der entscheidende Prüfpunkt. Entscheidend ist, ob die für den LaunchAgent nötige Sitzung aktiv ist und ob der Runner nach der Abmeldung weiter Kontakt hält.

Automatische Anmeldung als Wiederherstellung gegen Sicherheit abwägen

Die GitLab-Installationsdokumentation nennt die automatische Anmeldung als Möglichkeit, damit ein macOS Runner nach einem Neustart wieder in der benötigten Benutzersitzung verfügbar ist. Das ist eine dokumentierte Betriebsoption, aber keine allgemeine Sicherheitsempfehlung. Sie können daraus weder ableiten, dass sie für jeden Remote-Mac erforderlich ist, noch dass sie für jedes Team akzeptabel wäre. Prüfen Sie die Hinweise von GitLab zur macOS-Installation und zum Benutzerkontext zusammen mit den Apple-Informationen zur automatischen Anmeldung.

Die Abwägung hat konkrete Folgen:

  • Vorteil: Der Mac kann nach einem Neustart in die vorgesehene Sitzung gelangen, sodass ein sitzungsabhängiger LaunchAgent wieder starten kann.
  • Nachteil: Der Zugang zur physischen Maschine und zu einem bereits angemeldeten Konto erhält ein anderes Risikoprofil. Wer den Mac erreichen kann, könnte dadurch leichter an eine aktive Sitzung gelangen.
  • Zusätzliche Prüfung: Bewerten Sie, welche Projektgeheimnisse, Signierdaten und Zugangsdaten im Runner-Kontext verfügbar sind. Begrenzen Sie Berechtigungen und den Zugriff auf den Host so weit, wie es Ihr Betrieb erlaubt.
  • Entscheidung: Wenn ein unbeaufsichtigter Wiederanlauf zwingend erforderlich ist, dokumentieren Sie das Risiko und testen Sie die Wiederherstellung. Wenn automatische Anmeldung nicht vertretbar ist, planen Sie einen manuellen Anmeldeschritt oder eine andere Build-Route ein.

Geben Sie keine Zugangsdaten in Skripte oder CI-Protokolle aus, nur um den Neustart zu überbrücken. Eine laufende Pipeline ist kein Beleg dafür, dass die Zugriffsgrenzen angemessen gesetzt sind.

Runner online, aber der iOS-Build scheitert

Ein grüner oder erreichbarer Runner-Status ist nur eine Aussage über die Verbindung und Verfügbarkeit des Runners. Er beweist weder, dass ein Auftrag korrekt zugewiesen wurde, noch dass der Auftrag erfolgreich ausgeführt wurde oder Xcode das Projekt bauen kann. Prüfen Sie diese Ebenen getrennt:

  1. Runner-Verbindung: Wird der Runner in GitLab als online angezeigt?
  2. Auftragszuweisung: Passen Tags, Projektbereich und Berechtigungen zum wartenden Auftrag?
  3. Auftragsausführung: Startet der Job auf dem Mac, und welcher Schritt schlägt laut Job-Protokoll fehl?
  4. Xcode-Umgebung: Ist die erwartete Xcode-Installation beziehungsweise das passende Entwicklerverzeichnis aktiv?

Für die letzte Prüfung können Sie auf dem Mac xcode-select --print-path verwenden. Der ausgegebene Pfad zeigt, welches Entwicklerverzeichnis für die Kommandozeilenwerkzeuge ausgewählt ist. Vergleichen Sie ihn mit der Umgebung, die Ihr Projekt benötigt. Apple beschreibt Installation und Einrichtung der Xcode-Kommandozeilenwerkzeuge sowie die verfügbaren zusätzlichen Xcode-Komponenten.

Achten Sie im Job-Protokoll auf den ersten fehlgeschlagenen Befehl, nicht nur auf die letzte Fehlermeldung. Ein falsches Entwicklerverzeichnis, eine fehlende Komponente oder ein Berechtigungsproblem kann den Build verhindern, obwohl der Runner den Auftrag korrekt angenommen hat. Vermeiden Sie pauschale Neuinstallationen, bevor Sie den konkreten Fehler und den aktiven Entwicklerpfad erfasst haben.

Wiederanlaufwege nach Betriebsanforderung vergleichen

Wählen Sie den Wiederherstellungsweg danach, ob interaktive Anmeldung möglich ist, ob automatische Anmeldung akzeptabel ist und ob Sie bei einem Ausfall einen alternativen Build-Pfad haben.

Option Geeignet, wenn Vorteil Grenze
Anmeldung und LaunchAgent manuell prüfen Sie nach einem Neustart selbst auf den Mac zugreifen können Klare Kontrolle über Sitzung und Dienstzustand Kein vollständig unbeaufsichtigter Wiederanlauf
Automatische Anmeldung prüfen und bewusst freigeben Der Runner nach Neustarts ohne manuellen Eingriff verfügbar sein muss und das zusätzliche Zugriffsrisiko akzeptiert wird Kann die benötigte Benutzersitzung wiederherstellen Erfordert eine ausdrückliche Sicherheitsbewertung
Alternativen Build-Verfahren nutzen Eine interaktive Sitzung nicht zuverlässig bereitgestellt werden kann oder automatische Anmeldung ausscheidet Entkoppelt den Arbeitsablauf von diesem einzelnen Sitzungsproblem Erfordert eine eigene Prüfung von Projektanforderungen und Build-Umgebung

Das ist keine allgemeine Rangliste. Wenn Ihr Projekt Simulatorzugriff oder eine bestimmte Xcode-Umgebung braucht, muss die Alternative dieselben Anforderungen erfüllen. Wenn ein manueller Anmeldeschritt im Reisealltag zuverlässig möglich ist, ist eine riskantere automatische Anmeldung nicht automatisch die bessere Wahl.

Mit einer Wiederanlaufprobe die Entscheidung absichern

Führen Sie die Probe in einer kontrollierten Wartungsphase durch, bevor Sie sich auf den Runner für einen wichtigen Release verlassen. Notieren Sie für jeden Schritt Uhrzeit, beobachteten Status und nächste Maßnahme. Ändern Sie nicht gleichzeitig Tags, Berechtigungen und Startmodus: Sonst bleibt unklar, welche Änderung geholfen hat.

  1. Ausgangszustand erfassen: Notieren Sie Runner-Status, Projektzuordnung, Tags und den verwendeten macOS-Benutzer.
  2. Neustart durchführen: Starten Sie den Mac kontrolliert neu und prüfen Sie, ob die Benutzersitzung wie erwartet verfügbar ist.
  3. LaunchAgent kontrollieren: Melden Sie sich, falls nötig, mit dem Runner-Konto an und prüfen Sie, ob der Agent und Runner-Prozess aktiv sind.
  4. Kontakt zu GitLab prüfen: Warten Sie auf eine sichtbare Aktualisierung und unterscheiden Sie „offline“ von „paused“ oder „never_contacted“ anhand des Statusfelds.
  5. Testauftrag starten: Verwenden Sie einen Auftrag, dessen Tags und Projektberechtigungen zum Runner passen.
  6. Xcode-Build validieren: Prüfen Sie Job-Protokoll und Entwicklerverzeichnis. Erst ein erfolgreicher Projekt-Build schließt die Abnahme ab.

Danach entscheiden Sie anhand des Ergebnisses:

  • Wenn Sitzung, Agent, GitLab-Verbindung und Projekt-Build nach dem geplanten Neustart funktionieren, können Sie den selbst verwalteten Runner beibehalten und die geprüfte Wiederherstellungsfolge dokumentieren.
  • Wenn nur eine manuelle Anmeldung den Runner zurückbringt, entscheiden Sie, ob dieser Eingriff im Reisebetrieb praktikabel ist. Falls nicht, bewerten Sie automatische Anmeldung oder einen Ausweich-Build-Pfad.
  • Wenn der Runner online ist, der Job aber nicht startet, korrigieren Sie zuerst Tags, Projektzuordnung oder Berechtigungen.
  • Wenn der Job startet, aber Xcode scheitert, behandeln Sie das als Build-Umgebungsfehler und nicht als Runner-Ausfall.

Für die Reise zwischen eigener Wartung und Remote-Mac abwägen

Ein selbst verwalteter Mac gibt Ihnen Kontrolle über Benutzerkonto, LaunchAgent und Entwicklungsumgebung. Dafür müssen Sie Startverhalten, Zugangsschutz, Protokolle und Wiederherstellung selbst überwachen. Eine lokale Maschine auf Reisen bringt zusätzlich Abhängigkeit von Ihrem Zugriff auf genau dieses Gerät und dessen laufende Sitzung mit sich. Ein Remote-Mac verlagert die Wartung des Arbeitsgeräts aus Ihrem Gepäck, beseitigt aber nicht die Verantwortung für GitLab-Berechtigungen, CI-Geheimnisse oder die Abnahme Ihres Builds.

Wenn Sie nur gelegentlich einen macOS-Build prüfen oder nach einem Gerätewechsel weiterarbeiten müssen, kann ein gemieteter Remote-Mac gegenüber dem eigenen Reisegerät weniger Gepäck, weniger Abhängigkeit von dessen physischem Zustand und eine getrennte Arbeitsumgebung bieten. Prüfen Sie dennoch vorab, ob Ihr Projekt dort die nötigen Xcode-Komponenten und Zugriffsmöglichkeiten erhält. Für eine temporäre Test- oder Build-Umgebung können Sie die Informationen zu Remote-Mac-Angeboten von MACCOME prüfen. Wenn Sie nach der Wiederanlaufprobe feststellen, dass Sie dauerhaft selbst einen Mac verwalten möchten, finden Sie außerdem die Informationen zum Bestellen eines Mac mini.

Entscheiden Sie erst nach dem Wiederanlauftest: Ein selbst verwalteter Runner passt, wenn Sie die Sitzung kontrollieren und die Erholung regelmäßig verifizieren können. Wenn Sie dagegen auf Reisen eine zugängliche macOS-Umgebung brauchen, aber Neustarts, Sitzungsstatus und Hardware nicht selbst vor Ort betreuen möchten, kann ein Remote-Mac von MACCOME die passendere temporäre Lösung sein.