Review and merging

A Review is a second agent that checks the pull request of a finished task. Its reviewer only reads: it reports findings and does not change the code.

What the reviewer reads

The reviewer reads the pull request's changes with git in its own checkout. It reads the pull request's review threads, summaries, and comments with repositories.review, even when the Blueprint does not bind that operation, and so do the fix rounds and rechecks. For a task started from Chat, it reads them only while the Chat policy allows repositories.review. Otherwise it reviews the changes alone.

Fix rounds

A fix round runs the Session's Blueprint on the Session's model, as a continuation does, with the findings as its instruction, so the Blueprint's tests gate the fix. When the Project can no longer use that Blueprint, the findings go to a person with SESSION_BLUEPRINT_UNAVAILABLE instead of a fix round. Fixes need a publish node in the Blueprint, and devboxes must be able to push to the pull request's branch. Otherwise the Review ends in handoff and keeps its findings.

When devboxes merges after a Review

devboxes merges a pull request when all of these are true:

• Its Review, after any fix rounds, ended with no findings for the exact commit that devboxes published.
• Nobody held merging the work. devboxes records a hold when a person asks it not to merge the work, or to let them see or approve it before it merges: in the work's request, where the agent records it, or in Chat or with sessions.hold-merge. A hold covers every pull request that the held Session works on in place, reviewed, or opened, also when another Session works on it. A Session stacked on a pull request does not hold that pull request. devboxes still publishes held work, and a person merges it. sessions.inspect shows who held the work and when.
• Nobody pushed to the pull request, reviewed it, or changed its review threads while devboxes reviewed it or waited for its checks, and no person commented on it or replied in its review threads after the work started. Comments and replies from GitHub bot accounts, such as a CI app or the devboxes app, and the comments and replies that devboxes posted from its tasks, don't count.
• Every check on that commit finished and passed. devboxes waits while checks run, for up to a day after the Review. A commit without checks merges right away. A CI service that reports a status only once its build starts, rather than when the commit arrives, can leave the commit without checks for a moment, and devboxes can merge before that build reports. Require that check in branch protection to make GitHub wait for it.
• GitHub accepts the merge. Branch protection still applies. When it requires a person's approval, the person approves before the Review starts, because an approval during the Review stops the Review and leaves the pull request to a person.

devboxes merges only that exact commit, with the merge method that GitHub selects for the repository. When the base branch moves on while devboxes waits, devboxes still merges, unless branch protection requires the pull request to be up to date with its base branch.

When a person asks devboxes to merge

An owner or admin can ask devboxes to merge a pull request, for example "merge #42" in a Chat thread, whether or not the Project merges after Review. devboxes merges the commit that is the pull request's head when it reads it, and only after a review of that commit:

1. If someone with write access to the repository approved that commit on GitHub, devboxes merges it. Approvals by bots and dismissed approvals don't count.
2. If no devboxes Review covers that commit, or the pull request changed since the Review, for example its merge base, devboxes merges nothing and says so. When a devboxes task published that commit and was not reviewed yet, devboxes asks whether to start a Review. devboxes can't review other commits, for example of a pull request that a person opened or pushed to after a Review. Someone with write access can approve those on GitHub.
3. If the Review of that commit has medium or high findings, devboxes merges nothing. It lists the findings and asks whether to merge anyway.
4. Otherwise, devboxes merges.

devboxes also reads the pull request's checks and mentions failing or running ones. Branch protection on GitHub decides whether they block the merge.

After it merges, devboxes comments on the pull request who approved which commit, where, and when, for example "Lena Owner approved merging commit 3f2c9ab in Slack (Octo) on 2026-10-08 at 21:40 UTC." From the CLI or another client, it says "through devboxes" instead. A merge despite open findings says how many there were and how severe.