GitHub Actions macOS Runner offline? Fehlerbehebung 2026

GitHub Actions macOS Runner offline? Fehlerbehebung 2026

Sofortmaßnahme: Unterscheiden Sie zuerst zwischen einem offline angezeigten Runner, einem online verfügbaren Runner ohne passende Jobzuweisung und einem Fehler nach Jobstart. Prüfen Sie anschließend gezielt Host und Netzwerk, launchd, Labels und Protokolle; wechseln Sie die Mac-Umgebung nur, wenn die Ursache tatsächlich bei Verfügbarkeit oder laufendem Wartungsaufwand liegt. Diese Reihenfolge passt, wenn Sie einen selbst gehosteten macOS Runner betreiben und nicht bloß einen neuen Runner installieren möchten.

Diese Woche: Erfassen Sie für jeden Vorfall Status, Jobphase und letzten erfolgreichen Lauf in einem kurzen Fehlerprotokoll. So können Sie Konfigurationsfehler von wiederkehrenden Ausfällen der Infrastruktur trennen, statt bei jeder Warteschlange den Mac auszutauschen.

Dieser Leitfaden richtet sich an Entwickler und CI-Verantwortliche, die GitHub Actions Runner auf macOS betreiben.
Auch wenn iOS-Builds dauerhaft warten oder ein Dienst nach einem Neustart ausfällt, finden Sie hier eine passende Prüfreihenfolge.
Teamverantwortliche können daraus ableiten, ob eine Reparatur genügt oder eine andere Mac-Betriebsform sinnvoll ist.

Drei Fehlerbilder statt einer pauschalen Meldung „offline“

Der Status des Runners und der Status eines Workflows beschreiben unterschiedliche Dinge. Ein Runner kann offline sein, während ein Job lediglich auf eine passende Ausführung wartet; umgekehrt kann der Runner erreichbar sein und ein bereits gestarteter Build trotzdem scheitern. Halten Sie deshalb fest, was in GitHub angezeigt wird, in welcher Jobphase der Fehler auftritt und wann der letzte erfolgreiche Lauf stattfand.

GitHub unterscheidet bei selbst gehosteten Runnern die Zustände „Idle“, „Active“ und „Offline“. „Idle“ bedeutet, dass der Runner online ist und keinen Job ausführt; „Active“ weist auf einen laufenden Job hin; „Offline“ bedeutet, dass GitHub den Runner nicht als erreichbar sieht. Die offizielle Beschreibung der Runner-Zustände und Fehlerbehebung ist der maßgebliche Bezugspunkt. Prüfen Sie zusätzlich den Workflow: Ein wartender Job ist nicht automatisch ein Beleg dafür, dass der Runner offline ist.

Ordnen Sie den Vorfall einer dieser drei Gruppen zu:

Diese Einteilung ist entscheidend: Ein falsches runs-on-Label lässt sich durch eine neue Mac-Instanz nicht korrigieren. Ein regelmäßig nicht erreichbarer Host dagegen wird nicht durch eine Änderung an der Workflow-YAML dauerhaft verfügbar.

Offline gegenüber wartend: Host, Prozess und Verbindung prüfen

Beginnen Sie mit dem Rechner selbst. Prüfen Sie, ob der Mac eingeschaltet und erreichbar ist und ob seit dem letzten erfolgreichen Job ein Neustart, Systemupdate oder eine Netzwerkänderung stattgefunden hat. Wenn Sie SSH-Zugriff haben, kontrollieren Sie, ob das System reagiert und ob der Runner-Prozess aktiv ist. Eine erreichbare SSH-Verbindung allein beweist allerdings nicht, dass der Runner eine ausgehende Verbindung zu GitHub aufbauen kann.

Gehen Sie anschließend die Verbindungspfad-Kette durch:

  1. Namensauflösung: Lassen sich die von GitHub benötigten Hostnamen von diesem Mac aus auflösen? Vergleichen Sie das Ergebnis mit einem funktionierenden Rechner im selben Netz.
  2. Ausgehender Datenverkehr: Prüfen Sie Firewall, Proxy und Netzwerkrichtlinien. Der Runner benötigt eine funktionierende Verbindung nach außen; eine erlaubte SSH-Verbindung zum Mac ersetzt diese nicht.
  3. Zeitpunkt und Änderungen: Notieren Sie, ob der Ausfall mit einer Änderung an DNS, Proxy, Zertifikaten oder Netzwerksegment zusammenfällt.
  4. Runner-Verbindungstest: Verwenden Sie die in der GitHub-Anleitung zur Fehlerbehebung selbst gehosteter Runner dokumentierte Verbindungskontrolle. Führen Sie sie im Kontext der tatsächlichen Runner-Installation und mit den dafür vorgesehenen Zugangsdaten aus.

Suchen Sie die Diagnoseprotokolle im Verzeichnis _diag innerhalb des Runner-Installationsverzeichnisses. Vergleichen Sie die Zeitstempel der Runner-Protokolle mit dem Zeitpunkt, an dem GitHub den Status auf offline gesetzt hat. Eine Fehlermeldung zu Namensauflösung, Verbindungsaufbau oder Authentifizierung weist in unterschiedliche Richtungen; behandeln Sie sie daher nicht pauschal als „Netzwerkproblem“. Für Arbeitsabläufe mit detaillierterer Protokollierung beschreibt GitHub außerdem, wie Sie Debug-Protokolle für Workflows aktivieren.

Schalten Sie die TLS-Zertifikatsprüfung nicht als Standardmaßnahme ab. Wenn ein Proxy oder ein Zertifikat die Verbindung stört, müssen Sie die Ursache in der Netzwerkkonfiguration beheben und den Datenverkehr weiterhin nachvollziehbar absichern.

Online, aber keine Jobannahme: Labels und Runner-Gruppe abgleichen

Ein online angezeigter Runner bekommt einen Auftrag nur, wenn die Routing-Bedingungen passen. Prüfen Sie im betroffenen Workflow den Wert von runs-on und vergleichen Sie ihn mit den tatsächlichen Labels des Runners. GitHub verlangt, dass die angeforderten Labels zusammenpassen; ein Label, das sich nur in Schreibweise oder Bezeichnung unterscheidet, kann deshalb bereits verhindern, dass der Job den Runner findet. Die Dokumentation zu selbst gehostetem Runner-Routing erläutert, wie Jobs an Runner geleitet werden.

Prüfen Sie außerdem, ob der Workflow eine Runner-Gruppe vorgibt und ob diese Gruppe für das betreffende Repository freigegeben ist. Eine passende Label-Kombination reicht nicht aus, wenn die Gruppe den Zugriff nicht erlaubt. Maßgeblich sind die Einstellungen im betroffenen Repository oder in der Organisation, nicht eine Annahme darüber, wie andere Projekte konfiguriert sind. Die Regeln für Labels und Runner-Gruppen in Workflows und die Berechtigungen für Runner-Gruppen sollten Sie gemeinsam prüfen.

Achten Sie dabei auf die drei üblichen Standardlabels self-hosted, macOS und eine Architekturbezeichnung wie ARM64 oder X64. Diese Labelnamen stehen in der GitHub-Dokumentation; sie bedeuten aber nicht, dass jeder Runner automatisch dieselben Labels besitzt. Benutzerdefinierte Labels und Gruppenregeln können abweichen. Kontrollieren Sie die tatsächliche Runner-Konfiguration, bevor Sie die Workflow-Datei ändern.

Ein sinnvoller Gegencheck ist ein kontrollierter Testjob mit den Labels, die der Runner tatsächlich meldet. Verändert sich damit das Ergebnis, liegt die Ursache eher bei der Zuordnung als bei der Verfügbarkeit des Macs. Bleibt der Job wartend, prüfen Sie Gruppenrechte und ob ein anderer Workflow den Runner bereits belegt. Ersetzen Sie nicht mehrere Bedingungen gleichzeitig: Sonst wissen Sie nach dem Test nicht, welche Änderung das Routing beeinflusst hat.

Nach Neustart oder Benutzerabmeldung: launchd statt manueller Start

Ein Runner, der im Terminal funktioniert, ist nicht automatisch als dauerhafter Dienst eingerichtet. Ein manueller Start hängt von der interaktiven Sitzung und dem verwendeten Benutzer ab. Wenn der Runner nach einer Abmeldung, einem Neustart oder einer Änderung am Startkonto verschwindet, prüfen Sie daher, ob er tatsächlich als macOS-Dienst konfiguriert ist.

Wechseln Sie in das Runner-Installationsverzeichnis und verwenden Sie die dokumentierten Dienstbefehle, um den Status zu prüfen. GitHub beschreibt die Einrichtung und Verwaltung eines Runner-Dienstes in der Anleitung zur Konfiguration der Runner-Anwendung auf macOS. Dort finden Sie auch die vorgesehenen Schritte für Installation, Start und Statuskontrolle. Verwenden Sie die Befehle aus dieser Dokumentation passend zu Ihrer installierten Runner-Version und Dienstkonfiguration, statt einen beliebigen launchd-Eintrag zu verändern.

Prüfen Sie danach:

Wenn der Runner im Terminal startet, aber über launchd nicht, vergleichen Sie die Startbedingungen, statt denselben interaktiven Befehl wiederholt auszuführen. Ein erfolgreicher manueller Test belegt lediglich, dass der Prozess in dieser Sitzung starten kann. Er belegt nicht, dass launchd ihn nach einem Neustart startet oder dass er mit den erforderlichen Netzwerk- und Dateirechten läuft.

Job gestartet, aber fehlgeschlagen: Annahme und Build auseinanderhalten

Sobald GitHub einen Job dem Runner zugewiesen hat, ist die ursprüngliche Frage „Warum ist der Runner offline?“ nicht mehr die passende Diagnose. Rufen Sie die Workflow-Protokolle des konkreten Laufs auf und bestimmen Sie die letzte erfolgreiche Jobphase. Vergleichen Sie den Zeitpunkt mit den Dateien im Runner-Verzeichnis _diag; besonders hilfreich ist die Gegenüberstellung von Runner- und Worker-Ereignissen.

Wenn der Runner den Auftrag annimmt, aber das Build-Skript fehlschlägt, untersuchen Sie zuerst den tatsächlichen Fehler aus dem Jobprotokoll. Häufige Kategorien sind fehlende Abhängigkeiten, falsche Pfade, nicht verfügbare Umgebungsvariablen, unzureichende Dateirechte oder ein nicht passender Projektzustand. Prüfen Sie auch, ob ein Schritt nur in einer interaktiven Shell funktioniert, weil dort ein anderes Profil oder eine andere Umgebungsvariable geladen wird.

Trennen Sie dabei drei Zeitabschnitte: den Verbindungsaufbau des Runners, die Zuweisung des Jobs und die Ausführung der Build-Schritte. Ein Fehler vor der Auftragsannahme gehört in die Runner- oder Netzwerkdiagnose; ein Fehler nach dem Start gehört in die Job- und Projektprotokolle. Hardware sollte erst dann als Ursache in Betracht kommen, wenn die konkreten Logs und ein reproduzierbarer Vergleich darauf hinweisen. Der bloße Umstand, dass ein Build auf einem Mac fehlschlägt, belegt keinen Hardwaredefekt.

Prüfliste und Entscheidung: Konfiguration reparieren oder Host wechseln

Arbeiten Sie die Punkte der Reihe nach ab und halten Sie die Ergebnisse neben dem betroffenen Workflow fest:

Die folgende Bewertung ist eine Diagnosepriorität, keine Messung von GitHub oder eine Aussage über die Zuverlässigkeit eines bestimmten Mac-Modells:

Beobachtung Zuerst prüfen Diagnosebewertung Nächste Entscheidung
GitHub zeigt den Runner als offline Host, Runner-Prozess, ausgehende Verbindung und _diag Hoch: Erreichbarkeit zuerst klären Netzwerk- oder Dienstursache beheben; erst bei wiederkehrender Host-Instabilität Betriebsform prüfen
Runner ist online, Job wartet runs-on, tatsächliche Labels und Gruppenrechte Hoch: Routingbedingungen direkt vergleichen YAML oder Berechtigungen korrigieren; kein Hostwechsel wegen eines Label-Fehlers
Runner fällt nach Neustart aus launchd, Benutzerkonto, Dienst- und Systemprotokolle Hoch: manuellen Start nicht als Dienstnachweis werten Dienstkonfiguration reparieren und Neustartverhalten erneut prüfen
Auftrag startet, Build bricht ab Workflow-Schritte, Worker-Protokolle, Abhängigkeiten und Rechte Mittel: konkrete Fehlerphase entscheidet Projekt- oder Umgebungsfehler beheben; Host nur bei belegter Ressourcen- oder Verfügbarkeitsursache wechseln

Wenn Sie diese Prüfung abschließen, sollten Sie eine belastbare Ursache statt einer Vermutung haben. Eine falsche Label- oder Gruppenregel verlangt eine Konfigurationskorrektur. Eine nicht funktionierende Verbindung verlangt eine Netzwerk- oder Infrastrukturprüfung. Erst wenn der Mac wiederholt nicht verfügbar ist oder der Betrieb des Dienstes Ihr Team dauerhaft überlastet, ist eine andere Hostlösung eine vernünftige Option.

Häufige Fragen zum macOS Runner

Was sollte ich bei einem offline gemeldeten Runner zuerst untersuchen?

Beginnen Sie beim Host und beim Prozess, nicht mit einer Änderung an der Workflow-YAML. Prüfen Sie dann, ob der Runner die erforderlichen GitHub-Endpunkte erreicht, und vergleichen Sie den Fehlerzeitpunkt mit den Dateien in _diag. So trennen Sie einen nicht verfügbaren Mac von einem Verbindungsfehler und von einer reinen Job-Routingfrage. Lassen Sie die TLS-Prüfung aktiviert.

Warum wartet ein Job, obwohl der Runner online ist?

Online bedeutet nicht automatisch „für diesen Job auswählbar“. Die Labels in runs-on müssen den Labels des Runners entsprechen, und die verwendete Runner-Gruppe muss Zugriff auf das Repository haben. Kontrollieren Sie beide Bedingungen in der aktuellen Konfiguration. Wenn sie nicht passen, beheben Sie Workflow oder Berechtigungen; ein anderer Mac würde denselben Routingfehler nicht beseitigen.

Wie prüfe ich launchd bei einem Runner, der nach dem Neustart ausfällt?

Prüfen Sie den Dienststatus im Runner-Installationsverzeichnis mit den dafür dokumentierten GitHub-Befehlen. Kontrollieren Sie zusätzlich das eingerichtete Benutzerkonto, Dateirechte und Dienstprotokolle. Testen Sie den Start nach dem Neustart über den Dienstmechanismus und nicht nur in einem Terminal. Nur so erkennen Sie, ob der Fehler an launchd oder an den interaktiven Startbedingungen hängt.

Welche Logs helfen bei einem Verbindungsfehler?

Ordnen Sie zuerst den Zeitpunkt im Workflow-Protokoll ein und vergleichen Sie ihn mit den Runner-Diagnosedateien im Ordner _diag. Runner-Protokolle geben Hinweise auf Verbindung und Auftragsannahme; Worker-Protokolle helfen bei der Ausführung eines bereits angenommenen Jobs. Prüfen Sie bei Verbindungsproblemen außerdem DNS, Proxy und Firewall anhand der konkreten Fehlermeldung, statt pauschal Zertifikatsprüfungen abzuschalten.

Wenn Ihre Logs wiederkehrende Ausfälle des Hosts oder einen hohen Aufwand für Verfügbarkeit und Dienstpflege belegen, kann ein dauerhaft erreichbarer Remote-Mac eine passende Betriebsoption sein. Sie müssen dabei weiterhin Workflow, Labels, Gruppenrechte und Build-Abhängigkeiten selbst korrekt konfigurieren; ein Wechsel der Maschine behebt diese Fehler nicht. Bei einem stabilen, langfristig stark ausgelasteten Eigenbetrieb oder wenn Sie lokale physische Schnittstellen benötigen, kann ein eigener Mac geeigneter sein. Wenn Sie dagegen eine zusätzliche Mac-Umgebung für wechselnde CI-Last oder zeitlich begrenzte Tests benötigen, vergleichen Sie zunächst die Informationen zur Mac-Umgebung und die Mietoptionen und Preise mit Ihrem Wartungsbedarf, bevor Sie Runner migrieren.

Häufig gestellte Fragen

Was sollte ich zuerst prüfen, wenn ein selbst gehosteter macOS Runner offline angezeigt wird?

Prüfen Sie zuerst, ob der Mac erreichbar ist und der Runner-Prozess beziehungsweise der konfigurierte Dienst läuft. Vergleichen Sie danach den Status in GitHub mit dem Zeitpunkt des letzten erfolgreichen Laufs und untersuchen Sie die Runner-Diagnoseprotokolle. Wenn der Host erreichbar ist, der Runner aber keine Verbindung aufbaut, prüfen Sie DNS, ausgehende Netzwerkverbindungen und Proxy- oder Firewall-Regeln, statt TLS-Prüfungen abzuschalten.

Warum bleibt ein macOS Job in GitHub Actions in der Warteschlange, obwohl ein Runner online ist?

Ein online angezeigter Runner ist nicht automatisch für jeden Job verfügbar. Die in „runs-on“ angeforderten Labels müssen zu den Labels des Runners passen; außerdem muss die Runner-Gruppe Zugriff auf das Repository beziehungsweise den Workflow haben. Prüfen Sie deshalb die konkrete Jobkonfiguration und die Gruppenberechtigungen. Ein neuer Mac behebt keine falschen Labels oder fehlenden Zugriffsrechte.

Wie kontrolliere ich den launchd-Dienst eines GitHub Actions Runners auf macOS?

Verwenden Sie im Installationsverzeichnis des Runners die von GitHub dokumentierten Dienstbefehle, um den Status zu prüfen und den Dienst bei Bedarf kontrolliert zu starten. Verifizieren Sie außerdem, unter welchem Benutzer der Dienst eingerichtet wurde, und lesen Sie die macOS-Dienstprotokolle sowie die Runner-Diagnosedateien. Ein erfolgreicher manueller Start beweist nicht, dass der Dienst nach einem Neustart automatisch läuft.

Welche Protokolle helfen bei Verbindungsfehlern des GitHub Actions Runners?

Ordnen Sie den Zeitpunkt des Fehlers zuerst dem Workflow-Protokoll zu und vergleichen Sie ihn dann mit den Diagnosedateien im Verzeichnis „_diag“ der Runner-Installation. Die Runner-Protokolle helfen bei Verbindungsaufbau und Auftragsannahme; Worker-Protokolle zeigen eher, was während eines konkreten Jobs geschah. Nutzen Sie bei Bedarf die offizielle Verbindungskontrolle und bewahren Sie die tatsächliche Fehlermeldung für den Vergleich mit DNS-, Proxy- und Firewall-Ereignissen auf.

Weiterlesen

Testen Sie eine separate Mac-Umgebung für Ihre CI

Wenn Ihr bisheriger macOS-Runner offline ist, können Sie mit VPSPull einen eigenen physischen Apple-Silicon-Mac für Ihre Builds und Tests einsetzen.