Flag Review

flag-review

Request and submit approval reviews on GrowthBook feature flag draft revisions. Only needed when the org has approval workflows configured — if approvals aren't required, flag-publish handles the full flow without a review step.

Two roles use this skill: the drafter (requests a review, can't self-approve) and the reviewer (submits the review decision).

All API calls go through the bundled helper: ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call. It needs GB_API_KEY set in env or written to ~/.config/growthbook/.env by /growthbook:setup.

Approval flow

draft → [request-review] → pending-review → [approve]           → approved → [publish]
                                           → [request-changes]  → changes-requested → [edit + re-request] → pending-review
                                           → [comment]          → pending-review (status unchanged)

Workflow

Path A — Request review (drafter asking for approval)

1. Resolve the revision. If the user gave a version number, use it. Otherwise try /latest (happy path when one draft exists), then fall back to listing if needed:

``bash gb-call GET /api/v2/features//revisions/latest # or if version is known: gb-call GET /api/v2/features//revisions/ ` Accept draft or changes-requested` status. For any other status, surface it and explain what it means using the status table from flag-revisions.

1. Request review:

``bash echo '{"comment":""}' \ | gb-call POST /api/v2/features//revisions//request-review - ``

Revision moves to pending-review. Tell the user a reviewer needs to approve before it can be published via flag-publish. Remind them that self-approval is not allowed — a different team member must review.

Path B — Submit a review (reviewer acting on a pending-review revision)

1. Identify the revision. A version number alone is not enough — you always need the flag ID too (version numbers are per-flag counters, not globally unique). Collect whichever of these the user has, then query accordingly:

Flag ID + version known → fetch directly: ``bash gb-call GET /api/v2/features//revisions/ ``

Flag ID known, version unknown → list pending-review on that flag: ``bash gb-call GET '/api/v2/features//revisions?status=pending-review' ``

Author email or userId known → filter cross-feature by author: ``bash gb-call GET '/api/v2/flag-revisions?status=pending-review&author=' ``

Author name known but not email → fetch all pending-review revisions and filter client-side on createdBy matching the name: ``bash gb-call GET '/api/v2/flag-revisions?status=pending-review' ` Each revision has a createdBy field (display name or "API"). Filter for entries where createdBy` contains the name the user gave, then confirm with the user before proceeding.

Nothing known → same broad query, show all results and ask the user to identify theirs.

1. For anything non-trivial, offer to open the GrowthBook UI first — the side-by-side diff and approval controls are clearer than text:

``bash # macOS: open /features/?v= # Linux: xdg-open /features/?v= ` Derive from GBAPIURL by replacing api. → app.`. If the reviewer prefers to work in the UI, stop here.

For API-based review, fetch both the revision and the live feature to show a proper before/after diff: ``bash gb-call GET /api/v2/features//revisions/ # draft state gb-call GET /api/v2/features/ # current live state `` Surface: which rules changed (added/edited/removed), defaultValue change, metadata changes, env toggle changes, prerequisites changes — comparing draft fields against the live feature.

1. Ask the reviewer which action they want:

• approve — changes look good, ready to publish
• request-changes — issues found, author needs to update
• comment — feedback only, no status change

1. Submit the review:

``bash echo '{"action":"approve","comment":""}' \ | gb-call POST /api/v2/features//revisions//submit-review - ``

Status transitions:

• approve → approved — tell user to publish via flag-publish
• request-changes → changes-requested — tell reviewer what happens next (author edits, re-requests)
• comment → pending-review unchanged — comment is recorded

Path C — Check review status

If version isn't known, try /latest first:

gb-call GET /api/v2/features//revisions/latest
# or with a known version:
gb-call GET /api/v2/features//revisions/

Report status and what needs to happen next:

| Status | Next step | | --- | --- | | draft | Author requests review when ready | | pending-review | Reviewer submits a decision | | approved | Author publishes via flag-publish | | changes-requested | Author edits draft, then re-requests review |

Guardrails

• Self-approval is blocked server-side. The API rejects a review submitted by the draft's own author. If the user mentions they created the draft, halt before calling submit-review: "You created this draft — a different team member must approve it." Otherwise let the server enforce it and surface the error if it fires.
• Can only request-review on draft or changes-requested status. Surface the actual status if the user tries on anything else.
• Can only submit-review on pending-review status. Surface the actual status if it doesn't match.
• changes-requested is not discarded. The draft still exists; the author edits it and re-requests review via Path A. Don't suggest discarding unless the author explicitly wants to abandon the changes.
• Reset-review-on-changes. If the org has this setting enabled, any edit to an approved draft reverts it to draft. Warn the user if they're about to edit an already-approved revision: "Editing this revision will reset its approval status — you'll need to request review again."
• Approval ≠ publication. An approved draft is not yet live. The author still needs to run flag-publish.
• This skill does not publish. After approval, hand off to flag-publish.

Endpoints used

• GET /api/v2/features/:id/revisions/:version — inspect revision before acting
• GET /api/v2/features/:id/revisions (status filter) — find pending-review revisions for a flag
• GET /api/v2/flag-revisions (status, mine filters) — find pending-review revisions across all flags
• POST /api/v2/features/:id/revisions/:version/request-review (body: optional comment)
• POST /api/v2/features/:id/revisions/:version/submit-review (body: action + optional comment)

Handoffs

• flag-revisions — to list and inspect all open drafts
• flag-publish — after approval, to publish the draft live

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: growthbook
• Source: growthbook/skills
• License: MIT

Install and usage instructions live in the source repository linked above.