GitHub Acciones

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

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 el almacenamiento — sin que nadie en el equipo necesite un Mac, Xcode o Android Studio instalado.

¿Qué obtiene?

Releases sin intervención

Etique una versión en Git y sus 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 provisión, sin certificados de firma compartidos flotando en laptops.

Secretos de ámbito

Las credenciales viven en los secretos de repositorio de GitHub, limitados 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 típico lanzamiento termina 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 un Capgo API clave
Tu aplicación registrada en Capgo (bunx @capgo/cli@latest app add si no)
Configura credenciales de construcción configuradas localmente con bunx @capgo/cli@latest build init — vea Administración de credenciales para la guía paso a paso del asistente
Una construcción local exitosa (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debug) — la CI no es el lugar para depurar tu primera construcció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. .env Combinado con gh secret set -f, esto convierte todo el conjunto de CI/CD en tres comandos — sin codificación base64 manual, sin manipulación de JSON, sin copia y pegado de secretos por secretos.

Agrega tu Capgo API como un secreto de repositorio

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

Ejecutar el administrador de credenciales interactivo:
ventana de terminal
```
bunx @capgo/cli@latest build credentials manage --appId com.example.app
```
En la IU de texto, seleccione Exportar a .env. El CLI escribe .env.capgo.<appId> a su directorio actual con permisos 0600 (solo leesible por el propietario) — por ejemplo, .env.capgo.com.example.app. Cuando 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 variables de entorno de iOS y Android son disjuntos, por lo que combinarlos es conflict-free.

Pass --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.

A 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 haberse alejado. Si el administrador encuentra una diferencia, imprime las claves en conflicto, solicita una 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.
Push el .env archivo a los secretos de GitHub de Acciones

La 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
```
¡Listo! — cada secreto que necesita su flujo de trabajo ahora está 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 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 las compilaciones.

¿Qué termina 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`
(agregado 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

Permite que cualquier persona con acceso de escritura dispare un build desde el Acciones pestaña en GitHub con un menú desplegable de plataforma. Útil para pruebas ad-hoc o para iniciar un lanzamiento a petición.

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 por su ID de aplicación. Una vez confirmado, vaya a Acciones → Capgo Build (Manual) → Ejecutar flujo de trabajo para desencadenarlo.

2. Lanzamiento en Etiqueta

Compila y envía ambas plataformas en paralelo cada vez que empuje 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 compilación de iOS no cancelará la compilación en curso de Android (y viceversa) — útil cuando una plataforma tiene un problema de firma temporal.

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

Captura las regresiones de construcción nativa temprano produciendo un build de Android en modo depuración en cada envío a main. Barato de ejecutar, rápido feedback, y puedes saltarte la subida a Play Store 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

La paths filtro asegura que el flujo de trabajo no se ejecute en cambios solo de documentación. --no-playstore-upload salta la presentación en Play Store (no PLAY_CONFIG_JSON necesario), y --output-upload produce una URL de descarga para el resultado APK para que puedas instalarlo en un dispositivo de prueba.

Patrones Comunes

Saltar la carga en la Tienda de Juegos / Prueba de vuelo

Para versiones de prueba, omitir la presentación en la tienda: Android utiliza --no-playstore-upload; para iOS, construye 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 archivo binario.

Presentar la versión de la tienda para revisión

Por defecto, las versiones de liberación cargan el artefacto firmado y dejan la acción final de la tienda bajo tu control. Para las versiones de CI que deben moverse directamente en el flujo de revisión de la tienda, agrega --submit-to-store-review.

Android utiliza tu PLAY_CONFIG_JSON servicio de cuenta. Sin una pista explícita, --submit-to-store-review se ajusta a la pista de producción con release_status: completed. Preferir indicar la pista en el sitio de llamada con --android-track (o PLAY_STORE_TRACK), y sobreescribir el estado con --android-release-status / PLAY_STORE_RELEASE_STATUS cuando sea necesario:

- 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 recorrido API de App Store Connect y envía la versión procesada de TestFlight a revisión en la Tienda de Mac App. app_store Requiere --ios-testflight-groups es opcional para la distribución de beta externa y no se requiere para la revisión en la Tienda de Mac App:

- 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

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

Éxito --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 las siguientes etapas con build last-outputNo 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, finishedAty un código QR code PNG junto a /tmp/build.json.qr.png. build last-output lo lee de nuevo:

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

No incrementar el número de construcción

Por defecto, cada construcción de lanzamiento incrementa el número de construcció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 JS raramente es rentable, 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') }}

Resolución de problemas

Síntoma	Causa probable
`CAPGO_TOKEN is not set`	No se ha agregado la clave secreta, 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. Verificar 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`
La compilación 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. Verifica 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 — 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`
Los credenciales cambiaron localmente pero CI sigue fallando	No te olvides 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, 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. Fije tanto la versión del productor como la del lector en 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 el Guía de solución de problemas.

Pasos siguientes

Auto OTA o Nativo Rama CI entre la carga de actualizaciones en vivo y Capgo Compilación.

Activar desde la interfaz de CI Ejecutar Capgo Compilación desde la pestaña Acciones a demanda.

Webhooks de compilación Iniciar el mismo flujo de trabajo desde una llamada HTTP de panel de administración.

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

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