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 Cette 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 / les plugins et versions de Cordova). Il ne ne voit pas chaque modification sous ios/, android/, ou capacitor.config.*Barrer ces chemins dans Git d'abord, puis utilisez releaseType pour la compatibilité des dépendances — les exemples ci-dessous font les deux.

Voir Compatibilité Native pour les règles et le manuel complets et la table. bundle compatibility Conseil

Faites passer chaque pipeline de production par

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. releaseTypePrérequis

Section intitulée « Prérequis »

• Capgo app registered and a Capgo API key en CI secrets comme CAPGO_TOKEN
• en Mises à jour en direct chargent (travail) (bundle uploaden — voir fr 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 fr ou
• en Aucun canal qui existe déjà et correspond à la production (exemples utilisent production)
• en Canal sur le metadata fr stratégie afin que chaque téléchargement puisse transporter --auto-min-update-version fr (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 OTAupload avec --fail-on-incompatible et --auto-min-update-version.
5. Si native, run Capgo Build, then upload the matching bundle with --auto-min-update-version afin que les métadonnées natives du canal soient mises à jour. Ne pas utiliser --fail-on-incompatible pour cet upload de référence — les nouveaux packages natives doivent différer. Voir Native + OTA Channel Workflow pour la FAQ du niveau canal.

Actions de GitHub

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 reliez les secrets de signature comme décrit dans GitHub Actions pour Capgo Build.

Remarque

--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 a été expédié, téléchargez le paquet correspondant avec --auto-min-update-version et sans --auto-min-update-version et sans --fail-on-incompatible par la suite 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

when the pipeline is created, so branch with a shell CAPGO_TOKEN et Capgo les variables de signature de build sous forme masquée/protégée comme 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 vos conditionnels de plateforme (ou conservez un seul job avec une shell if, comme GitLab ci-dessus):

• Azure Pipelines — définissez une variable de sortie à partir d'une étape de script, puis utilisez-la condition: eq(variables['releaseType'], 'OTA')
• Bitbucket Pipelines — écrire RELEASE_TYPE=… vers $BITBUCKET_PIPELINES_VARIABLES_PATHdéclarer-le sous output-variableset brancher 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 un shell de runtime if ou une configuration dynamique / continuation, pas une valeur de bureau de travail dans when
• Jenkins — capte la sortie standard dans une variable d'environnement et utilise when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Filtrage des chemins (Optimisation de la vitesse, facultatif)

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

Section intitulée « 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 incorrects.

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 de secrets et flux de construction natifs complets.

Déclencher les constructions à partir de l'interface de l'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.