flag-publish

flag-publish

将 GrowthBook 功能标记草稿修订版发布上线，或撤销更改。处理完整的发布流程，包括两种常见失败情况——需要审批（受阻）和合并冲突（基准已过期）——以及应急选项：丢弃和还原。

所有 API 调用都通过捆绑的辅助工具执行：${CLAUDE_PLUGIN_ROOT}/scripts/gb-call。需要在环境中设置 GB_API_KEY，或由 /growthbook:gb-setup 将其写入 ~/.config/growthbook/.env。

工作流

选择与用户请求相符的路径。每条路径都以报告步骤结束——完成后不要继续进入其他路径。

• 发布 → 步骤 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'

如果列表中只有一项，向用户展示功能标记 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——服务端会拒绝自我审批。

如果用户选择绕过选项，则用一句话说明后停止。现有草稿会在重试时应用新的权限。

不要静默重试、忽略错误，或为规避策略而丢弃并重新创建。

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 — 发布前列出并检查草稿