Opciones de configuración

Complete reference for every Cloud Build configuration option. Use this page to find the CLI flag, environment variable, or credential key for any build setting.

Precedencia de configuración

Cada opción de compilación puede ser configurada de varias maneras. Cuando la misma opción se configura 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: Si sus credenciales guardadas tienen SKIP_BUILD_NUMBER_BUMP=true pero pasa --no-skip-build-number-bump en la bandera CLI, la bandera CLI gana y los números de compilación se incrementarán automáticamente.

Consejo

Para las cadenas de producción CI/CD, las variables de entorno suelen ser las más convenientes. Para el desarrollo local, las credenciales guardadas (a través de build credentials saveEvite repetir banderas cada vez.

---

Opciones de iOS

Code Firma

CLI Bandera	Variable de Entorno	Clave de Credencial	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	—	Profil de provisionamiento como un path o bundleId=path mapa. Repetible para aplicaciones multi-destino (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 Flag	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--apple-key-id <id>	APPLE_KEY_ID	APPLE_KEY_ID	—	App Store Connect API ID de clave
--apple-issuer-id <id>	APPLE_ISSUER_ID	APPLE_ISSUER_ID	—	App Store Connect ID de emisor (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 recomendado

Se desaconseja la autenticación de contraseña específica de la aplicación y se le aconseja en contra. Existió únicamente como un camino de compatibilidad para los equipos que migraban desde Ionic Appflow (que se basaba en ella). Está atado a una ID de Apple personal sin permisos granulares, no puede consultar App Store Connect (por lo que los números de compilación caen 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 específica de la aplicación (no recomendada)

Bandera de CLI	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--apple-id <email>	FASTLANE_USER	FASTLANE_USER	—	Correo electrónico de Apple ID del propietario de la aplicación
--apple-app-specific-password <password>	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD	—	Contraseña específica de la 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 aplicación de App Store Connect (por ejemplo. 1234567890)

Cuidado

All tres campos son requeridos juntos. El numérico APPLE_APP_ID (encontrado en App Store Connect → tu 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 y hora, porque App Store Connect no se consulta para el último número de compilación.

Configuración de compilación de iOS

CLI Flag	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--ios-scheme <scheme>	CAPGO_IOS_SCHEME	CAPGO_IOS_SCHEME	App	Esquema de Xcode para compilar
--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

---

Opciones de Android

Autenticación con llave de almacenamiento

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

Configuración de Google Play

CLI Flag	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
(solo entorno)	PLAY_STORE_TRACK	—	internal	Pista de lanzamiento de Google Play (internal, alpha, beta, production)
(solo de entorno)	PLAY_STORE_RELEASE_STATUS	—	draft	Estado de lanzamiento en la pista elegida (draft, completed, inProgress, halted)

Configuración de compilación de Android

CLI Flag	Predeterminado	Descripción
--android-flavor <flavor>	—	Flavor de producto para compilar (por ejemplo. production). Requerido si su proyecto define múltiples sabores.
--in-app-update-priority <0–5>	—	Prioridad de actualización en la 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 de aplicaciones de Google (requiere --output-upload).

---

Opciones de control de compilación

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

Modo de compilación

CLI Flag	Predeterminado	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 Construcción AI

Control de Número de Construcción

CLI Flag	Variable de Entorno	Clave de Credencial	Predeterminado	Descripción
--skip-build-number-bump	SKIP_BUILD_NUMBER_BUMP	SKIP_BUILD_NUMBER_BUMP	false	Saltar incremento automático del número de construcción / versión code
--no-skip-build-number-bump	—	—	—	Rehabilitar explícitamente la auto-incrementación (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 los archivos de su proyecto (proyecto Xcode o build.gradle).

Carga de salida

CLI Bandera	Variable de entorno	Clave de credenciales	Predeterminado	Descripción
--output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	BUILD_OUTPUT_UPLOAD_ENABLED	false	Subir resultados de compilación (IPA/APK/AAB) a Capgo de almacenamiento. Cuando se establezca mediante variable de entorno, utilice BUILD_OUTPUT_UPLOAD_ENABLED=true.
--no-output-upload	BUILD_OUTPUT_UPLOAD_ENABLED	—	—	No subir resultados de compilación. Cuando se establezca mediante variable de entorno, utilice BUILD_OUTPUT_UPLOAD_ENABLED=false.
--output-retention <duration>	BUILD_OUTPUT_RETENTION_SECONDS	BUILD_OUTPUT_RETENTION_SECONDS	1h	¿Cuánto tiempo permanecen activos los enlaces de descarga
--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: Usar duraciones legibles por humanos como 1h, 6h, 2d, 7d. El mínimo es 1 hora, el máximo es 7 días. Cuando se establezca mediante variable de entorno, utilice segundos (por ejemplo, 3600 por 1 hora).

Autenticación

CLI Flag	Variable de Entorno	Por defecto	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 de anonimo de Supabase personalizado (solo autohospedaje)

---

Referencia rápida de Variable de Entorno

Listo para copiar y pegar en tu pipeline de 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"

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 compilació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, guarde las 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 tu máquina
--local	.capgo-credentials.json en raíz del proyecto	Por proyecto — sobreescribe el global cuando ambos existen

Las credenciales están claveadas por ID de aplicación (por ejemplo, com.example.myapp), por lo que 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).

Advertencia

Agregar .capgo-credentials.json To tu .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 banderas 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

Configuración mixta

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

Los detalles de firma proporcionados por las credenciales guardadas mientras que CLI flags sobrescriben el comportamiento de compilación para esta ejecución específica.