Scegli automaticamente l'Aggiornamento in Tempo Reale o la Costruzione Nativa

La maggior parte delle rilasci Capacitor sono solo JavaScript 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 scelga la strada giusta 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 diversa — un bundle OTA non può aggiornare quei dispositivi in modo sicuro.

releaseType compara i metadati dei pacchetti nativi (Capacitor/plugin di Cordova e versioni). Non fa vede ogni modifica sotto , o ios/, android/. Blocca quelle cartelle in git prima, poi utilizza capacitor.config.*per la compatibilità delle dipendenze — gli esempi che seguono fanno entrambe le cose. releaseType Vedi

Copia nel portapenne Compatibilità nativa per le regole complete e il manuale bundle compatibility tabella.

Suggerimento

Sblocca ogni pipeline di produzione su releaseType. È più economico che indovinare, e evita di inviare un aggiornamento live che si blocca sui dispositivi ancora con il binario nativo più vecchio.

Requisiti

• Capgo app registrata e un Capgo API chiave nelle segrete di CI come CAPGO_TOKEN
• Aggiornamenti in tempo reale caricano lavorando (bundle upload) — vedere Integrazione CI/CD
• Capgo Credenziali di costruzione in CI se si aspettano lavori nativi — vedere GitHub Azioni o Costruire credenziali in CI se si aspettano lavori nativi — vedere
• Aggiornamenti in tempo reale caricano lavorando ( production)

) — vedere

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. Aggiornamenti in tempo reale caricano lavorando (
2. If 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, carica il bundle (con --fail-on-incompatible come barriera di sicurezza).
5. Se native, esegui Capgo Build, quindi carica il bundle corrispondente con --auto-min-update-version così il canale avanzerà i metadati nativi (utilizza la strategia dei metadati) Otherwise ask __CAPGO_KEEP_0__ whether the commit is OTA-safe.. Do non utilizzare --fail-on-incompatible per quella caricata di base — i nuovi pacchetti nativi sono destinati a differire.

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

  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: |
          # One-time: channel set production --disable-auto-update metadata
          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 Build.

Nota

--fail-on-incompatible appartiene solo al job OTA. Dopo che viene rilasciato un binario nativo, caricare il bundle corrispondente con --auto-min-update-version così releaseType vedi i nuovi pacchetti nativi.

GitLab CI

GitLab valuta rules quando viene creata la pipeline, quindi utilizza una shell if all'interno di un job di deploy (o genera un pipeline figlio dinamico se hai bisogno di job 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
      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 and Capgo Build signing variables as masked/protected CI/CD variables.

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

Mappa l'uscita della shell / stdout nelle condizionali della tua piattaforma (o mantieni un unico lavoro con una shell if:)

• Azure Pipelines — imposta una variabile di output da un passaggio di script, poi utilizza condition: eq(variables['releaseType'], 'OTA')
• Bitbucket Pipelines — scrivi RELEASE_TYPE=… a $BITBUCKET_PIPELINES_VARIABLES_PATHdeclare output-variablese condition: state: RELEASE_TYPE == "OTA" file artifacts da soli non possono guidare condition)
• CircleCI — when è valutato al tempo di compilazione della configurazione, quindi ramo con un shell di esecuzione in tempo di esecuzione if (o 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 di velocità facoltativa)

Il filtro dei percorsi è un'ottimizzazione di costo, non un sostituto del Capgo check. Preferisci escludere i percorsi dedicati solo 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 tue costruzioni web e native leggono, non solo src/ e package.json.

Dopo un Verdetto Nativo

Quando CI sceglie la versione nativa:

1. Capgo Costruisce file binari firmati e può inviarli su 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 esclusivamente JS ancora restituisce native.
3. Una volta che gli utenti installano il nuovo file binario, i commit successivi esclusivamente JavaScript tornano a OTA di nuovo.

Guide correlate

Compatibilità Nativa Perché Capgo restituisce OTA vs nativo e come bloccare le pubblicazioni non valide.

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 Capgo Costruzione da un dashboard amministrativo o da qualsiasi client HTTP.