Opzioni di configurazione

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

Precedenza della configurazione

Ogni opzione di build può essere impostata in diversi modi. Se la stessa opzione è definita in più punti, hanno la precedenza le fonti con priorità più alta:

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 le tue credenziali salvate hanno SKIP_BUILD_NUMBER_BUMP=true ma tu passi --no-skip-build-number-bump sulla CLI, la flag CLI ha la precedenza e i numeri di build verranno incrementati automaticamente.

Tip

Per le pipeline CI/CD, le variabili d'ambiente sono di solito la soluzione più comoda. Per lo sviluppo locale, le credenziali salvate (tramite build credentials save) evitano di ripetere le flag ogni volta.

---

Opzioni iOS

Firma Code

Flag CLI	Variabile d'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	—	Provisioning profile come path oppure bundleId=path mapping. 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 (ommettere se il certificato non ha password)

Autenticazione App Store Connect

Flag CLI	Variabile d'ambiente	Chiave delle credenziali	Predefinito	Descrizione
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	Key ID API di App Store Connect
--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	—	Chiave API di App Store Connect codificata in Base64 (.p8 file)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	Team ID di App Store Connect

Non consigliato

Si sconsiglia l'autenticazione tramite password specifiche per l'app e ne è sconsigliato l'uso. Esiste solo come percorso di compatibilità per i team in migrazione da Ionic Appflow (che ne faceva affidamento). È legata a un Apple ID personale senza permessi granulari, non può interrogare App Store Connect (quindi i numeri di build ricorrono a un timestamp) e copre solo l'upload su TestFlight. Preferisci una chiave API di App Store Connect (.p8) invece: è l'opzione consigliata, più potente e più sicura per la CI/CD.

Autenticazione con password specifica per l'app (non consigliata)

Flag CLI	Variabile d'ambiente	Chiave delle credenziali	Predefinito	Descrizione
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	Email dell'Apple ID dell'account che possiede l'app
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	Password specifica per l'app (xxxx-xxxx-xxxx-xxxx) generata il appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	ID numerico dell'app su App Store Connect (es. 1234567890)

Attenzione

Tutti e tre i campi sono richiesti insieme. Il valore numerico APPLE_APP_ID (in App Store Connect → la tua app → App Information → Apple ID) è obbligatorio: senza di esso fastlane ricorre a un login interattivo 2FA che non può essere completato sul build runner. Quando si usa questo metodo, il build number ricade su un valore basato su timestamp, perché App Store Connect non viene interrogato per l'ultimo build number.

Impostazioni build iOS

Flag CLI	Variabile d'ambiente	Chiave delle credenziali	Predefinito	Descrizione
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Xcode scheme da buildare
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Target Xcode per leggere le impostazioni di build
--ios-distribution <mode>	CAPGO_IOS_DISTRIBUTION	CAPGO_IOS_DISTRIBUTION	app_store	Modalità di distribuzione: app_store oppure ad_hoc
--xcode-version <version>	CAPGO_IOS_XCODE_VERSION	CAPGO_IOS_XCODE_VERSION	qualsiasi	Esegui la build con questa versione di Xcode, ad es. 26, 26.0.1 oppure 27. Una versione principale accetta qualsiasi versione minore. La build fallisce subito ed elenca le versioni disponibili se nessuna corrisponde.

Xcode 27

Esegui la build con Xcode 27 (iOS 27 SDK) con --xcode-version 27:

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

Le app create con SDK per iOS 27 devono adottare il ciclo di vita UIScene: senza un UIApplicationSceneManifest nella Info.plist e un scene delegate, iOS 27 arresta l'app all'avvio. Capgo blocca queste build prima che partano (controllo prescan ios/plist-scene-lifecycle-xcode27). Aggiungi un SceneDelegate e a una UIApplicationSceneManifest a ios/App/App/Info.plist, o continua a compilare con --xcode-version 26 finché non lo fai. Vedi le linee guida di Apple ciclo di vita delle scene.

Fine supporto CocoaPods (dicembre 2026)

Capgo Build smetterà di compilare i progetti iOS che usano CocoaPods a dicembre 2026. Migra il tuo progetto a Swift Package Manager prima di allora: vedi Guida SPM di Capacitor. Fino ad allora, le build con CocoaPods continueranno a funzionare; CLI visualizza un avviso e Capgo invia un promemoria via email agli amministratori della tua organizzazione.

---

Opzioni Android

Firma Keystore

Flag CLI	Variabile d'ambiente	Chiave delle credenziali	Predefinito	Descrizione
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	File keystore codificato in Base64 (.keystore oppure .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	Alias della chiave keystore
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	Password della chiave keystore (se non impostata, usa la password dello store)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	Password del keystore

Configurazione Google Play

Flag CLI	Variabile d'ambiente	Chiave delle credenziali	Predefinito	Descrizione
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Chiave JSON dell'account di servizio Google Play codificata in Base64
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal (o production con --submit-to-store-review)	Track di rilascio Google Play (internal, alpha, beta, production). Inoltrato dall'env CI / CLI al build runner.
--android-release-status <status>	PLAY_STORE_RELEASE_STATUS	PLAY_STORE_RELEASE_STATUS	draft (o completed con --submit-to-store-review)	Stato del rilascio sulla track scelta (draft, completed, inProgress, halted). I valori espliciti sovrascrivono il --submit-to-store-review predefinito.

Impostazioni build Android

Flag CLI	Predefinito	Descrizione
--android-flavor <flavor>	—	Product flavor da buildare (es. production). Obbligatorio se il progetto definisce più flavor.
--android-track <track>	internal	Google Play track per questo upload. Con --submit-to-store-review e nessuna track impostata, Capgo predefinisce production.
--android-release-status <status>	draft	Stato di rilascio Google Play. Con --submit-to-store-review e nessun status impostato, Capgo predefinisce completed.
--in-app-update-priority <0–5>	—	Priorità dell'aggiornamento in-app di Google Play per questo rilascio (più alta = più urgente).
--no-playstore-upload	—	Compila e firma, ma salta l'upload su Play Store (richiede --output-upload).

---

Opzioni di controllo build

Queste opzioni sono valide sia per le build iOS che Android.

Modalità di Build

Flag CLI	Predefinito	Descrizione
--platform <platform>	—	Obbligatorio. ios oppure android
--build-mode <mode>	release	debug oppure release
--path <path>	.	Directory di progetto
--verbose	false	Abilita i log di build dettagliati
--ai-analytics	false	In caso di errore di build, invia i log a Capgo AI per la diagnosi — vedi Diagnosi AI del build

Controllo numero build

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

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

• iOS: Recupera l'ultimo numero di build da App Store Connect e lo incrementa di 1
• Android: Recupera il massimo versionCode da Google Play e lo incrementa di 1

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

Upload dell'output

Flag CLI	Variabile d'ambiente	Chiave delle credenziali	Predefinito	Descrizione
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	Carica gli output di build (IPA/APK/AAB) nello storage di Capgo. Se impostato tramite variabile d'ambiente, usa 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	Durata di validità dei link di download
--output-record <path>	—	—	—	Dopo una build riuscita, scrive un record JSON (ID job, stato, URL di download, QR code) in <path> — rileggilo con build last-output.

Formato di retention: Usa durate leggibili come 1h, 6h, 2d, 7d. Minimo 1 ora, massimo 7 giorni. Se impostato tramite variabile d'ambiente, usa i secondi (es., 3600 per 1 ora).

Cache di build

Capgo salva gli artefatti nativi compilati (CocoaPods, Gradle e relativi output di build) per app così le build ripetute partono più velocemente. Build cache is enabled by default per ogni app.

Flag CLI	campo API	Predefinito	Descrizione
--no-cache	cache_enabled: false	cache attiva	Disabilita la cache per questa build: salta il restore e non salvare una nuova voce
--cache-key <value>	cache_key	(ometti)	Partiziona la cache (ad esempio prod, staging). Ometti per una cache generale condivisa per app

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

Tip

Usa valori --cache-key diversi quando le build RC e di produzione condividono lo stesso app ID ma non devono riutilizzare l'output compilato l'una dell'altra — 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 la tua integrazione chiama direttamente Capgo Build):

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

Ometti cache_key per la cache generale condivisa. Imposta cache_key per partizionare per ambiente. Imposta "cache_enabled": false per disabilitare la cache per una singola richiesta (come --no-cache).

Se una build sembra riuscita ma l'artifact è errato — o un AAB Android manca dopo il passaggio da RC a produzione — prova una cache key dedicata o una --no-cache build. Vedi Troubleshooting: restore della cache errato.

Autenticazione

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

---

Riferimento rapido alle variabili d'ambiente

Pronto da copiare e incollare nella tua pipeline CI/CD. Tutte le variabili sono opzionali: imposta solo ciò che ti 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"
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"

Controllo build

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

---

Storage credenziali

Salva credenziali localmente

Invece di passare flag o variabili d'ambiente ogni volta, salva le credenziali una sola 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

Percorsi di archiviazione

Flag	Posizione	Caso d'uso
(predefinito)	~/.capgo-credentials/credentials.json	Globale — condivisa tra tutti i progetti sulla tua macchina
--local	.capgo-credentials.json nella root del progetto	Per progetto — sovrascrive la globale se entrambe esistono

Le credenziali sono indicizzate per ID app (es. com.example.myapp), in modo che un singolo file di credenziali possa contenere le impostazioni per più app senza conflitti. Le credenziali di ogni app sono inoltre suddivise per piattaforma (ios / android).

Attenzione

Aggiungi .capgo-credentials.json al tuo .gitignore se utilizzi credenziali locali. Non committare mai le credenziali nel version control.

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

Azioni GitHub

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 dei flag CLI

# 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 gli override di 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

Le credenziali salvate forniscono i dettagli di firma, mentre i flag CLI sovrascrivono il comportamento di build per questa esecuzione specifica.