Scegli automaticamente l'aggiornamento in tempo reale 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 azioni, 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 percorso è sicuro. 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, la 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). Ciò non vede ogni modifica sotto ios/, android/, o capacitor.config.*Blocca quelle cartelle in Git prima, poi utilizza releaseType per la compatibilità delle dipendenze — gli esempi che seguono fanno entrambe.

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

Suggerimento

Blocca ogni pipeline di produzione su releaseTypeÈ più economico che indovinare, e evita di inviare un aggiornamento live che causa la caduta dei dispositivi ancora su binario nativo più vecchio.

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) — vedere Integrazione CI/CD
• Capgo Credenziali di costruzione in CI se si aspettano lavori nativi — vedere GitHub Azioni o Per esempio, una canale che esiste già e corrisponde alla produzione (ad esempio utilizza
• Canale sul production)
• tattica in modo che ogni caricamento possa trasportare metadata (una volta): --auto-min-update-version Credenziali

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, eseguire Capgo Build, quindi caricare il bundle corrispondente con --auto-min-update-version così il metadata nativo del canale avanzerà. Non fare utilizzare --fail-on-incompatible per quel caricamento di base — i nuovi pacchetti nativi sono destinati a differire. Vedi Flusso di lavoro del canale nativo + OTA per la FAQ del livello del canale.

GitHub Azioni

Un flusso di lavoro che blocca le vie native, quindi si dirama su releaseType:

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

GitLab CI

GitLab valuta rules quando viene creata la pipeline, quindi il ramo con un shell if all'interno di un lavoro di distribuzione (o generare un pipeline figlio dinamico se hai bisogno di lavori di matrice nativi 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 solo 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' }

Percorsi Filtri (Opcional Speedup)

Il filtro dei percorsi è un'ottimizzazione dei costi, non un sostituto del controllo Capgo. Preferisci escludere i percorsi dedicati ai documenti piuttosto che mantenere una lista di concessione 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 concessione invece, includi ogni input che le costruzioni web e native leggono, non solo src/ e package.json.

Context: Pagina/Area: Sito web di marketing Capgo. Ruolo: Etichetta UI breve o elemento di navigazione. Visualizzato in: pagina trust.astro. Chiave del messaggio `e` (E).

Sottosezione intitolata “Dopo un Verdetto Nativo”

1. Capgo Build produces signed binaries and can submit to TestFlight / Play (see configurazione).
2. Carica 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 ritorna 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.

Ciclo di lavoro del canale nativo + OTA Canali di sviluppo/produttivo 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 da qualsiasi client HTTP.