GitHub Acciones

Automatiza tus compilaciones de iOS y Android directamente desde tu GitHub repositorio. 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

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

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 flotando en laptops.

Secretos escalares

Las credenciales viven en secretos de repositorio __CAPGO_KEEP_0__, escalables a tu repositorio y visibles solo para el ejecutor de flujo de trabajo. Fáciles de rotar, fáciles de auditar.

Credentials live in GitHub repository secrets, scoped to your repo and visible only to the workflow runner. Easy to rotate, easy to audit.

Compila iOS y Android al mismo tiempo con un trabajo de matriz. Una típica versión se completa en menos de 10 minutos.

Requisitos previos

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
• The GitHub CLI (gh) instalado y autenticado (gh auth login)

Nota

El flujo a continuación asume que los credenciales ya existen en tu almacén de credenciales local (desde build init). Si aún no los has configurado, hazlo primero — el asistente maneja la creación de certificados, perfiles de configuración, keystore y cuentas de servicio de Play Store de manera interactiva.

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 setup de CI/CD en tres comandos — sin codificación base64 manual, sin manipulación de JSON, sin copiar y pegar secretos por secreto.

1. Agregue su clave Capgo API como secreto de repositorio

   La clave API no forma parte del almacén de credenciales por aplicación, así que agregue una sola vez manualmente:

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

   Generar la clave en el Capgo dashboard con permisos de subida o superior. Exporte sus credenciales a un

2. archivo .env Ejecute el administrador de credenciales interactivo:

   with

   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 de 0600 solo 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 === los encabezados de sección. Los nombres de las variables de entorno de iOS y Android son disjuntos, por lo que combinarlos es conflictivo.

   ¿Necesita un archivo por plataforma?

   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.

   Claves de configuración compartidas

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

3. Pushe el .env archivo a GitHub Secrets de Acciones de Cloudflare

   El gh secret set -f La orden lee un archivo dotenv y crea un secreto de repositorio por línea: KEY=value Terminal

   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.

   Contiene material de firma de texto plano. Una vez que lo haya empujado a __CAPGO_KEEP_0__:

   It contains plaintext signing material. Once you’ve pushed it to GitHub:

   echo '.env.capgo.*' >> .gitignore
   rm .env.capgo.*

   Crear el archivo de flujo de trabajo

4. command reads a dotenv file and creates one repository secret per line:

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

1. Disparo manual

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

.github/trabajos/capgo-build-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 }}

Sustituir com.example.app con tu ID de aplicación. Una vez comprometido, ve a Acciones → Capgo Construir (Manual) → Ejecutar flujo de trabajo para desencadenarlo.

2. Lanzamiento en Etiqueta

Construye y envía ambas plataformas en paralelo cada vez que se envía una etiqueta de versión como v1.4.0. Este 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.

github/workflows/capgo-build-release.yml

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.

Nota

Sobre el número de versión: Capgo El número de compilación se incrementa automáticamente con cada compilación de lanzamiento. Si prefieres mantenerlo en la etiqueta, consulta Saltar el incremento del número de compilación a continuación.

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

Captura las regresiones de compilación nativa temprano produciendo una compilación de Android en modo depuración con cada envío a mainBarato de ejecutar, rápido feedback y puedes saltarte la carga en la Tienda de Juegos para mantenerlo como un testeo de humo.

github/trabajos/capgo-compilar-main.yml

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 filter garantiza que el flujo de trabajo no se ejecute en cambios de solo documentación. --no-playstore-upload omite la presentación en la tienda Play (no PLAY_CONFIG_JSON necesario), y --output-upload produce una URL de descarga para el APK resultante para que puedas instalarlo en un dispositivo de prueba.

Patrones Comunes

Saltar la carga en la tienda Play / subir a TestFlight

Para compilaciones de prueba, 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 cualquiera con --output-upload para obtener una URL de descarga con límite de tiempo para el binario.

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

Por defecto, los builds de liberación suben el artefacto firmado y dejan la acción final de la tienda bajo tu control. Para las liberaciones de CI que deberían moverse directamente al flujo de revisión de la tienda, agrega --submit-to-store-review.

Android utiliza tu PLAY_CONFIG_JSON cuenta de servicio y envía la liberación de Google Play en lugar de dejarla inactiva. Agrega --store-release-name, --store-release-notes, y entradas opcionales cuando desees que la liberación de Play lleve el mismo etiqueta y cambios locales como CI: --store-release-notes-locale 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 \
      --store-release-name "${GITHUB_REF_NAME}" \
      --store-release-notes "Release ${GITHUB_REF_NAME}" \
      --store-release-notes-locale "en-US=Release ${GITHUB_REF_NAME}"

iOS uses the App Store Connect API key path and submits the processed TestFlight build to App Store review. It requires app_store es opcional para la distribución beta externa y no es necesario para la revisión de App Store: --ios-testflight-groups Copiar al portapapeles

- 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

Cuidado

Esta ruta solo envía el artefacto de compilación. Los metadatos de la lista de almacenamiento, los grupos de pruebas, los detalles de contacto de revisión, las respuestas de cumplimiento y las opciones de lanzamiento todavía deben estar disponibles en App Store Connect o Google Play Console antes de que CI lo ejecute.

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

Éxito --output-record <path> para persistir la URL y el código QR de la salida de compilación code en disco cuando la compilación tenga éxito, y luego leerla de nuevo en pasos posteriores sin build last-outputNo rastreo de registros, no 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 PNG code junto a /tmp/build.json.qr.png. build last-output lee de nuevo:

• --field outputUrl imprime solo la URL de descarga (terminada por nueva línea; segura para URL=$(...)).
• --field qrCodePngPath imprime el camino de la imagen PNG para que puedas subirla como una anexa 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 la escaneabilidad en línea.

Nota

El registro solo se escribe en una compilación exitosa. No soportado schemaVersion y desconocido --field los valores salen con código de salida no cero, por lo que un CLI estancado en el ejecutor falla ruidosamente en lugar de emitir silenciosamente una URL vacía.

No 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 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	La clave secreta no se agregó, 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	No se encuentra un plugin nativo package.jsono se olvidó 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 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. Re-ejecute build init para refrescar el perfil, luego re-export con build credentials manage
Se cambiaron las credenciales localmente pero el CI sigue fallando	No se olvide de re-exportar y re-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 pregunta por 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 tuvo éxito --output-uploado falló antes de producir un artefacto. outputUrl será null en el registro. Rama en [ -n "$URL" ] antes de usarlo
build last-output falla 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

Para fallos de construcción específicos de plataforma, consulte el 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.

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

Construcción de Android Configuración de keystore, cuentas de servicio de Tienda de aplicaciones y manejo de sabores.

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