iOS Builds

Mit Capgo’s dedizierter Mac-Infrastruktur Apps für iOS auf TestFlight und den App Store bereitstellen.

Was Sie lernen werden

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

Voraussetzungen

• Ein Capgo-Konto (ein kostenloses Probeabo reicht aus, um loszulegen)
• Ihre App bereits in Capgo registriert (führen Sie "run" aus, wenn nicht) bunx @capgo/cli@latest app add Ein Mac-Computer mit Xcode installiert (es ist möglich, die Bereitstellung auf einem Linux/Windows-Computer einzurichten, aber dies ist noch nicht dokumentiert)
• Ein gültiges Apple-Entwicklerkonto (99 $/Jahr) (Sie müssen Admin- oder Eigentümerrechte auf dem Apple-Entwicklerkonto haben)
• Ein gültiges 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 konfigurierte App-Icon. Apps ohne Icon können nicht im App Store hochgeladen werden.

Hinweis

Für diese Anleitung verwende ich die folgende App: 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:

• Aktivieren Sie die zweifaktor-Authentifizierung für das Apple-Konto, das für die Registrierung verwendet wird
• Wählen Sie die richtige Mitgliedschaftsart:
  • Einzelperson / Einzelunternehmen: Ihr persönlicher 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
• Benutzen Sie ein Konto, das Zugriff auf beide Apple Developer und App Store Connect für Zertifikate, App-Records, API-Schlüssel und TestFlight hat
• Legen Sie Ihren endgültigen Bundle-Id frühzeitig fest. Ändern Sie ihn später, bedeutet es normalerweise, die App Store-Einrichtung neu zu konfigurieren
• Planen Sie diese App Store Connect-Elemente vor der App-Review: Unterstützungs-URL, Datenschutzrichtlinien-URL, Altersfreigabe, Screenshot, Export-Kompliance und Kontaktdaten für die App-Review

Hinweis

Zu empfehlende 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-Version. Ab dem 28. April 2026iPhone- und iPad-Anwendungen, die in App Store Connect hochgeladen werden, müssen mit der iOS & iPadOS 26 SDK oder höher.

Empfohlen: Automatisierung des Einrichtungsprozesses

Sie müssen nichts von alledem selbst durchführen. Capgo erstellt und konfiguriert Ihre iOS-Zertifikate (Distributionszertifikat + Berechtigungsprofil) für Sie — dies ist der empfohlene Weg:

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

Der folgende manuelle Leitfaden ist nur für diejenigen gedacht, die die Zertifikate selbst einrichten möchten 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 sie 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 Computer einrichten
• Sie werden das App-Store-Verzeichnis erstellen, wenn Sie es noch nicht getan haben
• Sie werden in der Lage sein, Probleme im Build-Prozess zu erkennen, die mit Ihrer App code zusammenhängen

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

Die Verteilungszertifizierung einrichten

1. Xcode öffnen

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

   

3. Zu Accounts

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

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

6. Klicken Sie auf den Manage Certificates... 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. Ich werde mich in diesem Tutorial nicht damit befassen.

   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 Verteilungszertifikat installiert haben, können Sie den Build-Prozess beginnen.

Manueller Build zu TestFlight

1. Öffnen Sie die App in Xcode

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

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

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

   

3. Warten Sie, bis der Build abgeschlossen ist

4. Klicken Sie auf den Distribute App Schaltfläche

   

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

   

6. Konfigurieren Sie das App-Record

   Füllen Sie die folgenden Felder aus:

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

   Klicken Sie dann auf den next button

   

7. Wenn die Erstellung der App-Datei 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 gelaufen ist, sollten Sie die folgende Seite sehen

10. Klicken Sie auf den Done button

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

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

Lassen Sie uns mit dem ersten beginnen:

Sich selbst bei TestFlight hinzufügen

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

2. Sign in with your Apple Developer account

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

4. Klicken Sie auf den Apps Button

5. Finden Sie das von Ihnen im vorherigen Schritt erstellte App und klicken Sie darauf

6. Klicken Sie auf den TestFlight Button

7. Klicken Sie auf den Internal Testers plus Button

8. Neue Gruppe erstellen

   Ich bevorzuge es, der Gruppe den Namen „interne Tester“ zu geben. Du kannst sie gerne anders benennen.

   

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 wählen Sie das Häkchen neben Ihrem Namen aus. (Sie müssen sich möglicherweise neu anmelden, um sich selbst zu sehen) Dann klicken Sie auf die Add Schaltfläche.

    

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

    Now, you should see yourself in der Gruppe.

    

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

Einstellungen für die Einhaltung der Vorschriften

Sie müssen nun Apple versprechen, dass Ihre App keine nicht standardmäßige (wie ein benutzerdefiniertes Algorithmus) Verschlüsselung verwendet. Wenn Ihre App tatsächlich nicht standardmäßige Verschlüsselung verwendet, empfehlen wir Ihnen, die Dokumentation von Apple 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 so konfigurieren, dass dieser Wert automatisch auf false.

Setzt werden kann.

1. Lasst uns mit der ersten Möglichkeit beginnen: ‘Follow all the steps from the previous section to find the TestFlight section in App Store Connect’

2. Klicken Sie auf Builds -> iOS

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

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

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

   

5. Ihre App sollte jetzt sagen ready to test

   

Wenn es um den zweiten geht, hier sind die Schritte:

1. Öffnen Sie Info.plist Datei

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

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

3. Datei speichern

Hinweis

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

Die Installation der TestFlight-App und die Annahme der Einladung

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

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

Die Einladung zur Testung Ihrer App akzeptieren

Ich werde die Details zur 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.

1. Bezüglich der Akzeptanz der Einladung erhalten Sie eine E-Mail von Apple mit einem Link, um die Einladung anzunehmen.

2. Die E-Mail von Apple mit dem Link zur Akzeptanz der Einladung öffnen View in TestFlight Auf den

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

4. Die App auf Ihrem Gerät installieren

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

5. Warten Sie, bis die App installiert ist

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

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 in TestFlight zu bauen und zu übermitteln.

Konfigurieren Sie Capgo Native Build

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

Hier ist eine Liste der Dinge, die Sie an den __CAPGO_KEEP_1__ __CAPGO_KEEP_2__ übergeben werden:	Parameter
--platform	Beschreibungios)
--apple-team-id	Die Plattform, für die Sie bauen möchten ( Dein Apple-Entwickler-Team-ID (in der)
--apple-key	Path to your App Store Connect API Key file (.p8 Weg zu deinem App Store Connect __CAPGO_KEEP_0__-Sicherheitszertifikat (
--apple-key-id	The Key ID of your App Store Connect API Key
--apple-issuer-id	Die Key-ID deines App Store Connect __CAPGO_KEEP_0__-Sicherheitszertifikats
--certificate	Deine App Store Connect Aussteller-ID.p12 Weg zu deinem Verteilungszertifikat (
--ios-provisioning-profile	Profilzumordnungsmappe (bundleId=path oder einfach Pfad für einzelnes Profil)

Beispiel-Befehl:

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

Team-ID

Lassen Sie uns mit der Team-ID beginnen. Sie ist ziemlich einfach 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 nächsten Schritt: Der Apple-Schlüssel

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

Bei macOS können Sie capgo build init 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 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 folgenden manuellen Schritte sind die Alternative (und der Weg auf Windows oder Linux).

1. Zum App Store Connect-Benutzer- und Zugriffsbereich gehen Zum App Store Connect-Benutzer- und Zugriffsbereich gehen

   Hinweis

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

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

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

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

4. App Store Connect-Integrationen-Button issuer

   Achtung

   Dies MUSSEN SIE SICH DAS MERKEN - 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 fest und legen Sie den Zugriff fest App manager und klicken Sie auf den Generate Button

7. Sparen Sie die Schlüssel-ID

   Vorsicht

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

   

8. Herunterladen Sie den Schlüssel

   Vorsicht

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

   Gefahren

   NEHMEN SIE DIE SCHLÜSSEL NICHT MIT JEDERMANN TEIL - BENUTZEN SIE ES NUR IN DEM CAPGO CLI

   

   

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

Zertifikat

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

Es ist jedoch so, dass Apple in ihrer unendlichen Weisheit entschieden hat, dass die Art und Weise, wie Sie das Zertifikat exportieren, sich erheblich von der Art und Weise unterscheidet, wie Sie sie erstellen 🙃 Lassen Sie uns es auf die folgende Weise einrichten:

1. Öffnen Sie den Schlüsselkartenzugriff

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

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

3. Finden Sie Ihr Zertifikat in der Liste

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

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

5. Speichern Sie das Zertifikat als ein .p12 Datei

   Vorsicht

   Dies MUSS GESPEICHERT WERDEN - Sie werden es später benötigen

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

   

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

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

   

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

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

   

Herzlichen Glückwunsch 🎉 Sie haben das Zertifikat exportiert.

Provisionierungsprofil

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

1. Gehe zu Apple-Entwickler-Profilen

2. Wählen Sie das richtige Team aus dem 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 das Profiltyp Wählen Sie App Store Connect und klicken Sie auf die Continue Schaltfläche

   

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

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

   

7. Wählen Sie das richtige Verteilungszertifikat

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

   

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

   

8. Benennen Sie das Profil

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

   Tip

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

   

9. Das Profil herunterladen

   Klicken Sie auf den Download Button zum Herunterladen des Profils

   Vorsicht

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

   

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

Vorsicht

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

Ausführen der Konfigurationskommandos

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

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

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

Wertplätze ersetzen

Werte der oben stehenden Platzhalter durch Ihre tatsächlichen Anmeldeinformationen ersetzen, die Sie in den vorherigen Schritten gesammelt haben:

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

Wenn alles gut gelaufen ist, sehen Sie folgendes Ausgabe:

Apple-Berechtigungen fehlgeschlagen? Synchronisiere deinen Kalender

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

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

CI/CD-Einrichtung (GitHub Actions)

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

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

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

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

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

Tipps

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

2) Repository-Secrets erstellen

Im GitHub > Repository > Settings > Secrets and variables > Actions, fügen Sie hinzu:

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

Running the build

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

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

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

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

Zur App Store-Überprüfung einreichen

Die normale App Store Build-Pfad lädt das Build in App Store Connect/TestFlight hoch. Wenn Ihre CI-Release 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 einem Release-Build:

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

Dazu sind die App Store Connect API-Schlüssel (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, und APP_STORE_CONNECT_TEAM_ID) erforderlich. App-spezifische Passwörter und ad_hoc die Verteilung können kein Build zur Überprüfung einreichen. --store-release-name ist die App Store-Version; wenn nicht angegeben, Capgo liest MARKETING_VERSION aus dem Xcode-Projekt. --store-release-notes ist die App Store-Fallback-What’s New-Tex, und jede --store-release-notes-locale "locale=notes" Eintrag kann es für eine Veröffentlichungslokalisierung überschreiben. --ios-automatic-release nach Apple-Zustimmung automatisch freigeben oder --no-ios-automatic-release bis zu einer manuellen Freigabe warten. --ios-testflight-groups ist weiterhin für externe Beta-Distribution verfügbar, wird aber nicht für die Einreichung bei der App Store-Bewertung benötigt.

Ad-Hoc-Verteilungsmodus

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

Hinweis

Ad-hoc-Verteilung ist nicht gleichbedeutend mit Enterprise (In-Haus)-Verteilung. Enterprise-Verteilung erfordert ein separates Apple-Entwickler-Enterprise-Konto und verwendet unterschiedliche Berechtigungsprofile. Capgo unterstützt derzeit app_store und ad_hoc nur in diesen Modi.

Wenn Sie den Ad-hoc-Modus verwenden sollen

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

Anforderungen

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

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

Hinweis

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

Vorsicht

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

Ein ad-hoc-Beitrittsprofil erstellen

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

1. Gehe zu Apple-Entwickler-Profile
2. Klicke auf + Schaltfläche
3. Wähle aus Ad hoc und klicken Sie auf Fortsetzen
4. Wählen Sie Ihr App und Verteilungszertifikat
5. Wählen Sie die Geräte, 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-id, oder --apple-issuer-id erforderlich.

Einzelbuild ausführen

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

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

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

CI/CD mit Einzelbuilds

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

github/workflows/ios-adhoc-build.yml

name: iOS Ad-Hoc Build

on:
  workflow_dispatch:

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

Hinweis

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

Apps mit Erweiterungen (Multi-Target-Signing)

Wenn Ihre App Erweiterungen (z.B. Teilen-Erweiterungen, Widgets, Benachrichtigungsdienst-Erweiterungen usw.) enthält, benötigt jeder Erweiterungsziel 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 Jeder Flag ist einer Bundle-ID zugeordnet und stellt die entsprechende Provisionierungsvorlage-Datei dar. 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 einzelnes CAPGO_IOS_PROVISIONING_MAP Kredit

Tipp

Sie benötigen ein Verteilungszertifikat für alle Ziele – nur die Provisionierungsvorlagen unterscheiden sich pro Ziel.

Migration von Single Profile

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

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

Dies wandelt Ihre bestehenden Single-Profil-Anmeldeinformationen in die neue CAPGO_IOS_PROVISIONING_MAP Format um 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) 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 save Sie 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 passiert, weil Sie eine neue Funktion nach der Erstellung des Provisioning-Profils aktiviert haben. Das alte Provisioning-Profil enthält die neue Funktion noch nicht.

Um dies zu beheben, müssen Sie das Provisioning-Profil neu erstellen.

1. Öffnen Apple-Entwicklerportal
2. Wählen Sie das richtige Team aus dem Dropdown-Menü
3. Klicken Sie auf den Profiles Schaltfläche
4. Suchen Sie das Provisioning-Profil, das Sie neu erstellen möchten
5. Klicken Sie auf den Edit button
6. Klicken Sie auf den Save button
7. Klicken Sie auf den Download button
8. Führen Sie den Capgo Native Build-Einrichtungsbefehl erneut aus mit dem neu heruntergeladenen Profil.

Dies sollte das Problem beheben.

Weitere Probleme

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

Weitermachen von iOS Builds

Wenn Sie "iOS Builds" für die Planung der CI/CD-Automatisierung verwenden, verbinden Sie es mit __CAPGO_KEEP_0__ CI/CD für den Produktworkflow in __CAPGO_KEEP_0__ CI/CD, Capgo Native Builds für den Produktworkflow in Capgo Native Builds Wenn Sie für irgendeinen Grund Probleme haben, sei es mit Capgo Native Build, der Konfiguration der Anmeldeinformationen oder dem Aufbau der App, zögern Sie bitte nicht, uns über unsere for the product workflow in Capgo Native Builds, Capgo Integrations für den Produktworkflow in Capgo Integrations, CI/CD-Integration für die Implementierungsdetails in CI/CD-Integration, und GitHub Actions-Integration für die Implementierungsdetails in GitHub Actions-Integration.