Choisir automatiquement Live Update ou Native Build
Copiez un prompt de configuration incluant les étapes d'installation et le guide markdown complet pour ce plugin.
La plupart des releases Capacitor sont 100 % JavaScript et doivent être déployées comme live update. Certains changements touchent le code natif et nécessitent un nouveau binaire de Build Capgo. Ce guide montre comment faire en sorte que GitHub Actions, GitLab CI ou toute autre plateforme CI/CD choisisse le bon chemin à chaque push — sans décision humaine.
La décision
Section intitulée « La décision »Capgo sait déjà quel chemin est sûr. Après votre build web (et avant d'envoyer un bundle ou de demander un Native Build), lancez :
npx @capgo/cli@latest bundle releaseType com.example.app --channel production# → OTA ship with bundle upload# → native ship with Capgo BuildOTA signifie que les packages natifs correspondent à ce qui est déjà en ligne sur le canal. native signifie qu'un plugin, une version de Capacitor ou une autre dépendance native a changé — un simple bundle OTA ne peut pas mettre à jour ces appareils en toute sécurité.
releaseType compare métadonnées du package natif (Capacitor/Cordova plugins and versions). Il ne pas voit pas chaque modification sous ios/, android/, ou capacitor.config.*. Bloquez d’abord ces chemins dans git, puis utilisez releaseType pour la compatibilité des dépendances — les exemples ci-dessous font les deux.
Consultez Compatibilité native pour les règles complètes et le manuel bundle compatibility tableau.
Prerequisites
Section intitulée « Prérequis »- application Capgo enregistrée et un clé Capgo API dans les secrets CI en tant que
CAPGO_TOKEN - upload de Live Updates fonctionnel (
bundle upload) — voir Intégration CI/CD - Capgo Identifiants de build dans la CI si vous prévoyez des jobs natifs — voir GitHub Actions GitHub ou Identifiants
- Un canal existant correspondant à la production (les exemples utilisent
production) - Canal sur le
metadatastratégie pour que chaque upload puisse inclure--auto-min-update-version(une seule fois) :
npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadataFonctionnement attendu du pipeline
Section intitulée « Comment le pipeline doit 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]
- Compilez les assets web comme d’habitude.
- Si le commit touche
ios/,android/, oucapacitor.config.*, forcez le chemin natif. - Sinon, demandez à Capgo
releaseTypesi le commit est compatible OTA. - Si
OTA, envoyez avec--fail-on-incompatibleet--auto-min-update-version. - Si
native, lancez Capgo Build, puis envoyez le bundle correspondant avec--auto-min-update-versionafin que les métadonnées natives du canal avancent. Faites pas utiliser--fail-on-incompatiblepour cet upload de référence — les nouveaux packages natifs sont censés être différents. Voir Workflow canaux natifs + OTA pour la FAQ au niveau du canal.
GitHub Actions GitHub
Section intitulée « Actions GitHub »Un workflow qui conditionne les chemins natifs, puis bifurque sur releaseType:
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-versionRemplacer com.example.app et configure les secrets de signature comme décrit dans GitHub Actions pour Capgo Build.
GitLab CI
Section intitulée « GitLab CI »GitLab évalue rules lors de la création du pipeline, donc branchez avec un shell if dans un seul job de déploiement (ou générez un pipeline enfant dynamique si vous avez besoin de jobs natifs matrix séparés) :
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: - mainStore CAPGO_TOKEN et les variables de signature Capgo en tant que variables CI/CD masquées/protégées.
Autres plateformes CI
Section intitulée « Autres plateformes CI »Les mêmes trois étapes fonctionnent partout :
| Étape | Commande |
|---|---|
| Verdict | 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 shell / stdout dans les conditionnelles de votre plateforme (ou conservez un seul job avec un shell if, comme GitLab ci-dessus) :
- Azure Pipelines — définissez une variable de sortie depuis une étape de script, puis utilisez
condition: eq(variables['releaseType'], 'OTA') - Bitbucket Pipelines — écrivez
RELEASE_TYPE=…vers$BITBUCKET_PIPELINES_VARIABLES_PATH, déclarez-le sousoutput-variables, et conditionnez les étapes suivantes aveccondition: state: RELEASE_TYPE == "OTA"(les artefacts de fichiers seuls ne pilotent pascondition) - CircleCI —
whenest évalué au moment de la compilation de la config, donc conditionnez avec un shell d'exécutionif(ou une configuration dynamique / continuation), et non une valeur de workspace danswhen - Jenkins — capture stdout into an env var and use
when { environment name: 'RELEASE_TYPE', value: 'OTA' }
Filtres de chemins (accélération optionnelle)
Section intitulée « Filtres de chemins (accélération optionnelle) »Les filtres de chemins sont une optimisation des coûts, pas un substitut à la vérification Capgo. Privilégiez l'exclusion des chemins réservés à la documentation plutôt que de maintenir une liste d'autorisation fragile — les builds web dépendent souvent aussi de vite.config.*, tsconfig*.json, et les fichiers de config du framework :
on: push: branches: [main] paths-ignore: - '**.md' - 'docs/**' - '.github/**'Si vous utilisez une liste blanche, incluez toutes les entrées lues par vos builds web et natifs, pas seulement src/ et package.json.
Après un verdict natif
Section intitulée « Après un verdict natif »Lorsque la CI choisit le natif :
- Capgo Build produit des binaires signés et peut soumettre à TestFlight / Play (voir configuration).
- Envoyez le bundle JS correspondant avec
--auto-min-update-version(stratégie de métadonnées) afin que le canal enregistre les nouveaux paquets natifs — sinon, le prochain commit JS uniquement renverranative. - Une fois que les utilisateurs ont installé le nouveau binaire, les commits JavaScript suivants reviennent à
OTAà nouveau.