Opciones de Configuración

Referencia completa para cada opción de configuración de Cloud Build. Utilice esta página para encontrar la bandera CLI, la variable de entorno, o la clave de credencial para cualquier configuración de compilación.

Precedencia de la configuración

Cada opción de compilación puede configurarse de varias maneras. Cuando la misma opción se establece en varios lugares, las fuentes de mayor prioridad ganan.

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

Ejemplo: If tus credenciales guardadas tienen SKIP_BUILD_NUMBER_BUMP=true pero pasas --no-skip-build-number-bump en el CLI, la bandera CLI gana y los números de compilación se incrementarán automáticamente.

Consejo

Para las pipelines de CI/CD, las variables de entorno suelen ser las más convenientes. Para el desarrollo local, los credenciales guardados (a través de) build credentials saveevite repetir banderas cada vez.

---

Opciones de iOS

Firma Code

CLI Bandera	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--build-certificate-base64 <cert>	BUILD_CERTIFICATE_BASE64	BUILD_CERTIFICATE_BASE64	—	Codificado en Base64 .p12 certificado de distribución
--ios-provisioning-profile <map>	CAPGO_IOS_PROVISIONING_MAP	CAPGO_IOS_PROVISIONING_MAP	—	perfil de provisión como un path o bundleId=path mapeo. Repetible para aplicaciones multi-objetivo (aplicación + extensiones); el nombre del perfil se extrae automáticamente.
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	contraseña para el .p12 certificado (omitir si el certificado no tiene contraseña)

Autenticación de App Store Connect

CLI Bandera	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	Clave de API de App Store Connect
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	ID de emisor de App Store Connect (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Base64-encoded App Store Connect API key (.p8 archivo)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	ID de equipo de App Store Connect

No se recomienda

Se desaconseja la autenticación de contraseña de aplicación y se le aconseja no utilizarla. No existe más que como un camino de compatibilidad para equipos que migran desde Ionic Appflow (que se basaba en ella). Está ligado a una cuenta de Apple ID personal sin permisos granulares, no puede consultar App Store Connect (por lo que los números de compilación recaen en un timestamp), y solo cubre la carga de TestFlight en sí misma. Prefiera una clave de App Store Connect API (.p8) en su lugar: es la opción recomendada, más capaz y más segura para CI/CD.

Autenticación de contraseña de aplicación (no recomendada)

CLI Bandera	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	Correo electrónico de la cuenta de Apple ID que posee la aplicación
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	Contraseña de la aplicación (xxxx-xxxx-xxxx-xxxx) generada en appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	Numeric App Store Connect app ID (e.g. 1234567890)

Advertencia

Todas las tres opciones son necesarias. El número APPLE_APP_ID (encontrado en App Store Connect → su aplicación → Información de la aplicación → ID de Apple) es obligatorio: sin él, fastlane cae en un login de 2FA interactivo que no puede completarse en el ejecutor de compilación. Cuando se utiliza este método, el número de compilación cae en un valor basado en la fecha, porque App Store Connect no se consulta para el último número de compilación.

Ajustes de compilación de iOS

CLI Bandera	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Esquema de Xcode para construir
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Objetivo de Xcode para leer configuraciones de compilación
--ios-distribution <mode>	CAPGO_IOS_DISTRIBUTION	CAPGO_IOS_DISTRIBUTION	app_store	Modo de distribución: app_store o ad_hoc
--xcode-version <version>	CAPGO_IOS_XCODE_VERSION	CAPGO_IOS_XCODE_VERSION	cualquiera	Construye con esta versión de Xcode, por ejemplo 26, 26.0.1 o 27Una versión mayor acepta cualquier versión menor. La compilación falla rápidamente y lista las versiones disponibles cuando ninguna coincide.

Xcode 27

Construye con Xcode 27 (iOS 27 SDK) con --xcode-version 27:

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

Aplicaciones construidas con iOS 27 SDK deben adoptar el ciclo de vida de UIScene: sin UIApplicationSceneManifest en Info.plist y un delegado de escena, iOS 27 detiene la aplicación al inicio. Capgo bloquea estos builds antes de que comiencen (verificación previa) ios/plist-scene-lifecycle-xcode27y un SceneDelegate para UIApplicationSceneManifest o ios/App/App/Info.plisty continúa construyendo con --xcode-version 26 hasta que lo hagas. Consulta Apple’s Guía del ciclo de vida de la escena.

Fin del soporte de CocoaPods (diciembre 2026)

Capgo La compilación se detiene en los proyectos de iOS que utilizan CocoaPods en diciembre 2026. Migrar su proyecto al Gestor de Paquetes de Swift antes de entonces: consulte el Capacitor Guía del SPMHasta entonces, CocoaPods sigue construyendo; el CLI imprime una advertencia y Capgo envía un recordatorio por correo electrónico a los administradores de tu organización.

---

Opciones de Android

Firma de Keystore

CLI Bandera	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	Archivo de clave en formato Base64 (".keystore o .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	Alias de clave de seguridad
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	Keystore key password (falls back to store password if not set)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	Contraseña de almacenamiento de llaves

Configuración de Google Play

CLI Bandera	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Clave JSON de servicio de Google Play codificada en Base64
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal o production con --submit-to-store-review)	pista de lanzamiento de Google Play (internal, alpha, beta, production). Se transfiere desde el entorno CI / CLI al ejecutor de compilación.
--android-release-status <status>	PLAY_STORE_RELEASE_STATUS	PLAY_STORE_RELEASE_STATUS	draft o completed con --submit-to-store-review)	Estado de lanzamiento en la pista elegida (draft, completed, inProgress, halted). Los valores explícitos sobrescriben el --submit-to-store-review español.

Configuración de compilación de Android

CLI Bandera	Predeterminado	Descripción
--android-flavor <flavor>	—	Flavor de producto para compilar (por ejemplo, production). Requerido si su proyecto define múltiples sabores.
--android-track <track>	internal	Pista de Google Play para esta carga. Con --submit-to-store-review y sin pista configurada, Capgo se establece en production.
--android-release-status <status>	draft	estado de lanzamiento de Google Play. Con --submit-to-store-review and no status set, Capgo defaults to completed.
--in-app-update-priority <0–5>	—	Prioridad de actualización en-aplicación de Google Play para esta versión (mayor = más urgente).
--no-playstore-upload	—	Construye y firma, pero omite la carga en la tienda Play Store (requiere --output-upload).

---

Opciones de control de construcción

Estas opciones funcionan tanto para construcciones de iOS como de Android.

Build Mode

CLI Bandera	Default	Descripción
--platform <platform>	—	Requerido. ios o android
--build-mode <mode>	release	debug o release
--path <path>	.	Directorio del proyecto
--verbose	false	Habilitar registro de compilación detallado
--ai-analytics	false	Al fallar la compilación, enviar registros a Capgo AI para diagnóstico — consulte Diagnóstico de compilación con AI

Control de Número de Compilación

CLI Bandera	Variable de Entorno	Clave de Credenciales	Predeterminado	Descripción
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	No incrementar automáticamente el número de compilación / versión code
--no-skip-build-number-bump	—	—	—	Habilitar incremento automático explícitamente (sobreescribe credenciales guardadas)

Por defecto, Capgo Cloud Build incrementa automáticamente los números de compilación:

• iOS: Obtiene el último número de compilación desde App Store Connect, incrementa en 1
• Android: Obtiene el máximo versionCode desde Google Play, incrementa en 1

Cuando --skip-build-number-bump se establece, la compilación utiliza la versión que ya está en tus archivos de proyecto (proyecto de Xcode o build.gradle).

Subida de salida

CLI Bandera	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--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	How long download links remain active
--output-record <path>	—	—	—	Después de una compilación exitosa, escriba un registro JSON (ID de trabajo, estado, URL de descarga, QR code) a <path> — leerlo de nuevo con build last-output.

Formato de retención: Duraciones legibles por humanos como 1h, 6h, 2d, 7d. Minimum is 1 hour, maximum is 7 days. When set via env var, use seconds (e.g., 3600 para 1 hora).

Build cache

Capgo almacena artefactos nativos compilados (CocoaPods, Gradle y resultados de compilación relacionados) por aplicación para que las compilaciones repetidas comiencen más rápido. Build cache is enabled by default para cada aplicación.

CLI Bandera	API campo	Default	Descripción
--no-cache	cache_enabled: false	cache en caché	Deshabilitar caché para esta construcción: saltar restauración y no guardar una nueva entrada
--cache-key <value>	cache_key	(omitir)	Particionar la caché (por ejemplo prod, staging) Omitir para una caché compartida general por aplicación

equivalentes de CLI: build request acepta --no-cache y --cache-key.

Consejo

Utiliza valores diferentes --cache-key cuando los builds de RC y producción comparten el mismo ID de aplicación pero no deben reutilizar el resultado compilado del otro — por ejemplo --cache-key=prod y --cache-key=staging.

CLI ejemplos:

# 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 / carga de webhook (cuando tu integración llama a Capgo Build directamente):

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

Omitir cache_key para la caché general compartida. Establecer cache_key para particionar por entorno. Establecer "cache_enabled": false para deshabilitar la caché para una solicitud única (igual que --no-cache).

Si un build parece exitoso pero el artefacto está mal — o un AAB de Android está faltando después de cambiar RC vs producción — intenta una clave de caché dedicada o una construcción única --no-cache Ver Troubleshooting: wrong cache restore.

Autenticación

CLI Bandera	Variable de entorno	Default	Descripción
-a, --apikey <key>	CAPGO_TOKEN	—	Capgo API clave para autenticación
--supa-host <host>	—	—	Host de Supabase personalizado (solo autohospedaje)
--supa-anon <key>	—	—	Clave anónima de Supabase personalizada (solo autohospedaje)

---

Referencia rápida de variables de entorno

Preparado para pegar y soltar en tu pipeline CI/CD. Todos los variables son opcionales — solo establece lo que necesitas.

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"

Control de construcción

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

---

Almacenamiento de credenciales

Guardar credenciales localmente

En lugar de pasar banderas o variables de entorno cada vez, guarda credenciales una vez.

# 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

Ubicaciones de almacenamiento

Bandera	Ubicación	Uso de caso
(por defecto)	~/.capgo-credentials/credentials.json	Global — compartido en todos los proyectos en su máquina
--local	.capgo-credentials.json en la raíz del proyecto	Por proyecto — sobreescribe el global cuando ambos existen

Las credenciales están codificadas por app ID (ejemplo) com.example.myappDe esta manera, un archivo de credenciales puede almacenar configuraciones para múltiples aplicaciones sin conflictos. Las credenciales de cada aplicación se dividen además por plataforma.ios / android).

Caution

Advertencia .capgo-credentials.json Agregar .gitignore Si estás utilizando credenciales locales. Nunca comites credenciales a control de versiones.

Gestionar Credenciales Guardadas

# 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

---

Ejemplos

GitHub Acciones

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

Usando CLI Flags Directamente

# 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

Ejemplos de Configuración mixta

Combina credenciales guardadas con sobreescripciones de 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

Los credenciales guardados proporcionan detalles de firma mientras CLI flags sobrescriben el comportamiento de compilación para esta ejecución específica.