GitHub Actions Mac Runner ständig in der Warteschlange: Reparaturleitfaden 2026

Der erste Befund entscheidet über die weitere Spur

Ein Runner-Dashboard mit dem Status „Idle“ beweist allein nicht, dass ein bestimmter Job ihn verwenden darf. GitHub Actions bewertet unter anderem die im Workflow angegebenen runs-on-Labels, die Zugehörigkeit zu einer Runner Group, die Freigabe für das Repository sowie den Online- und Bereitschaftszustand des Knotens. Die offizielle Referenz zur Auswahl eines Runners beschreibt diese Zuordnung als Kombination aus Anforderungen, nicht als einfache Suche nach irgendeinem freien Mac.

Beginnen Sie deshalb mit einem unveränderten Belegsatz:

1. Öffnen Sie den betroffenen Workflow-Lauf und notieren Sie den Job-Namen.
2. Sichern Sie den vollständigen runs-on-Ausdruck aus der Workflow-Datei.
3. Erfassen Sie Runner-Labels, Runner Group, Repository-Freigabe und aktuellen Zustand.
4. Kopieren Sie die Job-Anmerkung oder den sichtbaren Wartestatus.
5. Frieren Sie YAML, Labels und Zugriffsregeln während der ersten Diagnose ein.

Damit wird verhindert, dass eine vermeintliche Reparatur lediglich die ursprüngliche Ursache verdeckt. Ein Job kann vor dem eigentlichen Runner-Routing warten, etwa wegen einer Freigabe oder einer Parallelitätsregel. GitHub dokumentiert solche Concurrency-Einstellungen für Workflows getrennt von der Auswahl eines selbst gehosteten Runners.

Warum nimmt ein online angezeigter self-hosted runner keinen Auftrag an?
Weil „online“ nur eine Teilbedingung ist. Der Prozess kann zwar mit der Plattform kommunizieren, aber wegen falscher Labels, fehlender Group-Berechtigung, eines nicht nutzbaren Arbeitsverzeichnisses oder eines instabilen Dienstes keinen Job erfolgreich übernehmen. Die offizielle Routing-Referenz für selbst gehostete Runner sollte deshalb parallel zum Dashboard geöffnet werden.

Label-Routing und Runner Group getrennt prüfen

Zweite Spur: runs-on vollständig gegen den Knoten abgleichen

Ein runs-on-Array ist eine Schnittmenge: Werden mehrere Labels angegeben, muss derselbe Runner alle Anforderungen erfüllen. Ein typisches Beispiel ist:

jobs:
  build:
    runs-on: [self-hosted, macos, arm64, xcode-ci]
    steps:
      - name: Diagnose
        run: |
          uname -m
          sw_vers
          echo "runner=$RUNNER_NAME"

Die Begriffe self-hosted, Betriebssystem, Architektur und internes Werkzeug-Label müssen auf dem ausgewählten Knoten tatsächlich vorhanden sein. Ein falsch geschriebenes benutzerdefiniertes Label genügt, damit der Job keinen geeigneten Runner findet. Ebenso problematisch ist ein nach einer Neuaufnahme oder Neuinstallation nicht wieder gesetztes Label. Die Dokumentation zu selbst gehosteten Runner-Labels ist für die aktuelle Oberfläche und die zulässigen Verwaltungsschritte maßgeblich.

Für die Diagnose sollte die Produktionsdefinition nicht dauerhaft auf ein allgemeines Label wie self-hosted reduziert werden. Dadurch könnte ein ungeeigneter Knoten Signierung, Simulator-Tests oder einen sensiblen Build übernehmen. Verwenden Sie stattdessen einen kurzlebigen Testjob ohne Geheimnisse:

name: runner-route-check

on:
  workflow_dispatch:

jobs:
  route:
    runs-on: [self-hosted, macos, arm64, xcode-ci]
    steps:
      - run: |
          printf 'name=%s\n' "$RUNNER_NAME"
          printf 'os=%s\n' "$RUNNER_OS"
          uname -m

Die Ausgabe muss zeigen, dass der Job auf dem erwarteten Knoten startet. Falls der Job weiterhin wartet, ist nicht die Xcode-Projektdatei die erste Spur, sondern die Kombination aus Label und Zugriffsregel.

Dritte Spur: Runner Group und Repository-Grenze

Labels zeigen, welcher Runner technisch passen könnte. Sie gewähren einem Repository jedoch nicht automatisch die Nutzung. Eine Runner Group kann auf Organisationsebene eingeschränkt sein; der betreffende Repository-Zugriff muss ausdrücklich zulässig sein. Die GitHub-Anleitung zur Verwaltung von Runner Groups beschreibt diese Zugriffsebene getrennt vom Label-Mechanismus.

Warum kann eine Runner Group für ein bestimmtes Repository unbrauchbar sein, obwohl das Label stimmt?
Weil Label-Matching und Zugriffskontrolle nacheinander wirken. Für einen sicheren Test wird eine harmlose Workflow-Datei in einem isolierten Repository verwendet. Vor und nach der Regeländerung sollte dokumentiert werden, welche Runner in der Verwaltungsansicht sichtbar und tatsächlich auswählbar sind.

Das Aufweiten einer Group auf die gesamte Organisation ist keine neutrale Reparatur. Es kann Builds auf einen Knoten lenken, der für andere Projekte, Geheimnisse oder Signaturvorgänge nicht vorgesehen ist. Ändern Sie die Berechtigung nur mit einer Rückkehrmöglichkeit: alte Regel exportieren oder dokumentieren, Testlauf durchführen, anschließend die ursprüngliche Einschränkung wiederherstellen, falls das Routingproblem an anderer Stelle liegt.

Belegung von echter Kapazitätsgrenze unterscheiden

Sind Labels und Group korrekt, prüfen Sie, ob alle passenden Runner wirklich beschäftigt sind. Dafür reicht die Anzeige „Busy“ nicht immer aus. Ordnen Sie jedem aktiven Job einen Prozess, ein Arbeitsverzeichnis und einen erwarteten Abschluss zu. Ein beendeter Workflow mit zurückgebliebenem Prozess kann einen Knoten ebenso blockieren wie ein lange laufender Simulator-Test.

Typische Exklusivitätsursachen sind:

• Xcode-Kompilierung mit großen Zwischenartefakten oder mehreren Zielvarianten;
• Simulator-Tests, die nach einem Testabbruch weiterlaufen;
• Signierung und Veröffentlichung, die bewusst nur auf einem geschützten Knoten stattfinden;
• lang laufende Skripte, die das Arbeitsverzeichnis oder eine Sperrdatei offen halten;
• parallele Jobs, die zwar logisch getrennt, auf demselben Mac aber praktisch nicht sicher gleichzeitig ausführbar sind.

Für eine vorsichtige Bestandsaufnahme können Sie auf dem Mac zunächst nur lesend arbeiten:

ps -axo pid,etime,user,command | egrep 'Runner|xcodebuild|simctl|fastlane' | head -n 40
launchctl print system | grep -i runner
df -h

Die Ausgabe ist kein Beweis für eine ausreichende oder unzureichende Kapazität. Sie zeigt lediglich, ob ein Runner-Prozess, typische Build-Prozesse und der Dienst sichtbar sind. Bei produktiven Signatur- oder Release-Jobs sollte vor dem Beenden eines Prozesses der zuständige Build-Verantwortliche zustimmen. Ein erzwungener Abbruch kann Artefakte, Logs oder Zwischenstände unvollständig hinterlassen.

Wann sollte die Organisation einen weiteren Remote-Mac-Runner hinzufügen?
Erst dann, wenn ein minimaler Testjob, ein realer Xcode-Build und ein produktionsnaher Job mit Ziel-Labels erfolgreich routen, die vorhandenen Runner nachweislich gesund sind und echte Warteschlangen trotz wiederholbarer Belegung bestehen bleiben. Ein einzelner sichtbarer Rückstau reicht nicht für eine Kapazitätsentscheidung.

Idle-Anzeige und macOS-Dienst sind verschiedene Befunde

Ein SSH-Zugang oder eine grafische Sitzung beweist nicht, dass der Runner-Dienst stabil läuft. Der Dienst kann unter einem anderen Benutzer gestartet sein, ein nicht beschreibbares Arbeitsverzeichnis verwenden oder nach einem Neustart nicht wieder aufgenommen worden sein. Für macOS stellt GitHub eine eigene Monitoring- und Troubleshooting-Dokumentation für selbst gehostete Runner bereit.

Prüfen Sie in dieser Reihenfolge:

1. Öffnen Sie die Runner-Verwaltung und vergleichen Sie den angezeigten Zustand mit dem lokalen Prozess.
2. Sichern Sie Diagnose- und Dienstprotokolle, bevor Sie den Dienst neu starten.
3. Prüfen Sie Benutzerkonto, Arbeitsverzeichnis und Schreibrechte.
4. Kontrollieren Sie die Netzwerkverbindung während eines Testlaufs, nicht nur bei einer interaktiven SSH-Sitzung.
5. Überprüfen Sie, ob der Dienst nach einem macOS-Neustart automatisch wieder erscheint.
6. Starten Sie erst danach den Dienst kontrolliert neu und protokollieren Sie die Zustandsänderung.

Ein mögliches lokales Muster für eine reine Zustandsprüfung lautet:

launchctl print gui/$(id -u) | grep -i runner
tail -n 100 ~/actions-runner/_diag/*.log

Die konkrete Dienstdomäne und der Pfad hängen von der verwendeten Runner-Installation ab. Deshalb sollte kein fremdes launchd-Beispiel ungeprüft übernommen werden. Vor einer Neuinstallation oder erneuten Registrierung müssen Registrierungsdaten, Arbeitsverzeichnis, Logdateien und die geplante Rückfallprozedur gesichert werden.

Die Entfernung eines Runners ist außerdem kein gewöhnlicher Neustart. Die offizielle Anleitung zum Entfernen selbst gehosteter Runner sollte vor diesem Schritt geprüft werden. Ein erneutes Registrieren behebt kein falsches runs-on-Label und keine fehlende Group-Berechtigung.

Vierte Spur: kontrollierte Reparatur statt Änderungen im Blindflug

Die folgende Reihenfolge begrenzt die Auswirkungen und erzeugt nach jeder Änderung einen prüfbaren Befund:

1. Workflow einfrieren: Kopieren Sie Commit, runs-on, Group-Konfiguration und Job-Status in ein Incident-Dokument.
2. Vorbedingungen ausschließen: Prüfen Sie Abhängigkeiten, manuelle Freigaben und Concurrency-Regeln, bevor Sie den Mac untersuchen.
3. Label-Matrix erstellen: Listen Sie pro Runner Betriebssystem, Architektur, benutzerdefinierte Labels und Group auf.
4. Minimalen Diagnosejob ausführen: Verwenden Sie keine Signaturgeheimnisse und keine produktiven Artefakte.
5. Group-Zugriff isoliert testen: Erlauben Sie nur dem Test-Repository den notwendigen Zugriff und dokumentieren Sie die Änderung.
6. Belegung zuordnen: Verbinden Sie aktive Jobs mit Prozessen, Arbeitsverzeichnissen und erwarteten Endbedingungen.
7. Dienst stabilisieren: Sichern Sie Logs, prüfen Sie launchd, Benutzerrechte und Neustartverhalten und starten Sie erst dann kontrolliert neu.
8. Nur bei dokumentiertem Registrierungsfehler neu registrieren: Bewahren Sie vorher die alte Konfiguration und die Wiederherstellungsinformationen auf.
9. Kapazität erst danach bewerten: Teilen Sie Build-, Test- und Release-Aufgaben gegebenenfalls in getrennte Runner-Pools auf.
10. Reproduzierbaren Abschluss dokumentieren: Halten Sie Routing, Start, Ausführung und Artefakt-Rückgabe getrennt fest.

Die offiziellen Hinweise zur Nutzung selbst gehosteter Runner in Workflows sollten bei Änderungen am YAML neben der tatsächlichen Konfiguration geprüft werden. So lässt sich vermeiden, dass ein syntaktisch gültiger, aber organisatorisch unpassender Runner ausgewählt wird.

Reparatur, Neuaufbau oder Erweiterung anhand einer Prüfliste entscheiden

• [ ] Der wartende Job ist nicht durch eine Vorbedingung, Genehmigung oder Concurrency-Regel blockiert.
• [ ] Der vollständige runs-on-Ausdruck wurde unverändert gesichert.
• [ ] Alle Labels existieren auf demselben Mac und sind korrekt geschrieben.
• [ ] Betriebssystem, Architektur und erforderliche Werkzeug-Labels stimmen mit dem Job überein.
• [ ] Die Runner Group erlaubt die Nutzung durch das Ziel-Repository.
• [ ] Ein Testjob ohne Geheimnisse erreicht genau den erwarteten Runner.
• [ ] Aktive Jobs, Runner-Prozesse und Arbeitsverzeichnisse wurden einander zugeordnet.
• [ ] Ein „Idle“-Runner wurde lokal über Prozess, Diagnose-Log und macOS-Dienst geprüft.
• [ ] Vor Dienständerung, Entfernung oder erneuter Registrierung existiert ein Rückfallpfad.
• [ ] Minimaljob, echter Xcode-Build und produktionsnaher Ziel-Label-Job wurden getrennt wiederholt.
• [ ] Die Artefakt- und Log-Rückgabe wurde nach der Ausführung bestätigt.
• [ ] Eine Erweiterung wird nur wegen anhaltender echter Belegung, nicht wegen eines Routingfehlers beschlossen.

Für einen neuen oder gemieteten Knoten ist dieselbe Abnahme erforderlich: Label- und Group-Routing, Dienststart nach Neustart, SSH- und Logzugriff, minimaler Workflow, echter Build sowie sichere Rückgabe der Artefakte. Das ist keine Installationsanleitung, sondern eine Trennung der möglichen Fehlerklassen.

Remote Mac als kontrollierter Ersatz- oder Testpfad

Wenn der vorhandene Knoten trotz korrekter Labels, Group-Rechte und Dienstprüfung nicht stabil Jobs annimmt, kann eine isolierte Remote-Mac-Umgebung den Fehler reproduzierbar eingrenzen. NodeMini stellt dafür eine zeitweise oder länger laufende Mac-Umgebung mit Zugriff per SSH, VNC oder Web-Konsole bereit. Die Entscheidung sollte jedoch erst nach der technischen Diagnose fallen: Für dauerhaft hohe, planbare Last kann ein eigener physischer Knoten wirtschaftlich sinnvoller sein; für einen zeitlich begrenzten Ersatz, einen zweiten Runner oder eine kontrollierte Wiederholung eines CI-Fehlers ist Miete flexibler.

Im Vergleich zum aktuellen Einzelknoten bleiben bei einer rein lokalen Lösung drei typische Nachteile: Wartungsarbeiten unterbrechen die Pipeline, ein einzelner defekter Dienst bildet einen Ausfallpunkt, und ein Kapazitätsengpass lässt sich nicht kurzfristig isolieren. Ein zusätzlicher Remote Mac kann diese Risiken nicht automatisch beseitigen, aber er ermöglicht einen getrennten Runner mit eigenen Labels, einer eigenen Group-Regel und einer nachvollziehbaren Abnahme. Informationen zur Mac-Mietlösung von NodeMini sollten deshalb erst nach der Label-, Rechte- und Dienstprüfung mit den betrieblichen Anforderungen abgeglichen werden.

Wer zunächst die laufende Umgebung strukturiert bewerten möchte, kann die Mac-mini-Optionen für Entwickler als Vergleichspunkt verwenden. Entscheidend bleiben dabei nicht ein sichtbarer „Idle“-Status oder die bloße Anzahl der Geräte, sondern ein belegbarer Weg von runs-on über Group-Zugriff und Dienstaufnahme bis zur erfolgreichen Xcode-Ausführung und Artefakt-Rückgabe.