Rollout progressivi

Un progressive rollout mantiene il fallback stabile di un canale attivo mentre distribuisce un target di rollout a un sottoinsieme controllato di dispositivi. La maggior parte degli utenti in produzione resta sulla versione stabile. Solo il gruppo di rollout riceve la candidata finché Completa rollout oppure Rollback del rollout.

Il Rollout progressivo la sezione nella scheda Informazioni di un canale mostra Target di rollout e Fallback stabile, i controlli percentuali e le azioni di rollout.

Come funzionano i rollout progressivi dall'inizio alla fine

Ogni canale può avere due link bundle contemporaneamente:

Etichetta console	API / CLI	Chi lo riceve
Fallback stabile	Bundle stabile (version su POST canali)	Ogni dispositivo sul canale che è hai nel cohort di rollout.
Target di rollout	Target di rollout (rolloutVersion / rollout_version)	Solo i dispositivi che Capgo seleziona casualmente nella coorte di rollout, mentre il rollout è abilitato e non in pausa.

Cosa succede a ogni verifica degli aggiornamenti

1. Il dispositivo chiede a Capgo un aggiornamento per il suo canale.
2. Se il rollout è disabilitato, o non c'è un target, Capgo fornisce il fallback stabile.
3. Se il rollout è abilitato e in pausa, i dispositivi già nel coorte mantengono il target del rollout; tutti gli altri ricevono il fallback stabile.
4. Se il rollout è abilitato e non in pausa, Capgo verifica se questo dispositivo è nel coorte del rollout:
   • Nel coorte → target del rollout.
   • Non nel cohort → fallback stabile.

Capgo prende una decisione casuale per ogni dispositivo idoneo, poi la memorizza in cache usando un hash dell'ID del dispositivo e dell'ID del rollout. Questo rende il cohort sticky per la durata della cache configurata, invece di ricalcolare a ogni verifica degli aggiornamenti.

Sticky non significa permanente

La durata predefinita della cache per le decisioni di rollout è di 30 giorni. Dopo la scadenza, un dispositivo può essere selezionato di nuovo. Modificare il target del rollout crea un nuovo ID di rollout e avvia un nuovo cohort. È possibile impostare la durata della cache da 60 secondi a 365 giorni.

Abilita un rollout

Un rollout richiede prima un fallback stabile. Nel dashboard, assegna il bundle stabile prima di scegliere il target del rollout. Con il Canali pubblici API, un canale esistente può fornire version e rolloutVersion nella stessa richiesta POST.

Per avviare la distribuzione:

1. Imposta la Target di rollout (o fare l'upload/assegnare un bundle — vedi Carica e assegna bundle).
2. Scegli una percentuale e clicca Applica percentuale.
3. Clicca su Abilita il rollout.

Finché non attivi il rollout, configurare un target e una percentuale non modifica i dispositivi che ricevono l'aggiornamento.

Variazioni percentuali

Nella console, modifica la percentuale e fai clic su Applica percentuale per salvarla. Capgo preserva le decisioni esistenti quando possibile:

• Aumentare una percentuale — i dispositivi già selezionati restano selezionati; viene aggiunta solo una sottoinsieme casuale di dispositivi precedentemente non selezionati.
• Diminuire una percentuale — un sottoinsieme casuale della coorte selezionata torna al fallback stabile.
• Imposta la percentuale al 0% — nessun nuovo dispositivo viene selezionato. I dispositivi che stanno già eseguendo il target del rollout abilitato continuano a riceverlo finché non lo disattivi, non esegui il rollback o non modifichi il target.
• Sospendi rollout — impedisce a nuovi dispositivi di entrare, mentre i dispositivi che stanno già eseguendo il target abilitato vi rimangono.
• Disabilita rollout — interrompe la risoluzione del target del rollout; i controlli di aggiornamento usano il fallback stabile.

Carica e assegna bundle

Sui canali con con rollout progressivo configurato, i nuovi upload e i link ai bundle vanno al target rollout di default. Fallback stabile rimane invariato, a meno che tu non scelga esplicitamente di sostituirlo.

Questo canale usa il progressive rollout

Quando carichi o colleghi un bundle a un canale configurato per il rollout, la console mostra il titolo Questo canale usa il progressive rollout e il banner:

I nuovi upload e i bundle collegati su questo canale vanno al target del rollout per impostazione predefinita. Stable rimane invariato, a meno che tu non scelga di sostituirlo.

Scegli dove deve finire il bundle:

Scelta dalla console	Quando usarlo
Auto (consigliato)	Default. Uguale a Target di rollout quando il progressive rollout è configurato; uguale a Sostituisci la stable quando non lo è. Corrisponde a API target: "auto" e gli upload di CLI senza --stable oppure --rollout.
Target di rollout	Rilascia un candidato; il fallback stable resta com'è.
Sostituisci la stable	Sostituisci intenzionalmente la stable di produzione (escape hatch).

Il suggerimento Auto usa rollout quando progressive è configurato si applica a API target: "auto" e agli upload di CLI che non superano --stable oppure --rollout.

Routing di upload predefinito

Stato del canale	Upload / assegnazione predefinita	Fallback stabile	Target di rollout
No progressive rollout configurato	Arriva sul canale	Impostato sull'upload	N/D
Progressive rollout configurato	Arriva sul canale	Invariato	Impostato sull'upload

Percorsi CLI e API

Come pubblichi il bundle	Fallback stabile	Target di rollout	Note
bundle upload --channel <name> (senza flag aggiuntivi)	Invariato sui canali di rollout; imposta quando non c'è rollout	Imposta sui canali di rollout	Corrisponde al default della console.
bundle upload --channel <name> --rollout <percent>	Invariato	Imposta; rollout abilitato a quella percentuale	Upload in un solo passo + attivazione.
bundle upload --channel <name> --stable	Sostituito	Invariato	Escape hatch — sostituzione stabile intenzionale.
bundle upload con no --channel	Invariato	Invariato	Registrazione solo; collega con channel set o API.
Dialogo link console → Auto (consigliato)	Invariato sui canali di rollout	Imposta sui canali di rollout	Scelta predefinita.
Dialogo link console → Target di rollout	Invariato	Imposta	Target di rollout esplicito.
Dialog link console → Sostituisci la stable	Sostituito	Invariato	Via di uscita.
PUT /bundle/ con target: "auto"	Invariato sui canali di rollout	Imposta sui canali di rollout	default di API.
PUT /bundle/ con target: "rollout"	Invariato	Imposta	Target di rollout esplicito.
PUT /bundle/ con target: "stable"	Sostituito	Invariato	Via di uscita.
channel set --bundle <version>	Sostituito	Invariato	Override esplicito della versione stable.
channel set --rollout-bundle <version> (+ --rollout-percentage, --rollout-enable)	Invariato	Impostato o modificato	Configura il target senza upload.
POST canali version	Sostituito quando impostato	Invariato	Override esplicito della versione stable.
POST canali rolloutVersion	Invariato	Impostato o modificato quando impostato	Assegnazione programmatica del target.

Esempi di CLI

Upload predefinito su un canale con rollout configurato (target rollout; stable invariato):

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

Upload, impostazione del target rollout e abilitazione al 5%:

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

Sostituisci stable esplicitamente:

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

Upload senza link, poi configura il rollout:

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 assegna con target esplicito (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/

Aumenta l'esposizione senza riassegnare i dispositivi già selezionati:

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

Usa --rollout-percentage-bps quando servono passi più fini rispetto alle percentuali intere (ad esempio 50 = 0.5%).

Guarda il Riferimento CLI del canale e riferimento bundle CLI per ogni opzione di rollout. L'UX della console viene rilasciata in capgo.app#3313.

Sezione progressive rollout (dashboard)

Apri un'app → Canali → scegli il canale → Informazioni → Rollout progressivo.

La sezione mostra Target di rollout e Fallback stabile per i due link del bundle. Usa Cambia target del rollout per scegliere un bundle candidato diverso. Dopo aver modificato la percentuale, clicca su Applica percentuale per salvare.

Controllo	Come funziona	Dispositivi già nella coorte	Nuovi dispositivi idonei
Cambia target del rollout	Impostazioni rolloutVersion. La modifica avvia un nuovo ID di rollout e una nuova coorte. Il caricamento o l'assegnazione di un bundle al canale (default) imposta anche l'obiettivo del rollout.	Mantieni l'obiettivo precedente finché non si riconnettono e corrispondono alle nuove regole di decisione.	Selezionati in base alla percentuale rispetto al nuovo obiettivo.
Applica percentuale	Salva la percentuale inserita.	Conservato in caso di aumento; un sottoinsieme casuale potrebbe essere escluso in caso di diminuzione.	Aggiunti o esclusi in base alle regole di percentuale sopra indicate.
Abilita il rollout	Attiva la distribuzione del rollout per l'obiettivo e la percentuale configurati.	No immediate change until the next update check.	Potrebbe essere selezionato al prossimo controllo.
Sospendi rollout	Impedisce a nuovi dispositivi di entrare.	Rimani sull'obiettivo del rollout.	Ricevi il fallback stabile al prossimo controllo.
Riprendi il rollout	Rimuove la pausa.	Invariato.	Potrebbe essere selezionato di nuovo al prossimo controllo.
Disabilita rollout	Interrompe la risoluzione dell'obiettivo del rollout; Capgo utilizza il fallback stabile per tutti.	Passa al fallback stabile al prossimo controllo.	Riceve il fallback stabile.
Completa rollout (API: promoteToStable; CLI: --rollout-promote)	Rende l'obiettivo del rollout il nuovo fallback stabile, quindi cancella lo stato del rollout. Confermato da Completare il rollout progressivo? — l'obiettivo diventa stabile per tutti, il precedente fallback stabile viene sostituito e la percentuale viene reimpostata.	Diventa fallback stabile per tutti.	Ricevi il bundle completato come stabile.
Rollback del rollout (API: rollback; CLI: --rollout-rollback)	Rimuove il target, disabilita il rollout, reimposta la percentuale al 0% e riporta i dispositivi al fallback stabile.	Ritorna al fallback stabile al prossimo check.	Ricevi il fallback stabile.

Usa un'azione terminale alla volta (Completa rollout e Rollback del rollout non può essere combinato in un'unica chiamata API):

# 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

Mantieni il bundle di destinazione del rollout disponibile finché non Completa rollout oppure Rollback del rollout. I bundle collegati come fallback stabile o come destinazione del rollout sono protetti dalla cancellazione.

Workflow sicuro

Il progressive rollout è progettato per consentirti di validare in produzione senza commutare l'intero canale in una volta sola. Una sequenza pratica:

1. Conferma che il fallback stabile sia funzionante. Dovrebbe essere la versione che sei disposto a continuare a servire alla maggior parte degli utenti.
2. Carica il candidato nel canale configurato per il rollout (bundle upload --channel <name> arriva su Target di rollout e lascia Fallback stabile intatto) oppure usa --rollout <small-percent> per abilitare l'esposizione nello stesso passaggio.
3. Inizia in piccolo — 1–5% è sufficiente per il primo segnale. Clicca su Applica percentuale, poi Abilita il rollout. Attiva l'auto-pause se vuoi che Capgo interrompa l'esposizione in caso di picchi nei tassi di errore.
4. Monitora prima di estendere. Usa Observe per la stabilità della versione, Analisi dei log per i pattern di errore e la tab Cronologia scheda per le modifiche di configurazione. Confronta il target del rollout con il fallback stabile; non aumentare la percentuale finché la coorte non risulta stabile.
5. Aumenta gradualmente — modifica la percentuale, clicca Applica percentuale, e aumenta gradualmente (ad esempio 5% → 25% → 50% → 100%). Capgo mantiene selezionati i dispositivi già presenti nella cohort quando aumenti.
6. Completa il rollout quando sei sicuro — conferma Completare il rollout progressivo? così la candidate diventa il fallback stabile per tutti.
7. Se qualcosa non va, metti prima in pausa il rollout — interrompe l'esposizione di nuovi dispositivi mentre indaghi. I dispositivi già sulla build difettosa restano su quella finché non Rollback del rollout oppure Disabilita rollout.

Completa rollout vs Rollback rollout vs Disabilita rollout

Completa rollout quando il candidato è valido e deve diventare il fallback stabile per tutti i dispositivi. Rollback del rollout quando il candidato deve essere scartato e tutti devono tornare al precedente fallback stabile. Disabilita rollout quando vuoi interrompere il rollout ma mantenere lo stesso fallback stabile senza completare il candidato.

Policy di auto-pausa

Capgo può valutare un rollout attivo ogni cinque minuti e intervenire quando il segnale di errore supera la tua soglia. Misura installazioni e fallimenti per l'obiettivo del rollout nel canale e nella finestra temporale selezionati, utilizzando un limite inferiore di confidenza di Wilson anziché solo il tasso di errore grezzo.

La pausa automatica è disabilitata per impostazione predefinita. Configura questi campi nella scheda Informazioni o con channel set:

• Soglia di tasso di errore in punti base (500 = 5%). È necessaria una soglia perché la policy venga attivata.
• Finestra in minuti (predefinito: 60).
• Confidence tra 0 e 1 (predefinito: 0.95).
• Tentativi e fallimenti minimi opzionali, per evitare di agire su campioni troppo piccoli.
• Cooldown in minuti (default: 60), il che impedisce azioni ripetute.
• Azione: pause, rollback, o notify.

pause interrompe l'esposizione al nuovo rollout, rollback cancella il target e torna al fallback stabile, e notify invia un alert di rollout senza modificare la distribuzione.

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 e punti di accesso alla dashboard

• Dashboard: app → Canali → channel → Informazioni → Rollout progressivo
• Canali API: Canali pubblici API per i campi di rollout, promote e rollback
• Assegnazione bundle API: PUT /bundle/ con target: auto, stable, o rollout

Per il routing dei canali e la precedenza dei dispositivi, consulta Canali. Per il recupero di emergenza di un bundle al di fuori di un rollout progressivo, consulta Rollback di un live update.