debian-mirror-gitlab/doc/user/project/code_owners.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

345 lines
12 KiB
Markdown
Raw Normal View History

2019-12-21 20:55:43 +05:30
---
2020-10-24 23:57:45 +05:30
stage: Create
group: Source Code
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2019-12-21 20:55:43 +05:30
---
2021-03-11 19:13:27 +05:30
# Code Owners **(PREMIUM)**
2019-07-31 22:56:46 +05:30
2022-03-02 08:16:31 +05:30
> Moved to GitLab Premium in 13.9.
2022-01-26 12:08:38 +05:30
2022-08-27 11:52:29 +05:30
Code Owners define who develops and maintains a feature, and own the resulting
files or directories in a repository.
2020-05-24 23:13:21 +05:30
2021-10-27 15:23:28 +05:30
- 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.
- You can protect a branch and allow only Code Owners to approve changes to the branch.
2020-05-24 23:13:21 +05:30
2022-08-27 11:52:29 +05:30
Use Code Owners and approvers together with
[approval rules](merge_requests/approvals/rules.md) to build a flexible approval
workflow:
2020-05-24 23:13:21 +05:30
2022-08-27 11:52:29 +05:30
- Use **Code Owners** to define the users who have domain expertise for specific paths in your repository.
- Use **Approvers** and **Approval rules** to define domains of expertise (such as a security team)
that are not scoped to specific file paths in your repository.
- **Approvers** define the users.
- **Approval rules** define when these users can approve work, and whether or not their approval is required.
For example:
2021-06-08 01:23:25 +05:30
2022-08-27 11:52:29 +05:30
| Type | Name | Scope | Comment |
|------|------|--------|------------|
| Approval rule | UX | All files | A user experience (UX) team member reviews the user experience of all changes made in your project. |
| Approval rule | Security | All files | A security team member reviews all changes for vulnerabilities. |
| Code Owner approval rule | Frontend: Code Style | `*.css` files | A frontend engineer reviews CSS file changes for adherence to project style standards. |
| Code Owner approval rule | Backend: Code Review | `*.rb` files | A backend engineer reviews the logic and code style of Ruby files. |
## Set up Code Owners
2020-05-24 23:13:21 +05:30
2022-08-27 11:52:29 +05:30
Create a `CODEOWNERS` file to specify users or [shared groups](members/share_project_with_groups.md)
that are responsible for specific files and directories in a repository. Each repository
can have a single `CODEOWNERS` file. To create it:
2020-05-24 23:13:21 +05:30
2021-09-30 23:02:18 +05:30
1. Choose the location where you want to specify Code Owners:
- In the root directory of the repository
- In the `.gitlab/` directory
- In the `docs/` directory
2020-05-24 23:13:21 +05:30
2021-09-30 23:02:18 +05:30
1. In that location, create a file named `CODEOWNERS`.
1. In the file, enter text that follows one of these patterns:
```plaintext
2021-10-27 15:23:28 +05:30
# Code Owners for a file
filename @username1 @username2
2021-09-30 23:02:18 +05:30
2021-10-27 15:23:28 +05:30
# Code Owners for a directory
directoryname/ @username1 @username2
2019-07-31 22:56:46 +05:30
2021-10-27 15:23:28 +05:30
# All group members as Code Owners for a file
2021-09-30 23:02:18 +05:30
filename @groupname
2019-07-31 22:56:46 +05:30
2021-10-27 15:23:28 +05:30
# All group members as Code Owners for a directory
directoryname/ @groupname
2021-09-30 23:02:18 +05:30
```
2019-07-31 22:56:46 +05:30
2021-10-27 15:23:28 +05:30
The Code Owners are now displayed in the UI. They apply to the current branch only.
2021-01-29 00:20:46 +05:30
2021-10-27 15:23:28 +05:30
Next steps:
2019-07-31 22:56:46 +05:30
2021-10-27 15:23:28 +05:30
- [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).
2020-04-08 14:13:33 +05:30
2021-10-27 15:23:28 +05:30
## Groups as Code Owners
2019-12-21 20:55:43 +05:30
2021-10-27 15:23:28 +05:30
> - [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.
2019-12-21 20:55:43 +05:30
2022-08-27 11:52:29 +05:30
You can use members of groups and subgroups as Code Owners for projects:
2019-12-21 20:55:43 +05:30
2022-08-27 11:52:29 +05:30
```mermaid
graph TD
A[Parent group X] -->|owns| B[Project A]
A -->|contains| C[Subgroup Y]
C -->|owns| D[Project B]
A-. inherits ownership .-> D
```
2020-06-23 00:09:42 +05:30
2022-08-27 11:52:29 +05:30
In this example:
2019-12-21 20:55:43 +05:30
2022-08-27 11:52:29 +05:30
- **Parent group X** (`group-x`) owns **Project A**.
- **Parent group X** also contains a subgroup, **Subgroup Y**. (`group-x/subgroup-y`)
- **Subgroup Y** owns **Project B**.
2019-12-21 20:55:43 +05:30
2022-08-27 11:52:29 +05:30
The eligible Code Owners are:
2020-06-23 00:09:42 +05:30
2022-08-27 11:52:29 +05:30
- **Project A**: the members of **Group X** only, because **Project A** doesn't belong to **Subgroup Y**.
- **Project B**: the members of both **Group X** and **Subgroup Y**.
2021-03-11 19:13:27 +05:30
2021-10-27 15:23:28 +05:30
You can [invite](members/share_project_with_groups.md) **Subgroup Y** to **Project A**
so that their members also become eligible Code Owners.
2020-05-24 23:13:21 +05:30
2022-08-27 11:52:29 +05:30
```mermaid
graph LR
A[Parent group X] -->|owns| B[Project A]
A -->|also contains| C[Subgroup Y]
C -.->D{Invite Subgroup Y<br/>to Project A?} -.->|yes| F[Approvals can be<br/> required] -.-> B
D{Invite Subgroup Y<br/>to Project A?} -.->|no| I[Subgroup Y cannot be<br /> an approver] -.-> B
C -.->E{Add Subgroup Y<br/>as Code Owners<br/>to Project A?} -.->|yes| H[Approvals can only<br/>be optional] -.-> B
```
2021-01-03 14:25:43 +05:30
2021-10-27 15:23:28 +05:30
If you do not invite **Subgroup Y** to **Project A**, but make them Code Owners, their approval
of the merge request becomes optional.
2020-05-30 21:06:31 +05:30
2021-12-11 22:18:48 +05:30
Inviting **Subgroup Y** to a parent group of **Project A**
[is not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/288851). To set **Subgroup Y** as
Code Owners, add this group directly to the project itself.
2022-08-13 15:12:31 +05:30
NOTE:
For approval to be required, groups as Code Owners must have a direct membership
(not inherited membership) in the project. Approval can only be optional for groups
that inherit membership. Members in the Code Owners group also must be direct members,
and not inherit membership from any parent groups.
2021-10-27 15:23:28 +05:30
### Add a group as a Code Owner
2020-05-30 21:06:31 +05:30
2021-10-27 15:23:28 +05:30
To set a group as a Code Owner:
2020-11-24 15:15:51 +05:30
2021-10-27 15:23:28 +05:30
In the `CODEOWNERS` file, enter text that follows one of these patterns:
2020-05-30 21:06:31 +05:30
2021-10-27 15:23:28 +05:30
```plaintext
# All group members as Code Owners for a file
file.md @group-x
2020-05-30 21:06:31 +05:30
2021-10-27 15:23:28 +05:30
# All subgroup members as Code Owners for a file
file.md @group-x/subgroup-y
2020-05-30 21:06:31 +05:30
2021-10-27 15:23:28 +05:30
# All group and subgroup members as Code Owners for a file
file.md @group-x @group-x/subgroup-y
```
2020-05-30 21:06:31 +05:30
2021-10-27 15:23:28 +05:30
## When a file matches multiple `CODEOWNERS` entries
2021-06-08 01:23:25 +05:30
2021-10-27 15:23:28 +05:30
When a file matches multiple entries in the `CODEOWNERS` file,
the users from last pattern matching the file are used.
2019-07-31 22:56:46 +05:30
2021-10-27 15:23:28 +05:30
For example, in the following `CODEOWNERS` file:
2020-11-24 15:15:51 +05:30
```plaintext
2021-10-27 15:23:28 +05:30
README.md @user1
2020-11-24 15:15:51 +05:30
2021-10-27 15:23:28 +05:30
# This line would also match the file README.md
*.md @user2
```
2020-11-24 15:15:51 +05:30
2021-10-27 15:23:28 +05:30
The Code Owner for `README.md` would be `@user2`.
2020-11-24 15:15:51 +05:30
2021-10-27 15:23:28 +05:30
If you use sections, the last user _for each section_ is used.
2019-07-31 22:56:46 +05:30
2021-10-27 15:23:28 +05:30
Only one CODEOWNERS pattern can match per file path.
### Organize Code Owners by putting them into sections
2020-07-28 23:09:34 +05:30
2022-06-21 17:19:12 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab 13.2 [with a flag](../../administration/feature_flags.md) named `sectional_codeowners`. Disabled by default.
> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4. Feature flag `sectional_codeowners` removed.
2020-07-28 23:09:34 +05:30
2021-10-27 15:23:28 +05:30
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:
2020-07-28 23:09:34 +05:30
```plaintext
[README Owners]
2020-10-24 23:57:45 +05:30
README.md @user1 @user2
2020-07-28 23:09:34 +05:30
internal/README.md @user2
```
2021-10-27 15:23:28 +05:30
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:
2020-07-28 23:09:34 +05:30
```plaintext
[Documentation]
2021-10-27 15:23:28 +05:30
ee/docs/ @docs
docs/ @docs
2020-07-28 23:09:34 +05:30
[Database]
2021-10-27 15:23:28 +05:30
README.md @database
model/db/ @database
2020-07-28 23:09:34 +05:30
[DOCUMENTATION]
2021-10-27 15:23:28 +05:30
README.md @docs
2020-07-28 23:09:34 +05:30
```
2021-10-27 15:23:28 +05:30
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.
2020-07-28 23:09:34 +05:30
2021-10-27 15:23:28 +05:30
### Make a Code Owners section optional
2021-03-08 18:12:59 +05:30
2022-05-07 20:08:51 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab 13.8.
2021-03-08 18:12:59 +05:30
2022-01-26 12:08:38 +05:30
You can designate optional sections in your Code Owners file. Prepend the
section name with the caret `^` character to treat the entire section as optional.
Optional sections enable you to designate responsible parties for various parts
of your codebase, but not require approval from them. This approach provides
a more relaxed policy for parts of your project that are frequently updated,
but don't require stringent reviews.
2021-10-27 15:23:28 +05:30
2022-01-26 12:08:38 +05:30
In this example, the `[Go]` section is optional:
2021-03-08 18:12:59 +05:30
```plaintext
[Documentation]
*.md @root
[Ruby]
*.rb @root
^[Go]
*.go @root
```
2021-10-27 15:23:28 +05:30
The optional Code Owners section displays in merge requests under the **Approval Rules** area:
2021-03-08 18:12:59 +05:30
2021-10-27 15:23:28 +05:30
![MR widget - Optional Code Owners sections](img/optional_code_owners_sections_v13_8.png)
2021-03-08 18:12:59 +05:30
2021-10-27 15:23:28 +05:30
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.
2021-03-08 18:12:59 +05:30
2021-10-27 15:23:28 +05:30
Optional sections in the `CODEOWNERS` file are treated as optional only
2021-03-11 19:13:27 +05:30
when changes are submitted by using merge requests. If a change is submitted directly
2021-10-27 15:23:28 +05:30
to the protected branch, approval from Code Owners is still required, even if the
2022-01-26 12:08:38 +05:30
section is marked as optional.
### Allowed to Push
The Code Owner approval and protected branch features do not apply to users who
are **Allowed to push**.
2021-03-08 18:12:59 +05:30
2020-07-28 23:09:34 +05:30
## Example `CODEOWNERS` file
2019-07-31 22:56:46 +05:30
2020-04-22 19:07:51 +05:30
```plaintext
2021-10-27 15:23:28 +05:30
# This is an example of a CODEOWNERS file.
# Lines that start with `#` are ignored.
2019-07-31 22:56:46 +05:30
# app/ @commented-rule
2021-10-27 15:23:28 +05:30
# Specify a default Code Owner by using a wildcard:
2019-07-31 22:56:46 +05:30
* @default-codeowner
2021-10-27 15:23:28 +05:30
# Specify multiple Code Owners by using a tab or space:
2020-05-24 23:13:21 +05:30
* @multiple @code @owners
2019-07-31 22:56:46 +05:30
# Rules defined later in the file take precedence over the rules
# defined before.
2021-10-27 15:23:28 +05:30
# For example, for all files with a filename ending in `.rb`:
2019-07-31 22:56:46 +05:30
*.rb @ruby-owner
2021-10-27 15:23:28 +05:30
# Files with a `#` can still be accessed by escaping the pound sign:
2019-07-31 22:56:46 +05:30
\#file_with_pound.rb @owner-file-with-pound
2021-10-27 15:23:28 +05:30
# Specify multiple Code Owners separated by spaces or tabs.
2020-05-24 23:13:21 +05:30
# In the following case the CODEOWNERS file from the root of the repo
2021-10-27 15:23:28 +05:30
# has 3 Code Owners (@multiple @code @owners):
2019-12-04 20:38:33 +05:30
CODEOWNERS @multiple @code @owners
2019-07-31 22:56:46 +05:30
2021-10-27 15:23:28 +05:30
# 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:
2019-07-31 22:56:46 +05:30
LICENSE @legal this_does_not_match janedoe@gitlab.com
2021-10-27 15:23:28 +05:30
# Use group names to match groups, and nested groups to specify
# them as owners for a file:
2019-09-30 21:07:59 +05:30
README @group @group/with-nested/subgroup
2021-10-27 15:23:28 +05:30
# End a path in a `/` to specify the Code Owners for every file
# nested in that directory, on any level:
2019-07-31 22:56:46 +05:30
/docs/ @all-docs
2021-10-27 15:23:28 +05:30
# 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`:
2019-07-31 22:56:46 +05:30
/docs/* @root-docs
2022-06-21 17:19:12 +05:30
# Include `/**` to specify Code Owners for all subdirectories
2022-07-23 23:45:48 +05:30
# in a directory. This rule matches `docs/projects/index.md` or
2022-06-21 17:19:12 +05:30
# `docs/development/index.md`
/docs/**/*.md @root-docs
2021-10-27 15:23:28 +05:30
# This code makes matches a `lib` directory nested anywhere in the repository:
2019-07-31 22:56:46 +05:30
lib/ @lib-owner
2021-10-27 15:23:28 +05:30
# This code match only a `config` directory in the root of the repository:
2019-07-31 22:56:46 +05:30
/config/ @config-owner
2021-10-27 15:23:28 +05:30
# If the path contains spaces, escape them like this:
2019-07-31 22:56:46 +05:30
path\ with\ spaces/ @space-owner
2020-07-28 23:09:34 +05:30
# Code Owners section:
[Documentation]
2021-10-27 15:23:28 +05:30
ee/docs @docs
docs @docs
2020-07-28 23:09:34 +05:30
[Database]
2021-10-27 15:23:28 +05:30
README.md @database
model/db @database
2020-07-28 23:09:34 +05:30
2021-10-27 15:23:28 +05:30
# This section is combined with the previously defined [Documentation] section:
2020-07-28 23:09:34 +05:30
[DOCUMENTATION]
2021-10-27 15:23:28 +05:30
README.md @docs
2019-07-31 22:56:46 +05:30
```
2022-03-02 08:16:31 +05:30
## Troubleshooting
### Approvals shown as optional
2022-04-04 11:22:00 +05:30
A Code Owner approval rule is optional if any of these conditions are true:
2022-03-02 08:16:31 +05:30
- The user or group are not a member of the project or parent group.
- [Code Owner approval on a protected branch](protected_branches.md#require-code-owner-approval-on-a-protected-branch) has not been set up.
- The section is [marked as optional](#make-a-code-owners-section-optional).
### Approvals do not show
Code Owner approval rules only update when the merge request is created.
If you update the `CODEOWNERS` file, close the merge request and create a new one.
### User not shown as possible approver
2022-11-25 23:54:43 +05:30
A user might not show as an approver on the Code Owner merge request approval rules
if any of these conditions are true:
2022-03-02 08:16:31 +05:30
2022-11-25 23:54:43 +05:30
- A rule prevents the specific user from approving the merge request.
Check the project [merge request approval](merge_requests/approvals/settings.md#edit-merge-request-approval-settings) settings.
- A Code Owner group has a visibility of **private**, and the current user is not a
member of the Code Owner group.