CircleCI Machine Runner 3 Migration: Abnahme-Checkliste für macOS 2026

Diese Checkliste richtet sich an Plattform- und IT-Verantwortliche, die CircleCI-macOS-Knoten betreiben und alte Launch-Agents ablösen müssen.

Sie ist besonders relevant, wenn private Netzwerke, Apple-Signaturen, interne Artefakte oder eine verbindliche iOS-CI/CD-Lieferkette betroffen sind. Auch technische Direktoren, die zwischen vorhandenen Macs, zusätzlichen isolierten Knoten und elastisch gemieteten Mac-Ressourcen entscheiden, erhalten dafür ein belastbares Auswahlmodell.

Die fachliche Grundlage bilden die offizielle macOS-Migrationsanleitung von CircleCI, die aktuelle Installationsanleitung für Machine Runner 3 und der offizielle CircleCI-Changelog. Letzte Aktualisierung: 21.08.2026; die Angaben wurden gegen diese offiziellen Dokumentationsbereiche und die im Auftrag genannten Abnahmegrenzen geprüft.

Eine Konfigurationsdatei kann syntaktisch akzeptiert werden, während sich Dienststart, Benutzerrechte oder Arbeitsverzeichnis anders verhalten. Genau deshalb ist „Runner online“ nur ein Verbindungsnachweis, keine Produktionsabnahme.

Die riskantesten Fehler liegen in fünf voneinander unabhängigen Bereichen:

• Dienstreste: Ein alter Launch-Agent, ein verbliebener Prozess oder ein zweiter Installationspfad kann gleichzeitig mit dem neuen Dienst arbeiten.
• Konfigurationssemantik: Ein Pfad kann existieren, aber dem falschen Benutzer gehören; eine Umgebungsvariable kann im interaktiven Terminal vorhanden sein, beim Dienststart jedoch fehlen.
• Auftragsrouting: Namespace, Resource Class, Projektberechtigung oder Token können Jobs an einen anderen Knoten senden als vorgesehen.
• Geheimnisreste: Arbeitsverzeichnisse, Caches, SSH-Schlüssel, temporäre Keychains, Provisioning Profile und Build-Artefakte können über den eigentlichen Job hinaus lesbar bleiben.
• Wiederanlauf: Nach einem Neustart oder einer kurzen Netzwerkunterbrechung kann der Prozess laufen, ohne neue Aufträge sicher anzunehmen.

Vor dem ersten Eingriff sollte die verantwortliche Person eine minimale Bestandsaufnahme dokumentieren:

Ein Rollback darf nicht erst während eines fehlgeschlagenen Builds entworfen werden. Es muss vor dem Pilot schriftlich festlegen, ob der alte Dienst wiederhergestellt, ein bereits vorbereiteter Ersatzknoten aktiviert oder der betroffene Resource Class vorübergehend gesperrt wird.

Die Migration beginnt mit der Kontrolle des alten Dienstes, nicht mit dem Start des neuen Runners. Die offizielle Anleitung ist dabei maßgeblich für die jeweils aktuelle macOS-Installations- und Serviceprozedur; lokale Abweichungen gehören in das Änderungsprotokoll.

1. Dienst, Prozess und Installationspfad aufnehmen

Zuerst werden die aktive Launch-Agent- oder LaunchDaemon-Definition, der laufende Runner-Prozess, der ausführende Benutzer und alle bekannten Installationsverzeichnisse festgehalten. Ein bloßes Löschen der Konfigurationsdatei genügt nicht, wenn macOS den Prozess weiterhin verwaltet.

Der alte Dienst wird nach der offiziellen Migrationssequenz gestoppt und entfernt. Anschließend wird geprüft, dass kein alter Prozess mehr läuft und keine zweite Startdefinition denselben Knoten erneut registriert. Das Ergebnis muss als Terminalausgabe oder Systemprotokoll abgelegt werden.

2. Installationsartefakte und Herkunft verifizieren

Wird Machine Runner 3 über Homebrew oder ein anderes vorgesehenes Installationsverfahren bezogen, müssen Binärdatei, Paketquelle, Prüfsumme beziehungsweise Signaturstatus und Installationsprotokoll zusammen dokumentiert werden. Die offizielle Konfigurationsreferenz für Machine Runner 3 beschreibt die relevanten Konfigurationsfelder, ersetzt aber nicht die lokale Herkunftskontrolle.

Auf macOS sollte die Abnahme außerdem den Signatur- und Notarisierungsstatus des installierten Programms erfassen. Ein erfolgreich gestarteter Prozess ist kein ausreichender Nachweis, dass das erwartete Artefakt installiert wurde. Bei Abweichungen wird der Pilot angehalten, statt den Produktionsknoten mit einer zweiten Installationsmethode zu reparieren.

3. Den neuen Dienst mit minimalem Eingriff starten

Die produktive Konfiguration wird nicht unkontrolliert überschrieben. Für den Pilot werden ein eigener Installationspfad, ein eigener Dienstbenutzer oder zumindest klar dokumentierte Berechtigungen und eine getrennte Resource Class verwendet. Die konkreten Installationsbefehle müssen aus der aktuellen macOS-Installationsanleitung übernommen werden, weil sich Startweise und unterstützte Bedingungen ändern können.

Nach dem Start sind Prozessstatus, Dienstprotokoll, Konfigurationspfad und CircleCI-Status gemeinsam zu prüfen. Erst wenn diese vier Nachweise zusammenpassen, wird eine ungefährliche Baseline-Aufgabe zugelassen.

Die vorhandene config.yaml kann als Ausgangspunkt dienen, darf aber nicht als Beweis vollständiger Kompatibilität gelten. Jede Annahme über Pfade, Nutzer, Caches oder Zeitlimits muss durch einen Job beobachtbar werden.

Zu prüfen sind insbesondere:

• working_directory zeigt auf ein Verzeichnis, das der Runner-Benutzer tatsächlich erstellen, lesen und löschen darf.
• cleanup_working_directory entspricht der gewünschten Sicherheits- und Debugging-Strategie.
• Der Runner-Modus und die Resource Class passen zur Organisation und zum Projekt.
• command_prefix verändert keine Shell-Aufrufe, Pfade oder Exit-Codes.
• Die zulässige maximale Laufzeit wird nicht mit der Erwartung verwechselt, dass ein hängender Prozess automatisch sicher beendet wird.
• Task-Agent-Caches enthalten keine projektübergreifend lesbaren Geheimnisse.
• Umgebungsvariablen werden im Dienstkontext genauso gesetzt wie im vorgesehenen Job.

Die Baseline-Pipeline darf keine Produktionszertifikate und keine echten Tokens verwenden. Sie muss mindestens Checkout, einen kontrollierten Buildschritt, Logausgabe, einen absichtlich überprüften Exit-Code und die Rückgabe eines Testartefakts ausführen. Ein grüner Job ohne Prüfung des Exit-Codes oder der Artefaktintegrität ist keine Abnahme.

Ein selbst gehosteter Runner ist nicht automatisch für jedes Repository geeignet. Die Migration muss deshalb die Frage beantworten, welche Projekte diesen konkreten macOS-Knoten aufrufen dürfen und welche ausdrücklich abgewiesen werden.

Für den Pilot werden zunächst nur freigegebene Projekte auf die neue Resource Class geroutet. Ein vertrauenswürdiger Release-Workflow mit Signaturmaterial gehört in eine andere Vertrauensgrenze als ein allgemeines Testprojekt. Die CircleCI-Dokumentation zu Konfigurationsrichtlinien für selbst gehostete Runner ist heranzuziehen, um organisationsweite Einschränkungen und zulässige Projektzuordnungen zu prüfen.

Die Abnahme muss beide Richtungen enthalten:

• Ein erlaubtes Projekt wird angenommen und erhält den erwarteten Knoten.
• Ein nicht erlaubtes Projekt wird abgewiesen oder auf einen vorgesehenen Ersatz geroutet.
• Namespace und Resource Class stimmen in Pipeline-Konfiguration und Runner-Registrierung überein.
• Das Authentifizierungstoken steht weder im Repository noch in einem gemeinsam genutzten Skript.
• Logs, Artefakte und Fehlermeldungen geben das Token nicht aus.
• Tokenrotation und Widerruf sind einer verantwortlichen Rolle zugeordnet.

Ein häufiger Fehler besteht darin, nur den erfolgreichen Pfad zu testen. Für die Sicherheit ist der negative Test ebenso wichtig: Ein gewöhnliches Repository darf nicht deshalb Zugriff auf einen signierenden Mac erhalten, weil es denselben Namespace oder eine zu weit gefasste Resource Class verwendet.

Die zentrale Sicherheitsfrage lautet nicht, ob ein Job erfolgreich war, sondern was der nächste Job vorfindet. Für diesen Nachweis werden zwei isolierte Testprojekte benötigt. Projekt A legt eindeutig erkennbare Testdateien, temporäre Variablen und nicht produktive Testschlüssel an. Nach dessen Abschluss prüft Projekt B, ob irgendeines dieser Merkmale noch erreichbar ist.

Die Kontrolle umfasst:

1. Arbeitsverzeichnis und versteckte Unterverzeichnisse.
2. Task-Agent- und Build-Caches.
3. SSH-Checkout-Schlüssel und bekannte Hosts.
4. Temporäre Keychains und entsperrte Schlüsselbunddateien.
5. Provisioning Profiles, Zertifikatskopien und signierte Testartefakte.
6. Shell-Logs, Runner-Logs und exportierte Umgebungsvariablen.
7. Zwischenverzeichnisse, Artefaktspeicher und lokale Paket-Caches.

Für produktive Signaturjobs sollte ein dedizierter Benutzer mit möglichst engem Dateisystemzugriff eingesetzt werden. Ein allgemein verwendeter macOS-Knoten, auf dem gleichzeitig untrusted Tests und Release-Signaturen laufen, bleibt auch nach erfolgreicher Runner-Migration eine ungeeignete Vertrauensgrenze.

Der Wiederanlauf muss als reale Betriebsprobe ausgeführt werden. Ein geplanter Remote-Neustart prüft, ob der Dienst nach dem Boot korrekt startet, die Konfiguration findet und wieder Jobs annimmt. Zusätzlich wird der Runner-Prozess kontrolliert beendet und eine kurze Netzwerkunterbrechung simuliert. Jeder Test braucht einen erwarteten Zustand und einen dokumentierten manuellen Eingriff, falls die automatische Erholung ausbleibt.

Dabei wird auf vier Risiken geachtet:

• Ein Job wird nach dem Wiederanlauf doppelt ausgeführt.
• Ein abgebrochener Signatur- oder Veröffentlichungsjob wird fälschlich als erfolgreich interpretiert.
• Der Mac ist erreichbar, der Runner wartet aber wegen fehlerhafter Dienstrechte nicht auf Aufträge.
• Die Warteschlange wächst, obwohl der Status im Dashboard online bleibt.

Die Kapazitätsentscheidung sollte auf einer echten Referenzpipeline beruhen. Zu dokumentieren sind Warteschlangenverlauf, Ausführungsstatus, Fehlerursache, Wiederherstellungszeit und erforderliche Handgriffe. Ohne eine separate Planung der CircleCI-macOS-Runner-Kapazität sollten keine Leistungswerte oder festen Knotenanzahlen behauptet werden.

Entscheidungsbedingungen für die Freigabe

• Wenn Dienststart, erlaubtes und abgewiesenes Routing, Bereinigung, Signaturisolation und Neustart erfolgreich nachgewiesen sind, dann wird der Pilot für eine begrenzte Produktionsgruppe freigegeben.
• Wenn nur die Bereinigung oder die Geheimnisisolation fehlschlägt, dann bleibt der Knoten für nicht signierende Testjobs gesperrt und die Produktivfreigabe wird zurückgestellt.
• Wenn der Runner nach Neustart oder Netzunterbrechung nicht zuverlässig zurückkehrt, dann wird auf den vorbereiteten Ersatzknoten oder den alten, nachweislich funktionsfähigen Dienst zurückgeschaltet.
• Wenn nur ein Projekt korrekt geroutet wird, dann werden Organisationsrichtlinien und Resource Classes korrigiert, bevor weitere Projekte migrieren.
• Wenn Queueing und Release-SLA trotz erfolgreicher Funktion nicht ausreichen, dann wird zusätzliche isolierte Mac-Kapazität bereitgestellt, statt den einzigen Produktionsknoten weiter zu überlasten.

Wie unterscheidet sich die Migration von einer einfachen Neuinstallation?

Eine Neuinstallation beantwortet nur, ob ein Programm auf dem Mac gestartet werden kann. Eine Migration muss zusätzlich beweisen, dass bestehende Projekte, Benutzerrechte, Pfade, Resource Classes, Geheimnisse und Rückfallmechanismen weiterhin korrekt funktionieren. Deshalb sind Parallelpilot und schrittweise Umschaltung sicherer als ein sofortiges Ersetzen des einzigen Produktivknotens.

Welche Rolle spielt Apple Silicon bei einem iOS-CI/CD-Pilot?

Apple Silicon sollte als eigene Abnahmedimension behandelt werden, nicht nur als Hardwareetikett. Toolchain, native Abhängigkeiten, Shell-Umgebung und Signaturworkflow müssen auf dem tatsächlich eingesetzten Mac geprüft werden. Ein erfolgreicher Test auf einem anderen Plattformtyp beweist nicht, dass derselbe iOS-CI/CD-Job unter den neuen Architektur- und Berechtigungsbedingungen identisch läuft.

Muss ein Rollback den alten Dienst dauerhaft aktiviert lassen?

Nein. Ein dauerhaft parallel aktiver alter Dienst erhöht das Risiko konkurrierender Auftragsannahme. Besser ist ein dokumentierter, getesteter Rückfallpfad: alter Dienst vollständig kontrolliert wiederherstellen oder einen vorbereiteten Ersatzknoten aktivieren. Vor der Produktionsumstellung müssen Verantwortliche wissen, welche Konfiguration, welches Token und welche Resource Class dabei verwendet werden.

Welche Belege sollte ein Audit zur Migration enthalten?

Zum Audit gehören die Bestandsaufnahme, Installations- und Signaturnachweise, Konfigurationsvergleich, Routingtests, Bereinigungsprotokolle, Neustart- und Netzwerktests sowie die Freigabe- oder Rückfallentscheidung. Zusätzlich sollten Tokenverantwortung, zulässige Projekte und die Zuordnung von signierenden Jobs zu dedizierten Knoten nachvollziehbar dokumentiert sein.

Nach der Prüfung sollte das Ergebnis ausdrücklich als „freigegeben“, „mit Einschränkung freigegeben“ oder „zur Nachbesserung zurückgegeben“ dokumentiert werden. Eine bloße Online-Anzeige im CircleCI-Dashboard reicht für keine dieser Entscheidungen aus.

Wer den einzigen vorhandenen Mac direkt umbaut, trägt weiterhin mehrere Risiken: Die Umstellung bündelt Wartungs- und Ausfallrisiko auf einem Host, lokale Hardware kann nur langsam ersetzt werden, und ein unklarer Rollback verlängert die Unterbrechung bei fehlerhaften Signaturjobs. Auch der Kauf zusätzlicher Macs bindet Kapital, verlangt Ersatzhardware und überlässt dem Unternehmen Stromversorgung, Remote-Zugriff, Betriebssystempflege und physische Ausfallszenarien.

Für einen isolierten Pilot kann daher ein gemieteter Mac sinnvoller sein, wenn kurzfristig eine getrennte Umgebung benötigt wird, ohne den produktiven Knoten zu verändern. NUKCLOUD ermöglicht den Zugriff auf einen realen, betreuten Mac per VNC, SSH oder Webkonsole; damit kann ein Team einen Machine-Runner-3-Piloten neben der bestehenden Infrastruktur prüfen und erst nach bestandener Abnahme über die dauerhafte Knotenanzahl entscheiden. Informationen zur verfügbaren Mac-Infrastruktur von NUKCLOUD sollten dabei mit den eigenen Datenschutz-, Netzwerk- und Beschaffungsanforderungen abgeglichen werden.

Für langfristig konstante Hochlast, spezielle physische Schnittstellen oder streng lokal gebundene Daten kann ein eigener Mac weiterhin die bessere Wahl sein. Wenn jedoch eine zeitlich begrenzte Migration, ein zusätzlicher Rollback-Knoten oder ein isolierter iOS-CI/CD-Pilot benötigt wird, vermeidet die gemietete Mac-Umgebung den riskanten Umbau des einzigen Produktionssystems.