diff options
Diffstat (limited to 'doc/user/project/protected_branches.md')
| -rw-r--r-- | doc/user/project/protected_branches.md | 104 |
1 files changed, 86 insertions, 18 deletions
diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index da53fe2f5e9..1d279436d2c 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -22,12 +22,14 @@ The [default branch](repository/branches/default.md) for your repository is prot ## Who can modify a protected branch +> Branch push permission [changed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/118532) to require GitLab administrators to also have the **allowed** permission in GitLab 16.0. + When a branch is protected, the default behavior enforces these restrictions on the branch. | Action | Who can do it | |:-------------------------|:------------------------------------------------------------------| | Protect a branch | At least the Maintainer role. | -| Push to the branch | GitLab administrators and anyone with **Allowed** permission. (1) | +| Push to the branch | Anyone with **Allowed** permission. (1) | | Force push to the branch | No one. | | Delete the branch | No one. (2) | @@ -36,6 +38,40 @@ When a branch is protected, the default behavior enforces these restrictions on 1. No one can delete a protected branch using Git commands, however, users with at least Maintainer role can [delete a protected branch from the UI or API](#delete-a-protected-branch). +### When a branch matches multiple rules + +When a branch matches multiple rules, the **most permissive rule** determines the +level of protection for the branch. For example, consider these rules, which include +[wildcards](#configure-multiple-protected-branches-by-using-a-wildcard): + +| Branch name pattern | Allowed to merge | Allowed to push and merge | +|---------------------|------------------------|-----------------| +| `v1.x` | Maintainer | Maintainer | +| `v1.*` | Maintainer + Developer | Maintainer | +| `v*` | No one | No one | + +A branch named `v1.x` matches all three branch name patterns: `v1.x`, `v1.*`, and `v*`. +As the most permissive option determines the behavior, the resulting permissions for branch `v1.x` are: + +- **Allowed to merge:** Of the three settings, `Maintainer + Developer` is most permissive, + and controls branch behavior as a result. Even though the branch also matched `v1.x` and `v*` + (which each have stricter permissions), users with the Developer role can merge into the branch. +- **Allowed to push and merge:** Of the three settings, `Maintainer` is the most permissive, and controls + branch behavior as a result. Even though branches matching `v*` are set to `No one`, branches + that _also_ match `v1.x` or `v1.*` receive the more permissive `Maintainer` permission. + +To be certain that a rule controls the behavior of a branch, +_all_ other patterns that match must apply less or equally permissive rules. + +If you want to ensure that `No one` is allowed to push to branch `v1.x`, every pattern +that matches `v1.x` must set `Allowed to push and merge` to `No one`, like this: + +| Branch name pattern | Allowed to merge | Allowed to push and merge | +|---------------------|------------------------|-----------------| +| `v1.x` | Maintainer | No one | +| `v1.*` | Maintainer + Developer | No one | +| `v*` | No one | No one | + ### Set the default branch protection level Administrators can set a default branch protection level in the @@ -43,10 +79,41 @@ Administrators can set a default branch protection level in the ## Configure a protected branch +Configure protected branches for all projects in a group, or just for a project. + +### For all projects in a group **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106532) in GitLab 15.9 behind a feature flag, disabled by default. + +Group owners can create protected branches for a group. These settings are inherited by all projects in the group and can't be overridden by project settings. + +FLAG: +On self-managed GitLab, by default this feature is not available. +To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) +named `group_protected_branches`. On GitLab.com, this feature is not available. + +Prerequisite: + +- You must have the Owner role in the group. + +To protect a branch for all the projects in a group: + +1. On the top bar, select **Main menu > Groups** and find your group. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Protected branches**. +1. In the **Branch** text box, type the branch name or a wildcard. +1. From the **Allowed to merge** list, select a role that can merge into this branch. +1. From the **Allowed to push and merge** list, select a role that can push to this branch. +1. Select **Protect**. + +The protected branch is added to the list of protected branches. + +### For a project + Prerequisite: - You must have at least the Maintainer role. -- When granting a group **Allowed to merge** or **Allowed to push** permissions +- When granting a group **Allowed to merge** or **Allowed to push and merge** permissions on a protected branch, the group must be added to the project. To protect a branch: @@ -56,7 +123,7 @@ To protect a branch: 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. -1. From the **Allowed to push** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. +1. From the **Allowed to push and merge** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. 1. Select **Protect**. The protected branch displays in the list of protected branches. @@ -65,7 +132,7 @@ The protected branch displays in the list of protected branches. If both a specific rule and a wildcard rule apply to the same branch, the most permissive rule controls how the branch behaves. For merge controls to work properly, -set **Allowed to push** to a broader set of users than **Allowed to merge**. +set **Allowed to push and merge** to a broader set of users than **Allowed to merge**. Prerequisite: @@ -86,7 +153,7 @@ To protect multiple branches at the same time: | `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` | 1. From the **Allowed to merge** list, select a role, or group that can merge into this branch. In GitLab Premium, you can also add users. -1. From the **Allowed to push** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. +1. From the **Allowed to push and merge** list, select a role, group, or user that can push to this branch. In GitLab Premium, you can also add users. 1. Select **Protect**. The protected branch displays in the list of protected branches. @@ -97,7 +164,7 @@ Users with at least the Developer role can create a protected branch. Prerequisites: -- **Allowed to push** is set to **No one** +- **Allowed to push and merge** is set to **No one** - **Allowed to merge** is set to **Developers**. You can create a protected branch by using the UI or API only. @@ -124,11 +191,7 @@ like the [GitLab workflow](../../topics/gitlab_flow.md). 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. 1. From the **Allowed to merge** list, select **Developers + Maintainers**. -1. From the **Allowed to push** list, select **No one**. - - NOTE: - Setting a role, group or user as **Allowed to push** also allows those users to merge. - +1. From the **Allowed to push and merge** list, select **No one**. 1. Select **Protect**. ## Allow everyone to push directly to a protected branch @@ -139,7 +202,7 @@ You can allow everyone with write access to push to the protected branch. 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. -1. From the **Allowed to push** list, select **Developers + Maintainers**. +1. From the **Allowed to push and merge** list, select **Developers + Maintainers**. 1. Select **Protect**. ## Allow deploy keys to push to a protected branch @@ -167,7 +230,7 @@ To allow a deploy key to push to a protected branch: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. -1. From the **Allowed to push** list, select the deploy key. +1. From the **Allowed to push and merge** list, select the deploy key. 1. Select **Protect**. Deploy keys are not available in the **Allowed to merge** dropdown list. @@ -186,7 +249,7 @@ To protect a new branch and enable force push: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. -1. From the **Allowed to push** and **Allowed to merge** lists, select the settings you want. +1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want. 1. To allow all users with push access to force push, turn on the **Allowed to force push** toggle. 1. To reject code pushes that change files listed in the `CODEOWNERS` file, turn on the **Require approval from code owners** toggle. @@ -203,10 +266,9 @@ Members who can push to this branch can now also force push. ## Require Code Owner approval on a protected branch **(PREMIUM)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab 12.4. -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in GitLab 13.5, users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. This means they can skip merge request approval rules. -For a protected branch, you can require at least one approval by a [Code Owner](code_owners.md). +For a protected branch, you can require at least one approval by a [Code Owner](codeowners/index.md). To protect a new branch and enable Code Owner's approval: @@ -214,7 +276,7 @@ To protect a new branch and enable Code Owner's approval: 1. On the left sidebar, select **Settings > Repository**. 1. Expand **Protected branches**. 1. From the **Branch** dropdown list, select the branch you want to protect. -1. From the **Allowed to push** and **Allowed to merge** lists, select the settings you want. +1. From the **Allowed to push and merge** and **Allowed to merge** lists, select the settings you want. 1. Turn on the **Require approval from code owners** toggle. 1. Select **Protect**. @@ -262,6 +324,12 @@ Protected branches can only be deleted by using GitLab either from the UI or API This prevents accidentally deleting a branch through local Git commands or third-party Git clients. +## Related topics + +- [Protected branches API](../../api/protected_branches.md) +- [Branches](repository/branches/index.md) +- [Branches API](../../api/branches.md) + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues |