Merge request approval rules

{{< details >}}

• Tier: Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Approval rules define how many approvals a merge request must receive before it can be merged, and which users should do the approving. They can be used in conjunction with code owners to ensure that changes are reviewed both by the group maintaining the feature, and any groups responsible for specific areas of oversight.

You can define approval rules:

• As project defaults.
• Per merge request.

You can configure approval rules:

• For the entire instance.

If you don't define a default approval rule, any user can approve a merge request. Even if you don't define a rule, you can still enforce a minimum number of required approvers in the project's settings.

Merge requests that target a different project, such as from a fork to the upstream project, use the default approval rules from the target (upstream) project, not the source (fork).

Merge request approvals can be configured globally to apply across all (or a subset) projects with policies. Merge request approval policies also provide additional flexibility with more granular configuration options.

Add an approval rule

Prerequisites:

• You must have the Maintainer or Owner role for the project.
• To add a group as an approver in GitLab.com, you must be a member of the group or the group must be public.

To add a merge request approval rule:

1. In the top bar, select Search or go to and find your project.
2. Select Settings > Merge requests.
3. In the Merge request approvals section, in the Approval rules section, select Add approval rule.
4. In the right sidebar, complete the fields:
   • In Approvals required, a value of 0 makes the rule optional, and any number greater than 0 creates a required rule. Maximum number of required approvals is 100.
   • From Add approvers, select users or groups that are eligible to approve. GitLab suggests approvers based on previous authors of the files changed by the merge request.
5. Select Save changes. You can add multiple approval rules.

Your configuration for approval rule overrides determines if the new rule is applied to existing merge requests:

• If approval rule overrides are allowed, changes to these default rules are not applied to existing merge requests, except for changes to the target branch of the rule.
• If approval rule overrides are not allowed, all changes to default rules are applied to existing merge requests. Any approval rules that were previously manually overridden during the period when approval rule overrides where allowed, are not modified.

Edit an approval rule

Prerequisites:

• You must have the Maintainer or Owner role for the project.
• To add a group as an approver in GitLab.com, you must be a member of the group or the group must be public.

To edit a merge request approval rule:

1. In the top bar, select Search or go to and find your project.
2. Select Settings > Merge requests.
3. In the Merge request approvals section, in the Approval rules section, next to the rule you want to edit, select Edit.
4. In the right sidebar, edit the fields:
   • In Approvals required, a value of 0 makes the rule optional, and any number greater than 0 creates a required rule. Maximum number of required approvals is 100.
   • To remove users or groups, identify the group or user to remove, and select Remove ({{< icon name="remove" >}}).
5. Select Save changes.

Delete an approval rule

Prerequisites:

• You must have the Maintainer or Owner role for the project.

To delete a merge request approval rule:

1. In the top bar, select Search or go to and find your project.
2. Select Settings > Merge requests.
3. In the Merge request approvals section, next to the rule you want to delete, select the trash can ({{< icon name="remove" >}}).
4. Select Remove approvers.

Multiple approval rules

To enforce multiple approval rules on a merge request, add multiple default approval rules for a project.

When an eligible approver approves a merge request, it reduces the number of approvals left (the Approvals column) for all rules that the approver belongs to:

<i class="fa-youtube-play" aria-hidden="true"></i> For an overview, see the multiple approvers video.

Get notified about all merge requests you can approve

To get email notifications every time a merge request you're eligible to approve is created:

• Set your notification level to Custom and select the Merge request you're eligible to approve is created event.

Edit or override merge request approval rules

You can override the merge request approval rules for a project by either:

• Editing an existing merge request.
• Creating a new merge request.

Prerequisites:

• The project setting Prevent editing approval rules in merge requests is disabled.
• One of the following must be true:
  • You have administrator access.
  • You are the author of the merge request, and have the Developer, Maintainer, or Owner role in the project.
  • You have the Maintainer or Owner role for the project.

To override approvers of a merge request:

1. When creating a new merge request, scroll to the Approval Rules section, and add or remove your desired approval rules before selecting Create merge request.
2. When viewing an existing merge request:
   1. In the top bar, select Search or go to and find your project.
   2. In the left sidebar, select Code > Merge requests and find your merge request.
   3. Select Edit.
   4. Scroll to the Approval Rules section.
   5. Add or remove your desired approval rules.
   6. Select Save changes.

Administrators can change the merge request approvals settings to prevent users from overriding approval rules for merge requests.

Require multiple approvals for a rule

To create an approval rule which requires more than one approval:

• When you create or edit a rule, set Approvals required to 2 or more.

To require multiple approvals for a rule, you can also use the Merge request approvals API to set the approvals_required attribute to 2 or more.

Configure optional approval rules

Merge request approvals can be optional for projects where approvals are appreciated, but not required. To make an approval rule optional:

• When you create or edit a rule, set Approvals required to 0.

To make an approval rule optional, you can also use the API to update an approval rule for a project, and set the approvals_required attribute to 0.

Approvals for protected branches

Approval rules are often relevant only to specific branches, like your default branch. To configure an approval rule for certain branches:

1. Create an approval rule.
2. Go to your project and select Settings > Merge requests.
3. In the Merge request approvals section, scroll to Approval rules.
4. For Target branch:
   • To apply the rule to all protected branches, select All protected branches.
   • To apply the rule to a specific branch, select it from the list.
5. To enable this configuration, follow Require code owner approval on a protected branch.

Enable approval permissions for additional users

Before users with the Planner or Reporter role can merge to a protected branch, you have to grant them permission to approve merge requests. Some users (like managers) might not need permission to push or merge code, but still need oversight on proposed work.

Users with the Planner or Reporter role can approve merge requests only through regular approval rules. Code owner approval rules require users to have the Developer, Maintainer, or Owner role. For more information, see eligible approvers.

Prerequisites:

• You must select a specific branch, as this method does not work with All Branches or All protected branches settings.
• The shared group must be added to an approval rule and not individual users, even when the added user is part of the group.

To enable approval permissions for these users without granting them push access:

1. Create a protected branch
2. Create a new group for the users with the Planner or Reporter role that need approval permissions.
3. Add the users to the group. The users must have the Planner, Reporter, Developer, Maintainer, or Owner role.
4. Share the project with your group, with the Reporter, Developer, Maintainer, or Owner role.
5. In the top bar, select Search or go to and find your project.
6. Select Settings > Merge requests.
7. In the Merge request approvals section, in the Approval rules section:
   • For a new rule, select Add approval rule and target the protected branch.
   • For an existing rule, select Edit and target the protected branch.
8. On the right sidebar, in Add approvers, select the group you created.
9. Select Save changes.

Security Approvals

{{< details >}}

• Tier: Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• Bot comment for approvals introduced in GitLab 16.2 with a flag named security_policy_approval_notification. Enabled by default.
• Bot comment for approvals generally available in GitLab 16.3. Feature flag security_policy_approval_notification removed.

{{< /history >}}

You can use merge request approval policies to define security approvals based on the status of vulnerabilities in the merge request and the default branch. Details for each security policy is shown in the Security Approvals section of your Merge Request configuration.

The security approval rules are applied to all merge requests until the pipeline is complete. The application of the security approval rules prevents users from merging in code before the security scans run. After the pipeline is complete, the security approval rules are checked to determine if the security approvals are still required. In case the scanners in the pipeline identify an issue and security approvals are required, a bot comment is generated on the merge request to indicate which steps are needed to proceed.

These policies are both created and edited in the security policy editor.

Eligible approvers

To be eligible as an approver for your project, a user must be a direct member of at least one of the following:

• Your project.
• Your project's group.
• Any of your project's group's parent groups.
• Another group that has been shared with your project.
• Another group that has been shared with your project's group or any of the group's parents.
• A group added as approvers.

Users with the Developer role can approve merge requests if one of the following is true:

• Users added as approvers at the project or merge request level.
• Users who are code owners of the files changed in the merge request.

Users with the Planner or Reporter role can approve only if all of the following are true:

• The users are part of a group that has been shared with the project. The group must have the Reporter, Developer, Maintainer, or Owner role.
• Approval permissions for users with the Planner and Reporter role are enabled.

To show who has participated in the merge request review, the Approvals widget in a merge request displays a Commented by column. This column lists eligible approvers who commented on the merge request. It helps authors and reviewers identify who to contact with questions about the merge request's content.

If the number of required approvals is greater than the number of assigned approvers, approvals from other users with the Developer, Maintainer, or Owner role in the project count toward meeting the required number of approvals, even if the users were not explicitly listed in the approval rules.

Code owners as approvers

If you add code owners to your repository, the owners of files become eligible approvers in the project. To enable this merge request approval rule:

1. In the top bar, select Search or go to and find your project.
2. Select Settings > Merge requests.
3. In the Merge request approvals section, in the Approval rules section, locate the All eligible users rule.
4. In the Approvals required column, enter the number of approvals required.

You can also require code owner approval for protected branches.

Approver by membership type

The following tables show how membership type affects eligibility for both approval rules and Code Owners.

User eligibility

When you assign individual users as approvers for approval rules or reference users in CODEOWNERS files, like @username:

Membership type	Approval rules	Code Owners
Direct member of the project	{{< yes >}}	{{< yes >}}
Direct member of the project's group	{{< yes >}}	{{< yes >}}
Inherited member of the project's group	{{< yes >}}	{{< yes >}}
Direct member of a group invited to the project	{{< yes >}}	{{< yes >}}
Inherited member of a group invited to the project	{{< no >}}	{{< no >}}
Direct member of a group invited to the project's group	{{< yes >}}	{{< yes >}}
Inherited member of a group invited to the project's group	{{< no >}}	{{< no >}}
Direct member of a group invited to the project's group's parent groups	{{< yes >}}	{{< yes >}}
Inherited member of a group invited to the project's group's parent groups	{{< no >}}	{{< no >}}

Group eligibility

When you assign groups as approvers for approval rules or reference groups in CODEOWNERS files, like @group-name, only direct members of eligible groups can provide approvals:

Group type	Approval rules	Code Owners
Groups invited to the project	{{< yes >}}	{{< yes >}}
Groups invited to the project's group	{{< yes >}}	{{< no >}}
Groups invited to a parent of the project's group	{{< yes >}}	{{< no >}}
The project's group	{{< yes >}}	{{< yes >}}
A parent of the project's group	{{< yes >}}	{{< yes >}}

[!note] For group-based approvals, only direct members of the group can approve merge requests. Inherited members of the eligible groups cannot provide approvals.

Group approvers

You can add a group of users as approvers. All direct members of this group can approve the rule. Inherited members cannot approve the rule.

Typically the group is a subgroup in your top-level namespace, unless you are collaborating with an external group. If you are collaborating with another group and want to use members of that group as approvers, you can either:

• Share access to the project.
• Share access to your project's group, which gives the external group approval access to all projects in your project's group.

A user's membership in an approver group determines their individual approval permissions in the following ways:

• Inherited members are not considered approvers. Only direct members can approve merge requests.
• A user from a group approver group who is later also added as an individual approver counts as one approver, not two.
• Merge request authors do not count as eligible approvers on their own merge requests by default. To change this behavior, disable the Prevent merge request creator approval project setting.
• By default, committers to merge requests can approve a merge request. To change this behavior, enable the Prevent committers approval project setting.

Troubleshooting

Approval rule name can't be blank

As a workaround for this validation error, you can delete the approval rule through the API.

1. List all approval rules for the project.
2. DELETE the rule.

For more information about this validation error, read issue 285129.

Groups need explicit or inherited Developer role on a project

A group created to handle approvals may be created in a different area of the project hierarchy than the project requiring review. If this happens, members of the group may not have permission to approve the merge request as they do not have access to it.

For example:

In the group structure below, project 1 belongs to subgroup 1 and subgroup 4 has users.

Project 1 has configured an approval rule for the project, which assigns subgroup 4 as approvers. When a merge request is created, approvers from subgroup 4 appear in the eligible approvers list. However, as users from subgroup 4 do not have permission to view the merge request, the 404 error is returned. To grant membership, the group must be invited as a project member. It is now possible for users from subgroup 4 to approve.