Document the new behavior of protected branches
This commit is contained in:
parent
12fe6a6fd7
commit
f83c5d2434
Binary file not shown.
Before Width: | Height: | Size: 23 KiB After Width: | Height: | Size: 19 KiB |
Binary file not shown.
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 16 KiB |
Binary file not shown.
After Width: | Height: | Size: 17 KiB |
|
@ -5,6 +5,8 @@ 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.
|
||||
|
||||
## Overview
|
||||
|
||||
By default, a protected branch does four simple things:
|
||||
|
||||
- it prevents its creation, if not already created, from everybody except users
|
||||
|
@ -15,6 +17,11 @@ By default, a protected branch does four simple things:
|
|||
|
||||
See the [Changelog](#changelog) section for changes over time.
|
||||
|
||||
>
|
||||
>Added benefits for GitLab Enterprise Edition:
|
||||
>
|
||||
>- Restrict push and merge access to [certain users][ee-restrict]
|
||||
|
||||
## Configuring protected branches
|
||||
|
||||
To protect a branch, you need to have at least Master permission level. Note
|
||||
|
@ -28,26 +35,45 @@ that the `master` branch is protected by default.
|
|||
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.
|
||||
|
||||
![Choose protected branch](img/protected_branches_choose_branch.png)
|
||||
![Protected branches page](img/protected_branches_page.png)
|
||||
|
||||
1. Once done, the protected branch will appear in the "Already protected" list.
|
||||
1. Once done, the protected branch will appear in the "Protected branches" list.
|
||||
|
||||
![Protected branches list](img/protected_branches_list.png)
|
||||
|
||||
## Using the Allowed to merge and Allowed to push settings
|
||||
|
||||
Since GitLab 8.10, we added another layer of branch protection which provides
|
||||
more granular management of protected branches. You can now choose the option
|
||||
"Developers can merge" so that Developer users can merge a merge request but
|
||||
not directly push. In that case, your branches are protected from direct pushes,
|
||||
yet Developers don't need elevated permissions or wait for someone with a higher
|
||||
permission level to press merge.
|
||||
> This feature was [introduced][ce-5081] in GitLab 8.11.
|
||||
|
||||
You can set this option while creating the protected branch or after its
|
||||
creation.
|
||||
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
|
||||
allow/prohibit Masters 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 + Masters", to require _everyone_ to submit a merge request for
|
||||
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
|
||||
"Allowed to push" to "Developers + Masters".
|
||||
|
||||
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.
|
||||
|
||||
![Developers can push](img/protected_branches_devs_can_push.png)
|
||||
|
||||
If you don't choose any of those options while creating a protected branch,
|
||||
they are set to "Masters" by default.
|
||||
|
||||
## Wildcard protected branches
|
||||
|
||||
> [Introduced][ce-4665] in GitLab 8.10.
|
||||
> This feature was [introduced][ce-4665] in GitLab 8.10.
|
||||
|
||||
You can specify a wildcard protected branch, which will protect all branches
|
||||
matching the wildcard. For example:
|
||||
|
@ -66,40 +92,22 @@ Two different wildcards can potentially match the same branch. For example,
|
|||
In that case, if _any_ of these protected branches have a setting like
|
||||
"Allowed to push", then `production-stable` will also inherit this setting.
|
||||
|
||||
If you click on a protected branch's name that is created using a wildcard,
|
||||
you will be presented with a list of all matching branches:
|
||||
If you click on a protected branch's name, you will be presented with a list of
|
||||
all matching branches:
|
||||
|
||||
![Protected branch matches](img/protected_branches_matches.png)
|
||||
|
||||
## Restrict the creation of protected branches
|
||||
|
||||
Creating a protected branch or a list of protected branches using the wildcard
|
||||
feature, not only you are restricting pushes to those branches, but also their
|
||||
creation if not already created.
|
||||
|
||||
## Error messages when pushing to a protected branch
|
||||
|
||||
A user with insufficient permissions will be presented with an error when
|
||||
creating or pushing to a branch that's prohibited, either through GitLab's UI:
|
||||
|
||||
![Protected branch error GitLab UI](img/protected_branches_error_ui.png)
|
||||
|
||||
or using Git from their terminal:
|
||||
|
||||
```bash
|
||||
remote: GitLab: You are not allowed to push code to protected branches on this project.
|
||||
To https://gitlab.example.com/thedude/bowling.git
|
||||
! [remote rejected] staging-stable -> staging-stable (pre-receive hook declined)
|
||||
error: failed to push some refs to 'https://gitlab.example.com/thedude/bowling.git'
|
||||
```
|
||||
|
||||
## Changelog
|
||||
|
||||
**8.10.0**
|
||||
**8.10**
|
||||
|
||||
- Allow specifying protected branches using wildcards [gitlab-org/gitlab-ce!5081][ce-4665]
|
||||
- Allow specifying protected branches using wildcards [gitlab-org/gitlab-ce!5081][ce-5081]
|
||||
- Allow creating protected branches that can't be pushed to [gitlab-org/gitlab-ce!5081][ce-4665]
|
||||
|
||||
---
|
||||
|
||||
[ce-4665]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4665 "Allow specifying protected branches using wildcards"
|
||||
[ce-5081]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5081 "Allow creating protected branches that can't be pushed to"
|
||||
[ee-restrict]: http://docs.gitlab.com/ee/user/project/protected_branches.html#restricting-push-and-merge-access-to-certain-users
|
||||
|
|
Loading…
Reference in New Issue