Review pull requests

A Review checks the pull request of a finished task and can fix what it finds.

Review every pull request

To do it yourself:

• Add a review node to the Blueprint, as shown in Write a Blueprint. A task that succeeds after reaching it starts a Review of the open pull request of its branch.
• Set reviewFixBudget with projects.configure, as shown in change a Project. It sets how many fix rounds one Review may run, from 0 to 10.

Review and merging explains what the reviewer reads and how fix rounds run.

Request a Review

To do it yourself, review the pull request of one finished Run:

{ "organizationId": "<organization id>", "sourceRunId": "<run id>", "pullNumber": 17 }

devboxes invoke review.request --input @review.json

The Run's ID is in the result of sessions.inspect.

Read the result

{ "organizationId": "<organization id>", "sessionId": "<session id>" }

devboxes invoke review.inspect --input @session.json

The result lists the findings and how the Review ended. How a Review ends lists the severities, outcomes, and handoffReason values.

Merge approved pull requests

By default, a person merges. A Project can let devboxes merge its pull requests once their Review approves them.

To do it yourself, turn on mergeAfterReview with projects.configure-merging. Owners and admins can change it:

{ "organizationId": "<organization id>", "projectId": "<project id>", "mergeAfterReview": true }

devboxes invoke projects.configure-merging --input @merging.json

To turn it off, send "mergeAfterReview": false. projects.list shows the current setting. Only a Project on GitHub can turn it on. devboxes reads the setting when it would merge, so turning it off also stops a merge that waits for checks, and the Review ends in complete.

In Chat, owners and admins who linked their chat account can ask devboxes to turn merging on or off for a Project of the channel when the Chat policy allows projects.configure-merging. devboxes refuses anyone else. It then says whether it now merges approved pull requests or leaves merging to a person.

devboxes merges a pull request only when its Review ended with no findings for the exact commit that devboxes published, nobody held or changed the pull request, and its checks passed. When devboxes merges after a Review lists every condition.

Otherwise the Review ends in handoff, and its handoffReason says why. Fix or merge the pull request on GitHub.

Ask devboxes to merge a pull request

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. When a person asks devboxes to merge explains which reviews and approvals devboxes requires.

In Chat, the Chat policy must allow repositories.merge, repositories.review, and repositories.checks, because devboxes reads the pull request and its checks before it merges. devboxes merges only when an owner or admin asks in a message, after linking their chat account. To merge despite open findings, the same person confirms it in a later message. From the CLI, owners and admins merge with repositories.merge:

{
  "organizationId": "<organization id>",
  "repositoryFullName": "my-org/web-app",
  "number": 42,
  "sha": "<the head commit you read>",
  "mergeDespiteOpenFindings": false
}

devboxes invoke repositories.merge --input @merge.json

state in the result is merged, needs_review, open_findings with the findings, or refused with GitHub's reason, for example conflicts or branch protection. To merge despite the open findings, send the same input with mergeDespiteOpenFindings set to true. When the pull request's head is no longer sha, or the pull request closed, the command fails with PULL_REQUEST_CHANGED. Read it again and decide again. devboxes merges only on GitHub, with the merge method that GitHub selects for the repository.