Branch rules

GitLab provides multiple methods to protect individual branches. These methods ensure your branches receive oversight and quality checks from their creation to their deletion:

• Apply enhanced security and protection to your project’s default branch.
• Configure protected branches to:
  • Limit who can push and merge to a branch.
  • Manage if users can force push to the branch.
  • Manage if changes to files listed in the CODEOWNERS file can be pushed directly to the branch.
• Configure approval rules to manage review requirements and implement security-related approvals.
• Integrate with third-party status checks to ensure the contents of your branch meets your defined quality standards.

You can manage your branches:

• With the GitLab user interface.
• With Git on the command line.
• With the Branches API.

View branch rules

The Branch rules overview page shows all branches with any configured protections, and their protection methods:

Prerequisites:

• You must have at least the Maintainer role for the project.

To view the Branch rules overview list:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Repository.
3. Expand Branch rules to view all branches with protections.

View branch rule details

To view branch rules and protections for a single branch:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Repository.
3. Expand Branch rules to view all branches with protections.
4. Identify the branch you want and select View details.

Create a branch rule

Prerequisites:

• You must have at least the Maintainer role for the project.

To create a branch rule:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Repository.
3. Expand Branch rules.
4. Select Add branch rule.
5. Choose one of the following options:
   • To enter a specific branch name or pattern:
     1. Select Branch name or pattern.
     2. From the Create branch rule dropdown list, select a branch name or create a wildcard by typing *.
   • To protect all branches in the project:
     1. Select All branches.
     2. On the rule’s details page, under Merge request approvals, enter the required number of approvals for the rule.
   • To protect all branches in the project that are already specified as protected:
     1. Select All protected branches.
     2. On the rule’s details page, under Merge request approvals, enter the required number of approvals for the rule.

Add a branch rule protection

To add protections to a new branch:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Repository.
3. Expand Branch rules.
4. Select Add branch rule.
5. Select one of All protected branches or Branch name or pattern.
6. Select Create protected branch.

Add an approval rule

Prerequisites:

• You must have at least the Maintainer role for the project.

To add a merge request approval rule:

1. From the branch rule details page, go to the Merge request approvals section.
2. In the Approval rules section, select Add approval rule.
3. On the right sidebar, complete the fields:

   • Enter a Rule name.

   • In Required number of approvals, enter a value (0-100).

     A value of 0 makes the rule optional, and any number greater than 0 creates a required rule. The maximum number of required approvals is 100.

   • Select users or groups that are eligible to approve.

     GitLab suggests approvers based on previous authors of the files changed by the merge request.

4. Select Save changes.

For additional information, see Approval rules.

Edit squash commits option

Prerequisites:

• You must have at least the Maintainer role for the project.

To edit a squash option:

1. From the branch rule details page, go to the Squash commits when merging section.

2. Select Edit.

3. Select one of the following options:

   • Do not allow: Squashing is never allowed and the checkbox is hidden.
   • Allow: Checkbox is visible and unselected by default.
   • Encourage: Checkbox is visible and selected by default.
   • Require: Squashing is almost performed. Checkbox is visible and selected, and users cannot change it.

4. Select Save changes.

Add a status check service

To add a status check service:

1. From the branch rule details page, go to the Status checks section.

2. Select Add status check.

3. Enter the Service name.

4. In the API to check field, enter the URL.

   You should use a HTTPS URL to protect your merge request data in transit.

For more information, see External status checks.

Edit a branch rule target

Prerequisites:

• You must have at least the Maintainer role for the project.

To edit a branch rule target:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Repository.
3. Expand Branch rules to view all branches with protections.
4. Identify the branch you want and select View details.
5. In the Rule target section, select Edit.
6. Edit the information as needed.
7. Select Update.

Edit a branch rule protection

To edit branch rule protections:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Repository.
3. Expand Branch rules to view all branches with protections.
4. Identify the branch you want and select View details.
5. From the Protect branch section, choose one of the following options:
   • From Allowed to merge, select Edit.
     1. Select the roles that can merge into this branch.
     2. Select Save changes.
   • From Allowed to push and merge, select Edit.
     1. Select the roles that can merge into this branch.
     2. If desired, search to add Deploy keys.
     3. Select Save changes.

For additional information about branch protection controls, see Protected branches.

Delete a branch rule

Prerequisites:

• You must have at least the Maintainer role for the project.

To delete a branch rule:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Repository.
3. Expand Branch rules.
4. Next to a rule you want to delete, select View details.
5. In the upper-right corner, select Delete rule.
6. On the confirmation dialog, select Delete branch rule.