Leitfaden zur CI-Einrichtung im Team

Runner einrichten – Schritt für Schritt

Der gesamte Apple-Silicon-M4-Mac-mini führt ausschließlich Aufgaben Ihres Teams aus. Prüfen Sie zuerst Instanz und Verbindung, registrieren Sie dann den Runner und legen Sie abschließend die Xcode-Toolchain fest. So grenzen Sie Probleme gezielt ein, statt die gesamte Pipeline neu aufzusetzen.

Prüfen Sie bestehende Bestellungen in der Konsole. Registrierungstoken, SSH-Passwörter und Signaturmaterial gehören nicht in öffentliche Logs.

Von der Bestellung zur Verbindung

Knoten in vier Schritten übernehmen

Von der Zahlungsbestätigung bis zu den geprüften Zugangsdaten dauert es in der Regel etwa 4 Minuten. Die Zeitangaben unten dienen der Orientierung und berücksichtigen weder die Bestätigung durch das Zahlungs-Gateway noch erneute Verbindungsversuche, Abhängigkeitsinstallationen oder die Runner-Registrierung. Maßgeblich ist der Status in der Konsole.

  1. Bestätigte Bestellung prüfen

    Etwa 30 Sekunden

    Prüfen Sie in der Konsole, ob die Bestellung bezahlt ist und Modell, Laufzeit und Knoten mit Ihrer Bestellung übereinstimmen. Merge M4 S bietet 16 GB RAM / 256 GB SSD, Merge M4 L 24 GB RAM / 512 GB SSD. Beide Modelle nutzen Apple Silicon M4.

    Hier kommen Sie nicht weiter? Prüfen Sie zuerst den Rechnungsstatus. Zahlen Sie nicht erneut, nur weil die Seite noch nicht aktualisiert wurde. Notieren Sie die Bestellnummer und gleichen Sie den Zahlungseingang im Abrechnungsbereich dieser Seite ab.

  2. Zuweisung des physischen Knotens prüfen

    Etwa 2 Minuten

    Öffnen Sie die mit der Bestellung verknüpfte Instanz und warten Sie, bis Status und Verbindungsdaten angezeigt werden. Jeder Rechner wird genau einem Kunden zugewiesen und ist keine virtuelle Maschine. Die Jobplanung innerhalb Ihres Teams übernehmen die von Ihnen konfigurierten Runner.

    Hier kommen Sie nicht weiter? Notieren Sie Instanz-ID, Bestellnummer und aktuellen Status und erstellen Sie über die Konsole ein Support-Ticket. „Rechnung bezahlt“ bedeutet nicht automatisch, dass die Instanz-Zugangsdaten bereits erstellt wurden.

  3. Verbindungsdaten abrufen

    Etwa 1 Minute

    Rufen Sie in den Instanzdetails SSH-Adresse, Port, Benutzernamen und VNC-Verbindungsdaten ab. Verwenden Sie die angezeigten Angaben genau. Raten Sie keine Standardports und nutzen Sie weder Adresse noch Passwort einer früheren Instanz weiter.

    Hier kommen Sie nicht weiter? Vergewissern Sie sich, dass das angemeldete Konto der Bestellung zugeordnet ist und Sie die richtige Instanz geöffnet haben. Für ein Support-Ticket genügen die Instanz-ID und die Bezeichnung des fehlenden Feldes. Senden Sie niemals das vollständige Passwort.

  4. Remote-Verbindung testen

    Etwa 30 Sekunden

    SSH eignet sich für Builds auf der Kommandozeile, die Runner-Registrierung und die Dateisynchronisierung. VNC ermöglicht die Nutzung der grafischen Xcode-Oberfläche, von Simulatoren und interaktiven Einstellungen. Sie können macOS sowohl grafisch als auch über die Kommandozeile bedienen und beide Zugriffswege kombinieren.

    ssh -p "$SSH_PORT" "$SSH_USER@$SSH_HOST"
    uname -m
    sw_vers

    Prüfen Sie beim ersten Verbindungsaufbau den Host-Fingerabdruck. Nach erfolgreicher Verbindung muss die Architektur arm64. Bei einer Zeitüberschreitung prüfen Sie Adresse, Port und lokales Netzwerk; bei einem Authentifizierungsfehler Benutzernamen und Zugangsdaten. Umgehen Sie einen abweichenden Fingerabdruck nicht, indem Sie die Host-Prüfung deaktivieren.

    Verwenden Sie im VNC-Client die entsprechenden Angaben aus den Instanzdetails, nicht einfach den SSH-Port. Ist die Verbindung langsam, reduzieren Sie zunächst die Auflösung. Automatische Builds können weiterhin über SSH ausgeführt werden.

Vorhandene CI weiterverwenden

Jobs gezielt diesem M4 zuweisen

Rufen Sie zuerst auf der CI-Plattform die Installationsdatei und den Registrierungsbefehl über die Seite zum Hinzufügen eines Runners oder Agents ab und führen Sie sie dann auf dem Knoten aus. Die folgenden Hinweise behandeln nur die Registrierung. Token, Organisations-URL und Arbeitsverzeichnis stellt Ihre Plattform bereit – die Beispielvariablen können nicht unverändert übernommen werden. Führen Sie nach der Installation zunächst einen Testjob ohne Signaturmaterial aus.

GitHub Actions

Fügen Sie in den Repository- oder Organisationseinstellungen einen self-hosted runner hinzu und wählen Sie das Paket für macOS und ARM64. Entpacken Sie es, führen Sie im Runner-Verzeichnis den von der Plattform bereitgestellten Konfigurationsbefehl aus und starten Sie anschließend den Prozess.

./config.sh \
  --url "$RUNNER_URL" \
  --token "$RUNNER_TOKEN" \
  --labels macos-m4
./run.sh

Legen Sie im Workflow runs-on: [self-hosted, macOS, ARM64, macos-m4]fest und prüfen Sie, ob die Labels mit der Registrierung übereinstimmen. Labels dienen der Job-Zuweisung; sie isolieren nicht automatisch verschiedene Aufgaben auf dem Rechner.

Prüfpunkt: Die Plattform zeigt den Runner als online an und der Testjob gibt bei uname -m den Wert arm64aus. Soll der Runner dauerhaft laufen, richten Sie den Dienst gemäß den Installationshinweisen ein und führen Sie ihn unter demselben Build-Benutzer aus.

Empfohlenes Label: macos-m4

GitLab Runner

Erstellen Sie im Projekt oder in der Gruppe einen Runner und rufen Sie das für die aktuelle Version geltende Authentifizierungstoken ab. Installieren Sie die ARM64-Version und registrieren Sie sie. Wählen Sie als Executor „shell“, damit Jobs in der macOS-Umgebung dieses Build-Benutzers ausgeführt werden.

gitlab-runner register
gitlab-runner verify
gitlab-runner run

Legen Sie auf der Plattform für den Runner das Label macos-m4 fest und tragen Sie in den Job- tags denselben Wert ein. Geben Sie bei der interaktiven Registrierung die von der Plattform bereitgestellte URL und das Token ein. Speichern Sie das Token nicht im Repository.

Prüfpunkt: Der Runner ist dem richtigen Projekt zugeordnet und Jobs wechseln in den Ausführungsstatus. Bleiben sie dauerhaft in der Warteschlange, prüfen Sie Labels, Einstellungen für geschützte Branches und die Projektberechtigung des Runners. Kontrollieren Sie anschließend die Systemauslastung.

Ausführungsmodus: shell

Jenkins-Agent

Erstellen Sie einen dedizierten Knoten und legen Sie das Remote-Arbeitsverzeichnis sowie das Label macos-m4 fest. Installieren Sie eine mit den Vorgaben des Controllers kompatible Java-Version, laden Sie die vom Controller bereitgestellte Agent-Datei herunter und verwenden Sie die dort erzeugten Startparameter.

java -jar agent.jar \
  -url "$JENKINS_URL" \
  -secret "$AGENT_SECRET" \
  -name "$AGENT_NAME" \
  -webSocket \
  -workDir "$AGENT_WORKDIR"

Geben Sie in der Pipeline agent { label 'macos-m4' }an. Das Build-Benutzerkonto muss Schreibrechte für das Arbeitsverzeichnis haben. Die Java-Version muss den Anforderungen des Controllers entsprechen – prüfen Sie nicht nur, ob Java im lokalen Terminal startet.

Prüfpunkt: Der Controller zeigt den Knoten als online an und der Arbeitsbereich liegt im erwarteten Verzeichnis. Ermitteln Sie zunächst mit einem Executor eine Ausgangsbasis. Bewerten Sie die Parallelverarbeitung anschließend anhand von Arbeitsspeicher, Speicherplatz und Testlast.

Zunächst einen einzelnen Job testen

Ein dedizierter Rechner verhindert CPU-Konkurrenz mit anderen Kunden, aber nicht Warteschlangen innerhalb Ihres Teams. Wenn ein Runner mehrere Jobs gleichzeitig ausführt, müssen Sie Parallelität, Arbeitsbereiche und die Isolation von Signaturmaterial weiterhin selbst verwalten.

Eine reproduzierbare Umgebung festlegen

Lokale Entwicklung und CI auf dieselbe Xcode-Version ausrichten

„Im Terminal funktioniert der Build, im Runner nicht“ liegt oft an einem anderen Toolchain-Pfad oder Benutzerkonto. Notieren Sie zuerst die aktuelle Version, wählen Sie dann die Toolchain und installieren Sie anschließend die erforderlichen Simulator-Runtimes. Eine Neuinstallation von Xcode sollte nicht der erste Schritt sein.

Vor dem Wechsel Version notieren

Mehrere Xcode-Versionen können in unterschiedlichen App-Verzeichnissen liegen. Erfassen Sie mit den folgenden Befehlen zunächst Systemversion, aktuelles Entwicklerverzeichnis und Build-Tool-Versionen. Vergleichen Sie die Ausgabe anschließend mit den Projektanforderungen.

sw_vers
xcode-select -p
xcodebuild -version
xcrun --find swift

Soll der Standard für den gesamten Rechner geändert werden, verwenden Sie xcode-select. Vergewissern Sie sich vor dem Wechsel, dass keine anderen Builds laufen, und prüfen Sie das Ergebnis anschließend unter dem CI-Ausführungskonto.

sudo xcode-select --switch \
  /Applications/Xcode.app/Contents/Developer
xcodebuild -version

Pro Job auswählen, je Projekt herunterladen

Wenn Ihr Team verschiedene Xcode-Versionen benötigt, legen Sie für jeden Job bevorzugt DEVELOPER_DIRfest, um Konflikte durch globale Wechsel zu vermeiden. Ersetzen Sie den Beispielpfad durch das tatsächliche Versionsverzeichnis auf dem Knoten.

export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
xcodebuild -version
xcrun simctl list runtimes
xcrun simctl list devices available
df -h

Laden Sie in den Xcode-Einstellungen die Simulator-Runtimes passend zu den Projektzielen herunter. Runtimes, Simulator-Daten und DerivedData belegen Speicherplatz. Prüfen Sie vor der Installation den freien Speicher und behalten Sie nur die vom Team tatsächlich verwendeten Versionen.

Dass ein Befehl verfügbar ist, bedeutet nicht, dass alle Projektabhängigkeiten installiert sind. Prüfen Sie Ruby, CocoaPods, Paketmanager und Sperrdateien unter demselben Benutzer. Bestätigen Sie Aufforderungen zur Erstinstallation zunächst in einer interaktiven Umgebung.

Prüfen Sie diese drei Punkte in der Runner-Umgebung, bevor Sie den ersten Build starten
PrüfpunktPrüfbefehl oder -ortErwartetes Ergebnis
Toolchain-Pfadxcode-select -p und Umgebungsvariablen des JobsVerweist auf die für das Projekt festgelegte Xcode-Version; die Versionsausgabe stimmt mit den Erwartungen überein
Ausführender Benutzerwhoamiundprintf '%s\n' "$HOME"Build-Benutzer, Home-Verzeichnis und Benutzer des Schlüsselbunds stimmen überein
Arbeitsbereich und Speicherplatzpwdunddf -hDer Arbeitsbereich ist beschreibbar; für Abhängigkeiten, temporäre Dateien und Archive ist genügend Speicherplatz vorhanden

Begriffe im Team einheitlich verwenden

Acht Begriffe, acht klare Abgrenzungen

Wenn Sie Rechner, Verbindungsmethode und Jobplanung getrennt betrachten, können Sie bei einer Supportanfrage genau angeben, auf welcher Ebene das Problem auftritt.

Physischer Knoten
Das Mac-mini-Gerät, auf dem macOS und Builds ausgeführt werden. Die Verbindungsdaten in den Instanzdetails gehören zu Ihrem gemieteten Knoten.
Dediziert
Der gesamte Rechner ist einem Kunden zugewiesen und teilt keine CPU-Ressourcen mit anderen Kunden. Die Jobparallelität im eigenen Team muss weiterhin selbst verwaltet werden.
Keine virtuelle Maschine
Sie erhalten eine dedizierte physische Mac-Umgebung und keine virtuelle Instanz auf einem gemeinsam genutzten Host.
VNC
Verbindung zur Anzeige und Steuerung der grafischen macOS-Oberfläche – geeignet für Xcode, Simulatoren und interaktive Konfigurationen.
SSH
Verschlüsselte Verbindung zur Kommandozeile. Damit können Sie Build-Befehle ausführen, Prozesse verwalten und Dateien mit geeigneten Tools übertragen.
Self-hosted Runner
CI-Ausführungsprogramm, das Ihr Team auf dem eigenen Knoten registriert und verwaltet. Es ruft Jobs von der CI-Plattform ab und führt sie aus.
Apple Silicon
Die Apple-Chiparchitektur in Macs. Beide Modelle dieses Angebots verwenden M4. Prüfen Sie bei Abhängigkeiten und Runner-Installationspaketen die Unterstützung für arm64.
Thunderbolt-5-Verbindung
Im Verzeichnis als Zusatzoption pro Gerät abgerechnete Verbindung. Sie fasst weder CPU noch Arbeitsspeicher mehrerer Rechner automatisch zu einem System zusammen. Die Arbeitslasten müssen weiterhin selbst orchestriert werden.

Protokolle sichern, dann Umgebung ändern

Builds anhand der Fehlerquelle wiederherstellen

Sichern Sie zuerst den fehlgeschlagenen Befehl, den Exitcode und die erste aussagekräftige Fehlermeldung. Ändern Sie dann nur eine Variable und führen Sie den Job erneut aus. Wenn Sie gleichzeitig Xcode wechseln, Caches löschen und den Runner neu registrieren, lässt sich nicht mehr feststellen, was das Problem behoben hat.

Signierung fehlgeschlagen? Benutzerkonto und Schlüsselbund prüfen

Unterscheiden Sie zunächst zwischen einem Compiler- und einem Signierungsfehler. Prüfen Sie Zertifikat, zugehörigen privaten Schlüssel, Provisioning Profile und Gültigkeitsdauer nur dann, wenn der Fehler beim Archivieren oder Signieren auftritt. Ihr Team muss diese Materialien gemäß den Projektanforderungen einrichten.

whoami
security list-keychains -d user
security find-identity -v -p codesigning

Kann die Signierung über die grafische Oberfläche ausgeführt werden, schlägt aber in CI fehl, prüfen Sie, ob der Runner unter demselben Benutzer läuft, der betreffende Schlüsselbund in der Suchliste steht und nicht interaktive Prozesse die nötigen Zugriffsrechte haben. Muss der Schlüsselbund entsperrt werden, injizieren Sie die Zugangsdaten über geschützte CI-Secrets. Passwörter dürfen nicht in Skripten, im Befehlsverlauf oder in Logs stehen.

Prüfen Sie nach dem Import eines Zertifikats außerdem, ob das Provisioning Profile zum Team, zur App-ID und zur Build-Konfiguration passt. Fügen Sie einem Support-Ticket nur bereinigte Fehlermeldungen bei – niemals private Schlüssel, Zertifikatspasswörter oder vollständiges Signaturmaterial.

Cache-Probleme? Zuerst auf ein Projekt eingrenzen

Führen Sie denselben Commit zunächst erneut aus und notieren Sie die Xcode-Version. Schlägt nur die Auflösung einer Abhängigkeit fehl, prüfen Sie Sperrdatei, Abhängigkeitsversion und Download-Fehler. Netzwerkprobleme lassen sich nicht dadurch beheben, dass Sie wiederholt alle Caches löschen.

Legen Sie für jedes Projekt einen eigenen DerivedData-Pfad fest, um nur dessen Build-Artefakte neu zu erstellen. Der folgende Befehl setzt einen vorhandenen, separaten Arbeitsbereich voraus. Ersetzen Sie vor der Ausführung die Variablen durch echte Pfade und ein gemeinsames Scheme.

xcodebuild \
  -workspace "$WORKSPACE" \
  -scheme "$SCHEME" \
  -derivedDataPath "$PROJECT_DERIVED_DATA" \
  clean build

clean erhöht den Aufwand beim nächsten Build. Mehrere Jobs dürfen nicht dasselbe beschreibbare Cache-Verzeichnis verwenden. Beenden Sie zuerst die Jobs, die das Verzeichnis nutzen, bevor Sie es bereinigen oder verschieben.

Speicherplatz knapp? Cache, Runtime und Build-Artefakte prüfen

Prüfen Sie zuerst den freien Speicherplatz und ermitteln Sie dann den tatsächlichen Speicherbedarf von DerivedData, Archiven und Simulatordaten. Löschen Sie nicht einfach rekursiv das gesamte Benutzerverzeichnis und entfernen Sie keine Artefakte, solange Archive hochgeladen werden.

df -h
du -sh "$HOME/Library/Developer/Xcode/DerivedData"
du -sh "$HOME/Library/Developer/Xcode/Archives"
du -sh "$HOME/Library/Developer/CoreSimulator"

Beenden Sie betroffene Jobs, löschen Sie nicht mehr benötigte Projekt-Caches, entfernen Sie ungenutzte Runtimes in Xcode und behandeln Sie gesicherte ältere Archive gemäß den Aufbewahrungsregeln Ihres Teams. Sichern Sie Projekte, Signaturmaterial und Release-Artefakte separat.

Berücksichtigen Sie bei dauerhaft höherem Speicherbedarf die Zusatzoptionen +1 TB SSD oder +2 TB SSD in der Bestellkonfiguration. Mehr Speicher bedeutet nicht mehr Arbeitsspeicher. Stellen Sie zuerst sicher, dass tatsächlich der Datenträger und nicht die Jobparallelität der Engpass ist.

Runner offline? Verbindung, Prozess und Berechtigungen prüfen

Prüfen Sie zuerst per SSH, ob der Knoten erreichbar ist, und kontrollieren Sie dann Runner-Prozess und Logs. Ist der Knoten online, während die CI-Plattform den Runner als offline anzeigt, prüfen Sie, ob der Prozess beendet wurde, die Verbindung zum CI-Controller möglich ist und Token oder Knotenberechtigungen geändert wurden.

Starten Sie den Runner einmal im Vordergrund und sichern Sie die erste Verbindungsfehlermeldung. Läuft er im Vordergrund, wird aber nach dem Schließen des Terminals beendet, müssen Sie gemäß der Dokumentation dieses Runners einen dauerhaften Dienst einrichten. Dienstkonto, Toolchain, Arbeitsverzeichnis und Schlüsselbund müssen auf denselben Benutzer abgestimmt sein.

Vergewissern Sie sich vor einem Neustart, dass keine Archive oder Uploads laufen, damit keine Artefakte abgeschnitten werden. Zeigt die Plattform den Runner als online an, während Jobs in der Warteschlange bleiben, prüfen Sie Labels, Branch-Berechtigungen und Parallelitätslimits. Löschen Sie den Runner nicht wiederholt, um ihn neu zu registrieren.

Wenn Sie mehrere Instanzgruppen oder Pools betreiben, geben Sie den Knoten aussagekräftige Labels, zum Beispiel macos-m4-build und macos-m4-release. So werden Release-Jobs nur den Knoten zugewiesen, auf denen die passende Signierungsumgebung eingerichtet ist.

Transaktion prüfen, bevor Sie es erneut versuchen

Zahlung und Bestellung eindeutig zuordnen

Abrechnung nach Tag, Woche, Monat oder Quartal – einheitlich in US-Dollar (USD). Unterstützt werden ausschließlich USDT-TRC20 sowie Visa / Mastercard / Amex, verarbeitet über Stripe. Welche Zahlungsoptionen tatsächlich verfügbar sind, hängt von der Rückmeldung der Backend-Schnittstelle ab.

USDT-TRC20 gesendet, Bestellung noch nicht bestätigt

Prüfen Sie Netzwerk, Empfängeradresse und Betrag anhand der Zahlungsseite der Bestellung. Eine gesendete Transaktion bedeutet nicht, dass die Bestellung bestätigt ist. Kontrollieren Sie sowohl den Status der Transaktion auf der Blockchain als auch den Rechnungsstatus in der Konsole.

Senden Sie keine weitere Zahlung, um die Bestätigung zu beschleunigen, und verwenden Sie keine Zahlungsdaten einer anderen Bestellung. Notieren Sie Bestellnummer, Transaktions-Hash, Betrag und Sendezeit und übermitteln Sie diese Angaben über ein Support-Ticket in der Konsole. Senden Sie niemals Wallet-Schlüssel oder Wiederherstellungsphrase.

Ist die Zahlungsseite bereits geschlossen, öffnen Sie zuerst dieselbe Bestellung erneut und prüfen Sie ihren aktuellen Status. Entscheiden Sie erst danach, ob Sie die Zahlung fortsetzen, damit keine doppelte Zahlung für denselben Dienst entsteht.

Kartenzahlung nicht abgeschlossen? Verifizierung und Rückmeldung der Bank prüfen

Prüfen Sie, ob Karten- und Rechnungsdaten korrekt sind, das Limit ausreicht und die Verifizierung durch den Kartenanbieter abgeschlossen wurde. Wurde die Weiterleitung blockiert, erlauben Sie die für den laufenden Zahlungsvorgang erforderliche Seite und prüfen Sie dann die Bestellung erneut.

Speichern Sie bei einer Ablehnung die Kurzbeschreibung des Fehlers und fragen Sie bei Ihrer Bank nach möglichen Transaktionsbeschränkungen. Versuchen Sie es nicht in rascher Folge erneut. Zeigt die Bank eine Belastung an, während die Bestellung unbestätigt bleibt, lassen Sie den Vorgang zuerst per Support-Ticket prüfen, statt sofort erneut zu zahlen.

Für ein Support-Ticket genügen Bestellnummer, Zeitpunkt und ein geschwärzter Screenshot der Fehlermeldung. Wir benötigen weder Ihre vollständige Kartennummer noch Sicherheitscode oder Bank-Verifizierungscode.

Vor der Verlängerung Instanz, Laufzeit und Ablaufdatum prüfen

Öffnen Sie in der Konsole das zur bestehenden Instanz gehörende Abonnement oder die Rechnung. Prüfen Sie Instanz-ID, Ablaufdatum und abzurechnende Laufzeit, bevor Sie zahlen. Eine neue Bestellung ist nicht dasselbe wie die Verlängerung einer bestehenden Instanz. Verlassen Sie sich nicht allein auf die Modellbezeichnung.

Ob die Verlängerung abgeschlossen ist, erkennen Sie am Rechnungs- und Instanzstatus. Gehen Sie nicht von einer automatischen Verlängerung aus. Sichern Sie vor dem Ablauf Projekte, Cache-Konfigurationen und Release-Artefakte. Eine Löschung des Datenträgers nach Freigabe der Instanz ist kein wiederherstellbares Backup.

Die Knoten laufen 365 Tage im Jahr. Wenn es um die Verfügbarkeit geht, übermitteln Sie zur Prüfung die Instanz-ID, den betroffenen Zeitraum und den Verbindungsfehler. Verwechseln Sie nicht das manuelle Beenden eines Prozesses mit einem Ausfall des Knotens.

Nachvollziehbare Angaben beifügen

Fehlerbild an den Support übermitteln

Melden Sie Probleme mit bestehenden Instanzen über ein Support-Ticket in der Konsole. Geben Sie Instanz-ID, Zeitpunkt und Zeitzone, fehlgeschlagenen Schritt, erwartetes Ergebnis und bereinigte Logs an. Für mehrere Knoten oder die Planung eines Runner-Pools bündeln Sie Ihre Anforderungen über die Kontaktseite oder schreiben Sie an support@vpsmerge.com.

Senden Sie keine Passwörter, Registrierungstoken, privaten Schlüssel oder vollständigen Zahlungsdaten. Die erste aussagekräftige Fehlermeldung ist hilfreicher als seitenlange, wiederholte Logs.