doc/user/project/codeowners/advanced.md
{{< details >}}
{{< /details >}}
The CODEOWNERS file helps you define who is responsible for specific files and directories.
You can use pattern matching, sections, and inheritance rules to assign reviewers to merge requests
and require their approval before merging.
GitLab uses File::fnmatch with the File::FNM_DOTMATCH and File::FNM_PATHNAME flags set for pattern matching:
File::FNM_DOTMATCH flag allows * to match dotfiles like .gitignore.File::FNM_PATHNAME flag prevents * from matching the / path separator.** matches directories recursively. For example, **/*.rb matches config/database.rb
and app/controllers/users/stars_controller.rb.To combine the syntax for default owners with optional sections and required approvals, place default owners at the end:
[Documentation][2] @docs-team
docs/
README.md
^[Database] @database-team
model/db/
config/db/database-setup.md @docs-team
If you set a default Code Owner for a path outside a section, their approval is always required. Such entries aren't overridden by sections. Entries without sections are treated as if they were another, unnamed section:
# Required for all files
* @general-approvers
[Documentation] @docs-team
docs/
README.md
*.txt
[Database] @database-team
model/db/
config/db/database-setup.md @docs-team
In this example:
@general-approvers owns all items everywhere, without overrides.@docs-team owns all items in the Documentation section.@database-team owns all items in the Database section except
config/db/database-setup.md, which has an override assigning it to @docs-team.model/db/CHANGELOG.txt would require three approvals: one from each
of the @general-approvers,@docs-team, and @database-team groups.Compare this behavior to when you use only default owners for sections, when specific entries in a section override the section default.
If multiple sections have the same name, they are combined. Also, section headings are not case-sensitive. For example:
[Documentation]
ee/docs/ @docs
docs/ @docs
[Database]
README.md @database
model/db/ @database
[DOCUMENTATION]
README.md @docs
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 a file or directory matches multiple entries in the CODEOWNERS file,
the users from last pattern matching the file or directory are used. This enables you
to define more specific owners for more specifically defined files or directories, when
you order the entries in a sensible way.
For example, in the following CODEOWNERS file:
# This line would match the file terms.md
*.md @doc-team
# This line would also match the file terms.md
terms.md @legal-team
The Code Owner for terms.md would be @legal-team.
You can require multiple approvals for the Code Owners sections in the Approvals area in merge requests.
Append the section name with a number n in brackets, for example, [2] or [3].
This requires n approvals from the Code Owners in this section.
Valid entries for n are integers ≥ 1. [1] is optional because it is the default. Invalid values for n are treated as 1.
[!warning] Issue 384881 proposes changes to the behavior of this setting. Do not intentionally set invalid values. They may become valid in the future and cause unexpected behavior.
To require multiple approvals from Code Owners:
CODEOWNERS file to add a rule for multiple approvals.For example, to require two approvals for the [Documentation] section:
[Documentation][2]
*.md @tech-writer-team
[Ruby]
*.rb @dev-team
The Documentation Code Owners section in the Approvals area displays two approvals are required:
%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
accTitle: Diagram of group inheritance
accDescr: If a subgroup owns a project, the parent group inherits ownership.
A[Parent group X] -->|owns| B[Project A]
A -->|contains| C[Subgroup Y]
C -->|owns| D[Project B]
A-. inherits ownership .-> D
In this example:
group-x) owns Project A.group-x/subgroup-y)The eligible Code Owners are:
{{< history >}}
check_inherited_groups_for_codeowners. Disabled by default.check_inherited_groups_for_codeowners removed.{{< /history >}}
To make members of a group eligible as Code Owners for projects they don't directly belong to, you can invite the group to a parent group of the project. When you invite a group, its direct members become eligible as Code Owners for all projects in the parent group's hierarchy.
Prerequisites:
For example, in this hierarchy:
group-x
├── engineering-group
└── product-group
└── project-a
If you invite engineering-group to product-group, members of
engineering-group become eligible as Code Owners for project-a.
You don't need to directly invite engineering-group to project-a.
Only direct members of the invited group are eligible as Code Owners. Members who inherit membership in the invited group are not eligible.
{{< history >}}
{{< /history >}}
Escape whitespace in paths with backslashes:
path\ with\ spaces/*.md @owner
Without escaping, GitLab parses folder with spaces/*.md @group as: path: "folder", owners: " with spaces/*.md @group".
If a section heading cannot be parsed, the section is:
* @group
[Section name
docs/ @docs_group
GitLab recognizes the heading [Section name as an entry. The default section includes 3 rules:
* owned by @group[Section owned by namedocs/ owned by @docs_group[Docs]
docs/**/* @group
[Section name
docs/ @docs_group
GitLab recognizes the heading [Section name as an entry. The [Docs] section includes 3 rules:
docs/**/* owned by @group[Section owned by namedocs/ owned by @docs_groupEach entry must contain one or more owners. Malformed owners are invalid and ignored:
/path/* @group user_without_at_symbol @user_with_at_symbol
This entry is owned by @group and @user_with_at_symbol.
GitLab ignores inaccessible or incorrect owners. For example:
* @group @grou @username @i_left @i_dont_exist [email protected] [email protected]
If only @group, @username, and [email protected] are accessible, GitLab ignores the others.
If an entry includes no owners, or zero accessible owners exist, the entry is invalid. Because this rule can never be satisfied, GitLab auto-approves it in merge requests.
[!note] When a protected branch has
Require code owner approvalenabled, rules with zero owners are still honored.
When defining the number of approvals for a section,
the minimum number of approvals is 1. Setting the number of approvals to
0 results in GitLab requiring one approval.