Wählen Sie Auto Choose Live Update oder Native Build

Die meisten Capacitor-Veröffentlichungen sind JavaScript-only und sollten als ein live updateEinige Änderungen betreffen native code und erfordern ein neues Binärpaket von Capgo Build. Diese Anleitung zeigt, wie man GitHub-Aktionen, GitLab CI oder jede andere CI/CD-Plattform die richtige Route auf jeden Push auswählen können – 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 bedeutet, dass die native Pakete mit dem bereits im Kanal verfügbaren entsprechen. native bedeutet, dass ein Plugin, eine Capacitor-Version oder eine andere native Abhängigkeit geändert wurde – ein über-ein-Netzwerk-Paket kann diese Geräte nicht sicher aktualisieren.

releaseType vergleicht native Paketmetadata (Capacitor/Cordova-Plugins und -Versionen). Es tut nicht jedes Änderung unter ios/, android/, oder capacitor.config.*Git-Verzeichnisse zuvor speichern, dann verwenden releaseType für Abhängigkeitskompatibilität – die folgenden Beispiele tun beides.

Siehe Native Kompatibilität Für die vollständigen Regeln und die Anleitung bundle compatibility Tabelle

Hinweis

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

Voraussetzungen

• Capgo-App registriert und ein Capgo __CAPGO_KEEP_1__-Schlüssel Capgo API Schlüssel Live-Updates-Upload funktioniert ( CAPGO_TOKEN
• Live Updates stellen Daten hoch ("bundle upload — siehe CI/CD-Integration
• Capgo Build-Zugangsdaten in CI, wenn Sie native Jobs erwarten – siehe GitHub Aktionen oder Entweder
• Ein Channel, der bereits existiert und dem Produktionsumfeld entspricht (Beispiele verwenden) production)
• Kanal auf dem metadata strategy, damit jeder Upload eine --auto-min-update-version (one-time):

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

Wie die Pipeline funktionieren sollte

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 das ios/, android/, oder capacitor.config.*, zwingen Sie den nativen Pfad.
3. Ansonsten fragen Sie Capgo releaseType ob die Commit OTA-sicher ist.
4. If OTA, hochladen mit --fail-on-incompatible Wenn --auto-min-update-version.
5. If nativerun Capgo Build, dann laden Sie das entsprechende Bundle hoch --auto-min-update-version so dass sich die native Metadaten des Kanals fortsetzen nicht benutzen --fail-on-incompatible für diese Basisupload — die neuen native Pakete sollen sich unterscheiden. Siehe Native + OTA-Kanal-Workflow für das Channel-Level-Faq

GitHub Aktionen

Eine Workflow, die native Pfade einschränkt, dann auf releaseType:

/github/Arbeitsabläufe/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 verbinden Sie die Signaturgeheimnisse wie in GitHub Aktionen für Capgo Build.

Hinweis

--fail-on-incompatible gehört nur zum OTA-Job. Nachdem Sie den Kanal auf die metadata Strategie gesetzt haben, behalten Sie --auto-min-update-version bei jedem Upload (OTA und native Basis). Nachdem ein natives Binärprogramm verschickt wurde, laden Sie das entsprechende Bundle mit --auto-min-update-version und ohne --fail-on-incompatible damit später releaseType Überprüfungen die neuen native Pakete sehen können.

GitLab CI

GitLab bewertet rules wenn der Pipeline erstellt wird, also Zweig mit einer Shell if inside one deploy job (or generate a dynamisches Kindpipeline 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 Gebäude Signierung Variablen als maskiert/geschützte CI/CD-Variablen speichern.

Sonstige 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
Native-Pfad	npx @capgo/cli@latest build request APP_ID --platform ios oder android) --build-mode release

Mapte die Ausgabe der Shell in Ihre Plattformbedingungen (oder behalten Sie ein einzelnes Job mit einer Shell ifAzure Pipelines

• Azure Pipelines setze eine Ausgabeveränderliche aus einem Skript-Schritt, dann verwende condition: eq(variables['releaseType'], 'OTA')
• Bitbucket Pipelines — schreiben RELEASE_TYPE=… zu $BITBUCKET_PIPELINES_VARIABLES_PATHErkläre es an. output-variablesund verwalte die späteren Schritte mit condition: state: RELEASE_TYPE == "OTA" , und später Schritte mit condition)
• CircleCI — when wird bei der Konfigurationskompilierung ausgewertet, also Zweig mit einem Laufzeit-Shell if am Konfigurations-Kompilationszeitpunkt ausgewertet wird, also mit einer Laufzeit-Shell when
• Jenkins — stdout in eine Umgebungsvariable speichern und verwenden when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Pfade Filtern (Optional Speedup)

Pfadfilter sind eine Kostenoptimierung, kein Ersatz für die Capgo-Überprüfung. Vorziehen Sie die Ausschluss von Dokumentationspfaden anstatt eine fragile Zulassungsliste zu pflegen — Web-Builds hängen oft auch von vite.config.*, tsconfig*.json, und Konfigurationsdateien für das Framework.

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

Wenn Sie eine Zulassungsliste verwenden, sollten Sie alle Eingaben berücksichtigen, die Ihre Web- und Native-Builds lesen, nicht nur src/ und package.json.

Nach einem Native-Urteil

Wenn CI native wählt:

1. Capgo-Build erzeugt signierte Binärdateien und kann bei TestFlight/Play hochladen (siehe Konfiguration).
2. Laden Sie das entsprechende JS-Bundle mit --auto-min-update-version (Metadatenstrategie) so dass der Kanal die neuen Native-Pakete aufzeichnet — ansonsten kehrt der nächste JS-nur-Commit native.
3. Einmal die Benutzer die neue Binärdatei installieren, kehren später JavaScript-only-Commits zu OTA Wieder.

Zugehörige Anleitungen

Native Kompatibilität Weshalb Capgo OTA vs. native zurückgibt und wie man schlechte Uploads blockiert.

Native + OTA-Kanalablauf Entwickler- und Produktionskanäle und wann man --fail-on-incompatible für einen bewussten native Baseline abwerten sollte.

GitHub-Aktionen (Capgo-Build) Signierungsschlüssel und vollständige native Build-Workflows.

Trigger Builds aus der CI-UI Ein native Build auf Abruf aus GitHub, GitLab oder Bitbucket ausführen.

Trigger Builds über Webhook Feuere Capgo Build aus einer Admin-Oberfläche oder einem beliebigen HTTP-Client.