Für alle, die Builds zusammenführen und veröffentlichen

Den nächsten Merge auf einem dedizierten Build-Server ausführen

Erstellen Sie zunächst manuell eine überprüfbare IPA und übergeben Sie den Build anschließend an CI. Die Anleitung führt Sie durch Start, Verbindung, CI-Einrichtung, Verteilung und den laufenden Betrieb – ohne dass Sie Ihre bestehende Pipeline neu aufsetzen müssen.

iOS-Build-Server mieten Schritt für Schritt einrichten

Der erste Verbindungstest ist auf etwa eine Stunde ausgelegt; das ist keine Zusage für eine feste Bereitstellungszeit. Große Downloads, die Xcode-Installation und die Vorbereitung der Signierungsunterlagen können länger dauern. Bei einem bestehenden Server können Sie direkt mit dem Verbindungscheck beginnen.

Vor dem Start: alles bereitlegen

Wählen Sie einen Server, der zu Ihrem Projekt passt

Wenn Sie nur gelegentlich Builds erstellen und bereits einen ungenutzten Mac haben, kann der Eigenbetrieb günstiger sein. Bei mehreren Merges am Tag und wenn Sie sich nicht um Stromversorgung, Netzwerk und Kühlung kümmern möchten, ist ein dedizierter, gehosteter Server eine Option. OSXPort stellt einen vollständigen physischen Mac mini bereit, der jeweils nur einem Kunden zugewiesen wird – keine virtuelle Maschine.

  1. 01

    Projektanforderungen klären

    Halten Sie einen reproduzierbaren Build-Befehl, den Codezugriff, die benötigte Xcode-Version und die Lockfiles bereit. Beginnen Sie mit einer App, einem Scheme und einem Branch. Machen Sie aus dem ersten Testlauf keine Migration des gesamten Release-Systems.

  2. 02

    Konfiguration und Laufzeit wählen

    Wählen Sie auf der Bestellseite Modell, Region und eine Laufzeit von einem Tag, einer Woche, einem Monat oder einem Quartal. Port M4 Base eignet sich für erste Tests mit leichter Auslastung. Bei Builds mehrerer Branches und Simulator-Aufgaben empfiehlt sich Port M4 Plus; für große Projekte mit vielen Targets kommt Port M4 Pro infrage.

  3. 03

    Zugangsdaten sichern

    Nach der Bestellung finden Sie im Portal die Serveradresse, den Benutzernamen für die Verbindung und die Zugangsdaten. Maßgeblich ist der aktuelle Status im Portal. Tragen Sie die Serverkennung in das Asset-Verzeichnis Ihres Teams ein. Zugangspasswörter gehören weder ins Repository noch in den Tickettext.

  4. 04

    Eine passende Region wählen

    Zur Auswahl stehen Singapur, Japan (Tokio), Südkorea (Seoul), Hongkong und der Westen der USA. Berücksichtigen Sie neben dem Standort Ihres Teams auch, wo Repository und Paketquellen liegen. Testen Sie die tatsächliche Verbindung mit Ihren eigenen Download- und Upload-Aufgaben.

Es gibt drei Konfigurationen: Apple Silicon M4 · 16 GB Unified Memory · 256 GB SSD, Apple Silicon M4 · 24 GB Unified Memory · 512 GB SSD sowie Apple Silicon M4 Pro · 64 GB Unified Memory · 2 TB SSD. Starten Sie beim ersten Test nicht gleich mit hoher Parallelität. Messen Sie zunächst Arbeitsspeicher, Speicherplatz und Größe der Artefakte für einen einzelnen Build.

Konfiguration wählen & mieten Im Portal Zugangsdaten ansehen
Erst den Server prüfen, dann CI anbinden

Anmeldung, Build und Export mit demselben Benutzer ausführen

Prüfen Sie bei der ersten Verbindung zunächst Serveradresse und Benutzername, danach die Entwicklungswerkzeuge. Die folgende Sitzung dient als Beispiel und zeigt keine Live-Ausgabe eines Servers. Versionsnummern veranschaulichen nur das Format; maßgeblich ist die Ausgabe auf dem jeweiligen Server.

In drei Schritten prüfen – nicht gleich die Umgebung neu aufsetzen

Verbindung: Stellen Sie die Verbindung mit Adresse, Port und Benutzername aus dem Portal her. Prüfen Sie beim ersten Mal den Host-Fingerprint. Hat er sich unerwartet geändert, klären Sie zunächst, ob der Server gewechselt wurde, statt die Prüfung zu überspringen. Bei einem Timeout prüfen Sie Adresse und Netzwerk; bei einem Authentifizierungsfehler Benutzername und Zugangsdaten.

Werkzeuge: Mit xcode-select -p prüfen Sie den aktiven Entwicklerpfad. Mit xcodebuild -version halten Sie die Version fest. Benötigt das Projekt eine andere Version, vergewissern Sie sich zuerst, dass sie installiert ist, und setzen Sie anschließend den Pfad explizit.

Projekt: Installieren Sie im Projektverzeichnis die festgelegten Abhängigkeiten und führen Sie den bestehenden Build-Befehl zunächst manuell aus. Eine erfolgreiche interaktive Anmeldung bedeutet nicht, dass ein Runner im Hintergrund auf Signierungsmaterial zugreifen kann. Testen Sie den Zugriff später mit dem tatsächlichen Ausführungsbenutzer des Runners.

Setzen Sie im Beispiel NODE_USER und NODE_ADDRESS auf die Werte aus dem Portal. App.ipa ist ein Beispielname für das Artefakt. Verwaltet das Projekt Fastlane mit Bundler, verwenden Sie bundle exec fastlane gym.

osxport · tokyo-node
$ ssh "$NODE_USER@$NODE_ADDRESS"
$ xcode-select -p
/Applications/Xcode.app/Contents/Developer
$ xcodebuild -version
Xcode 16.4
Build version 16F6
$ cd ~/workspace/App
$ fastlane gym
Creating archive
Exporting archive
Successfully exported and compressed dSYM file
Successfully exported and signed the ipa file
Exported ipa: ./build/App.ipa
$ ls -lh ./build/App.ipa

Abnahmekriterien: Der Remote-Befehl wird erfolgreich beendet, die Version entspricht den Projektanforderungen und das Artefakt liegt am erwarteten Pfad. Bewahren Sie bei Signierungs- oder Build-Fehlern die Logs rund um die erste Fehlermeldung auf, nicht nur die letzte Zeile.

Die bestehende CI weiterverwenden

Erst einen manuellen Job erfolgreich ausführen, dann den Runner registrieren

Alle drei Varianten laufen auf demselben physischen macOS-Server. Die Teamgrößen sind Empfehlungen zur Organisation, keine Kapazitätszusage. Legen Sie die Parallelität anhand des Arbeitsspeichers pro Build, der gleichzeitig laufenden Simulatoren und des Speicherbedarfs fest.

GitHub Actions: self-hosted Runner

Geeignet für: Teams mit etwa 3–15 Personen, die bereits mit Workflow-Dateien arbeiten. Ein zusätzliches Planungssystem ist nicht nötig: Registrieren Sie den Server einfach bei einem zugriffsgeschützten Repository oder einer Organisation.

  1. Laden Sie in den Einstellungen des Repositorys oder der Organisation das Runner-Paket und den Registrierungsschlüssel für die passende macOS-Version und Chiparchitektur herunter.
  2. Registrieren Sie den Runner mit einem eigenen Ausführungsbenutzer, vergeben Sie Team-Labels und verweisen Sie den Workflow mit runs-on auf das passende Label.
  3. Führen Sie zuerst eine Versionsprüfung und einen Build ohne vertrauliche Daten aus. Richten Sie anschließend Hintergrunddienst, Geheimnisverwaltung und Artefakt-Upload ein.

Nicht empfohlen: Geben Sie einen Server mit Signierungsmaterial für nicht vertrauenswürdige externe Pull Requests frei. Ein dedizierter Host isoliert einzelne Workflows nicht voneinander.

Runner prüfen

GitLab Runner · Shell Executor

Geeignet für: Teams mit etwa 3–30 Personen, die Code und Berechtigungen zentral in GitLab verwalten. Der Shell Executor verwendet Xcode und die Kommandozeilenwerkzeuge direkt auf dem Server.

  1. Installieren Sie GitLab Runner für macOS und registrieren Sie den Runner mit den Registrierungsdaten des Projekts oder der Gruppe.
  2. Wählen Sie den Executor shell, vergeben Sie ein eigenes Label und beschränken Sie den Einsatz auf geschützte Branches und freigegebene Jobs.
  3. Gliedern Sie Abhängigkeitsinstallation, Build, Export und Artefaktsicherung in einzeln prüfbare Schritte. Beginnen Sie mit einem parallelen Job.

Nicht empfohlen: Lassen Sie nicht vertrauenswürdige Kunden-Repositories auf demselben Shell Executor laufen. Arbeitsverzeichnis und Host-Berechtigungen müssen Sie selbst verwalten.

Runner prüfen

Jenkins Agent

Geeignet für: Teams mit etwa 10–30 Personen und einem bestehenden Jenkins Controller samt Release-Freigabeprozess. Binden Sie den Server als macOS-Agent ein, ohne die gesamte Pipeline zu migrieren.

  1. Erstellen Sie im Controller einen eigenen Agent und legen Sie Server-Label, Arbeitsverzeichnis und Ausführungsbenutzer fest.
  2. Richten Sie die Verbindung gemäß Controller-Konfiguration ein. Prüfen Sie die Kompatibilität der benötigten Java-Version und Laufzeitumgebung, bevor Sie den Agent dauerhaft aktivieren.
  3. Weisen Sie Testjobs explizit das macOS-Label zu und prüfen Sie Umgebungsvariablen, Werkzeugpfade und Berechtigungen für die Artefaktablage.

Nicht empfohlen: Richten Sie nicht eigens für einen gelegentlichen Build einen Controller ein. Bei einer vorhandenen schlanken CI bringt ein weiteres zu verwaltendes System meist keinen Vorteil.

Runner prüfen

Der Runner ist online? Prüfen Sie zusätzlich diese vier Punkte

Prüfen Sie alles mit dem tatsächlichen Runner-Benutzer – nicht nur in Ihrer interaktiven Sitzung.
PrüfpunktSo prüfen Sie esErfüllt, wenn
Arbeitsverzeichnis und WerkzeugeFühren Sie whoami, pwd und xcodebuild -version aus.Benutzer, Verzeichnis und Xcode-Version zur Job-Konfiguration passen
Repository und AbhängigkeitenRufen Sie mit den von CI bereitgestellten, eingeschränkten Zugangsdaten den vorgesehenen Branch ab und installieren Sie die Abhängigkeiten anhand der Lockfiles.Keine nicht dokumentierten Tokens oder Pfade aus einem persönlichen Terminal benötigt werden
SignierungErstellen und exportieren Sie ein Archiv in einem nicht interaktiven Job.Keine manuelle Bestätigung erforderlich ist und Zugangsdaten nicht in Logs erscheinen
Verbindung und ArtefaktePrüfen Sie den Status des Hintergrunddienstes und rufen Sie Artefakte und Logs nach dem Job ab.Der Runner die Verbindung wiederherstellen kann und Artefakte nicht nur im temporären Arbeitsverzeichnis liegen

Auf einem Server können mehrere kontrollierte Job-Einstiege registriert sein. Sie nutzen jedoch weiterhin dieselbe CPU, denselben Unified Memory und dieselbe SSD. Begrenzen Sie die Parallelität zunächst auf einen Build und erhöhen Sie sie schrittweise anhand eigener Messwerte. Mehrere Runner-Namen schaffen keine zusätzlichen Ressourcen.

Unter Windows entwickeln, unter macOS bauen

Den iOS-Build von Flutter auf dem Remote-Server ausführen

Unter Windows können Sie programmieren, Änderungen einreichen und Logs ansehen. Kompilierung und Signierung für iOS laufen weiterhin auf dem Cloud-Mac. Ein dedizierter Server ersetzt weder eine gültige Apple-Developer-Mitgliedschaft noch Signierzertifikat, privaten Schlüssel oder das zur App passende Provisioning Profile.

  1. 01

    Abhängigkeiten festlegen

    Verwenden Sie denselben Commit und dieselben Lockfiles und prüfen Sie die Kompatibilität von Flutter, Dart, CocoaPods und Xcode. Kontrollieren Sie die Toolchain zunächst mit flutter doctor -v und führen Sie dann flutter pub get aus. Übernehmen Sie keine absoluten Pfade von einem anderen Rechner in das Projekt.

  2. 02

    Signierungsmaterial einrichten

    Übertragen Sie Zertifikat, privaten Schlüssel und Provisioning Profile auf einem vom Team freigegebenen sicheren Weg. Importieren Sie das Zertifikat in einen dedizierten Schlüsselbund, auf den der tatsächliche Build-Benutzer zugreifen kann. Konfigurieren Sie Provisioning Profile und Exportoptionen. Bundle Identifier, Team-ID und Verteilungsart müssen zusammenpassen.

  3. 03

    Build ausführen und Artefakt abrufen

    Führen Sie flutter build ipa --release aus. Benötigt das Projekt bestimmte Exportregeln, ergänzen Sie die passende --export-options-plist-Datei. Das Artefakt liegt üblicherweise unter build/ios/ipa/ im Projektverzeichnis; maßgeblich ist die tatsächliche Ausgabe. Lassen Sie CI den Build anschließend im Artefaktspeicher des Teams ablegen.

  4. 04

    Testgrenzen beachten

    Simulator-Tests und automatisierte Builds lassen sich remote ausführen. Prüfungen mit einem physischen Gerät, seinen Sensoren oder der Bedienung müssen weiterhin am Gerät stattfinden. Auch React-Native-Teams können den iOS-Build auf dem Server ausführen; die Abhängigkeiten sollten anhand der projektspezifischen Skripte wiederhergestellt werden.

Ein Cache beschleunigt Builds, ist aber kein Backup. Verwenden Sie Cache-Schlüssel, die Projekt, Xcode-Version und Lockfiles berücksichtigen. Prüfen Sie bei Signierungsproblemen zuerst Gültigkeit, privaten Schlüssel und Provisioning Profile, statt alle Build-Caches zu löschen.

Erst den Export testen, dann den Upload einrichten

Zugangsdaten für die Verteilung getrennt vom Serverzugang verwalten

Für die Verteilung über TestFlight muss die App in App Store Connect entsprechend eingerichtet sein. Außerdem benötigen Sie die passenden Veröffentlichungsrechte. Der API Key autorisiert den Upload, ersetzt aber nicht das Signierzertifikat und Provisioning Profile für die Kompilierung.

Empfohlene Reihenfolge

  1. Installierbares Artefakt erstellen. Erstellen und exportieren Sie zunächst mit fastlane gym oder dem bestehenden Projektbefehl ein Archiv. Prüfen Sie Bundle Identifier, Versionsnummer und Buildnummer.
  2. API Key bereitstellen. Eine Person mit den nötigen Rechten erstellt einen App Store Connect API Key mit passender Rolle. Notieren Sie Key ID und Issuer ID und bewahren Sie die Datei mit dem privaten Schlüssel sicher auf.
  3. Für CI bereitstellen. Hinterlegen Sie Schlüssel und Kennungen in der Geheimnisverwaltung des Teams. Erzeugen Sie zu Jobbeginn eine eingeschränkte Konfigurationsdatei und löschen Sie sie nach Jobende. Committen Sie weder Konfiguration noch privaten Schlüssel ins Repository.
  4. Hochladen und Verarbeitung prüfen. Führen Sie pilot aus und kontrollieren Sie App-Kennung und Upload-Ergebnis. Ein erfolgreicher Upload bedeutet noch nicht, dass die App für Tester freigegeben ist. Prüfen Sie auch die Verarbeitung und Verteilung.

Upload-Befehl für eine vorhandene IPA

fastlane pilot upload \
  --api_key_path "$ASC_API_KEY_JSON" \
  --ipa "$IPA_PATH" \
  --skip_waiting_for_build_processing true

ASC_API_KEY_JSON verweist auf eine temporäre API-Key-Konfiguration im Fastlane-Format; IPA_PATH auf die tatsächliche IPA-Datei. Mit Bundler setzen Sie bundle exec vor den Befehl.

Halten Sie App-Version, Buildnummer, Commit-Kennung und Upload-Ergebnis fest. Geben Sie weder den privaten Schlüssel noch vollständige Authentifizierungsdaten in Logs aus.

Uploads nach Fehlertyp prüfen

Prüfen Sie bei Authentifizierungsfehlern Key ID, Issuer ID, privaten Schlüssel und Rollenrechte. Bei einer doppelten Buildnummer ändern Sie die Buildnummer; eine erneute Runner-Einrichtung ist nicht nötig. Bei Fehlern mit Signierung oder App-Kennung gehen Sie zurück zum Archiv- und Exportschritt. Wenn Sie Build, Signierung und Upload getrennt abnehmen, müssen Sie bei einem Fehler nicht jedes Mal den gesamten Job von vorn ausführen.

Übergaben in der Pipeline dokumentieren

Der Server ist ganzjährig online – Ihre Jobs sollten trotzdem umziehbar sein

Der Server ist an 365 Tagen im Jahr online; es gibt keine geplanten Ausfallzeiten. Das Rechenzentrum kümmert sich um Stromversorgung, Netzwerk und Kühlung. Ihr Team verwaltet Projektabhängigkeiten, Schlüssel, Job-Konfiguration und Backups. Bei Hardwareproblemen ist eine Prüfung per Ticket erforderlich. Behandeln Sie einen einzelnen Server nicht als einzige, unwiederbringliche Kopie Ihrer Daten.

Wiederherstellbare Konfiguration dokumentieren

Halten Sie Runner-Labels, Werkzeugversionen, Namen der Umgebungsvariablen, Installationsschritte für Abhängigkeiten und den Import der Signierungsmaterialien fest. Mit automatisierten Skripten lässt sich die Umgebung zuverlässiger wiederherstellen als aus dem Gedächtnis.

Signierzertifikate und private Schlüssel sollten verschlüsselt gesichert werden. Sichern Sie Build-Artefakte und Logs im Team-Speicher. Ob Sie DerivedData und Abhängigkeits-Caches sichern, können Sie anhand der Kosten entscheiden – sie müssen aber neu erstellt werden können.

Abnahmecheckliste ansehen

Bei Problemen zuerst Belege sichern

Notieren Sie Serverkennung, Zeitpunkt und Zeitzone, den letzten erfolgreichen Job sowie eine Zusammenfassung des Fehlers. Halten Sie fest, ob SSH erreichbar ist, der Runner online ist und ein Job gestartet werden kann. „Build kaputt“ allein hilft bei der Fehlersuche nicht weiter.

Wenn Sie sich noch anmelden können, sichern Sie wichtige Daten und Logs, bevor Sie neue Jobs anhalten. Fügen Sie dem Ticket nur bereinigte Informationen bei. Falls Sie eine Freigabe zur Fehleranalyse erteilen, beschränken Sie deren Umfang. Senden Sie niemals private Schlüssel oder vollständige Passwörter.

Problem im Portal melden

Nach einem Serverwechsel erneut prüfen

Das Support-Team prüft den Fehler und bestätigt das weitere Vorgehen per Ticket. Wenn ein Serverwechsel nötig ist, aktualisieren Sie Adresse und Zugangsdaten anhand der neuen Bereitstellungsinformationen und prüfen Sie den Host-Fingerprint erneut.

Stellen Sie Abhängigkeiten und Signierungsmaterial wieder her, registrieren oder verknüpfen Sie den Runner neu und führen Sie einen minimalen Build aus. Sobald der neue Server Jobs ausführen kann, widerrufen Sie alte Zugangsdaten und nicht mehr verwendete Runner-Registrierungen.

Verbindung erneut prüfen

Legen Sie vor dem Bereinigen des Speichers fest, was aufbewahrt wird: Artefakte nach Release-Version, Logs gemäß den Audit-Vorgaben des Teams und Caches nach dem Prinzip der Wiederherstellbarkeit. Bereinigen Sie während eines laufenden Builds weder das Arbeitsverzeichnis noch ändern Sie den globalen Xcode-Pfad.

Abrechnung und Server gemeinsam übergeben

Gültigkeit vor dem Release prüfen – nicht auf die letzte Erinnerung warten

Ein Tag eignet sich für erste Tests oder kurzfristige Builds, eine Woche für konzentrierte Projektphasen. Ein Monat oder Quartal passt eher zu dauerhaft laufenden Nightly-Builds. Vergleichen Sie die Gesamtpreise für die jeweilige Laufzeit; der Tagessatz ist keine verlässliche Grundlage für ein langfristiges Budget.

Vor Änderungen an der Umgebung die Rahmenbedingungen klären

Sechs häufige Fragen zur Teamnutzung des Servers

Kann ich Homebrew und Projektabhängigkeiten installieren?

Sie können Entwicklungswerkzeuge und Projektabhängigkeiten wie auf einem üblichen macOS-Entwicklungsrechner verwalten. Prüfen Sie vor der Installation Architektur, Installationspfad und Berechtigungen und dokumentieren Sie Versionen und Schritte. Stellen Sie bei der ersten Einrichtung zunächst die vorhandenen Projektabhängigkeiten wieder her. Aktualisieren Sie nicht gleichzeitig alle Werkzeuge – sonst lässt sich schwer erkennen, ob ein Fehler vom Projekt oder einer geänderten Umgebung kommt.

Kann ich eine bestimmte Xcode-Version wählen?

Wählen Sie eine mit dem Projekt kompatible Version und prüfen Sie zunächst, was auf dem Server installiert ist. Klären Sie vor der Installation einer anderen Version Speicherplatz, Bezugsquelle und Projektanforderungen. Gehen Sie nicht davon aus, dass eine bestimmte Version bereits vorhanden ist. Wenn mehrere Jobs den Server nutzen, setzen Sie DEVELOPER_DIR möglichst im jeweiligen Job, damit ein globaler Wechsel andere laufende Aufgaben nicht beeinträchtigt.

Gibt es Root-Zugriff, und sollte der Runner als Root laufen?

Die grafische Oberfläche und die Kommandozeile von macOS stehen vollständig zur Verfügung. Welche Administrator- und sudo-Rechte verfügbar sind, geht aus den Zugangsdaten im Portal hervor. Benötigt die Installation zusätzliche Berechtigungen, klären Sie das zunächst per Ticket. Verwenden Sie Root nicht standardmäßig für die Verbindung und führen Sie gewöhnliche CI-Jobs nicht mit weitreichenden Berechtigungen aus. Trennen Sie Build, Schlüssel und Arbeitsverzeichnisse nach dem Prinzip der geringsten Rechte.

Kann ein Team den Server gemeinsam nutzen?

Sie können den dedizierten Server in Team-Workflows einbinden. Die physischen Ressourcen der Maschine werden dadurch jedoch nicht größer. Richten Sie separate Benutzer oder klar abgegrenzte Job-Einstiege ein, begrenzen Sie die Parallelität und vereinbaren Sie, wann die Umgebung geändert werden darf. Ihr Team ist selbst für Zugriffsrechte auf Builds und Signierung verantwortlich. Der Server ist keine isolierte Multi-Tenant-Umgebung.

Können andere Kunden meine Caches löschen?

Der gesamte Rechner ist einem Kunden zugewiesen; Build-Ressourcen werden nicht mit anderen Kunden geteilt. Caches können dennoch von den eigenen Bereinigungsskripten des Teams, der Speicherverwaltung oder Änderungen an der Umgebung betroffen sein. Betrachten Sie Caches als wiederherstellbare Beschleunigung. Sichern Sie Code, Signierungsmaterial und fertige Artefakte separat. Bei einem Serverwechsel sollten sich Abhängigkeiten anhand der Lockfiles erneut installieren lassen.

Welche Angaben gehören in ein Ticket, wenn die Einrichtung nicht weitergeht?

Geben Sie Serverkennung, CI-System, Commit-Kennung des betroffenen Jobs, Zeitpunkt und Zeitzone sowie bereinigte Logs rund um den ersten Fehler an. Beschreiben Sie, ob derselbe Befehl im interaktiven Terminal und im Runner gleich ausgeführt wird. Entfernen Sie Zugriffstokens, private Schlüssel, Passwörter und vertrauliche Projektangaben aus Pfaden. Benötigt das Support-Team weitere Informationen, stimmt es den Umfang des Zugriffs mit Ihnen im Ticket ab.

Testen Sie den Build-Server mit einem echten Job

Testen Sie zunächst für einen Tag und entscheiden Sie danach, ob Sie Nightly-Builds dauerhaft darüber ausführen möchten. Port M4 Base ab $19.7/Tag. Dokumentieren Sie Commit-Kennung, Build-Logs und Artefakte, damit Ihre eigenen Projekte die Grundlage für die Wahl bilden.

iOS-Build-Server mieten Im Portal Ticket erstellen