CircleCI Machine Runner 3 sollten Sie auf einem Remote-Mac nur dann bereitstellen, wenn Sie eine feste Xcode-Umgebung, private Abhängigkeiten, interne Dienste oder kontrollierten Zugriff auf Signaturdaten benötigen; standardisierte Aufträge bleiben beim verwalteten Ausführer. Planen Sie die Einführung über fünf Prüfphasen: Ressourcen und Rechte, Installation, Routing, signierungsfreier Xcode-Test sowie Neustart- und Bereinigungsprüfung. Ein sichtbarer Runner ist noch kein produktionsfähiger macOS-Buildknoten.

Wer sollte diese Anleitung lesen?

Sie betreiben iOS- oder macOS-Pipelines in CircleCI und müssen die Werkzeugkette reproduzierbar halten.
Sie benötigen private Repositories, interne Netzwerkdienste oder getrennte Signaturzugänge.
Sie verwalten Remote-Macs, Ausführungskonten, Aktualisierungen und die Wiederherstellung nach Ausfällen.

Zuletzt aktualisiert am 29.08.2026; die Aussagen zu Installation, Registrierung, resource class und Ausführung wurden anhand der verlinkten CircleCI- und Apple-Dokumentation geprüft. Ändert CircleCI Paket, Konfigurationsstruktur oder macOS-Anforderungen, ist eine erneute Abnahme erforderlich.

01

Vor dem ersten Terminalbefehl die richtige Aufgabe auswählen

Ein selbstverwalteter Runner gibt Ihnen Kontrolle über den Mac. Er nimmt Ihnen aber nicht die Wartung ab. Der Auftrag läuft direkt in der vorhandenen Umgebung des Knotens; vorinstallierte Werkzeuge, Benutzerrechte, Schlüsselbunde, Netzwerkzugang und lokale Zustände beeinflussen das Ergebnis. Das beschreibt CircleCI im Überblick zum Runner-Ausführungsmodell.

Drei sinnvolle Betriebsmodelle

Betriebsmodell Passt, wenn … Hauptnachteil
Verwalteter Ausführer der Auftrag keine feste Xcode-Version, privaten Netzwerkzugang oder eigene Systempakete braucht weniger Kontrolle über die konkrete Umgebung
Remote-Mac mit Machine Runner 3 Sie Xcode, private Abhängigkeiten, lokale Werkzeuge oder Signierungszugänge kontrollieren müssen Betrieb, Updates, Bereinigung und Wiederherstellung liegen bei Ihnen
Doppelspurige Pipeline Tests und Standardprüfungen allgemein laufen, Veröffentlichung oder spezielle Xcode-Aufträge aber einen festen Mac brauchen zwei Ausführungswege müssen getrennt getestet und überwacht werden

Wählen Sie den Remote-Mac nicht allein wegen einer vermuteten Geschwindigkeitssteigerung. Der belastbare Grund ist die Umgebungskontrolle. Ein Xcode-Build kann von der aktiven Entwicklerverzeichnis-Auswahl, Command-Line-Tools, SDKs, Ruby- oder Node-Abhängigkeiten und Zugriffsrechten abhängen. Für allgemeine Linting- oder Plattform-unabhängige Tests erzeugt ein eigener Knoten dagegen unnötige Pflege.

CircleCI führt Machine Runner als Ausführungsmodell für eigene Infrastruktur. Die Dokumentation zu den Runner-Konzepten erklärt dabei die Trennung zwischen Orchestrierung und dem Rechner, der den Auftrag tatsächlich ausführt. Genau diese Trennung ist für Ihre Sicherheits- und Abnahmeplanung wichtig.

Entscheidungsbedingungen für die Migration

  • Wenn der Auftrag eine bestimmte Xcode-Umgebung oder macOS-spezifische Werkzeuge benötigt, dann wählen Sie einen eigenen Remote-Mac.
  • Wenn private Dienste nur aus einem kontrollierten Netzwerk erreichbar sind, dann ordnen Sie den Auftrag einer eigenen resource class zu.
  • Wenn Signaturmaterial benötigt wird, dann trennen Sie Build und Veröffentlichung und verwenden ein eigenes Ausführungskonto.
  • Wenn der Auftrag reproduzierbar ohne lokale Zustände läuft, dann lassen Sie ihn zunächst beim verwalteten Ausführer.
  • Wenn nur ein einzelner Release-Auftrag macOS benötigt, dann migrieren Sie nicht sofort die gesamte Pipeline.
  • Wenn nach einem Neustart keine automatische Wiederaufnahme nachweisbar ist, dann darf der Knoten nicht in die Produktionsspur.
02

Phase 1: Konto, Namespace und Ausführungskonto vorbereiten

Beginnen Sie auf dem Remote-Mac mit einer Betriebssystem- und Berechtigungsinventur. Halten Sie Hostname, macOS-Version, Architektur, Xcode-Installation, aktive Command-Line-Tools, Arbeitsverzeichnis und Netzwerkfreigaben in einer internen Betriebsnotiz fest. Diese Angaben gehören nicht als geheime Werte in das Repository.

Erstellen Sie ein eigenes, niedrig privilegiertes Konto für die Runner-Prozesse. Verwenden Sie kein persönliches Administratorkonto. Das Konto braucht Zugriff auf den vorgesehenen Quellcodebereich, Cache und Protokollpfad, aber nicht pauschal auf private Benutzerverzeichnisse, fremde Schlüsselbunde oder globale Zugangsdaten.

Trennen Sie mindestens diese Pfade logisch:

Bereich Zweck Zugriffsregel
<RUNNER_WORKDIR> temporärer Auftrag und Arbeitskopie nur das Ausführungskonto
<CACHE_DIR> kontrollierter Build-Cache regelmäßig auf Verschmutzung prüfen
<LOG_DIR> Runner- und Auftragsprotokolle Schreibzugriff für Runner, Lesezugriff für Betrieb
<SIGNING_DIR> zeitweise benötigte Signaturdateien nur signierende Aufgabe, kein allgemeiner Build
<RECOVERY_DIR> Wiederherstellungs- und Prüfscripte keine Secrets, versionierte Konfiguration

Legen Sie anschließend in CircleCI den Namespace und die resource class an. Die resource class ist kein bloßes Etikett. Sie ist das Routing-Signal, mit dem ein Auftrag den vorgesehenen Knotentyp anfordert. Die offizielle Übersicht zu resource classes beschreibt diese Zuordnung.

Benennen Sie die Werte eindeutig, zum Beispiel <NAMESPACE>, <RESOURCE_CLASS> und <RUNNER_NAME>. Der Token bleibt ein Platzhalter. Speichern Sie ihn in einem dafür vorgesehenen Secret-Mechanismus oder in einer geschützten lokalen Konfiguration. Schreiben Sie ihn niemals in eine Projektdatei, einen Commit, eine Shell-Historie oder ein Build-Protokoll.

Eingangsbedingung für Phase 2: Konto, Arbeitsverzeichnis, Namespace und resource class sind dokumentiert; der Token ist mit einem Ablauf- und Rotationsprozess hinterlegt.

Stoppen Sie hier, wenn: das Runner-Konto unnötige Administratorrechte benötigt, der Token nur im Repository abgelegt werden kann oder Signatur- und Standardaufträge denselben ungeschützten Bereich verwenden.

03

Phase 2: Machine Runner 3 auf macOS installieren und starten

Nutzen Sie für Installation und Start ausschließlich die am Einsatztag gültige CircleCI-Anleitung für Machine Runner 3 auf macOS. Installationspakete, Signaturprüfung, Pfade und Startmechanismus können sich ändern. Deshalb sollten Sie keine ältere Shell-Zeile aus einem Blogbeitrag übernehmen.

Die Installation besteht praktisch aus vier Kontrollpunkten:

  1. Laden Sie das von CircleCI vorgesehene Installationsprogramm über den offiziellen Ablauf.
  2. Prüfen Sie, ob macOS die Datei wegen Signatur-, Quarantäne- oder Berechtigungsstatus blockiert.
  3. Legen Sie die Konfiguration mit <RUNNER_NAME>, <NAMESPACE>, <RESOURCE_CLASS>, <RUNNER_WORKDIR> und dem Token an.
  4. Starten Sie den Runner unter dem vorgesehenen Ausführungskonto und bewahren Sie die lokale Startausgabe auf.

Bei macOS reicht es nicht, dass ein Programm einmal im Terminal startet. Prüfen Sie zusätzlich, ob der Prozess nach einer Abmeldung, einer nicht-interaktiven Ausführung und einem Neustart wieder gestartet wird. Behandeln Sie eine manuelle Terminal-Sitzung nur als Installations- und Diagnoseweg, nicht als Betriebsmodell.

CircleCI dokumentiert die Konfigurationsfelder für Machine Runner 3 in einer eigenen Referenz zur Runner-Konfiguration. Vergleichen Sie jeden Feldnamen und jeden Pfad direkt mit dieser Referenz. Verwenden Sie in einer Anleitung oder in internen Tickets weiterhin Platzhalter; echte Tokens und interne Hostnamen gehören nicht in geteilte Dokumentation.

Drei Nachweise für einen erfolgreichen Start

  • Der lokale Prozess läuft unter dem erwarteten Konto.
  • Der Runner erscheint in der CircleCI-Inventaransicht mit der vorgesehenen resource class.
  • Das lokale Protokoll zeigt keine wiederkehrenden Authentifizierungs-, Berechtigungs- oder Verbindungsfehler.

Die Inventaransicht allein ist kein ausreichender Beleg. Ein Runner kann registriert erscheinen und dennoch keine Aufträge korrekt ausführen. Wenn die Verbindung unklar ist, vergleichen Sie lokale Protokolle, Netzwerkzugang und Auftragsergebnis mit der offiziellen Anleitung zur Fehlersuche bei selbstverwalteten Runnern.

Stoppen Sie hier, wenn: die Registrierung nur mit einem persönlichen Token funktioniert, der Prozess als falscher Benutzer läuft oder der Start nach einer Abmeldung nicht reproduzierbar ist.

04

Phase 3: Routing und Xcode CI mit einem Wegwerfprojekt prüfen

Jetzt kommt der Test, der viele fehlerhafte Bereitstellungen entlarvt: ein minimaler Auftrag muss nachweisbar auf dem gewünschten Mac laufen. Fordern Sie in der Pipeline die zuvor erstellte resource class an. Verwenden Sie ein wegwerfbares Projekt ohne echte Zertifikate und ohne Produktionszugang.

Prüfen Sie im Auftrag:

  • den Hostnamen oder eine andere nicht geheime Knotenidentifikation,
  • den Benutzerkontext,
  • die aktive Xcode-Auswahl,
  • die Verfügbarkeit der Command-Line-Tools,
  • die Lesbarkeit der Projektabhängigkeiten,
  • den Rückgabestatus von Build und Test,
  • den Speicherort des Ergebnispakets.

Apple beschreibt sowohl die Installation der Command-Line-Tools als auch die Auswahl der aktiven Command-Line-Tools. Beides muss im Ausführungskonto funktionieren. Eine Xcode-Installation, die nur in Ihrer interaktiven Sitzung sichtbar ist, beweist keine erfolgreiche CI-Konfiguration.

Für Xcode CI sollten Sie den ersten Durchlauf in drei Ebenen zerlegen:

  1. Werkzeuge erkennen.
  2. Abhängigkeiten auflösen und kompilieren.
  3. Tests ausführen und ein Ergebnisartefakt ablegen.

So lässt sich unterscheiden, ob das Routing, die Umgebung oder das Projekt fehlschlägt. Lassen Sie den Auftrag absichtlich ohne Signierung laufen. Das reduziert die Zahl der gleichzeitig zu untersuchenden Fehlerquellen.

Typische unsichtbare Grenzen

Interaktive Anmeldung: Ein Build darf nicht davon abhängen, dass ein Entwickler zuvor eine grafische Sitzung geöffnet hat. Umgebungsvariablen, Schlüsselbundzugriff und Pfade müssen im Dienstkontext verfügbar sein.

Private Abhängigkeiten: Ein Repository kann im Entwicklerterminal erreichbar sein, aber für das Runner-Konto fehlen. Prüfen Sie DNS, Firewall, SSH-Schlüssel und Zertifikatsketten getrennt vom Build.

Lokale Zustände: Ein grüner Build kann auf einem bereits gefüllten Cache oder einer alten Derived-Data-Struktur beruhen. Führen Sie mindestens einen sauberen Durchlauf in einem neuen Arbeitsbereich aus.

Architektur: Ein Apple-Silicon-Mac kann native Werkzeuge und Abhängigkeiten anders behandeln als ein Intel-System. Prüfen Sie deshalb nicht nur, ob Xcode startet, sondern ob alle benötigten Pakete für die Zielarchitektur verfügbar sind.

Eingangsbedingung für Phase 4: Ein signierungsfreier Auftrag wird über die resource class korrekt geroutet, verwendet das richtige Konto und erzeugt ein prüfbares Ergebnis.

Stoppen Sie hier, wenn: der Auftrag auf einem anderen Ausführer landet, Xcode nur interaktiv funktioniert oder die Projektabhängigkeiten nur mit erweiterten Rechten auflösbar sind.

05

Phase 4: Signierung in eine getrennte Produktionsspur überführen

Signaturmaterial ist kein normaler Build-Bestandteil. Behandeln Sie Zertifikate, Profile, private Schlüssel, Schlüsselbundpasswörter und Kontozugänge als eigene Vertrauenszone. CircleCI weist in seinen Runner-Sicherheitsinformationen darauf hin, dass selbstverwaltete Infrastruktur vom Betreiber abgesichert werden muss. Prüfen Sie die Sicherheits-FAQ für selbstverwaltete Runner zusammen mit Ihren internen DSGVO-Vorgaben.

Trennen Sie mindestens:

  • Standard-Build und Test,
  • Archivierung ohne Veröffentlichung,
  • signierende Veröffentlichung,
  • Wartungs- und Diagnosezugriff.

Dafür eignen sich getrennte Aufträge oder getrennte resource classes. Ein allgemeiner Buildknoten sollte keine dauerhafte Leseberechtigung auf den produktiven Schlüsselbund erhalten. Geben Sie Signaturdateien möglichst nur für die signierende Aufgabe frei und entfernen Sie temporäre Kopien danach.

Ein robustes Berechtigungsmodell

Das Runner-Konto erhält nur Zugriff auf <RUNNER_WORKDIR>, <CACHE_DIR> und <LOG_DIR>. Ein separates Veröffentlichungsprofil greift auf <SIGNING_DIR> zu. Der Zugriff wird nicht über einen globalen Administratorstatus gelöst, sondern über explizite Dateirechte, Schlüsselbundrichtlinien und den jeweiligen Auftrag.

Verwenden Sie in der Pipeline keine echten Namen für Zertifikate, Konten, Tokens oder Passwörter. Maskierte Variablen schützen nicht automatisch vor Fehlkonfigurationen, Shell-Ausgaben oder Artefakten. Prüfen Sie deshalb Protokolle und Ergebnisdateien nach einem Testlauf manuell.

Entscheiden Sie außerdem, ob Abhängigkeiten vorinstalliert oder im Auftrag installiert werden. Vorinstallation verbessert oft die Vorhersagbarkeit, erhöht aber den Pflegeaufwand und kann veraltete Pakete konservieren. Installation im Auftrag erleichtert die Nachvollziehbarkeit, benötigt jedoch Netzwerkzugang und verlängert den Lauf. Die richtige Wahl hängt von Ihrer Reproduzierbarkeit, Cache-Strategie und Wartungsfrequenz ab.

Stoppen Sie hier, wenn: ein Standard-Build das Signaturverzeichnis lesen kann, Secrets in Protokollen auftauchen oder niemand den Wiederherstellungsweg für einen kompromittierten Token kennt.

06

Phase 5: Neustart, Bereinigung und Dauerbetrieb abnehmen

Planen Sie eine kontrollierte Unterbrechung, bevor der Mac produktive Veröffentlichungen ausführt. Starten Sie den Knoten nach einer dokumentierten Wartungsankündigung neu. Prüfen Sie danach in dieser Reihenfolge:

  1. Das Runner-Startverhalten nach dem Neustart.
  2. Prozess, Ausführungskonto und Arbeitsverzeichnis.
  3. Runner-Inventar und resource class.
  4. Annahme eines kleinen Testauftrags.
  5. Zugriff auf Xcode und Command-Line-Tools.
  6. Abschluss, Protokoll und Ergebnisartefakt.
  7. Bereinigung des Arbeitsbereichs.

Der Zweck dieser Reihenfolge ist die Beweiskette. Ein „online“ angezeigter Knoten kann trotzdem an einem falschen Pfad, einem nicht geladenen Schlüsselbund oder einem beschädigten Arbeitsbereich scheitern.

Testen Sie anschließend einen absichtlich fehlschlagenden Auftrag. Prüfen Sie, ob Quellcode, temporäre Archive, Zugangsdaten und generierte Dateien nach dem Fehlschlag entfernt oder sicher verworfen werden. Achten Sie auch auf Cache-Verschmutzung: Ein Cache darf keine Signaturmaterialien oder projektspezifische Geheimnisse enthalten.

Kontrollieren Sie Warteschlangen und Parallelität. Ein einzelner Remote-Mac ist nicht automatisch für mehrere gleichzeitige Xcode-Aufträge geeignet. Legen Sie eine klare Regel fest: entweder serielle Ausführung oder zusätzliche Knoten mit getrennten resource classes. Eine lange Warteschlange ist ein Kapazitätsproblem, kein Fehler des Routing-Labels.

Für Verbindungsprobleme bietet CircleCI zusätzlich eine spezielle Anleitung zur Prüfung selbstverwalteter Runner-Verbindungen. Dokumentieren Sie vor jeder Token-Widerrufung, Dienst-Neuinstallation oder destruktiven Arbeitsbereichbereinigung den Einflussbereich und einen Rückweg. Widerrufen Sie einen produktiven Token nicht während eines laufenden Veröffentlichungsfensters, wenn kein Ersatzknoten bereitsteht.

Produktionsfreigabe erst nach vier Nachweisen

  • Routing: Der Auftrag landet zuverlässig auf der vorgesehenen resource class.
  • Xcode: Build und Test laufen ohne interaktive Anmeldung.
  • Wiederherstellung: Nach einem geplanten Neustart wird ein neuer Auftrag angenommen.
  • Sauberkeit: Erfolgreiche und fehlgeschlagene Aufträge hinterlassen keine unzulässigen Geheimnisse oder veralteten Arbeitsdateien.

Erst wenn alle vier Nachweise dokumentiert sind, sollte der Knoten produktive signierende Aufgaben übernehmen. Fehlt ein Nachweis, bleibt der Runner in einer Testspur. Das ist langsamer als eine vorschnelle Freigabe, verhindert aber schwer reproduzierbare Veröffentlichungsfehler.

07

Remote-Mac oder eigener Mac mini: die Betriebsentscheidung

Ein eigener Mac mini kann für eine dauerhaft hohe, gleichmäßige Auslastung sinnvoll sein. Sie tragen dann jedoch Anschaffung, Stromversorgung, Internetanbindung, Ersatzgerät, lokale Wartung und physische Wiederherstellung. Bei einem Remote-Mac erhalten Sie dagegen eine ausgelagerte Hardwarebasis, müssen aber Netzwerkzugriff, Konten, Runner-Konfiguration und Pipeline-Sicherheit weiterhin selbst verantworten.

Wenn Sie verschiedene Standorte oder Projektlaufzeiten vergleichen, können Sie die verfügbaren Mac-mini-Mietpreise als Ausgangspunkt für Ihre Kalkulation prüfen. Entscheidend ist nicht nur die Monatsgebühr, sondern auch die Zeit für Wartung, Ausfallbehebung, Neuinstallation und Sicherheitsprüfungen.

Für eine zeitlich begrenzte Migration ist ein gemieteter Remote-Mac besonders dann sinnvoll, wenn Sie zuerst einen signierungsfreien Xcode-Auftrag, einen Neustart und eine Bereinigung prüfen möchten. Für eine langfristig stark ausgelastete, vollständig kontrollierte Plattform kann ein selbst betriebener Mac wirtschaftlich und organisatorisch besser passen. Benötigen Sie dagegen physische USB-Geräte, lokale Testhardware oder direkten Zugriff auf Peripherie, ist ein entfernter Knoten möglicherweise die falsche Wahl.

Wenn Ihr vorhandener Linux- oder Windows-Server die übrigen Pipeline-Schritte bereits zuverlässig übernimmt, sollten Sie nicht alles umziehen. Übertragen Sie nur die macOS-spezifische Spur. Ein Remote-Mac für Entwicklungsaufgaben kann dabei als isolierter Prüf- und Buildknoten dienen, ohne Ihre bestehende Standardpipeline unnötig zu ersetzen.

Ein selbstverwalteter Runner ist daher keine pauschale Alternative zum verwalteten Ausführer. Er ist eine gezielte Infrastrukturentscheidung für Xcode, private Netze, feste Werkzeuge und sensible Signierung. Wenn Ihr aktueller Ansatz diese Aufgaben auf einem gemeinsam genutzten Entwickler-Mac erledigt, entstehen typischerweise drei Nachteile: Builds hängen von interaktiven Sitzungen ab, lokale Zustände verfälschen Ergebnisse und Signaturzugänge liegen zu nahe an allgemeinen Entwicklungsrechten. Für eine zeitlich begrenzte oder isolierte Einführung kann die Miete eines Remote-Macs über VpsMesh diese Hardware- und Wiederherstellungsarbeit auslagern. Starten Sie trotzdem mit einem unsignierten Test, einem Neustart und einer Arbeitsbereichbereinigung, bevor Sie Veröffentlichungen freigeben.

08

Häufige Fragen zur Bereitstellung

Die folgenden Antworten fassen die wichtigsten Betriebsgrenzen zusammen, ohne echte Tokens, Konten, Pfade oder Zertifikatsnamen zu verwenden.

Funktioniert Machine Runner 3 auf Apple Silicon?

CircleCI bestätigt die Installation von Machine Runner 3 auf macOS über eine eigene Installationsanleitung. Für Apple-Silicon-Geräte müssen Sie zusätzlich die konkrete macOS-Version, die installierten Xcode-Werkzeuge und die Architektur Ihrer Abhängigkeiten prüfen. Der Runner stellt keine identische Umgebung her; der Auftrag verwendet den Zustand des registrierten Remote-Macs.

Wie wird die resource class mit dem Knoten verbunden?

Sie erstellen zunächst einen Namespace und eine resource class im CircleCI-Konto. Bei der Registrierung verknüpfen Sie den Knoten über die dafür vorgesehene Konfiguration und den geschützten Token. Danach fordert der Auftrag die resource class an. Der Nachweis ist erst erbracht, wenn ein Testauftrag auf dem erwarteten Knoten läuft und dessen lokale Protokolle dazu passen.

Was muss nach einem Mac-Neustart geprüft werden?

Prüfen Sie zuerst den Prozess und das Ausführungskonto, danach Inventarstatus und lokale Protokolle. Starten Sie anschließend einen kleinen Auftrag, der Xcode und die Command-Line-Tools aufruft. Testen Sie außerdem einen fehlerhaften Auftrag, damit Arbeitsbereichbereinigung und Cache-Verhalten sichtbar werden. Ein grüner Inventarstatus ohne erfolgreich angenommenen Auftrag reicht nicht für die Produktionsfreigabe.

Wie verhindert man zu weitreichenden Zugriff auf Signaturdaten?

Standard-Builds und signierende Veröffentlichungen sollten getrennt werden. Verwenden Sie ein eigenes Ausführungskonto oder mindestens eine eigene resource class mit einem begrenzten Schlüsselbundzugriff. Temporäre Zertifikats- und Profildateien müssen nach dem Auftrag entfernt werden. Prüfen Sie Protokolle und Artefakte auf Geheimnisse und planen Sie Rotation sowie Widerruf des Tokens als festen Betriebsprozess ein.

Wann bleibt der verwaltete Ausführer die bessere Wahl?

Wenn ein Auftrag keine feste Xcode-Umgebung, keinen privaten Netzwerkzugang und keine lokalen Werkzeuge benötigt, ist ein eigener Knoten meist zusätzliche Arbeit. Bleiben Sie beim verwalteten Ausführer, solange die Standardumgebung ausreicht. Migrieren Sie nur den macOS-spezifischen Teil, wenn Xcode, Signierung oder interne Dienste eine kontrollierte Umgebung tatsächlich erforderlich machen.