Auto wählen Sie Live-Update oder Native-Build

Die meisten Capacitor-Versionen sind JavaScript-basiert und sollten als live Aktualisierung geliefert werden. Einige Änderungen betreffen native code und erfordern ein neues Binärdatei von Capgo Build. Diese Anleitung zeigt, wie man GitHub-Aktionen, GitLab CI oder jede andere CI/CD-Plattform dazu bringen kann, die richtige Route auf jeden Push zu wählen – ohne dass ein Mensch entscheidet.

Die Entscheidung

Capgo weiß bereits, welcher Weg sicher ist. Nach Ihrer Web-Build (und bevor Sie eine native Build hochladen oder anfordern), führen Sie:

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

OTA bezeichnet die native Pakete, die mit dem bereits im Kanal verfügbaren übereinstimmen. native bezeichnet ein Plugin, eine Capacitor-Version oder eine andere native Abhängigkeit geändert wurde – ein OTA-Bundle kann diese Geräte nicht sicher aktualisieren.

releaseType vergleicht native Paketmetadata (Capacitor/Cordova-Plugins und -Versionen). Es tut nicht jede Änderung unter ios/, android/, oder capacitor.config.*. Blockieren Sie diese Pfade in Git zuerst, dann verwenden Sie releaseType für die Abhängigkeitskompatibilität – die folgenden Beispiele tun beides.

Blicken Sie Nativkompatibilität für die vollständigen Regeln und die Anleitung bundle compatibility Tabelle.

Tipps

Jede Produktionspipeline auf Gate einstellen releaseTypeEs ist günstiger als das Raten, und es vermeidet das Versenden eines lebendigen Updates, das auf älteren Geräten mit dem alten nativen Binärdatei abstürzt.

Voraussetzungen

• Capgo Anwendung registriert und ein Capgo __CAPGO_KEEP_1__-Schlüssel Capgo API key in CI-Secrets als CAPGO_TOKEN
• Live Updates hochladen funktioniert (bundle upload) — siehe CI/CD-Integration
• Capgo Build-Zugangsdaten in CI, wenn Sie native Jobs erwarten — siehe GitHub Aktionen oder Zugangsdaten
• Ein Kanal, der bereits existiert und der Produktionskanal entspricht (Beispiele verwenden production)
• Kanal auf der metadata Strategie, damit jeder Upload eine --auto-min-update-version (einmalig):

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

Wie sollte der Pipeline funktionieren?

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. Bauen Sie Web-Assets wie gewohnt.
2. Wenn der Commit die Datei berührt ios/, android/, oder capacitor.config.*, zwingen Sie den nativen Pfad.
3. Ansonsten fragen Sie Capgo releaseType ob der Commit OTA-sicher ist.
4. Wenn OTA, hochladen mit --fail-on-incompatible und --auto-min-update-version.
5. Wenn native, führe Capgo Build durch, dann hochlade das entsprechende Bundle mit --auto-min-update-version so dass sich die native Metadaten des Kanals weiterentwickeln. Führe nicht verwende --fail-on-incompatible das für die Basis-Hochladung — die neuen native Pakete sollen sich unterscheiden. Siehe Native + OTA-Kanal-Workflow für die Kanal-Faq.

GitHub Aktionen

Ein Workflow, der native Pfade sperren soll, dann auf 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

Ersetzen com.example.app und die Signierungsschlüssel wie in GitHub Aktionen für Capgo Build.

Hinweis

--fail-on-incompatible gehört nur zum OTA-Job. Sobald Sie den Kanal auf die Strategie setzen, behalten Sie metadata bei jeder Uploadsitzung (OTA und native Basislinie). Nachdem ein natives Binärprogramm verschickt wurde, laden Sie das entsprechende Bundle mit --auto-min-update-version und ohne --auto-min-update-version Hinweis --fail-on-incompatible später releaseType siehe die neuen native Pakete.

GitLab CI

GitLab bewertet rules wenn der Pipeline erstellt wird, also die Zweig mit einer Shell if innerhalb eines Deploy-Jobs (oder generieren Sie ein dynamisches Kind-Pipeline wenn Sie separate native Matrix-Jobs benötigen):

.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

Speichern CAPGO_TOKEN und Capgo Signierungsoptionen als maskierte/geschützte CI/CD-Variablen erstellen.

Andere CI-Plattformen

Die gleichen drei Schritte funktionieren überall:

Schritt	Befehl
Urteil	npx @capgo/cli@latest bundle releaseType APP_ID --channel production
OTA-Pfad	npx @capgo/cli@latest bundle upload APP_ID --channel production --fail-on-incompatible --auto-min-update-version
Nativpfad	npx @capgo/cli@latest build request APP_ID --platform ios (oder android) --build-mode release

Mappen Sie den Ausgang des Befehls / stdout in die Bedingungen Ihrer Plattform (oder behalten Sie ein einzelnes Job mit einer Shell if, wie GitLab oben):

• Azure Pipelines — eine Ausgabeverbinder aus einer Skript-Schritt setzen, dann verwenden condition: eq(variables['releaseType'], 'OTA')
• Bitbucket Pipelines — schreiben RELEASE_TYPE=… zu $BITBUCKET_PIPELINES_VARIABLES_PATHunter output-variablesund condition: state: RELEASE_TYPE == "OTA" späteren Schritten mit condition)
• CircleCI — when wird bei der Konfigurations-Kompilationszeit ausgewertet, also mit einer Laufzeit-Shell (oder dynamischer Konfiguration / Fortsetzung) und nicht mit einem Workspace-Wert in if Jenkins when
• (Datei-Artikel alleine können nicht die Ausführung von — die Ausgabe in eine Umgebungsvariable speichern und verwenden when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Schaltflächen-Filter (Optional Speedup)

Schaltflächenfilter sind eine Kostenoptimierung, keine Ersatzlösung für die Capgo-Überprüfung. Vorziehen Sie die Ausschließung von Dokumentationspfaden anstatt die Aufrechterhaltung einer fragilen Zulassungsliste — Web-Builds hängen oft auch von vite.config.*, tsconfig*.json, und Konfigurationsdateien von Frameworks ab:

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

Wenn Sie eine Zulassungsliste verwenden, fügen Sie alle Eingaben ein, die Ihre Web- und native Builds lesen, nicht nur src/ und package.json.

context: Seite/Abschnitt: Capgo-Marketingwebsite. Rolle: Kurze Benutzeroberflächenebene oder Navigationspunkt. Gesehen in: Seite trust.astro. Nachrichtsschlüssel `and` (Und).

Abschnitt mit dem Titel “Nach einer Native-Verurteilung”

1. Capgo Build produces signed binaries and can submit to TestFlight / Play (see Einstellungen).
2. Das passende JS-Bundle hochladen mit --auto-min-update-version (Metadatenstrategie) so dass das Kanal die neuen native Pakete aufzeichnet – ansonsten kehrt der nächste JS-Commit wieder native.
3. zurück zu OTA zurück zu

zurück zu

zurück zu Why Capgo returns OTA vs native and how to block bad uploads.

zurück zu zurück zu

GitHub Actions (Capgo Build) Signier-Schlüssel und vollständige native Build-Workflows.

Builds aus der CI-Oberfläche auslösen Führen Sie einen native Build auf Anforderung von GitHub, GitLab oder Bitbucket aus.

Builds über Webhook auslösen Auslösen Sie einen Capgo-Build aus einer Administrationskonsole oder einem beliebigen HTTP-Client.