Progressive Rollouts

Ein progressives Rollout behält den stabilen Fallback eines Kanals bei, während ein separater Rollout-Ziel an eine kontrollierte Teilmenge von Geräten ausgeliefert wird. Die meisten Produktionsnutzer bleiben auf der stabilen Version. Nur die Rollout-Gruppe erhält den Kandidaten, bis Sie Rollout abschließen oder Rollout zurückrollen.

Der Progressiver Rollout Abschnitt auf dem Information-Tab eines Kanals zeigt Rollout-Ziel und Stabiler Fallback, Prozent-Steuerungen und Rollout-Aktionen.

So funktionieren progressive Rollouts von Anfang bis Ende

Jeder Channel kann gleichzeitig über zwei Bundle-Links verfügen:

Console-Label	API / CLI	Wer erhält es
Stabiler Fallback	Stabiles Bundle (version auf Channels POST)	Jedes Gerät im Channel, das es nicht in der Rollout-Kohorte ist.
Rollout-Ziel	Rollout-Ziel (rolloutVersion / rollout_version)	Nur Geräte, die Capgo zufällig in die Rollout-Gruppe auswählt, während der Rollout aktiviert aktiv und nicht pausiert ist.

Was bei jeder Update-Prüfung passiert

1. Das Gerät fragt Capgo nach einem Update auf seinem Channel.
2. Wenn der Rollout deaktiviert, oder es gibt kein Ziel, liefert Capgo das stabilen Fallback.
3. Wenn der Rollout aktiviert und pausiert, behalten Geräte, die bereits in der Kohorte sind, das Rollout-Ziel; alle anderen erhalten den stabilen Fallback.
4. Wenn der Rollout aktiviert und nicht pausiert ist, prüft Capgo, ob dieses Gerät zur Rollout-Kohorte gehört:
   • In der Kohorte → Rollout-Ziel.
   • Nicht in der Kohorte → stabiler Fallback.

Capgo trifft für jedes berechtigte Gerät eine Zufallsentscheidung und cached diese anhand eines Hashes aus Device-ID und Rollout-ID. Das macht die Kohorte sticky für die konfigurierte Cache-Dauer, statt bei jedem Update-Check neu zu würfeln.

Sticky heißt nicht permanent

Die Standard-Cache-Dauer für Rollout-Entscheidungen beträgt 30 Tage. Nach Ablauf kann ein Gerät erneut ausgewählt werden. Das Ändern des Rollout-Targets erzeugt eine neue Rollout-ID und startet eine neue Kohorte. Du kannst die Cache-Dauer zwischen 60 Sekunden und 365 Tagen festlegen.

Rollout aktivieren

Ein Rollout braucht zuerst einen stabilen Fallback. Weise im Dashboard das stabile Bundle zu, bevor du das Rollout-Target wählst. Mit der Öffentliche Channels APIkann ein bestehender Channel bereitstellen version und rolloutVersion in derselben POST-Anfrage.

Um die Auslieferung zu starten:

1. Setze den Rollout-Ziel (oder ein Bundle hochladen/zuteilen – siehe Bundles hochladen und zuweisen).
2. Wähle eine Prozentsatz und klicke auf Prozentsatz anwenden.
3. Klicken Rollout aktivieren.

Solange der Rollout nicht aktiviert ist, ändert die Konfiguration von Zielgruppe und Prozentsatz nichts daran, was Geräte erhalten.

Änderungen am Prozentsatz

Ändere in der Console den Prozentsatz und klicke auf Prozentsatz anwenden um ihn zu speichern. Capgo behält bestehende Entscheidungen nach Möglichkeit bei:

• Prozentsatz erhöhen — bereits ausgewählte Geräte bleiben ausgewählt; es wird nur eine zufällige Teilmenge bisher nicht ausgewählter Geräte hinzugefügt.
• Prozentsatz verringern — eine zufällige Teilmenge der ausgewählten Kohorte kehrt zum stabilen Fallback zurück.
• Prozentsatz auf 0% setzen — keine neuen Geräte werden ausgewählt. Geräte, die bereits das aktivierte Rollout-Ziel ausführen, erhalten dieses weiterhin, bis Sie es deaktivieren, zurückrollen oder ändern.
• Rollout pausieren — verhindert, dass neue Geräte hinzukommen, während Geräte, die bereits das aktivierte Ziel ausführen, darauf bleiben.
• Rollout deaktivieren — stoppt die Auflösung des Rollout-Ziels; Update-Checks verwenden den stabilen Fallback.

Bundles hochladen und zuweisen

Auf Kanälen mit progressives Rollout konfiguriert, gehen neue Uploads und Bundle-Links an den Rollout-Ziel standardmäßig. Stabiler Fallback bleibt unverändert, es sei denn, Sie entscheiden sich ausdrücklich, es zu ersetzen.

Dieser Channel nutzt progressive Rollouts

Wenn du ein Bundle zu einem Channel mit Rollout-Konfiguration hochlädst oder verknüpfst, zeigt die Konsole den Titel Dieser Channel nutzt progressive Rollouts und das Banner an:

Neue Uploads und Bundle-Verknüpfungen in diesem Channel gehen standardmäßig an das Rollout-Ziel. Stable bleibt unverändert, es sei denn, du entscheidest dich dafür, es zu ersetzen.

Wähle aus, wo das Bundle landen soll:

Auswahl in der Konsole	Wann verwenden
Auto (empfohlen)	Standard. Gleich wie Rollout-Ziel wenn ein progressiver Rollout konfiguriert ist; gleich wie Stable ersetzen wenn nicht. Entspricht API target: "auto" und CLI Uploads ohne --stable oder --rollout.
Rollout-Ziel	Kandidat veröffentlichen; stabiler Fallback bleibt unverändert.
Stable ersetzen	Produktionsstabil bewusst ersetzen (Notausgang).

Der Hinweis Auto verwendet Rollout, wenn Progressive konfiguriert ist gilt für API target: "auto" und für CLI-Uploads, die nicht bestehen --stable oder --rollout.

Standard-Upload-Routing

Channel-Status	Standard-Upload / Zuweisung	Stabiler Fallback	Rollout-Ziel
Nein progressiver Rollout konfiguriert	Landet im Channel	Auf den Upload gesetzt	n. v.
Progressives Rollout konfiguriert	Landet im Channel	Unverändert	Auf den Upload gesetzt

CLI- und API-Pfade

Wie du das Bundle auslieferst	Stabiler Fallback	Rollout-Ziel	Notizen
bundle upload --channel <name> (keine zusätzlichen Flags)	Unverändert in Rollout-Channels; Setzen wenn kein Rollout erfolgt	Setzen Sie in Rollout-Channels	Entspricht dem Console-Standard.
bundle upload --channel <name> --rollout <percent>	Unverändert	Setzen Sie; Rollout aktiviert bei diesem Prozentsatz	Upload in einem Schritt + Aktivierung.
bundle upload --channel <name> --stable	Ersetzt	Unverändert	Notausgang – gezielte stabile Ersetzung.
bundle upload mit nein --channel	Unverändert	Unverändert	Nur registrieren; verknüpfen mit channel set oder API.
Console-Link-Dialog → Auto (empfohlen)	Unverändert auf Rollout-Kanälen	Setzen Sie in Rollout-Channels	Standardauswahl.
Console-Link-Dialog → Rollout-Ziel	Unverändert	Setzen Sie	Explizites Rollout-Ziel.
Console-Link-Dialog → Stable ersetzen	Ersetzt	Unverändert	Notausgang.
PUT /bundle/ mit target: "auto"	Unverändert auf Rollout-Kanälen	Setzen Sie in Rollout-Channels	API Standard.
PUT /bundle/ mit target: "rollout"	Unverändert	Setzen Sie	Explizites Rollout-Ziel.
PUT /bundle/ mit target: "stable"	Ersetzt	Unverändert	Notausgang.
channel set --bundle <version>	Ersetzt	Unverändert	Expliziter Stable-Override.
channel set --rollout-bundle <version> (+ --rollout-percentage, --rollout-enable)	Unverändert	Gesetzt oder geändert	Target konfigurieren ohne Upload.
Kanäle POST version	Ersetzt wenn gesetzt	Unverändert	Expliziter Stable-Override.
Kanäle POST rolloutVersion	Unverändert	Gesetzt oder geändert wenn gesetzt	Programmatische Target-Zuweisung.

CLI Beispiele

Standard-Upload auf einem Channel mit Rollout-Konfiguration (Rollout-Ziel; Stable bleibt unverändert):

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production

Upload, Rollout-Ziel festlegen und auf 5 % aktivieren:

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production \
  --rollout 5

Stable explizit ersetzen:

bunx @capgo/cli@latest bundle upload com.example.app \
  --path ./dist \
  --channel production \
  --stable

Hochladen ohne Verknüpfung, dann Rollout konfigurieren:

bunx @capgo/cli@latest bundle upload com.example.app --path ./dist -b 1.3.0

bunx @capgo/cli@latest channel set production com.example.app \
  --rollout-bundle 1.3.0 \
  --rollout-percentage 5 \
  --rollout-enable

API mit explizitem Ziel zuweisen (auto | stable | rollout):

curl -X PUT \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "version_id": 456,
    "channel_id": 789,
    "target": "rollout"
  }' \
  https://api.capgo.app/bundle/

Exposition erhöhen, ohne bereits ausgewählte Geräte neu zuzuweisen:

bunx @capgo/cli@latest channel set production com.example.app \
  --rollout-percentage 25

Nutzt --rollout-percentage-bps wenn du feinere Schritte als ganze Prozentwerte brauchst (zum Beispiel 50 = 0.5%).

Siehe den Channel CLI Referenz und bundle CLI Referenz für jede Rollout-Option. Die Console-UX erscheint in capgo.app#3313.

Progressive-Rollout-Bereich (Dashboard)

App öffnen → Kanäle → Kanal auswählen → Informationen → Progressiver Rollout.

Der Abschnitt zeigt Rollout-Ziel und Stabiler Fallback für die beiden Bundle-Links. Verwende Rollout-Ziel ändern um ein anderes Kandidaten-Bundle auszuwählen. Nach der Änderung des Prozentsatzes klickst du auf Prozentsatz anwenden zum Speichern.

Kontrolle	Was es bewirkt	Geräte, die bereits in der Kohorte sind	Neue berechtigte Geräte
Rollout-Ziel ändern	Legt fest rolloutVersion. Eine Änderung startet eine neue Rollout-ID und eine neue Kohorte. Das Hochladen oder Zuweisen eines Bundles zum Channel (Standard) setzt ebenfalls das Rollout-Ziel.	Das vorherige Ziel beibehalten, bis sie erneut einchecken und den neuen Entscheidungsregeln entsprechen.	Wird anhand des Prozentsatzes für das neue Ziel ausgewählt.
Prozentsatz anwenden	Speichert den eingegebenen Prozentsatz.	Bleibt beim Erhöhen erhalten; beim Verringern kann eine zufällige Teilmenge wegfallen.	Hinzugefügt oder ausgeschlossen gemäß den obigen Prozentregeln.
Rollout aktivieren	Aktiviert die Rollout-Auslieferung für das konfigurierte Ziel und den Prozentsatz.	Keine sofortige Änderung bis zum nächsten Update-Check.	Kann beim nächsten Check ausgewählt werden.
Rollout pausieren	Verhindert den Einstieg neuer Geräte.	Im Rollout-Ziel bleiben.	Stabilen Fallback erhalten beim nächsten Check.
Rollout fortsetzen	Pause aufheben.	Unverändert.	Kann beim nächsten Check erneut ausgewählt werden.
Rollout deaktivieren	Das Rollout-Ziel wird nicht mehr aufgelöst; Capgo nutzt den stabilen Fallback für alle.	Zum stabilen Fallback wechseln beim nächsten Check.	Stabilen Fallback erhalten.
Rollout abschließen (API: promoteToStable; CLI: --rollout-promote)	Macht das Rollout-Ziel zum neuen stabilen Fallback und löscht den Rollout-Status. Bestätigt durch Progressiven Rollout abschließen? — das Ziel wird für alle stabil, der vorherige stabile Fallback wird ersetzt und der Prozentsatz wird zurückgesetzt.	Als stabilen Fallback übernehmen for everyone.	Das fertige Bundle erhalten als stabil.
Rollout zurückrollen (API: rollback; CLI: --rollout-rollback)	Löscht das Ziel, deaktiviert den Rollout, setzt den Prozentsatz auf 0 % zurück und schickt Geräte zum stabilen Fallback zurück.	Zurück zum stabilen Fallback beim nächsten Check.	Stabilen Fallback erhalten.

Nur eine Terminal-Aktion gleichzeitig verwenden (Rollout abschließen und Rollout zurückrollen können nicht in einem einzigen API-Aufruf kombiniert werden):

# Stop adding devices while you investigate
bunx @capgo/cli@latest channel set production com.example.app --rollout-pause

# Allow new devices to enter again
bunx @capgo/cli@latest channel set production com.example.app --rollout-resume

# Complete rollout — candidate becomes stable for everyone
bunx @capgo/cli@latest channel set production com.example.app --rollout-promote

# Rollback rollout — discard candidate and return to stable
bunx @capgo/cli@latest channel set production com.example.app --rollout-rollback

Halte das Rollout-Ziel-Bundle verfügbar, bis du Rollout abschließen oder Rollout zurückrollen. Bundles, die als stabiler Fallback oder Rollout-Ziel verknüpft sind, sind vor dem Löschen geschützt.

Sicherer Workflow

Progressive Rollouts sind so konzipiert, dass du in der Produktion validieren kannst, ohne den gesamten Kanal auf einmal umzustellen. Eine praktische Abfolge:

1. Stabile Fallback-Gesundheit bestätigen. Es sollte die Version sein, die Sie den meisten Nutzern weiterhin bereitstellen möchten.
2. Laden Sie den Kandidaten in den für Rollouts konfigurierten Channel hoch (bundle upload --channel <name> landet auf Rollout-Ziel und lässt Stabiler Fallback unverändert) oder verwenden Sie --rollout <small-percent> um die Exposure im selben Schritt zu aktivieren.
3. Klein anfangen — 1–5 % reichen für das erste Signal aus. Klicken Sie auf Prozentsatz anwenden, dann Rollout aktivieren. Aktiviere Auto-Pause, wenn Capgo die Auslieferung stoppen soll, sobald die Fehlerraten in die Höhe schnellen.
4. Erst überwachen, dann ausweiten. Nutzt Observe für Version Health, Log-Insights für Fehlermuster und den Channel Verlauf Tab für Konfigurationsänderungen. Vergleiche das Rollout-Ziel mit dem stabilen Fallback; erhöhe den Prozentsatz erst, wenn die Kohorte gesund aussieht.
5. Schrittweise erhöhen — ändere den Prozentsatz und klicke Prozentsatz anwenden, und steigere sie schrittweise (z. B. 5 % → 25 % → 50 % → 100 %). Capgo behält die bereits in der Kohorte ausgewählten Geräte bei, wenn du erhöhst.
6. Rollout abschließen, wenn du sicher bist — bestätigen Progressiven Rollout abschließen? damit der Candidate für alle zum stabilen Fallback wird.
7. Falls etwas schiefläuft: Rollout zuerst pausieren — stoppt neue Auslieferungen, während du untersuchst. Geräte, die schon auf dem fehlerhaften Build sind, bleiben dort, bis du Rollout zurückrollen oder Rollout deaktivieren.

Rollout abschließen vs. Rollout zurückrollen vs. Rollout deaktivieren

Rollout abschließen wenn der Candidate gut ist und für alle Geräte der stabile Fallback werden soll. Rollout zurückrollen wenn der Candidate verworfen werden soll und alle zum vorherigen stabilen Fallback zurückkehren sollen. Rollout deaktivieren wenn du den Rollout stoppen, aber denselben stabilen Fallback beibehalten willst, ohne den Candidate abzuschließen.

Auto-pause-Policy

Capgo kann einen aktivierten Rollout alle fünf Minuten auswerten und eingreifen, sobald das Fehlersignal deinen Schwellenwert überschreitet. Gemessen werden Installs und Fehler für das Rollout-Ziel im gewählten Channel und Zeitfenster; bewertet wird dabei mit einer unteren Wilson-Konfidenzgrenze statt nur mit der rohen Failure-Rate.

Auto-pause ist standardmäßig deaktiviert. Konfiguriere diese Felder in den Channel-Einstellungen: Informationen Tab oder mit channel set:

• Fehlerraten-Schwellenwert in Basispunkten (500 = 5 %). Ein Schwellenwert ist erforderlich, damit die Policy ausgelöst wird.
• Zeitfenster in Minuten (Standard: 60).
• Konfidenz zwischen 0 und 1 (Standard: 0.95).
• Optionale Mindestanzahl an Versuchen und Fehlschlägen, um Reaktionen auf zu kleine Stichproben zu vermeiden.
• Cooldown in Minuten (Standard: 60), was wiederholte Aktionen verhindert.
• Aktion: pause, rollback, oder notify.

pause stoppt den Rollout für neue Nutzer, rollback löscht das Ziel und kehrt zum stabilen Fallback zurück, und notify sendet einen Rollout-Alert, ohne die Rollout-Auslieferung zu ändern.

bunx @capgo/cli@latest channel set production com.example.app \
  --auto-pause-enabled \
  --auto-pause-failure-rate-bps 500 \
  --auto-pause-window-minutes 60 \
  --auto-pause-confidence 0.95 \
  --auto-pause-min-attempts 100 \
  --auto-pause-min-failures 5 \
  --auto-pause-action pause \
  --auto-pause-cooldown-minutes 120

API und Dashboard-Einstiegspunkte

• Dashboard: App → Kanäle → Channel → Informationen → Progressiver Rollout
• Kanäle API: Öffentliche Channels API für Rollout-Felder, Promote und Rollback
• Bundle-Zuweisung API: PUT /bundle/ mit target: auto, stable, oder rollout

Für allgemeines Channel-Routing und Gerätepriorität siehe Kanäle. Für die Notfallwiederherstellung von Bundles außerhalb eines Progressive Rollouts siehe Rollback eines live update.