GitHub Actions: Mac Runner selbst hosten? 2026

GitHub dokumentiert drei Standardlabels für selbstgehostete Runner: self-hosted, Betriebssystem und Prozessorarchitektur (GitHub zur Runner-Kennzeichnung). Daraus folgt die wichtigste Entscheidung: Richten Sie einen selbstgehosteten Mac Runner für GitHub Actions nur ein, wenn ein Workflow macOS oder Mac-spezifische Werkzeuge benötigt und der Host zuverlässig erreichbar bleibt. Beginnen Sie in einem kontrollierten Repository mit Registrierung, Dienststart und einem risikoarmen Test.

Dieser Leitfaden richtet sich an unabhängige iOS- und macOS-Entwickler, die Builds auf einem Mac ausführen müssen.
Auch freie Entwickler und kleine Remote-Teams finden hier den Ablauf – einschließlich Wartung und Rechteprüfung.
Wenn Ihre Aufgaben keine macOS-Umgebung brauchen, ist ein Mac Runner meist unnötige zusätzliche Betriebsarbeit.

Vor dem Einrichten klären, ob ein Mac Runner wirklich nötig ist

Ein selbstgehosteter Runner ist ein Rechner, den Sie selbst bereitstellen und verwalten. GitHub Actions kann darauf Workflows ausführen, aber Sie verantworten unter anderem Betriebssystem, installierte Software und Verfügbarkeit. Bei einem von GitHub verwalteten Runner liegt ein größerer Teil dieser Hostverwaltung bei GitHub. Die Abgrenzung und die betrieblichen Pflichten beschreibt GitHubs Übersicht zu selbstgehosteten Runnern.

Der entscheidende Test lautet nicht „Verwenden wir GitHub Actions?“, sondern: „Benötigt dieser konkrete Job macOS oder eine bestimmte Mac-Umgebung?“ Ein iOS-Build, ein Test mit Xcode oder ein macOS-spezifisches Werkzeug kann einen Mac voraussetzen. Ein plattformübergreifender Lint- oder Dokumentationsjob dagegen nicht automatisch. Prüfen Sie jeden Job einzeln, bevor Sie einen dauerhaft erreichbaren Host einplanen.

Eine selbstgehostete Maschine führt jeweils einen Auftrag gleichzeitig aus; parallele Aufträge benötigen entsprechend eine weitere Runner-Kapazität. Diese Grenze ist in GitHubs Dokumentation zu selbstgehosteten Runnern beschrieben. Für ein kleines Projekt ist das oft eher eine Frage der Warteschlange als der reinen Einrichtung: Wenn mehrere Builds regelmäßig gleichzeitig laufen sollen, planen Sie den möglichen Engpass ein, statt nur den ersten erfolgreichen Lauf zu betrachten.

Vorbereitung: Repository, Mac und Arbeitsumgebung festlegen

Bevor Sie Befehle ausführen, entscheiden Sie, wo der Runner registriert werden soll. Ein Repository-Runner gehört zu einem einzelnen Repository. Ein Organisations-Runner kann für mehrere berechtigte Repositories verfügbar sein. Wählen Sie die engste Reichweite, die Ihren tatsächlichen Bedarf erfüllt. Ein Runner sollte nicht für Projekte erreichbar sein, deren Workflows und Berechtigungen Sie nicht geprüft haben.

Sie benötigen administrative Berechtigungen für den gewählten Bereich, einen erreichbaren Mac und eine Arbeitsumgebung, in der sich Projektdateien und Abhängigkeiten sicher verwalten lassen. Prüfen Sie außerdem, welche Personen Workflows auslösen dürfen und ob der Host in einer Umgebung läuft, die zu Ihren Datenschutz- und Vertraulichkeitsanforderungen passt. Für Teams in der EU gehören dazu auch die eigenen DSGVO-Prüfungen zu Quellcode, Build-Artefakten, Protokollen und Zugangsdaten. Eine passende Infrastruktur ersetzt diese Prüfung nicht.

Öffnen Sie anschließend die Einstellungen des gewählten Repositorys oder der Organisation und rufen Sie dort die Einrichtung für selbstgehostete Runner auf. Wählen Sie macOS und die Architektur, die zum Host passt. Die angezeigten Anweisungen sind maßgeblich: Sie enthalten den passenden Download und die Registrierung für genau diesen Bereich. GitHub führt diesen Ablauf in der Anleitung zum Hinzufügen eines Runners auf.

Registrierung: Die GitHub-Anweisungen auf dem Mac ausführen

Führen Sie die Einrichtung in einem Verzeichnis aus, das für den Runner vorgesehen ist. Folgen Sie der Reihenfolge der GitHub-Seite: Runner-Dateien laden, Archiv prüfen und entpacken, anschließend die angezeigte Konfiguration starten. Befehle können sich ändern. Deshalb sollten Sie keine alten Befehlszeilen aus einem Blogbeitrag übernehmen, wenn die aktuelle GitHub-Oberfläche andere Schritte ausgibt.

Die Registrierung verbindet die Runner-Anwendung mit dem gewählten Repository oder der Organisation. Das dabei angezeigte Token ist ein Zugangsmittel für diesen Vorgang. Kopieren Sie es nicht in ein Repository, ein Workflow-YAML, ein öffentliches Ticket oder eine gemeinsam genutzte Notiz. Speichern Sie es nicht dauerhaft im Projektverzeichnis. Verwenden Sie ausschließlich den offiziellen Registrierungsablauf und behandeln Sie das Token so, als könnte es die Zuordnung des Runners beeinflussen.

Während der Konfiguration fragt GitHub nach Angaben wie dem Runner-Namen und optionalen Labels. Wählen Sie einen Namen, der für Ihr Team verständlich ist und keine unnötigen internen Informationen offenlegt. Notieren Sie den tatsächlichen Namen und die Labels in der internen Betriebsdokumentation, aber nicht das Registrierungstoken. Nach erfolgreicher Konfiguration sollte die Runner-Anwendung den Host beim gewählten Bereich anmelden.

Ein typischer Ausschnitt aus der Oberfläche zeigt die passende Plattform und die Befehle zum Laden und Konfigurieren. Die konkreten Befehle bleiben absichtlich offen: Entscheidend ist, sie aus der aktuell geöffneten GitHub-Einrichtungsseite zu übernehmen. Stimmen Architektur, Repository und Host nicht überein, brechen Sie ab und wählen Sie die Einstellungen erneut, statt eine Registrierung mit geratenen Parametern zu erzwingen.

Dauerbetrieb: Den macOS-Dienst einrichten und kontrollieren

Ein Runner im Vordergrund ist an die geöffnete Sitzung und den laufenden Prozess gebunden. Wird das Terminal geschlossen oder die Sitzung beendet, kann der Prozess enden. Für einen Mac, der unbeaufsichtigt Aufträge annehmen soll, richten Sie den Runner als macOS-Dienst ein. GitHub beschreibt die Dienstkonfiguration in der Anleitung für macOS-Runner.

Nach der Registrierung wechseln Sie in das Verzeichnis des Runner-Programms und verwenden die von GitHub dokumentierten Dienstbefehle. Ein typischer Ablauf sieht so aus:

./svc.sh install
./svc.sh start
./svc.sh status

Die Befehle installieren, starten und prüfen den Dienst. Verwenden Sie sie nur im richtigen Runner-Verzeichnis und folgen Sie der aktuellen Dokumentation, falls die bereitgestellte Runner-Version einen abweichenden Ablauf verlangt. Eine erfolgreiche Ausgabe bei start allein genügt nicht. Prüfen Sie den Status lokal und kontrollieren Sie zusätzlich in GitHub, ob der Runner als verfügbar angezeigt wird.

Für die Betriebsabnahme gehört auch ein kontrollierter Neustart des Mac dazu. Prüfen Sie nach dem Neustart erneut den Dienststatus und die Anzeige im Repository oder in der Organisation. Erst wenn der Runner nach diesem Test erreichbar ist, sollten Sie sich für wiederkehrende Builds auf den Dienst verlassen. Dokumentieren Sie, wer bei einem Offline-Status reagiert und wie ein fehlerhafter Dienst neu gestartet oder neu konfiguriert wird.

GitHub stellt außerdem eine Anleitung zur Überwachung und Fehlersuche bereit. Nutzen Sie diese, wenn ein Runner zwar registriert ist, aber keine Aufträge annimmt. Prüfen Sie dabei nicht nur den GitHub-Status, sondern auch lokale Dienstprotokolle, Netzverbindung und die Verfügbarkeit der Projektwerkzeuge. Ein wiederholter Neustart kann ein Symptom kurzfristig beseitigen, ohne die Ursache zu beheben.

Workflow-Abnahme: Labels und reproduzierbaren Test verwenden

Ein Job wird nicht allein deshalb an den Mac geschickt, weil ein Runner registriert ist. Die Workflow-Anforderung muss zu den Labels des Runners passen. Standardlabels beschreiben den Runner als selbstgehostet sowie das Betriebssystem und die Architektur. Prüfen Sie die tatsächlich angezeigten Labels in GitHub und verwenden Sie sie im Workflow. GitHub erläutert die Auswahl und Verwendung von Labels in der Dokumentation zur Label-Zuweisung.

Ein Beispiel für einen Workflow, der einen selbstgehosteten macOS-Runner mit ARM64-Label anfordert:

jobs:
  macos-check:
    runs-on: [self-hosted, macOS, ARM64]
    steps:
      - uses: actions/checkout@v4
      - name: Runner-Umgebung anzeigen
        run: |
          sw_vers
          uname -m

Das Beispiel setzt voraus, dass die Labels des tatsächlich registrierten Runners dazu passen. Wenn Ihr Host eine andere Architektur hat, ändern Sie die Anforderung anhand der Runner-Anzeige. Ein Job, dessen Labels nicht erfüllt werden, bleibt möglicherweise in der Warteschlange, anstatt auf einem unpassenden Host zu starten. Prüfen Sie deshalb zuerst die Zuordnung, bevor Sie einen Workflow als fehlerhaft einstufen.

Führen Sie die Abnahme in kontrollierten Schritten durch:

1. Erstellen Sie einen einfachen Workflow, der nur auf den gewünschten Runner zielt und wenige, risikoarme Befehle ausführt.
2. Lösen Sie den Workflow aus einem vertrauenswürdigen Branch aus.
3. Prüfen Sie in GitHub, ob der Job auf dem erwarteten Runner startet und die Protokolle einsehbar sind.
4. Kontrollieren Sie, ob das Ergebnis – etwa ein Testbericht oder Build-Artefakt – dort ankommt, wo Ihr Team es erwartet.
5. Führen Sie danach den tatsächlichen Projekt-Build mit den benötigten macOS-Werkzeugen aus und prüfen Sie Abhängigkeiten, Signierung und Ergebnis separat.

Ein erfolgreicher einfacher Test bestätigt die Verbindung und die grundlegende Ausführung. Er beweist nicht, dass jedes Projekt, jede Abhängigkeit oder jeder Veröffentlichungsschritt funktioniert. Für eine belastbare macOS-CI-Konfiguration müssen Sie die Anforderungen des konkreten Projekts abnehmen. Dokumentieren Sie außerdem, welche Werkzeugversionen installiert sind und wie Änderungen an dieser Umgebung geprüft werden.

Sicherheitsgrenzen und Wartung vor dem produktiven Einsatz prüfen

Ein selbstgehosteter Runner führt Workflow-Code auf einem Host aus, den Sie verwalten. Das kann Dateien, installierte Werkzeuge und erreichbare Zugangsdaten betreffen. GitHub warnt in den Sicherheitshinweisen zur Verwendung von GitHub Actions vor Risiken durch nicht vertrauenswürdigen Workflow-Code. Besonders kritisch ist es, externe Beiträge auf einer persistenten Maschine auszuführen, die auch für vertrauenswürdige Builds verwendet wird.

Legen Sie fest, wer Workflow-Dateien ändern und Aufträge auslösen darf. Prüfen Sie Auslöser für Pull Requests aus Forks und vermeiden Sie es, vertrauliche Geheimnisse in Jobs verfügbar zu machen, deren Code nicht vertrauenswürdig ist. Ein öffentliches Repository ist nicht automatisch ein sicherer Einsatzbereich für einen privaten Runner. Wenn externe Beiträge ausgeführt werden müssen, sollten Sie eine isolierte, kurzlebige Umgebung prüfen, statt eine dauerhaft genutzte Entwickler-Maschine dafür freizugeben.

Auch nach der Inbetriebnahme bleibt Wartung erforderlich. Planen Sie regelmäßige Kontrollen für Runner-Software, macOS, Projektwerkzeuge, freien Speicher und Zugangsdaten ein. Entfernen Sie ungenutzte Runner-Zuordnungen und prüfen Sie, ob die verfügbaren Berechtigungen weiterhin erforderlich sind. Bei einem Ausfall sollte klar sein, wer Logs kontrolliert, den Dienst neu startet und die GitHub-Anzeige mit dem lokalen Zustand abgleicht.

Für die Entscheidung zwischen eigener Hardware und einem zeitweise genutzten Remote-Mac sollten Sie nicht nur den Installationsaufwand betrachten. Ein selbst verwalteter Host bindet Sie an Updates, Verfügbarkeit und Sicherheitskontrollen. Eine Remote-Umgebung kann diese Arbeit nicht automatisch aufheben; vor dem Einsatz müssen tatsächliche macOS-Version, Zugriffsrechte, Wiederherstellungsmöglichkeiten und Laufzeitbedingungen geprüft werden. Einen neutralen Überblick für die passende Mac-Option finden Sie in unserem Vergleich der Remote-Mac-Möglichkeiten. Wenn der Standort für Latenz oder interne Vorgaben relevant ist, prüfen Sie zusätzlich die Informationen zu den Rechenzentrumsstandorten. Informationen zu den angebotenen Umgebungen sollten Sie vor einer technischen Entscheidung anhand der konkreten Bedingungen prüfen, nicht aus einem Workflow-Beispiel ableiten.

Häufige Fragen zum selbstgehosteten Mac Runner

Wie füge ich GitHub Actions einen selbstgehosteten macOS Runner hinzu?

Wählen Sie in den Einstellungen des Repositorys oder der Organisation den Bereich für Actions-Runner und starten Sie dort die Einrichtung eines neuen selbstgehosteten Runners. Legen Sie macOS und die passende Prozessorarchitektur fest. GitHub zeigt anschließend die für diesen Geltungsbereich erzeugten Download- und Registrierungsschritte an. Verwenden Sie genau diese aktuellen Anweisungen und behandeln Sie das Registrierungstoken als vertrauliches, kurzlebiges Geheimnis.

Kann der Mac Runner weiterarbeiten, wenn das Terminal geschlossen ist?

Ein Runner, der nur im Vordergrund gestartet wurde, ist an diesen Prozess gebunden. Wird das Terminal geschlossen oder die Sitzung beendet, kann der Prozess stoppen und nimmt dann keine neuen Aufträge an. Für einen dauerhaft erreichbaren Mac richten Sie den Runner nach der Registrierung als macOS-Dienst ein, starten ihn und prüfen seinen Status. Erst der Dienstbetrieb ist der geeignete Weg für unbeaufsichtigte Arbeit.

Wie startet ein selbstgehosteter Mac Runner nach einem Neustart automatisch?

Richten Sie die Runner-Anwendung mit dem offiziellen macOS-Dienstskript als Dienst ein und starten Sie den Dienst. Prüfen Sie danach den Status auf dem Mac und die Runner-Anzeige in GitHub. Ein erfolgreicher Erststart beweist noch nicht, dass die Konfiguration einen Neustart übersteht. Testen Sie deshalb den vorgesehenen Neustart kontrolliert, bevor wichtige Workflows auf den Runner angewiesen sind.

Darf ein selbstgehosteter Mac Runner Pull Requests aus einem öffentlichen Repository ausführen?

Das ist sicherheitlich heikel, wenn Beiträge von nicht vertrauenswürdigen Personen auf einer dauerhaft genutzten Maschine ausgeführt werden. Workflow-Code kann die Runner-Umgebung beeinflussen und möglicherweise auf dort erreichbare Dateien oder Zugangsdaten zugreifen. Prüfen Sie deshalb Berechtigungen, Geheimnisse und Auslöser genau. Verwenden Sie einen persistenten Mac Runner nicht für externe Beiträge, wenn Sie den ausgeführten Code und seine Folgen nicht kontrollieren können.

Wenn die Abnahme zeigt, dass Ihr Projekt einen ständig verfügbaren Mac braucht, vergleichen Sie anschließend die laufende Pflege eines eigenen Hosts mit einer Remote-Lösung. Der eigene Mac verlangt Updates, Überwachung und Schutz vor nicht vertrauenswürdigen Jobs; ein Remote-Mac ist ebenfalls nur dann passend, wenn Zugriff, Rechte und Nutzungszeitraum zu Ihrem Workflow passen. Prüfen Sie bei OnceMac diese Bedingungen anhand der tatsächlichen Angebotsdetails, bevor Sie Ihre CI darauf ausrichten.

Häufig gestellte Fragen