Branch rules

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab 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

Version history

• 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

Version history

• 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 GitLab Self-Managed and GitLab Dedicated in GitLab 17.5.

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 with *.
   • 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

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 branch rule.

Add an approval rule

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

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.

Edit squash commits option

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

Version history

• Introduced in GitLab 17.9 with a flag named branch_rule_squash_settings. Disabled by default.
• Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated in GitLab 17.10.
• Generally available in GitLab 17.11. Feature flag branch_rule_squash_settings removed.

Prerequisites:

• You must have at least the Maintainer role for the project.
• In GitLab Free, this feature is available only if the branch rule targets All branches.
• In GitLab Premium and GitLab Ultimate, this feature is available for all branch rules.

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 always performed. Checkbox is visible and selected, and users cannot change it.

4. Select Save changes.

Add a status check service

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

Version history

• 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 GitLab Self-Managed and GitLab Dedicated in GitLab 17.5.

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 an HTTPS URL to protect your merge request data in transit.

For more information, see External status checks.

Edit a branch rule target

Version history

• 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 GitLab Self-Managed and GitLab Dedicated in GitLab 17.5.

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

For information about branch protection controls, see Protected branches.

Not available for all branches.

Delete a branch rule

Version history

• 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 GitLab Self-Managed and GitLab Dedicated in GitLab 17.5.

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

Deleting a branch rule is not available for rules targeting all branches.

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.

Related topics

• Default branch
• Protected branches
• Protect your repository
• Branching strategies
• Merge request approvals