GitHub Acciones

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

Automatice sus compilaciones de iOS y Android directamente desde su 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 almacenar — sin que nadie en el equipo necesite un Mac, Xcode o Android Studio instalado.

Lo que 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 desencadenar 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 GitHub secretos de repositorio, escalonados a tu repositorio y visibles solo para el ejecutor de flujo. Fácil de rotar, fácil de auditar.

Compilaciones paralelas

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úrese de tener:

Una cuenta de Capgo con una suscripción activa y una Capgo API clave
Su aplicación registrada en Capgo (bunx @capgo/cli@latest app add si no está registrado)
Las credenciales de construcción configuradas localmente con bunx @capgo/cli@latest build init — consulte Gestión de credenciales para el recorrido 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 su primera construcción
Los 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. .env Unido a gh secret set -f, esto convierte todo el setup de CI/CD en tres comandos — sin codificación base64 manual, sin manipulación de JSON, sin copia y pegado de secretos por secreto.

Agrega tu Capgo API como un secreto de repositorio

The API clave no forma parte del almacén de credenciales por aplicación, así que agrega manualmente:
Ventana de terminal
```
gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"
```
Genera la clave en el Capgo panel de control con permisos de subida o superior. Exporta tus credenciales a un
archivo .env Ejecuta el administrador de credenciales interactivo:

Ventana de terminal
__CAPGO_KEEP_0__
```
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 ambos sistemas se almacenan en el mismo archivo bajo # === IOS === y # === ANDROID === títulos de sección. Los nombres de las variables de entorno de iOS y Android son disjuntos, por lo que combinarlos es conflict-free.

Pasar --platform ios (o --platform android) para limitar 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 interruptores 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 explícita 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.
Empuja 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 cada KEY=value line:
Ventana de terminal
```
gh secret set -f .env.capgo.com.example.app
```
Eso es todo — ahora todos los secretos que necesita su flujo de trabajo 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`
(añadidos 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 una construcción desde el pestaña Acciones de __CAPGO_KEEP_0__ con un menú desplegable de plataforma. Útil para pruebas de ad-hoc o iniciar una versión en demanda. .GitHub/trabajos/__CAPGO_KEEP_1__-construye-manual.yml

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

con tu ID de aplicación. Una vez comprometido, ve a com.example.app Acciones → __CAPGO_KEEP_0__ Construye (Manual) → Ejecutar flujo de trabajo Actions → Capgo Build (Manual) → Run workflow To 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.0Este 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. Establecer 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. Compilación de depuración al enviar a Main

Captura las regresiones de compilación nativa temprano produciendo una compilación de depuración Android en cada envío a mainBarato de ejecutar, rápido feedback y puedes saltar la carga en la Tienda de Juegos para mantenerlo puramente como una prueba 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 paths filtro asegura que el flujo de trabajo no se ejecute en cambios de solo documentación. --no-playstore-upload skips la presentación en la Tienda de Google Play (no PLAY_CONFIG_JSON necesario), y --output-upload produce una URL de descarga para el archivo APK resultante para que puedas instalarlo en un dispositivo de prueba.

Patrones Comunes

Saltar la carga en la Tienda de Google Play / Carga de Prueba de Apple:

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

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

Pasa --output-record <path> para persistir el enlace de la unidad de compilación y el código QR code en disco cuando la compilación tenga éxito, y luego leerlo de nuevo en pasos posteriores sin escarbar en los registros ni utilizar regex. build last-outputCopiar a portapapeles

- 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 ) y un código QR __CAPGO_KEEP_0__ en PNG junto a jobId, status, outputUrl, qrCodeAscii, qrCodePngPath, finishedAt) and a PNG QR code alongside at /tmp/build.json.qr.png. build last-output imprime solo el enlace de descarga (terminado con nueva línea; seguro para

--field outputUrl imprime el camino del PNG para que puedas subirlo como una adjunta de PR. URL=$(...)).
--field qrCodePngPath imprime el código QR ASCII renderizado — colócalo dentro de una cerca de Markdown __CAPGO_KEEP_0__ en el comentario de PR para una escaneabilidad en línea.
--qr prints the rendered ASCII QR — drop it inside a Markdown code fence on the PR comment for inline scannability.

Saltar el aumento del número de compilación

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

bun install ya es lo suficientemente rápido que una caché de dependencias JS raramente es rentable, pero Capacitor’s dependencias nativas (CocoaPods, Gradle) merecen 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') }}

Resolución de problemas

Síntoma	Causa probable
`CAPGO_TOKEN is not set`	No se ha agregado un secreto, o el trabajo no tiene acceso a él (verifique 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	Un plugin nativo no está en `package.json`, o se olvidó `bun install` antes de `cap sync`
El compilado tiene éxito pero no aparece la aplicación en App Store Connect	El ID de equipo es 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`
La compilación se atasca después de ‘Subiendo proyecto’	El archivo de proyecto es inusualmente grande — compruebe 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 para firmar. Vuelva a ejecutar `build init` para refrescar el perfil, luego vuelva a exportar con `build credentials manage`
Los credenciales cambiaron localmente pero CI sigue fallando	No se olvide de volver a exportar y volver a enviar: `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 solicita confirmación. Confirme para sobreescribir uno, o vuelva a exportar por plataforma con `--platform ios` / `--platform android`
`build last-output` imprime una URL vacía	No se pasó la compilación `--output-upload`o falló antes de producir un artefacto. `outputUrl` será `null` en el registro. Selecciona la rama en `[ -n "$URL" ]` antes de utilizarlo
`build last-output` con errores `Unsupported record schemaVersion`	El ejecutor está en una versión más antigua de CLI que la que escribió el registro. Asigna la misma versión explícita tanto al productor como al lector (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 el Guía de solución de problemas.

Pasos siguientes

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

Edición de iOS Guía más profunda sobre certificados, perfiles y envío a la Tienda de Mac.

Edición de Android Configuración de keystore, cuentas de servicio de Tienda de Juegos y manejo de sabores.

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