GitHub Acciones

Copie 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 empuje, etiqueta o disparo manual puede producir aplicaciones firmadas y listas para el almacenamiento — sin que nadie en el equipo necesite un Mac, Xcode o Android Studio instalado.

¿Qué obtienes?

Releases sin intervención

Etiqueta una versión en Git y tus binarios firmados de iOS y Android se envían automáticamente a TestFlight y Play Store.

No configuración local

Colaboradores en Windows o Linux pueden desencadenar compilaciones de iOS. Sin Xcode, sin problemas de configuración, sin certificados de firma compartidos flotando en laptops.

Secretos escalonados

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

Construcciones paralelas

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

Prerequisites

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

Una cuenta de Capgo con una suscripción activa y un Capgo API clave
Tu aplicación registrada en Capgo (bunx @capgo/cli@latest app add si no)
Build credentials configured locally with bunx @capgo/cli@latest build init — vea Gestión de credenciales para la guía del mago
Una construcción local exitosa (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debugno es el lugar de la CI para depurar tu primera construcción
La GitHub CLI (gh) instalado y autenticado (gh auth login)

Configuración

La Capgo CLI puede exportar sus credenciales locales como un archivo listo para usar .env archivo. Combinado con gh secret set -f, esto convierte toda la configuración CI/CD 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

The API key isn’t part of the per-app credential store, so add it once manually:
Ventana de terminal
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Generar la clave en la Capgo consola con subir o permisos superiores.
Exporta tus credenciales a un .env archivo

Run the interactive credentials manager:
ventana de terminal
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
En la IU de texto, selecciona Exportar a .envEl CLI escribe .env.capgo.<appId> en tu directorio actual con permisos 0600 (solo lectura del propietario) — por ejemplo, .env.capgo.com.example.app. Cuando tanto iOS como Android estén configurados, los secretos de ambas plataformas se almacenan en el mismo archivo bajo # === IOS === y # === ANDROID === section headers. iOS and Android env-var names are disjoint, so combining them is conflict-free.

Pass --platform ios (o --platform android) para limitar el administrador a una plataforma. La exportación produce luego 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 conjunto de interruptores de configuración (BUILD_OUTPUT_UPLOAD_ENABLED, BUILD_OUTPUT_RETENTION_SECONDS, SKIP_BUILD_NUMBER_BUMP, CAPGO_IOS_DISTRIBUTIONSe puede almacenar cada plataforma por separado y puede haberse alejado. Si el administrador encuentra desfase, imprime las claves en conflicto, solicita confirmación explicita antes de escribir, y inserta la lista de conflictos como comentario en la parte superior del archivo. Re-export con --platform Si necesita preservar valores por plataforma.
Pulsa el .env archivo a GitHub Secretos de Acciones

La gh secret set -f comando lee un archivo dotenv y crea un secreto de repositorio por cada KEY=value line:
copiar a portapapeles
```
gh secret set -f .env.capgo.com.example.app
```
That’s it — every secret your workflow needs is now in GitHub. Verify with gh secret list.
Si necesita preservar valores por plataforma.
Contiene material de firma de texto plano. Una vez que lo hayas enviado a GitHub:
Ventana de terminal
echo '.env.capgo.*' >> .gitignore rm .env.capgo.*
Re-export en cualquier momento que necesite 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 Agrega a tu repositorio. Selecciona uno de los tres patrones de disparo a continuación según cómo deseas desencadenar los builds.

¿Qué acaba en tus secretos

¿Qué acaba en tus secretos? gh secret set -f Crearán estos secretos de repositorio (su archivo YAML de flujo de trabajo los referencia con estos nombres exactos):

Por referencia,	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, construye los activos web, sincroniza con nativo, luego llama Capgo Construye con credenciales pasadas como variables de entorno.

1. Disparo manual

Lets anyone with write access fire a build from the Acciones pestaña en GitHub con un menú desplegable de plataforma. Útil para pruebas ad-hoc o para iniciar una versión en 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 with your app ID. Once committed, go to Actions → Capgo Build (Manual) → Run workflow para desencadenarlo.

2. Lanzamiento en Etiqueta

Compila y envía ambas plataformas en paralelo cada vez que empujes una etiqueta de versión como v1.4.0Esto es el conjunto 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. Configurando fail-fast: false No cancela la compilación en curso de Android si falla la compilación de iOS (y viceversa) — útil cuando un plataforma tiene un problema de firma temporal.

3. Compilar en modo depuración al enviar a Main

Catches native build regressions early by producing a debug Android build on every push to main. Cheap to run, fast feedback, and you can skip Play Store upload to keep it purely a smoke test.

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

La paths filter ensures the workflow doesn’t run on doc-only changes. --no-playstore-upload omite la presentación en Google Play Store (no PLAY_CONFIG_JSON needed), y --output-upload genera una URL de descarga para el APK resultante para que puedas instalarlo en un dispositivo de prueba.

Patrones Comunes

Título de la sección ‘Patrones Comunes’

Para pruebas, omitir la presentación en la tienda: Android utiliza --no-playstore-upload; para iOS, compilar en modo ad-hoc con --ios-distribution ad_hoc (que nunca envía a la Tienda de Aplicaciones). Combine ambos con --output-upload obtener una URL de descarga temporal para el binario.

Envía la versión de la tienda para revisión

Por defecto, las compilaciones de liberación suben el artefacto firmado y dejan la acción final de la tienda bajo su control. Para las liberaciones de CI que deben moverse directamente al flujo de revisión de la tienda, agregue --submit-to-store-review.

Android utiliza su PLAY_CONFIG_JSON servicio de cuenta. Sin una pista explícita, --submit-to-store-review se establece en la pista de producción con release_status: completed. Prefer indicar el seguimiento en el sitio de llamada con --android-track (o PLAY_STORE_TRACKCuando sea necesario: --android-release-status / PLAY_STORE_RELEASE_STATUS Copiar al portapapeles

- name: Submit Android release for review
  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 }}
    PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform android \
      --build-mode release \
      --submit-to-store-review \
      --android-track production \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}"

Para un lanzamiento interno completado en lugar de producción:

- name: Submit Android internal release
  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 }}
    PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform android \
      --build-mode release \
      --submit-to-store-review \
      --android-track internal \
      --store-release-name "${GITHUB_REF_NAME}"

iOS utiliza la clave de ruta API de App Store Connect y envía la build procesada de TestFlight a revisión en App Store. Requiere app_store distribution; --ios-testflight-groups is optional for external beta distribution and is not required for App Store review:

- name: Submit iOS build to App Store review
  env:
    CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
    BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
    P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
    CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
    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 }}
  run: |
    npx @capgo/cli@latest build request com.example.app \
      --platform ios \
      --build-mode release \
      --ios-distribution app_store \
      --submit-to-store-review \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}" \
      --no-ios-automatic-release

Read the build output URL and QR code

Éxito --output-record <path> persistir la URL del artefacto de construcción y el código QR code en disco cuando el build tenga éxito, y leerlo de nuevo en pasos posteriores con build last-outputSin rastreo de registros, 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 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 la ruta del PNG para que puedas subirlo como una anexión de PR.
--qr imprime la codificación ASCII QR — colócala dentro de una cerca de Markdown code en el comentario de PR para una mayor escaneabilidad.

Saltar el aumento de número de compilación

Por defecto, cada compilación de lanzamiento incrementa el número de compilación. Para fijarlo en 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 de caché

bun install ya es lo suficientemente rápido que una caché de dependencias de JS rara vez vale la pena, pero Capacitor’s dependencias nativas (CocoaPods, Gradle) son dignas de cachear 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') }}

Troubleshooting

Symptom	Causa probable
`CAPGO_TOKEN is not set`	La clave secreta no se ha agregado, o el trabajo no tiene acceso a ella (ver protecciones de entorno/rama)
Errores de credenciales de iOS / Android faltantes	`gh secret set -f` No se ejecutó, o se ejecutó contra un repositorio diferente. Verifique con `gh secret list`
`cap sync` Falla en CI pero funciona localmente	A un plugin nativo no está disponible `package.json`o se te olvidó `bun install` antes `cap sync`
Build succeeds but no app appears in 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`
Build hangs after “Uploading project”	El archivo de proyecto es inusualmente grande — comprueba que `node_modules` no se está subiendo (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 utilizado por Xcode. Vuelve a ejecutar `build init` para refrescar el perfil, luego vuelve a exportar con `build credentials manage`
Credenciales cambiadas localmente pero la CI sigue fallando	No te olvides de re-exportar y re-enviar: `bunx @capgo/cli@latest build credentials manage` → `gh secret set -f .env.capgo.<appId>`
Manager refuses to write the combined file	Las claves de configuración compartidas difieren entre plataformas — el administrador advierte y solicita confirmación. Confirme para sobreescribir, 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 utilizarlo
`build last-output` con errores con `Unsupported record schemaVersion`	El ejecutor está en una versión más antigua de CLI que la que escribió el registro. Pinche tanto al productor como al 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

For platform-specific build failures, see the Guía de solución de problemas.

Pasos siguientes

Auto OTA o Nativo Branch CI entre live update subir y Capgo construir.

Disparar desde la interfaz de CI Ejecutar Capgo construir desde la pestaña Acciones a demanda.

Webhooks de construcción Start the same workflow from an admin dashboard HTTP call.

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

Opciones de configuración Todas las banderas y variables de entorno CLI para afinar tus compilaciones.