Zum Inhalt springen

Live Update oder Native Build automatisch auswählen

Die meisten Capacitor-Releases bestehen nur aus JavaScript und sollten als live update. Einige Änderungen betreffen nativen code und erfordern ein neues Binary von Capgo Build. Dieser Guide zeigt, wie GitHub Actions, GitLab CI oder jede andere CI/CD-Plattform bei jedem Push den richtigen Pfad wählt – ganz ohne manuelles Eingreifen.

Capgo weiß bereits, welcher Pfad sicher ist. Führe nach deinem Web-Build (und vor dem Upload oder der Anfrage eines Native Build) folgenden Befehl aus:

Terminalfenster
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 nativen Packages mit dem übereinstimmen, was bereits live auf dem Channel ist. native bedeutet, dass sich ein Plugin, die Capacitor-Version oder eine andere native Dependency geändert hat – ein Over-the-Air-Bundle allein kann diese Geräte nicht sicher aktualisieren.

releaseType vergleicht Metadaten des nativen Pakets (Capacitor/Cordova-Plugins und Versionen). Es es nicht sieht jede Änderung unter ios/, android/, oder capacitor.config.*. Sperre diese Pfade zuerst in Git, dann nutze releaseType für die Abhängigkeitskompatibilität – die Beispiele unten tun beides.

Siehe Native-Kompatibilität für die vollständigen Regeln und die manuelle bundle compatibility Tabelle.

  • Capgo App registriert und ein Capgo API Key ein in den CI-Secrets als CAPGO_TOKEN
  • Live Updates Upload funktioniert (bundle upload) — siehe CI/CD-Integration
  • Capgo Build-Credentials in der CI, wenn du Native Jobs erwartest — siehe GitHub Aktionen oder Anmeldedaten
  • Ein Channel, der bereits existiert und mit der Produktion übereinstimmt (die Beispiele verwenden production)
  • Channel auf der metadata Strategie, damit jeder Upload --auto-min-update-version (einmalig):
Terminalfenster
npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadata
  1. Web-Assets wie gewohnt bauen.
  2. Wenn der Commit Änderungen an ios/, android/, oder capacitor.config.*berührt, erzwingen Sie den nativen Pfad.
  3. Andernfalls fragen Sie Capgo releaseType ab, ob der Commit OTA-sicher ist.
  4. Wenn OTA, laden Sie mit --fail-on-incompatible und --auto-min-update-version.
  5. Wenn native, Capgo Build ausführen und anschließend das passende Bundle hochladen mit --auto-min-update-version so dass die nativen Metadaten des Channels aktualisiert werden. Do es nicht mit --fail-on-incompatible für diesen Baseline-Upload – die neuen nativen Pakete sollen sich unterscheiden. Siehe Native- + OTA-Channel-Workflow für die FAQ auf Channel-Ebene.

Ein Workflow, der native Pfade prüft und 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

Ersetze com.example.app und die Signierungsgeheimnisse wie in GitHub Actions für Capgo Build.

GitLab wertet rules bei der Erstellung der Pipeline aus, also Branch mit einem Shell- if in einem Deploy-Job (oder generiere eine dynamische Child-Pipeline falls du separate native Matrix-Jobs brauchst):

.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

Speichere CAPGO_TOKEN und Capgo Build-Signing-Variablen als maskierte/geschützte CI/CD-Variablen.

Die gleichen drei Schritte funktionieren überall:

SchrittBefehl
Fazitnpx @capgo/cli@latest bundle releaseType APP_ID --channel production
OTA-Pfadnpx @capgo/cli@latest bundle upload APP_ID --channel production --fail-on-incompatible --auto-min-update-version
Native-Pfadnpx @capgo/cli@latest build request APP_ID --platform ios (oder android) --build-mode release

Bilde den Shell-Exit / stdout auf die Conditionals deiner Plattform ab (oder behalte einen einzelnen Job mit einer Shell if, wie oben bei GitLab):

  • Azure Pipelines — setze eine Output-Variable aus einem Script-Step und nutze sie dann condition: eq(variables['releaseType'], 'OTA')
  • Bitbucket Pipelines — schreibe RELEASE_TYPE=… zu $BITBUCKET_PIPELINES_VARIABLES_PATH, deklariere sie unter output-variables, und verzweige in späteren Schritten mit condition: state: RELEASE_TYPE == "OTA" (Datei-Artefakte allein können nicht steuern condition)
  • CircleCI — when wird zur Konfigurations-Kompilierzeit ausgewertet, verzweige also mit einer Runtime-Shell if (oder dynamischer Konfiguration / Fortsetzung), nicht mit einem Workspace-Wert in when
  • Jenkins — fange stdout in einer Umgebungsvariable ab und verwende when { environment name: 'RELEASE_TYPE', value: 'OTA' }

Pfad-Filter sind eine Kostenoptimierung, kein Ersatz für die Capgo-Prüfung. Es ist besser, nur Dokumentations-Pfade auszuschließen, als eine fragile Allowlist zu pflegen – Web-Builds hängen oft auch ab von vite.config.*, tsconfig*.json, und Framework-Konfigurationsdateien:

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

Wenn du stattdessen eine Allowlist verwendest, nimm alle Inputs auf, die deine Web- und Native Builds lesen, nicht nur src/ und package.json.

Wenn die CI Native wählt:

  1. Capgo Build erstellt signierte Binaries und kann sie bei TestFlight / Play einreichen (siehe Konfiguration).
  2. Lade das passende JS-Bundle mit --auto-min-update-version (Metadata-Strategie) hoch, damit der Channel die neuen Native-Packages registriert – andernfalls liefert der nächste JS-only Commit weiterhin native.
  3. Sobald Nutzer die neue Binary installiert haben, kehren spätere JavaScript-only Commits zu OTA erneut aus.