=(s_("ProtectedBranch|%{wildcards_link_start}Wildcards%{wildcards_link_end} such as %{code_tag_start}*-stable%{code_tag_end} or %{code_tag_start}production/*%{code_tag_end} are supported.")%{wildcards_link_start: wildcards_link_start,wildcards_link_end: '</a>',code_tag_start: '<code>',code_tag_end: '</code>'}).html_safe
=(s_("ProtectedBranch|%{wildcards_link_start}Wildcards%{wildcards_link_end} such as %{code_tag_start}*-stable%{code_tag_end} or %{code_tag_start}production/*%{code_tag_end} are supported.")%{wildcards_link_start: wildcards_link_start,wildcards_link_end: '</a>',code_tag_start: '<code>',code_tag_end: '</code>'}).html_safe
|**[Audit events](audit_events.md)**<br>To maintain the integrity of your code, GitLab Enterprise Edition Premium gives administrators the ability to view any modifications made within the GitLab server in an advanced audit events system, so you can control, analyze, and track every change. | Premium+ | **{check-circle}** Yes | Instance, Group, Project |
|**[Audit events](audit_events.md)**<br>To maintain the integrity of your code, GitLab Enterprise Edition Premium gives administrators the ability to view any modifications made within the GitLab server in an advanced audit events system, so you can control, analyze, and track every change. | Premium+ | **{check-circle}** Yes | Instance, Group, Project |
|**[Auditor users](auditor_users.md)**<br>Auditor users are users who are given read-only access to all projects, groups, and other resources on the GitLab instance. | Premium+ | **{dotted-circle}** No | Instance |
|**[Auditor users](auditor_users.md)**<br>Auditor users are users who are given read-only access to all projects, groups, and other resources on the GitLab instance. | Premium+ | **{dotted-circle}** No | Instance |
|**[Credentials inventory](../user/admin_area/credentials_inventory.md)**<br>With a credentials inventory, GitLab administrators can keep track of the credentials used by all of the users in their GitLab instance. | Ultimate | **{dotted-circle}** No | Instance |
|**[Credentials inventory](../user/admin_area/credentials_inventory.md)**<br>With a credentials inventory, GitLab administrators can keep track of the credentials used by all of the users in their GitLab instance. | Ultimate | **{dotted-circle}** No | Instance |
|**Separation of Duties using [Protected branches](../user/project/protected_branches.md#protected-branches-approval-by-code-owners) and [custom CI Configuration Paths](../ci/pipelines/settings.md#custom-cicd-configuration-file)**<br> GitLab Premium users can leverage the GitLab cross-project YAML configurations to define deployers of code and developers of code. View the [Separation of Duties Deploy Project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and [Separation of Duties Project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md) to see how to use this set up to define these roles. | Premium+ | **{check-circle}** Yes | Project |
|**Separation of Duties using [Protected branches](../user/project/protected_branches.md#require-code-owner-approval-on-a-protected-branch) and [custom CI Configuration Paths](../ci/pipelines/settings.md#custom-cicd-configuration-file)**<br> GitLab Premium users can leverage the GitLab cross-project YAML configurations to define deployers of code and developers of code. View the [Separation of Duties Deploy Project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and [Separation of Duties Project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md) to see how to use this set up to define these roles. | Premium+ | **{check-circle}** Yes | Project |
|**[Compliance frameworks](../user/project/settings/index.md#compliance-frameworks)**<br>Create a custom compliance framework at the group level to describe the type of compliance requirements any child project needs to follow. | Premium+ | **{check-circle}** Yes | Group |
|**[Compliance frameworks](../user/project/settings/index.md#compliance-frameworks)**<br>Create a custom compliance framework at the group level to describe the type of compliance requirements any child project needs to follow. | Premium+ | **{check-circle}** Yes | Group |
|**[Compliance pipelines](../user/project/settings/index.md#compliance-pipeline-configuration)**<br>Define a pipeline configuration to run for any projects with a given compliance framework. | Ultimate | **{check-circle}** Yes | Group |
|**[Compliance pipelines](../user/project/settings/index.md#compliance-pipeline-configuration)**<br>Define a pipeline configuration to run for any projects with a given compliance framework. | Ultimate | **{check-circle}** Yes | Group |
|**[Compliance dashboard](../user/compliance/compliance_dashboard/index.md)**<br>Quickly get visibility into the compliance posture of your organization. | Ultimate | **{check-circle}** Yes | Group |
|**[Compliance dashboard](../user/compliance/compliance_dashboard/index.md)**<br>Quickly get visibility into the compliance posture of your organization. | Ultimate | **{check-circle}** Yes | Group |
### Example with user / group level access **(PREMIUM)**
### Example with user / group level access **(PREMIUM)**
Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the
Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the
form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users) and were [added to the API](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3516) in GitLab 10.3 EE.
form `{user_id: integer}`, `{group_id: integer}`, or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md).
```shell
```shell
curl --request POST --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1"
curl --request POST --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1"
@@ -195,7 +195,7 @@ The following table lists project permissions available for each role:
...
@@ -195,7 +195,7 @@ The following table lists project permissions available for each role:
1. Guest users can only view the confidential issues they created themselves.
1. Guest users can only view the confidential issues they created themselves.
1. If **Public pipelines** is enabled in **Project Settings > CI/CD**.
1. If **Public pipelines** is enabled in **Project Settings > CI/CD**.
1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md).
1. Not allowed for Guest, Reporter, Developer, Maintainer, or Owner. See [protected branches](project/protected_branches.md).
1. If the [branch is protected](project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings), this depends on the access Developers and Maintainers are given.
1. If the [branch is protected](project/protected_branches.md), this depends on the access Developers and Maintainers are given.
1. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see repository information like tags and commits.
1. Guest users can access GitLab [**Releases**](project/releases/index.md) for downloading assets but are not allowed to download the source code nor see repository information like tags and commits.
1. Actions are limited only to records owned (referenced) by user.
1. Actions are limited only to records owned (referenced) by user.
1. When [Share Group Lock](group/index.md#prevent-a-project-from-being-shared-with-groups) is enabled the project can't be shared with other groups. It does not affect group with group sharing.
1. When [Share Group Lock](group/index.md#prevent-a-project-from-being-shared-with-groups) is enabled the project can't be shared with other groups. It does not affect group with group sharing.
...
@@ -223,7 +223,7 @@ which visibility level you select on project settings.
...
@@ -223,7 +223,7 @@ which visibility level you select on project settings.
Additional restrictions can be applied on a per-branch basis with [protected branches](project/protected_branches.md).
Additional restrictions can be applied on a per-branch basis with [protected branches](project/protected_branches.md).
Additionally, you can customize permissions to allow or prevent project
Additionally, you can customize permissions to allow or prevent project
Maintainers and Developers from pushing to a protected branch. Read through the documentation on
Maintainers and Developers from pushing to a protected branch. Read through the documentation on
[Allowed to Merge and Allowed to Push settings](project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings)
@@ -25,12 +25,12 @@ these restrictions on the branch.
...
@@ -25,12 +25,12 @@ these restrictions on the branch.
| Force push to the branch | No one. |
| Force push to the branch | No one. |
| Delete the branch | No one. |
| Delete the branch | No one. |
(*) Users with developer permissions can create a project in a group,
(*) Users with the Developer role can create a project in a group,
but might not be allowed to initially push to the [default branch](repository/branches/default.md).
but might not be allowed to initially push to the [default branch](repository/branches/default.md).
### Set the branch protection default level
### Set the default branch protection level
The default branch protection level is set in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection).
Administrators can set a default branch protection level in the [Admin Area](../admin_area/settings/visibility_and_access_controls.md#default-branch-protection).
## Configure a protected branch
## Configure a protected branch
...
@@ -43,140 +43,108 @@ To protect a branch:
...
@@ -43,140 +43,108 @@ To protect a branch:
1. Go to your project and select **Settings > Repository**.
1. Go to your project and select **Settings > Repository**.
1. Expand **Protected branches**.
1. Expand **Protected branches**.
1. From the **Branch** dropdown menu, select the branch you want to protect.
1. From the **Branch** dropdown menu, 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. Select **Protect**.
1. Select **Protect**.
The protected branch displays in the **Protected branches** list.
The protected branch displays in the list of protected branches.
## Using the Allowed to merge and Allowed to push settings
## Configure multiple protected branches by using a wildcard
In GitLab 8.11 and later, we added another layer of branch protection which provides
Prerequisite:
more granular management of protected branches. The **Developers can push**
option was replaced by **Allowed to push**. You can set this value to allow
or prohibit Maintainers and/or Developers to push to a protected branch.
Using the **Allowed to push** and **Allowed to merge** settings, you can control
the actions that different roles can perform with the protected branch.
For example, you could set **Allowed to push** to "No one", and **Allowed to merge**
to "Developers + Maintainers", to require everyone to submit a merge request for
changes going into the protected branch. This is compatible with workflows like
the [GitLab workflow](../../topics/gitlab_flow.md).
However, there are workflows where that is not needed, and only protecting from
force pushes and branch removal is useful. For those workflows, you can allow
everyone with write access to push to a protected branch by setting
**Allowed to push** to "Developers + Maintainers".
You can set the **Allowed to push** and **Allowed to merge** options while creating
a protected branch or afterwards by selecting the option you want from the
dropdown list in the **Already protected** area.
If you don't choose any of those options while creating a protected branch,
they are set to Maintainers by default.
### Allow deploy keys to push to a protected branch
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30769) in GitLab 13.7.
> - This feature is being selectively deployed in GitLab.com 13.7, and may not be available for all users.
> - This feature is available for all users in GitLab 13.9.
You can allow specific machines to access protected branches in your repository with
[deploy keys](deploy_keys/index.md). This can be useful for your CI/CD workflow,
for example.
Deploy keys can be selected in the **Allowed to push** dropdown when:
- Defining a protected branch.
- You must have at least the [Maintainer role](../permissions.md).
- Updating an existing branch.
Select a deploy key to allow the key's owner to push to the chosen protected branch,
To protect multiple branches at the same time:
even if they aren't a member of the related project. The owner of the selected deploy
key must have at least read access to the given project.
For a deploy key to be selectable:
1. Go to your project and select **Settings > Repository**.
1. Expand **Protected branches**.
1. From the **Branch** dropdown menu, type the branch name and a wildcard.
For example:
- It must be [enabled for your project](deploy_keys/index.md#how-to-enable-deploy-keys).
| Wildcard protected branch | Matching branches |
- It must have [write access](deploy_keys/index.md#deploy-keys-permissions) to your project repository.
1. Go to your project and select **Settings > Repository**.
1. Expand **Protected branches**.
1. From the **Branch** dropdown menu, select the branch you want to protect.
1. From the **Allowed to push** list, select the deploy key.
1. Select **Protect**.
Deleting a protected branch is allowed only by using the web interface; not from Git.
Deploy keys are not available in the **Allowed to merge** dropdown.
This means that you can't accidentally delete a protected branch from your
command line or a Git client application.
## Allow force push on protected branches
## Allow force push on a protected branch
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 behind a disabled feature flag.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15611) in GitLab 13.10 behind a disabled feature flag.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323431) in GitLab 14.0.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/323431) in GitLab 14.0.
...
@@ -185,68 +153,77 @@ WARNING:
...
@@ -185,68 +153,77 @@ WARNING:
This feature might not be available to you. Check the **version history** note above for details.
This feature might not be available to you. Check the **version history** note above for details.
You can allow [force pushes](../../topics/git/git_rebase.md#force-push) to
You can allow [force pushes](../../topics/git/git_rebase.md#force-push) to
protected branches by either setting **Allowed to force push**
protected branches.
when you protect a new branch, or by configuring an already-protected branch.
To protect a new branch and enable Force push:
To protect a new branch and enable force push:
1.Navigate to your project's**Settings > Repository**.
1.Go to your project and select**Settings > Repository**.
1. Expand **Protected branches**, and scroll to **Protect a branch**.
1. Expand **Protected branches**.
1.Select a **Branch** or wildcard you'd like to protect.
1.From the **Branch** dropdown menu, select the branch you want to protect.
1.Select the user levels **Allowed to merge** and **Allowed to push**.
1.From the **Allowed to push** and **Allowed to merge** lists, select the settings you want.
1. To allow all users with push access to force push, toggle the **Allowed to force push** slider.
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, toggle
1. To reject code pushes that change files listed in the `CODEOWNERS` file, turn on the
**Require approval from code owners**.
**Require approval from code owners** toggle.
1.Click**Protect**.
1.Select**Protect**.
To enable force pushes on branches already protected:
To enable force pushes on branches that are already protected:
1.Navigate to your project's**Settings > Repository**.
1.Go to your project and select**Settings > Repository**.
1. Expand **Protected branches** and scroll to **Protected branch**.
1. Expand **Protected branches**.
1.Toggle the **Allowed to force push** slider for the chosen branch.
1.In the list of protected branches, next to the branch, turn on the **Allowed to force push** toggle.
When enabled, members who are allowed to push to this branch can also force push.
When enabled, members who are can push to this branch can also force push.
## Protected branches approval by Code Owners **(PREMIUM)**
## Require Code Owner approval on a protected branch **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in GitLab Premium 12.4.
It is possible to require at least one approval by a
You can require at least one approval by a
[Code Owner](code_owners.md) to a file changed by the
[Code Owner](code_owners.md) to a file changed by the
merge request. You can either set Code Owners approvals
merge request.
at the time you protect a new branch, or set it to a branch
already protected, as described below.
To protect a new branch and enable Code Owner's approval:
To protect a new branch and enable Code Owner's approval:
1. Navigate to your project's **Settings > Repository** and expand **Protected branches**.
1. Go to your project and select **Settings > Repository**.
1. Scroll down to **Protect a branch**, select a **Branch** or wildcard you'd like to protect, select who's **Allowed to merge** and **Allowed to push**, and toggle the **Require approval from code owners** slider.
1. Expand **Protected branches**.
1. Click **Protect**.
1. From the **Branch** dropdown menu, select the branch you want to protect.
1. From the **Allowed to push** and **Allowed to merge** lists, select the settings you want.
1. Turn on the **Require approval from code owners** toggle.
1. Select **Protect**.
To enable Code Owner's approval to branches already protected:
To enable Code Owner's approval on branches that are already protected:
1. Navigate to your project's **Settings > Repository** and expand **Protected branches**.
1. Go to your project and select **Settings > Repository**.
1. Scroll down to **Protected branch** and toggle the **Code owner approval** slider for the chosen branch.
1. Expand **Protected branches**.
1. In the list of protected branches, next to the branch, turn on the **Code owner approval** toggle.
When enabled, all merge requests targeting these branches require approval
When enabled, all merge requests for these branches require approval
by a Code Owner per matched rule before they can be merged.
by a Code Owner per matched rule before they can be merged.
Additionally, direct pushes to the protected branch are denied if a rule is matched.
Additionally, direct pushes to the protected branch are denied if a rule is matched.
[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, users and groups who are allowed to push to protected branches do not require a merge request to merge their feature branches. Thus, they can skip merge request approval rules.
[In](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5 and later,
users and groups who can push to protected branches do not have to use a merge request to merge their feature branches. Thus, they can skip merge request approval rules.
## Running pipelines on protected branches
## Run pipelines on protected branches
The permission to merge or push to protected branches is used to define if a user can
The permission to merge or push to protected branches defines
run CI/CD pipelines and execute actions on jobs that are related to those branches.
whether or not a user can run CI/CD pipelines and execute actions on jobs.
See [Security on protected branches](../../ci/pipelines/index.md#pipeline-security-on-protected-branches)
See [Security on protected branches](../../ci/pipelines/index.md#pipeline-security-on-protected-branches)
for details about the pipelines security model.
for details about the pipelines security model.
## Changelog
## Delete a protected branch
Users with the [Maintainer role](../permissions.md) and greater can manually delete protected
branches by using the GitLab web interface:
1. Go to **Repository > Branches**.
1. Next to the branch you want to delete, select the **Delete** button (**{remove}**).
1. On the confirmation dialog, type the branch name and select **Delete protected branch**.
-**13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769).
You can delete a protected branch from the UI only.
-**11.9**: [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361)
This prevents you from accidentally deleting a branch
by Developers (and users with higher permission levels) through the API and the user interface.
from the command line or from a Git client application.
