Merge request approvals (STARTER)

Introduced in GitLab Enterprise Edition 7.12.

Merge request approvals enable enforced code review by requiring specified people to approve a merge request before it can be merged.

Merge request approvals enable multiple use cases:

Enforcing review of all code that gets merged into a repository.
Specifying reviewers for a given proposed code change, as well as a minimum number of reviewers, through Approval rules.
Specifying categories of reviewers, such as backend, frontend, quality assurance, database, etc., for all proposed code changes.
Automatically designating Code Owners as eligible approvers, determined by the files changed in a merge request.
Requiring approval from a security team before merging code that could introduce a vulnerability.(ULTIMATE)

Approval rules

Approval rules define how many approvals a merge request must receive before it can be merged, and optionally which users should do the approving. Approvals can be defined:

As project defaults.
Per merge request.

If no approval rules are defined, any user can approve a merge request, though the default minimum number of required approvers can still be set in the project settings for merge request approvals.

Eligible approvers

The following can approve merge requests:

Users being added as approvers at project or merge request level.
Code owners to the files changed by the merge request.

An individual user can be added as an approver for a project if they are a member of:

The project.
The project's immediate parent group.
A group that has access to the project via a share.

A group of users can also be added as approvers. In the future, group approvers may be restricted to only groups with share access to the project.

If a user is added as an individual approver and is also part of a group approver, then that user is just counted once. The merge request author, as well as users who have committed to the merge request, do not count as eligible approvers, if Prevent author approval (enabled by default) and Prevent committers approval (disabled by default) are enabled on the project settings.

Implicit approvers

If the number of required approvals is greater than the number of assigned approvers, approvals from other users will count towards meeting the requirement. These would be users with developer permissions or higher in the project who were not explicitly listed in the approval rules.

Code Owners as eligible approvers

Introduced in GitLab Starter 11.5.

If you add Code Owners to your repository, the owners to the corresponding files will become eligible approvers, together with members with Developer or higher permissions.

To enable this merge request approval rule:

Navigate to your project's Settings > General and expand Merge request approvals.
Locate Any eligible user and choose the number of approvals required.

Once set, merge requests can only be merged once approved by the number of approvals you've set. GitLab will accept approvals from users with Developer or higher permissions, as well as by Code Owners, indistinguishably.

Alternatively, you can require Code Owner's approvals for Protected Branches. (PREMIUM)

Adding / editing a default approval rule

To add or edit the default merge request approval rule:

Navigate to your project's {settings} Settings > General and expand Merge request approvals.
Click Add approval rule, or Edit.
- Add or change the Rule name.
- Set the number of required approvals in No. approvals required. The minimum value is 0.
- (Optional) Search for users or groups that will be eligible to approve merge requests and click the Add button to add them as approvers. Before typing in the search field, approvers will be suggested based on the previous authors of the files being changed by the merge request.
- (Optional) Click the {remove} Remove button next to a group or user to delete it from the rule.
Click Add approval rule or Update approval rule.

Any merge requests that were created before changing the rules will not be changed. They will keep the original approval rules, unless manually overridden.

NOTE: Note: If a merge request targets a different project, such as from a fork to the upstream project, the default approval rules will be taken from the target (upstream) project, not the source (fork).

Editing / overriding approval rules per merge request

Introduced in GitLab Enterprise Edition 9.4.

By default, the merge request approval rule listed in each merge request (MR) can be edited by the MR author or a user with sufficient permissions. This ability can be disabled in the merge request approvals settings.

One possible scenario would be to add more approvers than were defined in the default settings.

When creating or editing a merge request, find the Approval rules section, then follow the same steps as Adding / editing a default approval rule.

Multiple approval rules (PREMIUM)

Introduced in GitLab Premium 11.10.

In GitLab Premium, it is possible to have multiple approval rules per merge request, as well as multiple default approval rules per project.

Adding or editing multiple default rules is identical to adding or editing a single default approval rule, except the Add approval rule button will be available to add more rules, even after a rule is already defined.

Similarly, editing or overriding multiple approval rules per merge request is identical to editing or overriding approval rules per merge request, except the Add approval rule button will be available to add more rules, even after a rule is already defined.

When an eligible approver approves a merge request, it will reduce the number of approvals left for all rules that the approver belongs to.

Scoped to Protected Branch (PREMIUM)

Introduced in GitLab Premium 12.8.

Approval rules are often only relevant to specific branches, like master. When configuring Default Approval Rules these can be scoped to all the protected branches at once by navigating to your project's Settings, expanding Merge request approvals, and selecting Any branch from the Target branch dropdown.

Alternatively, you can select a very specific protected branch from the Target branch dropdown:

To enable this configuration, see Code Owner’s approvals for protected branches.

Adding or removing an approval

When an eligible approver visits an open merge request, one of the following is possible:

If the required number of approvals has not been yet met, they can approve it by clicking the displayed Approve button.
If the required number of approvals has already been met, they can still approve it by clicking the displayed Approve additionally button.
They have already approved this merge request: They can remove their approval.

NOTE: Note: The merge request author is not allowed to approve their own merge request if Prevent author approval is enabled in the project settings.

Once the approval rules have been met, the merge request can be merged if there is nothing else blocking it. Note that the merge request could still be blocked by other conditions, such as merge conflicts, pending discussions, or a failed CI/CD pipeline.

Merge request approvals project settings

The project settings for Merge request approvals are found by going to {settings} Settings > General and expanding Merge request approvals.

Prevent overriding default approvals

By default, users are able to edit the approval rules in merge requests. If disabled, the approval rules for all new merge requests will be determined by the default approval rules. To disable this feature:

Uncheck the Can override approvers and approvals required per merge request checkbox.
Click Save changes.

Resetting approvals on push

You can force all approvals on a merge request to be removed when new commits are pushed to the source branch of the merge request. If disabled, approvals will persist even if there are changes added to the merge request. To enable this feature:

Check the Remove all approvals in a merge request when new commits are pushed to its source branch checkbox.
Click Save changes.

NOTE: Note: Approvals do not get reset when rebasing a merge request from the UI. However, approvals will be reset if the target branch is changed.

Allowing merge request authors to approve their own merge requests

Introduced in GitLab Starter 11.3.

You can allow merge request authors to self-approve merge requests. Authors also need to be included in the approvers list in order to be able to approve their merge request. To enable this feature:

Uncheck the Prevent approval of merge requests by merge request author checkbox, which is enabled by default.
Click Save changes.

Prevent approval of merge requests by their committers

Introduced in GitLab Starter 11.10.

You can prevent users that have committed to a merge request from approving it. To enable this feature:

Check the Prevent approval of merge requests by their committers checkbox.
Click Save changes.

Require authentication when approving a merge request

Introduced in GitLab Starter 12.0.

You can force the approver to enter a password in order to authenticate before adding the approval. This enables an Electronic Signature for approvals such as the one defined by CFR Part 11). To enable this feature:

Check the Require user password to approve checkbox.
Click Save changes.

Security approvals in merge requests (ULTIMATE)

Merge Request Approvals can be configured to require approval from a member of your security team when a vulnerability would be introduced by a merge request.

For more information, see Security approvals in merge requests.

Enabling the new approvals interface

Since GitLab v12.0, an updated approvals interface is available by default. In versions older than 12.0, the updated interface is not available unless the approval_rules feature flag is enabled, which can be done from the Rails console by instance administrators.

Use these commands to start the Rails console:

# Omnibus GitLab
gitlab-rails console

# Installation from source
cd /home/git/gitlab
sudo -u git -H bin/rails console -e production

Then run Feature.enable(:approval_rules) to enable the updated interface.