Konfigurationsoptionen

Vollständige Referenz für alle Cloud Build-Konfigurationsoptionen. Auf dieser Seite findest du das CLI-Flag, die Umgebungsvariable oder den Credential-Key für jede Build-Einstellung.

Konfigurationspriorität

Jede Build-Option kann auf verschiedene Weise festgelegt werden. Wenn dieselbe Option an mehreren Stellen gesetzt ist, haben Quellen mit höherer Priorität Vorrang:

flowchart LR
    A["🔧 CLI Flag"] -->|overrides| B["🌍 Environment Variable"]
    B -->|overrides| C["📁 Local Credentials"]
    C -->|overrides| D["🏠 Global Credentials"]
    style A fill:#6366f1,color:#fff,stroke:#4f46e5
    style B fill:#8b5cf6,color:#fff,stroke:#7c3aed
    style C fill:#a78bfa,color:#fff,stroke:#8b5cf6
    style D fill:#c4b5fd,color:#1e1b4b,stroke:#a78bfa

Beispiel: Wenn deine gespeicherten Credentials SKIP_BUILD_NUMBER_BUMP=true aber du übergibst --no-skip-build-number-bump auf der CLI hat der CLI-Flag Vorrang und die Build-Nummern werden automatisch hochgezählt.

Tipp

Für CI/CD-Pipelines sind Umgebungsvariablen meist am praktischsten. Für die lokale Entwicklung sind gespeicherte Credentials (via build credentials save) vermeiden Sie, Flags jedes Mal zu wiederholen.

---

iOS-Optionen

Code Signierung

CLI Flagge	Umgebungsvariable	Credential-Key	Standard	Beschreibung
--build-certificate-base64 <cert>	BUILD_CERTIFICATE_BASE64	BUILD_CERTIFICATE_BASE64	—	Base64-kodiert .p12 Distributionszertifikat
--ios-provisioning-profile <map>	CAPGO_IOS_PROVISIONING_MAP	CAPGO_IOS_PROVISIONING_MAP	—	Provisioning-Profil als path oder bundleId=path Mapping. Wiederholbar für Multi-Target-Apps (App + Extensions); der Profilname wird automatisch extrahiert.
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	Passwort für das .p12 Zertifikat (weglassen, falls das Zertifikat kein Passwort hat)

App Store Connect-Authentifizierung

CLI Flagge	Umgebungsvariable	Credential-Key	Standard	Beschreibung
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	App Store Connect API Key ID
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	App Store Connect Issuer ID (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Base64-kodierter App Store Connect API-Key (.p8 Datei)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	App Store Connect Team-ID

Nicht empfohlen

Die Authentifizierung mit app-spezifischen Passwörtern wird nicht empfohlen und deren Nutzung ist abzuraten. Sie existiert nur als Kompatibilitätsweg für Teams, die von Ionic Appflow (das darauf angewiesen war) migrieren. Sie ist an eine persönliche Apple-ID ohne granulare Berechtigungen gebunden, kann App Store Connect nicht abfragen (Build-Nummern fallen daher auf einen Zeitstempel zurück) und deckt nur den TestFlight-Upload selbst ab. Bevorzugen Sie einen App Store Connect API-Key (.p8) stattdessen: Er ist die empfohlene, leistungsfähigere und sicherere Option für CI/CD.

Authentifizierung mit app-spezifischem Passwort (nicht empfohlen)

CLI Flagge	Umgebungsvariable	Credential-Key	Standard	Beschreibung
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	Apple-ID-E-Mail-Adresse des Kontos, dem die App gehört
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	App-spezifisches Passwort (xxxx-xxxx-xxxx-xxxx) erstellt am appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	Numerische App Store Connect App-ID (z. B. 1234567890)

Achtung

Alle drei Felder sind zusammen erforderlich. Die numerische APPLE_APP_ID (zu finden in App Store Connect → deine App → App-Informationen → Apple ID) ist Pflicht: Ohne sie fällt fastlane auf einen interaktiven 2FA-Login zurück, der auf dem Build-Runner nicht abgeschlossen werden kann. Bei dieser Methode wird für die Build-Nummer ein zeitstempelbasierter Wert verwendet, da App Store Connect nicht nach der neuesten Build-Nummer abgefragt wird.

iOS Build-Einstellungen

CLI Flagge	Umgebungsvariable	Credential-Key	Standard	Beschreibung
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Xcode-Scheme für den Build
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Xcode-Target zum Auslesen der Build-Einstellungen
--ios-distribution <mode>	CAPGO_IOS_DISTRIBUTION	CAPGO_IOS_DISTRIBUTION	app_store	Distribution-Modus: app_store oder ad_hoc
--xcode-version <version>	CAPGO_IOS_XCODE_VERSION	CAPGO_IOS_XCODE_VERSION	beliebig	Build mit dieser Xcode-Version, z. B. 26, 26.0.1 oder 27. Eine Major-Version akzeptiert jede Minor-Version. Der Build schlägt sofort fehl und listet die verfügbaren Versionen auf, wenn keine passt.

Xcode 27

Build mit Xcode 27 (iOS 27 SDK) mit --xcode-version 27:

npx @capgo/cli@latest build request --platform ios --xcode-version 27

Apps, die mit dem iOS 27 SDK gebaut werden, müssen den UIScene-Lebenszyklus übernehmen: ohne eine UIApplicationSceneManifest in einem Info.plist und einen Scene-Delegate stoppt iOS 27 die App beim Start. Capgo blockiert diese Builds, bevor sie beginnen (Prescan-Check ios/plist-scene-lifecycle-xcode27). Füge eine SceneDelegate und einen UIApplicationSceneManifest zu ios/App/App/Info.plisthinzu, oder baue weiter mit --xcode-version 26 bis du das tust. Siehe Apples Scene-Lebenszyklus-Guide.

Ende der CocoaPods-Unterstützung (Dezember 2026)

Capgo Build stellt im Dezember 2026 die Erstellung von iOS-Projekten ein, die CocoaPods verwenden. Migrate your project to Swift Package Manager before then: see the Capacitor SPM-Guide. Bis dahin funktionieren CocoaPods-Builds weiter; CLI gibt eine Warnung aus und Capgo schickt den Admins deiner Organisation eine Erinnerung per E-Mail.

---

Android-Optionen

Keystore-Signierung

CLI Flagge	Umgebungsvariable	Credential-Key	Standard	Beschreibung
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	Base64-kodierte Keystore-Datei (.keystore oder .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	Keystore-Key-Alias
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	Keystore-Key-Passwort (fällt auf Store-Passwort zurück, wenn nicht gesetzt)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	Keystore-Store-Passwort

Google Play-Konfiguration

CLI Flagge	Umgebungsvariable	Credential-Key	Standard	Beschreibung
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Base64-kodierter Google Play Service Account JSON-Schlüssel
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal (oder production mit --submit-to-store-review)	Google Play Release-Track (internal, alpha, beta, production). Wird aus der CI-Umgebung / CLI an den Build-Runner weitergeleitet.
--android-release-status <status>	PLAY_STORE_RELEASE_STATUS	PLAY_STORE_RELEASE_STATUS	draft (oder completed mit --submit-to-store-review)	Release-Status auf dem gewählten Track (draft, completed, inProgress, halted). Explizite Werte überschreiben den --submit-to-store-review Standardwert.

Android-Build-Einstellungen

CLI Flagge	Standard	Beschreibung
--android-flavor <flavor>	—	Produktflavor, der gebaut werden soll (z. B. production). Erforderlich falls Ihr Projekt mehrere Flavors definiert.
--android-track <track>	internal	Google Play-Track für diesen Upload. Mit --submit-to-store-review und ohne gesetzten Track standardisiert Capgo auf production.
--android-release-status <status>	draft	Google Play-Release-Status. Mit --submit-to-store-review und ohne gesetztem Status standardisiert Capgo auf completed.
--in-app-update-priority <0–5>	—	Priorität der In-App-Updates für diese Version im Google Play Store (höher = dringender).
--no-playstore-upload	—	Builden und signieren, aber den Upload zum Play Store überspringen (erfordert --output-upload).

---

Build-Steuerungsoptionen

Diese Optionen gelten für iOS- und Android-Builds.

Build-Modus

CLI Flagge	Standard	Beschreibung
--platform <platform>	—	Pflichtfeld. ios oder android
--build-mode <mode>	release	debug oder release
--path <path>	.	Projektverzeichnis
--verbose	false	Ausführliche Build-Protokollierung aktivieren
--ai-analytics	false	Bei Build-Fehlern Logs an Capgo AI zur Diagnose senden — siehe KI-Build-Diagnose

Build-Nummern-Steuerung

CLI Flagge	Umgebungsvariable	Credential-Key	Standard	Beschreibung
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	Automatisches Inkrementieren der Build-Nummer / Version code überspringen
--no-skip-build-number-bump	—	—	—	Auto-Increment explizit wieder aktivieren (überschreibt gespeicherte Credentials)

Standardmäßig inkrementiert Capgo Cloud Build die Build-Nummern automatisch:

• iOS: Holt die neueste Build-Nummer von App Store Connect und erhöht sie um 1
• Android: Ruft max ab versionCode von Google Play und erhöht es um 1

Wenn --skip-build-number-bump ist gesetzt, verwendet der Build die Version, die bereits in deinen Projektdateien (Xcode-Projekt oder build.gradle).

Output-Upload

CLI Flagge	Umgebungsvariable	Credential-Key	Standard	Beschreibung
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	Build-Ausgaben (IPA/APK/AAB) in den Capgo-Speicher hochladen. Bei Verwendung über eine Umgebungsvariable: BUILD_OUTPUT_UPLOAD_ENABLED=true.
--no-output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	—	—	Upload der Ausgabe deaktivieren. Bei Verwendung über Env-Variablen: BUILD_OUTPUT_UPLOAD_ENABLED=false.
--output-retention <duration>	BUILD_OUTPUT_RETENTION_SECONDS	BUILD_OUTPUT_RETENTION_SECONDS	1h	Wie lange Download-Links aktiv bleiben
--output-record <path>	—	—	—	Nach einem erfolgreichen Build eine JSON-Aufzeichnung (Job-ID, Status, Download-URL, QR code) schreiben an <path> — mit folgendem Befehl auslesen: build last-output.

Retention-Format: Menschenlesbare Zeiträume wie 1h, 6h, 2d, 7d. Minimum ist 1 Stunde, Maximum 7 Tage. Bei Verwendung über eine Umgebungsvariable Sekunden angeben (z. B. 3600 für 1 Stunde).

Build-Cache

Capgo speichert kompilierte native Artefakte (CocoaPods, Gradle und zugehörige Build-Outputs) pro App damit wiederholte Builds schneller starten. Der Build-Cache ist standardmäßig aktiviert für jede App.

CLI Flagge	API-Feld	Standard	Beschreibung
--no-cache	cache_enabled: false	Cache an	Cache für diesen Build deaktivieren: Restore überspringen und keinen neuen Eintrag speichern
--cache-key <value>	cache_key	(auslassen)	Cache partitionieren (zum Beispiel prod, staging). Weglassen für einen gemeinsamen allgemeinen Cache pro App

CLI Äquivalente: build request akzeptiert --no-cache und --cache-key.

Tipp

Verwende unterschiedliche --cache-key Werte, wenn RC- und Production-Builds dieselbe App-ID nutzen, aber den kompilierten Output des jeweils anderen nicht wiederverwenden dürfen — zum Beispiel --cache-key=prod und --cache-key=staging.

CLI Beispiele:

# Default: restore/save the shared per-app cache
bunx @capgo/cli@latest build request com.example.app --platform android

# Separate caches per environment
bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=prod

bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=staging \
  --android-flavor staging

# One-off clean build (no restore, no save)
bunx @capgo/cli@latest build request com.example.app --platform ios --no-cache

API / Webhook-Payload (wenn deine Integration direkt Capgo Build aufruft):

{
  "platform": "android",
  "cache_key": "prod"
}

Weglassen cache_key für den gemeinsamen allgemeinen Cache. Setze cache_key um nach Umgebung zu partitionieren. Setze "cache_enabled": false um den Cache für eine einzelne Anfrage zu deaktivieren (wie bei --no-cache).

Wenn ein Build erfolgreich aussieht, aber das Artefakt falsch ist – oder ein Android AAB nach dem Wechsel zwischen RC und Production fehlt – versuche einen dedizierten Cache-Key oder einen einmaligen --no-cache build. Siehe Troubleshooting: Fehler beim Cache-Restore.

Authentifizierung

CLI Flagge	Umgebungsvariable	Standard	Beschreibung
-a, --apikey <key>	CAPGO_TOKEN	—	Capgo API Key zur Authentifizierung
--supa-host <host>	—	—	Eigener Supabase-Host (nur Self-Hosting)
--supa-anon <key>	—	—	Eigener Supabase anon Key (nur Self-Hosting)

---

Quick Reference: Umgebungsvariablen

Bereit zum Kopieren in deine CI/CD-Pipeline. Alle Variablen sind optional – setze nur, was du brauchst.

iOS

# Code signing (required for iOS builds)
BUILD_CERTIFICATE_BASE64="<base64-encoded .p12>"
CAPGO_IOS_PROVISIONING_MAP="<provisioning map generated by the CLI>"
P12_PASSWORD="<certificate password>"

# App Store Connect (required for store submission)
APPLE_KEY_ID="ABC1234567"
APPLE_ISSUER_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
APPLE_KEY_CONTENT="<base64-encoded .p8 key>"
APP_STORE_CONNECT_TEAM_ID="TEAM123456"

# Alternative to the App Store Connect API key above: Apple ID + app-specific
# password (e.g. when migrating from Ionic Appflow). All three are required.
# FASTLANE_USER="apple-id@example.com"
# FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD="xxxx-xxxx-xxxx-xxxx"
# APPLE_APP_ID="1234567890"

# Optional iOS settings
CAPGO_IOS_SCHEME="App"
CAPGO_IOS_TARGET="App"
CAPGO_IOS_XCODE_VERSION="27"

Android

# Keystore signing (required for Android builds)
ANDROID_KEYSTORE_FILE="<base64-encoded .keystore>"
KEYSTORE_KEY_ALIAS="my-key-alias"
KEYSTORE_KEY_PASSWORD="<key password>"
KEYSTORE_STORE_PASSWORD="<store password>"

# Google Play (required for store submission)
PLAY_CONFIG_JSON="<base64-encoded service account JSON>"

# Optional Android settings
PLAY_STORE_TRACK="internal"
PLAY_STORE_RELEASE_STATUS="draft"

Build-Steuerung

# Build behavior
SKIP_BUILD_NUMBER_BUMP="true"          # Skip auto-increment
BUILD_OUTPUT_UPLOAD_ENABLED="true"     # Upload IPA/APK/AAB
BUILD_OUTPUT_RETENTION_SECONDS="3600"  # 1 hour download link

# Authentication
CAPGO_TOKEN="your-api-key"

---

Credential-Speicherung

Credentials lokal speichern

Speichere die Credentials einmal, statt jedes Mal Flags oder Env-Vars zu übergeben:

# Save iOS credentials
bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./dist_cert.p12 \
  --ios-provisioning-profile ./profile.mobileprovision \
  --p12-password "cert-password" \
  --apple-key ./AuthKey.p8 \
  --apple-key-id ABC1234567 \
  --apple-issuer-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  --apple-team-id TEAM123456

# Save Android credentials
bunx @capgo/cli@latest build credentials save \
  --platform android \
  --keystore ./release.keystore \
  --keystore-alias my-key \
  --keystore-key-password "key-pass" \
  --keystore-store-password "store-pass" \
  --play-config ./play-service-account.json

Speicherorte

Flagge	Ort	Anwendungsfall
(Standard)	~/.capgo-credentials/credentials.json	Global — gilt für alle Projekte auf deinem Rechner
--local	.capgo-credentials.json im Projekt-Root	Pro Projekt — überschreibt global, wenn beides existiert

Credentials werden unterschieden nach App-ID (z. B. com.example.myapp), sodass eine einzige Credentials-Datei Einstellungen für mehrere Apps ohne Konflikte speichern kann. Die Credentials jeder App sind zusätzlich nach Plattform unterteilt (ios / android).

Achtung

Füge .capgo-credentials.json in deine .gitignore falls lokale Credentials verwendet werden. Credentials niemals in der Versionskontrolle committen.

Gespeicherte Zugangsdaten verwalten

# List saved credentials
bunx @capgo/cli@latest build credentials list

# Update a specific option without re-entering everything
bunx @capgo/cli@latest build credentials update --skip-build-number-bump

# Clear saved credentials
bunx @capgo/cli@latest build credentials clear --platform ios

---

Beispiele

GitHub Aktionen

name: Build and Submit
on:
  push:
    branches: [main]

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

  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bunx cap sync android
      - run: bunx @capgo/cli@latest build request --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

CLI Flags direkt nutzen

# Build iOS with all options inline
bunx @capgo/cli@latest build request \
  --platform ios \
  --build-mode release \
  --skip-build-number-bump \
  --output-retention 6h \
  --apikey YOUR_API_KEY

# Build Android, skip version bump, no output upload
bunx @capgo/cli@latest build request \
  --platform android \
  --skip-build-number-bump \
  --no-output-upload \
  --apikey YOUR_API_KEY

Gemischte Konfiguration

Kombinieren Sie gespeicherte Credentials mit CLI Overrides:

# Save base credentials once
bunx @capgo/cli@latest build credentials save --platform ios \
  --certificate ./cert.p12 \
  --ios-provisioning-profile ./profile.mobileprovision \
  --output-upload

# Override specific options per-build
bunx @capgo/cli@latest build request --platform ios \
  --skip-build-number-bump \
  --output-retention 2d

Die gespeicherten Credentials liefern die Signing-Details, während CLI Flags das Build-Verhalten für diesen spezifischen Run überschreiben.