GitHub Acciones

Automatiza tus compilaciones de iOS y Android directamente desde tu repositorio GitHub. Con un archivo de flujo de trabajo único 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 de 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.

Requisitos previos

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)
• Las credenciales de construcción configuradas localmente con bunx @capgo/cli@latest build init — vea Administración de credenciales para la guía del asistente
• Una construcción local exitosa (bunx @capgo/cli@latest build request com.example.app --platform android --build-mode debugno es el lugar de CI para depurar tu primera construcción
• La GitHub CLI (gh) instalado y autenticado (gh auth login)

Nota

El flujo a continuación asume que ya existen credenciales en tu almacén de credenciales local (desde build initSi aún no las 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

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.

1. Agregue su Capgo API clave como un secreto de repositorio

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

   gh secret set CAPGO_TOKEN --body "your_capgo_api_key_here"

   Generar la clave en la Capgo consola con subir o permisos superiores.

2. Exporta tus credenciales a un .env archivo

   Ejecuta el administrador de credenciales interactivo:

   bunx @capgo/cli@latest build credentials manage --appId com.example.app

   En la IU, seleccione En la IU, seleccionaEl CLI escribe .env.capgo.<appId> copiar a tu directorio actual con modo 0600 (único para el 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 === títulos de sección. Los nombres de variables de entorno de iOS y Android son disjuntos, por lo que combinarlos es conflictivo.

   ¿Necesita un archivo por plataforma?

   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.iosescopar el administrador a una plataforma. La exportación produce entonces un archivo por plataforma como

   Configuración compartida

   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 desplazamiento, 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 necesitas preservar valores por plataforma.

3. 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 línea:

   gh secret set -f .env.capgo.com.example.app

   Eso es todo — ahora todas las claves de tu flujo de trabajo están en GitHub. Verifica con gh secret list.

   No comites el archivo .env

   Contiene material de firma de texto plano. Una vez que lo hayas empujado a GitHub:

   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.

4. 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 desees desencadenar los builds.

¿Qué termina en tus secretos

Para referencia gh secret set -f Crearán estos secretos de repositorio (sus archivos YAML de flujo de trabajo los refieren por estos nombres exactos):

Para 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
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 a Capgo Construye con credenciales pasadas como variables de entorno.

1. Disparador manual

Puede cualquier persona con acceso de escritura disparar un build desde el Acciones pestaña en GitHub con un menú desplegable de plataforma. Útil para pruebas ad-hoc o iniciar una versión a 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 }}

Replace com.example.app with your app ID. Once committed, go to Acciones → Capgo Construir (Manual) → Ejecutar flujo de trabajo Desencadenarlo.

para desencadenarlo.

Builds and ships both platforms in parallel whenever you push a version tag like v1.4.0Esta 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.

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

Nota

Sobre el número de versión: Capgo Incrementa automáticamente el número de compilación con cada lanzamiento de compilación. Si prefieres fijarlo a la etiqueta, consulta Saltar el aumento del número de compilación abajo.

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

Captura las regresiones de compilación nativa temprano produciendo una compilación de depuración de Android en cada empujón a mainBarato de ejecutar, rápido feedback y puedes saltarte la subida a Play Store para mantenerlo puramente como prueba de humo.

github/trabajos/capgo-build-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 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 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 subida a Google Play Store / TestFlight

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 para obtener una URL de descarga temporal para el archivo binario.

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

Por defecto, las compilaciones de liberación cargan 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_TRACK, y sobreescribir el estado cuando sea necesario: --android-release-status / PLAY_STORE_RELEASE_STATUS Copiar a 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 versión procesada de TestFlight a revisión en la App Store. Requiere app_store distribution; --ios-testflight-groups es opcional para la distribución beta externa y no es necesario para la revisión de la tienda de aplicaciones.

- 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 de salida de compilación y el código 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 nuevamente en pasos posteriores con build last-outputNo hay rastreo de registros, no hay 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 PNG 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; seguro para URL=$(...)).
• --field qrCodePngPath imprime el camino de PNG para que puedas subirlo como una anexión de PR.
• --qr imprime la código ASCII QR — colócalo dentro de una code de Markdown en el comentario de PR para una escaneabilidad en línea.

Nota

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

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é

Nota

Esta sección trata sobre GitHub Acciones almacenar en el ejecutor de CI (local Pods/ y .gradle Capgo también mantiene un cache de construcción en la nube por aplicación en el ejecutor de construcción (habilitado por defecto; omitir cache_key para el cache general compartido). Pase --cache-key para particionar RC y producción, o --no-cache para deshabilitar, restaurar y guardar. Consulte Troubleshooting: wrong cache restore.

bun install ya es lo suficientemente rápido que una caché de dependencias de JS rara vez es rentable, 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

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. Verifique con gh secret list
cap sync falla en CI pero funciona localmente	A un plugin nativo no está disponible package.jsono 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 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 el 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>
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 usarlo
build last-output con errores de Unsupported record schemaVersion	El ejecutor está en una versión más antigua de CLI que la que escribió el registro. Pinche tanto el productor como el 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 errores de compilación específicos de plataforma, consulte el Guía de depuración.

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 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 banderas y variables de entorno CLI para afinar tus compilaciones.