2019-12-21 20:55:43 +05:30
---
type: reference
---
2019-09-30 21:07:59 +05:30
# Code Owners **(STARTER)**
2019-07-31 22:56:46 +05:30
2020-03-13 15:44:24 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6916)
2019-07-31 22:56:46 +05:30
in [GitLab Starter ](https://about.gitlab.com/pricing/ ) 11.3.
2020-06-23 00:09:42 +05:30
> - [Support for group namespaces](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) added in GitLab Starter 12.1.
> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9.
2019-07-31 22:56:46 +05:30
2020-05-24 23:13:21 +05:30
## Introduction
When contributing to a project, it can often be difficult
to find out who should review or approve merge requests.
Additionally, if you have a question over a specific file or
code block, it may be difficult to know who to find the answer from.
GitLab Code Owners is a feature to define who owns specific
files or paths in a repository, allowing other users to understand
who is responsible for each file or path.
## Why is this useful?
Code Owners allows for a version controlled single source of
truth file outlining the exact GitLab users or groups that
own certain files or paths in a repository. Code Owners can be
utilized in the merge request approval process which can streamline
the process of finding the right reviewers and approvers for a given
merge request.
In larger organizations or popular open source projects, Code Owners
can also be useful to understand who to contact if you have
a question that may not be related to code review or a merge request
approval.
## How to set up Code Owners
2019-09-30 21:07:59 +05:30
You can use a `CODEOWNERS` file to specify users or
[shared groups ](members/share_project_with_groups.md )
that are responsible for certain files in a repository.
2019-07-31 22:56:46 +05:30
You can choose and add the `CODEOWNERS` file in three places:
2019-12-21 20:55:43 +05:30
- To the root directory of the repository
- Inside the `.gitlab/` directory
- Inside the `docs/` directory
2019-07-31 22:56:46 +05:30
The `CODEOWNERS` file is scoped to a branch, which means that with the
introduction of new files, the person adding the new content can
specify themselves as a code owner, all before the new changes
get merged to the default branch.
When a file matches multiple entries in the `CODEOWNERS` file,
2020-04-08 14:13:33 +05:30
the users from last pattern matching the file are displayed on the
blob page of the given file. For example, you have the following
`CODEOWNERS` file:
2020-04-22 19:07:51 +05:30
```plaintext
2020-04-08 14:13:33 +05:30
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` .
2019-07-31 22:56:46 +05:30
2019-12-21 20:55:43 +05:30
## Approvals by Code Owners
Once you've set Code Owners to a project, you can configure it to
2020-05-24 23:13:21 +05:30
be used for merge request approvals:
2019-12-21 20:55:43 +05:30
2020-03-13 15:44:24 +05:30
- As [merge request eligible approvers ](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers ).
2019-12-21 20:55:43 +05:30
- As required approvers for [protected branches ](protected_branches.md#protected-branches-approval-by-code-owners-premium ). ** (PREMIUM)**
2020-06-23 00:09:42 +05:30
NOTE: **Note** :
Developer or higher [permissions ](../permissions.md ) are required in order to
approve a merge request.
2019-12-21 20:55:43 +05:30
Once set, Code Owners are displayed in merge requests widgets:
![MR widget - Code Owners ](img/code_owners_mr_widget_v12_4.png )
2020-06-23 00:09:42 +05:30
While the `CODEOWNERS` file can be used in addition to Merge Request [Approval Rules ](merge_requests/merge_request_approvals.md#approval-rules )
it can also be used as the sole driver of merge request approvals
(without using [Approval Rules ](merge_requests/merge_request_approvals.md#approval-rules )).
To do so, create the file in one of the three locations specified above and
set the code owners as required approvers for [protected branches ](protected_branches.md#protected-branches-approval-by-code-owners-premium ).
Use [the syntax of Code Owners files ](code_owners.md#the-syntax-of-code-owners-files )
to specify the actual owners and granular permissions.
Using Code Owners in conjunction with [Protected Branches Approvals ](protected_branches.md#protected-branches-approval-by-code-owners-premium )
will prevent any user who is not specified in the `CODEOWNERS` file from pushing changes
for the specified files/paths, even if their role is included in the **Allowed to push** column.
This allows for a more inclusive push strategy, as administrators don't have to restrict developers
from pushing directly to the protected branch, but can restrict pushing to certain
files where a review by Code Owners is required.
2020-05-24 23:13:21 +05:30
2019-07-31 22:56:46 +05:30
## The syntax of Code Owners files
Files can be specified using the same kind of patterns you would use
in the `.gitignore` file followed by the `@username` or email of one
2019-09-30 21:07:59 +05:30
or more users or by the `@name` of one or more groups that should
2020-03-13 15:44:24 +05:30
be owners of the file. Groups must be added as [members of the project ](members/index.md ),
or they will be ignored.
2019-07-31 22:56:46 +05:30
2020-05-30 21:06:31 +05:30
Starting in [GitLab 13.0 ](https://gitlab.com/gitlab-org/gitlab/-/issues/32432 ), you can now specify
groups or subgroups from the project's group hierarchy as potential code owners.
For example, consider the following hierarchy for a given project:
2020-06-23 00:09:42 +05:30
```plaintext
2020-05-30 21:06:31 +05:30
group >> sub-group >> sub-subgroup >> myproject >> file.md
```
Any of the following groups would be eligible to be specified as code owners:
- `@group`
- `@group/sub-group`
- `@group/sub-group/sub-subgroup`
2020-06-23 00:09:42 +05:30
In addition, any groups that have been invited to the project using the **Members** tool will also be recognized as eligible code owners.
2020-05-30 21:06:31 +05:30
2019-07-31 22:56:46 +05:30
The order in which the paths are defined is significant: the last
pattern that matches a given path will be used to find the code
owners.
Starting a line with a `#` indicates a comment. This needs to be
escaped using `\#` to address files for which the name starts with a
`#` .
Example `CODEOWNERS` file:
2020-04-22 19:07:51 +05:30
```plaintext
2020-05-24 23:13:21 +05:30
# This is an example of a code owners file
# lines starting with a `#` will be ignored.
2019-07-31 22:56:46 +05:30
# app/ @commented-rule
2019-09-04 21:01:54 +05:30
# We can specify a default match using wildcards:
2019-07-31 22:56:46 +05:30
* @default -codeowner
2020-05-24 23:13:21 +05:30
# We can also specify "multiple tab or space" separated codeowners:
* @multiple @code @owners
2019-07-31 22:56:46 +05:30
# 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`
*.rb @ruby -owner
2020-05-24 23:13:21 +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
2019-09-30 21:07:59 +05:30
# Multiple codeowners can be specified, 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
# 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
# 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
LICENSE @legal this_does_not_match janedoe@gitlab.com
2019-09-30 21:07:59 +05:30
# Group names can be used to match groups and nested groups to specify
# them as owners for a file
README @group @group/with -nested/subgroup
2019-07-31 22:56:46 +05:30
# Ending a path in a `/` will 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`
/docs/* @root -docs
# This will make a `lib` directory nested anywhere in the repository
# match
lib/ @lib -owner
# This will only match a `config` directory in the root of the
# repository
/config/ @config -owner
# If the path contains spaces, these need to be escaped like this:
path\ with\ spaces/ @space -owner
```