GitHub Acciones

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

Lo que 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 vagando por laptops.

Secretos escalonados

Las credenciales viven en los secretos de repositorio GitHub, 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. Una típica versión se completa en menos de 10 minutos.

Requisitos previos

Antes de configurar el flujo de trabajo, asegúrate de que tengas:

• A 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 el recorrido 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)

Nota

El flujo a continuación asume que ya existen credenciales en tu almacén de credenciales locales (desde build initSi aún no los has configurado, hazlo primero — el asistente gestiona 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 archivo. Combinado con gh secret set -fEsto convierte todo el conjunto de CI/CD en tres comandos — sin codificación base64 manual, sin manipulación de JSON, sin copiar-secret-por-secreto.

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

   La clave API 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 el Capgo panel de control con subir permisos o superior.

2. Exporta tus credenciales a un .env archivo

   Ejecuta el administrador interactivo de credenciales:

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

   In el TUI, selecciona Exportar a .env. El CLI escribe .env.capgo.<appId> a tu directorio actual con permisos 0600 (solo lectura del propietario) — por ejemplo, .env.capgo.com.example.app. Cuando tanto iOS como Android estén configurados, ambos secretos 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.

   ¿Necesitas un archivo por plataforma?

   Pass --platform ios (o --platform androidpara limitar el administrador a una plataforma. La exportación produce luego 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 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 haber divergido. Si el administrador encuentra divergencia, imprime las claves en conflicto, solicita 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. Envíe 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 KEY=value línea:

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

   ¡Listo! — Ahora todas las claves de tu flujo de trabajo 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 subido 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 Selecciona una de las tres patrones de disparo a continuación según cómo deseas desencadenar los builds para tu repositorio.

¿Qué acaba en tus secretos?

Por referencia, gh secret set -f Crearán estos secretos de repositorio (sus archivos YAML de flujo de trabajo los refieren 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
Agregados manualmente	CAPGO_TOKEN

No necesita memorizar estos — los ejemplos de flujo de trabajo a continuación ya refieren 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

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

.github/trabajos/capgo-construcción-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 por su ID de aplicación. Una vez comprometido, vaya a Acciones → Capgo Construye (Manual) → Ejecutar flujo de trabajo para dispararlo.

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.

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

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

Catches native build regressions early by producing a debug Android build on every push to GitHub. mainBarato de ejecutar, rápido feedback y puedes omitir la carga en la tienda Play para mantenerlo como una prueba 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 garantiza que el flujo de trabajo no se ejecute en cambios solo de documentación. --no-playstore-upload omite la presentación en la tienda Play (sin 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.

Pautas Comunes

Saltar la carga en la tienda Play / TestFlight

Para pruebas, 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 Aplicaciones). Combine ambos con --output-upload para obtener una URL de descarga temporal para el binario.

Presentar 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 de la tienda final bajo su control. Para las liberaciones de CI que deberían moverse directamente a la flujo de revisión de la tienda, agregue --submit-to-store-review.

Android utiliza su PLAY_CONFIG_JSON servicio de cuenta. Sin una pista explicita --submit-to-store-review se establece en 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 sobrescribir 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 una liberación interna completada 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 App Store. Requiere app_store distribución; --ios-testflight-groups es opcional para la distribución beta externa 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 compilación. Los metadatos de lista de tienda, grupos de probadores, detalles de contacto de revisión, respuestas de cumplimiento y opciones de lanzamiento todavía deben estar disponibles en App Store Connect o Google Play Console antes de que las CI las ejecute.

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

Pass --output-record <path> persistir la URL del artefacto de compilación y el código QR code en disco cuando la compilación tenga éxito, y leerlo nuevamente en los pasos posteriores con 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 PNG QR code al lado /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 del PNG para que puedas subirlo como una anexión de PR.
• --qr imprime el 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 un build exitoso. No soportados schemaVersion y desconocidos --field Si los valores salen de cero, un CLI en el ejecutor se detiene ruidosamente en lugar de emitir un URL vacío en silencio.

Saltar el aumento de número de compilación

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

Cachear dependencias

Nota

Esta sección trata sobre GitHub Acciones cachear en el ejecutor de CI (local Pods/ y .gradle antes de subir). 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 a particionar RC y producción, o --no-cache a deshabilitar restaurar y guardar. Consulte Resolución de problemas: restaurar cache equivocado.

bun install ya es lo suficientemente rápido que un cache de dependencias JS raramente vale la pena, 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

Symptom	Causa probable
CAPGO_TOKEN is not set	No se agregó secreto, o el trabajo no tiene acceso a él (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	Un plugin nativo no está en package.jsono se olvidó bun install antes de cap sync
Crea un problema y discute antes de trabajar en una nueva característica	El proyecto se compila con éxito pero no aparece la aplicación en App Store Connect bunx @capgo/cli@latest build credentials manage
Build hangs after “Uploading project”	La compilación se atasca después de 'Subiendo proyecto' 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 que Xcode está firmado. Re-ejecutar build init para refrescar el perfil, luego re-export con build credentials manage
Los credenciales cambiaron localmente pero CI sigue fallando	No olvide 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 uno-gana, o re-exporte por plataforma con --platform ios / --platform android
build last-output imprime una URL vacía	La compilación no pasó --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. Pin ambos productor y 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 construcción específicas de plataforma, consulte la Guía de solución de problemas.

Pasos siguientes

Auto OTA o Nativo Branch CI entre live update subida y Capgo construcción.

Disparar desde la interfaz de CI Ejecuta Capgo Build desde la pestaña Acciones a demanda.

Webhooks de construcción Inicia 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 construcciones.