• Pattern matching
• Default Code Owners and optional sections
• Regular entries and sections
• Sections with duplicate names
• Define Code Owners for specific files or directories
• Require multiple approvals from Code Owners
• Group inheritance and eligibility
  • Invite subgroups to parent groups
  • Invite subgroups to projects in parent groups
• Error handling
  • Entries with spaces
  • Unparsable sections
    • After the default section
    • After a named section
  • Malformed owners
  • Inaccessible or incorrect owners
  • Zero owners
  • Minimum approvals

Advanced CODEOWNERS configuration

This page describes advanced configuration options for Code Owners in GitLab.

Pattern matching

GitLab uses File::fnmatch with the File::FNM_DOTMATCH and File::FNM_PATHNAME flags set for pattern matching:

• The repository structure is treated like an isolated file system.
• The patterns follow a subset of shell filename globbing rules, and are not regular expressions.
• The File::FNM_DOTMATCH flag allows * to match dotfiles like .gitignore.
• The 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.

Default Code Owners and optional sections

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

Regular entries and sections

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.
• A merge request that modifies 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.

Sections with duplicate names

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.

Define Code Owners for specific files or directories

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.

Require multiple approvals from Code Owners

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.

To require multiple approvals from Code Owners:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Repository.
3. Expand Protected branches.
4. Next to the default branch, turn on the toggle under Code owner approval.
5. Edit the 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:

Group inheritance and eligibility

In this example:

• 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.

The eligible Code Owners are:

• 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.

Invite subgroups to parent groups

Inviting Subgroup Y to a parent group of Project A is not supported. To set Subgroup Y as Code Owners, invite this group directly to the project itself.

Invite subgroups to projects in parent groups

You can invite Subgroup Y to Project A so that their members also become eligible Code Owners.

If you do not invite Subgroup Y to Project A, but make them Code Owners, their approval of the merge request becomes optional.

Error handling

Entries with spaces

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".

Unparsable sections

If a section heading cannot be parsed, the section is:

1. Parsed as an entry.
2. Added to the previous section.
3. If no previous section exists, the section is added to the default section.

After the default section

* @group

[Section name
docs/ @docs_group

GitLab recognizes the heading [Section name as an entry. The default section includes 3 rules:

• Default section
  • * owned by @group
  • [Section owned by name
  • docs/ owned by @docs_group

After a named section

[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 name
• docs/ owned by @docs_group

Malformed owners

Each 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.

Inaccessible or incorrect owners

GitLab ignores inaccessible or incorrect owners. For example:

* @group @grou @username @i_left @i_dont_exist example@gitlab.com invalid@gitlab.com

If only @group, @username, and example@gitlab.com are accessible, GitLab ignores the others.

Zero owners

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.

Minimum approvals

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.