Choisissez automatiquement la mise à jour en direct ou la construction native

La plupart des Capacitor mises à jour sont JavaScript-only et devraient être envoyées comme une mise à jour en direct. Quelques changements touchent les __CAPGO_KEEP_0__ natifs et nécessitent un nouveau fichier binaire depuis __CAPGO_KEEP_0__ Build.Guide de construction de code Ce guide montre comment faire en sorte que les Capgo Actions, GitLab CI, ou toute autre plateforme CI/CD prennent la bonne décision à chaque push — sans qu'un humain décide.. 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.

Section intitulée « La Décision »

Capgo Build

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

OTA signifie que les packages natifs correspondent à ce qui est déjà en ligne sur le canal. native signifie qu'un plugin, une version Capacitor ou une autre dépendance native a changé — un bundle par voie aérienne ne peut pas mettre à jour ces appareils de manière sécurisée.

releaseType compare les métadonnées des packages natifs (Capacitor / plugins et versions Cordova). Il fait ne pas ios/, android/voir chaque modification sous capacitor.config.*, ou releaseType Barrer ces chemins dans Git d'abord, puis utilisez

Voir Compatibilité Native Voir les règles et le manuel complets dans la bundle compatibility tableau.

Conseil

Gardez chaque pipeline de production sur releaseType. C'est moins cher que de deviner, et cela évite de livrer une mise à jour live qui fait planter les appareils toujours sur la version native plus ancienne.

Prérequis

• l'application Capgo enregistrée et une clé Capgo API en CI secrets comme CAPGO_TOKEN
• en Mises à jour en direct chargent (bundle upload) — voir en Intégration CI/CD
• en Capgo Les informations d'identification de construction dans CI si vous attendez des tâches natives — voir en GitHub Actions en ou en Les informations d'identification
• en Une chaîne qui existe déjà et correspond à la production (exemples utilisent production)
• en Chaîne sur le metadata en stratégie afin que chaque téléchargement puisse transporter --auto-min-update-version en (une fois) :

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 OTA-safe.
4. Si OTA, téléchargez avec --fail-on-incompatible et --auto-min-update-version.
5. Si native, exécutez Capgo Build, puis téléchargez le bundle correspondant avec --auto-min-update-version de sorte que les métadonnées natives du canal soient mises à jour. Ne pas utilisez --fail-on-incompatible ce pour cette mise à niveau de base — les nouveaux packages natives doivent différer. Voir Workflow de canal Native + OTA pour la FAQ du niveau de canal.

GitHub Actions

Un flux de travail qui bloque les chemins natifs, 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 connecter les secrets de signature comme décrit dans GitHub Actions pour Capgo Build.

Note

--fail-on-incompatible appartient uniquement au job OTA. Une fois que vous avez mis le canal sur la stratégie, gardez metadata sur chaque téléchargement (OTA et baseline native). Une fois que le binaire natif est expédié, téléchargez le paquet correspondant avec --auto-min-update-version et sans --auto-min-update-version appartient uniquement au job OTA. Une fois que vous avez mis le canal sur la stratégie, gardez --fail-on-incompatible plus tard releaseType Vérifiez les nouveaux packages natifs.

GitLab CI

GitLab évalue rules lorsque la pipeline est créée, donc branch avec un shell if dans un job de déploiement (ou générer un pipeline enfant dynamique) si vous avez besoin de jobs de matrice natifs séparés :) .gitlab-ci.yml

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

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

Autres plateformes CI

Les mêmes trois étapes fonctionnent n'importe où :

É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

Cartographiez la sortie de la shell / stdout dans les conditionnels de votre plateforme (ou maintenez un seul job avec une shell if, comme GitLab ci-dessus):

• Azure Pipelines — définir une variable de sortie à partir d'une étape de script, puis utiliser condition: eq(variables['releaseType'], 'OTA')
• Bitbucket Pipelines — écrire RELEASE_TYPE=… pour $BITBUCKET_PIPELINES_VARIABLES_PATHdéclarer-le sous output-variableset faire dériver les étapes ultérieures avec condition: state: RELEASE_TYPE == "OTA" seul les artefacts de fichiers ne peuvent pas déterminer condition)
• CircleCI — when est évalué à temps de compilation de la configuration, donc brancher avec une console de shell en temps d'exécution if ou une configuration dynamique / continuation, et non une valeur de workspace dans when
• Jenkins — captez la sortie standard dans une variable d'environnement et utilisez-la when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Filtrages de chemins (Optimisation de vitesse facultative)

Les filtres de chemin sont une optimisation de coût, et non une substitution pour le Capgo vérificateur. 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*.jsonet des fichiers de configuration de framework :

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

Si vous utilisez une liste d'autorisation au lieu de cela, incluez tous les entrées que vos builds web et natifs lisent, et non seulement src/ et package.json.

context : Page/zone : Site web de marketing Capgo. Rôle : Étiquette de navigation ou élément UI court. Vu dans : page trust.astro. Clé de message `et` (Et).

Titre de la section « Après un verdict natif »

1. Lorsque CI choisit la version native : « Capgo » La construction produit des binaires signés et peut soumettre à TestFlight / Play (voir configuration).
2. Téléchargez le bundle JS correspondant avec --auto-min-update-version (stratégie de métadonnées) afin que les enregistrements du canal notent les nouveaux packages natifs — sinon, le prochain commit JS uniquement retourne native.
3. Une fois les utilisateurs ont installé le nouveau binaire, les commits JavaScript ultérieurs retournent à OTA encore.

Guides connexes

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

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

GitHub Actions (Capgo Build) Signatures et workflows de construction natives complets.

Déclencher les constructions à partir de l'interface de CI Exécuter une construction native à la demande à partir de GitHub, GitLab ou Bitbucket.

Déclencher les constructions via Webhook Déclencher la construction Capgo à partir d'un tableau de bord administrateur ou tout client HTTP.