Ihre erste iOS-Build-Pipeline zum Laufen bringen

Falls xcodes auf dem Host noch nicht installiert ist, richten Sie das Tool nach dem von Ihrem Team freigegebenen Softwareprozess ein. Verwenden Sie für die Installation einer bestimmten Version ein rechtmäßig bezogenes lokales Xcode-Installationspaket, das den Projektanforderungen entspricht. XCODE_VERSION und XCODE_XIP stehen im folgenden Beispiel für die geprüfte Versionsnummer und den absoluten Pfad zum Installationspaket. Interaktive Installationsschritte gehören nicht in unbeaufsichtigte Build-Jobs.

XCODE_APP muss auf den tatsächlichen Pfad der installierten App zeigen. Setzen Sie für CI bevorzugt DEVELOPER_DIR in der Job-Umgebung, damit mehrere Jobs nicht um die systemweite Auswahl konkurrieren. Wenn Sie die systemweite Standard-Toolchain ändern müssen, führen Sie sudo xcode-select --switch "$XCODE_APP/Contents/Developer" aus und prüfen Sie anschließend erneut xcodebuild -version.

Starten Sie die ausgewählte Xcode-Version zum ersten Mal und schließen Sie die erforderliche Komponenteneinrichtung ab. Die grafische Oberfläche erreichen Sie über eine Fernverbindung. Installieren Sie anschließend in den Komponenteneinstellungen von Xcode die benötigte Runtime. Führen Sie xcrun simctl list devices available aus und wählen Sie einen Simulator, der zum Testziel passt. Starten Sie ihn zunächst einmal interaktiv und warten Sie, bis er vollständig hochgefahren ist, bevor Sie einen kleinen Testjob ausführen. Das Archivieren für ein echtes Gerät und das Ausführen von Simulator-Tests sind getrennte Schritte. Eine fehlende Runtime ist kein Fehler der Archivierungs-Toolchain.

Geben Sie die Toolchain-Prüfung am Anfang des CI-Logs aus: mindestens die Xcode-Version, die SDK-Liste und den Commit-Hash. Erstellen Sie nach einem Xcode-Wechsel neue Cache-Schlüssel und prüfen Sie Drittanbieter-Abhängigkeiten, Signierung und Export. Nur das Runner-Tag zu ändern, ohne den tatsächlich verwendeten Toolpfad zu prüfen, garantiert keine einheitliche Build-Umgebung.

GitLab Runner: Tags und Executor gemeinsam prüfen

Erstellen Sie in den Runner-Einstellungen des Projekts einen Projekt-Runner, richten Sie das zugehörige Authentifizierungs-Token ein und vergeben Sie die drei Tags macos, arm64 und ios-archive. Hinterlegen Sie die Instanzadresse und das Authentifizierungs-Token vorübergehend in GITLAB_URL und GITLAB_RUNNER_TOKEN. Registrieren Sie unter einem dedizierten Build-Benutzer einen Shell-Executor. Entfernen Sie anschließend die temporäre Token-Variable.

Hinterlegen Sie die tatsächlichen Werte für IOS_WORKSPACE und IOS_SCHEME in den Projektvariablen und richten Sie zuerst die Signierung wie im nächsten Abschnitt beschrieben ein. Dieses Beispiel erstellt nur ein Archiv; Export und Upload sind nicht enthalten. Die Aufbewahrung der Build-Artefakte für 7 Tage ist ein Beispiel und kann an die Richtlinien Ihres Teams angepasst werden. Zertifikate, private Schlüssel und temporäre Keychains gehören nicht in Artefakte.

GitHub Actions: Ein Runner-Prozess pro Job

Laden Sie über die Installationsanweisungen des Repositorys die passende Runner-Anwendung für macOS ARM64 herunter und wechseln Sie in das entpackte Verzeichnis. Setzen Sie REPOSITORY_URL auf die Adresse des aktuellen Repositorys und RUNNER_TOKEN auf das Token für diese Registrierung. Die Tags müssen sowohl in der Runner-Konfiguration als auch im Workflow vorkommen, damit Jobs der richtigen Toolchain zugewiesen werden.

Hinterlegen Sie zuerst Toolpfad, Workspace und Scheme als Repository-Variablen. Das Beispiel wird manuell gestartet, damit Sie die Umgebung zunächst prüfen können. Stellen Sie Runner mit Signaturzugangsdaten nicht für nicht vertrauenswürdigen externen Code bereit. Ein Runner-Prozess führt jeweils einen Job aus; concurrency begrenzt zusätzlich die Ausführung von Workflows derselben Gruppe, aber nicht die Ressourcennutzung des Hosts.

Nach erfolgreicher Prüfung konfigurieren Sie den dauerhaften Betrieb anhand des mitgelieferten Dienstskripts und stellen Sie sicher, dass der Dienst unter demselben Benutzer läuft, mit dem Sie manuell getestet haben. Wenn Sie die Signierung für einen Benutzer einrichten, der Dienst aber unter einem anderen läuft, ist ein häufiges Ergebnis, dass interaktive Builds funktionieren, CI jedoch Zertifikat oder Bereitstellungsprofil nicht findet.

Verwenden Sie für automatisierte Jobs eine separate Build-Keychain. Das Passwort wird über eine geschützte CI-Geheimvariable bereitgestellt. Erlauben Sie nach dem Import des Zertifikats nur den tatsächlich benötigten Signierungstools den Zugriff. Gewähren Sie nicht allen Apps Zugriff auf den privaten Schlüssel. Die folgenden Prüfungen zeigen, ob der aktuelle Benutzer eine gültige Signierungsidentität sieht. Sie bestätigen nicht, dass Bereitstellungsprofil, Exportoptionen und Projekteinstellungen vollständig übereinstimmen.

Der Speicherort von Bereitstellungsprofilen kann je nach Xcode-Version variieren. Maßgeblich ist der Pfad, den die verwendete Toolchain tatsächlich ausliest. Prüfen Sie nach dem Import Gültigkeitsdauer, App-ID und Signierungstyp. Wenn die Archivierung funktioniert, der Export aber fehlschlägt, gleichen Sie die Exportmethode, Team-ID und Zuordnung der Bereitstellungsprofile ab, statt Xcode wiederholt neu zu installieren.

Wenn Ihr Team fastlane match bereits nutzt, halten Sie sich an das vorhandene verschlüsselte Zertifikats-Repository und die Zugriffsrichtlinien. Verwenden Sie zur Prüfung bundle exec fastlane match appstore --readonly, um zunächst vorhandenes Signierungsmaterial zu laden und unbeabsichtigte Änderungen an Teamzertifikaten durch den Build-Host zu vermeiden. Zugangsdaten für das Repository, Entschlüsselungspasswort und Keychain-Passwort müssen getrennt verwaltet werden. Produktive Signierungsvariablen dürfen nur geschützten Branches oder kontrollierten manuellen Jobs zur Verfügung stehen.

Entfernen Sie nach einem Job temporäre Dateien und sperren Sie die temporäre Keychain. Protokollieren Sie nur notwendige Fehlercodes und Ergebnisse der einzelnen Schritte. Private Schlüssel, Zertifikatspasswörter, Registrierungstoken und vollständige Geheimvariablen dürfen nicht im Log erscheinen. Ein dedizierter physischer Mac bietet Ressourcentrennung; die Berechtigungen für Zugangsdaten im Projekt sollten dennoch nach dem Prinzip der geringsten Rechte vergeben werden.

Führen Sie diskutil list und df -h aus, um Kapazität und Einhängepunkte zu prüfen. Löschen oder partitionieren Sie keine unbekannten Datenträger. Erstellen Sie für den Build-Benutzer ein Cache-Verzeichnis mit Schreibberechtigung und testen Sie Lese- und Schreibzugriff mit einer kleinen Datei. Nachdem Sie das Verhalten beim Neustart geprüft haben, können Sie den dauerhaft laufenden Runner auf den neuen Pfad umstellen.

Stoppen Sie vor der Migration die Annahme neuer Jobs und warten Sie, bis laufende Archivierungs- und Signierungsjobs abgeschlossen sind. DerivedData ist ein wiederherstellbarer Cache. Erstellen Sie den Cache vorzugsweise am neuen Speicherort neu, statt einen möglicherweise gerade beschriebenen alten Cache zu kopieren. Mit -derivedDataPath legen Sie den Pfad gezielt fest; das gesamte Benutzerverzeichnis muss nicht auf das zusätzliche Volume verschoben werden.

Setzen Sie BUILD_VOLUME vor dem Ausführen auf ein geprüftes, beschreibbares Einhängeverzeichnis. CACHE_KEY sollte Repository, Xcode-Version und Build-Konfiguration unterscheiden. Verwenden Sie für BUILD_ID eine eindeutige Kennung des aktuellen Jobs, damit sich verschiedene Jobs nicht gegenseitig überschreiben. Jobs, die parallel laufen, dürfen nicht dasselbe beschreibbare DerivedData-Verzeichnis verwenden.

Führen Sie zunächst einen Build ohne Cache aus und beobachten Sie anschließend Cache-Treffer und Speicherverbrauch. Legen Sie getrennte Aufbewahrungsregeln für Archive, Simulator-Daten und Abhängigkeits-Caches fest. Vergewissern Sie sich vor dem Löschen, dass kein Job die Daten noch verwendet. Build-Artefakte sollten zusätzlich in einem vom Team verwalteten Artefaktspeicher gesichert werden. Der Cache auf dem Host ist kein Ersatz für ein Backup. Exportieren Sie vor Ende der Mietdauer Ihre Daten und prüfen Sie, ob das Backup lesbar ist.