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 einen 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 jedes Änderung unter ios/, android/, oder capacitor.config.*. Blockiere diese Pfade in Git zuerst, dann verwenden Sie releaseType für die Abhängigkeitskompatibilität – die folgenden Beispiele tun beides.

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

Tipps

Jede Produktionspipeline sollte auf 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 im CI-Schlüsseln als CAPGO_TOKEN
• Werksweise Live Updates hochladen (bundle upload) — siehe CI/CD-Integration
• Capgo Build-Zugangsdaten in CI, wenn Sie native Jobs erwarten — siehe GitHub Aktionen oder __CAPGO_KEEP_0__
• Kredenziale production)
• Eine bereits existierende und der Produktion entsprechende Kanal (Beispiele verwenden metadata Kanal auf der --auto-min-update-version Strategie, damit jeder Upload eine (einzige):

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 aus, dann hochlade das entsprechende Bundle mit --auto-min-update-version so dass sich die native Metadaten des Kanals weiterentwickeln. Tue nicht dies --fail-on-incompatible für diesen Basisupload — die neuen native Pakete sollen sich unterscheiden. Siehe Native + OTA-Kanal-Workflow für die Kanal-Faq.

GitHub Aktionen

Eine 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 Signaturgeheimnisse wie beschrieben in GitHub Actions für Capgo Build.

Hinweis

--fail-on-incompatible gehört nur auf das OTA-Job. Nachdem Sie den Kanal auf die Strategie gesetzt haben, behalten Sie metadata auf jeden Upload (OTA und native Basis). Nachdem ein natives Binärprogramm verschickt wurde, laden Sie das entsprechende Bundle mit --auto-min-update-version und ohne --auto-min-update-version und ohne --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 Build-Zertifizierungsvariablen als maskiert/geschützte CI/CD-Variablen.

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 Ihres Plattformen (oder behalten Sie ein einzelnes Job mit einer Shell if, wie GitLab oben):

• Azure Pipelines — eine Ausgabeverbinder für einen 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" in einem späteren Schritt mit condition)
• nur Dateiartefakte können nicht die Ausführung steuern — when CircleCI if wird bei der Konfigurationskompilezeit ausgewertet, daher mit einer Laufzeit-Shell when
• oder einer dynamischen Konfiguration / Fortsetzung, nicht mit einem Workspace-Wert in — 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, nicht ein Ersatz für die Capgo-Überprüfung. Vorziehen Sie die Ausschließung von Dokumentationspfaden anstatt die Aufrechterhaltung einer brüchigen Zulassungsliste — Web-Builds hängen oft auch von vite.config.*, tsconfig*.json, und Konfigurationsdateien des 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/Bereich: Capgo-Marketingwebsite. Rolle: Kurze Benutzeroberflächenebene oder Navigationspunkt. Gesehen in: Seite trust.astro. Nachrichtsschlüssel `und` (Und).

Abschnitt mit dem Titel ‘Nach einem Native-Urteil’

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-only Commit wieder zu native.
3. Einmal die Benutzer das neue Binär installiert haben, kehren später JavaScript-only Commits wieder zu OTA zurück.

Wie man sich diese Situation vermeidet?

Verwandte Anleitungen Why Capgo returns OTA vs native and how to block bad uploads.

Wie __CAPGO_KEEP_0__ OTA vs native zurückgibt und wie man schlechte Uploads blockiert. Native + OTA-Kanalablauf

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.