flag-ramp

flag-ramp

GrowthBook のフィーチャーフラグルール用に、複数ステップの段階的なロールアウトスケジュールを作成・管理します。ロールアウトスケジュールでは、ステップ間に定められた待機時間を設けながら、ルールのトラフィック対象範囲を段階的に拡大（または縮小）します。ステップは手動（オペレーターが進める）または時間制限付き（所定の時間が経過すると自動的に進む）にできます。

すべての API 呼び出しは、同梱のヘルパー ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call を経由します。環境変数に GB_API_KEY を設定するか、/growthbook:gb-setup によって ~/.config/growthbook/.env に書き込む必要があります。

ロールアウトスケジュールの仕組み

ロールアウトスケジュールは、フィーチャーフラグの特定のルールに紐付けられます。公開すると、ロールアウトはすぐに実行を開始します。明示的に startDate を設定しない限り、自動的な遅延はありません（startDate を設定することはまれで、多くのチームでは公開後に GrowthBook の UI から手動でロールアウトを開始します）。

各ステップでは、スケジュールによってアクション（通常は coverage を変更するルールへのパッチ）が適用されます。ステップの後は次のようになります。

• ステップに interval（秒）が設定されている場合、その時間が経過すると自動的に次のステップに進みます。
• interval が null の場合、チームメンバーが UI から手動で次のステップに進めるまで、その状態を維持します。

すべてのステップが完了すると、endActions が適用されます（通常は coverage を 1.0 に設定します）。ロールアウトが途中でロールバックされると、startActions が適用されます（ロールアウト前の状態に戻します）。

ロールアウトスケジュールは、ドラフトリビジョンに rampActions として設定され、公開時にアトミックに実行されます。

ワークフロー

パス A — 既存のルールにロールアウトスケジュールを作成する

1. ルールを特定します。

gb-call GET /api/v2/features/<flag-id>

ルール一覧を表示します。ユーザーがロールアウトしたい force または rollout ルールの ID を取得します。現在の coverage を確認します。

2. ユーザーとロールアウトのステップを設計します。

次の内容を確認します。

• 開始時の coverage（例：0.05 = 5%）
• ステップの進行（例：5% → 25% → 50% → 100%）
• 各ステップの待機時間：自動的に次へ進む場合は秒数（例：86400 = 1 日）、手動で進めるまで待機する場合は null

承認待ちステップ：ロールアウトが進む前に人間の承認が必要なステップには、holdConditions: { "requiresApproval": true } を追加します。承認は常に最後のゲートです。ステップに interval も設定されている場合は、まずタイマーが終了し、その後、明示的な承認呼び出しを待ちます。時間要素のない手動ゲートは { "interval": null, "holdConditions": { "requiresApproval": true } } です。組み合わせの例：

• 1 日間待機してから承認を要求する：{ "interval": 86400, "holdConditions": { "requiresApproval": true } }
• 時間の待機なしで承認のみを要求する：{ "interval": null, "holdConditions": { "requiresApproval": true } }

interval 経過後に API から承認を送信する方法については、パス D を参照してください。

startActions は、ルールの現在の coverage（手順 1 で取得）と一致させる必要があります。これは、ロールバック時にロールアウトが復元する状態です。

3. ロールアウトスケジュールのペイロードを作成します。

{
  "startActions": [
    { "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 0 } }
  ],
  "steps": [
    {
      "interval": 86400,
      "actions": [{ "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 0.1 } }]
    },
    {
      "interval": 86400,
      "holdConditions": { "requiresApproval": true },
      "actions": [{ "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 0.5 } }]
    }
  ],
  "endActions": [
    { "targetType": "feature-rule", "targetId": "<rule-id>", "patch": { "coverage": 1.0 } }
  ]
}

startActions = ロールアウトの開始時に適用され、ロールバック時に復元される状態です。ロールアウト開始前のルールの**現在の coverage**に設定します。通常、新しいルールでは 0 です。 endActions = すべてのステップ完了後の最終状態です（通常は coverage 100%）。

ロールアウトにガードレール指標のモニタリングを追加するには、monitoringConfig ブロックと各ステップの "monitored": true を追加します。flag-monitoring を参照してください。

ユーザーから明示的な要望がない限り、startDate と cutoffDate は省略してください。ガードレールを参照してください。

4. ドラフトを介してロールアウトスケジュールをルールに関連付けます。

echo '<payload>' \
  | gb-call PUT /api/v2/features/<flag-id>/revisions/new/rules/<rule-id>/ramp-schedule -

返された version を記録します。ロールアウトスケジュールはドラフト上の rampAction として設定され、ドラフトを公開すると有効になります。

5. flag-publish に引き継ぎます。

パス B — ルールとロールアウトスケジュールを一度に作成する

ルールとロールアウトを同時に作成する場合は、まず使用可能な hashAttribute 候補を取得します（ロールアウトルールでは必須です）。

gb-call GET '/api/v1/attributes?projectId=<flag-project-id>'

ルールの value を、フィーチャーフラグのフェッチ時に取得した valueType と照合して検証します。その後、次を送信します。

echo '{
  "rule": {
    "type": "rollout",
    "value": "<on-value>",
    "coverage": 0.05,
    "hashAttribute": "<hash-attr-id>",
    "enabled": true,
    "allEnvironments": false,
    "environments": ["<env-id>"]
  },
  "rampSchedule": {
    "steps": [
      {
        "interval": 86400,
        "actions": [{ "targetType": "feature-rule", "targetId": "new", "patch": { "coverage": 0.05 } }]
      },
      {
        "interval": 86400,
        "actions": [{ "targetType": "feature-rule", "targetId": "new", "patch": { "coverage": 0.25 } }]
      },
      {
        "interval": 86400,
        "actions": [{ "targetType": "feature-rule", "targetId": "new", "patch": { "coverage": 1.0 } }]
      }
    ],
    "startActions": [{ "targetType": "feature-rule", "targetId": "new", "patch": { "coverage": 0.0 } }],
    "endActions": [{ "targetType": "feature-rule", "targetId": "new", "patch": { "coverage": 1.0 } }]
  }
}' | gb-call POST /api/v2/features/<flag-id>/revisions/new/rules -

ロールアウトアクションのプレースホルダーとして "targetId": "new" を使用します。サーバーが作成時に実際のルール ID に置き換えます。

パス C — ルールからランプスケジュールを削除する

gb-call DELETE /api/v2/features/<flag-id>/revisions/new/rules/<rule-id>/ramp-schedule

これにより、ドラフトに detach ランプアクションがステージングされます。ドラフトの公開時に、稼働中のスケジュールが削除されます。ルールのカバレッジは、スケジュールが最後に設定した値のままになります。

パス D — 稼働中のランプを管理する（公開後）

アクションを実行する前に、ランプの進捗を全体的に確認できるよう、ユーザーに機能ページを開くよう提案してください。UI にはスケジュールの状態、ステップのタイムライン、メトリクスの健全性が表示されますが、API から返されるのは生の値のみです。

# macOS:
open <host>/features/<flag-id>
# Linux:
xdg-open <host>/features/<flag-id>

その後、API ベースで管理するには、フラグのルールにあるランプスケジュール ID（ルールの rampScheduleId フィールド）を取得するか、検索してください。

gb-call GET '/api/v1/ramp-schedules?featureId=<flag-id>'
# or more precisely:
gb-call GET '/api/v1/ramp-schedules?ruleId=<rule-id>'

ステータスを確認する：

gb-call GET /api/v1/ramp-schedules/<rs-id>/status

返される情報：現在のステップインデックス、decision（"advance" / "hold" / "rollback" / "waiting"）、健全性シグナル、およびステップが承認待ちかどうかです。

ランプを開始する（自動で開始されていない場合）：

gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/start

承認待ちステップを承認する（インターバル経過後）：

gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/approve-step

インターバルがまだ経過していない場合や、ほかに保留中の状態がある場合は 400 が返されます。先に /status をポーリングし、ステップが承認待ちのときにのみ承認してください。

次のステップに進む（すべての保留を無視します。CI パイプラインや強制的なオーバーライドで使用します）：

echo '{}' | gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/advance -
# Force past an unsatisfied approval gate (requires canBypassApprovalChecks permission):
echo '{"force":true}' | gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/advance -

一時停止／再開：

gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/pause
gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/resume

ロールバックする（startActions の状態を復元し、ステータスを rolled-back にします）：

echo '{"reason":"<description>"}' | gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/rollback -

すぐに完了する（残りのステップをスキップし、endActions を適用します）：

gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/complete

ロールバック後に再開する：

gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/restart
# then start again:
gb-call POST /api/v1/ramp-schedules/<rs-id>/actions/start

緊急キルスイッチ（ロールバックより高速）：flag-toggle でフラグ環境を無効にします。ランプスケジュール ID がなくても、すべてのルールを即座に停止できます。

ガードレール

• ドラフトのバージョンを引き継ぎます。 このセッションで前回の書き込みスキルからバージョン番号を引き継いでいる場合は、new ではなく、その番号を明示的に使用してください。新しく開始する場合は new を使用します。
• ランプスケジュールを適用できるのは force ルールと rollout ルールのみです。 experiment-ref ルールや safe-rollout ルールでは機能しません。
• startActions は、ランプ開始前のルールのカバレッジと一致している必要があります。 ステップ 1 で値を取得し、ロールバック時の状態として使用してください。ランプ開始前のルールの値が 0 でない限り、既定値として 0 を使用しないでください。
• インターバルが null のステップは、UI で手動で進めるまで停止します。 人の判断が必要なチェックポイントに便利です。インターバルが設定されたステップは自動で進みます。
• startDate は省略可能です。省略した場合、公開時にランプがすぐに開始されます。ユーザーが特に開始を遅らせたいと希望する場合のみ、指定するか確認してください。多くのチームでは、公開の成功を確認してから手動で開始する方法を好みます。
• cutoffDate は限定的な安全策です。 ユーザーから尋ねられた場合のみ説明してください。期限を過ぎるとランプが自動でロールバックされます。既定では含めないでください。
• ステップのカバレッジパッチは 0～1 の範囲内である必要があります。 サーバーは公開時にこれを検証します。
• 対象環境が有効になっていることを確認してください。 対象環境でフラグが無効になっていると、ランプは何も実行しません。その場合は警告し、まず flag-toggle を使うよう案内してください。
• 監視対象のランプ（ガードレールメトリクス、自動ロールバックシグナル）には、flag-monitoring を使用してください。
• ランプアクションはドラフトにステージングされます。 公開するまで変更は適用されません。ドラフトが破棄された場合、ランプは作成されません。
• 1 つのルールにつき、ランプスケジュールは 1 つです。 新しいスケジュールを追加すると、既存のスケジュールが置き換えられます。

使用するエンドポイント

ドラフト（公開前）：

• GET /api/v2/features/:id — フラグと現在のルールを取得
• PUT /api/v2/features/:id/revisions/new/rules/:ruleId/ramp-schedule — ドラフトに段階的ロールアウトのスケジュールを設定
• DELETE /api/v2/features/:id/revisions/new/rules/:ruleId/ramp-schedule — 段階的ロールアウトの関連付け解除をドラフトに設定
• POST /api/v2/features/:id/revisions/new/rules — インラインの rampSchedule を指定してルールを作成

実行中の段階的ロールアウトの管理：

• GET /api/v1/ramp-schedules — 一覧を取得（featureId、ruleId、status でフィルタリング）
• GET /api/v1/ramp-schedules/:id/status — リアルタイムの健全性と判断を取得
• POST /api/v1/ramp-schedules/:id/actions/start
• POST /api/v1/ramp-schedules/:id/actions/pause
• POST /api/v1/ramp-schedules/:id/actions/resume
• POST /api/v1/ramp-schedules/:id/actions/advance（本文：省略可能な { force: true }）
• POST /api/v1/ramp-schedules/:id/actions/approve-step
• POST /api/v1/ramp-schedules/:id/actions/rollback（本文：{ reason: string }）
• POST /api/v1/ramp-schedules/:id/actions/restart
• POST /api/v1/ramp-schedules/:id/actions/complete

引き継ぎ先

• flag-monitoring — 段階的ロールアウトにガードレール指標と自動監視シグナルを追加する場合
• flag-targeting — 段階的ロールアウトを設定する前に、ルールのターゲティング条件を設定する場合
• flag-toggle — 段階的ロールアウトを直ちに停止する必要がある場合の緊急キルスイッチ
• flag-publish — ドラフトを公開して段階的ロールアウトを有効にする場合