iOS Builds

Erstellen und übermitteln Sie iOS-Anwendungen an TestFlight und den App Store mit Capgo's dediziertem Mac-Infrastruktur.

Was Sie lernen werden

• Sie werden erfahren, wie Sie Ihre App über Capgo Native Build hochladen
• Sie werden erfahren, wie Sie die Zertifikate für Capgo Native Build konfigurieren

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)
• A Mac-Computer mit Xcode installiert (Es ist möglich, die Build auf einem Linux/Windows-Maschine einzurichten, aber es ist noch nicht dokumentiert)
• Eine gültige Apple-Entwicklerkonto (99 $/Jahr) (Sie müssen Admin- oder Eigentümerrechte auf dem Apple-Entwicklerkonto haben)
• Ihre App muss erfolgreich über Xcode gebaut werden können
• Eine Capacitor-App
• Eine für die App konfigurierte Icon. Apps ohne Icon können nicht im App Store hochgeladen werden

Hinweis

Für diesen Tutorial 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 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 rechtlicher Name wird zum Verkäufernamen auf dem App Store
  • Organisation: erfordert eine juristische Person, eine D-U-N-S-Nummer, eine öffentliche Unternehmenswebsite, eine E-Mail-Adresse auf dem Unternehmensdomän und eine Person mit der Befugnis, die Organisation zu Apples Vereinbarungen zu binden
• Verwenden 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 End-Bundle-Id frühzeitig fest. Ändern Sie ihn später, wenn möglich, bedeutet App Store-Einrichtung neu durchführen
• Planen Sie diese App Store Connect-Elemente vor der App-Überprüfung: Support-URL, Datenschutzrichtlinien-URL, Altersfreigabe, Screenshot, Export-Kompliance und App-Überprüfungs-Kontaktinformationen

Hinweis

Nutzen Sie diese offiziellen Referenzen:

• Become a member of the Apple Developer Program
• Submit your apps and games
• Plattformversioneninformationen in App Store Connect

Vorsicht

Apple aktualisiert regelmäßig die Mindestanforderungen an die SDK-Version. Ab dem 28. April 2026, iPhone- und iPad-Apps, die in App Store Connect hochgeladen werden, müssen mit der IOS und iPadOS 26 SDK oder später.

Empfohlen: automatisierte Einrichtung

Sie müssen nichts davon selbst machen. Capgo's Einrichtung erstellt und konfiguriert Ihre iOS-Zertifikate (Distributionszertifikat + Verteilungsprofil) für Sie – dies ist die empfohlene Vorgehensweise:

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

Der folgende manuelle Leitfaden ist nur für diejenigen gedacht, die sich für die Einrichtung der Zertifikate selbst entscheiden oder genau wissen möchten, was Capgo unter der Haube macht.

Der erste manuelle Build

Bevor wir mit dem Aufbau der App mit Capgo beginnen können, sollten wir es zunächst einrichten und einen ersten Testflug- Build manuell durchführen. Es gibt einige Vorteile daran, einen manuellen Build zuerst durchzuführen:

• Sie werden das Distributionszertifikat auf Ihrem lokalen Rechner einrichten
• Sie werden das App-Store-Verzeichnis erstellen, wenn Sie es noch nicht getan haben
• Sie werden in der Lage sein, alle Probleme mit dem Build-Prozess, der mit Ihrer App verbunden ist, zu lösen code

Bevor wir beginnen können, müssen Sie das Verteilungszertifikat auf Ihrem lokalen Computer installiert haben. Dies ist ein bisschen komplex, aber ich werde es unten erklären.

Einrichtung des Verteilungszertifikats

1. Xcode öffnen

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

   

3. Zum Accounts

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

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

6. Klicken Sie auf den Manage Certificates... Schaltfläche

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. Ich werde mich nicht auf das in diesem Tutorial befassen.

   1. Klicken Sie auf den + Knopf 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.

Jetzt, da Sie das Verteilungszertifikat installiert haben, können Sie den Build-Prozess beginnen.

Manueller Build zum TestFlight

1. Ausführen

   Um die App in Xcode zu öffnen. bunx cap open ios Finden und auf den

2. Knopf archive In der Xcode-Leiste finden und auf den

   Manueller Build zum TestFlight product -> archive Klicken Sie auf den Button.

   

3. Warten Sie, bis das Build abgeschlossen ist

4. Klicken Sie auf den Distribute App Button

   

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

   

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-Records 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, dass alles in Ordnung ist und Sie Ihre App jetzt in TestFlight sehen können, aber es gibt noch ein paar Dinge, die noch erledigt werden müssen:

1. Fügen Sie sich selbst zu TestFlight hinzu
2. Erledigen Sie die Exportkonzessionen, damit die Veröffentlichung testbar wird
3. Füllen Sie die erforderlichen App Store Connect-Metadaten wie Ihre Support-URL, Ihre Datenschutzrichtlinien-URL und Ihre Altersangabe ein
4. Vorbereiten Sie Screenshots, die den von Ihnen unterstützten Geräten entsprechen
5. Fügen Sie die App-Review-Kontaktinformationen und die Testanmeldeinformationen hinzu, bevor die Produktionsabgabe erfolgt

Lassen Sie uns mit dem ersten beginnen:

Die Hinzufügung Ihrer selbst zu TestFlight

1. Gehe zur App Store Connect Seite

2. Mit Ihrem Apple-Entwicklerkonto anmelden

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 Schaltfläche

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

6. Klicken Sie auf den TestFlight Schaltfläche

7. Klicken Sie auf den Internal Testers plus Schaltfläche

8. Eine neue Gruppe erstellen

   Ich nenne die Gruppe gerne „interne Tester“. Sie können ihr einen beliebigen Namen geben.

   

9. Klicken Sie auf Invite testers Schaltfläche

10. Fügen Sie sich selbst der Gruppe hinzu

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

    

11. Stellen Sie sicher, dass Sie der Gruppe hinzugefügt wurden

    Sie sollten sich jetzt in der Gruppe sehen

    

Herzlichen Glückwunsch 🎉 Sie haben sich selbst in TestFlight hinzugefügt. Jetzt gibt es noch ein letztes Ding, was Sie tun müssen, bevor Sie Capgo Native Build konfigurieren können

Einrichten der Compliance-Informationen

Sie müssen Apple nun versprechen, dass Ihre App keine nicht standardmäßige (wie ein benutzerdefiniertes Algorithmus) Verschlüsselung verwendet. Wenn Ihre App jedoch nicht standardmäßige Verschlüsselung verwendet, empfehlen wir Ihnen, die Apple-Dokumentation zu lesen, wie Sie dies handhaben können. Es gibt zwei Möglichkeiten, dies zu tun:

1. Sie können dies jede Zeit, wenn Sie Ihre App bauen, manuell durchführen.
2. Sie können Ihre plist-Datei konfigurieren, um diese Werte automatisch auf diesen Wert zu setzen. false.

Lassen Sie uns mit dem ersten beginnen:

1. Folgen Sie 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 das Build mit fehlender Compliance-Information und klicken Sie auf Manage

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

   Für mich ist dies noneAber es könnte für Sie anders sein. Anschließend klicken Sie auf Speichern

   

5. Ihre App sollte jetzt sagen ready to test

   

Was das zweite betrifft, hier sind die Schritte:

1. Öffnen Sie das Info.plist Datei

2. Fügen Sie die folgende Schlüssel 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 Installation der TestFlight-App und die Annahme der Einladung

Jetzt bist du __CAPGO_KEEP_0__ fast bereit, deine App in TestFlight zu testen.

1. Bevor du fortfahren kannst, musst du folgende Schritte ausführen: Lade die __CAPGO_KEEP_0__
2. App

herunter, die du im App Store auf deinem iOS/iPadOS-Gerät findest.

Akzeptiere die Einladung, deine App zu testen.

1. Ich werde die Einzelheiten, wie du die TestFlight-App auf deinem Gerät installierst, überspringen. Wenn du nicht sicher bist, wie du eine App installierst, findest du auf Google einige großartige Anleitungen, wie du es tun kannst.

2. Wenn es um die Annahme der Einladung geht, erhältst du eine E-Mail von Apple mit einem Link, um die Einladung anzunehmen. View in TestFlight Öffne die E-Mail von Apple mit dem Link, um die Einladung anzunehmen und klicke auf den

3. Klicken Sie auf den Install Button

4. Installieren Sie die App auf Ihrem Gerät

   Wenn Sie die App zuvor mit Xcode installiert haben, sehen Sie möglicherweise die folgende Bildschirmmeldung. Bitte klicken Sie auf den install Button.

5. Warten Sie, bis die App installiert ist

6. Klicken Sie auf den Open Button und klicken Sie darauf

Herzlichen Glückwunsch 🎉 Sie haben die Einladung zur Testung Ihrer App in Testflug angenommen. Jetzt können Sie Capgo Native Build konfigurieren, um Ihre App zu bauen und bei Testflug zu submiten.

Konfiguration von Capgo Native Build

Um Ihre App in TestFlight hochladen zu können, müssen Sie einige Einstellungen in Capgo Native Build vornehmen. Hier ist eine Liste der Parameter, die Sie an die Capgo CLI übergeben werden:

Eigenschaft	Beschreibung
--platform	Die Plattform, für die Sie bauen möchten (ios)
--apple-team-id	Dein Apple-Entwickler-Team-ID (in der Apple-Entwickler-Portal)
--apple-key	Weg zu deinem App Store Connect API-Sicherheitszertifikat (.p8 Datei)
--apple-key-id	Die Key-ID Ihres App Store Connect API-Sicherheitszertifikats
--apple-issuer-id	Deine App Store Connect Aussteller-ID
--certificate	Pfad zu Ihrem Verteilungszertifikat (.p12 Datei)
--ios-provisioning-profile	Zuweisung von Provisioning-Profilen (bundleId=path oder einfach Pfad für ein einzelnes Profil)

Beispielbefehl:

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 die Team ID

   

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

Jetzt gehen wir zum Apple-Schlüssel über.

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

Auf macOS capgo build init Können Sie auf macOS diesen App Store Connect API-Schlüssel für Sie erstellen. Wählen Sie ‚Nein — erstelle einen für mich‘ und ein geführtes Fenster öffnet sich in App Store Connect, führt Sie durch jeden Schritt und fängt die 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. Gehe zu Benutzer- und Zugriffsberechtigungsseite von App Store Connect

   Hinweis

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

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

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

3. Klicke auf den Integrations Schaltfläche

4. Finde das issuer

   Vorsicht

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

   Klicken Sie auf den copy Button zum Kopieren des Ausstellers

5. Klicken Sie auf die Plus-Taste

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

7. Speichern Sie die Schlüssel-ID

   Vorsicht

   Dies IST ZU SPEICHERN - Sie benötigen es später App Store Connect Kopieren Sie die Schlüssel-ID

   

8. Vorsicht

   Vorsicht

   Dies MUSSEN SIE SICH DAS MERKEN Sie werden es später benötigen

   Gefahr

   TEILEN SIE DIE SCHLÜSSEL NICHT MIT JEDERMANN - BENUTZEN SIE SIE AUSNICHTS IN DEM CAPGO CLI

   

   

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

Zertifikat

Jetzt bist du bereit, das Zertifikat zu exportieren. Wie du dich erinnerst, war die Einrichtung des Verteilungszertifikats einer der ersten Schritte dieser Anleitung.

Allerdings hat Apple in ihrer unendlichen Weisheit entschieden, dass die Art und Weise, wie du das Zertifikat exportierst, sich erheblich von der Art und Weise unterscheidet, wie du sie erstellst 😊 Lass uns es auf die folgende Weise einrichten:

1. Öffne Keychain Access

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

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

3. Suchen Sie Ihr Zertifikat in der Liste

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

4. Rechtsklick auf das Zertifikat und wählen Sie Export

5. Speichern Sie das Zertifikat als einen .p12 Datei

   Vorsicht

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

   1. Stellen Sie sicher, dass Sie für das Zertifikatsdatei einen guten Namen 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 hier eines setzen. Passwortgeschützte Dateien werden vollständig von der __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ unterstützt - geben Sie einfach das Passwort mit der Option beim Ausführen der Konfigurationskommando an. .p12 files are fully supported by the Capgo CLI - just provide the password using the --p12-password Make sure to select a good name for the certificate file

   

7. Wenn Sie zum "Login-Keychain-Passwort" gefragt werden, geben Sie das Passwort ein, das Sie zum Anmelden an Ihrem Mac verwenden

   Das Passwort, das Sie zum Anmelden an Ihrem Mac verwenden. Klicken Sie dann auf den Allow Schaltfläche.

   

Herzlichen Glückwunsch 🎉 Sie haben das Zertifikat exportiert.

Zertifizierungsprofil

Abschnitt mit dem Titel "Zertifizierungsprofil"

1. Jetzt sind Sie bereit, das Zertifizierungsprofil zu exportieren. Ich verspreche Ihnen, das ist das letzte, was Sie von Apple benötigen werden. Hinweis:

2. Apple-Entwickler-Profile wählen Sie das richtige Team im Dropdown-Menü

   1. Klicken Sie auf Ihr Benutzerkonto in der oberen rechten Ecke
   2. Klicken Sie auf das Team, das Sie verwenden möchten

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 + Schaltfläche

5. Wählen Sie den Profiltyp Wählen Sie App Store Connect und klicken Sie auf die Continue Schaltfläche

   

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

   Finden Sie Ihre App im Dropdown-Menü und klicken Sie auf den Continue Schaltfläche

   

7. Wählen Sie das richtige Verteilungszertifikat

   Wählen Sie das Zertifikat, das Sie im vorherigen Schritt exportiert haben, und klicken Sie auf die Continue Schaltfläche

   

   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 Ablaufzeit an.

   

8. Benennen Sie das Profil

   Geben Sie dem Profil einen Namen und klicken Sie auf den Generate Schaltfläche

   Tipps

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

   

9. Laden Sie das Profil herunter

   Klicken Sie auf die Download Schaltfläche zum Herunterladen des Profils

   Vorsicht

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

   

Herzlichen Glückwunsch 🎉 Sie haben jetzt alles, was Sie zum Konfigurieren von Capgo Native Build benötigen.

Vorsicht

Kommentieren Sie die von Ihnen erstellten Anmeldeinformationen nie in Ihrem Repository ein. Behalten Sie sie sicher! 🔒

Abschnitt mit dem Titel „Running the configuration command“

You have done it! You have now got everything you need to configure Capgo Native Build.

Terminal-Fenster

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

Wert der Platzhalter ersetzen

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: Ihr Apple-Schlüssel-ID
• --apple-issuer-id: Ihr Apple-Aussteller-ID
• --certificate: Pfad zu Ihrem exportierten .p12 Zertifikat
• --ios-provisioning-profile: Pfad zu Ihrem heruntergeladenen .mobileprovision Datei (Bundle-ID wird automatisch für einzelne Profile ermittelt)

Wenn alles gut ging, sehen Sie folgende Ausgabe:

Apple-Authentifizierung fehlgeschlagen? Synchronisiere deinen Wecker

Wenn das App Store Connect API-Schlüssel korrekt aussieht, aber die Authentifizierung immer noch fehlschlägt, synchronisiere deinen Computerwecker 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 Wecker, der nur wenige Sekunden aus der Synchronisation ist, kann ausreichen, um diesen Schritt zu scheitern.

Siehe die Troubleshooting-Anleitung für den Builder für Schritte zur Uhrsynchronisierung.

CI/CD-Einrichtung (GitHub Actions)

Wenn Sie bereits die Schritte abgeschlossen haben Team-ID, Apple-Schlüssel, Apple-Schlüssel-ID und Apple-Aussteller-ID, Zertifikat, und ProvisionierungsprofilSie haben bereits alles, was Sie für CI/CD benötigen. Dieser Abschnitt beschreibt nur, wie Sie diese Werte als GitHub Actions-Secrets und Umgebungsvariablen übergeben.

1) Konvertieren Sie die Zugriffsberechtigung-Dateien in eine einzelne Zeile Base64

# 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

Tipp

GitHub Geheimnisse sollten einzelne Zeilenwerte sein. tr -d '\n' entfernt Zeilenumbrüche aus der Ausgabe von base64.

2) Erstelle Repository-Secrets

In GitHub > Repository > Settings > Secrets and variables > Actions, füge hinzu:

Geheimnisname	Wert
CAPGO_TOKEN	Dein Capgo API Token
APP_STORE_CONNECT_TEAM_ID	Team-ID aus Team-ID
APPLE_KEY_ID	Schlüssel-ID aus Apple-Schlüssel, Apple-Schlüssel-ID und Apple-Aussteller-ID
APPLE_ISSUER_ID	Aussteller-ID von 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 kopieren .capgo-credentials Datei
APPLE_KEY_CONTENT	Inhalt von apple_key_base64.txt
P12_PASSWORD (optional)	Ihr .p12 Passwort, wenn während der Export gesetzt

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 Einstellung sendet CI die Anmeldeinformationen nur über Umgebungsvariablen. Sie müssen keine Signierungsdateien committen oder sie als Workflow-Artikel hochladen.

Die Ausführung des Builds

Jetzt sind Sie bereit, Ihren ersten Build auszuführen.

Führen Sie den folgenden Befehl aus, um Ihre App zu bauen:

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

Herzlichen Glückwunsch 🎉 Sie haben Ihre App erfolgreich gebaut und sie ist bereit, zur App Store hochgeladen zu werden.

Zur App Store-Bewertung einreichen

Der normale App Store-Build-Weg lädt das Build in App Store Connect/TestFlight hoch. Wenn Ihre CI-Ausgabe auch die bearbeitete TestFlight-Build zum App Store-Veröffentlichung und zur App-Bewertung anhängen und diese für die App-Bewertung einreichen soll, übergeben Sie --submit-to-store-review mit einer 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

Dazu sind die App Store Connect API-Schlüssel (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, und APP_STORE_CONNECT_TEAM_ID). App-spezifische Passwörter und ad_hoc die Verteilung können ein Build für die Bewertung nicht einreichen. --store-release-name ist die App Store-Version; wenn diese weggelassen wird, Capgo liest MARKETING_VERSION diese aus dem Xcode-Projekt. --store-release-notes ist die Standard-App-Store-Neuigkeiten-Text, und jeder --store-release-notes-locale "locale=notes" Eintrag kann es für eine Lokalisierung des Stores überschreiben. Verwenden --ios-automatic-release um automatisch nach Apple-Zustimmung freizugeben, oder --no-ios-automatic-release um auf eine manuelle Freigabe zu warten. --ios-testflight-groups ist zwar noch für externe Beta-Verteilung verfügbar, aber nicht erforderlich für die Einreichung bei der App-Store-Bewertung.

Ad-Hoc-Verteilungsmodus

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

Hinweis

Die ad-hoc-Verteilung ist Not wie Enterprise (In-House)-Verteilung. Enterprise-Verteilung erfordert ein separates Apple-Entwickler-Enterprise-Konto und verwendet verschiedene Bereitstellungsprofile. __CAPGO_KEEP_0__ unterstützt derzeit nur the same as Enterprise (In-House) distribution. Enterprise distribution requires a separate Apple Developer Enterprise account and uses different provisioning profiles. Capgo currently supports app_store Erklärung ad_hoc Sie möchten IPAs direkt an registrierte Geräte verteilen (kein TestFlight)

Sie haben kein oder wollen kein App Store Connect __CAPGO_KEEP_0__-Schlüssel verwenden

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

Sie haben kein oder wollen kein App Store Connect __CAPGO_KEEP_0__-Schlüssel verwenden

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

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

Hinweis

In ad_hoc Modus, --apple-key, --apple-key-idund --apple-issuer-id werden nicht unterstützt und 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, verwendet die automatische Inkrementierung der Build-Nummer einen timestamp-basierten Ausfallwert. Um die Warnung zu unterdrücken, übergeben Sie --skip-build-number-bump.

Erstellung eines ad-hoc-Beitragsprofil

Folgen Sie den gleichen Schritten wie Beitragsprofilcontext: Seite/ Bereich: Capgo Builder / native cloud Build-Produktseite. Rolle: Kurzer UI-Label oder Navigationspunkt. Gesehen in: Seite native-build.astro. Nachrichten Schlüssel `native_build_v2_wiz_ios_s3_l` (Native Build V2 Wiz Ios S3 L). , aber in Schritt 5 wählen Sie Ad-hoc anstatt:

1. App Store Gehe zu
2. Apple-Entwickler-Profilen + Schaltfläche
3. Auswählen Ad Hoc und klicken Sie auf Weiter
4. Wählen Sie Ihre App und Ihren Verteilungszertifikat
5. Wählen Sie die Geräte aus, die Sie registrieren möchten
6. Benennen und das Profil herunterladen

Speichern Sie ad-hoc-Anmeldeinformationen

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-id, oder --apple-issuer-id benötigt.

Ein ad-hoc-Build ausführen

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

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

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

CI/CD mit ad-hoc-Builds

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

Tip

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

Apps mit Erweiterungen (Multi-Target-Signing)

Wenn Ihre App Erweiterungen (z. B. Teilen-Erweiterungen, Widgets, Benachrichtigungs-Service-Erweiterungen usw.) enthält, benötigt jeder Erweiterungsziel seinen eigenen Provisionierungsprofil. Capgo unterstützt dies über die wiederholbare --ios-provisioning-profile Flag.

Beispiel: App + Teilen-Erweiterung

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 Die Flagge entspricht einem Bundle-ID und ihrem entsprechenden Profil-Datei. Die CLI:

1. Jedes mobileprovision-File liest
2. Automatisch extrahiert den Profilnamen aus dem eingebetteten plist
3. Die Datei in Base64 kodiert
4. Alles als eine einzelne CAPGO_IOS_PROVISIONING_MAP Zugriffsdaten

Tipps

Sie benötigen eine Verteilungszertifizierung für alle Ziele – nur die Bereitstellungsprofile unterscheiden sich pro Ziel.

Migration von Single Profile

Wenn Sie zuvor BUILD_PROVISION_PROFILE_BASE64 (Single-Profile) verwendet haben, führen Sie Folgendes 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

Verwenden Sie update (nicht save) um Profile zu vorhandenen Anmeldeinformationen hinzuzufügen. Die update Kommandozeile kombiniert neue Profile mit bestehenden. Verwenden Sie save nur, wenn Sie alle Anmeldeinformationen von vorneherein einrichten.

Fehlersuche

Provisionierungsprofil enthält keine XYZ-Fähigkeit.

Manchmal sehen Sie den folgenden Fehler:

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

Dies tritt auf, weil Sie eine neue Funktion nach der Erstellung des Provisioning-Profils aktiviert haben. Das alte Provisioning-Profil enthält die neue Funktion noch nicht.

Regenerieren Sie das Provisioning-Profil.

1. Öffnen Apple-Entwicklerportal
2. Wählen Sie die richtige Team-Option im Dropdown-Menü aus
3. Klicken Sie auf den Profiles Button
4. Finden Sie das Provisioning-Profil, das Sie regenerieren möchten
5. Klicken Sie auf den Edit Schaltfläche
6. Klicken Sie auf den Save Schaltfläche
7. Klicken Sie auf den Download Schaltfläche
8. Re-run the Capgo Native Build setup command Führen Sie den __CAPGO_KEEP_0__ Native Build-Einrichtungsbefehl erneut mit dem neu heruntergeladenen Profil aus.

Dies sollte das Problem beheben.

Andere Probleme

Wenn Sie für irgendeinen Grund Probleme haben, entweder mit der nativen Capgo-Erstellung, der Konfiguration der Anmeldeinformationen oder der App-Buildung, zögern Sie bitte nicht, uns über unsere Support.

Weiterhin von iOS Builds

Wenn Sie iOS Builds zur Planung der CI/CD-Automatisierung verwenden, verbinden Sie es mit Capgo CI/CD für den Produktworkflow in Capgo CI/CD, Capgo Native Builds zur Produktworkflow in Capgo Native Builds Capgo Integrations zur Produktworkflow in Capgo Integrations CI/CD-Integration zur Implementierungsdetail in CI/CD-Integration, und GitHub Actions-Integration zur Implementierungsdetail in GitHub Actions-Integration