Code review
The Code review control asks for peer review in the VCS before a merge: a number of approving reviews on the merge request's latest commit, from people with a chosen repository role, and optionally no open request for changes. It is separate from the change approval, which is decided in the tracker (see Approval).
The control is set per change policy, in the policy editor's Checks tab (row Code review).
Modes
| Mode (label in the UI) | API value | What it does | Effect on the merge gate |
|---|---|---|---|
| Off | off | Reviews are not checked | None |
| Report | report | Reviews are checked and the result is shown on the merge request, marked (report only) | None |
| Enforce | block | Reviews are checked and hold the merge | Waiting while approvals are missing or the reviews cannot be read; Blocked while changes are requested |
A new policy starts with Off. Switching a policy from Off to Report or Enforce while it asks for nothing fills in 1 approving review and turns Requested changes hold the merge on. A control that asks for 0 approvals and does not hold on requested changes is skipped ("Not required by this policy.").
Settings
All settings are in the policy; the company has no code review defaults.
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Mode (row Code review) | See Modes | Off | Off, Report, Enforce | Policy | Policy manager, company admin, platform admin | controls.code_review.mode (off, report, block) |
| Approving reviews | How many approving reviews the latest commit needs | 0 (1 when the control is first turned on in the editor) | 0 to 20 | Policy | Same | controls.code_review.min_approvals |
| Reviewers need at least | The repository role a reviewer must hold for an approval to count | Developer / Write (default) | Reporter / Read, Developer / Write (default), Maintainer / Maintain, Owner / Admin. The API also accepts 25 (Triage on GitHub) | Policy | Same | controls.code_review.min_access (20, 25, 30, 40, 50; empty or 0: 30) |
| Requested changes hold the merge | While a reviewer's latest review requests changes, the control fails | Off (on when the control is first turned on in the editor) | On, off | Policy | Same | controls.code_review.requested_changes_block |
Who counts
An approving review counts when:
- it is on the merge request's latest commit (see GitLab and GitHub);
- it is not the author's own review, not Merge Pilot's, and not a bot's;
- the reviewer holds at least the chosen role on the repository. The role is read from the VCS; when it cannot be read, the review does not count. Approvals that do not count are named in the control's message ("Not counted (no role that may review): bob.").
A request for changes holds the merge (with Requested changes hold the merge on) when it comes from anyone other than the author, Merge Pilot or a bot; the role is not checked for it.
What the control says
| Status | Message |
|---|---|
| Passed | "Approved by alice, bob." or, with 0 approvals required, "No changes requested." |
| Pending | "1 of 2 approving reviews on the latest commit." |
| Failed | "Changes requested by carol." |
| Pending | "The reviews could not be read (the VCS did not answer); they are read again when the merge request is next evaluated." |
| Pending | "The reviews could not be read (the repository keeps approvals when commits are added, so they may be for an older commit; turn on removing approvals on push (a change management setup step)); they are read again when the merge request is next evaluated." (GitLab, see GitLab and GitHub) |
| Failed | "The VCS does not report reviews for this merge request." |
The message is shown on the merge request page (Policy card) and in the status comment Merge Pilot keeps on the merge request in the VCS.
When it runs
Reviews are read from the VCS every time the merge request is evaluated: after a review or approval event from the VCS, a new commit, a finished scan or CI run, a policy change, Resync on the merge request page, and the periodic re-check. There is nothing to re-scan.
In a watched repository, reviews are read and recorded even when the policy does not ask for them, as evidence for when it does.
GitLab and GitHub
| GitLab | GitHub | |
|---|---|---|
| What counts as approving | The merge request's approvals, as GitLab lists them | Each reviewer's latest Approve review |
| Requests for changes | Reviewers whose state is requested changes (on GitLab versions that report reviewer states; older versions report approvals only) | Each reviewer's latest Request changes review. A later approval replaces it; a dismissed review is dropped; comments do not count |
| Latest commit | GitLab approvals carry no commit. They concern the latest commit only when the project removes them when commits are added; the change management setup step Remove approvals when commits are added turns that on (see GitLab). When the project keeps approvals on push, no approval is counted and the control stays Pending with that explanation. When the setting cannot be read, approvals count as GitLab lists them | An approval counts only when it was given on the head commit |
| Role names | Reporter, Developer, Maintainer, Owner | Read, Write, Maintain, Admin (and Triage through the API) |
Audit
The control writes no entry of its own; its result is part of the merge gate entries mr_gate_approved, mr_gate_pending and mr_gate_blocked (see Audit log).
API
- Policy:
controls.code_reviewwithmode,min_approvals,min_access,requested_changes_block. - Merge request (
GET /api/v1/merge-requests/{id}):reviews(approversandchanges_requested_byathead_sha), and the result indecision.controls(control: "code_review").
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →