summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorAchilleas Pipinellis <axilleas@axilleas.me>2016-08-21 10:59:19 +0300
committerAchilleas Pipinellis <axilleas@axilleas.me>2016-08-21 10:59:19 +0300
commitf83c5d243459c06fc80a4bf0e287ed59f83e009c (patch)
tree3ff7b658324d97c5317fb2f8737c4fde3ff205f4 /doc
parent12fe6a6fd733110acc72aa0f5bdaec2b1fa1f358 (diff)
downloadgitlab-ce-f83c5d243459c06fc80a4bf0e287ed59f83e009c.tar.gz
Document the new behavior of protected branches
Diffstat (limited to 'doc')
-rw-r--r--doc/user/project/img/protected_branches_devs_can_push.pngbin23976 -> 19312 bytes
-rw-r--r--doc/user/project/img/protected_branches_list.pngbin16817 -> 16223 bytes
-rw-r--r--doc/user/project/img/protected_branches_page.pngbin0 -> 17839 bytes
-rw-r--r--doc/user/project/protected_branches.md78
4 files changed, 43 insertions, 35 deletions
diff --git a/doc/user/project/img/protected_branches_devs_can_push.png b/doc/user/project/img/protected_branches_devs_can_push.png
index 9c33db36586..812cc8767b7 100644
--- a/doc/user/project/img/protected_branches_devs_can_push.png
+++ b/doc/user/project/img/protected_branches_devs_can_push.png
Binary files differ
diff --git a/doc/user/project/img/protected_branches_list.png b/doc/user/project/img/protected_branches_list.png
index 9f070f7a208..f33f1b2bdb6 100644
--- a/doc/user/project/img/protected_branches_list.png
+++ b/doc/user/project/img/protected_branches_list.png
Binary files differ
diff --git a/doc/user/project/img/protected_branches_page.png b/doc/user/project/img/protected_branches_page.png
new file mode 100644
index 00000000000..1585dde5b29
--- /dev/null
+++ b/doc/user/project/img/protected_branches_page.png
Binary files differ
diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md
index 96d9bdc1b29..330e0040998 100644
--- a/doc/user/project/protected_branches.md
+++ b/doc/user/project/protected_branches.md
@@ -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
+
+> This feature was [introduced][ce-5081] in GitLab 8.11.
+
+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.
-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.
+![Developers can push](img/protected_branches_devs_can_push.png)
-You can set this option while creating the protected branch or after its
-creation.
+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