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 wenn nicht)
• A Mac Computer mit Xcode installiert (Es ist möglich, die Build-Einrichtung auf einem Linux/Windows-Maschine vorzunehmen, aber es ist noch nicht dokumentiert)
• Eine gültige Apple-Entwicklerkonto (99 $/Jahr) (Sie müssen Admin- oder Eigentümerrechte auf dem Apple-Entwicklerkonto haben)
• Ihr 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 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 Apples Vereinbarungen zu binden
• Verwenden Sie ein Konto, das Zugriff auf beide Apple Developer und App Store Connect für Zertifikate, App-Records, API-Schlüssel und TestFlight hat
• Sicherzustellen, dass Ihr End-Bundle-ID frühzeitig festgelegt ist. Ändern Sie es später, wenn möglich, bedeutet, dass die App Store-Einrichtung neu durchgeführt werden muss
• Planen Sie diese App Store Connect-Elemente vor der App-Überprüfung: Support-URL, Datenschutzrichtlinien-URL, Altersfreigabe, Screenshots, Export-Kompliance und Kontaktdaten für die App-Überprüfung

Hinweis

Nützliche offizielle Referenzen:

• Become a Member of the Apple Developer Program
• Submit your Apps und Spiele
• 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

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

Der erste manuelle Build

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

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

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

Einrichten des Verteilungszertifikats

1. Xcode öffnen

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

   

3. Zu Accounts

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

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

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

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

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

   Hinweis

   Apple beschränkt die Anzahl der Verteilungszertifikate, die Sie haben können, auf 3. Wenn Sie mehr als 3 Zertifikate haben, müssen Sie eines löschen, um ein neues zu erstellen. Ich werde mich nicht auf das in diesem Tutorial einlassen.

   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. Ausführen

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

2. Schaltfläche archive In der Xcode-Leiste finden und auf die

   Manueller Build zum TestFlight product -> archive Button.

   

3. Warten Sie, bis der Aufbau abgeschlossen ist

4. Klicken Sie auf den Distribute App Button

   

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

   

6. Konfigurieren Sie das App-Record

   Füllen Sie die folgenden Felder aus:

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

   Dann klicken Sie auf den next Schaltfläche

   

7. Wenn die Erstellung des App-Verlaufs 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 die Done Schaltfläche

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. Sich selbst in TestFlight hinzufügen
2. Die Exportkonzessionen abschließen, damit die Veröffentlichung testbar wird
3. Die erforderlichen App Store Connect-Metadaten wie Ihre Support-URL, Ihre Datenschutzrichtlinie-URL und Ihre Altersfreigabe eintragen
4. Vorbereiten Sie Screenshots, die den von Ihnen unterstützten Geräten entsprechen
5. Hinzufügen Sie die Kontaktinformationen für App Review und alle Testanmeldeinformationen, bevor die Produktionsabgabe erfolgt

Lassen Sie uns mit dem ersten beginnen:

Sich selbst in TestFlight hinzufügen

1. Gehen Sie zur App Store Connect Seite

2. Mit Ihrem Apple-Entwicklerkonto anmelden

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

4. Klicken Sie auf den Apps Schaltfläche

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

6. Klicken Sie auf den TestFlight Schaltfläche

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

8. Eine neue Gruppe erstellen

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

   

9. Klicken Sie auf Invite testers Schaltfläche

10. Fügen Sie sich selbst der Gruppe hinzu

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

    

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

    Jetzt sollten Sie sich selbst in der Gruppe sehen.

    

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

Einrichten der Compliance-Informationen

Sie müssen 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, die sich mit der Behandlung dieses Themas beschäftigt. 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. Folgen Sie allen Schritten aus der vorherigen Abschnitt, um die TestFlight-Sektion in App Store Connect zu finden

2. Klicken Sie auf Builds -> iOS

3. Finden Sie 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 noneAber es könnte für Sie anders sein. Klicken Sie dann auf Speichern

   

5. Ihre App sollte jetzt sagen ready to test

   

Was das zweite betrifft, hier sind die Schritte:

1. Öffnen Sie das Info.plist Datei

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

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

3. Speichern Sie die Datei

Hinweis

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

Die Installation der TestFlight-App und das Annnehmen der Einladung

Jetzt bist du Fast fertig bereit, deine App in TestFlight zu testen. Bevor du loslegst, musst du noch folgende Schritte ausführen:

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

Ich werde die Details, wie man die TestFlight-App auf Ihrem Gerät installiert, überspringen. Wenn Sie sich nicht sicher sind, wie man eine App installiert, hat Google einige großartige Anleitungen, wie man es macht.

Wenn es um die Akzeptierung der Einladung geht, 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 den Button

3. Klicken Sie auf den Install Button

4. Installieren Sie die App auf Ihrem Gerät

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

5. Warten Sie, bis die App installiert ist

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

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

Configuring 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:

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-Entwickler-Portal)
--apple-key	Pfad zu Ihrem App Store Connect Capgo-Zertifikats-API-Key-Datei (.p8 Datei)
--apple-key-id	Die Key-ID Ihres App Store Connect Capgo-Zertifikats-API-Key
--apple-issuer-id	Ihre App Store Connect Aussteller-ID
--certificate	Pfad zu Ihrem Verteilungszertifikat (.p12 Datei)
--ios-provisioning-profile	Zuordnung von Provisioning-Profilen (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

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

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

2. Finden Sie die Team ID

   

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

Zum Apple-Schlüssel wechseln wir nun

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

Auf einem macOS-System capgo build init Können Sie diese App Store Connect API-Schlüssel für Sie erstellen. Wählen Sie ‚Nein — erstelle einen für mich‘ und eine leitende Fensteröffnung öffnet 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 stehenden manuellen Schritte sind die Alternative (und der Weg auf Windows oder Linux).

1. Gehe zu Benutzer- und Zugriffsberechtigungen für App Store Connect

   Hinweis

   Für mich funktioniert der Link manchmal nicht. Wenn er auch 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 SPEICHERN SIE DAS! Sie werden es später benötigen Klicken Sie auf den Button, um den Herausgeber zu kopieren

   App Store Connect Herausgeber kopieren copy Klicken Sie auf den Plus-Button

5. Setzen Sie den Namen des Schlüssels und setzen Sie den Zugriff auf

6. Setzen Sie den Namen des Schlüssels und setzen Sie den Zugriff auf App manager und klicken Sie auf den Generate Schaltfläche

7. Sparen Sie den Schlüssel-ID

   Vorsicht

   Dies SICH BEWAHREN - Sie benötigen es später App Store Connect-Schlüssel-ID kopieren

   

8. Vorsicht

   Vorsicht

   Dies SICHER HEITEN SIE DAS Sie benötigen es später

   Gefahr

   TEILEN SIE DEN SCHRITT NICHT MIT JEDERMANN - BENUTZEN SIE ES NUR IN DER 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 erinnern, war die Einrichtung des Verteilungs-Zertifikats eines der ersten Schritte dieser Anleitung.

Allerdings hat Apple in ihrer unendlichen Weisheit entschieden, dass die Art und Weise, wie Sie das Zertifikat exportieren, sich erheblich von der Art und Weise unterscheidet, wie Sie sie erstellen.

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 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 SPEICHERN - 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 Button

   

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. Passwort-geschü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 Sie zum "Login-Keychain-Passwort" gefragt werden, geben Sie das Passwort ein, das Sie zum Anmelden an Ihrem Mac verwenden

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

   

Herzlichen Glückwunsch 🎉 Sie haben das Zertifikat exportiert.

Zertifikatsprofil

Abschnitt mit der Überschrift "Zertifikatsprofil"

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

2. Apple-Entwickler-Profilen

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

   

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

   Finden Sie Ihre App im Dropdown-Menü und klicken Sie auf den Continue 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 Ablaufzeit an.

   

8. Benennen Sie das Profil

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

   Tipps

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

   

9. Herunterladen Sie das Profil

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

   Vorsicht

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

   

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

Vorsicht

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

Ausführen der Konfigurationsanweisung

Sie haben es geschafft! Sie haben jetzt alles, was Sie zum Konfigurieren von Capgo Native Build benötigen.

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

Wenn alles gut ging, sehen Sie folgende Ausgabe:

Authentifizierung bei Apple fehlgeschlagen? Synchronisiere deinen Uhrzeiger

Wenn das App Store Connect-Schlüssel API korrekt aussieht, aber die Authentifizierung immer noch fehlschlägt, synchronisiere deinen Computer-Uhrzeiger 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 Uhrzeiger, 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 Uhrzeigersynchronisierung

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 ProvisionierungsprofilSie haben bereits alles, was Sie für CI/CD benötigen. Dieser Abschnitt beschreibt nur, wie Sie diese Werte als GitHub Actions-Secrets und Umgebungsvariablen übergeben.

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

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

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

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

Tipp

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

2) Erstelle Repository-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-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 — kopieren Sie von .capgo-credentials Datei
APPLE_KEY_CONTENT	Inhalt von apple_key_base64.txt
P12_PASSWORD (optional)	Ihr .p12 Passwort, wenn es während der Exportierung gesetzt wurde

3) Verwenden Sie Umgebungsvariablen in Ihrem GitHub Actions-Workflow

/github/workflows/ios-build.yml

name: iOS Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

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

Tip

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

Der Build ausführen

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

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

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

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

App Store-Bewerbung einreichen

Der normale App Store-Build-Weg lädt das Build in App Store Connect/TestFlight hoch. Wenn Ihre CI-Veröffentlichung auch die bearbeitete TestFlight-Build zum App Store-Veröffentlichung und zur App-Review-Übermittlung anhängen soll, geben Sie --submit-to-store-review mit einer Veröffentlichungsbuild:

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 App Store Connect API-Schlüssel-Zugriffsberechtigungen erforderlich (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, und APP_STORE_CONNECT_TEAM_ID). App-spezifische Kennwort-Uploads und ad_hoc die Verteilung können eine Build-Überprüfung nicht einreichen. --store-release-name ist die App Store-Version; wenn diese weggelassen wird, liest Capgo MARKETING_VERSION die App Store-Version 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 Apple-Zustimmung freizugeben, oder --no-ios-automatic-release um auf eine manuelle Freigabe zu warten. --ios-testflight-groups ist zwar noch für externe Beta-Verteilung verfügbar, aber nicht erforderlich für die Einreichung bei der App-Store-Bewertung.

Ad-Hoc-Verteilungsmodus

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

Hinweis

Die Ad-hoc-Verteilung ist Not gleich wie Enterprise (In-House) Verteilung. Enterprise Verteilung erfordert einen separaten Apple Developer Enterprise Account und verwendet unterschiedliche Provisionierungsprofile. __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: 'Wann Sie ad-hoc-Modus verwenden sollten'

• Sie haben keinen oder möchten keinen 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: '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)	Nein
Apple Key ID / Aussteller ID	Nein

Hinweis

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

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

1. App Store Zum
2. Apple-Entwickler-Profilen + Schaltfläche
3. Auswählen Ad Hoc und klicken Sie auf Fortfahren
4. Wählen Sie Ihre App und Ihr 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-id, oder --apple-issuer-id benötigt.

Ein ad-hoc-Build ausführen

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

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

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

CI/CD mit ad-hoc-Builds

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

.github/workflows/ios-adhoc-build.yml

name: iOS Ad-Hoc Build

on:
  workflow_dispatch:

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

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 seinen eigenen Provisioning-Profil. Capgo unterstützt dies über die wiederholbare --ios-provisioning-profile Flag.

Beispiel: App + Teilen-Erweiterung

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

Jeder --ios-provisioning-profile Die Flagge entspricht einem Bundle-ID und ihrem entsprechenden Profil-Datei. Die CLI:

1. 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-Zertifikate in die neue CAPGO_IOS_PROVISIONING_MAP Format 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"

Tipp

Verwenden Sie update (nicht save) um Profile zu vorhandenen Anmeldeinformationen hinzuzufügen. Die update Kommandozeilenanweisung fügt neue Profile den bestehenden hinzu. 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 Zertifikatsprofils aktiviert haben. Das alte Zertifikatsprofil enthält die neue Funktion noch nicht.

Um dies zu beheben, müssen Sie das Zertifikatsprofil neu erstellen.

1. Öffnen Apple-Entwicklerportal
2. Wählen Sie die richtige Team-Option im Dropdown-Menü aus
3. Klicken Sie auf den Profiles Button
4. Suchen Sie das Zertifikatsprofil, das Sie neu erstellen möchten
5. Klicken Sie auf den Edit Schaltfläche
6. Klicken Sie auf den Save Schaltfläche
7. Klicken Sie auf den Download Schaltfläche
8. Re-run the Capgo Native Build setup command Klicken Sie auf den

Dies sollte das Problem beheben.

Weitere Probleme

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

Weiterhin von iOS Builds

Wenn Sie iOS Builds 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 für das Produktworkflow in Capgo Native Builds Capgo Integrations für das 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