Skip to main content
Video tutorial · 1:13

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 valueWhat it doesEffect on the merge gate
OffoffReviews are not checkedNone
ReportreportReviews are checked and the result is shown on the merge request, marked (report only)None
EnforceblockReviews are checked and hold the mergeWaiting 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 doesDefaultAllowed valuesSet whereWho can change itAPI field
Mode (row Code review)See ModesOffOff, Report, EnforcePolicyPolicy manager, company admin, platform admincontrols.code_review.mode (off, report, block)
Approving reviewsHow many approving reviews the latest commit needs0 (1 when the control is first turned on in the editor)0 to 20PolicySamecontrols.code_review.min_approvals
Reviewers need at leastThe repository role a reviewer must hold for an approval to countDeveloper / Write (default)Reporter / Read, Developer / Write (default), Maintainer / Maintain, Owner / Admin. The API also accepts 25 (Triage on GitHub)PolicySamecontrols.code_review.min_access (20, 25, 30, 40, 50; empty or 0: 30)
Requested changes hold the mergeWhile a reviewer's latest review requests changes, the control failsOff (on when the control is first turned on in the editor)On, offPolicySamecontrols.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​

StatusMessage
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​

GitLabGitHub
What counts as approvingThe merge request's approvals, as GitLab lists themEach reviewer's latest Approve review
Requests for changesReviewers 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 commitGitLab 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 themAn approval counts only when it was given on the head commit
Role namesReporter, Developer, Maintainer, OwnerRead, 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_review with mode, min_approvals, min_access, requested_changes_block.
  • Merge request (GET /api/v1/merge-requests/{id}): reviews (approvers and changes_requested_by at head_sha), and the result in decision.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 →

Require a Code Review in GitLabYouTube ↗