Live Update oder Native Build automatisch auswählen
Kopiere einen Setup-Prompt mit den Installationsschritten und dem vollständigen Markdown-Guide für dieses Plugin.
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.
Die Entscheidung
Abschnitt mit dem Titel „Die Entscheidung“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:
npx @capgo/cli@latest bundle releaseType com.example.app --channel production# → OTA ship with bundle upload# → native ship with Capgo BuildOTA 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.
Voraussetzungen
Abschnitt: „Voraussetzungen“- 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
metadataStrategie, damit jeder Upload--auto-min-update-version(einmalig):
npx @capgo/cli@latest channel set production com.example.app --disable-auto-update metadataSo sollte die Pipeline funktionieren
Abschnitt mit dem Titel „So sollte die 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]
- Web-Assets wie gewohnt bauen.
- Wenn der Commit Änderungen an
ios/,android/, odercapacitor.config.*berührt, erzwingen Sie den nativen Pfad. - Andernfalls fragen Sie Capgo
releaseTypeab, ob der Commit OTA-sicher ist. - Wenn
OTA, laden Sie mit--fail-on-incompatibleund--auto-min-update-version. - Wenn
native, Capgo Build ausführen und anschließend das passende Bundle hochladen mit--auto-min-update-versionso dass die nativen Metadaten des Channels aktualisiert werden. Do es nicht mit--fail-on-incompatiblefür diesen Baseline-Upload – die neuen nativen Pakete sollen sich unterscheiden. Siehe Native- + OTA-Channel-Workflow für die FAQ auf Channel-Ebene.
GitHub Aktionen
Abschnitt mit dem Titel „GitHub Actions“Ein Workflow, der native Pfade prüft und dann auf releaseType:
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-versionErsetze com.example.app und die Signierungsgeheimnisse wie in GitHub Actions für Capgo Build.
GitLab CI
Abschnitt mit dem Titel „GitLab CI“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):
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: - mainSpeichere CAPGO_TOKEN und Capgo Build-Signing-Variablen als maskierte/geschützte CI/CD-Variablen.
Andere CI-Plattformen
Abschnitt mit dem Titel „Andere CI-Plattformen“Die gleichen drei Schritte funktionieren überall:
| Schritt | Befehl |
|---|---|
| Fazit | 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 |
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 unteroutput-variables, und verzweige in späteren Schritten mitcondition: state: RELEASE_TYPE == "OTA"(Datei-Artefakte allein können nicht steuerncondition) - CircleCI —
whenwird zur Konfigurations-Kompilierzeit ausgewertet, verzweige also mit einer Runtime-Shellif(oder dynamischer Konfiguration / Fortsetzung), nicht mit einem Workspace-Wert inwhen - Jenkins — fange stdout in einer Umgebungsvariable ab und verwende
when { environment name: 'RELEASE_TYPE', value: 'OTA' }
Pfad-Filter (Optionale Beschleunigung)
Abschnitt mit dem Titel „Pfad-Filter (Optionale Beschleunigung)“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.
Nach einem Native Verdict
Abschnitt mit dem Titel „Nach einem Native Verdict“Wenn die CI Native wählt:
- Capgo Build erstellt signierte Binaries und kann sie bei TestFlight / Play einreichen (siehe Konfiguration).
- 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 weiterhinnative. - Sobald Nutzer die neue Binary installiert haben, kehren spätere JavaScript-only Commits zu
OTAerneut aus.