Opzioni di configurazione

Riferimento completo per ogni opzione di configurazione di Cloud Build. Utilizza questa pagina per trovare la CLI flag, variabile di ambiente o chiave di credenziale per qualsiasi impostazione di build.

Precedenza della configurazione

Ogni opzione di build può essere impostata in modi diversi. Quando lo stesso opzione è impostata in più posti, le fonti di priorità più elevate vincono:

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

Esempio: Se i tuoi credenziali salvate hanno SKIP_BUILD_NUMBER_BUMP=true but you pass --no-skip-build-number-bump su CLI, la CLI flag vince e i numeri di build saranno incrementati automaticamente.

Tip

Per i flussi CI/CD, le variabili di ambiente sono di solito le più comode. Per lo sviluppo locale, i credenziali salvate (via build credentials saveevitare di ripetere le flag ogni volta.

---

Opzioni iOS

Code Firma

CLI Bandiera	Variabile di ambiente	Chiave delle credenziali	Predefinito	Descrizione
--build-certificate-base64 <cert>	BUILD_CERTIFICATE_BASE64	BUILD_CERTIFICATE_BASE64	—	Codificato in Base64 .p12 certificato di distribuzione
--ios-provisioning-profile <map>	CAPGO_IOS_PROVISIONING_MAP	CAPGO_IOS_PROVISIONING_MAP	—	profilo di provisioning come path o bundleId=path mappatura. Ripetibile per le applicazioni multi-target (app + estensioni); il nome del profilo viene estratto automaticamente.
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	la password per il .p12 il certificato (omissione se il certificato non ha password)

L'autenticazione di App Store Connect

CLI Flag	Variabile di ambiente	Chiave di credenziale	Predefinito	Descrizione
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	L'ID chiave di App Store Connect API
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	ID emettitore App Store Connect (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Chiave App Store Connect codificata in Base64 (API) (.p8 file)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	ID squadra App Store Connect

Non consigliato

L'autenticazione tramite password app-specific è scoraggiata e non è consigliata. Esiste solo come percorso di compatibilità per le squadre che stanno migrando da Ionic Appflow (che si basava su di esso). È legato a un ID Apple personale senza autorizzazioni granulari, non può interrogare App Store Connect (così i numeri di build ricadono su un timestamp), e copre solo l'upload di TestFlight stesso. Preferisci una chiave App Store Connect API (.p8) invece: è l'opzione consigliata, più capace e più sicura per CI/CD.

Autenticazione tramite password app-specific (non consigliata)

Flag CLI	Variabile di ambiente	Chiave di credenziale	Default	Descrizione
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	Indirizzo e-mail dell'ID Apple dell'account che possiede l'app
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	Password specifica dell'app (xxxx-xxxx-xxxx-xxxx) generata su appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	ID numerico dell'app Store Connect (ad esempio 1234567890)

Caution

Tutti e tre i campi sono richiesti insieme. Il campo numerico APPLE_APP_ID La chiave Apple ID (trovata in App Store Connect → la tua app → Informazioni sull'app → ID Apple) è obbligatoria: senza di essa, fastlane ricade su un login 2FA interattivo che non può completare sul runner di costruzione. Quando si utilizza questo metodo, il numero di costruzione ricade su un valore basato su timestamp, perché App Store Connect non viene interrogato per il numero di costruzione più recente.

Impostazioni di costruzione iOS

CLI Bandiera	Variabile di ambiente	Chiave di credenziale	Predefinito	Descrizione
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Schema Xcode per la costruzione
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Xcode target for reading build settings
--ios-distribution <mode>	CAPGO_IOS_DISTRIBUTION	CAPGO_IOS_DISTRIBUTION	app_store	Modalità di distribuzione: app_store o ad_hoc

---

Opzioni Android

Autenticazione con Keystore

Flag CLI	Variabile di ambiente	Chiave delle credenziali	Predefinito	Descrizione
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	File di keystore codificato in Base64 (.keystore o .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	Chiave di alias del keystore
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	Password della chiave del keystore (ricade sulla password del magazzino se non impostata)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	Password del magazzino del keystore

Configurazione di Google Play

CLI Flag	Variabile di ambiente	Chiave delle credenziali	Predefinito	Descrizione
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Chiave JSON del servizio Google Play codificata in Base64
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal (o production context --submit-to-store-review)	Tracciato di rilascio di Google Play (internal, alpha, beta, production) Trasferito dalla variabile di ambiente CI / CLI nel runner di costruzione.
--android-release-status <status>	PLAY_STORE_RELEASE_STATUS	PLAY_STORE_RELEASE_STATUS	draft (o completed with --submit-to-store-review)	). Valori espliciti sovrascrivono ildraft, completed, inProgress, haltedImpostazioni di costruzione Android --submit-to-store-review default.

__CAPGO_KEEP_0__ Flag

CLI Flag	Default	Description
--android-flavor <flavor>	—	Flavor del prodotto da costruire (ad es. production). Obbligatorio se il tuo progetto definisce più gusti.
--android-track <track>	internal	Tracciato di Google Play per questo upload. Con --submit-to-store-review e nessun tracciato impostato, Capgo si avvia a production.
--android-release-status <status>	draft	Stato di rilascio di Google Play. Con --submit-to-store-review e nessun stato impostato, Capgo si avvia a completed.
--in-app-update-priority <0–5>	—	Priorità di aggiornamento in-app di Google Play per questo rilascio (più alta = più urgente).
--no-playstore-upload	—	Costruisci e firma, ma saltare l'upload di Google Play (richiede --output-upload).

---

Opzioni di controllo della costruzione

Queste opzioni funzionano sia per le costruzioni iOS che per quelle Android.

Build Mode

Flag CLI	Predefinito	Descrizione
--platform <platform>	—	Richiesto. ios o android
--build-mode <mode>	release	debug o release
--path <path>	.	o (alternativa per Appflow)
--verbose	false	Directory del progetto
--ai-analytics	false	In caso di fallimento della costruzione, invia i log a Capgo AI per la diagnosi — vedi Diagnosi di costruzione AI

Numero di costruzione Controllo

Flag CLI	Variabile di ambiente	Chiave delle credenziali	Predefinito	Descrizione
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	Saltare l'incremento automatico del numero di costruzione / versione code
--no-skip-build-number-bump	—	—	—	Abilita esplicitamente l'incremento automatico (sovrascrive le credenziali salvate)

Di default, Capgo Cloud Build incrementa automaticamente i numeri di costruzione:

• iOS: Estrae il numero di costruzione più recente da App Store Connect, incrementa di 1
• Android: Estrae il massimo versionCode dalla Google Play, incrementa di 1

Quando --skip-build-number-bump è impostato, il build utilizza la versione già presente nei file del progetto (progetto Xcode o) build.gradle).

Carica Output

CLI Flag	Variabile di ambiente	Chiave delle credenziali	Predefinito	Descrizione
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	Carica output di build (IPA/APK/AAB) su Capgo archiviazione. Quando impostato tramite variabile di ambiente, utilizza BUILD_OUTPUT_UPLOAD_ENABLED=true.
--no-output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	—	—	Disable output upload. When set via env var, use BUILD_OUTPUT_UPLOAD_ENABLED=false.
--output-retention <duration>	BUILD_OUTPUT_RETENTION_SECONDS	BUILD_OUTPUT_RETENTION_SECONDS	1h	Come restano attivi i collegamenti di download
--output-record <path>	—	—	—	Dopo un costruzione riuscita, scrivi un record JSON (ID lavoro, stato, URL di download, QR code) su <path> — leggilo nuovamente con build last-output.

Formato di conservazione: Usa durate leggibili dall'uomo come 1h, 6h, 2d, 7d. Minimo è 1 ora, massimo è 7 giorni. Quando impostato tramite variabile di ambiente, utilizza secondi (ad esempio, 3600 per 1 ora).

Build cache

Capgo salva artefatti nativi compilati (CocoaPods, Gradle e relative output di costruzione) per app così i rebuild iniziano più velocemente. La cache di costruzione è abilitata di default per ogni app

CLI Bandiera	API campo	Predefinito	Descrizione
--no-cache	cache_enabled: false	cache abilitato	Disabilita il cache per questa costruzione: salta il ripristino e non salvare un nuovo elemento
--cache-key <value>	cache_key	(omit)	Dividi il cache (ad esempio) prod, stagingOmettere per un cache condiviso generale per app

CLI equivalenti: build request accetta --no-cache e --cache-key.

Consiglio

Usa diversi --cache-key valori quando le versioni RC e di produzione condividono lo stesso ID dell'applicazione, ma non devono riutilizzare l'output compilato l'uno dell'altro — ad esempio --cache-key=prod e --cache-key=staging.

Esempi di CLI:

# 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 / payload del webhook (quando il tuo integrazione chiama Capgo Costruisci direttamente):

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

Ometti cache_key per il cache generale condiviso. Imposta cache_key a suddividere per ambiente. Imposta "cache_enabled": false a disabilitare il cache per una singola richiesta (lo stesso di) --no-cache).

Se un build sembra riuscito ma l'artifact è sbagliato — o un AAB Android manca dopo aver passato da RC a produzione — prova un chiave di cache dedicata o un build a singolo uso. Vedi --no-cache costruisci. Vedi Risoluzione dei problemi: ripristino cache errato.

Autenticazione

CLI Bandiera	Variabile di ambiente	Predefinito	Descrizione
-a, --apikey <key>	CAPGO_TOKEN	—	Capgo API chiave per l'autenticazione
--supa-host <host>	—	—	Host Supabase personalizzato (solo per auto-hosting)
--supa-anon <key>	—	—	Chiave anonima Supabase personalizzata (solo per auto-hosting)

---

Riferimento rapido per le variabili di ambiente

Pronto per la copia-incolla nel tuo pipeline CI/CD. Tutte le variabili sono facoltative — imposta solo quelle che ti servono.

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"

Controllo della costruzione

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

---

Salvataggio delle credenziali

Salva le credenziali localmente

Invece di passare flag o variabili di ambiente ogni volta, salva le credenziali una volta:

# 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

Posizioni di archiviazione

Flag	Posizione	Caso d'uso
(default)	~/.capgo-credentials/credentials.json	Condiviso su tutti i progetti sul tuo computer
--local	.capgo-credentials.json in cartella del progetto	Per progetto — sovrascrive il globale quando entrambi esistono

Il file delle credenziali è identificato da ID dell'app (ad es. com.example.myapp), quindi un singolo file delle credenziali può memorizzare impostazioni per più app senza conflitti. Le credenziali di ogni app sono ulteriormente suddivise per piattaforma (ios / android).

Attento!

Aggiungi .capgo-credentials.json aggiungi a .gitignore Se si utilizzano credenziali locali. Mai commitare le credenziali al controllo di versione.

Gestisci Credenziali Salvate

# 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

---

Esempi

GitHub Azioni

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

Utilizzo diretto delle CLI Flag

# 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

Configurazione mista

Combina le credenziali salvate con le sovrascritture CLI:

# 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

I credenziali salvate forniscono dettagli di firma mentre i flag CLI sovrascrivono il comportamento di costruzione per questa esecuzione specifica.