Branch rules

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

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

• Introduced in GitLab 15.1 with a flag named branch_rules. Disabled by default.
• Enabled on self-managed in GitLab 15.11.
• Generally available in GitLab 16.1. Feature flag branch_rules removed.

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

• Introduced in GitLab 16.8 with a flag named add_branch_rules. Disabled by default.
• Feature flag add_branch_rules renamed to edit_branch_rules in GitLab 16.11. Disabled by default.
• All branches and All protected branches options introduced in GitLab 17.0.
• Enabled on GitLab.com in GitLab 17.4.
• Enabled on self-managed and GitLab Dedicated in GitLab 17.5.

FLAG: The availability of this feature is controlled by a feature flag. For more information, see the history.

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

NOTE: Not available for all branches.

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

DETAILS: Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

NOTE: Not available for all branches.

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.

Add a status check service

DETAILS: Tier: Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

• Introduced in GitLab 17.4 with a flag named edit_branch_rules. Disabled by default.
• Enabled on GitLab.com in GitLab 17.4.
• Enabled on self-managed and GitLab Dedicated in GitLab 17.5.

NOTE: Not available for all protected branches.

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

• Introduced in GitLab 16.8 with a flag named add_branch_rules. Disabled by default.
• Feature flag add_branch_rules renamed to edit_branch_rules in GitLab 16.11. Disabled by default.
• Enabled on GitLab.com in GitLab 17.4.
• Enabled on self-managed and GitLab Dedicated in GitLab 17.5.

FLAG: The availability of this feature is controlled by a feature flag. For more information, see the history.

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

NOTE: Not available for all branches.

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.

NOTE: In GitLab Premium and Ultimate, you can also add groups or individual users to Allowed to merge and Allowed to push and merge.

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

Delete a branch rule

• Introduced in GitLab 16.8 with a flag named add_branch_rules. Disabled by default.
• Feature flag add_branch_rules renamed to edit_branch_rules in GitLab 16.11. Disabled by default.
• Enabled on GitLab.com in GitLab 17.4.
• Enabled on self-managed and GitLab Dedicated in GitLab 17.5.

FLAG: The availability of this feature is controlled by a feature flag. For more information, see the history.

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.