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

Die meisten Capacitor-Versionen sind JavaScript-basiert und sollten als live Aktualisierungversendet 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 eine Erweiterung, eine Capacitor-Version oder eine andere native Abhängigkeit geändert hat – eine OTA-Bundle kann diese Geräte nicht sicher aktualisieren.

releaseType vergleicht native Paketmetadata (Capacitor/Cordova-Erweiterungen und -Versionen). Es tut nicht jede Änderung unter ios/, android/, oder capacitor.config.*. Blockieren Sie diese Pfade in Git zunächst, 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 auf releaseTypeEs ist günstiger als das Raten, und es vermeidet das Versenden eines lebenden 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 native Jobs erwartet werden — siehe GitHub Aktionen oder __CAPGO_KEEP_0__
• __CAPGO_KEEP_0__ production)
• __CAPGO_KEEP_0__ metadata __CAPGO_KEEP_0__ --auto-min-update-version __CAPGO_KEEP_0__

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ührt Capgo Build aus, dann hochladen Sie das entsprechende Bundle mit --auto-min-update-version so dass sich die native Metadaten des Kanals fortsetzen. Führen Sie nicht dazu --fail-on-incompatible benutzen da die neuen native Pakete voneinander abweichen sollen. Siehe Native + OTA-Kanal-Workflow

GitHub Actions

Eines der Workflows, der native Pfade einschränkt, 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 Aktionen 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 metadata Sie auf jeden Upload (OTA und native Basis) bei. 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 sieht man die neuen native Pakete.

GitLab CI

GitLab bewertet rules wenn der Pipeline erstellt wird, also die Verzweigung mit einer Shell if innerhalb eines Deploy-Jobs (oder generiert eine dynamische 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 Build-Signierungszahlungen 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 Ihrer Plattform (oder behalten Sie ein einzelnes Job mit einer Shell if, wie GitLab oben):

• Azure Pipelines — eine Ausgabeverbinder aus einem Skript-Schritt setzen, dann verwenden condition: eq(variables['releaseType'], 'OTA')
• Bitbucket Pipelines — schreiben RELEASE_TYPE=… zu $BITBUCKET_PIPELINES_VARIABLES_PATHerklären Sie es unter output-variables, und später Schritte mit condition: state: RELEASE_TYPE == "OTA" (Dateiartefakte alleine können nicht dazu führen, dass condition)
• CircleCI — when wird bei der Konfigurations-Kompilierzeit ausgewertet, daher mit einer Laufzeit-Shell if (oder dynamische Konfiguration / Fortsetzung), nicht mit einem Workspace-Wert in when
• Jenkins --- die Ausgabe in eine Umgebungsvariable speichern und verwenden when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Wegfilter (Optional Speedup)

Wegfilter sind eine Kostenoptimierung, nicht eine Ersatzlösung für die Capgo-Überprüfung. Vorziehen Sie die Ausschluss von Dokumentationspfaden anstatt die Aufrechterhaltung einer brüchigen 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, sollten Sie alle Eingaben berücksichtigen, die Ihre Web- und Native-Builds lesen, nicht nur src/ und package.json.

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

Abschnitt mit dem Titel ‘Nach einer Native-Verurteilung’

1. Capgo Build produces signed binaries and can submit to TestFlight / Play (see Konfiguration).
2. Laden Sie die entsprechende JS-Bundle hoch, mit --auto-min-update-version so dass das Kanal die neuen native Pakete aufzeichnet — ansonsten kehrt der nächste JS-Commit noch immer zu native.
3. Sobald die Benutzer das neue Binärdatei installieren, kehren später JavaScript-Commit wieder zu OTA wieder.

Zugehörige Anleitungen

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

Native + OTA Kanalworkflow Entwicklungs- und Produktionskanäle und wann man --fail-on-incompatible abschalten sollte, um eine absichtliche native Basis zu erhalten.

GitHub Aktionen (Capgo Build) Signierungsschlü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.