Options de configuration

Référence complète pour chaque option de configuration de Cloud Build. Utilisez cette page pour trouver la CLI drapeau, variable d'environnement ou clé de crédential pour n'importe quelle configuration de build.

Prééminence de la configuration

Tout option de build peut être définie de plusieurs manières. Lorsqu'une même option est définie dans plusieurs endroits, les sources de priorité élevée l'emportent :

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

Exemple : Si vos informations de connexion enregistrées ont SKIP_BUILD_NUMBER_BUMP=true mais vous passez --no-skip-build-number-bump sur le CLI, le flag CLI l'emporte et les numéros de build seront incrémentés automatiquement.

Conseil

Pour les pipelines CI/CD, les variables d'environnement sont généralement les plus pratiques. Pour le développement local, les informations de connexion enregistrées (via build credentials save) évitent de répéter les flags à chaque fois.

---

Options iOS

Code Signature

CLI Drapeau	Variable d'environnement	Clé de la credenciale	Par défaut	Description
--build-certificate-base64 <cert>	BUILD_CERTIFICATE_BASE64	BUILD_CERTIFICATE_BASE64	—	Encodé en Base64 .p12 certificat de distribution
--ios-provisioning-profile <map>	CAPGO_IOS_PROVISIONING_MAP	CAPGO_IOS_PROVISIONING_MAP	—	profil de provisionnement en tant que path ou bundleId=path cartographie. Répétable pour les applications multi-cibles (application + extensions) ; le nom du profil est automatiquement extrait.
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	mot de passe pour le .p12 certificat (omettre si le certificat n'a pas de mot de passe)

Authentification App Store Connect

CLI Drapeau	Variable d'environnement	Clé de l'authentification	Défaut	Description
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	Clé App Store Connect API ID
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	ID émetteur App Store Connect (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Clé App Store Connect API encodée en Base64 (.p8 fichier)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	ID d'équipe App Store Connect

Not recommandé

App-specific password authentication is discouraged and its use is advised against. Cela n'existe que comme un chemin de compatibilité pour les équipes en train de migrer de Ionic Appflow (qui s'y appuyait). Il est lié à un ID Apple personnel sans permissions granulaires, ne peut pas interroger App Store Connect (donc les numéros de build retombent sur une date et heure), et ne couvre que l'envoi de TestFlight lui-même. Préférez une clé App Store Connect API (.p8) au lieu de cela : c'est la recommandation, plus capable et plus sécurisé pour les CI/CD.

Mot de passe d'application d'authentification (non recommandé)

CLI Drapeau	Variable d'environnement	Clé de credenciaux	Par défaut	Description
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	Adresse e-mail de l'ID Apple qui possède l'application
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	Mot de passe d'application (xxxx-xxxx-xxxx-xxxx) généré sur appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	App ID numérique de l'App Store Connect (par exemple) 1234567890)

Avertissement

Tous les trois champs sont nécessaires ensemble. Le nombre APPLE_APP_ID (trouvé dans App Store Connect → votre application → Informations sur l'application → Identifiant Apple) est obligatoire : sans cela, fastlane revient à un login 2FA interactif qui ne peut pas se terminer sur le runner de build. Lorsque cette méthode est utilisée, le numéro de build revient à une valeur basée sur l'heure, car App Store Connect n'est pas interrogé pour le dernier numéro de build.

Paramètres de build iOS

CLI Drapeau	Variable d'environnement	Clé de l'identifiant	Par défaut	Description
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Schéma Xcode pour la construction
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Cible Xcode pour la lecture des paramètres de construction
--ios-distribution <mode>	CAPGO_IOS_DISTRIBUTION	CAPGO_IOS_DISTRIBUTION	app_store	Mode de distribution : app_store ou ad_hoc
--xcode-version <version>	CAPGO_IOS_XCODE_VERSION	CAPGO_IOS_XCODE_VERSION	ou	Construire avec cette version d'Xcode, par exemple. 26, 26.0.1 ou 27Une version majeure accepte toute version mineure. La construction échoue rapidement et liste les versions disponibles lorsque aucune correspondance n'est trouvée.

Xcode 27

Construire avec Xcode 27 (iOS 27 SDK) avec --xcode-version 27:

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

Applications construites avec l'iOS 27 SDK doivent adopter le cycle de vie de UIScene : sans un UIApplicationSceneManifest en Info.plist et un délégué de scene, l'iOS 27 arrête l'application au lancement. Capgo bloque ces constructions avant qu'elles ne commencent (vérification avant le lancement ios/plist-scene-lifecycle-xcode27et un SceneDelegate à UIApplicationSceneManifest to ios/App/App/Info.plistou continuez à construire avec --xcode-version 26 Jusqu'à ce que vous le fassiez. Consultez la page d'Apple. guide du cycle de vie de la scene.

Fin de support de CocoaPods (décembre 2026)

Capgo La construction s'arrête de construire les projets iOS qui utilisent CocoaPods en décembre 2026. Migratez votre projet vers le gestionnaire de packages Swift avant cela : voir le Capacitor Guide SPMJusqu'à présent, les builds CocoaPods continuent de fonctionner ; l'CLI affiche un avertissement et Capgo envoie un rappel par courriel à vos administrateurs d'organisation.

---

Options Android

Signature de clé de coffre

CLI Drapeau	Variable d'environnement	Clé de l'identifiant	Par défaut	Description
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	Fichier de clé de coffre en base64 (.keystore ou .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	Alias de la clé de coffre
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	Mot de passe de la clé de coffre (retourne au mot de passe du magasin si non défini)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	Mot de passe du magasin de clés

Configuration de Google Play

CLI Drapeau	Variable d'environnement	Clé de l'identifiant	Par défaut	Description
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Clé JSON de compte Google Play encodée en Base64
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal (ou production context --submit-to-store-review)	Google Play release track (internal, alpha, beta, production. Transféré depuis l'environnement CI / CLI dans l'exécuteur de build.
--android-release-status <status>	PLAY_STORE_RELEASE_STATUS	PLAY_STORE_RELEASE_STATUS	draft (ou completed context --submit-to-store-review)	piste de publication Google Play (draft, completed, inProgress, haltedValeurs explicites prennent le dessus de la --submit-to-store-review français.

Paramètres de construction Android

CLI Drapeau	Défaut	Description
--android-flavor <flavor>	—	Flavor de produit à construire (par exemple production). Requis si votre projet définit plusieurs saveurs.
--android-track <track>	internal	Piste Google Play pour ce téléchargement. Avec --submit-to-store-review et sans piste définie, Capgo se définit par défaut à production.
--android-release-status <status>	draft	l'état de publication Google Play. Avec --submit-to-store-review et aucun statut défini, Capgo se définit par défaut completed.
--in-app-update-priority <0–5>	—	Priorité d'actualisation de l'application Google Play pour cette version (plus élevée = plus urgente).
--no-playstore-upload	—	Build et signez, mais sautez l'upload sur Google Play (nécessite) --output-upload).

---

Options de contrôle de la construction

Ces options fonctionnent pour les builds iOS et Android.

Build Mode

CLI Drapeau	Par défaut	Description
--platform <platform>	—	Obligatoire. ios ou android
--build-mode <mode>	release	debug ou release
--path <path>	.	Répertoire du projet
--verbose	false	Activer la journalisation détaillée de la construction
--ai-analytics	false	En cas d'erreur de build, envoyez les journaux à Capgo AI pour le diagnostic — voir Diagnostic de construction AI

Contrôle du numéro de construction

CLI Drapeau	Variable d'environnement	Clé de crédential	Par défaut	Description
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	Sauvegarder le numéro de version automatique / la version code
--no-skip-build-number-bump	—	—	—	Explicitly re-enable auto-increment (overrides saved credentials)

Par défaut, Capgo Cloud Build incrémente automatiquement les numéros de version :

• iOS : Récupère le dernier numéro de version disponible sur App Store Connect, l'incrémente de 1
• Android : Récupère le max versionCode de Google Play, l'incrémente de 1

Lorsque --skip-build-number-bump est défini, la build utilise la version qui est déjà dans vos fichiers de projet (projet Xcode ou build.gradle).

Téléchargement de sortie

CLI Drapeau	Variable d'environnement	Clé de l'authentification	Défaut	Description
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	Upload build outputs (IPA/APK/AAB) to Capgo storage. When set via env var, use 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	La durée de validité des liens de téléchargement
--output-record <path>	—	—	—	Après une build réussie, écrire un enregistrement JSON (ID de travail, statut, URL de téléchargement, QR code) à <path> — lire à nouveau avec build last-output.

Format de conservation : Utilisez des durées lisibles par l'homme comme 1h, 6h, 2d, 7d. Minimum is 1 hour, maximum is 7 days. When set via env var, use seconds (e.g., 3600 Cache de construction

Build cache

Capgo enregistre les artefacts natifs compilés (CocoaPods, Gradle et les sorties de build connexes) par application Le cache de construction est activé par défaut pour chaque application. __CAPGO_KEEP_0__ Drapeau

CLI Champ	champ API	Default	Description
--no-cache	cache_enabled: false	cache sur	Désactiver le cache pour cette build : ignorer le chargement et ne pas enregistrer une nouvelle entrée
--cache-key <value>	cache_key	(omettre)	Partitionner le cache (par exemple prod, staging. Omettre pour une cache partagée générale par application

équivalents : CLI build request accepte --no-cache et --cache-key.

Conseil

Utilisez des valeurs différentes --cache-key lorsque les builds RC et de production partagent le même ID d'application mais ne doivent pas réutiliser les résultats compilés les uns des autres — par exemple --cache-key=prod et --cache-key=staging.

CLI exemples :

# 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 de webhook (lorsque votre intégration appelle Capgo Build directement :)

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

Omettre cache_key pour le cache partagé général. Définir cache_key pour partitionner par environnement. Définir "cache_enabled": false pour désactiver le cache pour une seule requête (même que --no-cache).

Si une build semble réussie mais l'artifact est incorrect — ou un AAB Android manque après avoir changé RC vs production — essayez une clé de cache dédiée ou une build unique. --no-cache Voir Troubleshooting : restauration de cache incorrecte.

Authentification

CLI Drapeau	Variable d'environnement	Défaut	Description
-a, --apikey <key>	CAPGO_TOKEN	—	Capgo API clé d'authentification
--supa-host <host>	—	—	Custom Supabase host (self-hosting only)
--supa-anon <key>	—	—	Custom Supabase anon key (self-hosting only)

---

Référence rapide des variables d'environnement

Prêt à copier-coller pour votre pipeline CI/CD. Toutes les variables sont optionnelles — n'activez que ce dont vous avez besoin.

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"

Contrôle de la construction

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

---

Stockage des informations d'identification

Enregistrer les informations d'identification localement

Enregistrez les informations d'identification une fois :

# 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

Emplacements de stockage

Drapeau	Lieu	Utilisation
Par défaut	~/.capgo-credentials/credentials.json	Global — partagé par tous les projets sur votre machine
--local	.capgo-credentials.json Dans le répertoire racine du projet	Par projet — remplace le global lorsqu'il existe les deux

Les informations d'identification sont associées à app ID (par exemple) com.example.myapp, afin qu'un seul fichier de credenciaux puisse stocker les paramètres pour plusieurs applications sans conflits. Les credenciaux de chaque application sont encore plus divisés par plateforme (ios / android).

Attention

Ajouter .capgo-credentials.json à votre .gitignore if using local credentials. Never commit credentials to version control.

Gérer les Identifiants Sauvegardés

# 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

---

Examples

GitHub Actions

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

En utilisant les drapeaux CLI directement

# 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

Configuration mixte

Combine saved credentials with CLI overrides:

# 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

The saved credentials provide signing details while CLI flags override build behavior for this specific run.