Konfigurationsoptionen

Vollständiger Leitfaden für jede Cloud Build-Konfigurationsoption. Verwende diese Seite, um die CLI Flagge, Umgebungsvariable oder Zugriffsschlüssel für jede Konfigurationsoption zu finden.

Konfigurations-Vorrang

Jede Build-Option kann auf mehrere Weise gesetzt werden. Wenn dieselbe Option an mehreren Stellen gesetzt wird, gewinnen höher-prioritäre Quellen:

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 Ihre gespeicherten Anmeldeinformationen haben SKIP_BUILD_NUMBER_BUMP=true aber Sie übergeben --no-skip-build-number-bump auf der CLI, gewinnt die CLI Flag und die Build-Zahlen werden automatisch inkrementiert.

Tip

Für CI/CD Pipelines sind Umgebungsvariablen normalerweise die bequemste Wahl. Für lokale Entwicklung vermeiden Sie es, Anmeldeinformationen (via build credentials save) avoid repeating flags every time.

---

iOS-Optionen

Code Signieren

CLI Flag	Umgebungsvariable	Zugriffschlüssel	Standard	Beschreibung
--build-certificate-base64 <cert>	BUILD_CERTIFICATE_BASE64	BUILD_CERTIFICATE_BASE64	—	Base64-codiert .p12 Verteilungszertifikat
--ios-provisioning-profile <map>	CAPGO_IOS_PROVISIONING_MAP	CAPGO_IOS_PROVISIONING_MAP	—	Provisioning-Profil als path oder bundleId=path Zuweisung. Wiederholbar für Mehrziel-Anwendungen (Anwendung + Erweiterungen); der Profilname wird automatisch extrahiert.
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	Zugangsdaten für das .p12 Zertifikat (weichen Sie aus, wenn kein Passwort vorhanden ist)

App Store Connect Authentifizierung

CLI Flag	Umgebungsvariable	Zugriffsschlüssel	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 Aussteller-ID (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Base64-encoded 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 App-spezifische Kennwortauthentifizierung wird abgeraten und wird dringend abgeraten. Es existiert nur als Kompatibilitätsweg für Teams, die von Ionic Appflow migrieren (das sich auf es verließ). Es ist an eine persönliche Apple-ID gebunden mit keinen fein abgestimmten Berechtigungen, kann App Store Connect nicht abfragen (so fallen Buildnummern auf ein Timestamp zurück), und deckt nur die TestFlight-Uploads selbst ab. Statt dessen wird eine App Store Connect API-Schlüssel (.p8) empfohlen: Sie ist die empfohlene, fähigere und sichere Option für CI/CD.

App-spezifische Kennwortauthentifizierung (nicht empfohlen)

CLI Flag	Umgebungsvariable	Zugriffsstufe	Zugriffschlüssel	Beschreibung
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	E-Mail-Adresse des Apple-Kontos, das das App gehört
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	App-spezifischer Passwort (xxxx-xxxx-xxxx-xxxx) generiert auf appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	Numerische App-Store-Connect-App-ID (z.B. 1234567890)

Vorsicht

Alle drei Felder sind gemeinsam erforderlich. Die numerische APPLE_APP_ID (in App Store Connect → Ihre App → App-Informationen → Apple-ID) ist verpflichtend: Ohne sie fällt fastlane auf einen interaktiven 2FA-Login zurück, der auf dem Build-Runner nicht abgeschlossen werden kann. Wenn diese Methode verwendet wird, fällt die Build-Nummer auf eine timestamp-basierte Werte zurück, weil App Store Connect nicht für die neueste Build-Nummer abgefragt wird.

iOS-Build-Einstellungen

CLI Flag	Umgebungsvariable	Zugriffschlüssel	Standard	Beschreibung
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Xcode-Baukette zum Bauen
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Xcode-Ziel für die Lesung von Build-Einstellungen
--ios-distribution <mode>	CAPGO_IOS_DISTRIBUTION	CAPGO_IOS_DISTRIBUTION	app_store	Verteilungsmodus: app_store oder ad_hoc

---

Android-Optionen

Sicherheitszertifikat für Android

CLI Flag	Umgebungsvariable	Benutzerkennwort	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-Schlüsselalias
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	Keystore-Schlüsselpasswort (fällt auf Store-Passwort zurück, wenn nicht gesetzt)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	Keystore-Speicherpasswort

Google Play-Konfiguration

CLI Flagge	Umgebungsvariable	Zugriffsschlüssel	Standard	Beschreibung
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Base64-kodierte Google Play-Dienstkontoeinheit im JSON-Format
(nur Umgebungsvariable)	PLAY_STORE_TRACK	—	internal	Google Play-Veröffentlichungsstrecke (internal, alpha, beta, production)
(nur Umgebungsvariable)	PLAY_STORE_RELEASE_STATUS	—	draft	Veröffentlichungsstatus auf der gewählten Strecke (draft, completed, inProgress, halted)

Einstellungen für Android-Builds

CLI Flag	Standard	Beschreibung
--android-flavor <flavor>	—	Produktflavor zum Bauen (z.B. production). Erforderlich wenn Ihr Projekt mehrere Flavours definiert.
--in-app-update-priority <0–5>	—	Google Play in-app-Update-Priorität für diese Version (höher = dringender).
--no-playstore-upload	—	Bauen und signieren, aber Play Store-Upload auslassen (erfordert --output-upload).

---

Baukontroll-Optionen

Diese Optionen funktionieren für beide iOS- und Android-Builds.

Bau-Modus

CLI Flagge	Standard	Beschreibung
--platform <platform>	—	Erforderlich. ios oder android
--build-mode <mode>	release	debug oder release
--path <path>	.	Projektverzeichnis
--verbose	false	Aktivieren Sie die ausführliche Protokollierung des Bauvorgangs
--ai-analytics	false	Bei einem Baufehler werden die Protokolle an die Capgo-KI zur Diagnose gesendet – siehe KI-Bau-Diagnose

Build-Nummer-Kontrolle

CLI Flag	Umgebungsvariable	Zugriffschlüssel	Standard	Beschreibung
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	Automatische Build-Nummer / Versionszählung code überspringen
--no-skip-build-number-bump	—	—	—	Expizit Auto-Zählung wieder aktivieren (überschreibt gespeicherte Zugriffsdaten)

Cloud Build erhöht standardmäßig die Build-Nummer automatisch: Capgo

• iOS: Lädt die neueste Build-Nummer von App Store Connect, erhöht sie um 1
• Android: Holt die maximale Anzahl versionCode aus Google Play, erhöht um 1

Wenn --skip-build-number-bump ist gesetzt, verwendet das Build das bereits in Ihren Projektdateien (Xcode-Projekt oder build.gradle).

Ausgabeanhänge

CLI Flag	Umgebungsvariable	Zugriffschlüssel	Standard	Beschreibung
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	Uploade Baustellenausgaben (IPA/APK/AAB) auf Capgo-Speicher. BUILD_OUTPUT_UPLOAD_ENABLED=true.
--no-output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	—	—	Deaktiviere die Ausgabeanhänge. BUILD_OUTPUT_UPLOAD_ENABLED=false.
--output-retention <duration>	BUILD_OUTPUT_RETENTION_SECONDS	BUILD_OUTPUT_RETENTION_SECONDS	1h	Wie lange bleiben Downloadlinks aktiv?
--output-record <path>	—	—	—	Nach einem erfolgreichen Build schreibe ein JSON-Protokoll (Job-ID, Status, Download-URL, QR-code) zu <path> — lese es mit build last-output.

Speicherkonfiguration: Verwende menschenlesbare Dauerangaben wie 1h, 6h, 2d, 7d. Der Mindestwert beträgt 1 Stunde, der Höchstwert 7 Tage. Wenn via Umgebungsvariable gesetzt, verwenden Sie Sekunden (z.B., 3600 Authentifizierung

Abschnitt mit dem Titel „Authentifizierung“

CLI	Umgebungsvariable	Standard	Beschreibung
-a, --apikey <key>	CAPGO_TOKEN	—	Capgo API-Schlüssel für die Authentifizierung
--supa-host <host>	—	—	Benutzerdefinierte Supabase-Host (nur Selbsthosting)
--supa-anon <key>	—	—	Benutzerdefinierte Supabase-Anon-Schlüssel (nur Selbsthosting)

---

Umgebungsvariable-Quick-Referenz

Fertig zum Kopieren und Einsetzen in Ihre CI/CD-Pipeline. Alle Variablen sind optional – setzen Sie nur das, was Sie benötigen.

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"

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 Control

# 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"

---

Zugriffsdatenspeicherung

Lokale Speicherung von Anmeldeinformationen

Stattdessen müssen Sie die Anmeldeinformationen nicht bei jedem Aufruf mit Flags oder Umgebungsvariablen übergeben, sondern speichern Sie sie einmal:

# 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	Standort	Verwendungsfall
(Standard)	~/.capgo-credentials/credentials.json	Global — auf allen Projekten auf Ihrem Computer gemeinsam verwendet
--local	.capgo-credentials.json in Projektroot	Projektübergreifend — überschreibt globale Einstellungen, wenn beide existieren

Die Anmeldeinformationen werden durch App-ID (z.B. com.example.myapp), so kann ein einzelnes Anmeldeinformationen-File Einstellungen für mehrere Apps ohne Konflikte speichern. Jede App’s Anmeldeinformationen werden weiterhin durch Plattform (ios / android).

Vorsicht

Hinzufügen .capgo-credentials.json zu Ihrem .gitignore wenn Sie lokale Anmeldeinformationen verwenden. Anmeldeinformationen niemals in die Versionskontrolle einchecken.

Gespeicherte Anmeldeinformationen 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 }}

Mit CLI Flags direkt verwenden

# 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

Mischkonfiguration

Combiniere gespeicherte Anmeldeinformationen mit CLI-Überwriten:

# 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 Anmeldeinformationen liefern Signierungsdetails, während CLI-Flaggen die Buildverhalten für diese spezifische Ausführung überschreiben.