Opzioni di configurazione

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

Precedenza della Configurazione

Ogni opzione di costruzione può essere impostata in più modi. Quando lo stesso opzione viene 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 le tue credenziali salvate hanno SKIP_BUILD_NUMBER_BUMP=true ma passi --no-skip-build-number-bump sul CLI, la CLI flag vince e i numeri di costruzione saranno incrementati automaticamente.

Consiglio

Per le pipeline CI/CD, le variabili di ambiente sono spesso le più comode. Per lo sviluppo locale, le credenziali salvate (via build credentials saveevitano di ripetere le flag ogni volta.

---

Opzioni iOS

Code Firma

CLI Flag	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
--build-provision-profile-base64 <profile>	BUILD_PROVISION_PROFILE_BASE64	BUILD_PROVISION_PROFILE_BASE64	—	Codificato in Base64 .mobileprovision profilo di provisioning
--build-provision-profile-base64-prod <profile>	BUILD_PROVISION_PROFILE_BASE64_PROD	BUILD_PROVISION_PROFILE_BASE64_PROD	—	Profilo di provisioning di produzione (facoltativo, per la distribuzione su App Store)
--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	—	Chiave ID di App Store Connect API
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	ID emittente App Store Connect (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	chiave App Store Connect API codificata in Base64 (.p8 file)
--apple-profile-name <name>	APPLE_PROFILE_NAME	APPLE_PROFILE_NAME	—	nome del profilo di provisioning come mostrato nel portale dello sviluppatore Apple
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	ID del team App Store Connect

Nota

Autenticazione alternativa: Puoi anche utilizzare un ID Apple + password app-specific al posto delle chiavi API. Passa --apple-id <email> e --apple-app-specific-password <password> (variabili di ambiente: APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD). Le chiavi API sono raccomandate per CI/CD.

Impostazioni di compilazione iOS

CLI Flag	Variabile di ambiente	Chiave delle credenziali	Predefinito	Descrizione
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Schema Xcode per la compilazione
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Target Xcode per la lettura delle impostazioni di compilazione

---

Opzioni Android

Cifratura del keystore

CLI Flag	Variabile di ambiente	Chiave delle credenziali	Impostazione predefinita	Descrizione
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	File del 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 del keystore

Configurazione di Google Play

CLI Flag	Variabile di ambiente	Chiave delle credenziali	Impostazione predefinita	Descrizione
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Chiave JSON di servizio Google Play codificata in Base64

Impostazioni di costruzione Android

Variabile di ambiente	Impostazione predefinita	Descrizione
PLAY_STORE_TRACK	internal	Rilascio di Google Play (internal, alpha, beta, production)
PLAY_STORE_RELEASE_STATUS	draft	Stato di rilascio su Google Play (draft, completed)

---

Opzioni di controllo della costruzione

Queste opzioni funzionano per entrambi i build di iOS e Android.

Modalità di costruzione

CLI Flag	Descrizione	Richiesto.
--platform <platform>	—	o ios o android
--build-mode <mode>	release	debug o release
--build-config <json>	—	Configurazione JSON aggiuntiva per la costruzione
--path <path>	.	Directory del progetto
--verbose	false	Abilita registrazione di logging di costruzione dettagliata

Controllo del numero di costruzione

CLI Flag	Variabile di ambiente	Chiave delle credenziali	Predefinito	Descrizione
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	Saltare l'aumento 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 di Output

CLI Flag	Variabile di 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) 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 degli output. 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 link di download

Formato di conservazione: Utilizza 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).

Autenticazione

CLI Flag	Variabile di ambiente	Impostazione predefinita	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 alle variabili di ambiente

Copia-incolla pronto per il 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>"
BUILD_PROVISION_PROFILE_BASE64="<base64-encoded .mobileprovision>"
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>"
APPLE_PROFILE_NAME="My App Distribution Profile"
APP_STORE_CONNECT_TEAM_ID="TEAM123456"

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

---

Archiviazione delle credenziali

Salva le credenziali localmente

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

# Save iOS credentials
bunx @capgo/cli build credentials save \
  --platform ios \
  --certificate ./dist_cert.p12 \
  --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-profile-name "My App Profile" \
  --apple-team-id TEAM123456

# Save Android credentials
bunx @capgo/cli 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	Utilizzo
(di default)	~/.capgo-credentials/credentials.json	Globale — condivisa tra tutti i progetti sul tuo computer
--local	.capgo-credentials.json in cartella del progetto	Per-progetto — sovrascrive la globale quando entrambe esistono

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

Attenzione

Aggiungi .capgo-credentials.json alla tua .gitignore se si utilizzano credenziali locali. Mai commetti le credenziali alla versione di controllo.

Gestisci Credenziali Salvate

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

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

# Clear saved credentials
bunx @capgo/cli 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 build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.IOS_CERTIFICATE }}
          BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.IOS_PROFILE }}
          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 }}
          APPLE_PROFILE_NAME: ${{ secrets.APPLE_PROFILE_NAME }}
          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 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 Bandiere

# Build iOS with all options inline
bunx @capgo/cli 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 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 build credentials save --platform ios \
  --certificate ./cert.p12 \
  --provisioning-profile ./profile.mobileprovision \
  --output-upload

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

Le credenziali salvate forniscono dettagli di firma mentre CLI flag sovrascrive il comportamento di costruzione per questa esecuzione specifica.