Native + OTA Channel Workflow

Ein typisches Capgo Setup nutzt einen Dev- Channel und einen Produktion Channel. Die CI lädt jedes OTA-Bundle in den devhoch und promotet es dann auf production sobald du bereit bist. Teams fügen oft --fail-on-incompatible hinzu, damit die CI nicht versehentlich ein live update ausliefert, das neue native code benötigt.

Diese Seite beantwortet die Folgefrage: Was tun Sie, wenn Sie absichtlich ein Bundle benötigst, das nicht mit den aktuellen nativen Paketen des Channels kompatibel ist?

Falls du mehr darüber wissen möchtest, warum Capgo native Pakete vergleicht, lies zuerst Native-Kompatibilität. Für einen vollständigen CI-Branch, der automatisch zwischen OTA und Capgo Build unterscheidet, siehe Auto OTA oder Native.

Empfohlenes Channel-Layout

Diese Anleitung setzt voraus, dass die dev und production Channels bereits existieren. Erstelle sie bei Bedarf zuerst:

npx @capgo/cli@latest channel add production com.example.app
npx @capgo/cli@latest channel add dev com.example.app

Channel	Wer erhält es?	Typischer Upload
dev	Interne / QA-Builds	Jeder CI-Push von JS (und gezielte Native Baselines)
production	Store-Nutzer	Nur bei Release-Ready-Status gepusht oder hochgeladen

--fail-on-incompatible ist ein guter Standard für beide Channels bei täglichen OTA-Uploads. Es vergleicht die nativen Pakete im Bundle, das du hochlädst, mit dem Bundle aktuell auf diesem Channel live ist. Bei Abweichungen bricht der Upload mit einem Fehler ab und es wird nichts veröffentlicht.

Tägliche OTA (Flag beibehalten)

Wenn die Änderung nur JavaScript betrifft und die nativen Packages mit dem Channel übereinstimmen:

npx @capgo/cli@latest bundle upload com.example.app \
  --channel production \
  --fail-on-incompatible \
  --auto-min-update-version

--fail-on-incompatible verhindert versehentlichen Native Drift. --auto-min-update-version ist bei jedem Upload erforderlich, sobald der Channel die metadata Strategie nutzt (unten empfohlen). Falls der Channel noch nicht auf metadata ist, kannst du --auto-min-update-version bis zum Wechsel weglassen.

Optionales CI-Gate vor dem Upload:

npx @capgo/cli@latest bundle releaseType com.example.app --channel production
# → OTA      safe to upload with --fail-on-incompatible
# → native   stop; ship a native binary first (see below)

Gezielter Native Bump (Flag einmalig weglassen)

Du kann nicht ein Bundle hochladen, das neue native code benötigt, während --fail-on-incompatible. Das Flag ist genau dafür da, diesen Fall zu blockieren. Wenn ein Plugin, eine Capacitor-Version oder eine andere native Dependency absichtlich geändert wurde:

1. Veröffentliche das passende native Binary (App Store / Play Store oder Capgo Build).
2. Passendes JS-Bundle hochladen ohne --fail-on-incompatible.
3. Bevorzugen --auto-min-update-version mit dem Channel auf der metadata Strategie, damit Geräte mit der alten Binary das neue Bundle erst bekommen, wenn sie die neue App installieren.
4. Nach diesem Baseline-Upload stelle --fail-on-incompatible zurück auf normales OTA CI (und behalte --auto-min-update-version solange der Channel auf metadata).

1. Einmalig pro Channel: Metadata Gating aktivieren

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

   Wiederholen für dev falls dieser Channel auch gezielt native Baselines erhält. Nach dieser Umstellung muss jeder Upload zum Channel Folgendes enthalten: --auto-min-update-version oder --min-update-version.

2. Native Binary ausliefern

   Erstelle und reiche die iOS/Android-App ein, die die neuen Plugins oder nativen Änderungen enthält. Solange Nutzer diese Binary nicht installiert haben, können sie kein Bundle sicher ausführen, das von diesen nativen Paketen abhängt.

3. Lade die passende OTA-Baseline hoch (kein --fail-on-incompatible)

   npx @capgo/cli@latest bundle upload com.example.app \
     --channel production \
     --auto-min-update-version

   Dies registriert die neuen nativen Pakete im Channel. Später bundle releaseType / --fail-on-incompatible nutzen Checks diese Baseline.

4. Geschützte OTA-Uploads fortsetzen

   Nachfolgende JS-only Releases nutzen beide Flags wieder:

   npx @capgo/cli@latest bundle upload com.example.app \
     --channel production \
     --fail-on-incompatible \
     --auto-min-update-version

Tipp

Behandle den Native-Baseline-Upload als einen eigenen CI-Job (oder ein manueller Release-Schritt), nicht als Ausnahme, die man wahllos in den Standard-OTA-Job einstreut. Der Standard-Job sollte immer beibehalten --fail-on-incompatible, und auf einem metadata Channel sollte er auch behalten --auto-min-update-version.

FAQ

Kann ich behalten --fail-on-incompatible und trotzdem ein native-inkompatibles Bundle pushen?

Nein. Wenn die nativen Pakete des Uploads von dem Live-Bundle des Channels abweichen, lässt die Flag den Befehl absichtlich fehlschlagen. Für ein beabsichtigtes Native Update lässt du die Flag bei diesem einen Upload einfach weg (und nutzt --auto-min-update-version wann immer möglich).

Ist ein einmaliger Upload ohne das Flag der richtige Weg?

Ja. Das ist der unterstützte Weg, um die native Baseline des Channels nach dem Release einer neuen Binary zu aktualisieren. Behalte die Flag bei allen anderen OTA-Uploads bei, damit ein versehentlicher Native Drift weiterhin die CI scheitern lässt.

Soll ich hochladen zu dev zuerst, und dann zu production?

Ja, wenn das deinem Prozess entspricht. Wende dieselben Regeln pro Channel an: Der Kompatibilitätscheck prüft gegen das, was im Ziel-Channel live ist. Promote oder erneut hochladen zu production erst nachdem dev sieht gut aus, und nutze einen Native-Baseline-Upload (kein --fail-on-incompatible) auf jedem Channel, auf dem die neuen nativen Packages erfasst sein müssen.

Was passiert, wenn ich das neue native Bundle hochlade, während das Flag noch aktiv ist?

Die CI schlägt fehl und Capgo liefert diesen Upload nicht aus. Das ist das erwartete Ergebnis. Entweder war die Änderung versehentlich (die nativen Packages fixen und als OTA erneut versuchen), oder sie war beabsichtigt (nutze den oben genannten nativen Pfad).

Welches Flag gehört zu welchem Job?

Pfad	Wenn	Upload-Flags
OTA	Nur JS; native Packages passen zum Channel	--fail-on-incompatible + --auto-min-update-version (erforderlich, wenn der Channel aktiv ist metadata)
Native Baseline	Neue native Binary + passendes JS Bundle	Nein --fail-on-incompatible; behalten --auto-min-update-version

Ähnliche Themen

Native-Kompatibilität

Wie Capgo Native Package Drift erkennt und was inkompatibel für Geräte bedeutet.

Auto OTA oder Native

Einbinden bundle releaseType in GitHub Actions oder GitLab, damit die CI den richtigen Pfad nimmt.

Version-Targeting

Channels, Semver-Regeln und die Metadaten-Strategie für Delivery Floors.

CLI: Bundle

Referenz für upload, compatibility, releaseType und zugehörige Flags.

Weiter mit Native + OTA Channel Workflow

Wenn du es nutzt Native + OTA Channel Workflow um Live Updates über Native-Releases hinweg abzusichern, verbinde es mit Native-Kompatibilität für die Regeln zum Paketvergleich, Auto OTA oder Native für das CI-Branching, Version-Targeting für Mindestwerte bei Metadaten und die Capgo CLI Bundle-Referenz für Upload-Flags.