GitLab-CI-Mac-Runner einrichten? Bereitstellungs- und Abnahmeleitfaden 2026

GitLab führt den Shell Executor im Wartungsmodus und weist auf seine begrenzte Isolation hin (GitLab-Dokumentation zum Shell Executor). Symptom: Apple-Builds brauchen macOS, aber ein beliebiger CI-Knoten ist keine sichere Ausführungsumgebung. Schnellste Lösung: Richten Sie den GitLab-CI-Mac-Runner zunächst nur auf einem dedizierten, vertrauenswürdigen Mac ein und geben Sie ihn erst nach einem echten Build- und Wiederherstellungstest frei.

Dieser Leitfaden ist für iOS- und macOS-Entwickler gedacht, die Builds oder Tests an einen Mac in GitLab CI übergeben möchten.
Er hilft DevOps-Teams, Registrierung, Benutzerkontext und Wiederanlauf nachvollziehbar zu prüfen.
Plattform- und Sicherheitsverantwortliche erhalten Kriterien, um Shell Executor, Projektvertrauen und Signiermaterial abzugrenzen.

SECTION 01Vor dem Setup: Ist ein Mac Runner für Ihre Pipeline die richtige Wahl?

Ein GitLab Runner lässt sich auf macOS installieren. GitLab dokumentiert für Apple-Plattform-Builds den Shell Executor als mögliche Ausführungsmethode; das macht ihn jedoch nicht zu einer isolierten Laufzeit. Prüfen Sie zuerst, welche Pipeline-Aufgaben tatsächlich macOS voraussetzen, und halten Sie allgemeine Tests und plattformunabhängige Jobs getrennt. Die GitLab-Anleitung zur Installation unter macOS beschreibt die Installation und Konfiguration auf dem Betriebssystem.

Ein Mac-Knoten ist vor allem dann sinnvoll, wenn ein Job Xcode, macOS-spezifische Werkzeuge, einen Simulator oder eine Apple-Signierumgebung benötigt. Quellcode-Prüfungen, Formatierung und viele serverseitige Tests können gegebenenfalls auf bestehenden Linux-Runnern bleiben. Diese Trennung verringert den Umfang der Projekte, die Zugriff auf den Mac-Knoten erhalten müssen; sie ersetzt aber keine Sicherheitsprüfung.

Behandeln Sie den Shell Executor als Ausführung auf einem normalen Benutzerkonto des Hosts, nicht als Container oder Sicherheitsgrenze. GitLab weist darauf hin, dass der Executor nur begrenzte Isolation bietet und sich im Wartungsmodus befindet. Die Übersicht zum Status der GitLab-Runner-Executor hilft, den Status im Kontext anderer unterstützter Ausführungsarten zu prüfen. Leiten Sie daraus nicht ab, dass eine Alternative auf Ihrer macOS-Version verfügbar ist oder automatisch eine sichere Apple-Toolchain bereitstellt.

Vor dem Start sollten Sie diese Entscheidung festhalten:

• Weiter mit einem Pilotbetrieb, wenn der Mac ausschließlich für bekannte, vertrauenswürdige Projekte vorgesehen ist und ein verantwortliches Team Konto, Updates und Wiederherstellung betreut.
• Erst Architektur und Berechtigungen ändern, wenn externe Beiträge, unbekannte Skripte oder Projekte mehrerer Vertrauensstufen denselben Runner verwenden sollen.
• Keinen produktiven Signierzugriff freigeben, solange Repository-Zugriff, Arbeitsbereichsbereinigung und Schlüsselbund nicht geprüft sind.
• Auf einen Mac-Knoten verzichten, wenn die Pipeline keine macOS-spezifischen Werkzeuge benötigt und der bestehende Runner die Aufgabe sicher erledigt.

Ein typischer Fehlerfall: Der Runner wird als „online“ angezeigt, ein plattformunabhängiger Job läuft, und daraus wird die Freigabe für den iOS-Release-Build abgeleitet. Diese Beobachtung belegt weder, dass Xcode verfügbar ist, noch, dass der richtige Benutzerkontext und Signierzugriff bestehen. Definieren Sie daher vorab getrennte Nachweise für Erreichbarkeit, Jobplanung, Werkzeugkette, Build und Wiederanlauf.

SECTION 02Schritt 1: Vertrauensgrenze und Zuständigkeit festlegen

Verwenden Sie keinen gemeinsam genutzten persönlichen Entwicklungs-Mac als CI-Knoten, wenn dort private Schlüssel, persönliche Konten oder nicht kontrollierte Projekte liegen. Ein dedizierter Rechner oder eine klar abgegrenzte Mac-Umgebung erleichtert die Zuordnung von Änderungen, Berechtigungen und Protokollen. Legen Sie fest, welche Personen den Runner verwalten dürfen, welche Projekte ihn verwenden dürfen und wer bei einem fehlgeschlagenen oder verdächtigen Job eingreift.

Der Runner sollte projektbezogene Aufgaben nur dann annehmen, wenn das Projekt und seine Pipeline-Konfiguration als vertrauenswürdig eingestuft sind. Ein CI-Skript wird mit den Rechten des ausführenden Kontos gestartet. Mit diesen Rechten kann es auf Dateien und Werkzeuge zugreifen, die diesem Konto offenstehen. Deshalb ist es riskant, auf demselben Knoten unkontrollierte Änderungen auszuführen und zugleich Zugang zu Signiermaterial oder vertraulichen Arbeitsverzeichnissen bereitzustellen.

Die GitLab-Sicherheitshinweise zu selbstverwalteten Runnern sind für diese Abwägung maßgeblich. Prüfen Sie insbesondere, welche Projekte Jobs auf dem Runner auslösen können und wie Änderungen an CI-Konfigurationen überprüft werden. Falls Ihr Team Beiträge aus nicht vertrauenswürdigen Quellen verarbeitet, sollte der Mac-Shell-Runner nicht als gemeinsames Ziel für diese Jobs dienen.

Dokumentieren Sie auch den Rückweg: Wer kann den Runner deaktivieren? Wie wird ein kompromittiertes Benutzerkonto gesperrt? Welche Projekte werden nach einem Vorfall von der Ausführung ausgeschlossen? Ohne einen solchen Rückweg ist ein Pilotversuch schwer zu begrenzen, selbst wenn der erste Build erfolgreich war.

SECTION 03Schritt 2: macOS und Xcode als nachvollziehbare Basis vorbereiten

Wählen Sie den Benutzer, unter dem Runner und Build-Werkzeuge laufen sollen, bevor Sie Xcode installieren oder Runner-Aufträge konfigurieren. Der Benutzerkontext beeinflusst, welche Verzeichnisse, Einstellungen und Schlüsselbundeinträge der Job sieht. Vermeiden Sie wechselnde Konten zwischen Installation, manueller Xcode-Prüfung und CI-Ausführung; sonst testen Sie womöglich eine andere Umgebung als die, in der später gebaut wird.

Installieren Sie die für Ihr Projekt benötigte Xcode-Version oder die passenden Kommandozeilenwerkzeuge entsprechend der Apple-Dokumentation. Apple beschreibt die Installation der Xcode-Kommandozeilenwerkzeuge und stellt eine Referenz zu den Xcode-Kommandozeilenwerkzeugen bereit. Welche Xcode- und macOS-Kombination zu Ihrem Projekt passt, müssen Sie anhand der Projektanforderungen und der jeweils aktuellen Apple-Angaben bestimmen; eine pauschale Versionsannahme wäre keine belastbare Abnahme.

Prüfen Sie im vorgesehenen Benutzerkonto, welcher Entwicklerpfad aktiv ist, ob die erwartete Xcode-Installation vorhanden ist und ob die benötigten Werkzeuge aufrufbar sind. Halten Sie die tatsächlich ausgewählte Toolchain sowie die Ausgabe Ihrer Prüfkommandos in der Betriebsdokumentation fest. Diese Aufzeichnung ist wichtiger als eine Installationsnotiz, weil sie den späteren Vergleich mit der Jobumgebung ermöglicht.

Einige häufig übersehene Punkte gehören ebenfalls zur Basis:

• Akzeptierte Lizenzbedingungen: Stellen Sie sicher, dass die notwendige Xcode-Einrichtung im vorgesehenen Benutzerkontext abgeschlossen ist.
• Werkzeugpfad: Prüfen Sie, ob die aktive Entwicklerumgebung auf die vorgesehene Xcode-Installation zeigt und nicht auf eine andere lokale Toolchain.
• Arbeitsverzeichnis: Definieren Sie, welche Daten nach einem Job entfernt oder zurückgesetzt werden und welche Caches bewusst erhalten bleiben.
• Projektbedarf: Notieren Sie benötigte Simulatoren, Build-Schemata und zusätzliche Werkzeuge, statt ihre Verfügbarkeit aus einer erfolgreichen Xcode-Installation abzuleiten.

Beachten Sie: Ein installierter Runner und ein installierter Xcode sind zwei getrennte Voraussetzungen. Erst der CI-Job zeigt, ob der Runner unter seinem tatsächlichen Konto dieselben Werkzeuge erreicht wie Ihre manuelle Sitzung.

SECTION 04Schritt 3: Runner installieren und mit begrenztem Zugriff registrieren

Folgen Sie der aktuellen GitLab-Anleitung für macOS, statt Installationsschritte aus einer nicht verifizierten Anleitung zu übernehmen. Die genaue Runner-Version und die dazu passende macOS-Umgebung müssen Sie bei der Einrichtung anhand der offiziellen Unterlagen und Ihres realen Knotens prüfen. Registrieren Sie den Runner mit einem klaren Namen und Tags, die den vorgesehenen Zweck beschreiben, beispielsweise für Apple-Build-Aufgaben. Tags sind jedoch keine Zugriffskontrolle: Sie verhindern nicht, dass eine unpassende Pipeline-Konfiguration den Knoten anfordert.

Für die Registrierung zeigt GitLab den Ablauf in der Dokumentation zur Runner-Registrierung. Verwenden Sie im Terminal nur die erforderlichen Angaben und behandeln Sie Registrierungstoken wie Zugangsdaten. Tragen Sie echte Tokens nicht in ein öffentliches Beispiel, ein Repository oder ein dauerhaft gespeichertes Terminalprotokoll ein. Im folgenden Schema stehen Platzhalter anstelle vertraulicher Werte:

gitlab-runner register \
  --url "<GITLAB-INSTANCE-URL>" \
  --token "<REGISTRIERUNGSTOKEN>" \
  --executor "shell"

Prüfen Sie vor der Bestätigung, ob die Instanz-URL, der Runner-Name und die Tags zu Ihrem Betriebsmodell passen. Der Executor-Wert ist hier bewusst shell: Er ist für macOS-Builds ein dokumentierter Ansatz, aber wegen seiner begrenzten Isolation nur für die zuvor freigegebene Vertrauensgrenze geeignet. Sie können die Shell-Executor-Beschreibung von GitLab neben der eigenen Registrierung als Referenz verwenden.

Wichtig ist der Unterschied zwischen LaunchAgent und LaunchDaemon: GitLab dokumentiert den macOS-Runner als benutzerbezogenen LaunchAgent, der von einer angemeldeten Benutzersitzung abhängt. Er ist daher nicht einfach ein systemweiter LaunchDaemon, der unabhängig von einer Benutzeranmeldung läuft. Prüfen Sie die tatsächliche Installations- und Startmethode auf Ihrem Knoten. Planen Sie nicht mit einem Hintergrunddienstverhalten, das Ihre konkrete Installation nicht nachweislich erfüllt.

Automatische Anmeldung ist keine neutrale Komfortoption. Sie kann dafür sorgen, dass eine Benutzersitzung nach einem Neustart verfügbar ist, erhöht aber zugleich die Bedeutung physischer Zugangskontrolle, Kontoschutz und der dort zugänglichen Geheimnisse. Falls Ihr Betrieb eine dauerhafte Sitzung erfordert, müssen Sicherheitsverantwortliche diese Entscheidung ausdrücklich freigeben. Wenn die Sicherheitsanforderungen keine automatische Anmeldung erlauben, muss die Betriebsplanung mit dem tatsächlichen Verhalten des benutzergebundenen Agents vereinbar sein.

SECTION 05Schritt 4: Mit einem Minimaljob den wirklichen Xcode-Aufruf belegen

Beginnen Sie nicht mit dem vollständigen Release-Prozess und allen Signierdaten. Verwenden Sie einen kleinen Pipeline-Job, der eindeutig an den vorgesehenen Runner gebunden ist, das Repository auscheckt und Diagnoseausgaben zur ausführenden Umgebung erzeugt. Namen, Repository, Tags, Scheme und Pfade sollten in Beispielen Platzhalter bleiben; in Ihrer Projektkonfiguration setzen Sie anschließend die echten Werte ein.

Ein schematischer Job kann so aussehen:

macos_build_check:
  tags:
    - "<MAC_RUNNER_TAG>"
  script:
    - whoami
    - xcode-select -p
    - xcodebuild -version
    - xcodebuild -list -project "<PROJEKTPFAD>"
    - xcodebuild -project "<PROJEKTPFAD>" -scheme "<SCHEME>" build

Passen Sie die Build-Befehle an die tatsächliche Projektstruktur an; nicht jedes Projekt verwendet dieselbe Projektdatei oder dasselbe Scheme. Entscheidend ist, dass das Protokoll nachvollziehbar zeigt, welcher Runner den Job ausgeführt hat, welches Konto den Shell-Prozess gestartet hat und welcher Entwicklerpfad für Xcode aktiv war. Der anschließende Projekt-Build muss tatsächlich durchlaufen, bevor Sie von einem funktionierenden Xcode CI sprechen.

Werten Sie die Ergebnisse als getrennte Abnahmestufen aus:

1. Runner erreichbar: GitLab zeigt den Runner als verfügbar.
2. Job zugeordnet: Ein Job mit den vorgesehenen Tags wird diesem Runner zugewiesen.
3. Shell-Kontext nachgewiesen: Das Protokoll zeigt das erwartete Benutzerkonto und den Zugriff auf das ausgecheckte Repository.
4. Toolchain verifiziert: Pfad und Versionsausgabe stimmen mit der dokumentierten Xcode-Basis überein.
5. Projekt-Build bestanden: Der echte Build-Befehl für Projekt und Scheme endet erfolgreich.

Diese Unterscheidung verhindert, dass ein grüner Online-Status mit einem erfolgreichen Apple-Build verwechselt wird. Wenn xcodebuild lokal funktioniert, aber im CI-Job nicht gefunden wird, vergleichen Sie zunächst Benutzer, Umgebungsvariablen und aktiven Entwicklerpfad. Verändern Sie nicht vorschnell globale Einstellungen, bevor Sie den Unterschied zwischen interaktiver Sitzung und Runner-Prozess verstanden haben.

Für den Pilotbetrieb sollten Sie außerdem ein fehlgeschlagenes Szenario kontrolliert testen: ein nicht vorhandenes Scheme oder ein absichtlich ungültiger Pfad muss im Jobprotokoll als Fehler erkennbar sein. So prüfen Sie, ob Ihre Pipeline echte Build-Fehler meldet und nicht lediglich einen erfolgreichen Vorbereitungsjob als Release-Freigabe interpretiert.

SECTION 06Schritt 5: Arbeitsbereich, Schlüsselbund und Zugriff prüfen

Bevor Sie den Runner für weitere Projekte öffnen, überprüfen Sie, welche Daten ein Job nach Ende im Arbeitsbereich hinterlässt. Shell-Aufträge laufen auf dem Host; betrachten Sie das Verzeichnis deshalb nicht automatisch als kurzlebige, isolierte Umgebung. Legen Sie fest, wie ausgecheckte Quellen, Build-Ausgaben, temporäre Dateien und Caches behandelt werden. Testen Sie die Bereinigung praktisch und prüfen Sie, ob ein späterer Job noch auf Dateien des vorherigen Auftrags zugreifen kann.

Signiermaterial verdient eine separate Freigabe. Ermitteln Sie, ob der Job auf den Schlüsselbund des ausführenden Benutzers zugreifen kann, welche Identitäten für den Build benötigt werden und wer diese Einträge verwalten darf. Hinterlegen Sie keine Signierdaten nur deshalb auf dem Knoten, weil der erste Testjob erfolgreich war. Trennen Sie zunächst den Nachweis „Projekt kann ohne vertrauliche Signierwerte gebaut werden“ von der späteren Prüfung des signierten Release-Prozesses.

Prüfen Sie diese Grenzen zusammen mit den GitLab-Sicherheitshinweisen zu Runnern:

• Welche Projekte und geschützten Branches dürfen den Mac-Runner anfordern?
• Wer darf Pipeline-Dateien ändern, die auf diesem Runner ausgeführt werden?
• Sind Zugangsdaten und Schlüsselbundzugriff auf die tatsächlich benötigten Aufgaben beschränkt?
• Wird der Arbeitsbereich nach Jobende bereinigt, und ist das Ergebnis überprüft?
• Können Jobs fremder Vertrauensstufen auf dieselbe Benutzerumgebung zugreifen?

Wenn Sie eine dieser Fragen nicht belegen können, halten Sie den Einsatz auf den Pilotbereich beschränkt. Ein Shell Executor ist kein Container und sollte nicht als Container-Ersatz für nicht vertrauenswürdigen Code behandelt werden. Für stärkere Isolation müssen Sie eine andere unterstützte Ausführungstopologie bewerten und anhand der GitLab-Dokumentation prüfen, ob sie Ihre macOS- und Xcode-Anforderungen erfüllt. Eine nicht geprüfte Alternative ist kein Sicherheitsnachweis.

SECTION 07Schritt 6: Abmeldung und Neustart als Freigabekriterium testen

Ein erfolgreicher Build in einer bereits angemeldeten Sitzung sagt nichts darüber aus, ob der Runner nach einer Abmeldung oder einem Systemneustart wieder Jobs annehmen kann. Prüfen Sie diese Ereignisse getrennt und protokollieren Sie, was tatsächlich passiert: Ist der Agent gestartet? Ist eine Benutzersitzung vorhanden? Wird der Runner in GitLab wieder als verfügbar angezeigt? Kann ein neuer Minimaljob zugeordnet und ausgeführt werden?

Führen Sie den Test zunächst ohne vertrauliche Signieraufgaben aus. Notieren Sie vor dem Neustart den Status, starten Sie den Knoten kontrolliert neu und prüfen Sie nach dem Wiederanlauf die Runner-Verbindung und den Job. Wiederholen Sie die Beobachtung für eine Benutzerabmeldung, weil ein LaunchAgent an die Sitzung gebunden ist. Stimmen die Ergebnisse nicht mit Ihrem Betriebsbedarf überein, ändern Sie die Start- und Wiederherstellungsplanung, anstatt den Status „online“ als dauerhafte Verfügbarkeit zu interpretieren.

Nutzen Sie die folgende Abnahmeliste. Haken Sie einen Punkt erst ab, wenn ein Protokoll, eine Konfiguration oder ein reproduzierbarer Test den Nachweis liefert:

• [ ] Der Mac-Knoten ist für die vorgesehenen Projekte bestimmt und nicht zugleich eine persönliche Arbeitsumgebung.
• [ ] Die zuständige Person und der Rückweg zum Deaktivieren des Runners sind dokumentiert.
• [ ] Der Runner wurde mit den vorgesehenen Tags registriert; der Zugriff auf Registrierungstokens ist begrenzt.
• [ ] Der Job zeigt das erwartete Benutzerkonto und den tatsächlichen Xcode-Pfad.
• [ ] Ein realer Projekt-Build mit dem vorgesehenen Scheme ist im CI-Protokoll nachvollziehbar erfolgreich.
• [ ] Repository-Zugriff, Arbeitsbereichsbereinigung, Schlüsselbund und Signierzugriff wurden separat bewertet.
• [ ] Das Verhalten nach Abmeldung und Neustart wurde praktisch überprüft.
• [ ] Die Freigabe beschränkt sich auf die Projekte und Aufgabentypen, deren Vertrauensgrenze geprüft wurde.

Entscheiden Sie danach ausdrücklich zwischen Pilotbetrieb, begrenzter Produktionsfreigabe und Neuplanung. Für den Pilotbetrieb können Sie auf ein kleines, vertrauenswürdiges Projekt begrenzen. Für eine weitergehende Freigabe müssen Sicherheitsverantwortliche die tatsächlichen Rechte, Geheimnisse und Jobquellen akzeptieren. Wenn der Runner nach Abmeldung nicht verfügbar ist und eine Sitzung aus Sicherheitsgründen nicht dauerhaft angemeldet bleiben darf, passt dieses Betriebsmodell nicht zu Ihrer Verfügbarkeitsanforderung.

Für einen wechselnden Bedarf an Mac-Kapazität kann eine gemietete Umgebung den Test eines dedizierten Knotens ermöglichen, ohne dass Sie sofort Hardware beschaffen und selbst bereitstellen müssen. Das ersetzt weder die Prüfung von Shell-Executor-Isolation noch die Abnahme Ihrer Zugangsdaten. Prüfen Sie vor einer Entscheidung die Mietmodelle und Konditionen von MACNOX und gleichen Sie sie mit Laufzeit, Zugang und Betriebsanforderungen Ihres Pilotprojekts ab.

SECTION 08Häufige Fragen zur Einrichtung

Lässt sich GitLab Runner direkt auf macOS installieren?

Ja. GitLab dokumentiert die Installation und Konfiguration des Runners unter macOS; für iOS- und macOS-Builds kommt häufig der Shell Executor zum Einsatz. Prüfen Sie vor dem Einsatz die aktuelle Installationsanleitung und den Status des Executors. Entscheidend ist außerdem, dass der Runner im vorgesehenen Benutzerkontext läuft und die benötigte macOS-Sitzung verfügbar ist.

Welcher Executor passt für Apple-Builds auf einem Mac?

Der Shell Executor ist ein dokumentierter Weg für iOS- und macOS-Aufgaben, bietet aber nur begrenzte Isolation und ist laut GitLab im Wartungsmodus. Er passt daher eher zu einem dedizierten Knoten mit vertrauenswürdigen Projekten als zu einem gemeinsam genutzten Runner für beliebige Beiträge. Prüfen Sie andere unterstützte Ausführungstopologien anhand der GitLab-Dokumentation, bevor Sie daraus eine stärkere Isolation ableiten.

Bleibt der macOS-Runner nach Abmeldung oder Neustart verfügbar?

Nicht automatisch in jeder Situation. GitLab beschreibt den macOS-Runner als benutzerbezogenen LaunchAgent, der eine angemeldete Benutzersitzung voraussetzt; er ist damit nicht mit einem LaunchDaemon gleichzusetzen. Testen Sie Abmeldung und Systemneustart getrennt. Aktivieren Sie automatische Anmeldung nicht als bequeme Standardlösung, sondern bewerten Sie deren Folgen für Zugangsschutz, Schlüsselbund und physische Sicherheit.

Wie weisen Sie nach, dass der Job das erwartete Xcode verwendet?

Lassen Sie den Job den ausgewählten Entwicklerpfad und die Xcode-Version in seinem Protokoll ausgeben und ergänzen Sie einen echten Projekt-Build mit dem vorgesehenen Scheme. Ein online angezeigter Runner belegt weder den richtigen Werkzeugpfad noch einen erfolgreichen Build. Vergleichen Sie die Jobausgabe mit der Knotenprüfung und dokumentieren Sie Abweichungen, bevor Sie weitere Projekte oder Signierschlüssel freigeben.

Ein Linux- oder Windows-Knoten kann allgemeine CI-Aufgaben übernehmen, stellt aber keine macOS-Umgebung für Xcode-Builds bereit; ein gemeinsam genutzter lokaler Mac wiederum erschwert die Trennung von persönlichen Daten, Arbeitsbereich und CI-Zugriff. Wenn Sie einen dedizierten Mac zunächst für einen begrenzten Pilotbetrieb benötigen, kann die Miete über MACNOX den Hardwarekauf und die eigene Bereitstellung vermeiden. Prüfen Sie die verfügbaren Mac-Mietoptionen von MACNOX erst dann, wenn Ihr Team Knotenvertrauen, Sitzungserfordernis und Wiederherstellung geklärt hat.

SECTION 09FAQ