Opzioni di configurazione

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

Precedenza della configurazione

Precedenza della configurazione: le __CAPGO_KEEP_0__ bandiere sovrascrivono le variabili di ambiente, che sovrascrivono le credenziali locali, che sovrascrivono le credenziali globali

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

Se le tue credenziali salvate hanno ma passi SKIP_BUILD_NUMBER_BUMP=true sulla __CAPGO_KEEP_0__, la __CAPGO_KEEP_1__ bandiera vince e i numeri di build saranno incrementati automaticamente. --no-skip-build-number-bump on the CLI, the CLI flag wins and build numbers will be auto-incremented.

Per i flussi di lavoro CI/CD, le variabili di ambiente sono spesso le più comode. Per lo sviluppo locale, le credenziali salvate (via

Precedenza della configurazione: le __CAPGO_KEEP_0__ bandiere sovrascrivono le variabili di ambiente, che sovrascrivono le credenziali locali, che sovrascrivono le credenziali globali build credentials saveEvita di ripetere le bandiere ogni volta.

---

Ipotesi per iOS

Code Firma

CLI Bandiera	Variabile di ambiente	Chiave della credenziale	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 un path o bundleId=path mappatura. Ripetibile per app multi-target (app + estensioni); il nome del profilo viene estratto automaticamente.
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	Password per il .p12 certificato (omettere se il certificato non ha password)

Autenticazione App Store Connect

CLI Flag	Variabile di ambiente	Chiave delle credenziali	Predefinito	Descrizione
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	App Store Connect API ID chiave
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	App Store Connect ID emittente (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Base64-encoded App Store Connect API key (.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 si consiglia di evitarla. Esiste solo come percorso di compatibilità per le squadre che stanno migrando da Ionic Appflow (che si basava su di essa). È legata 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. Preferisci una chiave App Store Connect API (.p8) invece: è l'opzione consigliata, più capace e più sicura per CI/CD.

L'autenticazione tramite password app-specific (non consigliata)

CLI Flag	Variabile di ambiente protetta	Chiave della chiave di accesso	Impostazione predefinita	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 di App Store Connect (ad esempio 1234567890)

Attenzione

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

Impostazioni di costruzione iOS

CLI Flag	Variabile di ambiente	Chiave delle credenziali	Predefinito	Descrizione
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Scegli lo schema Xcode per la costruzione
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Scegli il target Xcode per la lettura delle impostazioni di costruzione
--ios-distribution <mode>	CAPGO_IOS_DISTRIBUTION	CAPGO_IOS_DISTRIBUTION	app_store	Modalità di distribuzione: app_store o ad_hoc

---

Opzioni Android

Firma Keystore

CLI Flag	Variabile di ambiente	Chiave delle credenziali	Predefinito	Descrizione
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	File di chiave keystore codificato in Base64 (.keystore o .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	Alias della chiave 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

Configurazione 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
(solo ambiente)	PLAY_STORE_TRACK	—	internal	Rilascio traccia Google Play (internal, alpha, beta, production)
(solo ambiente)	PLAY_STORE_RELEASE_STATUS	—	draft	Stato di rilascio sulla traccia scelta (draft, completed, inProgress, halted)

Impostazioni di costruzione Android

CLI Flag	Predefinito	Descrizione
--android-flavor <flavor>	—	Flavor di prodotto da costruire (ad esempio production). Richiesto se il tuo progetto definisce più flavor.
--in-app-update-priority <0–5>	—	Priorità di aggiornamento in-app Google Play per questo rilascio (più alto = più urgente).
--no-playstore-upload	—	Costruisci e firma, ma saltare l'upload della Play Store (richiede --output-upload).

---

Opzioni di controllo della costruzione

Queste opzioni funzionano per entrambi i build iOS e Android.

Modalità di costruzione

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

Controllo del numero di costruzione

CLI Flag	Variabile di ambiente	Chiave delle credenziali	Impostazione predefinita	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'auto-incremento (sovrascrive le credenziali salvate)

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

• iOS: Estrae il numero di build più recente da App Store Connect, incrementa di 1
• Android: Estrae il massimo versionCode da 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).

Caricamento Output

CLI Flag	Variabile di ambiente	Chiave delle credenziali	Predefinito	Descrizione
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	Carica i risultati della compilazione (IPA/APK/AAB) nel Capgo storage. Quando impostato tramite variabile di ambiente, utilizza BUILD_OUTPUT_UPLOAD_ENABLED=true.
--no-output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	—	—	Disabilita l'upload dei risultati. Quando impostato tramite variabile di ambiente, utilizza BUILD_OUTPUT_UPLOAD_ENABLED=false.
--output-retention <duration>	BUILD_OUTPUT_RETENTION_SECONDS	BUILD_OUTPUT_RETENTION_SECONDS	1h	Quanto tempo rimangono attivi i collegamenti di download
--output-record <path>	—	—	—	Dopo una compilazione riuscita, scrivi un record JSON (ID del lavoro, stato, URL di download, QR code) in <path> — leggilo nuovamente con build last-output.

Formato di conservazione: Utilizza durate leggibili da esseri umani 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).

Autenticazione

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

---

Riferimento rapido alle variabili di ambiente

Pronto per la pipeline CI/CD. Tutti i variabili sono facoltativi — impostare solo ciò che serve.

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

---

Memorizzazione delle credenziali

Salva le credenziali localmente

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

# 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

Luoghi di archiviazione

Flag	Posizione	Utilizzo del caso
(predefinito)	~/.capgo-credentials/credentials.json	Globale — condiviso da tutti i progetti sul tuo computer
--local	.capgo-credentials.json in radice del progetto	Per-progetto — sovrascrive il globale quando entrambi esistono

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

Attenzione

Aggiungi .capgo-credentials.json al tuo .gitignore se si utilizzano credenziali locali. Mai commettere credenziali a 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 di 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 CLI override:

# 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

Il dettaglio di firma fornito dalle credenziali salvate mentre CLI flag sovrascrive il comportamento di costruzione per questa esecuzione specifica.