GitHub Acciones

Copia un prompt de configuración con los pasos de instalación y la guía de markdown completa para este plugin.

Automatiza tus compilaciones de iOS y Android directamente desde tu repositorio GitHub. Con un archivo de flujo de trabajo y un puñado de secretos de repositorio, cada empujón, etiqueta o disparo manual puede producir aplicaciones firmadas y listas para almacenar — sin que nadie en el equipo necesite un Mac, Xcode o Android Studio instalado.

¿Qué obtienes

Lanzamientos sin intervención

Etiqueta un lanzamiento en Git y tus binarios firmados de iOS y Android se envían automáticamente a TestFlight y Play Store.

No configuración local

Los contribuyentes en Windows o Linux pueden disparar compilaciones de iOS. Sin Xcode, sin problemas de configuración de provisión, sin certificados de firma compartidos que flotan en los portátiles.

Secretos escalonados

Las credenciales viven en los secretos del repositorio GitHub, escalonados a tu repositorio y visibles solo para el ejecutor de flujo de trabajo. Fácil de rotar, fácil de auditar.

Compilaciones en paralelo

Compila iOS y Android al mismo tiempo con un trabajo de matriz. Un lanzamiento típico se completa en menos de 10 minutos.

Requisitos previos

Antes de configurar el flujo de trabajo, asegúrate de tener:

Una cuenta de Capgo con una suscripción activa y una Capgo API clave
Tu aplicación registrada en Capgo (bunx @capgo/cli@latest app add si no está)
Las credenciales de construcción configuradas localmente con bunx @capgo/cli@latest build init — consulte Gestión de credenciales para el tutorial paso a paso del asistente
Una construcción local exitosa (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug — El CI no es el lugar para depurar tu primera compilación
La GitHub CLI (gh) instalado y autenticado (gh auth login)

Configuración

El Capgo CLI puede exportar tus credenciales locales como un archivo listo para usar. Unido a .env file. Combinado con gh secret set -fCI/CD, esto convierte toda la configuración en tres comandos — sin codificación base64 manual, sin manipulación de JSON, sin copiar y pegar secretos por secreto.

Agregue su Capgo API clave como un secreto de repositorio

La clave API no forma parte del almacén de credenciales por aplicación, así que agregue una vez manualmente:
Ventana de terminal
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Generar la clave en el Capgo panel de control con subir permisos o superior.
Exporte sus credenciales a un .env archivo

Ejecuta el administrador de credenciales interactivo:
ventana de terminal
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
En la IU, selecciona Exportar a .envEl CLI escribe .env.capgo.<appId> en tu directorio actual con permisos 0600 solo de lectura del propietario — por ejemplo, .env.capgo.com.example.appCuando tanto iOS como Android están configurados, los secretos de ambas plataformas se almacenan en el mismo archivo bajo # === IOS === y # === ANDROID === los encabezados de sección. Los nombres de las variables de entorno de iOS y Android son disjuntos, por lo que combinarlos es conflict-free.

Pass --platform ios (o --platform android) para escopar el administrador a una plataforma. La exportación produce entonces un archivo por plataforma como .env.capgo.com.example.app.ios. Útil cuando los secretos de iOS y Android viven en diferentes repositorios o entornos.

Un puñado de alternativas de configuración (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTION) se pueden almacenar bajo cada plataforma de manera independiente y pueden haber divergado. Si el administrador encuentra divergencia, imprime las claves en conflicto, pregunta por confirmación explicita antes de escribir y inserta la lista de conflictos como un comentario en la parte superior del archivo. Re-export con --platform si necesita preservar valores por plataforma.
Envía el .env archivo a GitHub Secrets de Acciones

El gh secret set -f comando lee un archivo dotenv y crea un secreto de repositorio por KEY=value línea:
Ventana de terminal
```
gh secret set -f .env.capgo.com.example.app
```
Eso es todo — todos los secretos que necesita su flujo de trabajo ahora están en GitHub. Verifique con gh secret list.
No cometas el archivo .env
Contiene material de firma de texto plano. Una vez que lo hayas subido a GitHub:
Ventana de terminal
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Re-exporta en cualquier momento en que necesites rotar credenciales — el archivo no es un artefacto de larga duración.
Crear el archivo de flujo de trabajo

Agregar .github/workflows/capgo-build.yml a tu repositorio. Selecciona uno de los tres patrones de disparo a continuación dependiendo de cómo deseas disparar los builds.

¿Qué acaba en tus secretos?

Por referencia, gh secret set -f creará estos secretos de repositorio (tu archivo YAML de flujo de trabajo los referencia por estos nombres exactos):

Plataforma	Secretos creados
iOS	`BUILD_CERTIFICATE_BASE64`, `P12_PASSWORD`, `CAPGO_IOS_PROVISIONING_MAP_BASE64`, `APPLE_KEY_ID`, `APPLE_ISSUER_ID`, `APPLE_KEY_CONTENT`, `APP_STORE_CONNECT_TEAM_ID`
Android	`ANDROID_KEYSTORE_FILE`, `KEYSTORE_KEY_ALIAS`, `KEYSTORE_KEY_PASSWORD`, `KEYSTORE_STORE_PASSWORD`, `PLAY_CONFIG_JSON`
(agregados manualmente)	`CAPGO_TOKEN`

No necesitas memorizar estos — los ejemplos de flujo de trabajo a continuación ya hacen referencia a todos ellos.

Ejemplos de Flujo de Trabajo

Los tres ejemplos a continuación cubren los patrones más comunes. Todos utilizan la misma forma: revisa el repositorio, instala dependencias, crea activos web, sincroniza con nativo, luego llama Capgo Construye con credenciales pasadas como variables de entorno.

1. Disparador Manual

Permite a cualquier persona con acceso de escritura disparar un build desde el Acciones pulgador en GitHub con un menú desplegable de plataforma. Útil para pruebas de ad-hoc o iniciar un lanzamiento a demanda.

name: Capgo Build (Manual)

on:
  workflow_dispatch:
    inputs:
      platform:
        description: 'Platform to build'
        required: true
        default: 'android'
        type: choice
        options: [ios, android, both]
      mode:
        description: 'Build mode'
        required: true
        default: 'debug'
        type: choice
        options: [debug, release]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync

      - name: Trigger Capgo Build
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          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 }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ inputs.platform }} \
            --build-mode ${{ inputs.mode }}

Sustituir com.example.app con tu ID de aplicación. Una vez que se haya confirmado, vaya a Acciones → Capgo Construcción (Manual) → Ejecutar flujo de trabajo para desencadenarlo.

2. Lanzamiento en Etiqueta

Construye y envía ambas plataformas en paralelo cada vez que empujes una etiqueta de versión como v1.4.0Esto es la configuración de producción más común — git tag v1.4.0 && git push --tags se convierte en tu comando de lanzamiento.

name: Capgo Build (Release)

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ${{ matrix.platform }}

      - name: Build ${{ matrix.platform }}
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          # iOS
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          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 }}
          # Android
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform ${{ matrix.platform }} \
            --build-mode release

La matriz ejecuta iOS y Android en paralelo en ejecutores separados. Configurar fail-fast: false significa que un fallo en la construcción de iOS no cancelará la construcción en curso de Android (y viceversa) — útil cuando una plataforma tiene un problema de firma temporal.

3. Compilar con depuración al enviar a Main

Captura las regresiones de compilación nativa temprano produciendo una compilación de Android de depuración en cada envío a mainBarato de ejecutar, rápido feedback y puedes saltar la subida a la tienda Play para mantenerlo como un testeo de humo.

name: Capgo Build (Main)

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'android/**'
      - 'ios/**'
      - 'package.json'
      - 'capacitor.config.*'

jobs:
  smoke-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync android

      - name: Smoke build (Android debug)
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
        run: |
          bunx @capgo/cli@latest build request com.example.app \
            --platform android \
            --build-mode debug \
            --no-playstore-upload \
            --output-upload

El filtro garantiza que el flujo de trabajo no se ejecute en cambios de solo documentos. paths omite la presentación en la tienda Play (no --no-playstore-upload necesario), y PLAY_CONFIG_JSON produce una URL de descarga para el APK resultante para que pueda instalarlo en un dispositivo de prueba. --output-upload Patrones Comunes

Sección titulada “Patrones Comunes”

Sección titulada “Saltar la carga en la tienda Play / subir a TestFlight”

; para iOS, compilar en modo ad-hoc con --no-playstore-upload(que nunca envía a la Tienda de Aplicaciones). Combine ambos con --ios-distribution ad_hoc patrones comunes --output-upload para obtener una URL de descarga temporal para el binario.

Lee la URL de salida de compilación y el código QR code

Persistir --output-record <path> para persistir la URL del artefacto de compilación y el código QR code en disco cuando la compilación tenga éxito, y luego leerlo de nuevo en los pasos posteriores sin build last-outputsin rastreo de logs, sin regex.

- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform android --build-mode debug \
      --output-upload --output-retention 1d \
      --output-record /tmp/build.json

- name: Comment on PR with build URL
  env:
    GH_TOKEN: ${{ github.token }}
  run: |
    URL=$(bunx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl)
    if [ -n "$URL" ]; then
      gh pr comment ${{ github.event.pull_request.number }} \
        --body "Debug build ready: $URL"
    fi

--output-record /tmp/build.json escribe un registro JSON (con jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) y un código QR code en PNG junto a /tmp/build.json.qr.png. build last-output lee de nuevo:

--field outputUrl imprime solo la URL de descarga (terminada con nueva línea; seguro para URL=$(...)).
--field qrCodePngPath imprime el camino del PNG para que puedas subirlo como una adjunta de PR.
--qr imprime el código ASCII QR — colócalo dentro de una code de Markdown en el comentario de PR para una escaneabilidad en línea.

No saltar el aumento del número de build

Por defecto, cada build de liberación incrementa el número de build. Para pincharlo a un valor que controlas (por ejemplo, la etiqueta Git), pasa --skip-build-number-bump:

- name: Set version from tag
  run: |
    VERSION="${GITHUB_REF#refs/tags/v}"
    # Update package.json or your version source here
    bun pm version "$VERSION" --no-git-tag-version

- name: Build
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    # ...credentials...
  run: |
    bunx @capgo/cli@latest build request com.example.app \
      --platform ios --build-mode release \
      --skip-build-number-bump

Dependencias en caché

bun install ya es lo suficientemente rápido que una caché de dependencias JS rara vez vale la pena, pero las dependencias nativas de Capacitor (CocoaPods, Gradle) merecen ser cacheadas para proyectos más grandes:

- uses: actions/cache@v4
  with:
    path: |
      ~/.bun/install/cache
      ios/App/Pods
      android/.gradle
    key: ${{ runner.os }}-capgo-${{ hashFiles('**/bun.lock', '**/Podfile.lock') }}

Solución de problemas

Síntoma	Causa probable
`CAPGO_TOKEN is not set`	No se agregó la clave secreta, o el trabajo no tiene acceso a ella (revisa protecciones de entorno/ramas)
Errores de credenciales de iOS / Android faltantes	`gh secret set -f` No se ejecutó, o se ejecutó contra un repositorio diferente. Verifica con `gh secret list`
`cap sync` Falló en CI pero funciona localmente	Un plugin nativo no está en `package.json`, o te olvidaste de él `bun install` antes `cap sync`
El build tiene éxito pero no aparece la aplicación en App Store Connect	ID de equipo incorrecto, o el registro de la aplicación no existe aún en App Store Connect. Verifique localmente con `bunx @capgo/cli@latest build credentials manage`
El build se queda colgado después de ‘Subiendo proyecto’	El archivo de proyecto es inusualmente grande — compruebe que `node_modules` no está siendo subido (no debería hacerlo por defecto)
`Provisioning profile doesn't match bundle ID`	El mapa de provisión apunta a un ID de paquete diferente al que Xcode está firmado. Re-ejecute `build init` para refrescar el perfil, luego re-export con `build credentials manage`
Los credenciales cambiaron localmente pero CI sigue fallando	No olvide re-exportar y re-pushear: `bunx @capgo/cli@latest build credentials manage` → `gh secret set -f .env.capgo.<appId>`
El administrador se niega a escribir el archivo combinado	Las claves de configuración compartidas difieren entre plataformas — el administrador advierte y pregunta por confirmación. Confirme para sobreescribir uno, o re-exporte por plataforma con `--platform ios` / `--platform android`
`build last-output` imprime una URL vacía	La compilación no pasó `--output-upload`, o falló antes de producir un artefacto. `outputUrl` será `null` en el registro. Rama en `[ -n "$URL" ]` antes de usarla
`build last-output` errores con `Unsupported record schemaVersion`	El ejecutor está en una versión más antigua de CLI que la que escribió el registro. Pin ambos productor y lector a la misma versión explícita (por ejemplo `bunx @capgo/cli@7.104.0 …` en ambos lados) en lugar de `@latest`, que flota y puede desplazarse entre tareas

Para fallas de compilación específicas de plataforma, consulte la Guía de solución de problemas.

Pasos siguientes

Configuración de credenciales Referencia completa para preparar credenciales de iOS y Android como secretos base64.

Compilación de iOS Guía más profunda sobre certificados, perfiles y presentación en la Tienda de Mac.

Compilación de Android Configuración de keystore, cuentas de servicio de Tienda de Google y manejo de sabores.

Opciones de configuración Todos los flags y variables de entorno CLI para afinar tus compilaciones.