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
-
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:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > Repository.
- Expand Branch rules to view all branches with protections.
View branch rule details
To view branch rules and protections for a single branch:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > Repository.
- Expand Branch rules to view all branches with protections.
- 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 toedit_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.
Prerequisites:
- You must have at least the Maintainer role for the project.
To create a branch rule:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > Repository.
- Expand Branch rules.
- Select Add branch rule.
- Choose one of the following options:
- To enter a specific branch name or pattern:
- Select Branch name or pattern.
- From the Create branch rule dropdown list, select a branch name or create a wildcard by typing
*
.
- To protect all branches in the project:
- Select All branches.
- 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:
- Select All protected branches.
- On the rule’s details page, under Merge request approvals, enter the required number of approvals for the rule.
- To enter a specific branch name or pattern:
Add a branch rule protection
all branches
.To add protections to a new branch:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > Repository.
- Expand Branch rules.
- Select Add branch rule.
- Select one of All protected branches or Branch name or pattern.
- Select Create protected branch.
Add an approval rule
all branches
.Prerequisites:
- You must have at least the Maintainer role for the project.
To add a merge request approval rule:
- From the branch rule details page, go to the Merge request approvals section.
- In the Approval rules section, select Add approval rule.
- 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 than0
creates a required rule. The maximum number of required approvals is100
. -
Select users or groups that are eligible to approve.
GitLab suggests approvers based on previous authors of the files changed by the merge request.
- Select Save changes.
For additional information, see Approval rules.
Add a status check service
-
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.
all protected branches
.To add a status check service:
- From the branch rule details page, go to the Status checks section.
- Select Add status check.
- Enter the Service name.
-
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 toedit_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.
Prerequisites:
- You must have at least the Maintainer role for the project.
To edit a branch rule target:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > Repository.
- Expand Branch rules to view all branches with protections.
- Identify the branch you want and select View details.
- In the Rule target section, select Edit.
- Edit the information as needed.
- Select Update.
Edit a branch rule protection
all branches
.To edit branch rule protections:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > Repository.
- Expand Branch rules to view all branches with protections.
- Identify the branch you want and select View details.
- From the Protect branch section, choose one of the following options:
- From Allowed to merge, select Edit.
- Select the roles that can merge into this branch.
- Select Save changes.
- From Allowed to push and merge, select Edit.
- Select the roles that can merge into this branch.
- If desired, search to add Deploy keys.
- Select Save changes.
- From Allowed to merge, select Edit.
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 toedit_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.
Prerequisites:
- You must have at least the Maintainer role for the project.
To delete a branch rule:
- On the left sidebar, select Search or go to and find your project.
- Select Settings > Repository.
- Expand Branch rules.
- Next to a rule you want to delete, select View details.
- In the upper-right corner, select Delete rule.
- On the confirmation dialog, select Delete branch rule.