Skip to content

G
gitlab-ce
Commit 89ffe893 authored by Suzanne Selhorn's avatar Suzanne Selhorn
Browse files
Options

Merge branch 'selhorn-code-owners-3' into 'master' 

Pared down Code Owners page

See merge request gitlab-org/gitlab!66875
parents b7beeeb2 ec2cfba1
Hide whitespace changes
Inline Side-by-side
Showing with 108 additions and 147 deletions
doc/raketasks/backup_restore.md
View file @ 89ffe893
......@@ -1481,7 +1481,7 @@ If this happens, examine the following:
> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#disable-or-enable-gitaly-backup).
There can be
[risks when disabling released features](../user/feature_flags.md#risks-when-disabling-released-features).
[risks when disabling released features](../administration/feature_flags.md#risks-when-disabling-released-features).
Refer to this feature's version history for more details.
`gitaly-backup` is used by the backup Rake task to create and restore repository backups from Gitaly.
......
doc/user/admin_area/settings/help_page.md
View file @ 89ffe893
......@@ -67,7 +67,7 @@ You can specify a custom URL to which users are directed when they:
> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-gitlab-documentation-link-redirects). **(FREE SELF)**
This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development).
[risks when enabling features still in development](../../../administration/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details.
Documentation links go to the `/help` section on the instance by default, but you can
......
doc/user/project/code_owners.md
View file @ 89ffe893
......@@ -11,7 +11,7 @@ type: reference
> - Code Owners for merge request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9.
> - Moved to GitLab Premium in 13.9.
Code Owners define who owns specific files or folders in a repository.
Code Owners define who owns specific files or directories in a repository.
- The users you define as Code Owners are displayed in the UI when you browse directories.
- You can set your merge requests so they must be approved by Code Owners before merge.
......@@ -23,7 +23,7 @@ If you don't want to use Code Owners for approvals, you can
## Set up Code Owners
You can use Code Owners to specify users or [shared groups](members/share_project_with_groups.md)
that are responsible for specific files and folders in a repository.
that are responsible for specific files and directories in a repository.
To set up Code Owners:
......@@ -41,116 +41,98 @@ To set up Code Owners:
filename @username1 @username2
# Code Owners for a directory
foldername @username1 @username2
directoryname @username1 @username2
# All group members as Code Owners for a file
filename @groupname
# All group members as Code Owners for a folder
foldername @groupname
# All group members as Code Owners for a directory
directoryname @groupname
```
The Code Owners are now displayed in the UI.
The Code Owners are now displayed in the UI. They apply to the current branch only.
Next steps:
- [Add Code Owners as merge request approvers](merge_requests/approvals/rules.md#code-owners-as-eligible-approvers).
- Set up [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch).
NOTE:
The Code Owners apply to the current branch only.
## When a file matches multiple `CODEOWNERS` entries
When a file matches multiple entries in the `CODEOWNERS` file,
the users from last pattern matching the file are used.
For example, in the following `CODEOWNERS` file:
```plaintext
README.md @user1
# This line would also match the file README.md
*.md @user2
```
The user that would show for `README.md` would be `@user2`.
## Groups as Code Owners
> - [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.
You can use members of groups and subgroups as Code Owners for a project.
For example, consider a given group called "Group X" (slug `group-x`) and a
"Subgroup Y" (slug `group-x/subgroup-y`) that belongs to the Group X, and
suppose you have a project called "Project A" within the group and a
"Project B" within the subgroup.
For example, if you have these groups:
The eligible Code Owners to Project B are both the members of the Group X and
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:
- **Group X** (`group-x`) with **Project A** in it.
- **Subgroup Y** (`group-x/subgroup-y`), which belongs to **Group X**, with **Project B** in it.
The eligible Code Owners:
- For **Project A** are the members of **Group X** only, because **Project A** doesn't belong to **Subgroup Y**.
- For **Project B** are the members of both **Group X** and **Subgroup Y**.
![Eligible Code Owners](img/code_owners_members_v13_4.png)
But you have the option to [invite](members/share_project_with_groups.md)
the Subgroup Y to the Project A so that their members also become eligible
Code Owners:
You can [invite](members/share_project_with_groups.md) **Subgroup Y** to **Project A**
so that their members also become eligible Code Owners.
![Invite subgroup members to become eligible Code Owners](img/code_owners_invite_members_v13_4.png)
NOTE:
If you do not invite Subgroup Y to Project A, but make them Code Owners, their approval
If you do not invite **Subgroup Y** to **Project A**, but make them Code Owners, their approval
of the merge request becomes optional.
![Invite subgroup members to become eligible Code Owners](img/code_owners_invite_members_v13_4.png)
### Add a group as a Code Owner
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:
To set a group as a Code Owner:
```plaintext
# A member of the group or subgroup as Code Owner to a file
file.md @user
In the `CODEOWNERS` file, enter text that follows one of these patterns:
# All group members as Code Owners to a file
```plaintext
# All group members as Code Owners for a file
file.md @group-x
# All subgroup members as Code Owners to a file
# All subgroup members as Code Owners for a file
file.md @group-x/subgroup-y
# All group and subgroup members as Code Owners to a file
# All group and subgroup members as Code Owners for a file
file.md @group-x @group-x/subgroup-y
```
### Code Owners sections **(PREMIUM)**
## When a file matches multiple `CODEOWNERS` entries
When a file matches multiple entries in the `CODEOWNERS` file,
the users from last pattern matching the file are used.
For example, in the following `CODEOWNERS` file:
```plaintext
README.md @user1
# This line would also match the file README.md
*.md @user2
```
The Code Owner for `README.md` would be `@user2`.
If you use sections, the last user _for each section_ is used.
Only one CODEOWNERS pattern can match per file path.
### Organize Code Owners by putting them into sections
> - [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
organization of broader categories of Code Owner rules to be applied.
Additionally, the usual guidance that only the last pattern matching the file is
applied is expanded such that the last pattern matching _for each section_ is
applied.
For example, in a large organization, independent teams may have a common interest
in parts of the application, for instance, a payment processing company may have
"development", "security", and "compliance" teams looking after common parts of
the codebase. All three teams may need to approve changes. Although approval rules
make this possible, they apply to every merge request. Also, while Code Owners are
applied based on which files are changed, only one CODEOWNERS pattern can match per
file path.
Using `CODEOWNERS` sections allows multiple teams that only need to approve certain
changes, to set their own independent patterns by specifying discrete sections in the
`CODEOWNERS` file. The section rules may be used for shared paths so that multiple
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 is assigned to that
section. The following example would create two Code Owner rules for the "README
Owners" section:
You can organize Code Owners by putting them into named sections.
You can use sections for shared directories, so that multiple
teams can be reviewers.
To add a section to the `CODEOWNERS` file, enter a section name in brackets,
followed by the files or directories, and users, groups, or subgroups:
```plaintext
[README Owners]
......@@ -158,43 +140,41 @@ README.md @user1 @user2
internal/README.md @user2
```
Multiple sections can be used, even with matching file or directory patterns.
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:
Each Code Owner in the merge request widget is listed under a label.
The following image shows a **Groups** and **Documentation** section:
![MR widget - Sectional Code Owners](img/sectional_code_owners_v13.2.png)
### Sections with duplicate names
If multiple sections have the same name, they are combined.
Also, section headings are not case-sensitive. For example:
```plaintext
[Documentation]
ee/docs @gl-docs
docs @gl-docs
ee/docs @docs
docs @docs
[Database]
README.md @gl-database
model/db @gl-database
README.md @database
model/db @database
[DOCUMENTATION]
README.md @gl-docs
README.md @docs
```
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
of the section encountered in the file.
This code results in three entries under the **Documentation** section header, and two
entries under **Database**. The entries defined under the sections **Documentation** and
**DOCUMENTATION** are combined, using the case of the first section.
When assigned to a section, each Code Owner rule displayed in merge requests
widget is sorted under a "section" label. In the screenshot below, we can see
the rules for "Groups" and "Documentation" sections:
![MR widget - Sectional Code Owners](img/sectional_code_owners_v13.2.png)
#### Optional Code Owners sections **(PREMIUM)**
### Make a Code Owners section optional
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8 behind a feature flag, enabled by default.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53227) in GitLab 13.9.
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:
You can make a section optional, so that approval from the Code Owners in that section is optional.
Put a caret `^` character before the Code Owners section name. For example:
```plaintext
[Documentation]
......@@ -211,83 +191,64 @@ The optional Code Owners section displays in merge requests under the **Approval
![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.
For example, the Code Owners of the "Documentation" section below is still required to approve merge requests:
```plaintext
[Documentation]
*.md @root
[Ruby]
*.rb @root
^[Go]
*.go @root
^[Documentation]
*.txt @root
```
If a section is duplicated in the file, and one of them is marked as optional and the other isn't, the section is required.
Optional sections in the `CODEOWNERS` 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),
and allow direct pushes to the protected branch for sections marked as optional.
section is marked as optional. [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/297638)
to allow direct pushes to the protected branch for sections marked as optional.
## Example `CODEOWNERS` file
```plaintext
# This is an example of a CODEOWNERS file
# lines starting with a `#` will be ignored.
# This is an example of a CODEOWNERS file.
# Lines that start with `#` are ignored.
# app/ @commented-rule
# We can specify a default match using wildcards:
# Specify a default Code Owner by using a wildcard:
* @default-codeowner
# We can also specify "multiple tab or space" separated codeowners:
# Specify multiple Code Owners by using a tab or space:
* @multiple @code @owners
# Rules defined later in the file take precedence over the rules
# defined before.
# This will match all files for which the file name ends in `.rb`
# For example, for all files with a filename ending in `.rb`:
*.rb @ruby-owner
# Files with a `#` can still be accessed by escaping the pound sign
# Files with a `#` can still be accessed by escaping the pound sign:
\#file_with_pound.rb @owner-file-with-pound
# Multiple codeowners can be specified, separated by spaces or tabs
# Specify multiple Code Owners separated by spaces or tabs.
# In the following case the CODEOWNERS file from the root of the repo
# has 3 Code Owners (@multiple @code @owners)
# has 3 Code Owners (@multiple @code @owners):
CODEOWNERS @multiple @code @owners
# Both usernames or email addresses can be used to match
# users. Everything else will be ignored. For example this will
# specify `@legal` and a user with email `janedoe@gitlab.com` as the
# owner for the LICENSE file
# You can use both usernames or email addresses to match
# users. Everything else is ignored. For example, this code
# specifies the `@legal` and a user with email `janedoe@gitlab.com` as the
# owner for the LICENSE file:
LICENSE @legal this_does_not_match janedoe@gitlab.com
# Group names can be used to match groups and nested groups to specify
# them as owners for a file
# Use group names to match groups, and nested groups to specify
# them as owners for a file:
README @group @group/with-nested/subgroup
# Ending a path in a `/` will specify the Code Owners for every file
# nested in that directory, on any level
# End a path in a `/` to specify the Code Owners for every file
# nested in that directory, on any level:
/docs/ @all-docs
# Ending a path in `/*` will specify Code Owners for every file in
# that directory, but not nested deeper. This will match
# `docs/index.md` but not `docs/projects/index.md`
# End a path in `/*` to specify Code Owners for every file in
# a directory, but not nested deeper. This code matches
# `docs/index.md` but not `docs/projects/index.md`:
/docs/* @root-docs
# This will make a `lib` directory nested anywhere in the repository
# match
# This code makes matches a `lib` directory nested anywhere in the repository:
lib/ @lib-owner
# This will only match a `config` directory in the root of the
# repository
# This code match only a `config` directory in the root of the repository:
/config/ @config-owner
# If the path contains spaces, escape them like this:
......@@ -295,14 +256,14 @@ path\ with\ spaces/ @space-owner
# Code Owners section:
[Documentation]
ee/docs @gl-docs
docs @gl-docs
ee/docs @docs
docs @docs
[Database]
README.md @gl-database
model/db @gl-database
README.md @database
model/db @database
# This section will be joined with the [Documentation] section previously defined:
# This section is combined with the previously defined [Documentation] section:
[DOCUMENTATION]
README.md @gl-docs
README.md @docs
```
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