DevOps / CI/CD

GitHub Actions macOS Runner 2026: Remote-Mac konfigurieren

GitHub warnt ausdrücklich davor, einen selbst gehosteten Runner für nicht vertrauenswürdigen Code aus öffentlichen Fork-Pull-Requests einzusetzen (Sicherheitshinweise zu selbst gehosteten Runnern). Ist das Repository privat oder sind Auslöser und Code zuverlässig kontrolliert, kann ein Remote-Mac Xcode-Arbeit übernehmen; begrenzen Sie zuerst den Zugriff, konfigurieren Sie danach den Runner-Dienst und prüfen Sie den Ablauf mit einem echten Projekt. Für öffentliche Repositories mit unkontrollierten Beiträgen ist ein Runner mit verfügbaren Zugangsdaten keine sichere Standardwahl.

Dieser Leitfaden richtet sich an unabhängige Entwickler, die iOS-Apps mit GitHub Actions unter macOS bauen möchten.
Kleine Teams können damit Zugriffsbereich, Dienststatus und belastbare Abnahmen für ihre Build-Automatisierung prüfen.
Er eignet sich auch für Entwickler, die bereits einen Remote-Mac haben und ihn als kontinuierlichen Build-Knoten einsetzen möchten.

Vor dem Einrichten: Eignung, Repository und Sicherheitsgrenzen klären

Ein GitHub Actions macOS Runner ist sinnvoll, wenn der Workflow Xcode oder andere macOS-spezifische Werkzeuge benötigt und der auszuführende Code als vertrauenswürdig eingestuft werden kann. GitHub bietet selbst gehostete Runner auf Repository-, Organisations- und Unternehmensebene an. Diese drei Verwaltungsebenen unterscheiden sich darin, welche Projekte einen Runner verwenden können; die passende Ebene sollte deshalb vor der Registrierung feststehen (GitHub-Dokumentation zu Runner-Zugriff und Verwaltung).

Prüfen Sie zunächst, von welchen Ereignissen ein Workflow gestartet wird. Ein Build auf einem kontrollierten Branch ist einfacher abzusichern als ein Workflow, der beliebigen Beiträgen aus Forks Zugriff auf einen dauerhaft laufenden Rechner gibt. Ein selbst gehosteter Runner führt Workflow-Code auf einer Maschine aus, deren Dateisystem, installierte Werkzeuge und erreichbare Netzwerkressourcen zu berücksichtigen sind. Das ist nicht mit einer isolierten, kurzlebigen Umgebung gleichzusetzen (Referenz zu selbst gehosteten Runnern).

Kann ein GitHub Actions self-hosted runner Xcode-Builds ausführen? Ja, sofern auf dem Mac ein passendes Xcode samt erforderlichen Projektkomponenten installiert ist und der Runner-Prozess diese Werkzeuge aufrufen darf. GitHub stellt die Ausführungsumgebung bereit; die Verantwortung für Xcode, Abhängigkeiten, Berechtigungen und Wartung des eigenen Rechners bleibt beim Betreiber.

Prüfpunkt Eher geeignet Vorher ändern oder andere Lösung wählen
Repository-Zugriff Privates Repository oder genau kontrollierte Auslöser Öffentliche Beiträge können ungeprüften Workflow-Code starten
Build-Aufgabe Xcode- oder macOS-spezifischer Build Der Job benötigt keine macOS-Werkzeuge
Zugangsdaten Geheimnisse sind nur für vertrauenswürdige Abläufe verfügbar Ungeprüfte Jobs könnten auf Signier- oder Veröffentlichungsdaten zugreifen
Betriebsmodell Der Mac darf für Builds verfügbar und administrierbar sein Der Rechner muss unabhängig von einem Teamprozess strikt abgeschottet sein

Entscheidungszweige:
- Wenn der Workflow nur auf einem kontrollierten Branch läuft, der Runner-Zugriff auf dieses Repository begrenzt ist und keine nicht vertrauenswürdigen PR-Aufträge den Rechner erreichen, können Sie mit der Vorbereitung fortfahren.
- Wenn externe Beiträge oder Fork-Pull-Requests beteiligt sind, führen Sie diese nicht auf demselben Runner mit verfügbaren Geheimnissen aus. Trennen Sie den Build in eine isolierte Umgebung oder verwenden Sie einen geeigneten verwalteten Runner.
- Wenn kein Xcode- oder macOS-spezifischer Schritt benötigt wird, ist ein eigener Mac-Runner möglicherweise unnötiger Betriebsaufwand.

Sicherheitsgrenze: Ein Runner ist kein Ersatz für Workflow-Berechtigungen. Begrenzen Sie den Token-Zugriff in der Workflow-Datei und geben Sie Zugangsdaten nur an Jobs weiter, die sie tatsächlich benötigen. GitHub beschreibt die verfügbaren Berechtigungseinstellungen in der Referenz zur Workflow-Syntax.

Vor der Registrierung: macOS und Xcode auf dem Remote-Mac prüfen

Bevor Sie den Runner anmelden, muss der Mac aus der Sicht des vorgesehenen Betriebs erreichbar sein. Prüfen Sie den vorgesehenen Zugang, die Netzwerkverbindung zu GitHub und die Möglichkeit, Software und Runner-Komponenten zu aktualisieren. Ein Rechner, der nur in einer angemeldeten Desktop-Sitzung erreichbar ist, ist nicht automatisch ein verlässlicher unbeaufsichtigter Build-Knoten.

Der wichtigste technische Vorabtest ist nicht eine angenommene Modell- oder Spezifikationsliste, sondern der tatsächliche Aufruf der Werkzeuge, die das Projekt verwendet. Xcode und die Kommandozeilenwerkzeuge müssen auf dem System verfügbar sein. Apple dokumentiert sowohl die Installation der Xcode Command Line Tools als auch die Auswahl des aktiven Entwicklerverzeichnisses über die Einstellungen für Kommandozeilenwerkzeuge.

Prüfung Beispiel Erwarteter Nachweis
Aktives Entwicklerverzeichnis xcode-select -p Ein vorhandener Pfad zum ausgewählten Entwicklerverzeichnis
Xcode-Aufruf xcodebuild -version Ausgabe der installierten Xcode- und Build-Version
Projektübersicht xcodebuild -list -project Projekt.xcodeproj Die erwarteten Targets oder Schemes werden angezeigt
Netzwerk und Zugriff Anmeldung und Verbindung nach Betriebsmodell prüfen Der Mac erreicht GitHub und kann die vorgesehenen Runner-Schritte ausführen

Die Befehle ersetzen keinen Build des tatsächlichen Projekts. Ein erfolgreicher Versionsaufruf beweist nur, dass xcodebuild aufrufbar ist; er bestätigt nicht, dass Simulator-Runtimes, Abhängigkeiten, Projektkonfigurationen oder benötigte SDKs vollständig vorhanden sind. Führen Sie deshalb vor der Runner-Registrierung mindestens eine projektbezogene Prüfung aus und halten Sie fest, welche Meldungen dabei auftreten.

Lässt sich der Remote-Mac für iOS-Automatisierung dauerhaft online halten? Das hängt nicht allein von der Runner-Registrierung ab. Netzwerkverbindung, Stromversorgung, Neustartverhalten, macOS-Dienst und Wartungsfenster müssen zusammenpassen. Prüfen Sie im späteren Test ausdrücklich, ob der Runner nach einem Stopp oder Neustart wieder verfügbar wird, bevor Sie ihn für zeitkritische Builds einplanen.

Bei der Registrierung: Runner-Bereich und Labels bewusst wählen

Registrieren Sie den Runner in den Einstellungen des gewünschten Repositorys, der Organisation oder des Unternehmens. Die gewählte Ebene legt fest, wer den Runner verwalten und für welche Projekte er verfügbar sein kann. Für einen einzelnen App-Build ist eine enge Zuordnung zum Repository oft leichter zu überblicken als eine organisationsweite Freigabe; eine gemeinsame Teamumgebung kann dagegen eine bewusst verwaltete Organisationszuordnung erfordern. GitHub erläutert die Optionen in der Dokumentation zum Verwalten des Zugriffs auf selbst gehostete Runner.

Folgen Sie in der jeweiligen GitHub-Oberfläche dem Weg zum Hinzufügen eines macOS-Runners. GitHub zeigt dabei die zum Registrierungsbereich passenden Schritte für das Runner-Programm an. Laden Sie die Anwendung auf dem Remote-Mac herunter und führen Sie die dort angezeigten Konfigurationsschritte aus. Verwenden Sie keine Registrierungsdaten aus einem Beispiel oder einer Dokumentation: Der angezeigte Token ist für den konkreten Registrierungsablauf bestimmt und darf nicht in ein öffentliches Protokoll, ein Repository oder ein Ticket kopiert werden.

Bei der Konfiguration sind Name und Labels nicht nur dekorative Angaben. Der Name erleichtert die Zuordnung in der Runner-Verwaltung; Labels helfen dem Workflow, eine passende Maschine auszuwählen. Übernehmen Sie die von GitHub vorgesehenen Betriebssystem- und Architekturmerkmale und ergänzen Sie nur Labels, die Sie tatsächlich im Workflow verwenden. Prüfen Sie nach der Registrierung in der GitHub-Oberfläche, ob der Runner als online angezeigt wird.

Wie wird der eigene Mac mit GitHub Actions verbunden? Die Verbindung entsteht durch die Registrierung im passenden Verwaltungsbereich und die Konfiguration der Runner-Anwendung auf dem Mac. Eine bloße Anmeldung am GitHub-Konto reicht nicht: Erst der registrierte Runner-Prozess nimmt zugewiesene Jobs an. Die offiziellen Schritte zum Hinzufügen eines selbst gehosteten Runners sind maßgeblich, weil die angezeigten Befehle vom Zielbereich abhängen.

Dokumentieren Sie für den Betrieb den Repository- oder Organisationsbereich, den Runner-Namen, die vergebenen Labels und die zuständige Person. Speichern Sie keine geheimen Registrierungswerte in dieser Dokumentation. Wenn die Zuordnung falsch gewählt wurde oder die Maschine für nicht vorgesehene Projekte auftaucht, stoppen Sie den Ablauf und korrigieren Sie den Verwaltungsbereich, bevor Sie den ersten Build starten.

Nach der Anmeldung: macOS-Dienst und Sitzung getrennt testen

Ein registrierter Runner kann online erscheinen, ohne dass damit alle späteren Build-Anforderungen bewiesen sind. Für unbeaufsichtigten Betrieb sollte der Runner nach dem offiziellen macOS-Verfahren als Dienst eingerichtet werden. GitHub beschreibt die Konfiguration der Runner-Anwendung und des Dienstes; folgen Sie dabei den für die installierte Anwendung angezeigten Schritten statt kopierte Kommandos aus einer anderen Runner-Installation zu übernehmen.

Prüfen Sie danach zwei Zustände getrennt: den Status des macOS-Dienstes auf dem Rechner und den Online-Status des Runners in GitHub. Ein gestarteter Dienst beweist nicht, dass GitHub den Runner erreichen kann. Umgekehrt reicht ein vorübergehend online angezeigter Runner nicht als Beleg, dass er nach einer Abmeldung oder einem Neustart weiterarbeitet.

Auch die Ausführungsumgebung kann sich zwischen einer interaktiven Desktop-Sitzung und einem Dienst unterscheiden. PATH-Einstellungen, Zugriffsrechte, Umgebungsvariablen und verfügbare Dateien sind zu prüfen. Besonders bei Signierung ist nicht vorauszusetzen, dass ein Schlüsselbund, ein Zertifikat oder eine grafische Bestätigungsaktion im Hintergrund automatisch verfügbar ist. Binden Sie Signier- und Veröffentlichungszugangsdaten daher nicht in den ersten Funktionstest ein.

Betriebshinweis: Wenn ein Build nur bei geöffneter Desktop-Sitzung funktioniert, ist der Runner noch nicht für den vorgesehenen unbeaufsichtigten Ablauf abgenommen. Beheben Sie zuerst die Abweichung zwischen interaktiver Sitzung und Dienstbetrieb, statt sie durch dauerhafte Anmeldung zu kaschieren.

Beim ersten Workflow: Xcode-Kommandozeilen-Build auslösen

Der erste Workflow sollte möglichst wenig Berechtigungen besitzen und zunächst nur einen Build auf einem kontrollierten Branch ausführen. Damit lässt sich prüfen, ob die Job-Zuweisung, der Checkout und der Xcode-Aufruf funktionieren, ohne gleichzeitig Signierung oder App-Store-Veröffentlichung einzuführen.

Ein minimales Beispiel kann so aussehen; passen Sie Branch, Projektdatei und Scheme an das Repository an. Die verwendete Version der Checkout-Aktion sollte der Freigabe- und Aktualisierungsrichtlinie des Projekts entsprechen.

name: iOS Build

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  build:
    runs-on: [self-hosted, macOS]
    steps:
      - name: Repository auschecken
        uses: actions/checkout@v4

      - name: Xcode-Build ausführen
        run: |
          xcodebuild \
            -project "Projekt.xcodeproj" \
            -scheme "AppScheme" \
            -destination 'generic/platform=iOS Simulator' \
            build

Der Job verwendet die selbst gehosteten und macOS-bezogenen Runner-Labels, damit GitHub ihn dem passenden Runner zuordnen kann. Die verfügbaren Standardlabels und die Auswahl eines selbst gehosteten Runners in einem Workflow erklärt GitHub in der Anleitung zur Runner-Auswahl im Workflow. Wenn Sie eigene Labels vergeben haben, müssen diese zur runs-on-Angabe passen.

Welche Aufgabe bestätigt den Xcode-Kommandozeilen-Build zuverlässig? Verwenden Sie zunächst einen Build des tatsächlichen Projekts mit dem vorgesehenen Scheme und einer zum Ziel passenden Destination. xcodebuild -version allein reicht als Nachweis nicht. Erfassen Sie im Workflow-Protokoll den verwendeten Aufruf und das Ergebnis, und prüfen Sie, ob der Job tatsächlich auf dem beabsichtigten Runner ausgeführt wurde.

In diesem Schritt werden weder ein signiertes Archiv noch ein Upload vorbereitet. Das trennt Fehler in der Runner-Zuweisung und im Xcode-Build von späteren Problemen mit Zertifikaten, Provisioning Profiles oder Veröffentlichungsberechtigungen. Erst wenn der einfache Build wiederholbar funktioniert, sollte das Team Signierung und Veröffentlichung als eigene, eingeschränkt zugängliche Erweiterung planen. Für den Umgang mit personenbezogenen Daten und Zugangsdaten im eigenen Ablauf kann zusätzlich die Datenschutzerklärung als Orientierung für die Prüfung des eigenen Datenschutzprozesses dienen; sie ersetzt keine projektspezifische Sicherheitsbewertung.

Nach dem Test: Abnahme belegen und Wartung festlegen

Ein erfolgreicher Lauf ist ein Anfang, aber noch kein Nachweis für verlässlichen Dauerbetrieb. Legen Sie vor der täglichen Nutzung fest, welche Protokolle aufbewahrt, wer Fehler untersucht und wie der Runner nach Updates oder Störungen wieder freigegeben wird. GitHub bietet Hinweise zur Überwachung und Fehlersuche bei Runnern.

Abnahmekriterium Nachweis Bei fehlendem Nachweis
Runner erreichbar GitHub zeigt den Runner im vorgesehenen Bereich als online Netzwerk, Dienststatus und Registrierungsbereich prüfen
Job korrekt zugewiesen Workflow-Protokoll weist die erwartete Runner-Umgebung aus Labels und runs-on-Angabe abgleichen
Build nachvollziehbar Protokoll enthält Projektaufruf und Ergebnis Checkout, Scheme und Xcode-Umgebung untersuchen
Ergebnis projektgerecht Build-Artefakt oder erfolgreicher Build entspricht dem vereinbarten Ziel Build-Ziel und Projektkonfiguration korrigieren
Wiederanlauf geprüft Nach geplantem Stopp oder Neustart wird der Dienststatus erneut kontrolliert Dienstkonfiguration und Startverhalten prüfen

Als Mindestprozess sollte das Team einen Ablauf für Updates der Runner-Anwendung, die Prüfung von Workflow-Rechten, die Untersuchung fehlgeschlagener Jobs und die Entfernung nicht mehr benötigter Runner festlegen. Überprüfen Sie auch, ob Labels, Repository-Zuordnung und Berechtigungen noch zum tatsächlichen Zweck passen. Ein Runner, der für ein früheres Projekt eingerichtet wurde, sollte nicht unbemerkt als allgemeine Maschine für weitere Repositories verfügbar bleiben.

Können öffentliche Repositories einen macOS-Runner verwenden? Technisch kann ein Runner registriert werden; sicher ist die Verwendung aber nicht automatisch. GitHub warnt besonders vor nicht vertrauenswürdigem Code aus Fork-Pull-Requests auf selbst gehosteten Runnern. Wenn solche Beiträge in den Ablauf gelangen können, darf ein Runner mit sensiblen Zugangsdaten nicht als ungeschützte Ausführungsumgebung dienen. Beschränken Sie Ereignisse und Berechtigungen oder wählen Sie für diese Jobs eine getrennte Umgebung.

Wenn ein Remote-Mac bereits vorhanden ist, sollte die Entscheidung für den täglichen Runner-Betrieb an den beschriebenen Nachweisen hängen: sichere Auslöser, begrenzter Zugriff, funktionierender Dienst, erfolgreicher Projekt-Build und getesteter Wiederanlauf. Ein lokaler Mac bindet Anschaffung, Wartung und Platz; ein verwalteter Runner bietet nicht notwendigerweise dieselbe Kontrolle über eine dauerhaft angepasste Build-Umgebung. Ist ein macOS-Knoten für verlässliche CI erforderlich, aber eine eigene Hardwareanschaffung nicht gewünscht, kann ein gemieteter Remote-Mac eine prüfenswerte Zwischenlösung sein. Vergleichen Sie dafür die konkreten Betriebsbedingungen und die verfügbare Unterstützung in den KuzCloud-Informationen, bevor Sie ihn für einen GitHub Actions macOS Runner einplanen.

Richten Sie Ihren dedizierten Remote-Mac bei KuzCloud ein

Nutzen Sie einen exklusiven macOS-Knoten mit vollem Root-Zugang für reproduzierbare Builds und CI/CD-Workflows.

Verbinden Sie sich per SSH oder VNC und installieren Sie die benötigten Entwicklungswerkzeuge selbst.