Rollout bertahap

Progressive rollout menjaga channel fallback stabil tetap aktif sambil mengirim target rollout ke subset perangkat yang terkontrol. Sebagian besar pengguna produksi tetap di versi stabil. Hanya kohort rollout yang menerima kandidat sampai Anda Selesaikan rollout atau Batalkan rollout.

Panduan Rollout bertahap bagian di tab Informasi sebuah channel menampilkan Target rollout dan Fallback stabil, kontrol persentase, dan aksi rollout.

Cara kerja progressive rollout dari awal sampai akhir

Setiap channel dapat memiliki dua tautan bundle secara bersamaan:

Label konsol	API / CLI	Siapa yang menerimanya
Fallback stabil	Bundle stabil (version aktif POST Channels)	Setiap perangkat di channel yang tidak ada di kohort rollout.
Target rollout	Target rollout (rolloutVersion / rollout_version)	Hanya perangkat yang dipilih Capgo secara acak ke dalam cohort rollout saat rollout sedang aktif dan tidak dijeda.

Apa yang terjadi di setiap pengecekan update

1. Perangkat meminta update ke Capgo pada channel-nya.
2. Jika rollout dinonaktifkan, atau tidak ada target, Capgo akan menyajikan fallback stabil.
3. Jika rollout aktif dan dijeda, perangkat yang sudah masuk kohort tetap memakai target rollout; yang lainnya menerima fallback stabil.
4. Jika rollout aktif dan tidak dijeda, Capgo mengecek apakah perangkat ini masuk dalam kohort rollout:
   • Dalam kohort → target rollout.
   • Tidak masuk kohort → fallback stable.

Capgo membuat keputusan acak untuk setiap perangkat yang memenuhi syarat, lalu meng-cache-nya menggunakan hash dari ID perangkat dan ID rollout. Hal ini membuat kohort sticky selama durasi cache yang dikonfigurasi, bukan mengulang proses pada setiap pemeriksaan update.

Sticky tidak berarti permanen

Durasi cache keputusan rollout default adalah 30 hari. Setelah kedaluwarsa, perangkat dapat dipilih kembali. Mengubah target rollout akan membuat ID rollout baru dan memulai kohort baru. Anda dapat mengatur durasi cache dari 60 detik hingga 365 hari.

Aktifkan rollout

Rollout membutuhkan fallback yang stabil terlebih dahulu. Di dashboard, tetapkan bundle yang stabil sebelum memilih target rollout. Dengan Kanal Publik API, channel yang sudah ada dapat menyediakan version dan rolloutVersion dalam request POST yang sama.

Untuk memulai pengiriman:

1. Atur Target rollout (atau upload/assign bundle — lihat Upload dan tetapkan bundle).
2. Pilih persentase dan klik Terapkan persentase.
3. Klik Aktifkan rollout.

Sampai rollout diaktifkan, mengatur target dan persentase tidak mengubah perangkat mana yang menerima update.

Perubahan persentase

Di konsol, edit persentase lalu klik Terapkan persentase untuk menyimpannya. Capgo mempertahankan keputusan yang sudah ada bila memungkinkan:

• Naikkan persentase — perangkat yang sudah terpilih tetap terpilih; hanya subset acak dari perangkat yang sebelumnya tidak terpilih yang ditambahkan.
• Turunkan persentase — subset acak dari kohort terpilih akan kembali ke fallback stabil.
• Atur persentase ke 0% — tidak ada perangkat baru yang dipilih. Perangkat yang sudah menjalankan target rollout aktif akan terus menerimanya sampai Anda menonaktifkan, melakukan roll back, atau mengubah target.
• Jeda rollout — menghentikan perangkat baru masuk, sementara perangkat yang sudah menjalankan target aktif tetap berada di target tersebut.
• Nonaktifkan rollout — menghentikan resolusi target rollout; pemeriksaan update menggunakan fallback stabil.

Upload dan tetapkan bundle

Pada channel dengan progressive rollout dikonfigurasi, upload baru dan tautan bundle dikirim ke target rollout secara default. Fallback stabil tetap tidak berubah kecuali Anda secara eksplisit memilih untuk menggantinya.

Channel ini menggunakan progressive rollout

Saat Anda mengunggah atau menautkan bundle ke channel yang dikonfigurasi untuk rollout, konsol menampilkan judul Channel ini menggunakan progressive rollout dan banner:

Unggahan baru dan tautan bundle di channel ini secara default menuju target rollout. Stable tetap tidak berubah kecuali Anda memilih untuk menggantinya.

Pilih di mana bundle harus ditempatkan:

Pilihan konsol	Kapan digunakan
Auto (direkomendasikan)	Default. Sama dengan Target rollout ketika progressive rollout dikonfigurasi; sama dengan Ganti stable ketika tidak. Cocok dengan API target: "auto" dan CLI uploads tanpa --stable atau --rollout.
Target rollout	Ship kandidat; stable fallback tetap apa adanya.
Ganti stable	Ganti stable produksi secara sengaja (escape hatch).

Hint Auto menggunakan rollout saat progressive dikonfigurasi berlaku untuk API target: "auto" dan untuk upload CLI yang tidak lolos --stable atau --rollout.

Routing upload default

Status channel	Upload / assign default	Fallback stabil	Target rollout
Tidak progressive rollout dikonfigurasi	Masuk ke channel	Ditetapkan ke upload	N/A
Progressive rollout dikonfigurasi	Masuk ke channel	Tidak berubah	Ditetapkan ke upload

Path CLI dan API

Cara Anda merilis bundle	Fallback stabil	Target rollout	Catatan
bundle upload --channel <name> (tanpa flag tambahan)	Tidak berubah di channel rollout; atur ketika tidak ada rollout	Atur di channel rollout	Sesuai default konsol.
bundle upload --channel <name> --rollout <percent>	Tidak berubah	Atur; rollout aktif pada persentase itu	Upload + aktifkan dalam satu langkah.
bundle upload --channel <name> --stable	Diganti	Tidak berubah	Escape hatch — penggantian stabil yang disengaja.
bundle upload dengan Tidak --channel	Tidak berubah	Tidak berubah	Daftar saja; hubungkan dengan channel set atau API.
Dialog link Console → Auto (direkomendasikan)	Tidak berubah di channel rollout	Atur di channel rollout	Pilihan default.
Dialog link Console → Target rollout	Tidak berubah	Atur	Target rollout eksplisit.
Dialog link Console → Ganti stable	Diganti	Tidak berubah	Jalan keluar.
PUT /bundle/ dengan target: "auto"	Tidak berubah di channel rollout	Atur di channel rollout	default API.
PUT /bundle/ dengan target: "rollout"	Tidak berubah	Atur	Target rollout eksplisit.
PUT /bundle/ dengan target: "stable"	Diganti	Tidak berubah	Jalan keluar.
channel set --bundle <version>	Diganti	Tidak berubah	Override stable eksplisit.
channel set --rollout-bundle <version> (+ --rollout-percentage, --rollout-enable)	Tidak berubah	Diatur atau diubah	Atur target tanpa upload.
POST Channels version	Diganti saat diatur	Tidak berubah	Override stable eksplisit.
POST Channels rolloutVersion	Tidak berubah	Diatur atau diubah saat diatur	Penetapan target secara programatik.

Contoh CLI

Upload default pada channel yang dikonfigurasi rollout (target rollout; stable tidak berubah):

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

Upload, atur target rollout, dan aktifkan di 5%:

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

Ganti stable secara eksplisit:

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

Upload tanpa link, lalu konfigurasikan 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 assign dengan target eksplisit (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/

Tingkatkan eksposur tanpa mereset perangkat yang sudah dipilih:

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

Gunakan --rollout-percentage-bps ketika Anda membutuhkan langkah yang lebih halus daripada persentase utuh (misalnya 50 = 0.5%).

Lihat referensi channel CLI dan referensi bundle CLI untuk setiap opsi rollout. Console UX tersedia di capgo.app#3313.

Bagian progressive rollout (dashboard)

Buka aplikasi → Channel → pilih channel → Informasi → Rollout bertahap.

Bagian ini menampilkan Target rollout dan Fallback stabil untuk dua tautan bundle. Gunakan Ubah target rollout untuk memilih kandidat bundle lain. Setelah mengedit persentase, klik Terapkan persentase untuk menyimpannya.

Kontrol	Fungsinya	Perangkat yang sudah ada di kohort	Perangkat baru yang memenuhi syarat
Ubah target rollout	Menetapkan rolloutVersion. Mengubahnya akan memulai ID rollout baru dan cohort baru. Mengunggah atau menetapkan bundle ke channel (default) juga menetapkan target rollout.	Pertahankan target sebelumnya sampai mereka check-in lagi dan cocok dengan aturan keputusan baru.	Dipilih berdasarkan persentase terhadap target baru.
Terapkan persentase	Menyimpan persentase yang Anda masukkan.	Dipertahankan saat dinaikkan; subset acak mungkin keluar saat diturunkan.	Ditambahkan atau dikecualikan sesuai aturan persentase di atas.
Aktifkan rollout	Mengaktifkan pengiriman rollout untuk target dan persentase yang dikonfigurasi.	Tidak ada perubahan langsung sampai pemeriksaan update berikutnya.	Mungkin dipilih pada pemeriksaan berikutnya.
Jeda rollout	Mencegah perangkat baru masuk.	Tetap pada target rollout.	Menerima fallback stabil pada pengecekan berikutnya.
Lanjutkan rollout	Menghapus status pause.	Tidak berubah.	Bisa terpilih lagi pada pengecekan berikutnya.
Nonaktifkan rollout	Berhenti me-resolve target rollout; Capgo memakai fallback stabil untuk semua orang.	Beralih ke fallback stabil pada pengecekan berikutnya.	Terima stable fallback.
Selesaikan rollout (API: promoteToStable; CLI: --rollout-promote)	Menjadikan target rollout sebagai stable fallback baru, lalu membersihkan status rollout. Dikonfirmasi oleh Selesaikan progressive rollout? — target menjadi stabil untuk semua orang, stable fallback sebelumnya diganti, dan persentase direset.	Menjadi stable fallback untuk semua orang.	Terima bundle yang selesai sebagai stabil.
Batalkan rollout (API: rollback; CLI: --rollout-rollback)	Menghapus target, menonaktifkan rollout, mengatur ulang persentase ke 0%, dan mengembalikan perangkat ke stable fallback.	Kembali ke stable fallback pada pengecekan berikutnya.	Menerima stable fallback.

Gunakan satu aksi terminal pada satu waktu (Selesaikan rollout dan Batalkan rollout tidak dapat digabungkan dalam satu panggilan 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

Biarkan bundle target rollout tetap tersedia sampai Anda Selesaikan rollout atau Batalkan rollout. Bundle yang ditautkan sebagai fallback stabil atau target rollout terlindungi dari penghapusan.

Workflow yang aman

Progressive rollout dirancang agar Anda dapat melakukan validasi di produksi tanpa harus mengganti seluruh channel sekaligus. Urutan praktisnya:

1. Pastikan fallback stabil dalam kondisi sehat. Ini harus merupakan versi yang ingin Anda berikan ke sebagian besar pengguna.
2. Upload kandidat ke channel yang dikonfigurasi untuk rollout (bundle upload --channel <name> masuk ke Target rollout dan membiarkan Fallback stabil sendiri) atau gunakan --rollout <small-percent> untuk mengaktifkan exposure di langkah yang sama.
3. Mulai kecil — 1–5% cukup untuk sinyal awal. Klik Terapkan persentase, lalu Aktifkan rollout. Aktifkan auto-pause jika Anda ingin Capgo menghentikan paparan ketika tingkat kegagalan melonjak.
4. Pantau sebelum memperluas. Gunakan Observe untuk kesehatan versi, Wawasan Log untuk pola error, dan tab channel Riwayat tab untuk perubahan konfigurasi. Bandingkan target rollout dengan fallback stabil; jangan tingkatkan persentase sampai kohort terlihat sehat.
5. Tingkatkan secara bertahap — edit persentase, klik Terapkan persentase, dan tingkatkan secara bertahap (misalnya 5% → 25% → 50% → 100%). Capgo mempertahankan perangkat yang sudah berada di kohort saat Anda meningkatkan persentase.
6. Selesaikan rollout saat yakin — konfirmasi Selesaikan progressive rollout? sehingga kandidat menjadi stable fallback untuk semua orang.
7. Jika ada masalah, Pause rollout terlebih dahulu — menghentikan paparan baru saat Anda menyelidiki. Perangkat yang sudah menggunakan build yang bermasalah akan tetap di sana sampai Anda Batalkan rollout atau Nonaktifkan rollout.

Selesaikan rollout vs Rollback rollout vs Nonaktifkan rollout

Selesaikan rollout saat candidate sudah bagus dan harus menjadi stable fallback untuk semua perangkat. Batalkan rollout saat candidate harus dibuang dan semua perangkat harus kembali ke stable fallback sebelumnya. Nonaktifkan rollout saat Anda ingin menghentikan rollout tetapi tetap memakai stable fallback yang sama tanpa menyelesaikan candidate.

Kebijakan auto-pause

Capgo dapat mengevaluasi rollout yang aktif setiap lima menit dan bertindak saat sinyal kegagalannya melewati threshold Anda. Sistem mengukur instalasi dan kegagalan untuk target rollout di channel dan jendela waktu yang dipilih, lalu menggunakan Wilson confidence lower bound, bukan sekadar raw failure rate.

Auto-pause dinonaktifkan secara default. Konfigurasikan field ini di Informasi tab atau dengan channel set:

• Ambang batas failure rate dalam basis poin (500 = 5%). Ambang batas diperlukan agar kebijakan terpicu.
• Periode dalam menit (default: 60).
• Keyakinan antara 0 dan 1 (default: 0.95).
• Opsional: minimum percobaan dan kegagalan, agar tidak mengambil tindakan berdasarkan sampel kecil.
• Cooldown dalam menit (default: 60), yang mencegah aksi berulang.
• Aksi: pause, rollback, atau notify.

pause menghentikan eksposur rollout baru, rollback menghapus target dan kembali ke fallback stabil, serta notify mengirim alert rollout tanpa mengubah pengiriman rollout.

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 dan entry point dashboard

• Dashboard: app → Channel → channel → Informasi → Rollout bertahap
• Channel API: Kanal Publik API untuk field rollout, promote, dan rollback
• Assign bundle API: PUT /bundle/ dengan target: auto, stable, atau rollout

Untuk routing channel umum dan prioritas perangkat, lihat Channel. Untuk pemulihan bundle darurat di luar progressive rollout, lihat Rollback live update.