GitHub Actions Self-hosted Runner auf dem Remote Mac 2026

Der Runner bleibt offline, startet nach einem Neustart nicht oder nimmt versehentlich ungeprüfte Pull Requests an.

Die schnellste belastbare Lösung ist ein dauerhaft erreichbarer, echter Apple-Silicon-Mac mit Administratorrechten, einem als macOS-Dienst eingerichteten GitHub Actions Self-hosted Runner, klaren Labels und einer Beschränkung auf vertrauenswürdige private Workflows.

Diese Anleitung ist für Sie geeignet, wenn Sie iOS- oder macOS-Projekte kontinuierlich bauen, testen, signieren oder veröffentlichen müssen; wenn Sie als DevOps-Verantwortlicher Runner, Zugriffsgruppen und Geheimnisse zentral verwalten; oder wenn die GitHub-gehostete Umgebung keine dauerhaften Caches, internen Netzwerkzugriff oder Ihre eigene Toolchain abbildet.

Eignung eines Remote Mac als produktiver Buildknoten

Ein Remote Mac ist als macOS-Buildknoten geeignet, wenn er dauerhaft online bleibt, Sie Administratorrechte besitzen, der Runner installiert werden darf und der Host ausgehend über HTTPS mit GitHub sowie den von Ihrem Workflow benötigten Paket-, Registry- und Signaturdiensten kommunizieren kann. GitHub nennt für selbst gehostete Runner ausreichende Hardware-Ressourcen sowie Netzwerkzugriff auf GitHub Actions als Grundvoraussetzungen. Weitere Details finden Sie in der offiziellen Dokumentation zu selbst gehosteten Runnern.

Prüfen Sie vor der Installation nicht nur, ob macOS startet, sondern ob die Maschine Ihren konkreten Buildprozess tragen kann:

• Betriebssystem und Architektur: Ermitteln Sie mit sw_vers und uname -m, welche macOS-Version und welche Prozessorarchitektur tatsächlich aktiv sind. Für native Apple-Silicon-Werkzeuge muss der Host nicht nur „Mac“ melden, sondern die erwartete ARM-Umgebung bereitstellen.
• Administratorzugriff: Sie benötigen Zugriff auf das Terminal, dürfen Software installieren und müssen den Runner als macOS-Dienst registrieren können.
• Dauerhafte Erreichbarkeit: Ein Host, der nach dem Schließen einer SSH-Sitzung oder nach einem Neustart nicht wieder online kommt, ist kein belastbarer Produktionsknoten.
• Ausgehender Netzwerkzugriff: GitHub dokumentiert ausgehende HTTPS-Verbindungen über Port 443 sowie zusätzliche Domains für Releases, Packages, OIDC, Git LFS und weitere Workflow-Funktionen. Eine restriktive Firewall muss diese Abhängigkeiten gezielt erlauben.
• Speicher und Arbeitsverzeichnis: Quellen, Abhängigkeiten, Build-Artefakte, Simulator-Daten und Caches können sich gegenseitig verdrängen. Planen Sie deshalb nicht nur für den Runner selbst, sondern für die größte realistische Pipeline.
• Werkzeugkette: Wenn Sie xcodebuild, simctl oder devicectl benötigen, reicht das Command-Line-Tools-Paket allein nicht aus; Apple weist darauf hin, dass diese Werkzeuge mit Xcode ausgeliefert werden. Die Voraussetzungen beschreibt Apple in der Dokumentation zu den Command Line Tools.

Für einen ersten Versuch mit nur einem Repository beginnen Sie auf Repository-Ebene. Wenn mehrere private Repositories dieselbe kontrollierte Werkzeugkette verwenden sollen, ist ein Organisations-Runner mit Runner-Gruppe und eingeschränkter Repository-Freigabe die sauberere Struktur. GitHub unterstützt Runner auf Repository-, Organisations- und Enterprise-Ebene.

Auswahl der Registrierungsebene

Die Wahl der Registrierung beeinflusst nicht nur die Bedienung, sondern auch den späteren Sicherheitsbereich.

GitHub warnt ausdrücklich davor, selbst gehostete Runner für öffentliche Repositories einzusetzen, weil Forks Pull Requests erstellen können, deren Workflow-Code auf dem persistenten Host ausgeführt wird. Die GitHub-Sicherheitsdokumentation beschreibt außerdem, dass ein kompromittierter Runner Zugriff auf lokale Dateien, private Schlüssel, API-Tokens und je nach Konfiguration auch auf Geheimnisse erhalten kann. Die entsprechenden Sicherheitsgrenzen erläutert GitHub in der Anleitung zur sicheren Verwendung von GitHub Actions.

Ein persistenter Remote Mac ist deshalb nicht automatisch eine sichere Alternative zu einem frischen, kurzlebigen Runner. Der entscheidende Unterschied ist, dass Arbeitsverzeichnisse, Caches, Anmeldungen und temporäre Dateien zwischen Jobs bestehen bleiben können. Für sensible oder nicht vertrauenswürdige Pull Requests verwenden Sie einen getrennten, ephemeren oder GitHub-gehosteten Ausführungspfad.

Rechte und Konten vor der Einrichtung trennen

Legen Sie auf dem Remote Mac ein eigenes CI-Konto an, das nicht Ihr tägliches Entwicklerprofil ist. Das Konto sollte nur die Werkzeuge, SSH-Schlüssel und Zugangsdaten besitzen, die für die vorgesehenen Workflows erforderlich sind.

Trennen Sie mindestens diese Bereiche:

1. Betriebssystemkonto: Ein eigenes Benutzerkonto für CI verhindert, dass private Dokumente, Browser-Sitzungen oder persönliche Schlüssel automatisch in Buildprozesse gelangen.
2. Runner-Gruppe: Eine Gruppe für normale Builds und eine separate Gruppe für Signatur- oder Veröffentlichungsjobs begrenzen den Kreis der berechtigten Repositories.
3. Arbeitsverzeichnis: Legen Sie den Runner in einem eindeutig benannten Verzeichnis ab, beispielsweise ~/actions-runner, und behandeln Sie dessen Unterverzeichnisse als ausführbaren Bereich.
4. Geheimnisse: Zertifikate, Provisioning-Profile, App-Store-Schlüssel und Tokens gehören in GitHub Secrets, Environments oder einen kontrollierten Secret-Manager, nicht in das Repository und nicht dauerhaft in Klartextdateien.
5. Workflow-Freigaben: Definieren Sie vor der Registrierung, welche Branches den Mac verwenden dürfen und ob Pull Requests aus Forks ausgeschlossen sind.

Organisationsweite Runner-Gruppen können den Zugriff auf bestimmte Repositories begrenzen und dadurch eine zusätzliche Sicherheitsgrenze schaffen. Die aktuellen Berechtigungsoptionen finden Sie in GitHubs Dokumentation zur Verwaltung von Runner-Gruppen.

Wichtiger Prüfpunkt: Ein Workflow, der den Runner verwenden darf, kann grundsätzlich Befehle auf dem Host ausführen. Wenn Sie nicht erklären können, welche Repositories, Branches und Personen diese Ausführung auslösen dürfen, ist der Runner noch nicht produktionsbereit.

Installation und Registrierung in der ersten Stunde

GitHub erzeugt die Download-URL, Registrierungsschritte und das zeitlich begrenzte Registrierungstoken direkt in der Oberfläche des ausgewählten Repositorys oder der Organisation. Übernehmen Sie diese Werte aus der aktuellen GitHub-Anleitung, statt eine alte Runner-Version oder ein bereits veröffentlichtes Token in ein Skript zu kopieren. Das Registrierungstoken ist laut GitHub nur begrenzte Zeit gültig; die Dokumentation nennt eine Gültigkeit von einer Stunde. Die einzelnen Schritte stehen in der Anleitung zum Hinzufügen selbst gehosteter Runner.

1. System und Architektur dokumentieren

Öffnen Sie eine SSH-Sitzung und speichern Sie zunächst die Ausgangswerte:

sw_vers
uname -m
whoami
df -h
xcode-select -p

Für einen Apple-Silicon-Host erwarten Sie typischerweise eine ARM64-Ausgabe bei uname -m. Entscheidend ist jedoch nicht das Etikett allein, sondern ob Ihre installierten Abhängigkeiten und Build-Skripte diese Architektur unterstützen.

2. Einen separaten Runner-Ordner anlegen

mkdir -p ~/actions-runner
cd ~/actions-runner

Laden Sie anschließend das für macOS und die erkannte Architektur angezeigte Archiv aus der GitHub-Oberfläche herunter. GitHub veröffentlicht unterschiedliche Archive für macOS auf Intel und Apple Silicon; die aktuelle Version und der konkrete Dateiname können sich ändern.

Beispielhaft sieht der Ablauf so aus, ohne eine feste Versionsnummer zu behaupten:

curl -L -o actions-runner.tar.gz "<AKTUELLE_GITHUB_DOWNLOAD_URL>"
tar xzf actions-runner.tar.gz

Prüfen Sie danach, ob die erwarteten Dateien vorhanden sind:

ls -la

Die verfügbaren Runner-Pakete und Änderungen an den unterstützten Versionen können Sie auf der offiziellen Release-Seite des actions/runner-Projekts nachvollziehen.

3. Den Runner auf Repository- oder Organisationsebene registrieren

Öffnen Sie in GitHub die Runner-Einstellungen und kopieren Sie die dort erzeugten Werte. Der Aufruf folgt diesem Muster:

./config.sh \
  --url "<REPOSITORY_ODER_ORGANISATIONS_URL>" \
  --token "<ZEITLICH_BEFRISTETES_REGISTRIERUNGSTOKEN>" \
  --name "macos-arm64-build-01" \
  --labels "macos,apple-silicon,ios-build"

Verwenden Sie eigene Labels nur dann, wenn sie eine echte Routingentscheidung ausdrücken. Labels sind laut GitHub nicht dazu gedacht, eine nicht überprüfte Hardwareeigenschaft zu behaupten; bei der manuellen Vergabe prüft GitHub nicht automatisch, ob die Bezeichnung zur tatsächlichen Maschine passt. Einzelheiten zur Label-Zuweisung beschreibt GitHub in der Dokumentation zu Runner-Labels.

4. Den Dienst für den automatischen Start einrichten

Nach erfolgreicher Registrierung installieren Sie den Runner als macOS-Dienst:

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

Der konkrete Dienstname und die erzeugte launchd-Datei werden vom Runner festgelegt. Beenden Sie anschließend die SSH-Sitzung und öffnen Sie eine neue Verbindung. Prüfen Sie danach erneut:

cd ~/actions-runner
./svc.sh status

Startet der Dienst nach einem Neustart nicht automatisch, beenden Sie die Einrichtung an dieser Stelle. Ein Runner, der nur während Ihrer interaktiven Sitzung online ist, erfüllt die Anforderung eines dauerhaften macOS-Buildknotens nicht.

5. Registrierung, Label und Dienststatus getrennt prüfen

Kontrollieren Sie in GitHub:

• Runner ist am richtigen Repository oder an der richtigen Organisation registriert.
• Der Name entspricht dem vorgesehenen Host.
• Die Labels enthalten mindestens self-hosted, macos und das von Ihnen definierte Architektur- oder Zwecklabel.
• Der Runner befindet sich in der richtigen Runner-Gruppe.
• Der Status lautet „Online“ und nicht nur „Idle“ in einer veralteten Browseransicht.

Zusätzlich prüfen Sie lokal den Dienststatus und die Logs. Für die Fehlersuche auf macOS sind launchctl, die Runner-Serviceausgabe und die Dateien im diag-Verzeichnis wichtiger als ein einzelner Screenshot aus der GitHub-Oberfläche.

Gezieltes Routing auf den Apple-Silicon-Mac

Ein GitHub Actions Workflow darf nicht nur self-hosted verwenden, wenn in Ihrer Organisation mehrere Runner existieren. Kombinieren Sie die Labels, damit ein iOS-Build nicht versehentlich auf einem Intel-Mac oder einem ungeeigneten Linux-Host landet:

jobs:
  build:
    runs-on: [self-hosted, macos, apple-silicon, ios-build]

    steps:
      - name: Repository auschecken
        uses: actions/checkout@v4

      - name: Hostnachweis erfassen
        run: |
          sw_vers
          uname -m
          xcodebuild -version

      - name: Projekt bauen
        run: |
          xcodebuild \
            -workspace App.xcworkspace \
            -scheme App \
            -configuration Release \
            -destination 'generic/platform=iOS' \
            build

Die Versionsnummer von actions/checkout ist hier kein Beleg dafür, dass Ihr gesamter Workflow kompatibel ist. Prüfen Sie Actions, Xcode, SDK, Ruby-, Node- oder Swift-Abhängigkeiten getrennt. Apple dokumentiert, dass Xcode die Werkzeuge zum Bauen, Testen und Verteilen von Anwendungen für Apple-Plattformen bereitstellt. Die Produktseite finden Sie unter Apple Xcode.

Behandeln Sie die erste Pipeline als zweistufige Abnahme:

• Stufe A – Routing: Der Job startet auf dem richtigen Runner und protokolliert Betriebssystem, Architektur sowie aktive Toolchain.
• Stufe B – Projektbuild: Abhängigkeiten werden installiert, Tests ausgeführt, Signatur geprüft und ein definiertes Artefakt erzeugt.

Ein grüner Stufe-A-Lauf beweist nicht, dass Ihr Projekt gebaut oder signiert werden kann.

Offline-Fehler systematisch beheben

Ein Offline-Status entsteht häufig nicht durch GitHub selbst, sondern durch einen nicht laufenden Dienst, eine falsche Benutzerumgebung oder fehlende ausgehende Netzwerkverbindungen.

Gehen Sie in dieser Reihenfolge vor:

1. Prüfen Sie, ob der Mac erreichbar ist und das CI-Konto verwendet wird.
2. Führen Sie ./svc.sh status im Runner-Verzeichnis aus.
3. Prüfen Sie die launchd-Einträge mit launchctl und vergleichen Sie den Dienstpfad mit der .service-Datei.
4. Öffnen Sie die Runner-Logs und suchen Sie nach Authentifizierungs-, Zertifikats-, DNS- oder Verbindungsfehlern.
5. Testen Sie ausgehend HTTPS über Port 443 und die in der GitHub-Dokumentation genannten Domains.
6. Prüfen Sie, ob der Runner in GitHub deaktiviert, entfernt oder einer falschen Gruppe zugewiesen wurde.
7. Vergleichen Sie die Workflow-Labels mit den tatsächlich registrierten Labels.

GitHub stellt für Runner außerdem REST-Informationen wie status, busy, Betriebssystem, Version und Labels bereit. Diese Werte eignen sich für ein einfaches Monitoring, sofern Sie die API-Zugriffsrechte sicher verwalten. Die verfügbaren Endpunkte sind in der REST-API-Dokumentation für selbst gehostete Runner beschrieben.

Wenn der Runner nach dem Neustart online ist, aber Jobs nicht startet, prüfen Sie zuerst die Label-Kombination. Wenn Jobs starten und anschließend sofort fehlschlagen, kontrollieren Sie dagegen Arbeitsverzeichnis, Toolchain, Berechtigungen und verfügbare Umgebungsvariablen.

Sicherheitsmaßnahmen für den ersten Betriebstag

Die größte Fehlannahme lautet: „Der Runner ist online, also ist die Bereitstellung abgeschlossen.“ Tatsächlich müssen Sie den Zustand nach jedem Job kontrollieren, weil der Runner standardmäßig kein vollständig frisches System pro Ausführung bereitstellt. Arbeitsverzeichnisse, Caches, Anmeldungen und temporäre Dateien können zwischen Jobs bestehen bleiben.

Setzen Sie am ersten Betriebstag diese Maßnahmen um:

• Arbeitsverzeichnisse nach jedem Job kontrollieren und bekannte temporäre Dateien löschen.
• Caches nur für unkritische Abhängigkeiten verwenden; Signaturmaterial und Tokens niemals in Caches schreiben.
• Secrets möglichst über GitHub Environments mit Branch- und Freigaberegeln injizieren.
• Keine privaten SSH-Schlüssel oder App-Store-Zugangsdaten im Benutzerverzeichnis zurücklassen.
• Signatur- und Veröffentlichungsjobs auf eine eigene Runner-Gruppe begrenzen.
• Netzwerkzugriff auf interne Dienste nur erlauben, wenn der Workflow ihn tatsächlich benötigt.
• Bei Fehlern den Runner pausieren, Logs sichern und den Host vor einer erneuten Aktivierung prüfen.
• Zugriffe auf personenbezogene oder interne Daten nach dem Grundsatz der geringsten Berechtigung behandeln und Ihre internen DSGVO-Vorgaben dokumentieren.

Für öffentliche Repositories sollten Sie einen persistenten Remote Mac grundsätzlich nicht als Standardziel für Pull-Request-Workflows einsetzen. Das Risiko entsteht nicht erst beim eigentlichen Build, sondern bereits dadurch, dass nicht vertrauenswürdiger Workflow-Code auf dem dauerhaft vorhandenen Host ausgeführt werden kann.

Betrieb, Updates und Wiederanlauf

Ein produktiver macOS-Buildknoten braucht eine kleine, wiederholbare Betriebsroutine:

• Online-Status: täglich oder automatisiert prüfen, ob der Runner erreichbar und nicht dauerhaft blockiert ist.
• Warteschlange: beobachten, ob Jobs wegen fehlender Labels oder Kapazität warten.
• Speicherplatz: Arbeitsverzeichnisse, Xcode-Artefakte, Simulator-Daten, Logs und Caches regelmäßig kontrollieren.
• Dienstprotokolle: launchd-Status und Runner-Diagnosedateien nach Fehlern auswerten.
• Runner-Updates: automatische Updates nicht ungeprüft deaktivieren. GitHub erklärt, dass bei deaktivierten automatischen Updates innerhalb von 30 Tagen nach einer verfügbaren Version aktualisiert werden muss; andernfalls werden keine Jobs mehr an den Runner gereicht.
• macOS- und Xcode-Wartung: nicht gemeinsam mit einem Runner-Update erzwingen, sondern in einem Wartungsfenster testen und bei Bedarf zurückrollen.
• Wiederanlauf: Neustart durchführen und nach dem Boot prüfen, ob Dienst, Netzwerk, Toolchain und GitHub-Status wieder korrekt sind.
• Stilllegung: Runner aus GitHub entfernen, lokale Geheimnisse löschen und den Host erst danach aus dem Betrieb nehmen.

Akzeptieren Sie einen Buildknoten erst dann als produktiv, wenn alle vier Übungen erfolgreich waren: Neustart-Wiederherstellung, erneuter Lauf eines fehlgeschlagenen Jobs, Speicherbereinigung und kontrollierte Deaktivierung.

Für eine strukturierte Konfiguration einer Remote-Mac-Entwicklungsumgebung können Sie die Hostvorbereitung unabhängig vom GitHub-Registrierungsprozess dokumentieren. Wenn mehrere Teams zwischen gehosteten und selbst verwalteten Optionen abwägen, hilft zusätzlich die Übersicht zu Remote-Mac-Einsatzszenarien, bevor Sie Runner-Gruppen und Signaturzugriffe endgültig festlegen.

Abnahme-Checkliste vor dem Produktionsstart

• [ ] Der Mac bleibt auch ohne aktive SSH-Sitzung erreichbar.
• [ ] sw_vers, uname -m und die aktive Developer Directory sind dokumentiert.
• [ ] Der Runner ist auf Repository- oder Organisationsebene bewusst registriert.
• [ ] Die Registrierung verwendet ein aktuelles, automatisch erzeugtes Token.
• [ ] Der Runner läuft als macOS-Dienst und startet nach einem Neustart wieder.
• [ ] Labels routen Jobs eindeutig auf den vorgesehenen Apple-Silicon-Host.
• [ ] Ein Minimalworkflow beweist das Routing.
• [ ] Ein echter Buildworkflow beweist Abhängigkeiten, Tests und Artefakterzeugung.
• [ ] Signatur- und Veröffentlichungsjobs sind separat berechtigt.
• [ ] Öffentliche Pull Requests erreichen den persistenten Host nicht.
• [ ] Arbeitsverzeichnisse, Caches und Secrets sind auf Persistenzrisiken geprüft.
• [ ] Logs, Speicherplatz und Runner-Updates besitzen einen festen Prüfprozess.
• [ ] Ein dokumentierter Rollback- und Stilllegungsweg ist vorhanden.

Wenn Sie heute bereits einen Windows- oder Linux-Rechner mit einem temporären macOS-Umweg kombinieren, bleiben häufig drei Nachteile bestehen: Die Toolchain entspricht nicht zuverlässig der Apple-Zielumgebung, interne Signatur- und Testschritte benötigen zusätzliche Übergaben, und ein eigener Mac muss separat gekauft, dauerhaft betrieben und überwacht werden. Für kurzfristige Projekte, zusätzliche CI-Kapazität oder einen kontrollierten Testknoten kann ein von KVMFLUX bereitgestellter Remote Mac daher die praktischere Zwischenlösung sein.

Prüfen Sie zunächst die verfügbaren Mietzeiträume und Bereitstellungsoptionen, wählen Sie einen Host mit Administratorzugriff und führen Sie anschließend genau diese Runner-Abnahme durch. Wenn Sie einen Mac langfristig mit hoher, gleichmäßiger Buildlast betreiben, physische Geräte oder spezielle Peripherie benötigen, kann der Kauf und die eigene Wartung weiterhin sinnvoller sein. Für zeitlich begrenzte CI-Kapazität, einen zusätzlichen Apple-Silicon-Buildknoten oder eine kontrollierte Testumgebung ist die Miete dagegen leichter zurückzubauen.