ContextQMD
Back to Gitlabhq

Branch rules

doc/user/project/repository/branches/branch_rules.md

18.11.211.3 KB
Original Source

{{< details >}}

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

{{< /details >}}

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

{{< history >}}

{{< /history >}}

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

Prerequisites:

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

To view the branch rules overview list:

  1. In the top bar, 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. In the top bar, 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

{{< history >}}

{{< /history >}}

Prerequisites:

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

To create a branch rule:

  1. In the top bar, 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

[!note] Not available for all branches.

To add protections to a new branch:

  1. In the top bar, 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

{{< details >}}

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

{{< /details >}}

[!note] Not available for all branches.

Prerequisites:

  • You must have the Maintainer or Owner 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. In 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

{{< details >}}

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

{{< /details >}}

{{< history >}}

{{< /history >}}

Prerequisites:

  • You must have the Maintainer or Owner 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:

    • Default: Removes the branch-level squash setting and inherits from the project's default settings. This option is not available for the All branches rule, which defines the project's default settings.
    • 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

{{< details >}}

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

{{< /details >}}

{{< history >}}

{{< /history >}}

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

For more information, see external status checks.

Edit a branch rule target

{{< history >}}

{{< /history >}}

Prerequisites:

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

To edit a branch rule target:

  1. In the top bar, 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.

[!note] Not available for all branches.

Delete a branch rule

{{< history >}}

{{< /history >}}

Prerequisites:

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

To delete a branch rule:

  1. In the top bar, 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.

[!note] Deleting a branch rule is not available for rules targeting all branches.