2019-10-17 14:08:05 -04:00
---
2020-07-28 14:09:36 -04:00
stage: Create
group: Source Code
2020-11-26 01:09:20 -05:00
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
2019-10-17 14:08:05 -04:00
type: reference
---
2021-02-03 10:09:24 -05:00
# Code Owners **(PREMIUM)**
2019-05-05 11:37:18 -04:00
2021-01-29 10:09:40 -05:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916) in GitLab 11.3.
2021-07-26 02:10:00 -04:00
> - Code Owners for merge request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9.
2021-02-03 10:09:24 -05:00
> - Moved to GitLab Premium in 13.9.
2019-05-05 11:37:18 -04:00
2021-07-30 17:10:15 -04:00
Code Owners define who owns specific files or directories in a repository.
2020-04-23 11:09:55 -04:00
2021-07-26 02:10:00 -04:00
- 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-04-23 11:09:55 -04:00
2021-07-05 17:07:32 -04:00
If you don't want to use Code Owners for approvals, you can
[configure rules ](merge_requests/approvals/rules.md ) instead.
2020-04-23 11:09:55 -04:00
2021-07-05 17:07:32 -04:00
## Set up Code Owners
2021-05-14 17:10:41 -04:00
2021-07-26 02:10:00 -04:00
You can use Code Owners to specify users or [shared groups ](members/share_project_with_groups.md )
2021-07-30 17:10:15 -04:00
that are responsible for specific files and directories in a repository.
2020-04-23 11:09:55 -04:00
2021-07-05 17:07:32 -04:00
To set up Code Owners:
2020-04-23 11:09:55 -04:00
2021-07-05 17:07:32 -04:00
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-04-23 11:09:55 -04:00
2021-07-05 17:07:32 -04:00
1. In that location, create a file named `CODEOWNERS` .
1. In the file, enter text that follows one of these patterns:
```plaintext
2021-07-26 02:10:00 -04:00
# Code Owners for a file
filename @username1 @username2
2021-07-05 17:07:32 -04:00
2021-07-26 02:10:00 -04:00
# Code Owners for a directory
2021-07-30 17:10:15 -04:00
directoryname/ @username1 @username2
2019-05-05 11:37:18 -04:00
2021-07-26 02:10:00 -04:00
# All group members as Code Owners for a file
2021-07-05 17:07:32 -04:00
filename @groupname
2019-05-05 11:37:18 -04:00
2021-07-30 17:10:15 -04:00
# All group members as Code Owners for a directory
directoryname/ @groupname
2021-07-05 17:07:32 -04:00
```
2019-05-05 11:37:18 -04:00
2021-07-30 17:10:15 -04:00
The Code Owners are now displayed in the UI. They apply to the current branch only.
2021-07-26 02:10:00 -04:00
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 ).
2021-07-05 17:07:32 -04:00
## Groups as Code Owners
2020-05-20 17:09:09 -04:00
2021-01-29 10:09:40 -05:00
> - [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.
2020-05-20 17:09:09 -04:00
2021-07-30 17:10:15 -04:00
You can use members of groups and subgroups as Code Owners for a project.
2020-09-08 08:08:41 -04:00
2021-07-30 17:10:15 -04:00
For example, if you have these groups:
2020-05-20 17:09:09 -04:00
2021-07-30 17:10:15 -04:00
- **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** .
2020-05-20 17:09:09 -04:00
2020-09-08 08:08:41 -04:00
![Eligible Code Owners ](img/code_owners_members_v13_4.png )
2020-05-20 17:09:09 -04:00
2021-07-30 17:10:15 -04:00
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 )
2020-05-20 17:09:09 -04:00
2021-07-30 17:10:15 -04:00
If you do not invite **Subgroup Y** to **Project A** , but make them Code Owners, their approval
2021-04-22 14:10:13 -04:00
of the merge request becomes optional.
2021-10-26 14:09:19 -04:00
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.
2021-07-30 17:10:15 -04:00
### Add a group as a Code Owner
2019-05-05 11:37:18 -04:00
2021-07-30 17:10:15 -04:00
To set a group as a Code Owner:
2020-09-08 08:08:41 -04:00
2021-07-30 17:10:15 -04:00
In the `CODEOWNERS` file, enter text that follows one of these patterns:
2020-09-08 08:08:41 -04:00
2021-07-30 17:10:15 -04:00
```plaintext
# All group members as Code Owners for a file
2020-09-08 08:08:41 -04:00
file.md @group -x
2021-07-30 17:10:15 -04:00
# All subgroup members as Code Owners for a file
2020-09-08 08:08:41 -04:00
file.md @group -x/subgroup-y
2021-07-30 17:10:15 -04:00
# All group and subgroup members as Code Owners for a file
2020-09-08 08:08:41 -04:00
file.md @group -x @group -x/subgroup-y
```
2019-05-05 11:37:18 -04:00
2021-07-30 17:10:15 -04:00
## 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
2020-07-16 08:09:22 -04:00
2021-01-29 10:09:40 -05:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12137) in GitLab Premium 13.2 behind a feature flag, enabled by default.
2020-10-08 05:08:40 -04:00
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42389) in GitLab 13.4.
2020-07-16 08:09:22 -04:00
2021-07-30 17:10:15 -04:00
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-16 08:09:22 -04:00
```plaintext
[README Owners]
2020-08-17 02:10:12 -04:00
README.md @user1 @user2
2020-07-16 08:09:22 -04:00
internal/README.md @user2
```
2021-07-30 17:10:15 -04:00
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-16 08:09:22 -04:00
```plaintext
[Documentation]
2021-07-30 17:10:15 -04:00
ee/docs/ @docs
docs/ @docs
2020-07-16 08:09:22 -04:00
[Database]
2021-07-30 17:10:15 -04:00
README.md @database
model/db/ @database
2020-07-16 08:09:22 -04:00
[DOCUMENTATION]
2021-07-30 17:10:15 -04:00
README.md @docs
2020-07-16 08:09:22 -04:00
```
2021-07-30 17:10:15 -04:00
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-16 08:09:22 -04:00
2021-07-30 17:10:15 -04:00
### Make a Code Owners section optional
2021-01-14 16:10:37 -05:00
2021-01-29 10:09:40 -05:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232995) in GitLab Premium 13.8 behind a feature flag, enabled by default.
2021-02-03 22:09:19 -05:00
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/53227) in GitLab 13.9.
2021-01-14 16:10:37 -05:00
2021-07-30 17:10:15 -04:00
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:
2021-01-14 16:10:37 -05:00
```plaintext
[Documentation]
*.md @root
[Ruby]
*.rb @root
^[Go]
*.go @root
```
2021-07-26 02:10:00 -04:00
The optional Code Owners section displays in merge requests under the **Approval Rules** area:
2021-01-14 16:10:37 -05:00
2021-07-26 02:10:00 -04:00
![MR widget - Optional Code Owners sections ](img/optional_code_owners_sections_v13_8.png )
2021-01-14 16:10:37 -05:00
2021-07-30 17:10:15 -04:00
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-01-14 16:10:37 -05:00
2021-07-26 02:10:00 -04:00
Optional sections in the `CODEOWNERS` file are treated as optional only
2021-01-29 10:09:40 -05:00
when changes are submitted by using merge requests. If a change is submitted directly
2021-07-26 02:10:00 -04:00
to the protected branch, approval from Code Owners is still required, even if the
2021-07-30 17:10:15 -04:00
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.
2021-01-14 16:10:37 -05:00
2020-07-16 08:09:22 -04:00
## Example `CODEOWNERS` file
2019-05-05 11:37:18 -04:00
2020-03-25 02:07:58 -04:00
```plaintext
2021-07-30 17:10:15 -04:00
# This is an example of a CODEOWNERS file.
# Lines that start with `#` are ignored.
2019-05-05 11:37:18 -04:00
# app/ @commented-rule
2021-07-30 17:10:15 -04:00
# Specify a default Code Owner by using a wildcard:
2019-05-05 11:37:18 -04:00
* @default -codeowner
2021-07-30 17:10:15 -04:00
# Specify multiple Code Owners by using a tab or space:
2020-04-24 11:09:37 -04:00
* @multiple @code @owners
2019-05-05 11:37:18 -04:00
# Rules defined later in the file take precedence over the rules
# defined before.
2021-07-30 17:10:15 -04:00
# For example, for all files with a filename ending in `.rb`:
2019-05-05 11:37:18 -04:00
*.rb @ruby -owner
2021-07-30 17:10:15 -04:00
# Files with a `#` can still be accessed by escaping the pound sign:
2019-05-05 11:37:18 -04:00
\#file_with_pound.rb @owner -file-with-pound
2021-07-30 17:10:15 -04:00
# Specify multiple Code Owners separated by spaces or tabs.
2020-04-24 11:09:37 -04:00
# In the following case the CODEOWNERS file from the root of the repo
2021-07-30 17:10:15 -04:00
# has 3 Code Owners (@multiple @code @owners):
2019-08-29 22:25:44 -04:00
CODEOWNERS @multiple @code @owners
2019-05-05 11:37:18 -04:00
2021-07-30 17:10:15 -04:00
# 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-05-05 11:37:18 -04:00
LICENSE @legal this_does_not_match janedoe@gitlab.com
2021-07-30 17:10:15 -04:00
# Use group names to match groups, and nested groups to specify
# them as owners for a file:
2019-07-04 05:13:50 -04:00
README @group @group/with -nested/subgroup
2021-07-30 17:10:15 -04:00
# End a path in a `/` to specify the Code Owners for every file
# nested in that directory, on any level:
2019-05-05 11:37:18 -04:00
/docs/ @all -docs
2021-07-30 17:10:15 -04:00
# 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-05-05 11:37:18 -04:00
/docs/* @root -docs
2021-07-30 17:10:15 -04:00
# This code makes matches a `lib` directory nested anywhere in the repository:
2019-05-05 11:37:18 -04:00
lib/ @lib -owner
2021-07-30 17:10:15 -04:00
# This code match only a `config` directory in the root of the repository:
2019-05-05 11:37:18 -04:00
/config/ @config -owner
2021-07-26 02:10:00 -04:00
# If the path contains spaces, escape them like this:
2019-05-05 11:37:18 -04:00
path\ with\ spaces/ @space -owner
2020-07-16 08:09:22 -04:00
# Code Owners section:
[Documentation]
2021-07-30 17:10:15 -04:00
ee/docs @docs
docs @docs
2020-07-16 08:09:22 -04:00
[Database]
2021-07-30 17:10:15 -04:00
README.md @database
model/db @database
2020-07-16 08:09:22 -04:00
2021-07-30 17:10:15 -04:00
# This section is combined with the previously defined [Documentation] section:
2020-07-16 08:09:22 -04:00
[DOCUMENTATION]
2021-07-30 17:10:15 -04:00
README.md @docs
2019-05-05 11:37:18 -04:00
```