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 dazu bunx @capgo/cli@latest app add falls nicht)
• A Mac Computer mit Xcode installiert (Es ist möglich, die Build-Einrichtung auf einem Linux/Windows-Computer vorzunehmen, aber es ist noch nicht dokumentiert)
• Eine gültige Apple-Entwickler-Konto (99 $/Jahr) (Sie müssen Admin- oder Eigentümerrechte auf dem Apple-Entwickler-Konto haben)
• Ihre App muss erfolgreich über Xcode gebaut werden können
• Eine Capacitor-App
• Eine konfigurierte App-Ikone. Apps ohne eine App-Ikone 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-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:
  • Einzelunternehmen / Einzelunternehmer: Ihr rechtlicher Name wird zum Verkäufernamen auf dem App Store
  • Organisation: erfordert eine rechtliche 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
• 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
• Setzen Sie Ihren End-Bundle-Id frühzeitig fest. Ändern Sie ihn später, wenn möglich, um die App Store-Einrichtung neu zu konfigurieren
• Planen Sie diese App Store Connect-Elemente vor der App-Überprüfung: Support-URL, Datenschutzrichtlinien-URL, Altersfreigabe, Screenshot, Export-Kompliance und Kontaktdaten für die App-Überprüfung

Hinweis

Benutzerfreundliche offizielle Referenzen:

• Apple-Entwickler-Programm beitreten
• Apps und Spiele einreichen
• Plattformversionen 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 höher.

Empfohlen: automatisierte Einrichtung

Sie müssen nichts davon manuell durchführen. Capgo's Einrichtung 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 sich für die Einrichtung der Zertifikate selbst entscheiden 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 es zunächst einrichten und eine erste Testflug-Erstellung manuell durchführen. Es gibt einige Vorteile bei der Durchführung einer manuellen Erstellung:

• Sie werden das Distributionszertifikat auf Ihrem lokalen Computer 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 Verteilungszeugnis auf Ihrem lokalen Computer installiert haben. Dies ist ein bisschen komplex, aber ich werde es unten erklären.

Einrichten des Verteilungszeugnisses

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-Entwicklerkonto 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 dürfen, auf 3. Wenn Sie mehr als 3 Zertifikate haben, müssen Sie eines löschen, um ein neues zu erstellen. Dies werde ich in diesem Tutorial nicht behandeln.

   1. Klicken Sie auf den + Drücken Sie 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.

Da Sie nun das Verteilungszertifikat installiert haben, können Sie den Build-Prozess beginnen.

Manueller Build zum TestFlight

1. Öffnen Sie die App in Xcode

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

2. Finden und auf den archive Schaltfläche

   In der Xcode-Leiste finden und auf die product -> archive 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 Hauptsprache - die Hauptsprache 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 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:

Hinzufügen Sie sich 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. Erstellen Sie eine neue Gruppe

   Ich nenne die Gruppe gerne „interne Tester“. Sie können sie jedoch nach Ihren Wünschen benennen.

   

9. Klicken Sie auf Invite testers Schaltfläche

10. Sagen Sie sich selbst zu

    Finden Sie sich selbst in der Liste und wählen Sie das Häkchen neben Ihrem Namen aus. (Sie müssen die Seite möglicherweise neu laden, um sich selbst zu sehen) Dann klicken Sie auf 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 Dinge, was Sie tun müssen, bevor Sie Capgo Native Build konfigurieren können

Einrichten der Compliance-Informationen

Sie müssen nun Apple versprechen, dass Ihre App keine nicht standardmäßige (wie ein benutzerdefiniertes Algorithmus) Verschlüsselung verwendet. Wenn Ihre App eine 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 diese Werte zu setzen. false.

Lassen Sie uns mit dem ersten beginnen:

1. Beachten Sie alle Schritte aus der vorherigen Abschnitt, um die TestFlight-Sektion in App Store Connect zu finden

2. Klicken Sie auf Builds -> iOS

3. Finden Sie die 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 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

   

Bezüglich der zweiten Option 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. Speichern Sie die Datei

Hinweis

Hier finden Sie die offizielle Apple-Dokumentation zur Information von Apple über Ihre Einhaltung der Verschlüsselungsexportregulierungen.

Installation des TestFlight-Apps und Annahme der Einladung

Jetzt bist du Fast fertig bereit, deine App in TestFlight zu testen. Bevor du fortfährst, musst du die folgenden Schritte ausführen:

1. Herunterladen der TestFlight-App aus dem App Store auf deinem iOS/iPadOS-Gerät
2. Die Einladung zu deiner App akzeptieren

Ich werde die Details, wie du die TestFlight-App auf deinem Gerät installierst, überspringen. Wenn du nicht sicher bist, wie du eine App installierst, hat Google einige großartige Anleitungen, die du befolgen kannst.

Bezüglich der Akzeptierung der Einladung erhältst du eine E-Mail von Apple mit einem Link, um die Einladung anzunehmen.

1. Öffne die E-Mail von Apple mit dem Link, um die Einladung anzunehmen

2. Klicke auf View in TestFlight Schaltfläche

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. Klicken Sie bitte 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 zum Testen Ihrer App in TestFlight angenommen. Jetzt können Sie Capgo Native Build konfigurieren, um Ihre App zu bauen und bei TestFlight zu submiten.

Konfiguration von Capgo Native Build

Um Ihre App in TestFlight hochladen zu können, müssen Sie einige Dinge in Capgo Native Build konfigurieren. Hier ist eine Liste der Dinge, 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 deines App Store Connect API-Sicherheitszertifikats
--apple-issuer-id	Deine App Store Connect Aussteller-ID
--certificate	Zugangspfad zu Ihrem Verteilungszertifikat (.p12 Datei)
--ios-provisioning-profile	Zuordnung des Provisioning-Profils (bundleId=path oder einfach Pfad für ein 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

Wir beginnen mit der Team-ID. Sie ist 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

Zum Apple-Schlüssel wechseln wir nun

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. Wenn es bei Ihnen nicht funktioniert, laden Sie die Seite neu.

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

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

3. Klicken Sie auf den Integrations Schaltfläche

4. Finde das issuer

   Vorsicht

   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 die Zugriffsberechtigung fest App manager und klicken Sie auf den Generate Schaltfläche

7. Die Schlüssel-ID speichern

   Vorsicht

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

   

8. Vorsicht

   Achtung

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

   Warnung

   NEHMEN SIE DIE SCHLÜSSEL NICHT MIT JEDEREN TEILEN - BENUTZEN SIE ES NUR 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 eine der ersten Schritte in dieser Anleitung die Einrichtung des Verteilungs-Zertifikats.

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 Button

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 Sichern - 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 eingeben
   • 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 durch die __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ unterstützt - geben Sie einfach das Passwort mit der Option an, wenn Sie die Konfigurationskommando ausführen. .p12 files are fully supported by the Capgo CLI - just provide the password using the --p12-password protectedTokens

   

7. Wenn Sie zum "Login-Keychain-Passwort" gefragt werden, geben Sie das Passwort ein, das Sie zum Anmelden Ihres Macs verwenden

   Das Passwort, das Sie zum Anmelden Ihres Macs verwenden. Klicken Sie dann auf den Allow Schaltfläche.

   

Glückwunsch 🎉 Sie haben das Zertifikat exportiert.

Zertifikatsprofil

Abschnitt mit dem Titel "Zertifikatsprofil"

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

2. Apple-Entwickler-Profilseiten

   1. Klicken Sie auf Ihren Namen 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 Anwendung, die Sie bauen möchten

   Finden Sie Ihre Anwendung 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, kehren Sie zu Keychain Access zurück und finden Sie das Zertifikat, das Sie exportiert haben. Dann überprüfen Sie die Ablaufzeit.

   

8. Benennen Sie das Profil

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

   Tip

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

   

9. Das Profil herunterladen

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

   Vorsicht

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

   

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

Vorsicht

Kommt nie dazu, die von Ihnen erstellten Anmeldeinformationen in Ihrem Repository zu committen. Behalten Sie sie sicher! 🔒

Laufende Konfigurationskommando

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

Der Befehl, den Sie ausführen müssen, lautet:

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-Sicherheitszertifikat
• --apple-issuer-id: Ihr Apple-Zertifikatsanbieter-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 Anleitung zum Auflösen von Problemen im Builder für Schritte zur Uhrsynchronisierung.

CI/CD-Einrichtung (GitHub Actions)

Wenn Sie bereits den Schritt 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.

, Sie haben bereits alles, was Sie für CI/CD benötigen. Dieser Abschnitt beschreibt nur, 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

Tipp

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

2) Erstelle Repository-Geheimnisse

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-Key-ID und Apple-Issuer-ID
APPLE_ISSUER_ID	Issuer-ID von Apple-Schlüssel, Apple-Key-ID und Apple-Issuer-ID
BUILD_CERTIFICATE_BASE64	Inhalt von certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Durch CLI — kopieren Sie von .capgo-credentials Datei
APPLE_KEY_CONTENT	Inhalt von apple_key_base64.txt
P12_PASSWORD (optional)	Ihr Passwort, wenn es während der Exportierung gesetzt wurde .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 }}

Tipp

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

Der Build ausführen

Jetzt bist du bereit, deinen ersten Build auszuführen.

Laufen 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 hochzuladen.

Zum App Store-Bewertungsprozess einreichen

Der normale App Store-Build-Weg lädt das Build in App Store Connect/TestFlight hoch. Wenn Ihre CI-Ausgabe auch die verarbeitete TestFlight-Version mit der App Store-Version verknüpfen und für die App-Überprüfung 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 Überprüfung 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 der Standard-App-Store-Text für 'Was's Neues' und jeder --store-release-notes-locale "locale=notes" Eintrag kann ihn für eine Lokalisierung des Stores überschreiben. Verwenden --ios-automatic-release um automatisch nach Genehmigung durch Apple 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 zur 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 (zum Beispiel für interne Tests oder CI-Artikel), können Sie das --ios-distribution Flag verwenden.

Hinweis

Die ad-hoc-Verteilung ist Not wie Enterprise (In-House)-Verteilung. Enterprise-Verteilung erfordert einen separaten 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 Modi nur. ad_hoc Wann Sie ad-hoc-Modus verwenden sollten

Abschnitt mit dem Titel ‘Wann Sie ad-hoc-Modus verwenden sollten’

• Sie haben kein oder möchten kein App Store Connect __CAPGO_KEEP_0__-Schlüssel verwenden
• You don’t have or don’t want to use an App Store Connect API key
• ohne bei der App Store zu melden --output-upload Anforderungen

Abschnitt mit dem Titel ‘Anforderungen’

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)	No
Apple Key ID / Aussteller ID	No

Hinweis

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

Erstellung eines ad-hoc-Beitrittsprofils

Folgen Sie den gleichen Schritten wie Beitrittsprofilcontext: Seite/ Bereich: Capgo Builder / native cloud Build-Produktseite. Rolle: Kurzer UI-Label oder Navigationselement. Gesehen in: Seite native-build.astro. Nachrichtenschlü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 Zertifikat für die Verteilung
5. Wählen Sie die Geräte aus, die Sie registrieren möchten
6. Benennen und das Profil herunterladen

Speichern Sie die 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-idoder --apple-issuer-id benötigt.

Ein ad-hoc-Build ausführen

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

Um das 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

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)

Wenn Ihre App Erweiterungen (z.B. Teilen-Erweiterungen, Widgets, Benachrichtigungs-Service-Erweiterungen usw.) enthält, benötigt jede Erweiterung-Ziel seine eigene Zertifizierungsprofil. 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 Profildatei. Die CLI:

1. Liest jede mobileprovision-Datei
2. Auto-extrahiert den Profilnamen aus dem eingebetteten plist
3. Base64-codiert die Datei
4. Speichert alles als eine einzelne CAPGO_IOS_PROVISIONING_MAP Zugangsdaten

Tip

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-Kredentials 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) zum Hinzufügen von Profilen zu bestehenden Anmeldeinformationen. Die update Kommandozeilenanweisung fügt neue Profile mit bestehenden zusammen. Verwenden Sie save nur, wenn Sie alle Anmeldeinformationen von vorneherein einrichten.

Hilfe bei Problemen

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 Provisionierungsprofils aktiviert haben. Das alte Provisionierungsprofil enthält die neue Funktion noch nicht.

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

1. Öffnen Apple-Entwickler-Portal
2. Wählen Sie die richtige Team-Option im Dropdown-Menü
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 Schaltfläche
6. Klicken Sie auf den Save Schaltfläche
7. Klicken Sie auf den Download Schaltfläche
8. Wiederholen Sie den Capgo Native Build-Einrichtungsbefehl mit dem neu heruntergeladenen Profil.

Dies sollte das Problem beheben.

Weitere Probleme

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

Weitergehen von iOS Builds

Wenn Sie iOS Builds zum Planen der CI/CD-Automatisierung verwenden, verbinden Sie es mit Capgo CI/CD für den Produktworkflow in Capgo CI/CD, Capgo Native Builds for the product workflow in Capgo Native Builds, Capgo Integrations for the product workflow in Capgo Integrations, CI/CD-Integration für die Implementierungsdetails in CI/CD-Integration, und GitHub Actions Integration for the implementation detail in GitHub Actions Integration.