GitLab Runner unter macOS selbst hosten: Anleitung 2026
Ein CI-Auftrag landet auf einem Linux-Knoten, obwohl für den iOS-Build Xcode benötigt wird.
Schnellste Lösung: GitLab Runner lässt sich auf einem Remote Mac betreiben; für iOS- und macOS-Builds ist der shell-Executor die naheliegende Wahl. Der Dienst muss laut GitLab als benutzerbezogener LaunchAgent laufen, nicht als systemweiter LaunchDaemon. Da der shell-Executor Aufträge lokal auf dem Host ausführt und nur begrenzt voneinander isoliert, sollte der Knoten ausschließlich vertrauenswürdige Projekte annehmen.
Dieser Leitfaden ist für iOS- und macOS-Entwickler gedacht, die GitLab CI/CD um einen Apple-Buildknoten ergänzen möchten.
Auch DevOps-Verantwortliche, die einen macOS-Knoten aus einer Windows- oder Linux-Umgebung verwalten, finden hier die relevanten Prüfungen.
Teams, die einen Remote Mac für kontinuierliche Integrationsaufgaben erwägen, können damit vorab Eignung und Betriebsrisiken abgleichen.
Kann GitLab Runner auf macOS laufen?
Ja. Installieren Sie GitLab Runner auf dem macOS-Rechner, der die CI-Aufträge tatsächlich ausführen soll, und bereiten Sie dort auch Xcode sowie die jeweiligen Projektabhängigkeiten vor. Das bedeutet nicht, dass GitLab selbst auf diesem Mac betrieben werden muss: GitLab verwaltet Projekte und Aufträge, während der Runner die ausgewählten Jobs auf seinem eigenen Ausführungsknoten abarbeitet. Die GitLab-Dokumentation zur macOS-Installation beschreibt die Installation und den Dienstbetrieb auf macOS.
Diese Trennung ist für die Planung wichtig. Ein vorhandener GitLab-Server macht noch keinen macOS-Buildknoten verfügbar, und ein registrierter Runner enthält weder automatisch Xcode noch projektspezifische Zertifikate, Profile oder Abhängigkeiten. Der Runner ist die ausführende Komponente; die macOS-Umgebung muss auf dem Host vorhanden und betriebsbereit sein.
Vor der Einrichtung sollte das Team daher drei Fragen beantworten: Ist der vorgesehene Mac für das Projekt erreichbar? Darf er die benötigten Quelltexte und Build-Geheimnisse erhalten? Und kann das Team den Knoten warten, wenn Anmeldung, Werkzeugkette oder Netzwerkzugang ausfallen? Eine positive Antwort auf die erste Frage allein reicht nicht für eine belastbare Pipeline.
Die Dienstsitzung als Betriebsindikator festlegen
Bei macOS zählt nicht nur, ob ein Prozess gestartet wurde, sondern auch, unter welcher Benutzer- und Sitzungskonstellation er läuft. GitLab dokumentiert für macOS den Betrieb als benutzerbezogenen LaunchAgent und weist darauf hin, dass ein systemweiter LaunchDaemon für diesen Zweck nicht unterstützt wird. Die Unterschiede zwischen benutzerbezogenen Agenten und systemweiten Daemons erläutert auch Apples Dokumentation zu launchd-Aufträgen.
Warum ist ein LaunchDaemon für GitLab Runner unter macOS ungeeignet?
Ein LaunchAgent ist an den Benutzerkontext gebunden; ein LaunchDaemon läuft als systemweiter Dienst. Deshalb sollte ein Runner nicht durch eine eigene Systemdienst-Konfiguration in einen anderen Betriebsmodus gezwungen werden. Maßgeblich ist der von GitLab dokumentierte Dienstweg für macOS, nicht die Annahme, dass jeder Unix-Dienst sinnvoll als Systemprozess ausgeführt werden kann. Details zum Dienstbetrieb nennt die GitLab-Anleitung für Runner auf macOS.
Prüfen Sie, welcher Benutzer den Runner installiert und ausführt, ob dieser Benutzer Zugang zur benötigten Sitzung hat und unter welchem Konto Projektdateien angelegt werden. Bei Simulatoraufgaben, interaktiven Werkzeugen oder Zugriffen auf benutzerbezogene Schlüsselbunddaten kann die Sitzung entscheidend sein. Solche Funktionen sollten mit einem repräsentativen Auftrag geprüft werden, statt aus einem erfolgreichen Start des Runner-Prozesses abgeleitet zu werden.
Für den Wiederanlauf nach einem Neustart ist die Benutzeranmeldung ein eigener Betriebsfaktor. GitLabs macOS-Dokumentation führt die Voraussetzungen für den Betrieb nach einem Neustart auf. Wenn dafür eine automatische Anmeldung in Betracht gezogen wird, muss das Team den Verfügbarkeitsgewinn gegen das zusätzliche Risiko abwägen: Ein dauerhaft angemeldetes Benutzerkonto kann bei physischem oder administrativem Zugriff zusätzliche Folgen haben. Die Entscheidung gehört in das Sicherheits- und Betriebsmodell und sollte nicht stillschweigend Teil der Installationsroutine werden.
Achtung: Ein Runner, der nach einem manuellen Login funktioniert, ist noch nicht automatisch ein belastbarer CI-Knoten. Prüfen Sie getrennt, ob er nach Abmeldung, Neustart und Wartungsarbeiten wieder erreichbar ist und ob die dafür nötige Anmeldestrategie mit den Sicherheitsvorgaben vereinbar bleibt.
Für sensible Schlüsselbunddaten und personenbezogene Projektinformationen sollten Zugriff und Aufbewahrung ebenfalls festgelegt sein. Das betrifft nicht allein den Runner: Auch Protokolle, zwischengespeicherte Dateien und erzeugte Artefakte können interne Daten enthalten. Die internen Vorgaben zur DSGVO und zum Datenschutz sollten deshalb den Zugriff auf den Host und die Weitergabe von Job-Ausgaben abdecken. Als Ausgangspunkt für die Prüfung der eigenen Anbieterbedingungen dient die Datenschutzerklärung von KuzCloud; sie ersetzt nicht die Datenschutzprüfung des jeweiligen Projekts.
Welcher Executor eignet sich für macOS-Builds?
Für iOS- und macOS-Builds empfiehlt GitLab den shell-Executor. Er führt Skripte in der lokalen Shell-Umgebung des Runner-Hosts aus; dadurch kann ein Auftrag auf dort installierte Apple-Werkzeuge zugreifen. Das ist jedoch kein Containerbetrieb: Abhängigkeiten, Berechtigungen und potenziell erreichbare Dateien des Hosts müssen bewusst verwaltet werden. GitLabs Dokumentation zum Shell-Executor beschreibt die Ausführungsweise und ihre Einschränkungen.
Die Executor-Wahl ist somit eine Abwägung zwischen Zugang zur nativen macOS-Umgebung und Isolation. Für Xcode-Aufträge ist der direkte Hostzugriff oft genau der Grund für diese Wahl. Wenn hingegen nicht vertrauenswürdige Beiträge oder Projekte denselben Knoten verwenden könnten, ist dieser Vorteil zugleich ein Risiko. Der Shell-Executor darf nicht als Sicherheitsgrenze verstanden werden, die einen Job zuverlässig von anderen Jobs abschirmt.
Prüfen Sie vor der Freigabe, welche Projekte den Runner verwenden dürfen, wer deren Pipeline-Konfiguration ändern kann und welche Geheimnisse dem Runner-Konto zugänglich sind. GitLab beschreibt die Risiken und Empfehlungen für selbst verwaltete Runner. Die Einstellungen zum Geltungsbereich von Runnern helfen dabei, die Zuordnung nach Projekt, Gruppe oder Instanz zu planen. Ein eng begrenzter Runner ist meist besser kontrollierbar als ein macOS-Knoten, der ohne Einschränkung Aufträge aus beliebigen Projekten übernimmt.
Falls die erforderliche Trennung mit dem Shell-Executor nicht erreicht werden kann, sollte das Team zunächst eine andere Ausführungsarchitektur bewerten. Es hilft nicht, den Shell-Executor lediglich anders zu benennen oder zusätzliche Skriptprüfungen vorzuschalten, wenn Jobs weiterhin mit ähnlichen lokalen Berechtigungen auf denselben Host zugreifen.
Den Runner nach messbaren Kriterien abnehmen
Die folgenden Prüfungen sind keine bloße Installationsreihenfolge. Sie bilden Abnahmekriterien: Ein Knoten sollte erst für reguläre Aufträge freigegeben werden, wenn Ausführungsumgebung, Sitzungsmodell, Werkzeugkette, Sicherheitsgrenzen und Routing zusammenpassen.
Ausführungsumgebung: Host und Projektabhängigkeiten nachweisen
Der Runner muss auf dem Mac installiert sein, auf dem die Jobs laufen sollen. Dokumentieren Sie, welche Werkzeuge und Projektabhängigkeiten auf diesem Host erwartet werden, und halten Sie diese Liste mit der Repository-Konfiguration in Einklang. Ein erfolgreicher Runner-Start beweist nicht, dass eine bestimmte Build-Abhängigkeit vorhanden oder die zugehörige Version für das Projekt geeignet ist.
Führen Sie danach einen minimalen CI-Auftrag aus, der ausschließlich die erwartete Plattform und grundlegende Umgebungsinformationen protokolliert. Der Zweck ist nicht, einen vollständigen Produktbuild zu simulieren, sondern nachzuweisen, dass der Job auf dem vorgesehenen macOS-Host und mit dem erwarteten Executor ausgeführt wird. Vermeiden Sie dabei die Ausgabe von Zugangsdaten, privaten Schlüsselpfaden oder anderen sensiblen Umgebungswerten.
Werkzeugkette: Xcode aus dem CI-Kontext erkennen
Ein Xcode-Build ist erst aussagekräftig, wenn der CI-Auftrag genau die Werkzeugkette verwendet, die das Team für das Projekt vorgesehen hat. Prüfen Sie den Installationszustand, das aktive Entwicklerverzeichnis und die erforderlichen Zusatzkomponenten. Apple dokumentiert sowohl die Installation der Xcode-Kommandozeilenwerkzeuge als auch das Herunterladen und Installieren zusätzlicher Xcode-Komponenten.
Zur Diagnose können CI-Aufträge beispielsweise xcode-select -p und xcodebuild -version ausgeben. Diese Angaben gehören in die Job-Protokolle, damit sich ein Fehler mit der tatsächlich verwendeten Umgebung abgleichen lässt. Die Befehle sind allerdings nur Diagnosepunkte: Eine passende Ausgabe belegt für sich genommen weder die Simulatorfähigkeit noch eine erfolgreiche Signierung oder die Korrektheit des App-Ergebnisses.
Verwenden Sie deshalb neben der Werkzeugkettenprüfung einen repräsentativen Build des eigenen Projekts. Der Auftrag sollte mindestens die im Repository vorgesehene Build-Aufgabe ausführen und einen nachvollziehbaren Erfolg oder Fehler liefern. Wenn Simulatorläufe, Archivierung oder Signierung benötigt werden, testen Sie diese Fähigkeiten jeweils gezielt. Ein erfolgreicher Kompilierungsschritt ist kein Beleg dafür, dass auch alle nachgelagerten Apple-Plattformaufgaben funktionieren.
Routing und Rückverfolgbarkeit: den richtigen Knoten belegen
Registrieren Sie den Runner nach der offiziellen GitLab-Anleitung zum Registrieren eines Runners und verwenden Sie ein eigenes, aussagekräftiges Tag für die macOS-Aufgaben. In der Pipeline sollte dieses Tag ausdrücklich angefordert werden. So lässt sich vermeiden, dass ein Auftrag versehentlich auf einem andersartigen Runner landet oder dort beginnt, wo Xcode und die benötigten Projektabhängigkeiten fehlen.
Legen Sie vor der Registrierung fest, welche Projekte den Knoten anfordern dürfen und wer dessen Konfiguration ändern kann. Bewahren Sie Registrierungstoken nicht in einer Repository-Datei oder in frei zugänglichen Job-Ausgaben auf. Die konkreten Zugangsdaten sollten über die dafür vorgesehene GitLab-Konfiguration verwaltet und nach dem Berechtigungsmodell des Teams geschützt werden.
Die Abnahme sollte im Job-Protokoll mindestens erkennen lassen, welcher Runner den Auftrag ausgeführt hat, welche Plattformumgebung vorlag und ob die erwarteten Artefakte erzeugt wurden. Bei einem Fehler muss die Diagnose von der Pipeline-Konfiguration bis zum lokalen Build nachvollziehbar bleiben. Eine grüne Pipeline ohne Zuordnung zu Host, Werkzeugkette und Artefakt ist für den Betrieb nur begrenzt nützlich.
Abnahme-Checkliste: Freigabe an Bedingungen knüpfen
- [ ] GitLab Runner ist auf dem macOS-Rechner installiert, der die CI-Aufträge ausführen soll.
- [ ] Der Runner wird nach der dokumentierten macOS-Methode als benutzerbezogener
LaunchAgentbetrieben, nicht alsLaunchDaemon. - [ ] Das Team hat festgelegt, wie Benutzeranmeldung, Neustart und gegebenenfalls automatische Anmeldung gehandhabt werden.
- [ ] Ein minimaler Auftrag bestätigt Host, Plattform, Runner-Zuordnung und Executor.
- [ ] Der CI-Kontext erkennt die erwartete Xcode-Installation und das aktive Entwicklerverzeichnis.
- [ ] Ein repräsentativer Projektbuild wurde tatsächlich auf diesem Runner ausgeführt.
- [ ] Simulator-, Signierungs- und Archivierungsanforderungen wurden separat geprüft, sofern das Projekt sie benötigt.
- [ ] Nur freigegebene, vertrauenswürdige Projekte können den Runner anfordern.
- [ ] Das Runner-Konto erhält nur die für die Jobs erforderlichen Berechtigungen; verfügbare Geheimnisse sind entsprechend begrenzt.
- [ ] Protokolle, Fehler und Build-Artefakte lassen sich dem Auftrag zuordnen, ohne vertrauliche Werte offenzulegen.
- [ ] Das Verhalten nach Abmeldung, Neustart und Wartung entspricht der festgelegten Betriebserwartung.
Verfügbarkeit: Neustart, Abmeldung und Wartung bewerten
Ein einzelner erfolgreicher Build sagt wenig darüber aus, ob ein Knoten für eine dauerhafte Pipeline geeignet ist. Prüfen Sie, wie sich Runner-Prozess und Jobannahme nach Abmeldung und Neustart verhalten. Halten Sie fest, wo Dienststatus und Diagnoseinformationen ermittelt werden und wer bei einem Ausfall Zugriff auf Host, GitLab-Konfiguration und Werkzeugkette hat. Für die konkreten macOS-Dienstbedingungen ist die GitLab-Anleitung zum Betrieb auf macOS die maßgebliche Referenz.
Wartung betrifft auch die Reproduzierbarkeit. Wenn Xcode oder Projektabhängigkeiten aktualisiert werden, sollte das Team festlegen, wie die Änderung geprüft und bei einem fehlgeschlagenen Build zurückgenommen wird. Der Runner darf nicht unbemerkt eine andere aktive Werkzeugkette verwenden als die, mit der die Pipeline zuvor freigegeben wurde. Dokumentieren Sie daher den bekannten Zustand und nehmen Sie nach Änderungen einen erneuten repräsentativen Auftrag ab.
Ordnen Sie den Knoten erst nach diesen Prüfungen einer Einsatzklasse zu: persönlicher Test, kontrollierte Team-Pipeline oder kritische CI/CD-Aufgabe. Für den letzten Fall gehören Wartungsfenster, Wiederanlauf, Zuständigkeit und ein Ausweichverfahren zur Betriebsplanung. Fehlen diese Punkte, ist ein erfolgreicher Testbuild ein guter Anfang, aber noch kein Nachweis für eine belastbare Produktionspipeline.
| Option | Geeignet, wenn | Entscheidender Prüfpunkt | Hauptrisiko |
|---|---|---|---|
| Lokaler Mac | Das Team besitzt und betreibt bereits geeignete macOS-Hardware | Dauerbetrieb, Benutzeranmeldung und lokale Wartung sind abgedeckt | Hardware und Wartung bleiben an den eigenen Standort gebunden |
| Remote Mac mit GitLab Runner | Ein externer macOS-Ausführungsknoten gebraucht wird und Zugriffsweg sowie Mietdauer zum CI-Bedarf passen | Vorab die tatsächlichen Zugangsbedingungen, den Dienstbetrieb und den Werkzeugkettenzustand prüfen | Netzabhängigkeit, Anmelde- und Berechtigungskonzept sowie begrenzte Isolation des Shell-Executors |
| Windows- oder Linux-Runner allein | Die Pipeline keine macOS-spezifischen Build- oder Testschritte benötigt | Nachweisen, dass kein Schritt Xcode oder eine Apple-Plattformumgebung voraussetzt | macOS-Aufgaben lassen sich dort nicht durch bloße Runner-Tags ersetzen |
Wenn der vorhandene Windows- oder Linux-Knoten die Apple-Werkzeugkette nicht ausführen kann, bleiben für macOS-Aufgaben zusätzliche Betriebs- und Infrastrukturkosten: ein eigener Mac bindet Kapital und Wartungsaufwand, während ein alleiniger Linux-Aufbau die benötigten Apple-Werkzeuge nicht bereitstellt. Ein Remote Mac kann dann eine flexiblere Alternative sein, sofern Sitzung, Sicherheitsgrenzen und Wiederanlauf zur Pipeline passen; er ist jedoch nicht automatisch die richtige Wahl für dauerhaft hohe Last oder Anforderungen an physische Schnittstellen. Vor einer Entscheidung sollte das Team bei KuzCloud die verfügbaren Zugangswege und Mietbedingungen prüfen und sie mit den eigenen Abnahmekriterien abgleichen. Informationen zu Zugang und Nutzung sind über die KuzCloud-Konsole erreichbar.
Betreiben Sie Ihren macOS-Runner auf dedizierter Hardware
Mit KuzCloud erhalten Sie einen dedizierten Mac mini M4 für GitLab-CI/CD-Aufgaben ohne Virtualisierungsschicht.
Installieren Sie mit vollem Root-Zugang Ihre benötigte Werkzeugkette, darunter Xcode, Fastlane und weitere Build-Tools.