diff options
Diffstat (limited to 'doc/user/project/code_owners.md')
| -rw-r--r-- | doc/user/project/code_owners.md | 43 |
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:  +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 |