summaryrefslogtreecommitdiff
path: root/doc/user/project/code_owners.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/project/code_owners.md')
-rw-r--r--doc/user/project/code_owners.md43
1 files changed, 39 insertions, 4 deletions
diff --git a/doc/user/project/code_owners.md b/doc/user/project/code_owners.md
index 49083be77dc..45d9e8f04e0 100644
--- a/doc/user/project/code_owners.md
+++ b/doc/user/project/code_owners.md
@@ -9,6 +9,33 @@ in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
> - [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.
+## 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
+
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.
@@ -41,7 +68,7 @@ The user that would show for `README.md` would be `@user2`.
## Approvals by Code Owners
Once you've set Code Owners to a project, you can configure it to
-receive approvals:
+be used for merge request approvals:
- As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers).
- As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)**
@@ -50,6 +77,9 @@ Once set, Code Owners are displayed in merge requests widgets:
![MR widget - Code Owners](img/code_owners_mr_widget_v12_4.png)
+NOTE: **Note**:
+ 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 a Merge Request approval (without using [Approval Rules](merge_requests/merge_request_approvals.md#approval-rules)) by simply creating the file in one of the three locations specified above, configuring the Code Owners to be required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium) and then using [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files) to specify the actual owners and granular permissions.
+
## The syntax of Code Owners files
Files can be specified using the same kind of patterns you would use
@@ -69,23 +99,28 @@ escaped using `\#` to address files for which the name starts with a
Example `CODEOWNERS` file:
```plaintext
-# This is an example code owners file, lines starting with a `#` will
-# be ignored.
+# This is an example of a code owners file
+# lines starting with a `#` will be ignored.
# app/ @commented-rule
# We can specify a default match using wildcards:
* @default-codeowner
+# We can also specify "multiple tab or space" separated codeowners:
+* @multiple @code @owners
+
# 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
-# Files with a `#` can still be accesssed by escaping the pound sign
+# Files with a `#` can still be accessed by escaping the pound sign
\#file_with_pound.rb @owner-file-with-pound
# Multiple codeowners can be specified, separated by spaces or tabs
+# In the following case the CODEOWNERS file from the root of the repo
+# has 3 code owners (@multiple @code @owners)
CODEOWNERS @multiple @code @owners
# Both usernames or email addresses can be used to match