-
-
Pull-request sidebar card: PR 2 held under §2.1 (Dockerfile) and §2.2 (httpx major), each rule with reason and unblock step
-
Repository settings page: MERGE-POLICY.md found on main, parsed rules, starter template, dry-run per open pull request
-
Dry-run from the settings page: PR 2 returns HELD §2.1/§2.2 without touching the pull request
-
PR 3 (520 changed lines) held under §3.4 size limit; §2.1/§2.2/§3.5 shown OK
-
Rovo chat on Jira: the companion agent Merge Gate Explainer explains the same verdict with rule numbers and next steps
Inspiration
On Bitbucket, the pull requests that merge themselves are the ones nobody reads: Dependabot bumps, agent-authored branches, infra tweaks. Branch permissions can require a reviewer, but they cannot say "a patch bump may merge alone, a major bump needs a human, and nobody touches the Dockerfile without one". We wanted a rule set that lives next to the code, is read from the branch being merged into (so a pull request cannot loosen the rules it is judged by), and explains every decision with a rule number instead of a red X. Build with context: the context here is the policy file, the diff, the reviewers and the linked Jira work item, all read at evaluation time.
What it does
Merge Policy Gate is a Forge custom merge check for Bitbucket Cloud. It reads MERGE-POLICY.md from the destination branch and decides pass or held, citing the rules it relied on:
- §2.1 protected paths (CI config, Dockerfiles, the policy file) need a human approval;
- §2.2 dependency files may change automatically only for patch or minor bumps; majors and added or removed packages wait for a human (the gate diffs
package.json,requirements.txt,pyproject.toml,go.mod,Cargo.tomlbetween destination and source commits); - §3.4 size limits; §3.5 drafts never merge; §3.6 defines a human approval (an Approved review by a non-author);
- §4.1 the linked Jira work item key must be in the branch or title when required, optionally in an allowed status.
The verdict shows in three places: the merge-checks card (held: §2.1 …; §2.2 … rules=[…] policy=MERGE-POLICY.md), a pull-request sidebar card (UI Kit) with one row per rule, HELD/OK, the reason and the unblock step, and a repository settings page that shows whether the policy file was found, the parsed rules, the starter template and a Dry-run button for every open pull request. The check re-runs on pushes, reviewer status changes and merges, so an approval releases §2.1/§2.2 without a new push.
The same evaluator is exposed through rovo:mcp as four tools (evaluate-pull-request, last-verdict, explain-rule, policy-template) and a rovo:agent, so a coding agent can ask the gate before it pushes. An open-source skills/merge-policy-gate/SKILL.md tells Claude Code or any MCP client when to call which tool and how to plan a change that passes. A read-only web trigger (the verdict feed) publishes verdicts per pull request and per Jira key, which the companion Jira app Merge Gate Explainer (a separate submission) and a Jira Automation template consume.
How we built it
Forge, Node 24, UI Kit. Modules: bitbucket:mergeCheck (on-code-pushed, on-reviewer-status-changed, on-merge), bitbucket:repoPullRequestCard, bitbucket:repoSettingsMenuPage, rovo:agent, rovo:mcp, action ×4, webtrigger, resolver functions via @forge/resolver. Policy parsing and every rule live in src/policy.js with unit tests (node --test). Verdicts are stored in Forge KVS keyed by repository slug and pull request, plus an index by Jira key. Scopes: read:pullrequest:bitbucket, read:repository:bitbucket, storage:app. The app never writes to the repository and makes no calls outside Atlassian.
Challenges we ran into
- The merge-check event carries UUIDs, the agent and MCP callers pass slugs, and the sidebar card only sees the repository UUID without a workspace scope; everything is normalised to the slug path and the card parses the slugs from its page URL.
@forge/resolveris not a constructor under ESM bundling (makeResolveris).- Bitbucket's Markdown renderer collapses a fence whose info string has a space, so the policy block is marked with a first-line
# merge-policycomment and the parser accepts both spellings. - Required checks are Premium-only on Bitbucket; on Free/Standard the gate is advisory, so the UI says so instead of pretending.
Accomplishments that we're proud of
A live drill on a public repository (hanvigo-dev/gate-demo): PR 2 (Dockerfile + httpx major) held under §2.1/§2.2, PR 3 (520 lines) held under §3.4, PR 1 evaluated on merge and allowed, dry-runs from the settings page, and a coding agent calling the same evaluator over MCP. Everything the judge sees is one evaluator, one stored verdict, one rule numbering.
What we learned
Forge apps cannot hold Bitbucket and Jira scopes at once, which forced a clean two-app design with a documented read-only contract between them. Policy-as-code only works if the policy is read from the destination branch.
What's next for Merge Policy Gate
Marketplace listing (free), per-path reviewer groups, a verdict history view, and support for Bitbucket's required checks on Premium workspaces with a "why required" explanation.
Try it
Judge guide with the 10-minute path and installation steps: JUDGES.md in the repository. Demo pull requests: https://bitbucket.org/hanvigo-dev/gate-demo/pull-requests/2 (held), /3 (held §3.4), /1 (merged, pass).
