Options de configuration

Référence complète pour chaque option de configuration du build cloud. Utilisez cette page pour trouver le flag CLI, la variable d'environnement ou la clé d'identification correspondant à chaque paramètre de build.

Priorité de configuration

Chaque option de build peut être définie de plusieurs façons. Lorsqu'une même option est définie à plusieurs endroits, les sources de priorité supérieure 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 identifiants enregistrés ont SKIP_BUILD_NUMBER_BUMP=true mais que 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.

Astuce

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

---

Options iOS

Code Signature

Flag CLI	Variable d'environnement	Clé d'identification	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 mapping. Répétable pour les apps multi-cibles (app + extensions) ; le nom du profil est extrait automatiquement.
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	Mot de passe du .p12 certificat (à omettre si le certificat n’a pas de mot de passe)

Authentification App Store Connect

Flag CLI	Variable d'environnement	Clé d'identification	Par défaut	Description
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	ID de la clé API App Store Connect
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	ID de l'émetteur App Store Connect (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Clé API App Store Connect 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

Non recommandé

L'authentification par mot de passe spécifique à l'app est déconseillée et son usage est à éviter. Elle n'existe que comme solution de compatibilité pour les équipes qui migrent depuis Ionic Appflow (qui l'utilisait). Elle est liée à un identifiant Apple personnel sans permissions granulaires, ne peut pas interroger App Store Connect (les numéros de build retombent donc sur un timestamp) et ne couvre que l'upload vers TestFlight. Préférez une clé API App Store Connect (.p8) : c'est l'option recommandée, plus complète et plus sécurisée pour la CI/CD.

Authentification par mot de passe d’application (non recommandée)

Flag CLI	Variable d'environnement	Clé d'identification	Par défaut	Description
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	E-mail de l’identifiant Apple du compte propriétaire de l’app
--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é le appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	ID numérique de l'app App Store Connect (ex. 1234567890)

Attention

Les trois champs sont obligatoires ensemble. Le numérique APPLE_APP_ID (trouvé dans App Store Connect → votre app → Informations sur l’app → Apple ID) est obligatoire : sans lui, fastlane bascule sur une connexion 2FA interactive qui ne peut pas se terminer sur le build runner. Lorsque cette méthode est utilisée, le numéro de build bascule sur une valeur basée sur un horodatage, car App Store Connect n’est pas interrogé pour le dernier numéro de build.

Paramètres de build iOS

Flag CLI	Variable d'environnement	Clé d'identification	Par défaut	Description
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Schéma Xcode à compiler
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Cible Xcode pour lire les paramètres de build
--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	tous	Build avec cette version de Xcode, ex : 26, 26.0.1 ou 27. Une version majeure accepte n'importe quelle version mineure. Le build échoue rapidement et liste les versions disponibles si aucune ne correspond.

Xcode 27

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

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

Les apps compilées avec l’iOS 27 SDK doivent adopter le cycle de vie UIScene : sans un UIApplicationSceneManifest dans Info.plist et un scene delegate, l’iOS 27 arrête l’app au lancement. Capgo bloque ces builds avant leur démarrage (vérification prescan ios/plist-scene-lifecycle-xcode27). Ajoutez un SceneDelegate et une UIApplicationSceneManifest vers ios/App/App/Info.plist, ou continuez à compiler avec --xcode-version 26 jusqu’à ce que ce soit fait. Consultez le guide du cycle de vie des scènes.

Fin de support de CocoaPods (décembre 2026)

Capgo Build cesse de compiler les projets iOS utilisant CocoaPods en décembre 2026. Migratez votre projet vers Swift Package Manager avant cette date : voir le Guide SPM Capacitor. En attendant, les builds CocoaPods continuent de fonctionner ; CLI affiche un avertissement et Capgo envoie un e-mail de rappel aux administrateurs de votre organisation.

---

Options Android

Signature keystore

Flag CLI	Variable d'environnement	Clé d'identification	Par défaut	Description
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	Fichier keystore encodé en Base64 (.keystore ou .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	Alias de clé Keystore
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	Mot de passe de la clé Keystore (à défaut, celui du store)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	Mot de passe du store Keystore

Configuration Google Play

Flag CLI	Variable d'environnement	Clé d'identification	Par défaut	Description
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Clé JSON de compte de service Google Play en Base64
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal (ou production par --submit-to-store-review)	Canal de release Google Play (internal, alpha, beta, production). Transmis de l'env CI / CLI vers le runner de build.
--android-release-status <status>	PLAY_STORE_RELEASE_STATUS	PLAY_STORE_RELEASE_STATUS	draft (ou completed par --submit-to-store-review)	Statut de la release sur le canal choisi (draft, completed, inProgress, halted). Les valeurs explicites remplacent la --submit-to-store-review par défaut.

Paramètres de build Android

Flag CLI	Par défaut	Description
--android-flavor <flavor>	—	Flavor produit à compiler (ex. production). Requis si votre projet définit plusieurs flavors.
--android-track <track>	internal	Track Google Play pour cet upload. Avec --submit-to-store-review et sans track défini, Capgo utilise par défaut production.
--android-release-status <status>	draft	Statut de release Google Play. Avec --submit-to-store-review et sans statut défini, Capgo utilise par défaut completed.
--in-app-update-priority <0–5>	—	Priorité de mise à jour in-app Google Play pour cette release (plus élevée = plus urgent).
--no-playstore-upload	—	Compiler et signer, mais ignorer l'upload sur le Play Store (nécessite --output-upload).

---

Options de contrôle du build

Ces options s’appliquent aux builds iOS et Android.

Mode de build

Flag CLI	Par défaut	Description
--platform <platform>	—	Requis. ios ou android
--build-mode <mode>	release	debug ou release
--path <path>	.	Répertoire du projet
--verbose	false	Activer les logs de build détaillés
--ai-analytics	false	En cas d’échec du build, envoyez les logs à l’IA Capgo pour diagnostic — voir Diagnostic de build par IA

Contrôle du numéro de build

Flag CLI	Variable d'environnement	Clé d'identification	Par défaut	Description
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	Ignorer l’incrémentation automatique du numéro de build / de la version code
--no-skip-build-number-bump	—	—	—	Réactiver explicitement l’incrémentation automatique (remplace les identifiants enregistrés)

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

• iOS : Récupère le dernier numéro de build depuis App Store Connect et l’incrémente de 1
• Android : Récupère le max versionCode depuis Google Play et l’incrémente de 1

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

Upload de l'output

Flag CLI	Variable d'environnement	Clé d'identification	Par 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	Durée de validité des liens de téléchargement
--output-record <path>	—	—	—	Après un build réussi, écrire un enregistrement JSON (ID du job, statut, URL de téléchargement, QR code) dans <path> — le relire avec build last-output.

Format de rétention : Utiliser des durées lisibles comme 1h, 6h, 2d, 7d. Minimum 1 heure, maximum 7 jours. Si défini via une variable d’environnement, utiliser des secondes (par ex., 3600 pour 1 heure).

Cache de build

Capgo conserve les artefacts natifs compilés (CocoaPods, Gradle et sorties de build associées) par application afin que les builds répétés démarrent plus rapidement. Le build cache est activé par défaut pour chaque application.

Flag CLI	champ API	Par défaut	Description
--no-cache	cache_enabled: false	cache activé	Désactiver le cache pour ce build : ignorer la restauration et ne pas enregistrer une nouvelle entrée
--cache-key <value>	cache_key	(omettre)	Partitionner le cache (par exemple prod, staging). Omettre pour un cache général partagé par application

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

Astuce

Utiliser des --cache-key valeurs différentes lorsque les builds RC et production partagent le même ID d’application mais ne doivent pas réutiliser leur sortie compilée — par exemple --cache-key=prod et --cache-key=staging.

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

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

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

Si un build semble réussi mais que l’artefact est incorrect — ou si un AAB Android est manquant après un basculement entre RC et production — essayez une clé de cache dédiée ou un --no-cache build. Voir Dépannage : erreur de restauration du cache.

Authentification

Flag CLI	Variable d'environnement	Par défaut	Description
-a, --apikey <key>	CAPGO_TOKEN	—	Clé Capgo API pour l’authentification
--supa-host <host>	—	—	Hôte Supabase personnalisé (auto-hébergement uniquement)
--supa-anon <key>	—	—	Clé anon Supabase personnalisée (auto-hébergement uniquement)

---

Référence rapide des variables d'environnement

Prêt à copier-coller pour votre pipeline CI/CD. Toutes les variables sont optionnelles — ne définissez que celles 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 du 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"

---

Stockage des credentials

Enregistrer les credentials localement

Instead of passing flags or env vars every time, save credentials once:

# 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

Flag	Localisation	Cas d’usage
(par défaut)	~/.capgo-credentials/credentials.json	Global — commun à tous les projets de votre machine
--local	.capgo-credentials.json à la racine du projet	Par projet — remplace le global si les deux existent

Les identifiants sont indexés par ID de l’app (ex. com.example.myapp), de sorte qu’un seul fichier de credentials peut stocker les paramètres de plusieurs apps sans conflit. Les credentials de chaque app sont ensuite séparés par plateforme (ios / android).

Attention

Ajoutez .capgo-credentials.json vers votre .gitignore si vous utilisez des identifiants locaux. Ne commitez jamais d'identifiants dans la gestion de versions.

Gérer les credentials enregistré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

---

Exemples

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

Utiliser directement les flags 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

Configuration mixte

Combinez les identifiants enregistrés avec les surcharges 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

Les identifiants enregistrés fournissent les détails de signature, tandis que les flags CLI surchargent le comportement du build pour cette exécution spécifique.