Opciones de configuración

Referencia completa de todas las opciones de configuración de Cloud Build. Usa esta página para encontrar la bandera CLI, la variable de entorno o la clave de credenciales para cualquier configuración de build.

Precedencia de configuración

Cada opción de build se puede configurar de varias formas. Si la misma opción se define en varios lugares, prevalecen las fuentes con mayor prioridad:

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: Si tus credenciales guardadas tienen SKIP_BUILD_NUMBER_BUMP=true pero pasas --no-skip-build-number-bump en CLI, la bandera CLI tiene prioridad y los números de build se incrementarán automáticamente.

Consejo

En pipelines de CI/CD, las variables de entorno suelen ser la opción más práctica. Para desarrollo local, las credenciales guardadas (vía build credentials save) evitan repetir flags cada vez.

---

Opciones de iOS

Firma de Code

Flag CLI	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 aprovisionamiento como path o bundleId=path mapping. Repetible para apps multi-objetivo (app + extensiones); el nombre del perfil se extrae automáticamente.
--p12-password <password>	P12_PASSWORD	P12_PASSWORD	—	Contraseña para el .p12 certificado (omítala si el certificado no tiene contraseña)

Autenticación de App Store Connect

Flag CLI	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	Key ID de API de App Store Connect
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	Issuer ID de App Store Connect (UUID)
--apple-key-content <content>	APPLE_KEY_CONTENT	APPLE_KEY_CONTENT	—	Clave API de App Store Connect codificada en Base64 (.p8 archivo)
--app-store-connect-team-id <id>	APP_STORE_CONNECT_TEAM_ID	APP_STORE_CONNECT_TEAM_ID	—	Team ID de App Store Connect

No recomendado

No se recomienda la autenticación con contraseñas específicas de la app. Solo existe como ruta de compatibilidad para equipos que migran desde Ionic Appflow (que dependía de ella). Está vinculada a un ID de Apple personal sin permisos granulares, no puede consultar App Store Connect (por lo que los números de build usan una marca de tiempo como respaldo) y solo cubre la subida a TestFlight. Opta por una clave API de App Store Connect (.p8) en su lugar: es la opción recomendada, con más capacidades y más segura para CI/CD.

Autenticación con contraseña de aplicación (no recomendado)

Flag CLI	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	Email del Apple ID de la cuenta propietaria de la app
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	Contraseña de aplicación (xxxx-xxxx-xxxx-xxxx) generada en appleid.apple.com
--apple-app-id <id>	APPLE_APP_ID	APPLE_APP_ID	—	ID numérico de la app en App Store Connect (ej. 1234567890)

Precaución

Los tres campos son obligatorios en conjunto. El valor numérico APPLE_APP_ID (en App Store Connect → tu app → App Information → Apple ID) es obligatorio: sin él, fastlane recurre a un login interactivo con 2FA que no puede completarse en el build runner. Al usar este método, el build number pasa a usar un valor basado en timestamp, ya que no se consulta App Store Connect para obtener el último build number.

Configuración de build de iOS

Flag CLI	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Xcode scheme para el build
--ios-target <target>	CAPGO_IOS_TARGET	CAPGO_IOS_TARGET	App	Objetivo de Xcode para leer la configuración de build
--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	Compilar con esta versión de Xcode, p. ej. 26, 26.0.1 o 27. Una versión principal acepta cualquier versión menor. La compilación falla rápidamente y lista las versiones disponibles si ninguna coincide.

Xcode 27

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

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

Las apps creadas con iOS 27 SDK deben adoptar el ciclo de vida de UIScene: sin un UIApplicationSceneManifest en Info.plist y un scene delegate, iOS 27 detiene la app al iniciar. Capgo bloquea estas compilaciones antes de que comiencen (verificación de prescan ios/plist-scene-lifecycle-xcode27). Añade un SceneDelegate y un UIApplicationSceneManifest a ios/App/App/Info.plist, o sigue compilando con --xcode-version 26 hasta que lo hagas. Consulta la guía del ciclo de vida de la escena.

Fin del soporte de CocoaPods (diciembre de 2026)

Capgo Build dejará de compilar proyectos iOS que usen CocoaPods en diciembre de 2026. Migra tu proyecto a Swift Package Manager antes de esa fecha: ver Guía de Capacitor SPM. Until then, CocoaPods builds keep working; the CLI prints a warning and Capgo emails your organization admins a reminder.

---

Opciones de Android

Firma con Keystore

Flag CLI	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--android-keystore-file <keystore>	ANDROID_KEYSTORE_FILE	ANDROID_KEYSTORE_FILE	—	Archivo keystore codificado en Base64 (.keystore o .jks)
--keystore-key-alias <alias>	KEYSTORE_KEY_ALIAS	KEYSTORE_KEY_ALIAS	key0	Alias de la clave Keystore
--keystore-key-password <password>	KEYSTORE_KEY_PASSWORD	KEYSTORE_KEY_PASSWORD	—	Contraseña de la clave Keystore (usa la del almacén si no se define)
--keystore-store-password <password>	KEYSTORE_STORE_PASSWORD	KEYSTORE_STORE_PASSWORD	—	Contraseña del almacén Keystore

Configuración de Google Play

Flag CLI	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--play-config-json <json>	PLAY_CONFIG_JSON	PLAY_CONFIG_JSON	—	Clave JSON de la cuenta de servicio de Google Play en Base64
--android-track <track>	PLAY_STORE_TRACK	PLAY_STORE_TRACK	internal (o production con --submit-to-store-review)	Canal de lanzamiento de Google Play (internal, alpha, beta, production). Reenviado desde el entorno de 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)	Estado de lanzamiento en el canal seleccionado (draft, completed, inProgress, halted). Los valores explícitos sobrescriben el --submit-to-store-review por defecto.

Ajustes de build de Android

Flag CLI	Predeterminado	Descripción
--android-flavor <flavor>	—	Product flavor a compilar (p. ej. production). Obligatorio si tu proyecto define varios flavors.
--android-track <track>	internal	Canal de Google Play para esta subida. Con --submit-to-store-review y sin canal definido, Capgo usa por defecto production.
--android-release-status <status>	draft	Estado del lanzamiento en Google Play. Con --submit-to-store-review y sin estado definido, Capgo usa por defecto completed.
--in-app-update-priority <0–5>	—	Prioridad de actualización in-app de Google Play para este lanzamiento (mayor = más urgente).
--no-playstore-upload	—	Compilar y firmar, pero omitir la subida a Play Store (requiere --output-upload).

---

Opciones de control de compilación

Estas opciones funcionan para builds de iOS y Android.

Modo de build

Flag CLI	Predeterminado	Descripción
--platform <platform>	—	Obligatorio. ios o android
--build-mode <mode>	release	debug o release
--path <path>	.	Directorio del proyecto
--verbose	false	Activar logs de build detallados
--ai-analytics	false	Si el build falla, envía los logs a la IA de Capgo para el diagnóstico — ver Diagnóstico de Build con IA

Control del número de build

Flag CLI	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	Omitir el incremento automático del número de build / versión de code
--no-skip-build-number-bump	—	—	—	Reactivar explícitamente el auto-incremento (sobrescribe las credenciales guardadas)

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

• iOS: Obtiene el último número de build de App Store Connect y lo incrementa en 1
• Android: Obtiene el máximo versionCode de Google Play y lo incrementa en 1

Cuando --skip-build-number-bump está configurado, la build utiliza la versión que ya esté en los archivos de tu proyecto (proyecto Xcode o build.gradle).

Subida de salida

Flag CLI	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	Sube los outputs del build (IPA/APK/AAB) al almacenamiento de Capgo. Si se define mediante env var, usa BUILD_OUTPUT_UPLOAD_ENABLED=true.
--no-output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	—	—	Desactiva la subida de los outputs. Si se define mediante env var, usa BUILD_OUTPUT_UPLOAD_ENABLED=false.
--output-retention <duration>	BUILD_OUTPUT_RETENTION_SECONDS	BUILD_OUTPUT_RETENTION_SECONDS	1h	Cuánto tiempo siguen activos los enlaces de descarga
--output-record <path>	—	—	—	Tras un build exitoso, escribe un registro JSON (job ID, status, download URL, QR code) en <path> — vuelve a leerlo con build last-output.

Formato de retención: Usa duraciones legibles como 1h, 6h, 2d, 7d. El mínimo es 1 hora y el máximo, 7 días. Si se define mediante env var, usa segundos (p. ej., 3600 para 1 hora).

Caché de build

Capgo guarda los artefactos nativos compilados (CocoaPods, Gradle y otras salidas de build relacionadas) por app para que los builds repetidos empiecen más rápido. La caché de build está activada por defecto para cada app.

Flag CLI	Campo API	Predeterminado	Descripción
--no-cache	cache_enabled: false	caché activada	Desactivar la caché para este build: omitir la 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é general compartida por app

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

Consejo

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

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

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

Omitir cache_key para el caché general compartido. Establece cache_key para particionar por entorno. Establece "cache_enabled": false para desactivar el caché en una sola petición (igual que --no-cache).

Si un build parece exitoso pero el artefacto es incorrecto — o falta un AAB de Android al cambiar entre RC y producción — intenta con una cache key dedicada o un --no-cache build. Ver Troubleshooting: wrong cache restore.

Autenticación

Flag CLI	Variable de entorno	Predeterminado	Descripción
-a, --apikey <key>	CAPGO_TOKEN	—	Clave Capgo API para autenticación
--supa-host <host>	—	—	Host personalizado de Supabase (solo autoalojado)
--supa-anon <key>	—	—	Clave anon personalizada de Supabase (solo autoalojado)

---

Referencia rápida de variables de entorno

Listo para copiar y pegar en tu pipeline de CI/CD. Todas las variables son opcionales: configura solo lo que necesites.

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

---

Almacenamiento de credenciales

Guardar credenciales localmente

En lugar de pasar flags o variables de entorno cada vez, guarda las credenciales una sola 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

Flag	Ubicación	Caso de uso
(predeterminado)	~/.capgo-credentials/credentials.json	Global — compartido entre todos los proyectos de tu máquina
--local	.capgo-credentials.json en la raíz del proyecto	Por proyecto — sobrescribe el global si ambos existen

Las credenciales se indexan por ID de la app (p. ej. com.example.myapp), por lo que un único archivo de credenciales puede almacenar configuraciones para varias apps sin conflictos. Las credenciales de cada app se dividen además por plataforma (ios / android).

Precaución

Añadir .capgo-credentials.json a tu .gitignore si usas credenciales locales. Nunca subas credenciales al 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

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

Uso directo de las banderas 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

Configuración mixta

Combina las credenciales guardadas con las sobrecargas 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

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