iOS Builds

Erstellen und iOS-Apps an TestFlight und den App Store über Capgo’s dedizierte Mac-Infrastruktur bereitstellen.

Was Sie lernen werden

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

Voraussetzungen

• Ein Capgo-Konto (ein kostenloses Probeabo reicht aus, um loszulegen)
• Ihre App ist bereits in Capgo registriert (führen Sie bunx @capgo/cli@latest app add wenn nicht
• Ein Mac-Computer mit Xcode installiert (es ist möglich, die Build-Einrichtung auf einem Linux/Windows-Maschine vorzunehmen, aber es ist noch nicht dokumentiert)
• Ein gültiges Apple-Entwicklerkonto (99 $/Jahr) (Sie müssen auf dem Apple-Entwicklerkonto Admin- oder Eigentümerrechte haben)
• Ihre App muss erfolgreich über Xcode gebaut werden können
• Ein 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 diesen Tutorial werde ich die folgende App verwenden: https://github.com/Cap-go/capgo-native-build-tutorial-app

Bevor Sie mit der Einrichtung in Apples Portalen beginnen

Bevor Sie Zertifikate einrichten oder Ihre erste TestFlight-Upload auslösen, stellen Sie sicher, dass das Apple-Konto und die Team-Struktur bereit sind:

• Zwei-Faktor-Authentifizierung für das Apple-Konto aktivieren, das für die Registrierung verwendet wird
• Wählen Sie die richtige Mitgliedschaftsart:
  • Einzelunternehmen / EinzelunternehmerIhr 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 Arbeits-E-Mail auf der Unternehmensdomain und eine Person mit der Befugnis, die Organisation zu Apple's Vereinbarungen zu binden
• Verwende ein Konto, das Zugriff auf beide Apple Developer und App Store Connect für Zertifikate, App-Records, API-Schlüssel und TestFlight hat
• Fixiere deine endgültige Bundle-ID früh. Änderungen später bedeuten normalerweise eine erneute App Store-Einrichtung
• Plane diese App Store Connect-Elemente vor der App-Review: Unterstützungs-URL, Datenschutzrichtlinien-URL, Altersfreigabe, Screenshot, Export-Kompliance und App-Review-Kontaktinformationen

Anmerkung

Zuverlässige offizielle Referenzen:

• Stelle dich dem Apple Developer Programm
• Übermitteln Sie Ihre Apps und Spiele
• Plattformversioneninformationen in App Store Connect

Achtung

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

Empfohlen: Automatisierte Einbindung

Sie müssen nichts davon manuell durchführen. Capgo's Einbindung erstellt und konfiguriert Ihre iOS-Zertifizierungsdaten (Distributionszertifikat + Provisioning-Profil) 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 sich selbst die Anmeldeinformationen einrichten möchten oder genau wissen möchten, was Capgo unter der Haube tut.

Der erste manuelle Build

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

• Sie werden die Verteilungs-Zertifizierung 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 erkennen, die mit Ihrer App code verbunden sind

Bevor wir beginnen können, müssen Sie das Verteilungs-Zertifizierung auf Ihrem lokalen Computer installiert haben. Das ist ziemlich komplex, aber ich werde es unten erklären.

Die Einrichtung der Verteilungs-Zertifizierung

1. Xcode öffnen

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

   

3. Gehe 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... Knopf

7. Stellen Sie sicher, dass Sie die Zertifikatsverteilung in der Liste sehen können

8. Wenn Sie dies nicht tun, 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 + Knopf 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.

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

Manueller Build zum TestFlight

1. Öffnen Sie die App in Xcode

   Starten bunx cap open ios um die App in Xcode zu öffnen.

2. Finden und auf den archive Button

   In der Xcode-Leiste finden und auf den product -> archive Button klicken.

   

3. Warten, bis das Build abgeschlossen ist

4. Auf den Distribute App Button klicken

   

5. Auswählen TestFlight Internal Only als Verteilungsverfahren auswählen und auf Distribute Button

   

6. Die App-Veröffentlichung konfigurieren

   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. Hauptsprache - die Hauptsprache Ihrer App

   Klicken Sie dann auf den next Button

   

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

8. Warten Sie, bis der Upload abgeschlossen ist

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

10. Klicken Sie auf den Done Schaltfläche

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 erledigen sind:

1. Fügen Sie sich selbst in TestFlight hinzu
2. Abschließen Sie die Export-Kompliance, damit das Build testbar wird
3. Füllen Sie die erforderlichen App Store Connect-Metadaten wie Ihre Support-URL, Ihre Datenschutzrichtlinien-URL und Ihre Altersangabe aus
4. Vorbereiten Sie Screenshots, die den von Ihnen unterstützten Geräten entsprechen
5. Fügen Sie die Kontaktinformationen von App Review und alle Testanmeldeinformationen vor der Produktionsabgabe hinzu

Los geht’s mit dem ersten:

Sich selbst bei TestFlight hinzufügen

1. Gehe zur App Store Connect Seite

2. Melden Sie sich mit Ihrem Apple-Entwicklerkonto an

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

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

6. Klicken Sie auf den TestFlight Button

7. Klicken Sie auf den Internal Testers plus Button

8. Erstellen Sie eine neue Gruppe

   Ich nenne die Gruppe gerne „intern“. Sie können sie nennen, wie Sie wollen.

   

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 setzen Sie das Kontrollkästchen neben Ihrem Namen. (Sie müssen sich möglicherweise neu laden, um sich selbst zu sehen) Dann klicken Sie auf die Add Schaltfläche.

    

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

    Jetzt sollten Sie sich selbst in der Gruppe sehen.

    

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

Die Einrichtung der Compliance-Informationen

Sie müssen nun Apple versprechen, dass Ihre App keine nicht standardmäßigen (wie ein benutzerdefinierter Algorithmus) Verschlüsselungen verwendet. Wenn Ihre App nicht standardmäßige Verschlüsselungen verwendet, empfehle ich Ihnen, die Dokumentation von Apple zu lesen, um dies zu handhaben. 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 false.

Los geht's mit der ersten Möglichkeit:

1. Folgen Sie allen Schritten aus der vorherigen Sektion, 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. Hinzufügen Sie die folgende Schlüssel:

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

3. Speichern Sie das Datei

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 sind Sie Fast so gut bereit, Ihre App in TestFlight zu testen. Bevor Sie das tun, müssen Sie die folgenden Schritte ausführen:

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

Ich werde die Details davon auslassen, wie Sie die TestFlight-App auf Ihrem Gerät installieren. Wenn Sie sich nicht sicher sind, wie Sie eine App installieren, hat Google einige großartige Anleitungen dazu.

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

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

2. Klicken Sie auf View in TestFlight Schaltfläche

3. Klicken Sie auf die Install Schaltfläche

4. Installieren Sie die App auf Ihrem Gerät

   If Sie die App zuvor mit Xcode installiert haben, sehen Sie möglicherweise die folgende Bildschirm. 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 TestFlight angenommen. Jetzt können Sie Capgo Native Build konfigurieren, um Ihre App zu bauen und bei TestFlight zu submiten.

Capgo Native Build konfigurieren

Es gibt ein paar Dinge, die Sie in Capgo Native Build konfigurieren müssen, um Ihre App bauen und bei TestFlight submiten zu können. Hier ist eine Liste der Dinge, die Sie an die Capgo CLI übergeben werden:

Parameter	Beschreibung
--platform	Die Plattform zum Bauen für (ios)
--apple-team-id	Ihre Apple-Entwickler-Team-ID (im Apple-Entwickler-Portal)
--apple-key	Pfad zu Ihrem App Store Connect API-Schlüsseldatei (.p8 Datei)
--apple-key-id	Die Schlüssel-ID Ihrer App Store Connect API-Schlüssel
--apple-issuer-id	Ihre App Store Connect Aussteller-ID
--certificate	Pfad zu Ihrer Verteilungszertifizierung (.p12 Datei)
--ios-provisioning-profile	Zuordnung des Bereitstellungsprofils (bundleId=path oder einfach Pfad für ein einzelnes Profil)

Beispielbefehl:

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

Team-ID

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

Jetzt wechseln wir zu der Apple-Schlüssel.

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

Auf einem Mac capgo build init kann API für Sie diesen App Store Connect-Schlüssel 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 Key-ID und die Issuer-ID automatisch ein – kein Kopieren und Einfügen. Die unten beschriebenen manuellen Schritte sind die Alternative (und der Weg auf Windows oder Linux).

1. Gehe zu der App Store Connect-Benutzer- und Zugriffseite

   Hinweis

   Für mich funktioniert der Link manchmal nicht. Lade die Seite neu, wenn es für Sie 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 Mannschaft, die Sie verwenden möchten

3. Klicken Sie auf den Integrations __CAPGO_KEEP_0__

4. Achtung: Diese issuer

   Dies

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

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

5. Klicken Sie auf die Plus-Schaltfläche

6. Legen Sie den Namen der Schlüssel und legen Sie den Zugriff auf App manager und klicken Sie auf die Generate Schaltfläche

7. Speichern Sie die Schlüssel-ID

   Achtung

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

   

8. Laden Sie die Schlüssel

   Achtung

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

   Warnung

   VERTEILE DEN SCHLÜSSEL NICHT MIT JEDERMANN - BENUTZE IHNEN AUSNICHTS IN DEN 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 auszuführen. Wie Sie sich vielleicht erinnern, war eine der ersten Schritte dieses Leitfadens die Einrichtung des Verteilungszertifikats.

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.

1. Öffnen Sie Keychain Access

   1. Klicken Sie Command + Space um den Suchbalken 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. Finden Sie Ihr Zertifikat in der Liste

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

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

5. Speichern Sie das Zertifikat als .p12 Datei

   Vorsicht

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

   1. Stellen Sie sicher, dass Sie für das Zertifikat-Dateinamen einen guten Namen wä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. Passwortgeschützte .p12 Dateien werden vollständig von der Capgo CLI unterstützt – geben Sie einfach das Passwort mit der --p12-password Option an, wenn Sie die Konfigurationskommando ausführen.

   

7. Wenn Sie nach dem „Anmelde-Schlüsselkette-Passwort“ 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.

   

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-Profil

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. Stellen Sie sicher, dass Sie sich auf der richtigen Seite befinden Es sollte so aussehen, wenn es nicht so aussieht, klicken Sie auf profiles in der Seitenleiste

   

4. Klicken Sie auf den + Schaltfläche

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

   

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

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

   

7. Wählen Sie das korrekte Verteilungszeugnis

   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 Button

   Tipp

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

   

9. Das Profil herunterladen

   Klicken Sie auf den Download Button zum Herunterladen des Profils

   Vorsicht

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

   

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

Vorsicht

Kommt nie dazu, die von euch erstellten Zugangsdaten in eurem Repository zu committen. Behaltet sie sicher! 🔒

Ausführen der Konfigurationskommando

Ihr habt es geschafft! Ihr habt jetzt alles, was ihr zum Konfigurieren von Capgo Native Build benötigt.

Das Kommando, das ihr ausführen müsst 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

Ersatzwerte für Platzhalter

Ersetzt die oben stehenden Platzhalterwerte mit euren tatsächlichen Zugangsdaten, die ihr in den vorherigen Schritten gesammelt habt:

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

Wenn alles gut gelaufen ist, sehen Sie folgende Ausgabe:

CI/CD-Einrichtung (GitHub Actions)

Wenn Sie bereits alle erforderlichen Schritte abgeschlossen haben Team-ID, Apple-Schlüssel, Apple-Schlüssel-ID und Apple-Aussteller-ID, Zertifikat, und Provisioning-Profil, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

Diese Abschnitt behandelt nur, wie Sie diese Werte als __CAPGO_KEEP_0__ Actions-Secrets und Umgebungsvariablen übergeben.

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

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

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

Tip

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

2) Erstelle Repository-Geheimnisse

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

Geheimnisname	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	Erstellt durch CLI — Kopieren Sie von .capgo-credentials Datei
APPLE_KEY_CONTENT	Inhalt von apple_key_base64.txt
P12_PASSWORD (optional)	Dein .p12 Passwort, wenn während der Export gesetzt

3) Verwende Umgebungsvariablen in deinem 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 nur die Anmeldeinformationen über Umgebungsvariablen. Sie müssen keine Signierungsdateien committen oder sie als Workflow-Artikel hochladen.

Die Verarbeitung ausführen

Jetzt sind Sie bereit, Ihre erste Verarbeitung 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 Ihr App erfolgreich erstellt und es ist bereit, zur Veröffentlichung im App Store eingereicht zu werden.

Ad-hoc-Verteilungsmodus

Standardmäßig erstellt Capgo iOS-Apps für die Verteilung im App Store (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 Flagge

Hinweis

Die ad-hoc-Verteilung ist nicht die gleiche wie die Enterprise (In-House)-Verteilung. Die Enterprise-Verteilung erfordert ein separates Apple-Entwickler-Enterprise-Konto und verwendet unterschiedliche Bereitstellungsprofile. Capgo unterstützt app_store und ad_hoc Verteilungsmodi nur.

When soll man den Ad-hoc-Modus verwenden

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

Anforderungen

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

Zertifikat	Erforderlich?
Verteilungszertifikat (.p12)	Ja
Ad-hoc-Provisioning-Profil (.mobileprovision)	Ja
Team-ID (--apple-team-id)	Ja
App Store Connect API-Sicherheitszertifikat (.p8)	Nein
Apple Key ID / Aussteller-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 den app_store Vorsicht

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

Without an App Store Connect API key, build number auto-increment uses a timestamp-based fallback. To suppress the warning, pass --skip-build-number-bump.

Abschnitt mit Titel „Erstellung eines ad-hoc-Beitrittsprofils“

Follow the same steps as Provisionierungsprofilaber in Schritt 5 wählen Sie Ad Hoc anstatt App Store:

1. Zum Apple Developer-Profil
2. Klicken Sie auf + Schaltfläche
3. Wählen Sie Ad Hoc und klicken Sie auf Weiter
4. Wählen Sie Ihre App und das Zertifikat für die Verteilung
5. Wählen Sie die Geräte aus, die Sie registrieren möchten
6. Benennen und herunterladen Sie das Profil

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

Ein Ad-hoc-Build ausführen

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

Um das 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 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 erforderlich sind.

Apps mit Erweiterungen (Multi-Target-Signing)

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

Jedes --ios-provisioning-profile flag kartet eine Bundle-ID mit ihrem Provisioning-Profile-Datei ab. Die CLI:

1. Jedes mobileprovision-File liest
2. Auto-extrahiert den Profilnamen aus dem eingebetteten plist
3. Base64-codiert die Datei
4. Speichert alles als ein CAPGO_IOS_PROVISIONING_MAP Kreditkarten-Daten

Tipp

Sie benötigen ein Verteilungs-Zertifikat für alle Ziele – nur Provisioning-Profile unterscheiden sich pro Ziel.

Migration von Single Profile

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

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

Dies wandelt Ihre bestehenden Ein-Profil-Anmeldeinformationen in das neue CAPGO_IOS_PROVISIONING_MAP Format um und entfernt die alten 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 update (nicht save) um Profile zu vorhandenen Anmeldeinformationen hinzuzufügen. Das update Befehl kombiniert neue Profile mit bestehenden. Verwenden save nur, wenn alle Anmeldeinformationen von vorneherein eingerichtet werden.

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 tritt auf, weil Sie eine neue Fähigkeit aktiviert haben, nachdem das Provisionierungsprofil erstellt wurde.

Das alte Provisionierungsprofil enthält die neue Fähigkeit noch nicht.

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 erneuern möchten
5. Klicken Sie auf den Edit Button
6. Klicken Sie auf den Save Schaltfläche
7. Klicken Sie auf den Download Schaltfläche
8. Führen Sie den Capgo Native Build Setup-Befehl 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 der App-Build, zögern Sie bitte nicht, uns über unsere Unterstützung.

Weitermachen von iOS Builds

Wenn Sie "iOS Builds" verwenden iOS Builds um die CI/CD-Automatisierung zu planen, verbinden Sie es mit Capgo CI/CD für den Produktworkflow in Capgo CI/CD Capgo Native Builds für den Produktworkflow 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 Aktionen-Integration für die Implementierungsdetails in GitHub Aktionen-Integration.