Wie setzen Sie Docker CI auf selbstgehosteten Macs mit macOS 27 ein? Leitfaden 2026

GitHub zieht bei selbstgehosteten Runnern eine klare Systemgrenze: Für Docker-Container-Actions und Service Container ist Linux erforderlich (GitHub-Dokumentation zu selbstgehosteten Runnern). Ein Mac unter macOS 27 kann daher für geprüfte Docker-Builds dienen, aber nicht als gleichwertiger Ersatz für einen Linux-Runner mit diesen Container-Funktionen. Prüfen Sie vor der Einrichtung die Docker-Desktop-Unterstützung, die Teamlizenz und die tatsächlichen Berechtigungen der Zielumgebung.
Dieser Leitfaden richtet sich an DevOps-Teams, die Docker-Builds in GitHub Actions integrieren und einen selbstgehosteten Mac-Runner bereitstellen möchten.
Er hilft dabei, macOS-Schritte und Docker-Aufgaben passend auf Mac- und Linux-Runner aufzuteilen.
Verantwortliche für gemietete CI-Umgebungen erhalten außerdem Prüfpunkte zu Lizenz, Virtualisierung und Betrieb.
Zuletzt aktualisiert am 04.10.2026. Die Aussagen wurden anhand der GitHub-Dokumentation für Runner und Workflow-Routing sowie der Docker-Dokumentation zu Installation, Lizenz und Buildx abgeglichen. Die konkrete Unterstützung von macOS 27 durch Docker Desktop und die Möglichkeiten einer gemieteten Umgebung müssen vor der Inbetriebnahme anhand der dann aktuellen Dokumentation und im Zielsystem geprüft werden.
Vor dem Deployment: Mac-Runner und Linux-Runner nach Jobtyp trennen
„Docker-CI“ bezeichnet nicht immer dieselbe Ausführung. Ein Workflow kann einen Docker-Build direkt auf dem Runner-Host starten, eine Container-Action verwenden oder einen Service Container für Tests anfordern. Diese Varianten haben unterschiedliche Anforderungen. Ein verfügbarer Docker-Befehl allein belegt nicht, dass alle Jobtypen auf macOS funktionieren.
| Workflow-Aufgabe | Passender Runner | Was vorab zu prüfen ist |
|---|---|---|
| Shell-Schritt auf macOS, der einen Docker-Build startet | Mac-Runner, sofern Docker Desktop im Zielsystem unterstützt und funktionsfähig ist | Docker CLI, Verbindung zum Daemon, Berechtigungen, Build-Ergebnis und Zugang zum Image-Registry |
| Docker-Container-Action | Linux-Runner | GitHubs Linux-Anforderung für selbstgehostete Runner |
| Service Container, etwa für einen Testjob | Linux-Runner | Betriebssystemvorgabe und Erreichbarkeit zwischen Job und Service |
| macOS-spezifischer Arbeitsschritt ohne Container-Action | Mac-Runner | System- und Architekturkompatibilität sowie benötigte Host-Berechtigungen |
Die Einschränkung bei Container-Actions und Service Containern ist keine Vermutung über Docker Desktop, sondern eine Vorgabe der GitHub-Anforderungen an selbstgehostete Runner. Sie betrifft diese Workflow-Funktionen. Sie bedeutet nicht automatisch, dass jeder Host-seitige Docker-Aufruf auf einem Mac fehlschlägt.
Ein typischer Fall: Ein Team will macOS-spezifische Schritte und das Erstellen eines Images in einer Pipeline bündeln. Der Image-Build kann als Shell-Schritt auf einem Mac-Runner getestet werden. Benötigt der Testjob zusätzlich einen Datenbank-Service als Service Container, gehört dieser Job auf einen Linux-Runner. Alternativ kann das Team die Pipeline in getrennte Jobs aufteilen und Artefakte zwischen den passenden Umgebungen weitergeben.
Entscheidung nach Abhängigkeit statt nach verfügbarem Docker-Befehl
- Wenn ein Job macOS voraussetzt und Docker nur über einen Host-Shell-Schritt aufruft, testen Sie ihn auf dem Mac-Runner. Übernehmen Sie den Job erst nach erfolgreicher Prüfung von Build, Anmeldung und Artefakt.
- Wenn ein Job eine Docker-Container-Action oder einen Service Container verwendet, routen Sie ihn auf einen Linux-Runner.
- Wenn beides im selben Job steckt, teilen Sie den Job nach Möglichkeit auf. Andernfalls ist der Linux-Runner die sichere Wahl für die Container-Abhängigkeit; der macOS-Teil muss separat ausgeführt werden.
- Wenn Docker Desktop in der Zielumgebung nicht unterstützt wird oder erforderliche Rechte fehlen, stoppen Sie die Mac-Einrichtung für diesen Build und verwenden Sie einen geeigneten Linux-Runner oder eine andere geprüfte Umgebung.
Damit ist vor der Registrierung klar, welche Fähigkeiten der Mac-Runner tatsächlich liefern muss. Auch die Zahl der Runner und deren Labels sollten aus dieser Aufteilung folgen, nicht aus der bloßen Absicht, „Docker auf dem Mac“ zu betreiben.
Registrierung: Wie richten Sie den GitHub-Actions-Mac-Runner passend ein?
Ein selbstgehosteter Runner wird entweder einem Repository oder einer Organisation zugeordnet. Die Wahl hängt davon ab, wer den Runner verwenden darf und wie zentral das Team den Betrieb verwalten will. GitHub beschreibt das Hinzufügen von Runnern und die verfügbaren Verwaltungsschritte in der Anleitung zum Einrichten selbstgehosteter Runner. Die tatsächlich angezeigten Optionen und erforderlichen Berechtigungen richten sich nach dem jeweiligen GitHub-Kontext; sie sollten nicht aus einer Anleitung für ein anderes Repository abgeleitet werden.
Legen Sie vor der Registrierung fest, welche Workflows den Mac erreichen dürfen. Ein Repository-Runner begrenzt den Einsatz auf den jeweiligen Repository-Kontext. Ein Runner auf Organisationsebene kann für mehrere passende Projekte vorgesehen werden, benötigt aber eine sorgfältige Zugriffskontrolle. Runner-Gruppen helfen dabei, die Nutzung bestimmter Runner auf ausgewählte Repositorys zu beschränken. Die Gruppe ersetzt nicht die Prüfung, ob ein Job für macOS geeignet ist.
Bei Labels gilt: Ein Job muss die Labels des gewünschten Runners erfüllen. Verwenden Sie daher eindeutige Bezeichnungen für Betriebssystem, Architektur und Aufgabe, etwa self-hosted, macOS und ein teaminternes Label für den Docker-Host-Build. Vermeiden Sie ein allgemeines Label wie docker, wenn damit auch Jobs angesprochen werden könnten, die Container-Actions oder Service Container voraussetzen. GitHub erläutert die Runner-Auswahl über Labels und Gruppen.
Ein minimales Routing-Beispiel kann so aussehen:
jobs:
image-build:
runs-on: [self-hosted, macOS, docker-host-build]
steps:
- uses: actions/checkout@v4
- name: Docker-Build auf dem Runner-Host
run: docker build -t beispiel-image .
Das Beispiel zeigt die Absicht des Routings, nicht eine vollständige Produktionskonfiguration. Verwenden Sie die für Ihr Projekt freigegebene Action-Version und ergänzen Sie Checkout, Registry-Anmeldung sowie Artefaktverarbeitung nach den Sicherheitsvorgaben des Teams. Ein Container-Service-Job sollte ein passendes Linux-Label erhalten und getrennt bleiben. Prüfen Sie nach dem ersten Lauf im Workflow-Protokoll, welcher Runner den Job übernommen hat; ein erfolgreich gespeicherter YAML-Workflow beweist noch nicht, dass die gewünschte Maschine ausgewählt wurde.
Für die Kommunikation muss der Runner die von GitHub benötigten Dienste erreichen können. Bei restriktiven Netzwerken sind daher ausgehende Verbindungen, Proxy-Regeln und Firewall-Vorgaben gemeinsam mit dem Netzwerkteam zu prüfen. GitHub führt Kommunikationsanforderungen in der Runner-Referenz auf. Ein Runner, der offline erscheint oder keine Jobs abholt, ist zunächst ein Erreichbarkeits- und Registrierungsproblem, kein Docker-Build-Fehler.
Docker Desktop auf macOS 27: Unterstützung, Lizenz und Rechte zuerst klären
Die macOS-Version im Titel ist kein Kompatibilitätsnachweis. Docker verlangt für die Installation von Docker Desktop eine unterstützte macOS-Version. Der unterstützte Versionsbereich kann sich ändern; gleichen Sie ihn deshalb unmittelbar vor dem Deployment mit der aktuellen Installationsdokumentation für Docker Desktop auf dem Mac ab. Für macOS 27 gilt: Ohne eine Bestätigung in der aktuellen Dokumentation und einen erfolgreichen Test im Zielsystem sollte das Team keine Kompatibilität voraussetzen.
Prüfen Sie neben der Betriebssystemversion auch Prozessorarchitektur, Installationsweg, verfügbare Virtualisierungsfunktionen und die benötigten Benutzerrechte. Bei einem gemieteten oder anderweitig virtualisierten Mac muss der Anbieter die für Docker Desktop erforderlichen Eigenschaften im konkreten Angebot und System bestätigen. Dass ein Mac remote zugänglich ist, beweist nicht, dass Docker Desktop dort installiert und gestartet werden darf. Docker führt die Voraussetzungen und Berechtigungen für Docker Desktop auf macOS gesondert auf.
Die Lizenzfrage ist unabhängig davon zu beantworten, ob ein Build technisch startet. Docker veröffentlicht die Bedingungen für die kommerzielle Nutzung von Docker Desktop in seiner Lizenzübersicht. Prüfen Sie anhand dieser Bedingungen, ob die Organisation für den vorgesehenen Einsatz eine Lizenz benötigt. Unternehmensgröße, Nutzungszweck und interne Richtlinien können für die Bewertung relevant sein. Ein CI-System sollte nicht mit einer Annahme wie „kostenlos für Entwickler“ freigegeben werden, ohne die konkrete Teamnutzung gegen die aktuelle Regelung zu halten.
| Prüffeld | Vor Freigabe belegen | Abbruch- oder Rückfallkriterium |
|---|---|---|
| macOS-Unterstützung | Die aktuelle Docker-Dokumentation führt das Zielsystem als unterstützt | Version nicht aufgeführt oder Status unklar: nicht produktiv einplanen |
| Architektur und Virtualisierung | Zielsystem und Docker Desktop starten im realen Einsatzmodell | Funktion im gemieteten oder virtualisierten System nicht nachweisbar: Linux-Alternative prüfen |
| Benutzerrechte | Installation und erster Start sind mit dem vorgesehenen Runner-Konto möglich | Erforderliche Freigaben fehlen: Rechte klären, nicht umgehen |
| Docker-Desktop-Lizenz | Verantwortliche haben die konkrete Teamnutzung anhand der Docker-Bedingungen bewertet | Lizenzbedarf ungeklärt: vor dem produktiven Einsatz klären |
| Netzwerk und Registry | Runner erreicht GitHub und die benötigten Image-Registry-Endpunkte | Firewall, Proxy oder Zugang verhindern den Ablauf: Netzwerkfreigabe herstellen |
Diese Prüfung kostet vor dem ersten Pipeline-Lauf Zeit, verhindert aber eine häufige Fehlannahme: Eine erfolgreiche macOS-Runner-Registrierung sagt nichts über Docker-Desktop-Lizenz, Virtualisierung oder Daemon-Zugriff aus. Für personenbezogene Zugriffsdaten und gespeicherte Zugangsinformationen sollte das Team außerdem seine internen Datenschutzregeln einbeziehen. Die Datenschutzhinweise von ProxyMac können bei der Prüfung von Datenschutzfragen zu einer gemieteten Umgebung als zusätzlicher Orientierungspunkt dienen; sie ersetzen weder die eigene Datenschutzbewertung noch eine Vertragsprüfung.
Erster Build: Docker-Image mit einem Host-Shell-Schritt verifizieren
Nach der Installation sollte zunächst ein kleiner, nicht produktiver Build auf dem tatsächlichen Runner laufen. Damit werden vier voneinander unabhängige Punkte sichtbar: Ist die Docker-CLI vorhanden? Kann sie den Daemon erreichen? Wird das Image wie erwartet erzeugt? Funktioniert anschließend der Zugriff auf die Registry oder den vorgesehenen Artefaktweg?
Führen Sie die Prüfung in einer kontrollierten Reihenfolge aus:
- Runner identifizieren. Kontrollieren Sie im Jobprotokoll, dass der Workflow auf dem vorgesehenen Mac-Runner gelandet ist. Prüfen Sie das System und die Architektur mit den verfügbaren Host-Werkzeugen, statt sie aus dem Runner-Label abzuleiten.
- Docker-CLI aufrufen. Lassen Sie den Job die Docker-Version ausgeben und die Verbindung zum Daemon prüfen. Eine installierte CLI ohne erreichbaren Daemon reicht für einen Build nicht aus.
- Minimales Dockerfile verwenden. Erstellen Sie ein Testimage aus einem kleinen, nachvollziehbaren Kontext. Verwenden Sie für die Erstprüfung keine vertraulichen Produktionsdaten und keine unkontrollierten Build-Skripte.
- Buildx ausführen. Nutzen Sie den dokumentierten Build-Befehl und legen Sie bewusst fest, ob das Image nur lokal erzeugt oder in eine Registry geschrieben werden soll. Die verfügbaren Optionen für Ausgabe, Plattform und Cache sind in der Buildx-Referenz zu
docker buildx buildbeschrieben. - Ergebnis prüfen. Kontrollieren Sie den Build-Status, den Image-Namen und den vorgesehenen Ausgabepfad. Wenn der nächste Schritt einen Push erfordert, prüfen Sie die Anmeldung mit einem dafür vorgesehenen, begrenzten CI-Geheimnis.
- Aufräumen und wiederholen. Entfernen Sie Testartefakte und vertrauliche Anmeldedaten nach dem Test. Wiederholen Sie den Ablauf nach einem Runner-Neustart, damit eine nur temporär verfügbare Sitzung nicht fälschlich als betriebsbereit gilt.
Die Buildx-Konfiguration sollte zur tatsächlichen Zielplattform passen. Bei plattformübergreifenden Images sind Architektur, Emulation und Build-Umgebung gesondert zu testen. Docker dokumentiert die Grundlagen in der Anleitung zu Multi-Platform-Builds. Daraus folgt keine Garantie für eine bestimmte Build-Zeit oder identisches Verhalten in jeder gemieteten Umgebung. Bewerten Sie Erfolg anhand der benötigten Image-Plattformen und der Ergebnisse im Zielsystem, nicht anhand einer unbelegten Geschwindigkeitsannahme.
Eine sinnvolle Testreihe umfasst zunächst den lokalen Build ohne Push, danach einen kontrollierten Push in eine Test-Registry und zuletzt einen Workflow-Lauf mit dem vorgesehenen Cache-Verhalten. Trennen Sie Build-Fehler von Authentifizierungsfehlern. Ein Image, das lokal entsteht, aber nicht hochgeladen werden kann, weist nicht zwingend auf eine Docker-Desktop-Störung hin; Ursache können fehlende Secrets, Netzwerkregeln oder Registry-Berechtigungen sein.
Für Buildx-Cache gilt ebenfalls: Legen Sie fest, wo Cache-Daten gespeichert werden, wer sie lesen darf und wann sie entfernt werden. Ein gemeinsam genutzter Cache kann Build-Arbeit sparen, darf aber nicht unbeabsichtigt Daten zwischen nicht vertrauenswürdigen Workflows austauschen. Richten Sie die konkrete Cache-Strategie nach den Projektanforderungen und den dokumentierten Buildx-Optionen aus, statt einen Cache-Schlüssel ungeprüft für alle Jobs zu verwenden.
Workflow-Routing: Mac für Host-Builds, Linux für Container-Jobs
Die richtige Trennung entsteht aus den Abhängigkeiten jedes Jobs. Ein Docker-Image-Build, der als Shell-Befehl auf dem Host läuft, kann auf dem Mac-Runner verbleiben, wenn Installation, Lizenz, Daemon und Ergebnis im Zielsystem erfolgreich geprüft sind. Eine Container-Action oder ein Service Container muss dagegen auf einen Linux-Runner. Genau diese Trennung sollte sich in den Labels und im Workflow wiederfinden.
Prüfen Sie außerdem, ob ein Job mehrere Aufgaben bündelt, die unterschiedliche Systeme verlangen. Ein Build auf macOS und ein Integrationstest mit Service Container gehören nicht automatisch in denselben Job. Wird daraus ein mehrstufiger Ablauf, müssen die Übergabe des Images oder anderer Artefakte, die Authentifizierung und die Löschung temporärer Daten explizit geregelt sein. Richten Sie die Runner-Auswahl über Labels passend zu den tatsächlichen Jobanforderungen ein.
Ein robuster Routing-Ansatz hat klare Vorteile: macOS-Schritte laufen dort, wo sie benötigt werden; containerbasierte Tests landen auf einem dafür geeigneten Linux-Runner; und Fehler lassen sich der jeweiligen Umgebung zuordnen. Der Preis dafür ist zusätzlicher Betriebsaufwand. Es müssen mehr als ein Runner-Typ, die Artefaktübergabe und getrennte Zugriffsregeln gepflegt werden. Das ist meist weniger riskant, als einen Mac-Runner mit einem allgemeinen Label für Jobs freizugeben, deren Container-Anforderungen er nicht erfüllen kann.
Betrieb: Zugangsdaten, Cache und Runner-Updates kontrollieren
Ein selbstgehosteter Runner ist Teil der CI-Infrastruktur und braucht einen klar verantwortlichen Betrieb. Legen Sie fest, wer den Runner aktualisieren, neu registrieren und außer Betrieb nehmen darf. Prüfen Sie, welche Repositorys und Workflows Zugriff erhalten. Halten Sie Produktionsgeheimnisse aus Testläufen heraus und geben Sie Tokens nur mit den für den jeweiligen Schritt notwendigen Rechten frei.
Vor der Freigabe sollten folgende Abläufe in einer nicht produktiven Pipeline getestet werden:
- Fehler und Wiederholung: Kann ein fehlgeschlagener Build gezielt erneut gestartet werden, ohne alte Artefakte oder falsche Cache-Inhalte zu übernehmen?
- Bereinigung: Werden temporäre Images, Arbeitsverzeichnisse und Zugangsdaten nach dem Job zuverlässig entfernt?
- Runner-Ausfall: Ist erkennbar, ob ein Job wegen fehlender Runner-Verfügbarkeit, Netzwerkzugriff oder eines Build-Fehlers wartet?
- Änderungen: Werden Änderungen an macOS, Docker Desktop, Runner-Software und Workflow-Konfiguration dokumentiert und vor der breiten Einführung geprüft?
- Datenschutz und Zugriff: Sind Speicherung und Verarbeitung von Quellcode, Protokollen und Secrets mit den internen Vorgaben vereinbar?
Bewahren Sie dazu ein knappes Änderungsprotokoll mit Systemversion, Docker-Desktop-Version, Runner-Konfiguration und Workflow-Änderungen auf. Diese Angaben helfen, Regressionen nach Updates einzugrenzen. Tragen Sie keine vermeintlich allgemein gültige Kompatibilitätsfreigabe ein: Docker Desktop kann seinen unterstützten macOS-Bereich ändern, und ein Update im Zielsystem kann einen zuvor erfolgreichen Installations- oder Build-Ablauf beeinflussen. Prüfen Sie die Installationsvoraussetzungen vor einem geplanten Update erneut.
Wenn der Betrieb eines gemieteten CI-Macs geprüft wird, klären Sie technische Zugänge, Installationsrechte und die Grenzen der Umgebung vor der Buchung. Die Hilfe von ProxyMac kann für Fragen zum verfügbaren Zugang herangezogen werden; ob Docker Desktop in einer konkreten Konfiguration funktioniert, muss dennoch im Zielsystem getestet werden. Es sollte insbesondere nicht vorausgesetzt werden, dass Virtualisierung, privilegierte Einstellungen oder eine Docker-Desktop-Lizenz automatisch enthalten sind.
Für ein Team, das ausschließlich Linux-Container-Jobs ausführt und keine macOS-Schritte benötigt, ist ein Linux-Runner in der Regel die direktere CI-Wahl: Er vermeidet eine zusätzliche Mac-spezifische Docker-Desktop-Prüfung. Ein eigener Mac lohnt sich eher, wenn Host-Schritte tatsächlich macOS verlangen und das Team die Installation, Lizenz und Wartung selbst tragen kann. Wer nur vorübergehend eine Mac-Umgebung für diese Validierung benötigt, kann eine zeitlich begrenzte Mac-Miete von ProxyMac als Testweg prüfen. Das kann gegenüber einem dauerhaft selbst betriebenen Mac die passendere Erfahrung sein, sofern Rechte, Docker-Desktop-Unterstützung und Zugriff für den konkreten Workflow vorab bestätigt werden. ProxyMac ist damit eine Option für die Umgebungsevaluierung, keine Zusage, dass jeder Docker-CI-Job auf einem Mac ausführbar ist.