Elige automáticamente Live Update o construye nativamente

La mayoría de las versiones de Capacitor son solo JavaScript y deben enviarse como un live updateAlgunos cambios afectan nativos code y requieren un nuevo binario de Capgo ConstrucciónEsta guía muestra cómo hacer que las acciones de GitHub, GitLab CI o cualquier otra plataforma de CI/CD elijan el camino correcto en cada push — sin que un humano decida.

La Decisión

Capgo ya sabe qué ruta es segura. Después de tu compilación web (y antes de subir o solicitar una compilación nativa), ejecuta:

npx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      ship with bundle upload
# → native   ship with Capgo Build

OTA significa que los paquetes nativos coinciden con lo que ya está vivo en el canal. native significa que un plugin, una versión Capacitor, o otra dependencia nativa ha cambiado — un paquete por aire no puede actualizar esos dispositivos de manera segura.

releaseType compara metadatos nativos del paquete (Capacitor/Plugins de Cordova y versiones). Lo hace , o ver cada cambio en vivo ios/, android/, or capacitor.config.*Gatee esas rutas en Git primero, luego utilice releaseType para compatibilidad de dependencias — los ejemplos a continuación hacen ambas cosas.

See See Native Compatibility para las reglas completas y el manual bundle compatibility tabla.

Consejo

Coloque cada pipeline de producción en releaseTypeEs más barato que adivinar, y evita enviar un live update que hace que los dispositivos con la versión nativa anterior se caigan.

__CAPGO_KEEP_0__

• La aplicación Capgo registrada y un Capgo API clave en secretos de CI CAPGO_TOKEN
• __CAPGO_KEEP_0__ app registrada y unabundle upload — vea Integración CI/CD
• Capgo Credenciales de construcción en CI si espera trabajos nativos — vea GitHub Acciones o o bien
• Un canal que ya existe y coincide con la producción (los ejemplos utilizan) production)
• credenciales metadata estrategia para que cada subida pueda transportar --auto-min-update-version Canal en el

npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata

Cómo debería funcionar la Pipeline

flowchart TD
  A[Push / merge] --> B[Install + web build]
  B --> C["bundle releaseType"]
  C -->|OTA| D["bundle upload"]
  C -->|native| E["build request iOS + Android"]
  E --> F[Store / TestFlight / Play]

1. Construye activos web de manera habitual.
2. Si el commit afecta ios/, android/, o capacitor.config.*, fuerza el camino nativo.
3. De lo contrario, pregunta a Capgo releaseType si el commit es seguro para OTA.
4. Si OTA, sube con --fail-on-incompatible y --auto-min-update-version.
5. Si native, ejecuta Capgo Build, luego sube el paquete correspondiente con --auto-min-update-version para que los metadatos nativos del canal avancen. No no no usar --fail-on-incompatible para esa carga de base — los nuevos paquetes nativos deben diferir. Consulte Flujo de trabajo de Canal Nativo + OTA para la FAQ del canal.

GitHub Acciones

Un flujo de trabajo que bloquea las rutas nativas, luego bifurca en releaseType:

.github/workflows/capgo-release.yml

name: Capgo Release

on:
  push:
    branches: [main]

jobs:
  decide:
    runs-on: ubuntu-latest
    outputs:
      release_type: ${{ steps.verdict.outputs.type }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'

      - run: npm ci
      - run: npm run build

      - name: Decide OTA vs native
        id: verdict
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
        run: |
          BEFORE="${{ github.event.before }}"
          if [ -z "$BEFORE" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
            BEFORE="$(git rev-parse HEAD~1 2>/dev/null || echo '')"
          fi
          if [ -z "$BEFORE" ] || git diff --name-only "$BEFORE" "${{ github.sha }}" \
            | grep -qE '^(ios/|android/|capacitor\.config\.)'; then
            TYPE=native
            echo "Native path/config changed (or no prior commit) — forcing native"
          else
            TYPE=$(npx @capgo/cli@latest bundle releaseType com.example.app --channel production | tr -d '[:space:]')
          fi
          echo "type=$TYPE" >> "$GITHUB_OUTPUT"
          echo "Capgo release type: $TYPE"

  live_update:
    needs: decide
    if: needs.decide.outputs.release_type == 'OTA'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - name: Upload live update
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
        run: |
          npx @capgo/cli@latest bundle upload com.example.app \
            --channel production \
            --fail-on-incompatible \
            --auto-min-update-version

  native_build:
    needs: decide
    if: needs.decide.outputs.release_type == 'native'
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - run: npx cap sync ${{ matrix.platform }}
      - name: Capgo Build ${{ matrix.platform }}
        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 }}
          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 ${{ matrix.platform }} \
            --build-mode release

  native_bundle:
    needs: [decide, native_build]
    if: needs.decide.outputs.release_type == 'native'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v6
        with:
          node-version: '24'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - name: Upload bundle for new native baseline
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
        run: |
          # Channel must already be on metadata (see Prerequisites above)
          npx @capgo/cli@latest bundle upload com.example.app \
            --channel production \
            --auto-min-update-version

Sustituir com.example.app y conectar los secretos de firma como se describe en GitHub Acciones para Capgo Construcción.

Nota

--fail-on-incompatible solo debe estar en el trabajo OTA. Después de poner el canal en la metadata estrategia, mantenga --auto-min-update-version Después de que se envíe un binario nativo, suba el paquete correspondiente con --auto-min-update-version y sin --fail-on-incompatible más adelante releaseType verifiquen los nuevos paquetes nativos.

GitLab CI

GitLab evalúa rules cuando se crea el pipeline, por lo que la rama con una shell if dentro de un trabajo de despliegue (o genere un pipeline hijo dinámico si necesita matrices de trabajo nativas separadas):

.gitlab-ci.yml

image: node:24

stages:
  - build
  - deploy

variables:
  APP_ID: com.example.app
  CHANNEL: production

build_web:
  stage: build
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
      - node_modules/
    expire_in: 1 hour
  only:
    - main

deploy:
  stage: deploy
  needs: [build_web]
  script:
    - |
      BEFORE="${CI_COMMIT_BEFORE_SHA:-}"
      if [ -z "$BEFORE" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
        BEFORE="$(git rev-parse HEAD~1 2>/dev/null || echo '')"
      fi
      if [ -z "$BEFORE" ] || git diff --name-only "$BEFORE" "$CI_COMMIT_SHA" \
        | grep -qE '^(ios/|android/|capacitor\.config\.)'; then
        TYPE=native
      else
        TYPE=$(npx @capgo/cli@latest bundle releaseType "$APP_ID" --channel "$CHANNEL" | tr -d '[:space:]')
      fi
      echo "Capgo release type: $TYPE"
      if [ "$TYPE" = "OTA" ]; then
        npx @capgo/cli@latest bundle upload "$APP_ID" \
          --channel "$CHANNEL" \
          --fail-on-incompatible \
          --auto-min-update-version
      elif [ "$TYPE" = "native" ]; then
        npx cap sync
        npx @capgo/cli@latest build request "$APP_ID" --platform ios --build-mode release
        npx @capgo/cli@latest build request "$APP_ID" --platform android --build-mode release
        npx @capgo/cli@latest bundle upload "$APP_ID" \
          --channel "$CHANNEL" \
          --auto-min-update-version
      else
        echo "Unexpected release type: $TYPE" >&2
        exit 1
      fi
  only:
    - main

Guardar CAPGO_TOKEN y Capgo Variables de firma de compilación almacenadas como variables de CI/CD protegidas.

Otras plataformas de CI

Los mismos tres pasos funcionan en cualquier lugar:

Paso	Comando
Veredicto	npx @capgo/cli@latest bundle releaseType APP_ID --channel production
OTA path	npx @capgo/cli@latest bundle upload APP_ID --channel production --fail-on-incompatible --auto-min-update-version
Ruta nativa	npx @capgo/cli@latest build request APP_ID --platform ios (o android) --build-mode release

Mapa la salida de la shell / stdout en las condiciones de tu plataforma (o mantén un solo trabajo con una shell ifFlujo de trabajo de Azure Pipelines

• Azure Pipelines sete un variable de salida desde un paso de script, luego utilice condition: eq(variables['releaseType'], 'OTA')
• contexto de la ruta OTA — escribir RELEASE_TYPE=… a $BITBUCKET_PIPELINES_VARIABLES_PATH, declare it under output-variablesy posteriormente con la rama condition: state: RELEASE_TYPE == "OTA" (los artefactos de archivo no pueden impulsar condition)
• CircleCI — when is evaluated at config-compile time, so branch with a runtime shell if (dynamic configuración / continuación), no un valor de espacio de trabajo en when
• Jenkins — capture stdout into an env var and use when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Filtros de Rutas (Aceleración Opcional)

Los filtros de ruta son una optimización de costos, no un sustituto de la Capgo comprobación. Prefiere excluir rutas de documentos únicamente en lugar de mantener una lista de permisos frágil — las compilaciones web a menudo también dependen de vite.config.*, tsconfig*.json, y archivos de configuración de marco:

on:
  push:
    branches: [main]
    paths-ignore:
      - '**.md'
      - 'docs/**'
      - '.github/**'

Si utiliza una lista de permisos, incluya todos los inputs que leen tanto sus compilaciones web como nativas, no solo src/ y package.json.

Después de un Veredicto Nativo

Cuando CI elige nativo:

1. Capgo La compilación produce binarios firmados y puede enviar a TestFlight / Play (consulte Configuración).
2. Subir el conjunto de JS correspondiente con --auto-min-update-version (método de metadatos) así que el canal registra los nuevos paquetes nativos — de lo contrario, el próximo commit solo de JS sigue devolviendo native.
3. Una vez que los usuarios instalen la nueva binaria, los commits de JavaScript solo volverán a OTA de nuevo.

Guías relacionadas

Compatibilidad nativa ¿Por qué Capgo devuelve OTA vs nativo y cómo bloquear subidas maliciosas?

Flujo de trabajo de canal NATIVO + OTA Canales de desarrollo y producción y cuándo dejar de usar --fail-on-incompatible para una base nativa intencional.

GitHub Acciones (Capgo Construcción) Flujos de compilación nativos completos y secretos de firma.

Desencadenar construcciones desde la interfaz de CI Ejecutar una construcción nativa a demanda desde GitHub, GitLab o Bitbucket.

Desencadenar compilaciones mediante webhook Enciende Capgo Construye desde una consola de administrador o cualquier cliente HTTP.