GitHub Acciones

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.

¿Qué obtienes?

Lanzamientos sin intervención

Etiqueta un lanzamiento en Git y sus binarios de iOS y Android firmados se envían automáticamente a TestFlight y Play Store.

Sin 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 escalables

Las credenciales viven en los secretos de repositorio de GitHub, escopados a tu repositorio y visibles solo para el ejecutor de flujo.

Construcción en paralelo

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

Nota

El flujo a continuación asume que las credenciales ya existen en el almacén de credenciales local (desde build init). Si 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

El Capgo CLI puede exportar sus credenciales locales como un archivo listo para usar. .env Combinado con gh secret set -festo, 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 subida permisos o superior.

2. Exporte sus credenciales a un .env archivo

   Ejecute el administrador de credenciales interactivo:

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

   En la IU, seleccione Exportar a .env. El CLI escribe .env.capgo.<appId> en su directorio actual con permisos 0600 (solo lectura del propietario) — por ejemplo, .env.capgo.com.example.app. Cuando tanto iOS como Android estén configurados, las claves de ambas plataformas se almacenan en el mismo archivo bajo # === IOS === y # === ANDROID === Encabezados 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?

   Aceptar --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 If necesitas preservar valores por plataforma.

3. Envía 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 KEY=value línea:

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

   Listo — todos los secretos que necesita tu flujo de trabajo ahora están en GitHub. Verifica con gh secret list.

   No cometas el archivo .env

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

   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.

4. Crear el archivo de flujo de trabajo

   Agregar .github/workflows/capgo-build.yml a tu repositorio. Elige uno de los tres patrones de disparador a continuación dependiendo de cómo deseas disparar los builds.

¿Qué acaba en tus secretos

Por referencia, gh secret set -f crearán 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ñadido 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. Disparador Manual

Permite a 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 de ad-hoc o iniciar un lanzamiento 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 }}

Reemplazar com.example.app con tu ID de aplicación. Una vez que se haya confirmado, vaya a Acciones → Capgo Construye (Manual) → Ejecuta flujo de trabajo para 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.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.

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. Configuración fail-fast: false significa que un build de iOS fallido no cancelará el build de Android en curso (y viceversa) — útil cuando una plataforma tiene un problema de firma transitorio.

Nota

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

3. Realizar un build de depuración al enviar a Main

Captura las regresiones de build nativo temprano produciendo un build de depuración de Android en cada envío a main. Barato de ejecutar, rápido feedback, y puedes saltarte la carga en la Tienda de Juegos para mantenerlo puramente como una 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 El filtro asegura que el flujo de trabajo no se ejecute en cambios solo de documentación. --no-playstore-upload salta la carga en la Tienda de Juegos (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 Juegos / TestFlight

For test builds, omit 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 binario.

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

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

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

iOS utiliza la clave de recorrido de App Store Connect API y envía la versión procesada de TestFlight a revisión en App Store. Requiere app_store distribución; --ios-testflight-groups es opcional para la distribución de pruebas externas y no es necesario para la revisión en App Store:

- 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

Advertencia

Esta ruta solo envía el artefacto de la compilación. Los metadatos de la lista de tienda, los grupos de probadores, 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 las ejecuciones de CI las utilicen.

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

Éxito --output-record <path> to persist the build artifact URL and QR code to disk when the build succeeds, then read it back in subsequent steps with build last-outputrastrillar logs, 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 PNG QR code al lado /tmp/build.json.qr.png. build last-output lo lee de nuevo:

• --field outputUrl imprime solo la URL de descarga (terminada con nueva línea; seguro para URL=$(...)).
• --field qrCodePngPath imprime el camino del PNG para que puedas subirlo 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.

Nota

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

Saltar el aumento de 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 rara vez vale la pena, pero las dependencias nativas de Capacitor (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') }}

Solució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 (ver protecciones de entorno/rama)
Faltan credenciales de iOS / Android	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 hay una extensión nativa en package.jsono se te olvidó bun install antes de cap sync
El compilado 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. Verificar localmente con bunx @capgo/cli@latest build credentials manage
El compilado se queda colgado después de ‘Subiendo proyecto’	El archivo de proyecto es inusualmente grande — verifique que node_modules no se está subiendo (no debería hacerlo por defecto)
Provisioning profile doesn't match bundle ID	The map de provisión apunta a un ID de paquete diferente al que Xcode está firmado. Re-ejecuta build init para refrescar el perfil, luego re-export con build credentials manage
Los credenciales cambiaron localmente pero CI sigue fallando	No te olvides de re-export 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. Confirma para sobreescribir, o re-export por plataforma con --platform ios / --platform android
build last-output imprime una URL vacía	No se pasó la construcción --output-uploado falló antes de producir un artefacto. outputUrl será null en el registro. Rama en [ -n "$URL" ] antes de usarlo
build last-output errores con Unsupported record schemaVersion	El ejecutor está en una versión más antigua de CLI que la que escribió el registro. Acople 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 fallas de compilación específicas de plataforma, consulte el Guía de solución de problemas.

Pasos siguientes

Auto OTA o Nativo Branch CI entre la actualización en vivo de carga y Capgo Build.

Activar desde la interfaz de usuario de CI Ejecutar Capgo Build desde la pestaña Acciones a demanda.

Crear Webhooks Iniciar el mismo flujo de trabajo desde una llamada HTTP desde la consola 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.