Commit 40753f30 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'doc-protected-branches' into 'master'

Refactor protected branches documentation

Fixes https://gitlab.com/gitlab-org/gitlab-ce/issues/19832

See merge request !5419
parents 50124864 b48fd097
......@@ -6,12 +6,13 @@
= page_title
%p Keep stable branches secure and force developers to use merge requests.
%p.prepend-top-20
Protected branches are designed to:
By default, protected branches are designed to:
%ul
%li prevent pushes from everybody except #{link_to "masters", help_page_path("user/permissions"), class: "vlink"}
%li prevent anyone from force pushing to the branch
%li prevent anyone from deleting the branch
%p.append-bottom-0 Read more about #{link_to "project permissions", help_page_path("user/permissions"), class: "underlined-link"}
%li prevent their creation, if not already created, from everybody except Masters
%li prevent pushes from everybody except Masters
%li prevent <strong>anyone</strong> from force pushing to the branch
%li prevent <strong>anyone</strong> from deleting the branch
%p.append-bottom-0 Read more about #{link_to "protected branches", help_page_path("user/project/protected_branches"), class: "underlined-link"} and #{link_to "project permissions", help_page_path("user/permissions"), class: "underlined-link"}.
.col-lg-9
%h5.prepend-top-0
Protect a branch
......@@ -23,7 +24,7 @@
= f.label :name, "Branch", class: "label-light"
= render partial: "dropdown", locals: { f: f }
%p.help-block
= link_to "Wildcards", help_page_path('workflow/protected_branches', anchor: "wildcard-protected-branches")
= link_to "Wildcards", help_page_path('user/project/protected_branches', anchor: "wildcard-protected-branches")
such as
%code *-stable
or
......
# 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.
By default, a protected branch does four simple things:
- it prevents its creation, if not already created, from everybody except users
with Master permission
- it prevents pushes from everybody except users with Master permission
- 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.
## Configuring protected branches
To protect a branch, you need to have at least Master permission level. Note
that the `master` branch is protected by default.
1. Navigate to the main page of the project.
1. In the upper right corner, click the settings wheel and select **Protected branches**.
![Project settings list](img/project_settings_list.png)
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)
1. Once done, the protected branch will appear in the "Already protected" list.
![Protected branches list](img/protected_branches_list.png)
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.
You can set this option while creating the protected branch or after its
creation.
## Wildcard protected branches
>**Note:**
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:
| Wildcard Protected Branch | Matching Branches |
|---------------------------+--------------------------------------------------------|
| `*-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.
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:
![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**
- Allow specifying protected branches using wildcards [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"
......@@ -12,7 +12,7 @@
- [Project Features](project_features.md)
- [Project forking workflow](forking_workflow.md)
- [Project users](add-user/add-user.md)
- [Protected branches](protected_branches.md)
- [Protected branches](../user/project/protected_branches.md)
- [Sharing a project with a group](share_with_group.md)
- [Share projects with other groups](share_projects_with_other_groups.md)
- [Web Editor](web_editor.md)
......
# Protected Branches
Permissions 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.
A protected branch does three simple things:
* it prevents pushes from everybody except users with Master permission
* it prevents anyone from force pushing to the branch
* it prevents anyone from deleting the branch
You can make any branch a protected branch. GitLab makes the master branch a protected branch by default.
To protect a branch, user needs to have at least a Master permission level, see [permissions document](../user/permissions.md).
![protected branches page](protected_branches/protected_branches1.png)
Navigate to project settings page and select `protected branches`. From the `Branch` dropdown menu select the branch you want to protect.
Some workflows, like [GitLab workflow](gitlab_flow.md), require all users with write access to submit a Merge request in order to get the code into a protected branch.
Since Masters and Owners can already push to protected branches, that means Developers cannot push to protected branch and need to submit a Merge request.
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 selecting `Developers can push` check box.
On already protected branches you can also allow developers to push to the repository by selecting the `Developers can push` check box.
![Developers can push](protected_branches/protected_branches2.png)
## Wildcard Protected Branches
>**Note:**
This feature was added in GitLab 8.10.
1. You can specify a wildcard protected branch, which will protect all branches matching the wildcard. For example:
| Wildcard Protected Branch | Matching Branches |
|---------------------------+--------------------------------------------------------|
| `*-stable` | `production-stable`, `staging-stable` |
| `production/*` | `production/app-server`, `production/load-balancer` |
| `*gitlab*` | `gitlab`, `gitlab/staging`, `master/gitlab/production` |
1. Protected branch settings (like "Developers Can Push") apply to all matching branches.
1. Two different wildcards can potentially match the same branch. For example, `*-stable` and `production-*` would both match a `production-stable` branch.
>**Note:**
If _any_ of these protected branches have "Developers Can Push" set to true, then `production-stable` has it set to true.
1. If you click on a protected branch's name, you will be presented with a list of all matching branches:
![protected branch matches](protected_branches/protected_branches3.png)
This document is moved to [user/project/protected_branches.md](../user/project/protected_branches.md)
......@@ -36,7 +36,7 @@ describe HelpController do
context 'when requested file exists' do
it 'renders the raw file' do
get :show,
path: 'workflow/protected_branches/protected_branches1',
path: 'user/project/img/labels_filter',
format: :png
expect(response).to be_success
expect(response.content_type).to eq 'image/png'
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment