iOS Builds

Build and submit iOS apps to TestFlight und dem App Store mithilfe von Capgo's dedizierter Mac-Infrastruktur.

Was Sie lernen werden

• Sie werden erfahren, wie Sie Ihre App über Capgo eine native Build hochladen können.
• Sie werden erfahren, wie Sie die Zertifikate für Capgo Native Build konfigurieren können.

Voraussetzungen

• Ein Capgo-Konto (ein kostenloses Probeabo reicht aus, um loszulegen)
• Ihre App ist bereits in Capgo registriert (führen Sie) bunx @capgo/cli@latest app add wenn nicht
• Ein Mac-Computer mit Xcode installiert (es ist möglich, die Build-Einstellungen auf einem Linux-/Windows-Computer zu konfigurieren, aber dies ist noch nicht dokumentiert)
• Ein gültiges Apple-Entwicklerkonto (99 $/Jahr) (Sie müssen über Admin- oder Eigentümerrechte auf dem Apple-Entwicklerkonto verfügen)
• Ihre App muss erfolgreich über Xcode gebaut werden können
• Eine Capacitor-App
• Eine konfigurierte App-Icon. Apps ohne Icon können nicht im App Store hochgeladen werden.

Hinweis

Für diese Anleitung werde ich die folgende App verwenden: https://github.com/Cap-go/capgo-native-build-tutorial-app

Bevor Sie in Apples Portalen beginnen

Bevor Sie Zertifikate einrichten oder Ihre erste TestFlight-Upload auslösen, stellen Sie sicher, dass das Apple-Konto und die Team-Struktur bereit sind:

• Zwei-Faktor-Authentifizierung für das Apple-Konto aktivieren, das für die Registrierung verwendet wird
• Wählen Sie die richtige Mitgliedschaftsart:
  • Einzelperson / Einzelunternehmen: Ihr persönlicher Name wird zum Verkäufernamen im App Store
  • Organisation: Erfordert eine juristische Person, eine D-U-N-S-Nummer, eine öffentliche Unternehmenswebsite, eine E-Mail-Adresse auf der Unternehmensdomain und eine Person mit der Befugnis, die Organisation zu Apple’s Vereinbarungen zu binden
• Benutzen Sie ein Konto, das Zugriff auf beide Apple Developer und App Store Connect für Zertifikate, App-Records, API-Schlüssel und TestFlight hat
• Legen Sie Ihren finalen Bundle-Id frühzeitig fest. Ändern Sie ihn später, wenn möglich, um die App Store-Einrichtung nicht wiederholen zu müssen
• Planen Sie diese App Store Connect-Elemente vor der App-Überprüfung: Unterstützungs-URL, Datenschutzrichtlinien-URL, Altersfreigabe, Screenshot, Export-Kompliance und Kontaktdaten für die App-Überprüfung

Hinweis

Zu empfehlende offizielle Referenzen:

• Stellen Sie sich dem Apple Developer Programm bei
• Stellen Sie Ihre Apps und Spiele ein
• Plattformversioneninformationen in App Store Connect

Vorsicht

Apple aktualisiert regelmäßig seine Mindestanforderungen an SDK. Stand vom 28. April 2026iPhone- und iPad-Anwendungen, die in App Store Connect hochgeladen werden, müssen mit der iOS & iPadOS 26 SDK oder höher.

Empfohlen: automatisierte Einrichtung

Sie müssen nichts davon selbstständig durchführen. Capgo erstellt und konfiguriert Ihre iOS-Zertifikate (Distributionszertifikat + Verteilungsprofil) für Sie — dies ist die empfohlene Route:

bunx @capgo/cli@latest build init --platform ios

Die folgende manuelle Anleitung ist nur für diejenigen gedacht, die ihre Zertifikate selbst einrichten möchten oder genau wissen möchten, was Capgo unter der Haube macht.

Die erste manuelle Erstellung

Bevor wir mit der Erstellung der App mit Capgo beginnen können, sollten wir sie zunächst einrichten und eine erste Testflug-Erstellung durchführen.

• Es gibt einige Vorteile darin, eine manuelle Erstellung vorzunehmen:
• Sie werden das Distributionszertifikat auf Ihrem lokalen Rechner einrichten
• You will be able to figure out any issues with the build process linked to your app code

Sie werden in der Lage sein, Probleme im Build-Prozess zu erkennen, die mit Ihrer App __CAPGO_KEEP_0__ zusammenhängen

Die Verteilungszertifizierung einrichten

1. Xcode öffnen

2. Klicken Sie auf Xcode -> Settings... Alternativ können Sie den Kurzbefehl verwenden Cmd + ,

   

3. Zu Accounts

4. Finden Sie das Apple-Konto, das der Apple-Entwicklerkonto hinzugefügt wurde

5. Finden Sie das Team, das Sie zum Bereitstellen der App verwenden werden

6. Klicken Sie auf den Manage Certificates... Button

7. Stellen Sie sicher, dass Sie das Verteilungszertifikat in der Liste sehen können

8. Wenn Sie dies nicht sehen, müssen Sie ein neues Zertifikat erstellen

   Hinweis

   Apple beschränkt die Anzahl der Verteilungszertifikate, die Sie haben können, auf 3. Wenn Sie mehr als 3 Zertifikate haben, müssen Sie eines löschen, um ein neues zu erstellen. Dies werde ich in der Anleitung nicht behandeln.

   1. Klicken Sie auf den + Button und dann auf Apple Distribution
   2. Das Zertifikat wird automatisch erstellt. Sie können es in der Liste sehen. Schauen Sie sich den vorherigen Schritt an, um sicherzustellen, dass Sie es sehen.

Nachdem Sie das Verteilungs-Zertifikat installiert haben, können Sie den Build-Prozess beginnen.

Manueller Build zu TestFlight

1. Öffnen Sie die App in Xcode

   Ausführen bunx cap open ios um die App in Xcode zu öffnen.

2. Finden und klicken Sie auf den archive Schaltfläche

   In der Xcode-Leiste finden und klicken Sie auf die product -> archive Schaltfläche.

   

3. Warten Sie, bis der Build abgeschlossen ist

4. Klicken Sie auf den Distribute App Schaltfläche

   

5. Wählen Sie TestFlight Internal Only als Verteilungsverfahren und klicken Sie auf Distribute Schaltfläche

   

6. Konfigurieren Sie das App-Record

   Füllen Sie die folgenden Felder aus:

   1. Name: Der Name Ihrer App - sichtbar im App Store
   2. SKU - die SKU Ihrer App - diese wird verwendet, um Ihre App im App Store zu identifizieren
   3. Die primäre Sprache - die primäre Sprache Ihrer App

   Klicken Sie dann auf den next button

   

7. Wenn die Erstellung des App-Protokolls fehlschlägt, versuchen Sie, das Fenster zu schließen und das Archivieren der App erneut zu versuchen.

8. Warten Sie, bis der Upload abgeschlossen ist

9. Wenn alles gut ging, sollten Sie die folgende Seite sehen

10. Klicken Sie auf den Done button

Sie denken vielleicht instinktiv, dass alles in Ordnung ist und dass Sie Ihre App in TestFlight jetzt sehen können, aber es gibt noch ein paar Dinge, die noch zu beenden sind:

1. Fügen Sie sich selbst zu TestFlight hinzu
2. Die Exportkonzessionen erfüllen, damit das Build testbar wird
3. Die erforderlichen App Store Connect-Metadaten wie Ihre Support-URL, Ihre Datenschutzrichtlinie-URL und Ihre Altersstufeneinstellung einfüllen
4. Vorbereiten Sie Screenshots, die den von Ihnen tatsächlich unterstützten Geräten entsprechen
5. App Review-Kontaktinformationen und alle Testanmeldeinformationen vor der Produktionsabgabe hinzufügen

Beginnen wir mit dem ersten:

Sich selbst bei TestFlight hinzufügen

1. Gehe zur App Store Connect-Seite App Store Connect-Anmeldeseite

2. Sign in with your Apple Developer account

3. Wählen Sie das Team, das Sie verwendet haben, als Sie das Anwendungsprotokoll erstellt haben. Wenn Sie nur in einem Entwicklerkonto sind, können Sie diesen Schritt überspringen.

4. Klicken Sie auf den Apps Button

5. Finden Sie die Anwendung, die Sie im vorherigen Schritt erstellt haben, und klicken Sie darauf

6. Klicken Sie auf den TestFlight Button

7. Klicken Sie auf den Internal Testers plus Button

8. Eine neue Gruppe erstellen

   Ich bevorzuge es, der Gruppe den Namen „interne Tester“ zu geben. Du kannst sie jedoch nennen, wie du willst.

   

9. Klicken Sie auf Invite testers Schaltfläche

10. Fügen Sie sich der Gruppe hinzu

    Suchen Sie sich selbst in der Liste und wählen Sie das Häkchen neben Ihrem Namen aus. (Sie müssen sich möglicherweise neu einloggen, um sich selbst zu sehen) Dann klicken Sie auf die Add Schaltfläche.

    

11. Überprüfen Sie, ob Sie der Gruppe beigetreten sind

    Jetzt solltest du dich selbst im Gruppe sehen.

    

Herzlichen Glückwunsch 🎉 Du hast dich selbst in TestFlight hinzugefügt. Jetzt gibt es noch etwas, das du tun musst, bevor du Capgo Native Build konfigurieren kannst.

Die Einrichtung der Compliance-Informationen

Du musst nun Apple versprechen, dass deine App keine nicht standardmäßige (wie ein benutzerdefinierter Algorithmus) Verschlüsselung verwendet. Wenn deine App tatsächlich nicht standardmäßige Verschlüsselung verwendet, empfehle ich dir, die Dokumentation von Apple zu lesen, um dies zu handhaben. Es gibt zwei Möglichkeiten, dies zu tun:

1. Du kannst dies jede Zeit, wenn du deine App bauen musst, manuell tun.
2. Du kannst deine plist-Datei konfigurieren, um diese Werte automatisch auf false.

Lass uns mit der ersten beginnen:

1. Folge allen Schritten aus der vorherigen Abschnitt, um die TestFlight-Sektion in App Store Connect zu finden

2. Klicken Sie auf Builds -> iOS

3. Finden Sie den Build, der fehlende Compliance-Informationen enthält und klicken Sie auf Manage

4. Wählen Sie die Option, die Ihre App am besten beschreibt

   Für mich ist das none, aber es könnte für Sie anders sein. Anschließend klicken Sie auf Speichern

   

5. Ihre App sollte jetzt sagen ready to test

   

Was die zweite Option betrifft, hier sind die Schritte:

1. Öffnen Sie das Info.plist Datei

2. Fügen Sie die folgende Schlüsselzeile hinzu:

   <key>ITSAppUsesNonExemptEncryption</key>
   <false/>

3. Die Datei speichern

Hinweis

Hier ist die offizielle Apple-Dokumentation zur Information von Apple über die Einhaltung von Verschlüsselungsexportregulierungen.

Die TestFlight-App installieren und die Einladung akzeptieren

Jetzt bist du Fast Ihr App ist bereit, in TestFlight zu testen. Bevor Sie beginnen, müssen Sie die folgenden Schritte ausführen:

1. Die TestFlight App herunterladen
2. von der App Store auf Ihrem iOS/iPadOS-Gerät

Die Einladung zu Ihrer App akzeptieren

Ich werde die Details, wie Sie die TestFlight App auf Ihrem Gerät installieren, überspringen. Wenn Sie sich nicht sicher sind, wie Sie eine App installieren, finden Sie auf Google einige großartige Anleitungen, um es zu tun.

1. Wenn es um die Annahme der Einladung geht, erhalten Sie eine E-Mail von Apple mit einem Link, um die Einladung anzunehmen.

2. Die E-Mail von Apple mit dem Link, um die Einladung anzunehmen, öffnen View in TestFlight Auf

3. TestFlight-E-Mail-Button Install Schaltfläche

4. Die App auf Ihrem Gerät installieren

   Wenn Sie die App zuvor mit Xcode installiert haben, sehen Sie möglicherweise die folgende Seite. Bitte klicken Sie auf die install Schaltfläche.

5. Warten Sie, bis die App installiert ist

6. Klicken Sie auf die Open Schaltfläche und klicken Sie darauf

Glückwunsch 🎉 Sie haben die Einladung zum Testen Ihrer App in TestFlight angenommen. Jetzt können Sie Capgo Native Build konfigurieren, um Ihre App in TestFlight zu bauen und zu übermitteln.

Konfigurieren Sie Capgo Native Build

There are a few things you need to configure in Capgo Native Build to be able to build and submit your app to TestFlight. Here is a list of the things you will pass to the Capgo CLI:

Hier ist eine Liste der Dinge, die Sie an den __CAPGO_KEEP_1__ __CAPGO_KEEP_2__ übergeben werden:	Plattform
--platform	Beschreibungios)
--apple-team-id	Die zu bauende Plattform ( Ihre Apple-Entwickler-Team-ID (im)
--apple-key	Path to your App Store Connect API Key file (.p8 Pfad zu Ihrem App Store Connect __CAPGO_KEEP_0__-Sicherheitszertifikat (
--apple-key-id	The Key ID of your App Store Connect API Key
--apple-issuer-id	Die Key-ID Ihres App Store Connect __CAPGO_KEEP_0__-Sicherheitszertifikats
--certificate	Ihre App Store Connect Aussteller-ID.p12 Pfad zu Ihrem Verteilungszertifikat (
--ios-provisioning-profile	Profilzuweisungsmappe (bundleId=path oder einfach Pfad für einzelnes Profil

Beispiel-Befehl:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile '/path/to/profile.mobileprovision'

Team-ID

Lassen Sie uns mit der Team-ID beginnen. Sie ist ziemlich leicht zu finden.

1. Gehe zu Apple-Entwicklerkonto und scrollen Sie nach unten

2. Finden Sie das Team ID

   

Apple-Schlüssel, Apple-Schlüssel-ID und Apple-Aussteller-ID

Zum Apple-Schlüssel wechseln

macOS: Lassen Sie Capgo diesen Schlüssel für Sie erstellen

Auf macOS können Sie capgo build init dieses App Store Connect API-Schlüssel für Sie erstellen. Wählen Sie “Nein — erstelle einen für mich” und ein interaktives Fenster öffnet sich in App Store Connect, führt Sie durch jeden Schritt und fängt den Schlüssel, die Schlüssel-ID und die Aussteller-ID automatisch ein — kein Kopieren und Einfügen. Die unten aufgeführten manuellen Schritte sind die Alternative (und der Weg auf Windows oder Linux).

1. Zum App Store Connect-Benutzer- und Zugriffsbereich wechseln Go to App Store Connect user and access page

   Hinweis

   Für mich funktioniert der Link manchmal nicht. Lade die Seite neu, wenn es auch bei Ihnen nicht funktioniert.

2. Wählen Sie die richtige Mannschaft aus dem Dropdown-Menü

   1. Klicken Sie auf Ihren Namen in der oberen rechten Ecke
   2. Klicken Sie auf die

3. Apple Developer-Schlüssel-Mannschafts-Auswahl Integrations Klicken Sie auf die

4. App Store Connect-Integrationen-Button issuer

   Achtung

   Dies IST ZU SPEICHERN - Sie werden es später benötigen

   Klicken Sie auf den copy Button um den Herausgeber zu kopieren

5. Klicken Sie auf den Plus-Button

6. Legen Sie den Namen des Schlüssels und legen Sie den Zugriff fest App manager und klicken Sie auf den Generate Button

7. Sparen Sie die Schlüssel-ID

   Vorsicht

   Dies WIRD ZU SPEICHERN SEIN - Sie benötigen es später

   

8. Herunterladen Sie den Schlüssel

   Vorsicht

   Dies IST ZU SPEICHERN - Sie werden es später benötigen

   Gefahr

   TEILE DEN SCHLÜSSEL NICHT MIT JEDERMANN - BENUTZE IHNEN NICHT AUSSENHALB DES CAPGO CLI

   

   

Herzlichen Glückwunsch 🎉 Sie haben den Apple-Schlüssel, den Apple-Key-ID und die Apple-Issuer-ID erstellt.

Zertifikat

Jetzt sind Sie bereit, das Zertifikat auszuführen. Wie Sie sich erinnern, war eine der ersten Schritte dieser Anleitung die Einrichtung des Verteilungs-Zertifikats.

Allerdings hat Apple in ihrer unendlichen Weisheit entschieden, dass die Art und Weise, wie Sie das Zertifikat exportieren, sich erheblich von der Art und Weise unterscheidet, wie Sie sie erstellen 🙃 Lassen Sie uns nun die Einrichtung durchführen:

1. Öffnen Sie das Keychain-Access

   1. Klicken Sie Command + Space um die Suchleiste zu öffnen
   2. Suchen Sie nach Keychain Access
   3. Klicken Sie auf das Keychain Access Anwendungsprogramm

2. Wählen Sie die login Kategorie und klicken Sie auf den My Certificates Button

3. Finden Sie Ihr Zertifikat in der Liste

   Der Zertifikat sollte benannt werden Apple Distribution: [Your Name/Company] (your team ID)

4. Klicken Sie mit der rechten Maustaste auf das Zertifikat und wählen Sie Export

5. Speichern Sie das Zertifikat als ein .p12 Datei

   Vorsicht

   Dies MUSSEN SIE SICH ERHALTEN - Sie werden es später benötigen

   1. Stellen Sie sicher, dass Sie einen guten Namen für das Zertifikat-Datei auswählen
   2. Stellen Sie sicher, dass das Dateiformat auf Personal Information Exchange (.p12)
   3. Klicken Sie auf den Save Schaltfläche

   

6. Wenn Sie nach dem Passwort gefragt werden, können Sie entweder:

   • Das Passwort überspringen (empfohlen für Einfachheit): Klicken Sie OK ohne Passwort einzugeben
   • Ein Passwort setzen: Wenn Sie Ihr Zertifikat mit einem Passwort schützen möchten, können Sie eines hier einstellen. Zertifikate mit Passwort sind vollständig von der __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ unterstützt – geben Sie einfach das Passwort mit der .p12 files are fully supported by the Capgo CLI - just provide the password using the --p12-password Keychain Access-Sicherheitszertifikatspeicher-Passwortdialog

   

7. Klicken Sie auf die

   Gebe das Passwort ein, das du zum Anmelden deines Macs verwendest. Klicke dann auf den Allow Schaltfläche.

   

Herzlichen Glückwunsch 🎉 Du hast das Zertifikat exportiert.

Provisionierungsprofil

Jetzt bist du bereit, das Provisionierungsprofil zu exportieren. Ich verspreche dir, das ist das letzte, was du von Apple benötigst.

1. Zu Apple-Entwickler-Profil

2. Wähle das richtige Team aus dem Dropdown-Menü

   1. Klicke auf deinen Namen in der oberen rechten Ecke
   2. Klicke auf das Team, das du verwenden möchtest

3. Stellen Sie sicher, dass Sie sich auf der richtigen Seite befinden Es sollte wie folgt aussehen, wenn es nicht so ist, klicken Sie auf profiles in der Seitenleiste

   

4. Klicken Sie auf den + Button

5. Wählen Sie das Profiltyp Wählen Sie App Store Connect und klicken Sie auf den Continue Button

   

6. Wählen Sie das App, das Sie bauen möchten

   Finden Sie Ihre App im Dropdown-Menü und klicken Sie auf den Continue __CAPGO_KEEP_0__

   

7. Wählen Sie das richtige Verteilungs-Zertifikat

   Wählen Sie das Zertifikat, das Sie im vorherigen Schritt exportiert haben, und klicken Sie auf den Continue __CAPGO_KEEP_0__

   

   Wenn Sie unsicher sind, welches Zertifikat auswählen sollen, kommen Sie zurück zu Keychain Access und finden Sie das Zertifikat, das Sie exportiert haben. Dann sehen Sie sich die Ablaufdatum an.

   

8. Benennen Sie das Profil

   Geben Sie dem Profil einen Namen und klicken Sie auf den Generate __CAPGO_KEEP_0__

   Tip

   Der Profilname wird automatisch durch den Capgo CLI extrahiert — Sie müssen es nicht merken.

   

9. Das Profil herunterladen

   Klicken Sie auf den Download Button zum Herunterladen des Profils

   Vorsicht

   Dieser Datei MUSS GESPEICHERT WERDEN - Sie benötigen es später

   

Herzlichen Glückwunsch 🎉 Sie haben jetzt alles, was Sie benötigen, um Capgo Native Build zu konfigurieren.

Vorsicht

Kommunizieren Sie die von Ihnen erstellten Anmeldeinformationen nie in Ihrem Repository. Halten Sie sie sicher! 🔒

Ausführen der Konfigurationskommando

Sie haben es geschafft! Sie haben jetzt alles, was Sie benötigen, um Capgo Native Build zu konfigurieren.

Das Kommando, das Sie ausführen müssen, ist:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id UVTJ336J2D \
  --apple-key ./capgo-tutorial/AuthKey_66FGQZB566.p8 \
  --apple-key-id 66FGQZB566 \
  --apple-issuer-id 0cd4db4a-5598-45b8-9d32-75cdf127d005 \
  --certificate ./capgo-tutorial/capgo-build-tutorial-certificate.p12 \
  --ios-provisioning-profile ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision

Ersetzen Sie die Platzhalterwerte

Ersetzen Sie die oben stehenden Platzhalterwerte mit Ihren tatsächlichen Anmeldeinformationen, die Sie in den vorherigen Schritten gesammelt haben:

• --apple-team-id: Ihre Apple-Team-ID
• --apple-key: Pfad zu Ihrem heruntergeladenen .p8 Sicherheitszertifikat
• --apple-key-id: Ihre Apple-Schlüssel-ID
• --apple-issuer-id: Ihre Apple-Issuer-ID
• --certificate: Pfad zu Ihrem exportierten .p12 Zertifikat
• --ios-provisioning-profile: Pfad zu Ihrem heruntergeladenen .mobileprovision Datei (Bundle-ID wird für einzelne Profile automatisch ermittelt)

: Alle Schritte sind erfolgreich verlaufen, Sie sehen folgendes Ausgabe:

Apple-Authentifizierung fehlgeschlagen? Synchronisiere deinen Zeitstrahl

Wenn der App Store Connect API-Schlüssel korrekt aussieht, aber die Authentifizierung immer noch fehlschlägt, synchronisiere deinen Computer-Zeitstrahl und versuche es erneut. Capgo signiert Apples JWT mit deiner lokalen Systemzeit, und Apple lehnt Token ab, die mehr als 20 Minuten in der Zukunft ablaufen. Ein Zeitstrahl, der nur wenige Sekunden aus der Synchronisation ist, kann ausreichen, um diesen Schritt zu scheitern.

Siehe das Troubleshooting-Leitfaden für den Builder für Schritte zur Zeitstrahlsynchronisierung.

CI/CD-Einrichtung (GitHub Actions)

Wenn du bereits Team-ID, Apple-Schlüssel, Apple-Schlüssel-ID und Apple-Aussteller-ID, Zertifikat, und Provisionierungsprofil, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

In dieser Abschnitt wird nur beschrieben, wie Sie diese Werte als __CAPGO_KEEP_0__ Actions-Secrets und Umgebungsvariablen übergeben.

# Distribution certificate (.p12)
base64 -i ./capgo-tutorial/capgo-build-tutorial-certificate.p12 | tr -d '\n' > certificate_base64.txt

# Provisioning profile (.mobileprovision)
base64 -i ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision | tr -d '\n' > profile_base64.txt

# App Store Connect API key (.p8)
base64 -i ./capgo-tutorial/AuthKey_66FGQZB566.p8 | tr -d '\n' > apple_key_base64.txt

Tipps

GitHub secrets should be single-line values. tr -d '\n' __CAPGO_KEEP_0__-Geheimnisse sollten einzelne Zeilenwerte sein.

2) Repository-Secrets erstellen

In GitHub > Repository > Settings > Secrets and variables > Actions, add:

hinzufügen:	Geheimer Name
CAPGO_TOKEN	Your Capgo API token
APP_STORE_CONNECT_TEAM_ID	Ihr __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ Token Team-ID aus
APPLE_KEY_ID	Team-ID Schlüssel-ID aus
APPLE_ISSUER_ID	Apple-Schlüssel, Apple-Schlüssel-ID und Apple-Aussteller-ID aus Apple-Schlüssel, Apple-Schlüssel-ID und Apple-Aussteller-ID
BUILD_CERTIFICATE_BASE64	Inhalt von certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Durch CLI generiert — aus CLI kopiert .capgo-credentials Datei
APPLE_KEY_CONTENT	Inhalt von apple_key_base64.txt
P12_PASSWORD (optional)	Ihr Passwort, wenn während der Export gesetzt .p12 3) Verwenden Sie Umgebungsvariablen in Ihrem __CAPGO_KEEP_0__ Actions-Workflow

Abschnitt mit dem Titel „3) Verwenden Sie Umgebungsvariablen in Ihrem GitHub Actions-Workflow“

.github/workflows/ios-build.yml

name: iOS Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  ios-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS build with Capgo
        run: bunx @capgo/cli@latest build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}

Tip

Mit dieser Konfiguration sendet CI die Anmeldeinformationen nur über Umgebungsvariablen. Sie müssen keine Signierungsdateien committen oder als Workflow-Artikel hochladen.

Running the build

Jetzt bist du bereit, deine erste Build auszuführen.

Führe den folgenden Befehl aus, um deine App zu bauen:

bunx @capgo/cli@latest build request --platform ios

Glückwunsch 🎉 Du hast deine App erfolgreich gebaut und sie ist bereit, zur App Store-Überprüfung eingereicht zu werden.

Zur App Store-Überprüfung einreichen

The normale App Store-Build-Pfad lädt das Build in App Store Connect/TestFlight hoch. Wenn Ihre CI-Release auch das bearbeitete TestFlight-Build zum App Store-Veröffentlichung und zur App-Review einreichen soll, geben Sie --submit-to-store-review mit einem Release-Build:

npx @capgo/cli@latest build request com.example.app \
  --platform ios \
  --build-mode release \
  --ios-distribution app_store \
  --submit-to-store-review \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales" \
  --no-ios-automatic-release

Dies erfordert App Store Connect API-Sicherheitszertifikate (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, und APP_STORE_CONNECT_TEAM_ID). App-spezifische Passwörter und ad_hoc Verteilung können kein Build zur Review einreichen. --store-release-name ist die App Store-Version; wenn weggelassen, Capgo liest MARKETING_VERSION aus dem Xcode-Projekt. --store-release-notes ist die App Store-Fallback-What’s New-Tex, und jeder --store-release-notes-locale "locale=notes" Eintrag kann es für eine Store-Localisierung überschreiben. Verwenden Sie --ios-automatic-release zum automatischen Release nach Apple-Zustimmung oder --no-ios-automatic-release zum manuellen Release zu warten. --ios-testflight-groups ist weiterhin für externe Beta-Distribution verfügbar, aber nicht erforderlich für die Einreichung bei der App Store-Bewertung.

Ad-Hoc-Verteilungsmodus

Standardmäßig erstellt Capgo iOS-Anwendungen für die App Store-Verteilung (TestFlight + App Store). Wenn Sie stattdessen ad-hoc-gebaute Anwendungen benötigen (für interne Tests oder CI-Artikel-Sammlung), können Sie die --ios-distribution Flagge verwenden.

Hinweis

Ad-hoc-Verteilung ist nicht die gleiche wie Enterprise (In-House)-Verteilung. Enterprise-Verteilung erfordert ein separates Apple-Entwickler-Enterprise-Konto und verwendet unterschiedliche Bereitstellungsprofile. Capgo unterstützt derzeit app_store und ad_hoc nur in diesen Modi.

Wenn Sie den Ad-hoc-Modus verwenden sollen

• Sie möchten IPAs direkt an registrierte Geräte verteilen (kein TestFlight)
• You don’t have or don’t want to use an App Store Connect API key
• Sie möchten Build-Artikel sammeln via --output-upload ohne bei der App Store zu submiten

Anforderungen

Ad-hoc-Builds haben weniger Anforderungen als App Store Builds:

Zugangsdaten	Erforderlich?
Verteilungszertifikat (.p12)	Ja
Ad-hoc-Verteilungsprofil (.mobileprovision)	Ja
Team-ID (--apple-team-id)	Ja
App Store Connect API-Schlüssel (.p8)	Nein
Apple Key ID / Issuer ID	Nein

Hinweis

In ad_hoc Modus, --apple-key, --apple-key-id, und --apple-issuer-id werden nicht unterstützt und werden ignoriert. Dies ist der Grund, warum die beiden App Store Connect Zeilen oben keine ad-hoc CLI-Flags anzeigen; diese Optionen gelten nur für app_store Modus.

Vorsicht

Ohne einen App Store Connect API-Schlüssel wird die automatische Inkrementierung der Buildnummer auf eine timestamp-basierte Fallback zurückgegriffen. Um die Warnung zu unterdrücken, übergeben Sie --skip-build-number-bump.

Ein ad-hoc-Beitrittsprofil erstellen

Folge den gleichen Schritten wie Beitragsprofil, aber in Schritt 5 wähle Ad Hoc anstatt App Store:

1. Gehe zu Apple-Entwickler-Profile
2. Klicke auf + Schaltfläche
3. Wähle Ad Hoc klicken Sie auf Fortfahren
4. Wählen Sie Ihre App und Zertifikat für die Verteilung
5. Wählen Sie die Geräte aus, die Sie registrieren möchten
6. Benennen und herunterladen Sie das Profil

Speichern Sie die Ad-hoc-Kredentials

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --ios-distribution ad_hoc \
  --apple-team-id YOUR_TEAM_ID \
  --certificate './certificate.p12' \
  --ios-provisioning-profile './adhoc_profile.mobileprovision'

Nein --apple-key, --apple-key-idoder --apple-issuer-id erforderlich.

Einzelbuild ausführen

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc

Um die IPA als Buildartefakt zu sammeln, fügen Sie --output-upload:

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc \
  --output-upload

CI/CD mit Einzelbuilds

Für GitHub Actions benötigen Sie weniger Geheimnisse als App Store Builds:

github/workflows/ios-adhoc-build.yml

name: iOS Ad-Hoc Build

on:
  workflow_dispatch:

jobs:
  ios-adhoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS ad-hoc build
        run: bunx @capgo/cli@latest build request --platform ios --ios-distribution ad_hoc --output-upload
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_ADHOC }}
          CAPGO_IOS_DISTRIBUTION: ad_hoc

Hinweis

Beachten Sie, dass APPLE_KEY_ID, APPLE_ISSUER_ID, und APPLE_KEY_CONTENT für Ad-hoc-Builds nicht erforderlich sind.

Apps mit Erweiterungen (Multi-Target-Signing)

If your app includes extensions (share extensions, widgets, notification service extensions, etc.), each extension target needs its own provisioning profile. Capgo supports this via the repeatable --ios-provisioning-profile Terminal-Fenster

Apps with Extensions (Multi-Target Signing)

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile "com.example.app=./app_profile.mobileprovision" \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

Jeder --ios-provisioning-profile flag maps a bundle ID to its provisioning profile file. The CLI:

1. Die __CAPGO_KEEP_0__:
2. Jedes mobileprovision-Datei liest
3. Automatisch extrahiert der Profilnamen aus dem eingebetteten plist
4. Base64-codiert die Datei CAPGO_IOS_PROVISIONING_MAP Speichert alles als ein

Tipp

Tipp

Sie benötigen für alle Ziele eine Verteilungszertifikat – nur Provisioning-Profile unterscheiden sich pro Ziel.

Sie haben zuvor BUILD_PROVISION_PROFILE_BASE64 (Single-Profile) verwendet. Führen Sie folgenden Befehl aus:

bunx @capgo/cli@latest build credentials migrate --platform ios

Dies wandelt Ihre bestehenden Single-Profile-Anmeldeinformationen in die neue CAPGO_IOS_PROVISIONING_MAP Format um und entfernt die Legacy-Schlüssel (BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Nach der Migration fügen Sie Erweiterungsprofile mit dem update Befehl (additiver Merge) hinzu:

bunx @capgo/cli@latest build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

Tip

Benutze update (nicht save) um Profile zu vorhandenen Anmeldeinformationen hinzuzufügen. Das update Kommando kombiniert neue Profile mit bestehenden. Benutze save nur, wenn du alle Anmeldeinformationen von vorneherein einrichtest.

Fehlersuche

Provisionierungsprofil enthält keine XYZ-Fähigkeit.

Manchmal siehst du folgenden Fehler:

Provisioning profile "YOUR_PROVISIONING_PROFILE_NAME" doesn't include the XYZ capability. (in target 'App' from project 'App')"

Dies passiert, weil Sie eine neue Fähigkeit nach der Erstellung des Provisionierungsprofils aktiviert haben. Das alte Provisionierungsprofil enthält die neue Fähigkeit noch nicht.

Um dies zu beheben, müssen Sie das Provisionierungsprofil neu generieren.

1. Öffnen Apple-Entwicklerportal
2. Wählen Sie das richtige Team aus der Dropdown-Liste
3. Klicken Sie auf den Profiles Schaltfläche
4. Suchen Sie das Provisionierungsprofil, das Sie neu generieren möchten
5. Klicken Sie auf den Edit Button
6. Klicken Sie auf den Save Button
7. Klicken Sie auf den Download Button
8. Re-run the Capgo Native Build setup command Dies sollte das Problem beheben.

Andere Probleme

__CAPGO_KEEP_0__

Wenn Sie für irgendeinen Grund Probleme haben, entweder mit Capgo Native Build, der Konfiguration der Anmeldeinformationen oder der App-Build, zögern Sie bitte nicht, uns über support.

Fortsetzung von iOS Builds

Wenn Sie iOS Builds verwenden, um die CI/CD-Automatisierung zu planen, verbinden Sie es mit __CAPGO_KEEP_0__ CI/CD für den Produktworkflow in __CAPGO_KEEP_0__ CI/CD, Capgo Native Builds für den Produktworkflow in Capgo Native Builds Capgo Native Builds Wenn Sie für irgendeinen Grund Probleme haben, entweder mit Capgo Native Build, der Konfiguration der Anmeldeinformationen oder der App-Build, zögern Sie bitte nicht, uns über Capgo Integrations für den Produktworkflow in Capgo Integrations CI/CD-Integration für die Implementierungsdetails in CI/CD-Integration, und GitHub Actions-Integration für die Implementierungsdetails in GitHub Actions-Integration.