Was tun, wenn GitHub-Actions-macOS-Runner in der Warteschlange stehen? Abnahmecheckliste für selbst gehostete Runner 2026

Drei unterstützte Betriebssystemfamilien – und diese Woche zuerst die Zuweisung prüfen

GitHub dokumentiert Runner für drei Betriebssystemfamilien: Linux, Windows und macOS (Übersicht zu selbst gehosteten Runnern). Das sagt jedoch nicht, warum ein bestimmter macOS-Auftrag wartet. Prüfen Sie zuerst die runs-on-Labels, den Online-Status des Runners und die Zugriffsrechte der Runner-Gruppe. Erst wenn diese Punkte stimmen und die verfügbare Kapazität oder eine feste Wartungsumgebung tatsächlich der Engpass ist, sollten Sie einen selbst gehosteten macOS Runner erwägen.

Diese Woche: Sichern Sie zuerst den fehlgeschlagenen Workflow-Lauf und seine Protokolle. Führen Sie anschließend einen minimalen Testlauf aus und arbeiten Sie die Abnahmechecks für Annahme, Build, Wiederherstellung und Bereinigung ab. Eine zusätzliche Maschine behebt keine falschen Labels und keine fehlenden Berechtigungen.

Dieser Leitfaden ist für Sie, wenn Sie GitHub-Actions-Workflows für iOS- oder macOS-Projekte pflegen und Aufträge nicht zuverlässig zugewiesen werden.
Er hilft Ihnen, einen selbst gehosteten macOS Runner nach einer Migration oder Neueinrichtung systematisch zu prüfen.
Wenn Sie Runner betreiben, können Sie daraus außerdem konkrete Wiederherstellungs- und Überwachungsprüfungen ableiten.

Warteschlange, fehlende Annahme oder Buildfehler – zuerst den Zustand trennen

Ein Warteschlangenstatus und ein fehlgeschlagener Build sind unterschiedliche Befunde. Wird ein Auftrag nicht zugewiesen, kommt der Runner möglicherweise nicht infrage oder kann den Auftrag nicht erreichen. Ist der Runner online, aber nimmt den Auftrag nicht an, müssen Sie zusätzlich den Dienstzustand und die Erreichbarkeit untersuchen. Startet der Auftrag und schlägt erst danach ein Schritt fehl, liegt der Fehler im laufenden Workflow oder in dessen Umgebung.

Notieren Sie vor Änderungen den Link zum Workflow-Lauf, den Namen des Jobs, die verwendeten runs-on-Angaben und den sichtbaren Runner-Status. Sichern Sie die Jobprotokolle, bevor Sie Dienste neu starten oder Einstellungen ändern. So können Sie später unterscheiden, ob sich die Zuweisung oder nur das Buildverhalten verändert hat.

Beobachtung im Workflow	Wahrscheinlicher Prüfbereich	Nächster sinnvoller Nachweis
Job bleibt in der Warteschlange; kein Runner führt ihn aus	Labels, Runner-Gruppe, Verfügbarkeit	`runs-on` mit den Runner-Labels und dem Gruppenbereich vergleichen
Runner wird angezeigt, aber der Job beginnt nicht	Dienstzustand, Netzwerk, Erreichbarkeit	Status des Runner-Dienstes und die Runner-Protokolle prüfen
Job beginnt und schlägt in einem Schritt fehl	Xcode, Abhängigkeiten, Signierung, Geheimnisse	Fehlgeschlagenen Schritt und dessen konkrete Fehlermeldung sichern
Job ist abgeschlossen, aber Dateien bleiben zurück	Workspace, temporäre Daten, Zugangsdaten	Zustand des Arbeitsverzeichnisses und der Bereinigung nach dem Lauf prüfen

Warum bleibt ein GitHub-Actions-macOS-Runner in der Warteschlange? Eine einzelne Ursache lässt sich aus dem Warteschlangenstatus nicht ableiten. Häufige Prüfbereiche sind nicht übereinstimmende Labels, eine Runner-Gruppe ohne Zugriff auf das Repository, ein offline befindlicher Runner oder eine fehlende passende Kapazität. Behandeln Sie diese Punkte als Diagnosemöglichkeiten, nicht als pauschale Erklärung. GitHub beschreibt die Zuweisung über Anforderungen des Workflows und verfügbare Runner; gleichen Sie deshalb den konkreten Job mit den Regeln zur Auswahl eines Runners im Workflow ab.

Achtung: Ein grüner oder online angezeigter Runner beweist nur, dass er erreichbar beziehungsweise registriert ist. Er beweist nicht, dass das Repository ihn verwenden darf oder dass seine Labels die Jobanforderungen erfüllen.

Passende Labels und Rechte – statt auf Verdacht zusätzliche Macs zu starten

Bei selbst gehosteten Runnern entscheidet die Kombination der Jobanforderungen darüber, ob ein Runner für einen Auftrag infrage kommt. Kontrollieren Sie deshalb die Schreibweise jedes Labels in runs-on und vergleichen Sie sie mit den tatsächlich zugewiesenen Runner-Labels. GitHub erklärt, wie Labels einem Runner hinzugefügt werden und wie diese Angaben für die Zuordnung verwendet werden (Dokumentation zu Runner-Labels).

Prüfen Sie anschließend die Ebene, auf der der Runner registriert ist: Repository, Organisation oder Unternehmen. Eine Registrierung auf einer höheren Ebene bedeutet nicht automatisch, dass jedes Repository darauf zugreifen darf. Runner-Gruppen können den Zugriff zusätzlich beschränken. Stimmen die Labels, aber die Gruppe schließt das Repository aus, führt ein weiterer Mac nicht zur Lösung. Die Dokumentation zu Zugriffsrichtlinien für Runner-Gruppen beschreibt die relevanten Zugriffskontrollen und Sicherheitsaspekte.

Der Runner ist online, aber der Workflow startet nicht: Was prüfen Sie? Vergleichen Sie zuerst die effektiven Jobanforderungen mit den Labels. Prüfen Sie danach, ob die Gruppe des Runners für das Repository freigegeben ist und ob der Workflow tatsächlich in diesem Repository und Kontext läuft. Bei Unsicherheit hilft ein kleiner Testjob, der keine Signierung, privaten Abhängigkeiten oder projektspezifischen Buildschritte voraussetzt.

Führen Sie diesen Test nicht als bloße Konfigurationsprobe ohne Ergebnisprüfung aus. Er muss tatsächlich auf dem vorgesehenen Runner starten. Prüfen Sie im Lauf, welcher Runner den Job bearbeitet hat und ob der Job die erwarteten Basisinformationen ausgeben kann. Ein minimaler Test reduziert Variablen: Scheitert bereits die Zuweisung, ist das kein Xcode- oder Paketmanagerproblem.

Erster Schritt: Einen minimalen Zuweisungstest durchführen

Erfassen Sie die Labels, die der Job in runs-on verlangt.
Vergleichen Sie diese mit den Labels des gewünschten Runners.
Prüfen Sie die Freigabe der Runner-Gruppe für das betreffende Repository.
Starten Sie einen temporären Job ohne Build, Signierung und private Abhängigkeiten.
Verifizieren Sie im Workflow-Lauf, dass genau der vorgesehene Runner den Job angenommen hat.
Entfernen Sie den Testjob oder kennzeichnen Sie ihn klar als Diagnoseworkflow.

Wenn der Testjob nicht zugewiesen wird, beheben Sie zuerst Labels und Zugriffsbereich. Wenn er ausgeführt wird, aber der eigentliche Build scheitert, wechseln Sie zur Builddiagnose. Diese Trennung verhindert, dass Sie ein Zugriffsproblem durch eine neue Maschine „reparieren“ wollen.

Offline oder nach Neustart nicht verfügbar – Dienst und Wiederherstellung getrennt testen

Ein Runner kann korrekt registriert sein und später trotzdem offline gehen. Mögliche Gründe sind ein beendeter Dienst, ein Neustart ohne automatischen Wiederanlauf oder eine unterbrochene Netzwerkverbindung. Der Status in der Runner-Übersicht ist daher nur ein Teil der Prüfung. Sie brauchen auch einen betrieblichen Nachweis, dass der Dienst nach einer Störung wieder erreichbar wird.

GitHub stellt Hinweise für Überwachung und Fehlerbehebung bei selbst gehosteten Runnern bereit. Nutzen Sie diese neben den lokalen Systemprotokollen. Halten Sie fest, welche Meldung auf eine Unterbrechung hinweist, wer benachrichtigt wird und welche Schritte zur Wiederherstellung erlaubt sind. Vermeiden Sie eine automatische Endlosschleife aus Neustarts: Sie kann den ursprünglichen Fehler verdecken, ohne die Ursache zu beheben.

Für eine aussagekräftige Abnahme sollten Sie kontrolliert drei Situationen prüfen: einen normalen Start, einen Neustart des Rechners und eine kurzzeitige Unterbrechung der Verbindung. Dokumentieren Sie jeweils, ob der Runner wieder online erscheint und ob anschließend ein Testjob angenommen wird. Legen Sie außerdem fest, ab welchem beobachteten Zustand ein Alarm ausgelöst wird. Eine nicht definierte Reaktionszeit lässt sich nicht zuverlässig überwachen; wählen Sie den Grenzwert anhand Ihrer eigenen Buildanforderungen, statt eine allgemeingültige Zahl zu übernehmen.

Betriebshinweis: Testen Sie den Wiederanlauf nicht während eines wichtigen Release-Builds. Verwenden Sie einen geplanten Wartungszeitraum und einen Testworkflow, dessen Abbruch keine Veröffentlichung oder Signierung auslöst.

Prüffall	Was Sie gezielt auslösen	Abnahmekriterium
Normalbetrieb	Runner starten und Testjob ausführen	Job wird angenommen und endet mit nachvollziehbarem Status
Neustart	System kontrolliert neu starten	Runner-Dienst startet wieder und nimmt einen neuen Testjob an
Verbindungsunterbrechung	Netzwerkzugriff im Wartungsfenster kurzzeitig unterbrechen	Zustand wird sichtbar; nach Wiederherstellung ist ein neuer Test möglich
Fehlersignal	Diagnoseereignis auslösen oder vorhandene Meldung prüfen	Zuständigkeit, Alarmweg und Wiederherstellungsschritt sind dokumentiert

Job gestartet, Build fehlgeschlagen – Werkzeugkette statt Runner-Kapazität prüfen

Sobald der Job begonnen hat, ist die Frage „Wird der Runner zugewiesen?“ zunächst beantwortet. Ein danach auftretender Fehler kann trotzdem von der Maschine abhängen: etwa wenn die erwartete Xcode-Version fehlt, Abhängigkeiten nicht erreichbar sind oder Signierungsdaten nicht korrekt eingebunden wurden. Erfassen Sie den fehlerhaften Schritt und seine Ausgabe, bevor Sie die Runner-Anzahl verändern.

Vergleichen Sie die im Projekt erwartete Xcode-Version mit der installierten Umgebung. Apples Systemanforderungen für Xcode helfen dabei, die unterstützte Kombination aus Xcode und Betriebssystem zu prüfen. Sie sind jedoch kein Nachweis dafür, dass ein konkretes Projekt erfolgreich baut: Projektabhängigkeiten, SDK-Anforderungen und Signierung müssen Sie zusätzlich im eigenen Workflow verifizieren.

Gehen Sie bei einem fehlgeschlagenen Build in dieser Reihenfolge vor:

Fehlgeschlagenen Schritt bestimmen. Unterscheiden Sie Checkout, Abhängigkeitsinstallation, Kompilierung, Tests und Signierung.
Werkzeugkette erfassen. Prüfen Sie Xcode- und Betriebssystemversion sowie die im Job aufgerufenen Werkzeuge.
Abhängigkeiten prüfen. Verifizieren Sie Netzwerkzugriff, Paketquellen und erforderliche Authentifizierung.
Signierung gesondert testen. Prüfen Sie, ob Zertifikate und Profile verfügbar sind und nur dort verwendet werden, wo sie benötigt werden.
Zuweisung und Buildfehler getrennt dokumentieren. Ein erfolgreicher Start mit späterem Fehler ist keine Warteschlangenstörung.

GitHub Actions unterstützt zusätzliche Diagnoseinformationen über Debug-Protokollierung für Workflows. Aktivieren Sie Debug-Ausgaben gezielt für einen Diagnosefall und prüfen Sie vorher, welche Informationen in den Protokollen erscheinen können. Protokolle können interne Pfade oder andere sensible Details enthalten. Beschränken Sie den Zugriff und deaktivieren Sie zusätzliche Protokollierung wieder, wenn sie für die Diagnose nicht mehr erforderlich ist.

Nach dem Job bleiben Dateien oder Zugangsdaten zurück – Bereinigung als Sicherheitsprüfung

Ein erfolgreicher Workflow ist noch keine vollständige Abnahme, wenn Arbeitsdateien oder Geheimnisse für nachfolgende Jobs erreichbar bleiben. Bei dauerhaft genutzten Maschinen ist besonders wichtig, welche Jobs dieselbe Umgebung nacheinander verwenden und ob sie einander vertrauen dürfen. Ein Cache kann Builds beschleunigen, ist aber kein geeigneter Ort für Signierungsdaten, temporäre Schlüssel oder sonstige Geheimnisse.

Legen Sie fest, welche Daten nach jedem Job gelöscht werden müssen. Dazu gehören projektspezifische Arbeitsdateien, temporäre Dateien und Material, das nur für einen begrenzten Signierungsschritt bereitgestellt wird. Prüfen Sie anschließend nicht nur, ob ein Bereinigungsschritt im YAML steht, sondern ob er auch nach einem fehlgeschlagenen Job ausgeführt wird. Ein Bereinigungsschritt, der nur bei Erfolg läuft, lässt gerade nach einem Abbruch möglicherweise Reste zurück.

Für jedes Geheimnis sollten Sie beantworten können: Wo wird es bereitgestellt? Welcher Job benötigt es? Wann wird es entfernt oder widerrufen? Wer darf die Protokolle des Laufs einsehen? Prüfen Sie zudem, ob unterschiedliche Workflows dieselbe Maschine nutzen dürfen. Wenn die Vertrauensgrenzen nicht klar sind, begrenzen Sie die gemeinsame Nutzung, statt sensible Dateien über Caches oder gemeinsame Verzeichnisse zugänglich zu machen.

Ein hilfreicher interner Abnahmeschritt ist die Prüfung nach einem erfolgreichen und einem absichtlich fehlgeschlagenen Testlauf. Kontrollieren Sie danach das Arbeitsverzeichnis, temporäre Ablagen und die Verfügbarkeit der Zugangsdaten. Nehmen Sie nur die tatsächlich erforderlichen Cachepfade in die Wiederverwendung auf. So vermeiden Sie, dass ein vermeintlicher Leistungsvorteil unbemerkt zum Zugriffspfad auf vertrauliche Buildartefakte wird.

Bedingungen statt Bauchgefühl – wann sich ein selbst gehosteter Runner lohnt

Ein selbst gehosteter macOS Runner ist keine automatische Entlastung. Er verlagert Verantwortung für Registrierung, Updates, Netzwerkzugriff, Verfügbarkeit und Bereinigung auf Ihr Team oder Ihren Dienstleister. Bevor Sie wechseln oder zusätzliche Runner bereitstellen, prüfen Sie, ob das Problem überhaupt auf fehlende Kapazität zurückgeht.

Entscheiden Sie anhand dieser Bedingungen:

Wenn Labels oder Runner-Gruppen nicht stimmen: Korrigieren Sie zuerst Workflow- und Zugriffsregeln. Fügen Sie keine Maschine hinzu.
Wenn der Runner offline ist oder nach einem Neustart nicht startet: Reparieren Sie Dienst, Netzwerk oder Wiederanlauf und wiederholen Sie den Test. Neue Kapazität behebt keinen unterbrochenen Dienst.
Wenn der Job startet und erst im Build scheitert: Prüfen Sie Xcode, Abhängigkeiten, Signierung und Geheimnisse. Skalieren Sie nicht aufgrund eines Buildfehlers.
Wenn die Zuordnung stimmt, der Runner erreichbar ist und nachvollziehbar zu wenig verfügbare Ausführungskapazität besteht: Bewerten Sie zusätzliche oder selbst gehostete Runner anhand von Wartungsaufwand, Zugriffsschutz und Auslastung.
Wenn Ihr Team eine reproduzierbare, fest betreute macOS-Umgebung benötigt: Testen Sie die Umgebung mit einem realen Projektworkflow und dokumentieren Sie Zuständigkeit, Updateprozess und Bereinigung vor dem Produktivbetrieb.

Der Vergleich mit einem GitHub-gehosteten Runner sollte nicht nur die Bereitstellung betrachten. Ein gehosteter Runner erspart Ihnen die unmittelbare Verwaltung des zugrunde liegenden Rechners, bietet aber weniger Kontrolle über dessen dauerhafte Wartung und konkrete Umgebung. Ein selbst gehosteter Runner kann die Umgebung gezielter an Ihre Prozesse anpassen, verlangt dafür jedoch laufende Pflege, sichere Geheimnisverwaltung und einen getesteten Wiederanlauf. Welche Variante wirtschaftlicher ist, hängt von Ihrer tatsächlichen Nutzung und den internen Betriebskosten ab; ohne belastbare Daten ist eine pauschale Kostenbehauptung nicht sinnvoll.

Abnahme in fünf Bereichen – erst danach produktive Builds umstellen

Nutzen Sie die folgende Liste für eine nachvollziehbare Freigabe. Ein Punkt gilt erst als bestanden, wenn Sie dafür einen konkreten Nachweis aus einem Workflow-Lauf oder einem dokumentierten Betriebstest haben.

[ ] Annahme: Ein minimaler Workflow wird vom vorgesehenen Runner angenommen; Labels und Runner-Gruppe sind dokumentiert.
[ ] Build: Ein repräsentativer Projektbuild läuft mit der erwarteten Xcode- und Abhängigkeitskonfiguration durch.
[ ] Alarmierung: Ein Offline- oder Fehlerzustand wird sichtbar, und Zuständigkeit sowie Reaktionsweg sind festgehalten.
[ ] Wiederherstellung: Nach einem kontrollierten Neustart oder einer Netzwerkunterbrechung kann der Runner wieder einen Testjob ausführen.
[ ] Bereinigung: Arbeitsdateien und temporäre Zugangsdaten werden nach Erfolg und Fehler entfernt; Cachepfade enthalten keine sensiblen Daten.

Nach einer Migration sollten Sie nicht nur denselben YAML-Workflow starten und auf ein grünes Ergebnis schauen. Prüfen Sie zusätzlich, ob der Lauf auf dem erwarteten Runner stattfand, ob die benötigten Werkzeuge wirklich aus der vorgesehenen Umgebung kamen und ob die Bereinigung nach dem Ende wirksam war. Verändert sich ein Buildverhalten, vergleichen Sie die protokollierten Werkzeugversionen und den fehlgeschlagenen Schritt. So lassen sich Umgebungsabweichungen von Anwendungsfehlern unterscheiden.

Wenn Sie Zugriffsrechte und Zuständigkeiten dokumentieren möchten, prüfen Sie ergänzend die geltenden Servicebedingungen. Für konkrete Fragen zur passenden Umgebung können Sie auch die Hilfeübersicht heranziehen. Diese Seiten ersetzen nicht die technische Abnahme Ihres Workflows; maßgeblich bleibt, ob Ihr eigener Testjob die geforderten Schritte erfolgreich durchläuft.

Wenn Ihre aktuelle Lösung auf einem gemeinsam genutzten Rechner oder einer spontan eingerichteten Maschine läuft, können Wartungsfenster, wechselnde Werkzeugstände und unklare Zuständigkeiten die Fehleranalyse erschweren. Ein gemieteter Mac von Hashvps kann dann eine passendere Option sein, sofern die angebotene Umgebung Ihre Anforderungen an Runner-Zugriff, Arbeitsabläufe und Betrieb tatsächlich erfüllt. Vergleichen Sie die Angaben auf der Übersichtsseite der Pakete mit Ihrer Abnahmeliste, bevor Sie migrieren. Wenn lediglich Labels oder Berechtigungen falsch gesetzt sind, beheben Sie diese zuerst; ein Wechsel der Maschine ist dafür nicht erforderlich.