Auto Choose Live Update or Native Build

Most Capacitor releases are JavaScript-only and should ship as a live update. Certaines modifications affectent le native code et nécessitent un nouveau binaire de Capgo Build. This guide shows how to make GitHub Actions, GitLab CI, or any other CI/CD platform pick the correct path on every push — without a human deciding.

Cette page

Capgo already knows which path is safe. After your web build (and before you upload or request a native build), run:

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

OTA Correspond à ce que les packages natifs sont déjà en live sur le canal. native Signifie un plugin, une version Capacitor ou une autre dépendance native modifiée — un bundle par voie aérienne ne peut pas mettre à jour ces appareils de manière sûre.

releaseType compare les métadonnées des packages natifs (Capacitor / plugins Cordova et versions). Il fait pas voir chaque modification sous ios/, android/, ou capacitor.config.*. Bloquez ces chemins dans Git avant, puis utilisez releaseType pour la compatibilité des dépendances — les exemples ci-dessous font les deux.

Voir Compatibilité Native pour les règles complètes et le manuel bundle compatibility table.

Conseil

Gardez chaque pipeline de production sur releaseTypeIl est moins coûteux que de deviner, et il évite de livrer un live update qui fait planter les appareils toujours sur le binôme natif plus ancien.

Prerequisites

• Application Capgo enregistrée et une Capgo API clé en tant que secrets de CI CAPGO_TOKEN
• Mises à jour en direct téléchargent (bundle upload) — voir Intégration CI/CD
• Capgo Build credentials in CI if you expect native jobs — see Actions de GitHub or ou
• Un canal qui existe déjà et correspond à la production (les exemples utilisent) production)
• Informations d'identification metadata strategy so every upload can carry --auto-min-update-version Canal sur le

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

Comment la pipeline devrait fonctionner

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. Construire les actifs web comme d'habitude.
2. Si le commit touche ios/, android/, ou capacitor.config.*, forcer le chemin natif.
3. Sinon demander à Capgo releaseType si le commit est sécurisé OTA.
4. Si OTA, télécharger avec --fail-on-incompatible et --auto-min-update-version.
5. Si native, exécutez Capgo Build, puis téléchargez ensuite le bundle correspondant avec --auto-min-update-version Ainsi, les métadonnées natives du canal sont mises à jour. pas utilisez --fail-on-incompatible ce processus pour cette mise à jour de base — les nouveaux packages natives doivent différer. Consultez Workflow Native + OTA du canal pour la FAQ du niveau canal.

GitHub Actions

Une workflow qui bloque les chemins natives, puis se branche sur 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

Remplacer com.example.app et reliez les secrets de signature comme décrit dans GitHub Actions pour Capgo Construction.

Note

--fail-on-incompatible appartient uniquement au job OTA. Une fois que vous avez ajouté le canal sur le metadata stratégie de maintenance --auto-min-update-version Sur chaque téléchargement (OTA et ligne de base native). Après l'envoi d'un fichier binaire natif, téléchargez le bundle correspondant avec --auto-min-update-version afin que plus tard --fail-on-incompatible plus tard releaseType Vérifiez les nouveaux packages natifs.

GitLab CI

GitLab évalue rules lors de la création du pipeline, afin de brancher une commande shell if dans une seule tâche de déploiement (ou générer un) pipeline enfant dynamique si vous avez besoin de tâches de matrice native séparées)

Copier dans le presse-papier

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

Store CAPGO_TOKEN et Capgo les variables de signature de build comme variables CI/CD masquées/protégées.

Autres plateformes CI

Les mêmes trois étapes fonctionnent partout :

Étape	Commande
Résultat	npx @capgo/cli@latest bundle releaseType APP_ID --channel production
Chemin OTA	npx @capgo/cli@latest bundle upload APP_ID --channel production --fail-on-incompatible --auto-min-update-version
Chemin natif	npx @capgo/cli@latest build request APP_ID --platform ios ou android) --build-mode release

Mappez l'exit de la shell / stdout dans vos conditionnels de plateforme (ou maintenez un seul job avec une shell) ifcomme GitLab ci-dessus) :

• Azure DevOps — définir une variable de sortie à partir d'une étape de script, puis utiliser condition: eq(variables['releaseType'], 'OTA')
• Bitbucket Pipelines — écrire RELEASE_TYPE=… vers $BITBUCKET_PIPELINES_VARIABLES_PATHdeclarez-le sous output-variableset branchons les étapes ultérieures avec condition: state: RELEASE_TYPE == "OTA" (file artefacts seuls ne peuvent pas déterminer) condition)
• CircleCI — when is evaluated at config-compile time, so branch with a runtime shell if ou une configuration dynamique / continuation, et non une valeur de workspace dans when
• Jenkins — capture stdout into an env var and use when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Filtres de Chemins (Amélioration de vitesse facultative)

Les filtres de chemin sont une optimisation de coût, et non une substitution pour la vérification Capgo. Préférez exclure les chemins de documentation uniquement plutôt que de maintenir une liste d'autorisation fragile — les builds web dépendent souvent également de vite.config.*, tsconfig*.json, et de fichiers de configuration de framework :

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

Si vous utilisez une liste d'autorisation, incluez tous les inputs que vos builds web et natives lisent, et non seulement src/ et package.json.

Après un verdict natif

Lorsque CI choisit la version native :

1. Capgo La construction produit des binaires signés et peut soumettre à TestFlight / Play (voir configuration).
2. Envoyez le bundle JS correspondant avec --auto-min-update-version (stratégie de métadonnées) donc le canal enregistre les nouveaux packages natifs — sinon le prochain commit JS uniquement retourne encore native.
3. Une fois que les utilisateurs installent le nouveau binaire, les commits JavaScript ultérieurs retournent à OTA encore.

Guides connexes

Compatibilité native Pourquoi Capgo retourne OTA vs natif et comment bloquer les téléchargements malveillants.

Flux de travail du canal Native + OTA Canaux Dev/production et quand abandonner --fail-on-incompatible pour une base native intentionnelle.

GitHub Actions (Capgo Build) Secrets de signature et flux de construction natif complet.

Déclencher des constructions à partir de l'interface de CI Exécutez une build native sur demande à partir de GitHub, GitLab ou Bitbucket.

Déclenchez les Builds via Webhook Allumez Capgo Construisez à partir d'un tableau de bord administratif ou tout client HTTP.