Scegli automaticamente l'aggiornamento live o la costruzione nativa

La maggior parte delle rilasci Capacitor sono JavaScript-only e dovrebbero essere inviati come un aggiornamento live. Alcune modifiche toccano il code nativo e richiedono un nuovo binario da code Build Costruzione di Capgo. Questa guida mostra come fare in modo che le GitHub Actions, GitLab CI o qualsiasi altra piattaforma CI/CD scelgano la strada corretta con ogni push — senza che un essere umano decida.

La Decisione

Capgo già sa quale strada è sicura. Dopo la tua costruzione web (e prima di caricare o richiedere una costruzione 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à disponibili sul canale. native significa che è stato modificato un plugin, una versione Capacitor o una dipendenza nativa — un pacchetto OTA non può aggiornare quei dispositivi in modo sicuro.

releaseType compara metadati dei pacchetti nativi (Capacitor/plugin di Cordova e versioni). Non vede ogni modifica sotto , o ios/, android/Piazzare questi percorsi in git prima, quindi utilizzare capacitor.config.*per la compatibilità delle dipendenze — gli esempi che seguono fanno entrambe. releaseType vede ogni modifica sotto

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

Suggerimento

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

Requisiti

• l'app Capgo registrata e una Capgo __CAPGO_KEEP_1__ chiave Capgo API key In segreto CI come CAPGO_TOKEN
• Aggiornamenti in tempo reale caricano funzionano (bundle upload) — vedi Integrazione CI/CD
• Capgo Credenziali di costruzione in CI se si aspetta di lavorare con job nativi — vedi GitHub Azioni o Perché scegliere Capgo?
• Creditenziali production)
• Un canale che esiste già e corrisponde alla produzione (esempi utilizzano metadata Canale sul --auto-min-update-version tattica in modo che ogni caricamento possa trasportare

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

Come dovrebbe funzionare il flusso di lavoro

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 la via nativa.
3. Altrimenti chiedi a Capgo releaseType se il commit è sicuro per OTA.
4. Se OTA, caricare con --fail-on-incompatible e --auto-min-update-version.
5. Se native, esegui Capgo Build, caricare quindi il pacchetto corrispondente con --auto-min-update-version così il metadata nativo del canale avanzerà. Non utilizzare quella caricata di base — i nuovi pacchetti nativi dovrebbero differire. Vedi --fail-on-incompatible Flusso di lavoro del canale nativo + OTA per la FAQ del livello del canale. __CAPGO_KEEP_0__ Azioni

Sezione intitolata “GitHub Azioni”

Un flusso di lavoro che blocca le vie native, quindi si dirama su 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

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 strategia, mantieni metadata su ogni upload (OTA e baseline nativa). Dopo che un binario nativo è stato inviato, invia il pacchetto corrispondente con --auto-min-update-version e senza --auto-min-update-version Copia --fail-on-incompatible in seguito releaseType verifica i nuovi pacchetti nativi.

GitLab CI

GitLab valuta rules quando viene creata la pipeline, quindi ramo con un shell if all'interno di un lavoro di distribuzione (o generare un pipeline figlio dinamico se hai bisogno di job di matrice nativa 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 le variabili di firma di build come variabili CI/CD mascherate/protette.

Altre piattaforme CI

I tre stessi passaggi funzionano 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 nativo	npx @capgo/cli@latest build request APP_ID --platform ios (o android) --build-mode release

Mappa l'uscita della shell / stdout nei condizionali della tua piattaforma (o conserva un unico lavoro con una shell if, come GitLab sopra):

• Azure Pipelines — impostare una variabile di output da un passaggio di script, quindi utilizzare condition: eq(variables['releaseType'], 'OTA')
• Bitbucket Pipelines — scrivere RELEASE_TYPE=… per $BITBUCKET_PIPELINES_VARIABLES_PATHdichiararlo sotto output-variablese procedere con i passaggi successivi con condition: state: RELEASE_TYPE == "OTA" (gli artefatti di file da soli non possono guidare condition)
• CircleCI — when viene valutato al tempo di compilazione della configurazione, quindi procedere con un shell di runtime if o una configurazione dinamica / continuazione, non un valore di workspace in when
• Jenkins — cattura la stdout in una variabile di ambiente e utilizza when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Filtri per percorsi (Optimizzazione della velocità facoltativa)

I filtri per percorsi sono un'ottimizzazione dei costi, non un sostituto del controllo Capgo. Preferisci escludere i percorsi dei documenti esclusivamente piuttosto che mantenere una lista di concessione fragile — le costruzioni web spesso dipendono anche dai file di configurazione del framework: vite.config.*, tsconfig*.json, e i file di configurazione del framework:

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

Se utilizzi una lista di concessione invece, includi ogni input che le tue 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. Inviare il bundle JS corrispondente con --auto-min-update-version (strategia di metadati) in modo che il canale registri i nuovi pacchetti nativi — altrimenti il prossimo commit solo JS torna 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 sbagliate.

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

GitHub Azioni (Capgo Costruzione) Segreti di firma e workflow di costruzione nativa completa.

Avvia costruzioni dalla UI di CI Esegui una costruzione nativa su richiesta da GitHub, GitLab o Bitbucket.

Avvia costruzioni tramite Webhook Avvia costruzione Capgo da un pannello di amministrazione o qualsiasi client HTTP.