Scegli automaticamente Live Update o Costruisci nativo

Most Capacitor releases are JavaScript-only and should ship as a live updateAlcune modifiche interessano il nativo code e richiedono un nuovo binario da Capgo BuildQuesta guida mostra come creare GitHub Azioni, GitLab CI, o qualsiasi altra piattaforma CI/CD per scegliere la strada corretta con ogni push — senza che un essere umano debba decidere.

La Scelta

Ecco già Capgo che sa quale percorso è sicuro. Dopo la tua build web (e prima di caricare o richiedere una build nativa), esegui:

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

OTA significa che i pacchetti nativi corrispondono a quelli già live sul canale. native significa che un plugin, una versione Capacitor o una dipendenza nativa è cambiata — un bundle OTA non può aggiornare quei dispositivi in modo sicuro.

releaseType compara i metadati dei pacchetti nativi (Capacitor/plugin Cordova e versioni). Non not vedi ogni modifica qui ios/, android/, or capacitor.config.*Gestisci quelle rotte in git per primo, poi utilizza releaseType per compatibilità di dipendenza — gli esempi che seguono fanno entrambi.

See Compatibilità nativa per le regole complete e il manuale bundle compatibility tabella.

Consiglio

Porta ogni pipeline di produzione su releaseType. È più economico che indovinare, e evita di caricare un live update che si blocca sui dispositivi ancora con la versione nativa precedente.

Prerequisites

• l'app Capgo registrata e una chiave API Capgo in segreti di CI come CAPGO_TOKEN
• Live Updates caricamento funzionante (bundle upload — vedi Integrazione CI/CD
• Capgo Credenziali di build in CI se si aspettano lavori nativi — vedi GitHub Azioni o oppure
• Un canale che esiste già e corrisponde alla produzione (gli esempi utilizzano production)
• Un canale che già esiste e corrisponde alla produzione (esempi utilizzano metadata tattica per cui ogni upload può trasportare --auto-min-update-version (one-time):

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

Come dovrebbe funzionare 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. Costruisci gli asset web come di consueto.
2. Se il commit tocca ios/, android/, o capacitor.config.*, forza il percorso nativo.
3. Altrimenti chiedi a Capgo releaseType se il commit è sicuro per OTA.
4. Se OTA, carica con --fail-on-incompatible e --auto-min-update-version.
5. Se nativeEsegui Capgo Build, quindi carica il bundle corrispondente con --auto-min-update-version così il metadati nativi del canale avanzano. Non utilizzare use --fail-on-incompatible per quel upload di base — i nuovi pacchetti nativi dovrebbero differire. Vedi per la FAQ del canale. Esegui __CAPGO_KEEP_0__ Azioni

Sottosezione intitolata “Esegui GitHub Azioni”

.__CAPGO_KEEP_0__/workflows/__CAPGO_KEEP_1__-release.yml releaseType:

/github/workflow/capgo-rilascio.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

Sostituisci com.example.app e collega i segreti di firma come descritto in GitHub Azioni per Capgo Costruzione.

Nota

--fail-on-incompatible appartiene solo al lavoro OTA. Dopo aver messo il canale sulla metadata strategia, mantieni --auto-min-update-version su ogni caricamento (OTA e baseline nativo). Dopo che un binario nativo viene spedito, carica il bundle corrispondente con --auto-min-update-version e senza --fail-on-incompatible così releaseType controlli vedano i nuovi pacchetti nativi.

GitLab CI

GitLab valuta rules quando viene creata la pipeline, quindi ramo con un shell if dentro un lavoro di distribuzione (o generare un) pipeline figlio dinamico se hai bisogno di job di matrice native separati):

.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

Salva CAPGO_TOKEN e Capgo Variabili di firma di build come variabili CI/CD mascherate/protette.

Altre piattaforme CI

Lo stesso processo in tre passaggi funziona ovunque:

Passo	Comando
Verdetto	npx @capgo/cli@latest bundle releaseType APP_ID --channel production
Percorso OTA	npx @capgo/cli@latest bundle upload APP_ID --channel production --fail-on-incompatible --auto-min-update-version
Percorso OTA	npx @capgo/cli@latest build request APP_ID --platform ios (or android) --build-mode release

Mappa l'uscita della shell / stdout nelle condizionali della tua piattaforma (o conserva un unico lavoro con una shell) ifcome GitLab sopra):

• Azure Pipelines — impostare una variabile di output da un passo di script, quindi utilizzarla condition: eq(variables['releaseType'], 'OTA')
• Bitbucket Pipelines — scrivi RELEASE_TYPE=… per $BITBUCKET_PIPELINES_VARIABLES_PATHdichiararlo sotto output-variablese procedere con i passaggi successivi condition: state: RELEASE_TYPE == "OTA" (file artifacts da soli non possono guidare condition)
• CircleCI — when is evaluated at config-compile time, so branch with a runtime shell if o una configurazione dinamica / continuazione, non un valore di workspace in when
• Jenkins — cattura stdout in una variabile di ambiente e utilizza when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Perimetrazioni dei percorsi (Opzionale accelerazione)

Le filtri di percorso sono un'ottimizzazione dei costi, non un sostituto del Capgo check. Preferisci escludere le cartelle dei documenti esclusivamente piuttosto che mantenere una lista di permessi fragile — le costruzioni web spesso dipendono anche da vite.config.*, tsconfig*.json, e file di configurazione del framework:

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

Se utilizzi una lista di permessi, includi ogni input che le costruzioni web e native leggono, non solo src/ e package.json.

Dopo un Verdetto Nativo

Quando CI sceglie la versione nativa:

1. Capgo La costruzione produce binari firmati e può inviare a TestFlight / Play (vedi configurazione).
2. Carica il bundle JS corrispondente con --auto-min-update-version (strategia di metadata) quindi il canale registra i nuovi pacchetti nativi — altrimenti il prossimo commit solo JS ancora restituisce native.
3. Una volta che gli utenti installano il nuovo binario, i commit JavaScript successivi tornano a OTA di nuovo.

Guida correlata

Compatibilità nativa Perché Capgo restituisce OTA vs nativo e come bloccare le upload non desiderate.

Flusso di lavoro del canale nativo + OTA Canali di sviluppo e produzione e quando abbandonare --fail-on-incompatible per una baseline nativa intenzionale.

GitHub Azioni (Capgo Build) Segreti di firma e flussi di costruzione nativi completi.

Eseguire costruzioni da interfaccia utente CI Eseguire una costruzione nativa su richiesta da GitHub, GitLab o Bitbucket.

Avvia costruzioni tramite Webhook Avvia la costruzione di Capgo dall'interfaccia amministrativa o da qualsiasi client HTTP.