iOS-Builds

Mit Capgo’s dedizierter Mac-Infrastruktur können Sie iOS-Apps auf TestFlight und dem App Store bereitstellen.

Was Sie lernen werden

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

Voraussetzungen

• Ein Capgo-Konto mit einer aktiven Abonnement
• Ihr App ist bereits in Capgo registriert (führen Sie bitte "run" aus, wenn nicht) bunx @capgo/cli@latest app add Wenn nicht registriert
• Ein Mac-Computer mit Xcode installiert (es ist möglich, die Build-Einrichtung auf einem Linux/Windows-Maschine zu erstellen, aber dies ist noch nicht dokumentiert)
• Ein gültiger Apple-Entwickler-Account (99 $/Jahr) (Sie müssen Admin- oder Eigentümerrechte auf dem Apple-Entwickler-Account haben)
• Ihre App muss erfolgreich über Xcode gebaut werden können
• Eine Capacitor-App
• Ein für die App konfiguriertes Icon. Apps ohne ein Icon können nicht auf dem App Store hochgeladen werden

Hinweis

Für diese Anleitung werde ich die folgende App verwenden https://github.com/Cap-go/capgo-native-build-tutorial-app

Bevor Sie beginnen in Apples Portal

Bevor Sie Zertifikate einrichten oder Ihre erste Testflug-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:
  • Einzelunternehmen / Einzelunternehmer: Ihr rechtlicher Name wird zum Verkäufernamen auf dem App Store
  • Organisation: Erfordert eine juristische Person, eine D-U-N-S-Nummer, eine öffentliche Unternehmenswebsite, eine E-Mail-Adresse auf dem Unternehmensdomän und eine Person mit der Befugnis, die Organisation zu Apples Vereinbarungen zu binden
• Verwenden Sie ein Konto, das Zugriff auf beide Apple Developer und App Store Connect für Zertifikate, App-Records, API-Schlüssel und Testflug hat
• Bewahren Sie Ihren finalen Bundle-ID frühzeitig auf. Ändern Sie sie später, wenn möglich, bedeutet normalerweise, dass Sie die App Store-Einrichtung neu konfigurieren müssen
• Planen Sie diese App Store Connect-Einträge vor der App-Überprüfung: Unterstützungs-URL, Datenschutzrichtlinien-URL, Altersfreigabe, Screenshot, Exportkonzession und App-Überprüfungs-Kontaktinformationen

Hinweis

Nützliche offizielle Referenzen:

• Wählen Sie die Apple-Entwickler-Programm-Mitgliedschaft
• Hinweis
• Plattformversioneninformationen in App Store Connect

Vorsicht

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

Die erste manuelle Erstellung

Before we can start thinking about building the app with Capgo, we should first set it up, and do a first TestFlight build by hand. There are some advantages to doing a manual build first:

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

Bevor wir beginnen können, müssen Sie die Verteilungszertifizierung auf Ihrem lokalen Computer installiert haben.

Zur Verteilungszertifikatskonfiguration einrichten

1. Xcode öffnen

2. Klicken Sie auf Xcode -> Settings... Alternativ können Sie den Schnellzugriff 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 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 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 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 um die App in Xcode zu öffnen.

2. Finden und auf den archive Schaltfläche

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

   

3. Warten Sie, bis die Veröffentlichung abgeschlossen ist

4. Klicken Sie auf den Distribute App Button

   

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

   

6. Konfigurieren Sie das App-Verzeichnis

   Füllen Sie die folgenden Felder aus:

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

   Klicken Sie dann auf den next button

   

7. Wenn die Erstellung des App-Records fehlschlägt, versuchen Sie, das Fenster zu schließen und das Archivieren der App erneut zu versuchen.

8. Warten Sie, bis der Upload abgeschlossen ist

9. Wenn alles gut ging, sollten Sie die folgende Bildschirmansicht sehen

10. Klicken Sie auf den Done Sie denken vielleicht instinktiv, dass jetzt alles in Ordnung ist und Sie Ihre App in TestFlight sehen können, aber es gibt noch ein paar Dinge, die noch erledigt werden müssen:

Fügen Sie sich selbst zu TestFlight hinzu

1. button
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 Datenschutzrichtlinien-URL und Ihre Altersbeschränkung aus
4. Vorbereiten Sie Screenshots, die den von Ihnen 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. Geht zu dem App Store Connect-Seite App Store Connect-Anmeldeseite

2. Geht zu App Store Connect

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 App Store Connect-Team-Button

5. App Store Connect-Appauswahl

6. App Store Connect-Testflug-Button TestFlight Klicken Sie auf den

7. Klicken Sie auf den Internal Testers plus App Store Connect-App-Button

8. Eine neue Gruppe erstellen

   Ich bevorzuge es, der Gruppe den Namen „interne Tester“ zu geben. Du kannst sie jedoch nennen, wie du willst.

   

9. Klicken Sie auf Invite testers Schaltfläche

10. Fügen Sie sich selbst der Gruppe hinzu

    Finden Sie sich selbst in der Liste und wählen Sie das Kontrollkästchen 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

    Jetzt solltest du dich selbst 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.

Einrichtung der Compliance-Informationen

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

1. Du kannst dies jede Zeit, wenn du deine App baust, manuell tun.
2. Du kannst deine plist-Datei so einrichten, dass dieser Wert automatisch gesetzt wird. false.

Lass uns mit der ersten 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 das Build mit fehlender Compliance-Information und klicken Sie auf Manage

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

   Für mich ist 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

   

Was die zweite Option betrifft, hier sind die Schritte:

1. Öffnen Sie das Info.plist Datei

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

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

3. Die Datei speichern

Hinweis

Hier Hier finden Sie die offizielle Apple-Dokumentation zur Einhaltung von Verschlüsselungsexportvorschriften bei Apple.

Die TestFlight-App installieren und die Einladung akzeptieren

Jetzt bist du Fast da 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

aus dem App Store auf Ihrem iOS/iPadOS-Gerät herunterladen

1. Die Einladung zu Ihrer App akzeptieren

2. 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. View in TestFlight Sie erhalten eine E-Mail von Apple mit einem Link, um die Einladung zu akzeptieren.

3. Auf den "Link"-Button klicken Install Button

4. Die App auf Ihrem Gerät installieren

   Wenn Sie die App zuvor mit Xcode installiert haben, sehen Sie möglicherweise die folgende Seite. Klicken Sie bitte auf den install Button.

5. Warten Sie, bis die App installiert ist

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

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

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 ( Ihre Apple-Entwickler-Team-ID (in der)
--apple-key	Path to your App Store Connect API Key file (.p8 Pfad zu Ihrem 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 Ihres App Store Connect __CAPGO_KEEP_0__-Sicherheitszertifikats
--certificate	Ihre App Store Connect Aussteller-ID.p12 Pfad zu Ihrem Verteilungszertifikat (
--ios-provisioning-profile	Zuweisungsprofil-Abbildung (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

1. Zum App Store Connect-Benutzer- und Zugriffsbereich

   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 Ihr Benutzerkonto 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. Finden Sie das issuer

   Vorsicht

   Dies __CAPGO_KEEP_0__ - Sie benötigen es später

   Klicken Sie auf den copy Schaltfläche, um den Aussteller zu kopieren

5. Klicken Sie auf das Plus-Button

6. Legen Sie den Namen des Zertifikats fest und legen Sie den Zugriff auf App manager und klicken Sie auf den Generate Button

7. Speichern Sie die Zertifikats-ID

   Vorsicht

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

   

8. Laden Sie die Schlüssel herunter

   Vorsicht

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

   Gefahr

   TEILE DEN SCHLÜSSEL NICHT MIT JEDERMANN - BENUTZE ES AUSNICHTS IN DEN CAPGO CLI

   

   

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

Zertifikat

Jetzt sind Sie bereit, das Zertifikat auszuführen. Wie Sie sich vielleicht erinnern, war eine der ersten Schritte dieses Leitfadens die Einrichtung des Verteilungszertifikats.

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 🙃 Lassen Sie uns es auf die folgende Weise einrichten:

1. Öffnen Sie Keychain Access

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

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

3. Finden Sie Ihr Zertifikat in der Liste

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

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

5. Speichern Sie das Zertifikat als ein .p12 Datei

   Vorsicht

   Dies __CAPGO_KEEP_0__ - Sie benötigen es später

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

   

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

   • Das Passwort überspringen (empfohlen für Einfachheit): Klicken OK ohne Eingabe eines Passworts
   • Passwort setzen: Wenn Sie Ihr Zertifikat mit einem Passwort schützen möchten, können Sie eines hier setzen. Passwortgeschützt .p12 Dateien werden vollständig vom Capgo CLI unterstützt - geben Sie einfach das Passwort mit der --p12-password Option an, wenn Sie die Konfigurationskommando ausführen.

   

7. Wenn Sie nach dem „Anmelde-Schlüsselkettenschlüssel“ gefragt werden, geben Sie das Passwort ein, das Sie zum Anmelden an Ihrem Mac verwenden.

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

   

Glückwunsch 🎉 Sie haben das Zertifikat exportiert.

Provisionierungsprofil

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

1. Gehe zu Apple-Entwickler-Profil

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

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

3. Stelle sicher, dass du auf der richtigen Seite bist Es sollte so aussehen, wenn es nicht so aussieht, klicke auf profiles in der Seitenleiste

   

4. Klicke auf den + Button

5. Wählen Sie den Profiltyp Wählen Sie App Store Connect und klicken Sie auf den Continue Button

   

6. Wählen Sie das App-Entwicklungsprojekt aus

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

   

7. Wählen Sie das richtige Verteilungs-Zertifikat

   Wählen Sie das Zertifikat aus, 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 den Ablaufdatum an.

   

8. Name des Profils

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

   Der Profilname wird automatisch durch die __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ extrahiert – Sie müssen es sich nicht merken.

   The profile name is automatically extracted by the Capgo CLI — you don’t need to remember it.

   

9. Klicken Sie auf den

   Apple Developer Auswahl des Verteilungs-Zertifikats Download Button zum Herunterladen des Profils

   Vorsicht

   Dieses Datei WIRD ZU SPEICHERN - Sie werden sie später benötigen

   

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

Vorsicht

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

Ausführen der Konfigurationskommando

Du hast es geschafft! Du hast jetzt alles, was du zum Konfigurieren von Capgo Native Build benötigst.

Das Kommando, das du ausführen musst, 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

Ersatzwerte für Platzhalter ersetzen

Ersetze die oben stehenden Platzhalterwerte durch deine tatsächlichen Anmeldeinformationen, die du in den vorherigen Schritten gesammelt hast:

• --apple-team-id: Deine Apple-Team-ID
• --apple-key: Pfad zu deinem heruntergeladenen .p8 : Dein Apple-Schlüsseldatei
• --apple-key-id: Deine Apple-Schlüssel-ID
• --apple-issuer-id: Dein Apple-Aussteller-Id
• --certificate: Pfad zu deinem exportierten .p12 zertifikat
• --ios-provisioning-profile: Pfad zu deinem heruntergeladenen .mobileprovision Datei (Bundle-Id wird für einzelne Profile automatisch ermittelt)

Wenn alles gut ging, sehen Sie folgende Ausgabe:

CI/CD-Einrichtung (GitHub Actions)

Wenn Sie bereits die 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

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

Das Bauen ausführen

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

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 die gleiche wie Enterprise (In-Haus)-Verteilung. Enterprise-Verteilung erfordert ein separates Apple-Entwickler-Enterprise-Konto und verwendet unterschiedliche Bereitstellungsprofile. Capgo unterstützt derzeit app_store und ad_hoc Modi nur.

Wann ad-hoc-Modus verwenden

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

Anforderungen

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

Zertifikat	Erforderlich?
Distributionszertifikat (.p12)	Ja
Ad-hoc-Provisionierungsprofil (.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 sind nicht unterstützt und werden ignoriert. Dies ist der Grund, warum die beiden App Store Connect Zeilen oben keine ad-hoc CLI Flags anzeigen; diese Optionen gelten nur für app_store Modus nur.

Vorsicht

Ohne einen App Store Connect API-Schlüssel verwendet die automatische Inkrementierung der Build-Nummer einen timestamp-basierten Ausfall. Um die Warnung zu unterdrücken, übergeben Sie --skip-build-number-bump.

Erstellung eines ad-hoc-Beitrittsprofils

Folgen Sie den gleichen Schritten wie Beitrittsprofil, aber in Schritt 5 wählen Sie Ad-hoc anstatt App Store:

1. Zu Apple-Entwicklerprofile
2. Klicken Sie auf den + Schaltfläche
3. Wählen Sie Ad Hoc und klicken Sie auf Weiter
4. Wählen Sie Ihr App und Verteilungszertifikat
5. Wählen Sie die Geräte aus, die Sie registrieren möchten
6. Benennen und herunterladen Sie das Profil

Ad-hoc-Zugangsdaten speichern

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.

Einzelne Ad-hoc-Builds ausführen

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

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

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

CI/CD mit ad-hoc-Builds

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

github/workflows/ios-adhoc-build.yml

name: iOS Ad-Hoc Build

on:
  workflow_dispatch:

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

Tipp

Beachten Sie, dass APPLE_KEY_ID, APPLE_ISSUER_IDund APPLE_KEY_CONTENT für ad-hoc-Builds nicht benötigt werden.

Apps mit Erweiterungen (Multi-Target-Signing)

Wenn Ihre App Erweiterungen (Teilen-Erweiterungen, Widgets, Benachrichtigungs-Service-Erweiterungen usw.) enthält, benötigt jede Erweiterungsziel eine eigene Provisionierung-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"

Flag stellt eine Bundle-ID auf ihren Provisionierung-Profil-Datei zu. Der __CAPGO_KEEP_0__: --ios-provisioning-profile flag maps a bundle ID to its provisioning profile file. The CLI:

1. Auto-extrahiert den Profilnamen aus dem eingebetteten plist
2. Auto-extracts the profile name from the embedded plist
3. Base64-codiert das Datei
4. Alles als ein einzelnes CAPGO_IOS_PROVISIONING_MAP Kreditkarte

Tipp

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

Migration von Single Profile

Wenn Sie zuvor BUILD_PROVISION_PROFILE_BASE64 (Single Profile) ausgeführt haben, führen Sie:

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

Dies wandelt Ihre bestehenden Einzelprofil-Anmeldeinformationen in die neue Format um und entfernt die Legacy-Schlüssel ( CAPGO_IOS_PROVISIONING_MAP Nach der Migration fügen Sie Erweiterungsprofile mit demBUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Befehl (additiver Merge) hinzu: update Terminalfenster

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

Verwenden Sie

(nicht update ) um Profile zu bestehenden Anmeldeinformationen hinzuzufügen. Der saveBefehl kombiniert neue Profile mit bestehenden. Verwenden Sie update Sie save nur wenn Sie alle Anmeldeinformationen von vorne beginnen.

Fehlersuche

Der Bereitstellungsprofil enthält nicht die 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 Fähigkeit aktiviert haben, nachdem das Bereitstellungsprofil erstellt wurde. Das alte Bereitstellungsprofil enthält die neue Fähigkeit noch nicht.

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

1. Öffnen Apple-Entwicklerportal
2. Wählen Sie das richtige Team aus dem Dropdown-Menü
3. Klicken Sie auf den Profiles Button
4. Finden Sie das Provisioning-Profil, das Sie wiederherstellen möchten
5. Klicken Sie auf den Edit Button
6. Klicken Sie auf den Save Button
7. Klicken Sie auf den Download Schaltfläche
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, entweder mit Capgo Native Build, der Konfiguration der Anmeldeinformationen oder der App-Build, zögern Sie bitte nicht, uns über Support.