プログレッシブ・ロールアウト

インストール手順とこのプラグインの完全なMarkdownガイドを含むセットアップ用プロンプトをコピーします。

Progressive rolloutを使用すると、チャンネルの 安定したフォールバックを 維持したまま、特定の ロールアウト対象へ 制御された一部のデバイスに配信できます。ほとんどのプロダクションユーザーはstableを使い続けます。ロールアウト対象のグループのみが、以下の操作を行うまで候補となるアップデートを受け取ります。 ロールアウトを完了 または ロールアウトをロールバック.

Capgo チャンネルのProgressive rolloutコントロール — この **段階的なロールアウト** チャンネルのInformationタブには、以下が表示されます： **ロールアウト対象** と **安定版フォールバック**、パーセンテージ設定、およびロールアウト操作。

プログレッシブ・ロールアウトの仕組み（エンドツーエンド）

各チャンネルでは、同時に2つのbundleリンクを持つことができます：

コンソール上のラベル	API / CLI	配信対象
安定版フォールバック	安定版のbundle (`version` に Channels POST)	そのチャンネル内の全デバイスのうち、ロールアウト対象外のデバイスが対象となります。
ロールアウト対象	ロールアウト対象 (`rolloutVersion` / `rollout_version`)	ロールアウトが有効かつ一時停止中でない場合、Capgo がランダムに選出した有効かつ一時停止中でない状態。

アップデート確認時の挙動

デバイスは、自身のチャンネルに対して Capgo にアップデートを確認します。
ロールアウトが無効、またはターゲットが設定されていない場合、Capgo は 安定版フォールバック.
ロールアウトが有効と 一時停止中、すでにコホートに含まれているデバイスは ロールアウト対象; それ以外のユーザーには 安定版が配信されます.
ロールアウトが有効かつ一時停止されていない場合、Capgo はこのデバイスがロールアウト対象のコホートに含まれているかを確認します：
- コホートに含まれる場合 → ロールアウト対象
- コホートに含まれない場合 → 安定版

Capgo は対象となる各デバイスに対してランダムに決定を行い、デバイスIDとロールアウトIDのハッシュを使用してその結果をキャッシュします。これにより、コホートが 固定（sticky） され、アップデートの確認ごとに再判定されることなく、設定されたキャッシュ期間中維持されます。

ロールアウトを有効にする

ロールアウトには、まず安定したフォールバックが必要です。ダッシュボードでロールアウトの対象を選択する前に、安定したbundleを割り当ててください。パブリックチャンネル APIを使用する場合、既存のチャンネルから提供できます version と rolloutVersion を同じPOSTリクエスト内で。

配信を開始するには：

以下を設定します ロールアウト対象 (または bundle を upload/割り当て — 詳細は bundle の upload と割り当て).
以下の パーセンテージ を選択して パーセンテージを適用.
をクリックして ロールアウトを有効化.

ロールアウトを有効化するまで、対象やパーセンテージを設定してもデバイスへの配信内容は変更されません。

パーセンテージの変更

コンソールでパーセンテージを編集し、 適用する割合 をクリックして保存します。Capgo は、可能な限り既存の決定を維持します：

パーセンテージを増やす場合 — すでに選択されているデバイスはそのまま維持され、未選択のデバイスからランダムにサブセットが追加されます。
パーセンテージを減らす場合 — 選択されているコホートからランダムにサブセットが選ばれ、安定したフォールバックに戻ります。
パーセンテージを0%に設定 — 新しいデバイスは選択されません。現在ロールアウト対象となっているデバイスは、無効化、ロールバック、または対象の変更を行うまで、引き続きその対象を受け取ります。
ロールアウトを一時停止 — 新しいデバイスの流入を停止しますが、すでに有効なターゲットを実行中のデバイスはそのまま維持されます。
ロールアウトを無効化 — ロールアウト対象の解決を停止し、アップデートチェックでは stable fallback が使われます。

Bundle のアップロードと割り当て

Channel ではと progressive rollout が設定されている場合、新しいアップロードと bundle リンクは ロールアウト対象 にデフォルトで送られます。 安定版へのフォールバック Stable fallback は、明示的に置き換えない限り変更されません。

rollout設定済みのチャンネルにbundleをアップロードまたはリンクすると、コンソールにタイトル この channel では progressive rollout を使用しています とバナーが表示されます：

このチャンネルへの新規アップロードとbundleリンクは、デフォルトでrollout対象に送られます。Stableは置き換えを選ばない限り変更されません。

bundleの配信先を選択してください：

コンソールの選択肢	ユースケース
Auto（推奨）	デフォルト。以下と同じ： rollout対象 progressive rolloutが設定されている場合は以下と同じ： Stableを置き換えそうでない場合。API と一致します `target: "auto"` および CLI のアップロードに `--stable` または `--rollout`.
rollout対象	候補をリリースします。安定版はそのまま維持されます。
Stableを置き換え	本番環境の安定版を意図的に置き換えます（エスケープハッチ）。

ヒント Progressive が設定されている場合、Auto はロールアウトを使用します API に適用されます target: "auto" および、テストを通過しなかった CLI のアップロードに適用されます --stable または --rollout.

デフォルトのアップロードルーティング

チャネルの状態	デフォルトのアップロード / 割り当て	安定版へのフォールバック	rollout対象
いいえ progressive rollout 設定済み	チャネルに到達	アップロード先に設定済み	該当なし
progressive rollout 設定済み	チャンネルに配信されます	変更なし	アップロードに設定

CLI と API のパス

bundle の配信方法	安定版へのフォールバック	rollout対象	備考
`bundle upload --channel <name>` (追加フラグなし)	ロールアウトチャンネルでは変更なし設定済みロールアウトなしの場合	設定ロールアウトチャネルに	コンソールのデフォルト設定と同じです。
`bundle upload --channel <name> --rollout <percent>`	変更なし	設定; ロールアウト有効そのパーセンテージで	アップロードと有効化をワンステップで。
`bundle upload --channel <name> --stable`	置き換え済み	変更なし	エスケープハッチ — 意図的な安定版への置換。
`bundle upload` といいえ `--channel`	変更なし	変更なし	登録のみ。以下とリンク： `channel set` または API。
コンソールのリンクダイアログ → Auto（推奨）	ロールアウトチャネル上では変更なし	設定ロールアウトチャネル上で	デフォルト設定。
コンソールリンクダイアログ → rollout対象	変更なし	設定	ロールアウト対象を明示的に指定。
コンソールリンクダイアログ → Stableを置き換え	置換済み	変更なし	エスケープハッチ。
PUT `/bundle/` と `target: "auto"`	ロールアウトチャネルに変更なし	設定ロールアウトチャネルに	API のデフォルト。
PUT `/bundle/` と `target: "rollout"`	変更なし	設定	明示的なロールアウト対象。
PUT `/bundle/` と `target: "stable"`	置換済み	変更なし	エスケープハッチ。
`channel set --bundle <version>`	置換済み	変更なし	明示的な安定版の上書き。
`channel set --rollout-bundle <version>` (+ `--rollout-percentage`, `--rollout-enable`)	変更なし	設定または変更済み	アップロードせずにターゲットを設定。
Channels POST `version`	置換済み設定時	変更なし	安定版を明示的に上書きします。
Channels POST `rolloutVersion`	変更なし	設定または変更済み設定時	プログラムによるターゲット割り当て。

CLI の例

ロールアウト設定済みのチャンネルへのデフォルトのアップロード (ロールアウト対象; 安定版は変更なし):

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

アップロードしてロールアウト対象を設定し、5%で有効化:

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

stableを明示的に置き換える:

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

リンクせずにアップロードし、ロールアウトを設定:

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 を明示的なターゲットで割り当て (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/

すでに選択されているデバイスを維持したまま、公開範囲を拡大するには：

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

使用するのは --rollout-percentage-bps パーセント単位よりも細かいステップが必要な場合（例： 50 = 0.5%).

次を参照： channel CLI リファレンスと bundle CLI リファレンスすべてのロールアウトオプションについて。コンソールUXは capgo.app#3313 に実装されています.

Progressive rollout セクション (dashboard)

アプリを開く → チャネル → チャネルを選択 → 情報 → 段階的なロールアウト.

このセクションには以下が表示されます： rollout対象 と 安定版へのフォールバック 2つの bundle リンクについて。 ロールアウト対象を変更 別の候補となるbundleを選択するには、パーセンテージを編集した後、 適用する割合 をクリックして保存してください。

コントロール	機能説明	すでにコホートに含まれているデバイス	新しく対象となるデバイス
ロールアウト対象を変更	設定値 `rolloutVersion`を変更すると、新しいロールアウトIDと新しいコホートが開始されます。チャンネル（デフォルト）にbundleをアップロードまたは割り当てた場合も、ロールアウト対象が設定されます。	デバイスが再度チェックインし、新しい決定ルールに一致するまで、以前のターゲットを維持します。	新しいターゲットに対するパーセンテージに基づいて選択されます。
パーセンテージを適用	入力したパーセンテージを保存します。	増やすと維持され、減らすとランダムなサブセットが外れる可能性があります。	上記のパーセンテージルールに従って、追加または除外されます。
ロールアウトを有効化	設定したターゲットとパーセンテージでロールアウト配信を有効にします。	次回のアップデート確認まで変更は適用されません。	次回のチェックで選択される可能性があります。
ロールアウトを一時停止	新しいデバイスが参加するのを停止します。	ロールアウト対象に留まる	安定したフォールバックを受信次回のチェック時に適用されます。
ロールアウトを再開	一時停止を解除します。	変更なし	次回のチェックで再度選択される可能性があります。
ロールアウトを無効化	ロールアウト対象の解決を停止します。Capgo は全員に stable fallback を使用します。	stable fallback へ移行次回のチェック時に適用されます。	stable fallback を受信します。
ロールアウトを完了 (API: `promoteToStable`; CLI: `--rollout-promote`)	ロールアウト対象を新しい安定版フォールバックに設定し、ロールアウト状態をクリアします。確認者：プログレッシブ・ロールアウトを完了しますか？ — 対象が全員に対して安定版となり、以前の安定版フォールバックが置き換わり、パーセンテージがリセットされます。	安定版フォールバックにする全員に。	完了したバンドルを安定版として受け取ります。
ロールアウトをロールバック (API: `rollback`; CLI: `--rollout-rollback`)	対象をクリアし、ロールアウトを無効化してパーセンテージを0%にリセットし、デバイスを安定版フォールバックに戻します。	安定版のフォールバックに戻る次回のチェック時に適用されます。	stable fallback を受信します。

ターミナルでの操作は一度に一つずつ行ってください（ロールアウトを完了 と ロールアウトをロールバック 単一の 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

ロールアウト対象のbundleを、以下まで保持してください: ロールアウトを完了 または ロールアウトをロールバックstable fallback または rollout の対象としてリンクされている Bundle は、削除できないよう保護されます。

安全なワークフロー

Progressive rollout は、チャンネル全体を一気に切り替えることなく、本番環境で検証できるように設計されています。推奨される手順は以下の通りです：

stable fallback が正常であることを確認します。 これは、ほとんどのユーザーに継続して配信したいバージョンである必要があります。
候補となる Bundle を upload します rollout 設定済みのチャンネルへ（bundle upload --channel <name> が適用される対象 rollout対象 および残りの 安定版へのフォールバック ) または使用して --rollout <small-percent> 同じステップで公開を開始します。
まずはスモールスタートで — 初期の兆候を確認するには1〜5%で十分です。クリックして パーセンテージを適用、次に ロールアウトを有効化。失敗率が急増した際に Capgo に公開を停止させたい場合は、auto-pauseをオンにしてください。
対象を広げる前に、必ずモニタリングを行いましょう。 使用するのは Observe バージョンの健全性を確認し、ログ分析エラーパターンを監視して、チャンネルの履歴タブで設定変更を確認します。ロールアウト対象と安定版のフォールバックを比較し、コホートが健全であることを確認してから、徐々にパーセンテージを引き上げてください。
段階的に増やす — パーセンテージを編集して、 パーセンテージを適用をクリックし、段階的に引き上げます（例：5% → 25% → 50% → 100%）。Capgo により、パーセンテージを引き上げた際も、すでにコホートに含まれているデバイスはそのまま維持されます。
確信が持てたらロールアウトを完了する — 確定 プログレッシブ・ロールアウトを完了しますか？ これにより、候補版が全員にとっての安定したフォールバックになります。
問題が発生した場合は、まずロールアウトを一時停止してください — 調査中の間、新規の適用を停止します。不具合のあるビルドが適用済みのデバイスは、以下を行うまでその状態が維持されます： ロールアウトをロールバック または ロールアウトを無効化.

自動一時停止ポリシー

Capgo は、有効なロールアウトを5分ごとに評価し、失敗シグナルが閾値を超えた際にアクションを実行します。選択されたチャンネルと時間枠におけるロールアウト対象のインストール数と失敗数を測定し、単なる失敗率ではなく Wilson confidence lower bound（ウィルソン信頼区間の下限）を使用して判断します。

自動一時停止はデフォルトで無効です。チャンネルの Information タブ、または channel set:

失敗率の閾値 をベーシスポイント（500 = 5%）で指定します。ポリシーをトリガーするには閾値の設定が必要です。
ウィンドウ 分（デフォルト: 60）。
信頼度 の間 0 と 1 (デフォルト: 0.95).
サンプル数が極端に少ない場合に誤作動を防ぐための、最小試行回数と失敗回数のオプション設定。
クールダウン 分（デフォルト: 60）。繰り返しの実行を防止します。
アクション: pause, rollback、または notify.

pause 新しいロールアウトの公開を停止します。 rollback ターゲットをクリアして安定したフォールバックに戻し、 notify ロールアウトの配信内容は変えずにロールアウトアラートを送信します。

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 とダッシュボードへのアクセス方法

ダッシュボード: app → チャネル → channel → 情報 → 段階的なロールアウト
API チャンネル: パブリックチャンネル API ロールアウト、昇格、ロールバック用
API バンドル割り当て: PUT /bundle/ と target: auto, stableまたは rollout

一般的なチャンネルルーティングとデバイスの優先順位については、チャネルを参照してください。プログレッシブロールアウト外での緊急のバンドル復旧については、 live update のロールバック.