iOS-Builds

Mit Capgo erstellen und hochladen Sie iOS-Apps auf TestFlight und den App Store mithilfe der dedizierten Mac-Infrastruktur von Capgo.

Was Sie lernen werden

• Sie lernen, wie Sie Ihre App über Capgo Native Build hochladen können
• Sie lernen, 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 (führen Sie) bunx @capgo/cli@latest app add wenn nicht
• Kein Mac erforderlich: Capgo Der Build kompiliert und signiert Ihr iOS-App im Cloud, sodass Sie dies von macOS, Windows oder Linux aus ausführen können.
• Ein gültiges Apple-Entwicklerkonto (99 $/Jahr) (Sie müssen über Admin- oder Eigentümerrechte auf dem Apple-Entwicklerkonto verfügen)
• Dein App muss erfolgreich kompiliert werden (in Xcode lokal oder mit Capgo Build)
• Ein Capacitor-App
• Ein konfiguriertes Icon für die App. Apps ohne Icon können nicht auf dem App Store hochgeladen werden.

Hinweis

Ich werde folgende App für das Tutorial verwenden: https://github.com/Cap-go/capgo-native-build-tutorial-app

Bevor du beginnst in Apples Portalen

Bevor du Zertifikate einrichtest oder deine erste TestFlight-Upload auslöst, stelle sicher, dass das Apple-Konto und die Team-Übersicht bereit sind:

• Zwei-Faktor-Authentifizierung für das Apple-Konto aktivieren, das für die Registrierung verwendet wird
• Wähle 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
• Frühzeitig die endgültige Bundle-ID festlegen. Änderungen später führen häufig zu einer erneuten App-Store-Einrichtung.
• 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

Nützliche offizielle Referenzen:

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

Vorsicht

Apple aktualisiert regelmäßig seine Mindestanforderungen an die SDK. Ab dem 28. April 2026, iPhone- und iPad-Anwendungen, die auf App Store Connect hochgeladen werden, müssen mit dem iOS & iPadOS 26 SDK oder später.

Empfohlen: automatisierte Einrichtung

Sie müssen nichts von alledem selbst machen. 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 die 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 manuell durchführen. Es gibt einige Vorteile bei der Durchführung einer manuellen Erstellung:

• 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, Probleme mit dem Build-Prozess zu identifizieren, die mit Ihrer App code verbunden sind

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

Die Vorbereitung der Verteilungszertifikat

1. Xcode öffnen

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

   

3. Gehe zu Accounts

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

5. Suchen 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 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 + Schaltfläche 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 zum TestFlight

1. Öffnen Sie die App in Xcode

   Ausführen bunx cap open ios Öffnen Sie die App in Xcode.

2. Um die App in Xcode zu öffnen. archive button

   In der Xcode-Leiste finden und klicken Sie auf product -> archive button.

   

3. Warten Sie auf das Abschließen des Builds

4. Klicken Sie auf den Distribute App Knopf

   

5. Wählen Sie TestFlight Internal Only als Verteilungsmethode und klicken Sie auf Distribute Knopf

   

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

   Dann klicken Sie auf den next Schaltfläche

   

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

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

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

1. TestFlight-Teilnehmer hinzufügen
2. Sicherstellung der Exportkonzession, damit das Build 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 Kontaktinformationen für die App-Überprüfung und alle Testanmeldeinformationen vor der Produktionsabgabe hinzu

Lassen Sie uns mit dem ersten beginnen:

Hinzufügen 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 bei der Erstellung des App-Records verwendet 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 App, 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 nenne die Gruppe gerne „interne Tester“. Du kannst sie jedoch benennen, 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 die Seite möglicherweise neu laden, 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 im Gruppe sehen.

    

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

Einstellungen für die Compliance-Informationen

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

1. Du kannst dies jede Zeit, wenn du deine App bauen musst, manuell durchführen.
2. Du kannst deine plist-Datei so konfigurieren, dass dieser Wert automatisch auf false.

Lasst uns mit der ersten Möglichkeit 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 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

   

Was die zweite Option betrifft, hier sind die Schritte:

1. Öffnen Sie das Info.plist Datei

2. Fügen Sie die folgende Schlüsselzeichen ein:

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

3. Datei speichern

Hinweis

Hier Die offizielle Apple-Dokumentation, die beschreibt, wie Sie Apple von der Einhaltung von Verschlüsselungsexportregulierungen informieren.

Die Installation der TestFlight-App und die Annahme der Einladung

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

1. Herunterladen Sie das TestFlight-App aus dem App Store auf Ihrem iOS/iPadOS-Gerät
2. Akzeptieren Sie die Einladung, Ihre App zu testen

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

Was die Annahme der Einladung betrifft, erhalten Sie eine E-Mail von Apple mit einem Link, um die Einladung anzunehmen

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

2. Klicken Sie auf View in TestFlight Schaltfläche

3. Klicken Sie auf Install Schaltfläche

4. Installieren Sie die App auf Ihrem Gerät

   Wenn Sie die App zuvor mit Xcode installiert haben, sehen Sie möglicherweise die folgende Bildschirm. 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

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

Capgo Native Build konfigurieren

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:

Parameter	Beschreibung
--platform	Die Plattform, für die Sie bauen möchten (ios)
--apple-team-id	Ihre Apple-Entwickler-Team-ID (in der Apple-Entwickler-Portal)
--apple-key	Pfad zu Ihrem App Store Connect API-Sicherheitszertifikat (.p8 Datei)
--apple-key-id	Die Key-ID Ihres App Store Connect API-Sicherheitszertifikats
--apple-issuer-id	Ihre App Store Connect Aussteller-ID
--certificate	Pfad zu Ihrem Verteilungszertifikat (.p12 Datei)
--ios-provisioning-profile	Zuweisungsprofilabbildung (bundleId=path oder einfach Pfad für 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 das Team ID

   

Apple Key, Apple Key-ID und Apple Zertifikats-ID

Zum Apple-Schlüssel wechseln wir nun

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

Bei macOS capgo build init Kann diese 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 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

   Hinweis

   Für mich funktioniert der Link manchmal nicht. Lade die Seite neu, wenn es 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. Click on the team you want to use

3. Klicken Sie auf den Integrations Button

4. Finden Sie die issuer

   Vorsicht

   Dies SPEICHERN SIE DAS Sie benötigen es später

   Klicken Sie auf den copy App Store Connect Kopierer

5. App Store Connect Schlüssel hinzufügen

6. Setze den Namen der Schlüssel und setze den Zugriff auf App manager Schlüssel hinzufügen Generate button

7. Sparen Sie die Schlüssel-ID

   Vorsicht

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

   

8. Laden Sie die Schlüssel herunter

   Vorsicht

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

   Geheimnis

   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-Key-ID und die Apple-Issuer-ID erstellt.

Zertifikat

Jetzt sind Sie bereit, das Zertifikat zu exportieren. Wie Sie sich vielleicht erinnern, war eine der ersten Schritte in dieser Anleitung die Einrichtung des Distribution-Zertifikats.

However, Apple in their infinite wisdom, decided that the way you export the certificate is quite different from the way you create them 🙃 Let’s get into setting it up:

1. Öffnen Sie 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. Finden Sie Ihr Zertifikat in der Liste

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

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

5. Speichern Sie das Zertifikat als ein .p12 Datei

   Vorsicht

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

   1. Wählen Sie einen guten Namen für das Zertifikatsdatei
   2. Stellen Sie sicher, dass das Dateiformat auf Personal Information Exchange (.p12)
   3. Klicken Sie auf das 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
   • Einen Passwort setzen: Wenn Sie Ihr Zertifikat mit einem Passwort schützen möchten, können Sie hier eines setzen. Passwortgeschützte .p12 Dateien werden vollständig von der Capgo CLI unterstützt – geben Sie einfach das Passwort mit der --p12-password Option an, wenn Sie die Konfigurationskommando ausführen.

   

7. Wenn nach dem "Anmelde-Schlüsselkettenschlüssel" gefragt wird, geben Sie den Passwort ein, das Sie zum Anmelden auf Ihrem Mac verwenden.

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

   

Herzlichen Glückwunsch 🎉 Du hast das Zertifikat exportiert.

Zertifikatsprofil

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

1. Gehe zu Apple-Entwickler-Profil

2. Wählen Sie die richtige Team aus dem Dropdown

   1. Wähle das richtige Team aus dem Dropdown-Menü
   2. Click on the team you want to use

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

   

4. Klicken Sie auf den + Schaltfläche

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

   

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

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

   

7. Die richtige Verteilungszertifizierung auswählen

   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 exportierte Zertifikat. Dann prüfen Sie die Ablaufzeit.

   

8. Profil benennen

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

   Hinweis

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

   

9. Das Profil herunterladen

   Klicken Sie auf den Download Button, um das Profil herunterzuladen

   Vorsicht

   Dieser 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

Kommentieren Sie Ihre gerade erstellten Anmeldeinformationen nie in Ihrem Repository. Behalten Sie sie sicher! 🔒

Ausführung 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, 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

Ersatz von Platzhalterwerten

Ersetzen Sie die Platzhalterwerte oben durch Ihre 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 Schlüsseldatei
• --apple-key-id: Ihre Apple-Schlüssel-ID
• --apple-issuer-id: Ihre Apple-Aussteller-ID
• --certificate: Pfad zu Ihrem exportierten .p12 Zertifikat
• --ios-provisioning-profile: Pfad zu Ihrem heruntergeladenen .mobileprovision : (Bundle-ID wird für einzelne Profile automatisch ermittelt)

Wenn alles gut gelaufen ist, sehen Sie folgende Ausgabe:

Apple Auth-Fehler? Synchronisiere deinen Zeitserver

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

Siehe das Fehlerbehebungsleitfaden für den Builder für Schritte zur Zeitserver-Synchronisierung.

CI/CD-Einrichtung (GitHub Actions)

Wenn du bereits die Team-ID, Apple-Schlüssel, Apple Key ID und Apple Issuer ID, Zertifikat, und ZertifikatsprofilSie 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 Zertifikatsdateien 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

Tipps

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

2) Repository-Secrets erstellen

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

Geheimer Name	Wert
CAPGO_TOKEN	Ihr Capgo API-Token
APP_STORE_CONNECT_TEAM_ID	Team-ID von Team-ID
APPLE_KEY_ID	Schlüssel-ID von Apple-Schlüssel, Apple-Key-ID und Apple-Issuer-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

1) 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 als Workflow-Artikel hochladen.

Laufende Erstellung

Jetzt bist du bereit, deine erste Erstellung durchzuführen.

Bauen Sie Ihre App mit dem folgenden Befehl:

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

Herzlichen Glückwunsch 🎉 Sie haben Ihr App erfolgreich erstellt und es ist bereit, für die App Store zu werden.

Zur App Store-Überprüfung einreichen

Die normale App Store-Build-Pfad lädt das Build in App Store Connect/TestFlight hoch. Wenn Ihre CI-Ausgabe auch die verarbeitete TestFlight-Build zum App Store-Veröffentlichung und zur App-Überprüfung anhängen 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

Dies erfordert App Store Connect API-Schlüssel-Zugriff (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 eine Build für die Überprüfung nicht einreichen. --store-release-name ist die App Store-Version; wenn diese weggelassen wird, liest Capgo MARKETING_VERSION aus dem Xcode-Projekt. --store-release-notes ist die Ausfallsicherheit App Store Was Neues Text, und jeder --store-release-notes-locale "locale=notes" entry kann es für eine Store-Lokalisierung überschreiben. Verwenden Sie --ios-automatic-release zum automatischen Release nach Genehmigung durch Apple, oder --no-ios-automatic-release um auf ein manuelles Release zu warten. --ios-testflight-groups ist zwar noch für externe Beta-Verteilung verfügbar, aber nicht für die Einreichung bei der App Store-Bewertung erforderlich.

Ad-hoc-Verteilungsmodus

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

Hinweis

Ad-hoc-Verteilung ist nicht Die gleiche wie Enterprise (In-House)-Distribution. Für Enterprise-Distribution ist ein separates Apple-Developer-Enterprise-Konto erforderlich und werden unterschiedliche Provisionierungsprofile verwendet. Capgo unterstützt derzeit app_store und ad_hoc Nur in diesen Modi.

Wann Sie den Ad-hoc-Modus verwenden sollten

• Sie möchten IPAs direkt an registrierte Geräte verteilen (kein TestFlight)
• Sie haben keinen oder möchten keinen App Store Connect API-Schlüssel verwenden
• Sie möchten Build-Artikel über --output-upload ohne bei der App Store zu melden

Anforderungen

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

Credential	Wird benötigt?
Verteilungszertifikat (.p12)	Ja
Ad-hoc-Bezugsprofil (".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-id, und --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 app_store Vorsicht

Caution

Ohne einen App Store Connect API-Schlüssel, verwendet die automatische Inkrementierung der Buildnummer eine zeitbasierte Fallback-Methode. Um die Warnung zu unterdrücken, übergeben Sie --skip-build-number-bump.

Erstellung eines ad-hoc-Beitrittsprofils

Folge den gleichen Schritten wie Beitrittsprofil, aber in Schritt 5 auswählen Ad Hoc Ad-hoc anstatt:

1. App Store Apple-Entwickler-Profil
2. Klicken Sie auf + Klicke auf
3. Schaltfläche Ad-hoc und klicken Sie auf Fortsetzen
4. Wählen Sie Ihre App und Ihren Zertifikatschlüssel
5. Wählen Sie die Geräte aus, die Sie registrieren möchten
6. Benennen und herunterladen Sie das Profil

Speichern Sie ad-hoc-Zugangsdaten

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 needed.

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

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 jeder Erweiterungsziel seine eigene Zertifizierungsprofil. Capgo unterstützt dies über die wiederholbare --ios-provisioning-profile Flagge.

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 seinem Profil-Datei. 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 Profilprofile unterscheiden sich pro Ziel.

Migration von Single Profile

Wenn Sie zuvor Single Profile verwendet haben BUILD_PROVISION_PROFILE_BASE64 (single Profil), ausführen:

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

Nach der Migration fügen Sie Erweiterungsprofile mit dem Befehl (additiver Merge) hinzu: CAPGO_IOS_PROVISIONING_MAP entwickelt und entfernt die veralteten Schlüssel ("BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

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

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

Tip

Verwende update (nicht save) um Profile zu vorhandenen Anmeldeinformationen hinzuzufügen. Die update Befehl kombiniert neue Profile mit bestehenden. Verwenden Sie save verwende nur, wenn du alle Anmeldeinformationen neu einrichtest.

Troubleshooting

Profilierungsschlüssel enthält nicht die 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 tritt auf, weil Sie eine neue Funktion nach der Erstellung des Bereitstellungsprofils aktiviert haben. Das alte Bereitstellungsprofil enthält die neue Funktion noch nicht.

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

1. Öffnen Apple-Entwickler-Portal
2. Wählen Sie die richtige Team-Option im Dropdown-Menü
3. Klicken Sie auf den Profiles Button
4. Finden Sie das Bereitstellungsprofil, 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. Rufen Sie den Capgo Native Build Setup-Befehl erneut auf. mit dem neu heruntergeladenen Profil.

Dies sollte das Problem lösen.

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 Unterstützung.

Fortsetzung von iOS Builds

Wenn Sie Capgo verwenden iOS-Builds Um die CI/CD-Automatisierung zu planen, mit ihr verbinden Capgo CI/CD für den Produktworkflow in Capgo CI/CD, Capgo nativee Native Builds Capgo Native Builds im Produktworkflow in Capgo-Integrationen für den Produktworkflow in Capgo-Integrationen CI/CD-Integration für die Implementierungsdetails in CI/CD-Integration, und GitHub-Aktionen-Integration für die Implementierungsdetails in GitHub-Aktionen-Integration.