Merge Gate Explainer

The Rovo agent in Jira that tells you why a Bitbucket pull request is held and what to do next: gate verdicts with rule numbers, work-item status from the Teamwork Graph, reusable skills.

Comment

Inspiration

A held merge check answers "no". Developers then open the policy, the diff, the reviewers list and Jira to work out "why" and "what now". Release managers ask the opposite question, "is KAN-3 ready to merge?", and have to find the pull requests first. We wanted one place, inside Jira where the work item lives, that answers both with the gate's own reasoning. Build with context: the context is the work item in the Teamwork Graph plus the verdicts the merge check already stored.

What it does

Merge Gate Explainer is a Forge app for Jira with a Rovo agent and two reusable skills. It is the companion of Merge Policy Gate (a separate submission), a Bitbucket Cloud custom merge check that judges pull requests against MERGE-POLICY.md and cites rule numbers.

  • Explain a verdict. "Why is pull request 2 in hanvigo-dev/gate-demo held?" The agent calls the gate's read-only verdict feed, evaluates live, and answers with one line per cited rule (§2.1 Dockerfile is a protected path, §2.2 httpx major bump) and the shortest unblock step (one approval from a non-author releases both, no push needed).
  • Start from the work item. "Which pull requests of KAN-3 are held?" The work-item-pull-requests action reads the work item's status, assignee and linked pull requests from the Teamwork Graph (requestTeamworkGraph with objects(ids) and jiraWorkItemLinkedExternalPullRequests), fetches every pull request the gate evaluated for that key, and re-checks them against the current status so the policy's allowed-status rule (§4.1) is applied with real data.
  • Adopt a policy. The adopt-merge-policy skill returns the starter MERGE-POLICY.md, explains which keys to tune first (protected paths, size limits, Jira requirement) and where to enable the check.
  • Never bypass. The prompt and both skills forbid suggesting that the check be disabled or the policy edited on the source branch; they always point at satisfying the rule or changing the policy on the destination branch through a reviewed pull request.

The unblock-held-pull-request skill ships the rule catalogue (references/rule-catalogue.md), the answer format and the rule-to-action map, so other Rovo agents can reuse it. followUpPrompt generates the next questions a developer or release manager would ask. A Jira Automation template (one Send web request to the verdict feed) comments on a work item moved to a ready status while a pull request is still held, with no code.

How we built it

Forge modules: rovo:agent (prompt as a resource, five conversation starters, followUpPrompt), rovo:skill ×2, action ×6, Forge KVS for the connected feed URL. Scopes: storage:app, read:jira-work, and the read-only Teamwork Graph scopes read:graph:issue:jira, read:graph:issue-status:jira, read:graph:pull-request:external, read:graph:user:atlassian. Egress is limited to the gate's Forge web trigger host. The feed contract is three GET shapes: by pull request, by pull request with live=1&jiraStatus=, and by Jira key.

Challenges we ran into

  • Rovo chat was unavailable on developer sites for everyone during the hackathon; we provisioned a Forge demo site, where the agent, the actions and the graph queries were exercised end to end.
  • The Teamwork Graph docs describe a jiraWorkItem root field that does not exist in the live schema; we introspected the schema, switched to objects(ids) with a union fragment, and learned that operation names must follow the company_operation shape.
  • Missing graph scopes return empty data rather than errors, so every hop (work item, status, pull request, user) needed its own scope.
  • A Forge app cannot hold Bitbucket and Jira scopes at once, which is why the gate publishes a read-only feed and this app consumes it.

Accomplishments that we're proud of

A recorded conversation on the demo site: connect the site to a gate with one UPDATE action, explain PR 2 with rules and next steps, then "Which pull requests of KAN-3 are held, and why?" answered from the Teamwork Graph (statusSource: teamwork-graph) plus the gate's verdicts, with three follow-up suggestions generated from followUpPrompt.

What we learned

Agents are most useful when they are bounded and cite their sources; every answer here quotes rule numbers and comes from a tool result, never from the model's memory.

What's next for Merge Gate Explainer

A release-readiness view per sprint (every work item with its held pull requests), an agentConnector for teams that run their own agents, and surfacing jiraWorkItemLinkedExternalPullRequests results directly once the Bitbucket workspace is linked to the site.

Try it

Install the app on a Jira site with Rovo, open Rovo chat, pick Merge Gate Explainer, and paste the gate's verdict feed URL: Connect this site to the Merge Policy Gate. The verdict feed URL is https://d6c929d9-996c-4661-a715-c6dc155b06e3.hello.atlassian-dev.net/x1/DE6WoDgpgY1h653b7uOxp9qA-KY. Then ask "Why is pull request 2 in hanvigo-dev/gate-demo held?" or "Which pull requests of KAN-3 are held?" (KAN-3 exists on our demo site; on your own site use any key whose branch the gate has evaluated). Judge guide: JUDGES.md in the merge-policy-gate repository.

Share this project:

Updates

Submission history