Guide · safe AI delivery
How to auto-merge AI pull requests safely
Letting an agent open a pull request is easy. Letting it merge its own work needs a gate that checks more than a green test run. This guide follows the four checks Orbi makes before an AI-written PR can land.
THE PROBLEM
Why “CI is green, merge it” is not enough
An agent can open a PR whose tests pass while the tests miss an acceptance detail. If green CI is the only decision, nobody checks whether the diff satisfies the Issue, whether it was reviewed independently, or whether the branch is still based on current code.
The safe question is not “did the agent run tests?” It is “which exact, reviewed head passed every gate?”
THE MERGE GATE
Four gates before an AI PR can merge
These rules come from the Orbi workflow, and the review checks the acceptance criteria written in the Issue:
- 01 · INDEPENDENT VERDICTA separate review session gives a clean verdict
The verdict is bound to the PR’s current head. If the verdict head is not the PR head, the merge is not authorized.
- 02 · FRESH BASEThe reviewed head contains the latest base
A review of stale code is not a review of what would land now. The branch must include the latest base branch.
- 03 · CI CONCLUDEDCI has a conclusion
Pending CI waits for the next round. A check is not treated as passed while it is still running.
- 04 · HEAD STILL SAFEThe PR is mergeable and the remote head has not changed
Orbi reads mergeability and the remote head once, then only merges the head it just verified.
PUBLIC EVIDENCE
A real PR was stopped twice
Issue #1018 led to PR #1023, later included in release v0.5.17. The independent review stopped it for two rounds: round 1 found a major release-ordering compensation problem—published tags could be left without their docs page; round 2 found that the current-head CI diff-coverage gate failed because new promotion, resume, deduplication, and tag-push compensation branches were uncovered. The fixes and CI evidence came before release.
The gate is useful precisely because “the PR exists” and “the PR is green” were not enough.
WHEN A POLICY SAYS NO
Protection rules do not get bypassed
If review and checks pass but a known repository policy still blocks the merge, Orbi stops at ai-awaiting-merge. The Issue comment names the one maintainer action required. Once the maintainer changes that policy or supplies the required approval, Orbi resumes and merges the named PR head.
Want a human to look first?
The ai-human-review acceptance gate is off by default. When an operator turns it on, a person confirms the delivery’s acceptance checklist before the independent review and merge continue.
AFTER MERGE
The merged result stays identifiable
After the delivery, the release Issue freezes a SHA and creates a tag. This guide stops there: the important safety property is that the thing released is an identified, gated result—not an agent’s moving branch.
Compare the workflow with a coding agent → · Inspect public evidence → · Run it with Orbi Cloud →
THE SHORT VERSION
Automate the merge, not the trust
Give the agent a path to merge only after an independent review, a fresh base, concluded CI, and an unchanged mergeable head. That is how an AI can merge its own PR without making a green check the whole safety story.