flag-publish

flag-publish

GrowthBook の機能フラグのドラフトリビジョンを公開するか、変更を元に戻します。承認が必要な場合（ブロック）とマージコンフリクト（ベースが古い場合）という、よくある2つの失敗モードに加え、変更を破棄して元に戻す方法も含め、公開フロー全体に対応します。

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

ワークフロー

ユーザーの依頼に合った経路を選択します。各経路はレポートで終了します。1つの経路を完了した後、別の経路に進まないでください。

• 公開 → 手順 1 → 2 →（手順 2 が失敗した場合のみ 3a または 3b）→ 6
• 破棄 → 手順 4 → 6
• 元に戻す → 手順 5 → 6

1. リビジョンを特定する

バージョン番号がすでにコンテキストにある場合（このセッションで以前の書き込みスキルから引き継がれている場合）は、先に進み、その番号を直接使用します。

ユーザーがフラグ ID を指定し、バージョンを指定していない場合は、/latest を使用します。

# User's own most recent active draft:
gb-call GET '/api/v2/features/<id>/revisions/latest?mine=true'

# Most recently updated active draft by anyone:
gb-call GET /api/v2/features/<id>/revisions/latest

/latest が 404 を返した場合、このフラグに有効なドラフトはありません。公開するものがないことをユーザーに伝えて終了します。

ドラフトが同時に複数存在する可能性がある場合は、一覧を表示してユーザーに選んでもらいます。

# User's own active drafts:
gb-call GET '/api/v2/features/<id>/revisions?status=all-drafts&mine=true'
# All active drafts:
gb-call GET '/api/v2/features/<id>/revisions?status=all-drafts'

ユーザーがフラグ ID を指定していない場合（セッションが失われた後に戻ってきた場合や、フラグの動作を説明している場合）は、すべての機能を対象に承認済みドラフトを検索します。

# Find all approved drafts the user is involved in:
gb-call GET '/api/v2/flag-revisions?status=approved&mine=true'

一覧の項目が1つの場合は、フラグ ID、リビジョン番号、承認者、変更内容の概要を提示して、ユーザーに確認します。複数ある場合は、すべて表示してユーザーに選んでもらいます。

フラグ ID が不明で、ユーザーが内容からフラグを説明している場合（例：「country = US のルールがあるブール値フラグ」）、ルールの内容で絞り込む API フィルターはありません。そのため、候補となる各リビジョンを取得し、説明と照らし合わせてルールを調べ、公開前にユーザーの確認を得る必要があります。一致していると決めつけないでください。

続行する前に version 番号を記録します。

2. 公開を試みる

echo '{"comment":"<optional summary of the change>"}' \
  | gb-call POST /api/v2/features/<id>/revisions/<version>/publish -

レスポンスに応じて分岐します。

• 2xx → 手順 6（完了）。
• 承認が必要であることを示す本文を伴う 400 → 手順 3a。
• 409 → 手順 3b（マージコンフリクト）。
• その他の 4xx → 処理を中断し、生の本文を提示します。

3a. 承認が必要なブランチ

ドラフトは作成されていますが、組織の承認ポリシーにより公開がブロックされています。手順 1 のリビジョンの status に応じて分岐します。適切な対応はそれぞれ異なります。

pending-review の場合： すでに誰かに承認が依頼されています。待つ以外にすることはありません。

「リビジョン <version> はすでにレビュー待ちです。GrowthBook でチームメイトが承認したら、flag-publish を再実行して完了してください。」 ここで終了します。

approved の場合： リビジョンは承認されていますが、公開はまだ失敗しています。問題はレビューの状態ではなく、トークンまたは組織のバイパス設定にあります。オプション A は省略し、バイパスのオプションのみを提示します。

「リビジョン <version> は承認されていますが、API キーに公開権限がありません。次から選んでください。

A. 組織全体のバイパス — 管理者が Settings → General → Approvals で「REST API always bypasses approval requirements」を有効にします。その後、flag-publish を再実行してください。

B. トークンごとのバイパス — このプロジェクトで bypassApprovalChecks が許可されているロールの Personal Access Token を使用します。GB_API_KEY を更新してから、再実行してください。」

draft または changes-requested の場合： まだレビューは依頼されていません。今すぐ依頼するかどうかを尋ね、UI を開くオプションも提示します。

「このリビジョンを公開するには、組織の承認が必要です。次から選んでください。

A. 標準のレビューフロー（推奨）— 今すぐレビューを依頼します。チームメイトが GrowthBook で承認したら、flag-publish を再実行して完了してください。レビュー担当者が確認できるよう、フラグページを開きますか？

B. UI でレビュー — フラグページを直接開き、そこでレビューを管理します。

C. 組織全体のバイパス — 管理者が Settings → General → Approvals で「REST API always bypasses approval requirements」を有効にします。

D. トークンごとのバイパス — このプロジェクトで bypassApprovalChecks が許可されているロールの Personal Access Token を使用します。GB_API_KEY を更新してから、再実行してください。」

ユーザーが UI を開くことを希望する場合（オプション B、または A と併せて）：

# macOS:
open <host>/features/<flag-id>?v=<version>
# Linux:
xdg-open <host>/features/<flag-id>?v=<version>

ユーザーが A を選んだ場合は、レビューを依頼して終了します。

echo '{"comment":"Requesting review — re-run flag-publish after approval"}' \
  | gb-call POST /api/v2/features/<id>/revisions/<version>/request-review -

submit-review は実行しないでください。自己承認はサーバー側で拒否されます。

ユーザーがバイパスのオプションを選んだ場合は、1 行のメモを添えて終了します。既存のドラフトは、再試行時に新しい権限を適用します。

ポリシーを回避するために、黙って再試行したり、エラーを無視したり、ドラフトを破棄して作り直したりしないでください。

3b. マージコンフリクトの分岐

409 は、ドラフトのベースリビジョンが古くなっていることを意味します。ドラフト作成後にライブフラグが変更されています。ドラフト自体は残っており、公開前にリベースする必要があるだけです。

複雑なコンフリクトには、GrowthBook の UI を使うのがおすすめです。差分が左右に並んで表示され、ユーザーはフィールドごとに視覚的に解決できます。UI を開くか確認してください。

「<flag-id> でマージコンフリクトが発生しています。GrowthBook の UI で解決しますか（複雑な変更にはこちらがおすすめです）、それともここで一緒に進めますか？」

UI を使う場合：

# macOS:
open <host>/features/<flag-id>?v=<version>
# Linux:
xdg-open <host>/features/<flag-id>?v=<version>

GB_API_URL の api. を app. に置き換えて <host> を導き出します（クラウドのデフォルト：https://app.growthbook.io）。ここで止め、UI でリベースしてから、完了後に flag-publish を再実行するようユーザーに伝えてください。

API 経由で解決する場合は、続行します。

ステップ 3b-i：コンフリクトの詳細を取得します。

gb-call GET /api/v2/features/<id>/revisions/<version>/merge-status

{ hasConflicts: true, conflicts: [...] } が返されます。各コンフリクトオブジェクトには、次の情報が含まれます。

• key — 競合したフィールド（defaultValue、rules、prerequisites、environmentsEnabled.<envId>）
• name — フィールドの人間が読みやすいラベル
• revision — ドラフトの値
• live — 現在のライブ値
• base — ドラフト作成時の値

コンフリクトキーとして、defaultValue、rules、prerequisites、environmentsEnabled.<envId>（例：environmentsEnabled.production）が考えられます。

ステップ 3b-ii：各コンフリクトについて、両方のバージョンをユーザーに提示し、どちらを残すか尋ねます。

ドラフトのバージョンには revision フィールドを、現在のライブバージョンには live を使います。両方を並べて提示し、次のどちらにするか尋ねます。

• 上書き — ドラフトのバージョンを残します（revision を優先し、同時に行われたライブの変更は破棄されます）。
• 破棄 — ライブバージョンを残します（live を優先し、このフィールドに対するドラフトの変更は破棄されます）。

**コンフリクトを自動で解決してはいけません。**どのバージョンが正しいかは、それぞれ人間が判断する必要があります。

ステップ 3b-iii：リベースします。

echo '{"conflictResolutions":{"defaultValue":"overwrite","rules":"discard"}}' \
  | gb-call POST /api/v2/features/<id>/revisions/<version>/rebase -

コンフリクトがあったフィールドのキーのみを含めてください。

ステップ 3b-iv：公開を再試行します。 ステップ 2 に戻ります。リベース中に新たなコンフリクトが発生しない限り（まれです）、リベース後のドラフトは問題なく公開されるはずです。

4. 破棄の手順（ドラフトを完全に破棄する）

続行する前に、明確に確認してください。

「<flag-id> のリビジョン <version> を破棄しますか？このドラフトに含まれる保留中の変更はすべて完全に失われます。」

gb-call POST /api/v2/features/<id>/revisions/<version>/discard

終端状態でないステータスであれば実行できます。draft、pending-review、approved、changes-requested はすべて直接破棄できます。サーバーによってブロックされるのは published と discarded のみです。

5. 復元の手順（過去に公開されたリビジョンに戻す）

最近公開されたリビジョンを一覧表示し、復元先をユーザーに選んでもらいます。

gb-call GET '/api/v2/features/<id>/revisions?status=published&limit=10'

意図を確認します。「フラグ <id> をリビジョン <N> の状態（公開日：<date>）に復元しますか？」

echo '{"strategy":"draft"}' \
  | gb-call POST /api/v2/features/<id>/revisions/<target-version>/revert -

strategy: "draft" は、過去の状態で新しいドラフトを作成します。ユーザーは flag-publish を通じて内容を確認してから公開します。これがデフォルトで推奨される方法です。

strategy: "publish" は、作成と同時に公開します。ユーザーが即時ロールバックを明示的に求めた場合にのみ、この方法を提示してください。組織の承認設定は引き続き適用されます。

6. 結果の報告

• フラグ ID と結果（公開／承認リクエスト／破棄／復元）。
• リビジョンのバージョンと新しいステータス（公開レスポンスから取得）。
• UI リンク — GB_API_URL の api. を app. に置き換えて <host> を導き出します（クラウドのデフォルト：https://app.growthbook.io）。次のリンクを開くか表示します：<host>/features/<flag-id>?v=<version>。
• 公開の場合：任意でフラグの完全な状態を取得し、現在ライブになっている内容を要約します。

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

  表示する内容：有効になっている環境、デフォルト値、有効なルールの簡潔な要約。ユーザーが急いでいる場合は、この呼び出しを省略してください。UI リンクから全体を確認できます。

ガードレール

• 409 はマージコンフリクトであり、一時的なエラーではありません。 むやみに再試行しないでください。再試行しても失敗し続けます。
• 自動でリベースしないでください。 各コンフリクトフィールドには、人間による判断が必要です。すべて「上書き」と推測すると、チームメイトによる同時進行の変更を気付かないうちに破棄する可能性があります。
• マージコンフリクトを回避するために、ドラフトを破棄しないでください。 ドラフトにはユーザーの作業内容が含まれています。代わりに、リベースを支援してください。
• サーバー側で自己承認がブロックされます。 ドラフトを作成したユーザーがステップ 3a で承認しようとすると失敗します。別のレビュアーが必要です。
• リベースが成功しても、ドラフトのステータスは draft のままです。 明示的に再度公開してください。リベースしても自動では公開されません。
• 破棄は取り消せません。 ドラフトは復元できません。呼び出す前に確認してください。
• revert の strategy: "publish" はレビューを迂回します。 組織の承認設定によっては、引き続き承認が必要になる場合があります。デフォルトでは "draft" 戦略を使用し、ユーザーが即時のロールバックを明示的に希望した場合にのみ "publish" を提示してください。
• コンフリクト解決キーは完全一致の文字列です。 環境レベルの切り替えでは、キーは environmentsEnabled.<envId>（例：environmentsEnabled.production）です。conflictResolutions に文字列全体を含めてください。
• 承認が必要な 400 と権限エラーの 403 は異なります。 承認を示す本文を含む 400 は、ポリシーゲートが意図どおりに機能していることを意味します。403 は、トークンに必要な権限がまったくない可能性があります。エラー本文に承認への言及がない場合は、GB_API_KEY の権限を確認してください。

使用するエンドポイント

• GET /api/v2/features/:id/revisions — ドラフト選択用にリビジョンを一覧表示します
• GET /api/v2/features/:id/revisions/latest — 最新のドラフトを取得します
• POST /api/v2/features/:id/revisions/:version/publish （本文：省略可能なコメント）
• GET /api/v2/features/:id/revisions/:version/merge-status
• POST /api/v2/features/:id/revisions/:version/rebase （本文：{ conflictResolutions: { key: "overwrite"|"discard" } }）
• POST /api/v2/features/:id/revisions/:version/request-review （承認必須のブランチのみ）
• POST /api/v2/features/:id/revisions/:version/discard
• POST /api/v2/features/:id/revisions/:version/revert （本文：{ strategy: "draft"|"publish" }）

引き継ぎ

• flag-review — 承認ワークフロー用（ステップ 3a で実行）
• flag-revisions — 公開前にドラフトを一覧表示して確認するためのもの