Skip to content

G
gitlab-ce
Commit 1950c267 authored by Craig Norris's avatar Craig Norris
Browse files
Options

Merge branch 'docs-aqualls-create-3' into 'master' 

Word and line reviews for Create documentation

See merge request gitlab-org/gitlab!52852
parents a56d6581 781109b5
Hide whitespace changes
Inline Side-by-side
Showing with 140 additions and 159 deletions
doc/user/project/code_owners.md
View file @ 1950c267
......@@ -7,9 +7,8 @@ type: reference
# Code Owners **(STARTER)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916)
in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in GitLab 11.3.
> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9.
## Introduction
......@@ -18,7 +17,7 @@ to find out who should review or approve merge requests.
Additionally, if you have a question over a specific file or
code block, it may be difficult to know who to find the answer from.
GitLab Code Owners is a feature to define who owns specific
The GitLab Code Owners feature defines who owns specific
files or paths in a repository, allowing other users to understand
who is responsible for each file or path.
......@@ -32,7 +31,7 @@ the process of finding the right reviewers and approvers for a given
merge request.
In larger organizations or popular open source projects, Code Owners
can also be useful to understand who to contact if you have
can help you understand who to contact if you have
a question that may not be related to code review or a merge request
approval.
......@@ -49,12 +48,12 @@ You can choose to add the `CODEOWNERS` file in three places:
- Inside the `docs/` directory
The `CODEOWNERS` file is valid for the branch where it lives. For example, if you change the code owners
in a feature branch, they won't be valid in the main branch until the feature branch is merged.
in a feature branch, the changes aren't valid in the main branch until the feature branch is merged.
If you introduce new files to your repository and you want to identify the code owners for that file,
you have to update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same
branch), GitLab will count the owners as soon as the branch is merged. If
you don't, you can do that later, but your new files will not belong to anyone until you update your
you must update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same
branch), GitLab counts the owners as soon as the branch is merged. If
you don't, you can do that later, but your new files don't belong to anyone until you update your
`CODEOWNERS` file in the TARGET branch.
When a file matches multiple entries in the `CODEOWNERS` file,
......@@ -73,29 +72,32 @@ The user that would show for `README.md` would be `@user2`.
## Approvals by Code Owners
Once you've added Code Owners to a project, you can configure it to
After you've added Code Owners to a project, you can configure it to
be used for merge request approvals:
- As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers).
- As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners). **(PREMIUM)**
Developer or higher [permissions](../permissions.md) are required in order to
Developer or higher [permissions](../permissions.md) are required to
approve a merge request.
Once set, Code Owners are displayed in merge requests widgets:
After it's set, Code Owners are displayed in merge request widgets:
![MR widget - Code Owners](img/code_owners_mr_widget_v12_4.png)
While the `CODEOWNERS` file can be used in addition to Merge Request [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules),
it can also be used as the sole driver of merge request approvals
(without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)).
To do so, create the file in one of the three locations specified above and
set the code owners as required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners).
Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files)
to specify the actual owners and granular permissions.
While you can use the `CODEOWNERS` file in addition to Merge Request
[Approval Rules](merge_requests/merge_request_approvals.md#approval-rules),
you can also use it as the sole driver of merge request approvals
without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules):
1. Create the file in one of the three locations specified above.
1. Set the code owners as required approvers for
[protected branches](protected_branches.md#protected-branches-approval-by-code-owners).
1. Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files)
to specify the actual owners and granular permissions.
Using Code Owners in conjunction with [Protected Branches](protected_branches.md#protected-branches-approval-by-code-owners)
will prevent any user who is not specified in the `CODEOWNERS` file from pushing
prevents any user who is not specified in the `CODEOWNERS` file from pushing
changes for the specified files/paths, except those included in the
**Allowed to push** column. This allows for a more inclusive push strategy, as
administrators don't have to restrict developers from pushing directly to the
......@@ -114,13 +116,13 @@ in the `.gitignore` file followed by one or more of:
- The `@name` of one or more groups that should be owners of the file.
- Lines starting with `#` are ignored.
The order in which the paths are defined is significant: the last pattern that
matches a given path will be used to find the code owners.
The path definition order is significant: the last pattern
matching a given path is used to find the code owners.
### Groups as Code Owners
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab Starter 12.1.
> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.0.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1.
> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0.
Groups and subgroups members are inherited as eligible Code Owners to a
project, as long as the hierarchy is respected.
......@@ -131,7 +133,7 @@ suppose you have a project called "Project A" within the group and a
"Project B" within the subgroup.
The eligible Code Owners to Project B are both the members of the Group X and
the Subgroup Y. And the eligible Code Owners to the Project A are just the
the Subgroup Y. The eligible Code Owners to the Project A are just the
members of the Group X, given that Project A doesn't belong to the Subgroup Y:
![Eligible Code Owners](img/code_owners_members_v13_4.png)
......@@ -142,9 +144,9 @@ Code Owners:
![Invite subgroup members to become eligible Code Owners](img/code_owners_invite_members_v13_4.png)
Once invited, any member (`@user`) of the group or subgroup can be set
as Code Owner to files of the Project A or B, as well as the entire Group X
(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as exemplified below:
After being invited, any member (`@user`) of the group or subgroup can be set
as Code Owner to files of the Project A or B, and the entire Group X
(`@group-x`) or Subgroup Y (`@group-x/subgroup-y`), as follows:
```plaintext
# A member of the group or subgroup as Code Owner to a file
......@@ -162,7 +164,7 @@ file.md @group-x @group-x/subgroup-y
### Code Owners Sections **(PREMIUM)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2 behind a feature flag, enabled by default.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab Premium 13.2 behind a feature flag, enabled by default.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4.
Code Owner rules can be grouped into named sections. This allows for better
......@@ -185,8 +187,8 @@ changes, to set their own independent patterns by specifying discrete sections i
teams can be added as reviewers.
Sections can be added to `CODEOWNERS` files as a new line with the name of the
section inside square brackets. Every entry following it is assigned to that
section. The following example would create 2 Code Owner rules for the "README
section inside square brackets. Every entry following is assigned to that
section. The following example would create two Code Owner rules for the "README
Owners" section:
```plaintext
......@@ -196,7 +198,7 @@ internal/README.md @user2
```
Multiple sections can be used, even with matching file or directory patterns.
Reusing the same section name will group the results together under the same
Reusing the same section name groups the results together under the same
section, with the most specific rule or last matching pattern being used. For
example, consider the following entries in a `CODEOWNERS` file:
......@@ -213,7 +215,7 @@ model/db @gl-database
README.md @gl-docs
```
This will result in 3 entries under the "Documentation" section header, and 2
This results in three entries under the "Documentation" section header, and two
entries under "Database". Case is not considered when combining sections, so in
this example, entries defined under the sections "Documentation" and
"DOCUMENTATION" would be combined into one, using the case of the first instance
......@@ -227,9 +229,10 @@ the rules for "Groups" and "Documentation" sections:
#### Optional Code Owners Sections **(PREMIUM)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.8 behind a feature flag, enabled by default.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8 behind a feature flag, enabled by default.
When you want to make a certain section optional, you can do so by adding a code owners section prepended with the caret `^` character. Approvals from owners listed in the section will **not** be required. For example:
To make a certain section optional, add a code owners section prepended with the
caret `^` character. Approvals from owners listed in the section are **not** required. For example:
```plaintext
[Documentation]
......@@ -242,13 +245,13 @@ When you want to make a certain section optional, you can do so by adding a code
*.go @root
```
The optional code owners section will be displayed in merge requests under the **Approval Rules** area:
The optional code owners section displays in merge requests under the **Approval Rules** area:
![MR widget - Optional Code Owners Sections](img/optional_code_owners_sections_v13_8.png)
If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails.
If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the requirement prevails.
For example, the code owners of the "Documentation" section below will still be required to approve merge requests:
For example, the code owners of the "Documentation" section below is still required to approve merge requests:
```plaintext
[Documentation]
......@@ -264,12 +267,12 @@ For example, the code owners of the "Documentation" section below will still be
*.txt @root
```
Optional sections in the code owners file are currently treated as optional only
when changes are submitted via merge requests. If a change is submitted directly
to the protected branch, approval from code owners will still be required, even if the
section is marked as optional. We plan to change this in a
Optional sections in the code owners file are treated as optional only
when changes are submitted by using merge requests. If a change is submitted directly
to the protected branch, approval from code owners is still required, even if the
section is marked as optional. We plan to change this behavior in a
[future release](https://gitlab.com/gitlab-org/gitlab/-/issues/297638),
where direct pushes to the protected branch will be allowed for sections marked as optional.
and allow direct pushes to the protected branch for sections marked as optional.
## Example `CODEOWNERS` file
......
doc/user/project/highlighting.md
View file @ 1950c267
......@@ -7,7 +7,7 @@ type: reference
# Syntax Highlighting
GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It will try to guess what language to use based on the file extension, which most of the time is sufficient.
GitLab provides syntax highlighting on all files through the [Rouge](https://rubygems.org/gems/rouge) Ruby gem. It attempts to guess what language to use based on the file extension, which most of the time is sufficient.
NOTE:
The [Web IDE](web_ide/index.md) and [Snippets](../snippets.md) use [Monaco Editor](https://microsoft.github.io/monaco-editor/)
......@@ -25,10 +25,10 @@ you can add the following to your `.gitattributes` file:
```
<!-- vale gitlab.Spelling = NO -->
When you check in and push that change, all `*.pl` files in your project will be highlighted as Prolog.
When you check in and push that change, all `*.pl` files in your project are highlighted as Prolog.
<!-- vale gitlab.Spelling = YES -->
The paths here are simply Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is:
The paths here are Git's built-in [`.gitattributes` interface](https://git-scm.com/docs/gitattributes). So, if you were to invent a file format called a `Nicefile` at the root of your project that used Ruby syntax, all you need is:
``` conf
/Nicefile gitlab-language=ruby
......@@ -44,7 +44,8 @@ To disable highlighting entirely, use `gitlab-language=text`. Lots more fun shen
/other-file gitlab-language=text?token=Error
```
Please note that these configurations will only take effect when the `.gitattributes` file is in your default branch (usually `master`).
Please note that these configurations only take effect when the `.gitattributes`
file is in your default branch (usually `master`).
NOTE:
The Web IDE does not support `.gitattribute` files, but it's [planned for a future release](https://gitlab.com/gitlab-org/gitlab/-/issues/22014).
doc/user/project/index.md
View file @ 1950c267
......@@ -17,12 +17,12 @@ the number of private projects you create.
## Project features
When you create a project in GitLab, you'll have access to a large number of
When you create a project in GitLab, you receive access to a large number of
[features](https://about.gitlab.com/features/):
**Repositories:**
- [Issue tracker](issues/index.md): Discuss implementations with your team within issues
- [Issue tracker](issues/index.md): Discuss implementations with your team in issues
- [Issue Boards](issue_board.md): Organize and prioritize your workflow
- [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project
- [Repositories](repository/index.md): Host your code in a fully
......@@ -42,13 +42,13 @@ When you create a project in GitLab, you'll have access to a large number of
**Issues and merge requests:**
- [Issue tracker](issues/index.md): Discuss implementations with your team within issues
- [Issue tracker](issues/index.md): Discuss implementations with your team in issues
- [Issue Boards](issue_board.md): Organize and prioritize your workflow
- [Multiple Issue Boards](issue_board.md#multiple-issue-boards): Allow your teams to create their own workflows (Issue Boards) for the same project
- [Merge Requests](merge_requests/index.md): Apply your branching
strategy and get reviewed by your team
- [Merge Request Approvals](merge_requests/merge_request_approvals.md): Ask for approval before
implementing a change **(STARTER)**
implementing a change
- [Fix merge conflicts from the UI](merge_requests/resolve_conflicts.md):
Your Git diff tool right from the GitLab UI
- [Review Apps](../../ci/review_apps/index.md): Live preview the results
......@@ -108,7 +108,7 @@ When you create a project in GitLab, you'll have access to a large number of
- [Conan packages](../packages/conan_repository/index.md): your private Conan repository in GitLab.
- [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab.
- [NPM packages](../packages/npm_registry/index.md): your private NPM package registry in GitLab.
- [Code owners](code_owners.md): specify code owners for certain files **(STARTER)**
- [Code owners](code_owners.md): specify code owners for certain files
- [License Compliance](../compliance/license_compliance/index.md): approve and deny licenses for projects. **(ULTIMATE)**
- [Dependency List](../application_security/dependency_list/index.md): view project dependencies. **(ULTIMATE)**
- [Requirements](requirements/index.md): Requirements allow you to create criteria to check your products against. **(ULTIMATE)**
......@@ -192,7 +192,7 @@ To delete a project, first navigate to the home page for that project.
1. Click **Delete project**
1. Confirm this action by typing in the expected text.
Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects within a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal).
Projects in personal namespaces are deleted immediately on request. For information on delayed deletion of projects in a group, please see [Enabling delayed project removal](../group/index.md#enabling-delayed-project-removal).
## CI/CD for external repositories **(PREMIUM)**
......@@ -214,11 +214,11 @@ filtered by **Push events**, **Merge events**, **Issue events**, **Comments**,
### Leave a project
**Leave project** will only display on the project's dashboard
**Leave project** only displays on the project's dashboard
when a project is part of a group (under a
[group namespace](../group/index.md#namespaces)).
If you choose to leave a project you will no longer be a project
member, therefore, unable to contribute.
If you choose to leave a project you are no longer a project
member, and cannot contribute.
## Project's landing page
......@@ -230,15 +230,15 @@ with [permissions to view the project's code](../permissions.md#project-members-
- The content of a
[`README` or an index file](repository/#repository-readme-and-index-files)
is displayed (if any), followed by the list of directories within the
is displayed (if any), followed by the list of directories in the
project's repository.
- If the project doesn't contain either of these files, the
visitor will see the list of files and directories of the repository.
visitor sees the list of files and directories of the repository.
For users without permissions to view the project's code:
For users without permissions to view the project's code, GitLab displays:
- The wiki homepage is displayed, if any.
- The list of issues within the project is displayed.
- The wiki homepage, if any.
- The list of issues in the project.
## GitLab Workflow - VS Code extension
......@@ -259,15 +259,15 @@ Depending on the situation, different things apply.
When [renaming a user](../profile/index.md#changing-your-username),
[changing a group path](../group/index.md#changing-a-groups-path) or [renaming a repository](settings/index.md#renaming-a-repository):
- Existing web URLs for the namespace and anything under it (e.g., projects) will
- Existing web URLs for the namespace and anything under it (such as projects) will
redirect to the new URLs.
- Starting with GitLab 10.3, existing Git remote URLs for projects under the
namespace will redirect to the new remote URL. Every time you push/pull to a
namespace redirect to the new remote URL. Every time you push/pull to a
repository that has changed its location, a warning message to update
your remote will be displayed instead of rejecting your action.
This means that any automation scripts, or Git clients will continue to
your remote is displayed instead of rejecting your action.
This means that any automation scripts, or Git clients continue to
work after a rename, making any transition a lot smoother.
- The redirects will be available as long as the original path is not claimed by
- The redirects are available as long as the original path is not claimed by
another group, user or project.
## Use your project as a Go package
......@@ -278,11 +278,11 @@ and `godoc.org` discovery requests, including the
[`go-source`](https://github.com/golang/gddo/wiki/Source-Code-Links) meta tags.
Private projects, including projects in subgroups, can be used as a Go package,
but may require configuration to work correctly. GitLab will respond correctly
but may require configuration to work correctly. GitLab responds correctly
to `go get` discovery requests for projects that *are not* in subgroups,
regardless of authentication or authorization.
[Authentication](#authenticate-go-requests) is required to use a private project
in a subgroup as a Go package. Otherwise, GitLab will truncate the path for
in a subgroup as a Go package. Otherwise, GitLab truncates the path for
private projects in subgroups to the first two segments, causing `go get` to
fail.
......@@ -302,10 +302,10 @@ queries), and [`GONOSUMDB`](../../development/go_guide/dependencies.md#fetching)
`GOPRIVATE`, `GONOPROXY`, and `GONOSUMDB` are comma-separated lists of Go
modules and Go module prefixes. For example,
`GOPRIVATE=gitlab.example.com/my/private/project` will disable queries for that
one project, but `GOPRIVATE=gitlab.example.com` will disable queries for *all*
projects on GitLab.com. Go will not query module proxies if the module name or a
prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go will not query checksum
`GOPRIVATE=gitlab.example.com/my/private/project` disables queries for that
one project, but `GOPRIVATE=gitlab.example.com` disables queries for *all*
projects on GitLab.com. Go does not query module proxies if the module name or a
prefix of it appears in `GOPRIVATE` or `GONOPROXY`. Go does not query checksum
databases if the module name or a prefix of it appears in `GONOPRIVATE` or
`GONOSUMDB`.
......@@ -315,8 +315,8 @@ To authenticate requests to private projects made by Go, use a [`.netrc`
file](https://ec.haxx.se/usingcurl-netrc.html) and a [personal access
token](../profile/personal_access_tokens.md) in the password field. **This only
works if your GitLab instance can be accessed with HTTPS.** The `go` command
will not transmit credentials over insecure connections. This will authenticate
all HTTPS requests made directly by Go but will not authenticate requests made
does not transmit credentials over insecure connections. This authenticates
all HTTPS requests made directly by Go, but does not authenticate requests made
through Git.
For example:
......@@ -332,16 +332,18 @@ On Windows, Go reads `~/_netrc` instead of `~/.netrc`.
### Authenticate Git fetches
If a module cannot be fetched from a proxy, Go will fall back to using Git (for
GitLab projects). Git will use `.netrc` to authenticate requests. Alternatively,
Git can be configured to embed specific credentials in the request URL, or to
use SSH instead of HTTPS (as Go always uses HTTPS to fetch Git repositories):
If a module cannot be fetched from a proxy, Go falls back to using Git (for
GitLab projects). Git uses `.netrc` to authenticate requests. You can also
configure Git to either:
- Embed specific credentials in the request URL.
- Use SSH instead of HTTPS, as Go always uses HTTPS to fetch Git repositories.
```shell
# embed credentials in any request to GitLab.com:
# Embed credentials in any request to GitLab.com:
git config --global url."https://${user}:${personal_access_token}@gitlab.example.com".insteadOf "https://gitlab.example.com"
# use SSH instead of HTTPS:
# Use SSH instead of HTTPS:
git config --global url."git@gitlab.example.com".insteadOf "https://gitlab.example.com"
```
......@@ -354,7 +356,7 @@ visit the `/projects/:id` URL in your browser or other tool accessing the projec
## Project aliases **(PREMIUM SELF)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.1.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1.
When migrating repositories to GitLab and they are being accessed by other systems,
it's very useful to be able to access them using the same name especially when
......@@ -369,9 +371,9 @@ A project alias can be only created via API and only by GitLab administrators.
Follow the [Project Aliases API documentation](../../api/project_aliases.md) for
more details.
Once an alias has been created for a project (e.g., an alias `gitlab` for the
project `https://gitlab.com/gitlab-org/gitlab`), the repository can be cloned
using the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of
After an alias has been created for a project (such as an alias `gitlab` for the
project `https://gitlab.com/gitlab-org/gitlab`), you can clone the repository
with the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of
`git clone git@gitlab.com:gitlab-org/gitlab.git`).
## Project activity analytics overview **(ULTIMATE SELF)**
......
doc/user/project/protected_branches.md
View file @ 1950c267
......@@ -13,7 +13,7 @@ further restrictions on certain branches, they can be protected.
## Overview
By default, a protected branch does four simple things:
By default, a protected branch does these things:
- It prevents its creation, if not already created, from everybody except users
with Maintainer permission.
......@@ -30,49 +30,47 @@ The default branch protection level is set in the [Admin Area](../admin_area/set
## Configuring protected branches
To protect a branch, you need to have at least Maintainer permission level. Note
that the `master` branch is protected by default.
To protect a branch, you need to have at least Maintainer permission level.
The `master` branch is protected by default.
1. Navigate to your project's **Settings ➔ Repository**
1. In your project, go to **Settings > Repository**.
1. Scroll to find the **Protected branches** section.
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.
![Protected branches page](img/protected_branches_page_v12_3.png)
1. Once done, the protected branch will appear in the "Protected branches" list.
1. Once done, the protected branch displays in the **Protected branches** list.
![Protected branches list](img/protected_branches_list_v12_3.png)
## Using the Allowed to merge and Allowed to push settings
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in GitLab 8.11.
In GitLab 8.11 and later, 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 Maintainers and/or Developers to push to a protected branch.
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
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
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".
**Allowed to push** to "Developers + Maintainers".
You can set the "Allowed to push" and "Allowed to merge" options while creating
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.
dropdown list in the **Already protected** area.
![Developers can push](img/protected_branches_devs_can_push_v12_3.png)
If you don't choose any of those options while creating a protected branch,
they are set to "Maintainers" by default.
they are set to Maintainers by default.
### Allow Deploy Keys to push to a protected branch
......@@ -88,7 +86,7 @@ Deploy keys can be selected in the **Allowed to push** dropdown when:
- Defining a protected branch.
- Updating an existing branch.
Select a deploy key to allow the owner of the key to push to the chosen protected branch,
Select a deploy key to allow the key's owner to push to the chosen protected branch,
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.
......@@ -103,24 +101,20 @@ Deploy Keys are not available in the **Allowed to merge** dropdown.
## Restricting push and merge access to certain users **(STARTER)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.11.
With GitLab Enterprise Edition you can restrict access to protected branches
by choosing a role (Maintainers, Developers) as well as certain users. From the
by choosing a role (Maintainers, Developers) and certain users. From the
dropdown menu select the role and/or the users you want to have merge or push
access.
![Select roles and users](img/protected_branches_select_roles_and_users.png)
Click **Protect** and the branch will appear in the "Protected branch" list.
Click **Protect** and the branch displays in the **Protected branch** list.
![Roles and users list](img/protected_branches_select_roles_and_users_list.png)
## Wildcard protected branches
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665) in GitLab 8.10.
You can specify a wildcard protected branch, which will protect all branches
You can specify a wildcard protected branch, which protects all branches
matching the wildcard. For example:
| Wildcard Protected Branch | Matching Branches |
......@@ -129,15 +123,15 @@ matching the wildcard. For example:
| `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
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.
"Allowed to push", then `production-stable` also inherit this setting.
If you click on a protected branch's name, you will be presented with a list of
If you click on a protected branch's name, GitLab displays a list of
all matching branches:
![Protected branch matches](img/protected_branches_matches.png)
......@@ -151,41 +145,36 @@ When a protected branch or wildcard protected branches are set to
Developers (and users with higher [permission levels](../permissions.md)) are
allowed to create a new protected branch as long as they are
[**Allowed to merge**](#using-the-allowed-to-merge-and-allowed-to-push-settings).
This can only be done via the UI or through the API (to avoid creating protected
branches accidentally from the command line or from a Git client application).
This can only be done by using 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. Go to **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.
1. Fill in the branch name and select an existing branch, tag, or commit to
base the new branch on. Only existing protected branches and commits
that are already in protected branches are accepted.
## Deleting a protected branch
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393) in GitLab 9.3.
From time to time, it may be required to delete or clean up branches that are
protected.
From time to time, you may need to delete or clean up protected branches.
User with [Maintainer permissions](../permissions.md) and greater can manually delete protected
branches by using the GitLab web interface:
User with [Maintainer permissions](../permissions.md) and up can manually delete protected
branches via the GitLab 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
1. Go to **Repository > Branches**.
1. Click on the delete icon next to the branch you wish to delete.
1. 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.
Deleting a protected branch is allowed only by using the web interface; not from Git.
This means that you can't accidentally delete a protected branch from your
command line or a Git client application.
## Protected Branches approval by Code Owners **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 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
[Code Owner](code_owners.md) to a file changed by the
......@@ -208,7 +197,7 @@ To enable Code Owner's approval to branches already protected:
![Code Owners approval - branch already protected](img/code_owners_approval_protected_branch_v12_4.png)
When enabled, all merge requests targeting these branches will require approval
When enabled, all merge requests targeting these branches require approval
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.
......@@ -224,26 +213,9 @@ for details about the pipelines security model.
## Changelog
**13.5**
- [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769).
**11.9**
- [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361) by Developers (and users with higher permission levels) through the API and the user interface.
**9.2**
- Allow deletion of protected branches via the web interface ([issue #21393](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21393)).
**8.11**
- Allow creating protected branches that can't be pushed to ([merge request !5081](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5081)).
**8.10**
- Allow developers without push access to merge into a protected branch ([merge request !4892](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4892)).
- Allow specifying protected branches using wildcards ([merge request !4665](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/4665)).
- **13.5**: [Allow Deploy keys to push to protected branches once more](https://gitlab.com/gitlab-org/gitlab/-/issues/30769).
- **11.9**: [Allow protected branches to be created](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53361)
by Developers (and users with higher permission levels) through the API and the user interface.
<!-- ## Troubleshooting
......
doc/user/project/protected_tags.md
View file @ 1950c267
......@@ -15,11 +15,13 @@ This feature evolved out of [protected branches](protected_branches.md)
## Overview
Protected tags will prevent anyone from updating or deleting the tag, and will prevent creation of matching tags based on the permissions you have selected. By default, anyone without Maintainer permission will be prevented from creating tags.
Protected tags prevent anyone from updating or deleting the tag, and prevent
creation of matching tags based on the permissions you have selected. By default,
anyone without Maintainer [permissions](../permissions.md) is prevented from creating tags.
## Configuring protected tags
To protect a tag, you need to have at least Maintainer permission level.
To protect a tag, you need to have at least Maintainer [permissions](../permissions.md).
1. Navigate to the project's **Settings > Repository**:
......@@ -29,17 +31,18 @@ To protect a tag, you need to have at least Maintainer permission level.
![Protected tags page](img/protected_tags_page_v12_3.png)
1. From the **Allowed to create** dropdown, select who will have permission to create matching tags and then click **Protect**:
1. From the **Allowed to create** dropdown, select users with permission to create
matching tags, and click **Protect**:
![Allowed to create tags dropdown](img/protected_tags_permissions_dropdown_v12_3.png)
1. Once done, the protected tag will appear in the **Protected tags** list:
1. After done, the protected tag displays in the **Protected tags** list:
![Protected tags list](img/protected_tags_list_v12_3.png)
## Wildcard protected tags
You can specify a wildcard protected tag, which will protect all tags
You can specify a wildcard protected tag, which protects all tags
matching the wildcard. For example:
| Wildcard Protected Tag | Matching Tags |
......@@ -52,9 +55,9 @@ matching the wildcard. For example:
Two different wildcards can potentially match the same tag. For example,
`*-stable` and `production-*` would both match a `production-stable` tag.
In that case, if _any_ of these protected tags have a setting like
**Allowed to create**, then `production-stable` will also inherit this setting.
**Allowed to create**, then `production-stable` also inherit this setting.
If you click on a protected tag's name, you will be presented with a list of
If you click on a protected tag's name, GitLab displays a list of
all matching tags:
![Protected tag matches](img/protected_tag_matches.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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7