protected_branches.md 7.27 KB
Newer Older
1 2 3 4 5 6 7
# Protected Branches

[Permissions](../permissions.md) in GitLab are fundamentally defined around the
idea of having read or write permission to the repository and branches. To
prevent people from messing with history or pushing code without review, we've
created protected branches.

8 9
## Overview

10 11 12
By default, a protected branch does four simple things:

- it prevents its creation, if not already created, from everybody except users
13
  who are allowed to merge
Mark Chao's avatar
Mark Chao committed
14
- it prevents pushes from everybody except users with Maintainer permission
15 16 17 18 19
- it prevents **anyone** from force pushing to the branch
- it prevents **anyone** from deleting the branch

See the [Changelog](#changelog) section for changes over time.

20
>
21
>Additional functionality for GitLab Enterprise Edition:
22 23 24
>
>- Restrict push and merge access to [certain users][ee-restrict]

25 26
## Configuring protected branches

Mark Chao's avatar
Mark Chao committed
27
To protect a branch, you need to have at least Maintainer permission level. Note
28 29
that the `master` branch is protected by default.

30 31
1. Navigate to your project's **Settings ➔ Repository**
1. Scroll to find the **Protected branches** section.
32 33 34
1. From the **Branch** dropdown menu, select the branch you want to protect and
   click **Protect**. In the screenshot below, we chose the `develop` branch.

35
    ![Protected branches page](img/protected_branches_page.png)
36

37
1. Once done, the protected branch will appear in the "Protected branches" list.
38 39 40

    ![Protected branches list](img/protected_branches_list.png)

41 42
## Using the Allowed to merge and Allowed to push settings

43
> [Introduced][ce-5081] in GitLab 8.11.
44 45 46 47

Since GitLab 8.11, we added another layer of branch protection which provides
more granular management of protected branches. The "Developers can push"
option was replaced by an "Allowed to push" setting which can be set to
Mark Chao's avatar
Mark Chao committed
48
allow/prohibit Maintainers and/or Developers to push to a protected branch.
49 50 51 52

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"
53
to "Developers + Maintainers", to require _everyone_ to submit a merge request for
54 55 56 57 58 59
changes going into the protected branch. This is compatible with workflows like
the [GitLab workflow](../../workflow/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
60
"Allowed to push" to "Developers + Maintainers".
61 62 63 64

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.
65

66
![Developers can push](img/protected_branches_devs_can_push.png)
67

68
If you don't choose any of those options while creating a protected branch,
Mark Chao's avatar
Mark Chao committed
69
they are set to "Maintainers" by default.
70 71 72

## Wildcard protected branches

73
> [Introduced][ce-4665] in GitLab 8.10.
74 75 76 77 78

You can specify a wildcard protected branch, which will protect all branches
matching the wildcard. For example:

| Wildcard Protected Branch | Matching Branches                                      |
79
|---------------------------|--------------------------------------------------------|
80 81 82 83 84 85 86 87 88 89 90 91
| `*-stable`                | `production-stable`, `staging-stable`                  |
| `production/*`            | `production/app-server`, `production/load-balancer`    |
| `*gitlab*`                | `gitlab`, `gitlab/staging`, `master/gitlab/production` |

Protected branch settings (like "Developers can push") apply to all matching
branches.

Two different wildcards can potentially match the same branch. For example,
`*-stable` and `production-*` would both match a `production-stable` branch.
In that case, if _any_ of these protected branches have a setting like
"Allowed to push", then `production-stable` will also inherit this setting.

92 93
If you click on a protected branch's name, you will be presented with a list of
all matching branches:
94 95 96

![Protected branch matches](img/protected_branches_matches.png)

97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
## Creating a protected branch

> [Introduced][https://gitlab.com/gitlab-org/gitlab-ce/issues/53361] in GitLab 11.9.

When a protected branch or wildcard protected branches are set to
[**No one** is **Allowed to push**](#using-the-allowed-to-merge-and-allowed-to-push-settings),
Developers (and users with higher [permission levels](../permissions.md)) are allowed
to create a new protected branch, but only via the UI or through the API (to avoid
creating protected branches accidentally from the command line or from a Git
client application).

To create a new branch through the user interface:

1. Visit **Repository > Branches**.
1. Click on **New branch**.
1. Fill in the branch name and select an existing branch, tag, or commit that
   the new branch will be based off. Only existing protected branches and commits
   that are already in protected branches will be accepted.

116 117 118 119 120 121 122
## Deleting a protected branch

> [Introduced][ce-21393] in GitLab 9.3.

From time to time, it may be required to delete or clean up branches that are
protected.

Mark Chao's avatar
Mark Chao committed
123
User with [Maintainer permissions][perm] and up can manually delete protected
124 125 126 127 128 129 130 131 132 133 134 135 136
branches via GitLab's web interface:

1. Visit **Repository > Branches**
1. Click on the delete icon next to the branch you wish to delete
1. In order to prevent accidental deletion, an additional confirmation is
   required

    ![Delete protected branches](img/protected_branches_delete.png)

Deleting a protected branch is only allowed via the web interface, not via Git.
This means that you can't accidentally delete a protected branch from your
command line or a Git client application.

137 138 139 140 141 142 143 144
## Running pipelines on protected branches

The permission to merge or push to protected branches is used to define if a user can
run CI/CD pipelines and execute actions on jobs that are related to those branches.

See [Security on protected branches](../../ci/pipelines.md#security-on-protected-branches)
for details about the pipelines security model.

145 146
## Changelog

147 148 149 150
**11.9**

- [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-ce/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface.

151 152 153 154
**9.2**

- Allow deletion of protected branches via the web interface [gitlab-org/gitlab-ce#21393][ce-21393]

155 156 157 158
**8.11**

- Allow creating protected branches that can't be pushed to [gitlab-org/gitlab-ce!5081][ce-5081]

159
**8.10**
160

161 162
- Allow developers to merge into a protected branch without having push access [gitlab-org/gitlab-ce!4892][ce-4892]
- Allow specifying protected branches using wildcards [gitlab-org/gitlab-ce!4665][ce-4665]
163 164 165 166

---

[ce-4665]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4665 "Allow specifying protected branches using wildcards"
167
[ce-4892]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4892 "Allow developers to merge into a protected branch without having push access"
168
[ce-5081]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5081 "Allow creating protected branches that can't be pushed to"
169
[ce-21393]: https://gitlab.com/gitlab-org/gitlab-ce/issues/21393
170
[ee-restrict]: http://docs.gitlab.com/ee/user/project/protected_branches.html#restricting-push-and-merge-access-to-certain-users
171
[perm]: ../permissions.md