Commit 7cff2f77 authored by Amy Qualls's avatar Amy Qualls

Merge branch 'selhorn-codeowners' into 'master'

Docs: Started editing for CTRT

See merge request gitlab-org/gitlab!65488
parents 883a98d9 2cf1647a
......@@ -13,7 +13,7 @@ When implementing new features, please refer to these existing features to avoid
- [Issue Templates](../user/project/description_templates.md#create-an-issue-template): `.gitlab/issue_templates/`.
- [Merge Request Templates](../user/project/description_templates.md#create-a-merge-request-template): `.gitlab/merge_request_templates/`.
- [GitLab Kubernetes Agents](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/configuration_repository.md#layout): `.gitlab/agents/`.
- [CODEOWNERS](../user/project/code_owners.md#how-to-set-up-code-owners): `.gitlab/CODEOWNERS`.
- [CODEOWNERS](../user/project/code_owners.md#set-up-code-owners): `.gitlab/CODEOWNERS`.
- [Route Maps](../ci/review_apps/#route-maps): `.gitlab/route-map.yml`.
- [Customize Auto DevOps Helm Values](../topics/autodevops/customize.md#customize-values-for-helm-chart): `.gitlab/auto-deploy-values.yaml`.
- [GitLab managed apps CI/CD](../user/clusters/applications.md#usage): `.gitlab/managed-apps/config.yaml`.
......
......@@ -11,56 +11,56 @@ type: reference
> - Code Owners for Merge Request approvals was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4418) in GitLab Premium 11.9.
> - Moved to GitLab Premium in 13.9.
## Introduction
Code Owners define who owns specific files or paths in a repository.
You can require that Code Owners approve a merge request before it's merged.
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.
Code Owners help you determine who should review or approve merge requests.
If you have a question about a file or feature, Code Owners
can help you find someone who knows the answer.
The GitLab Code Owners feature defines who owns specific
files or paths in a repository, allowing other users to understand
who is responsible for each file or path.
If you don't want to use Code Owners for approvals, you can
[configure rules](merge_requests/approvals/rules.md) instead.
As an alternative to using Code Owners for approvals, you can instead
[configure rules](merge_requests/approvals/rules.md).
## Set up Code Owners
## Why is this useful?
You can specify users or [shared groups](members/share_project_with_groups.md)
that are responsible for specific files and directories in a repository.
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. In larger organizations
or popular open source projects, Code Owners can help you understand
who to contact if you have a question about a specific portion of
the codebase. Code Owners can also streamline the merge request approval
process, identifying the most relevant reviewers and approvers for a
given change.
To set up Code Owners:
## How to set up Code Owners
1. Choose the location where you want to specify Code Owners:
- In the root directory of the repository
- In the `.gitlab/` directory
- In the `docs/` directory
You can use a `CODEOWNERS` file to specify users or
[shared groups](members/share_project_with_groups.md)
that are responsible for specific files and directories in a repository.
1. In that location, create a file named `CODEOWNERS`.
1. In the file, enter text that follows one of these patterns:
```plaintext
# A member as Code Owner of a file
filename @username
# A member as Code Owner of a directory
directory @username
You can choose to add the `CODEOWNERS` file in three places:
# All group members as Code Owners of a file
filename @groupname
- To the root directory of the repository
- Inside the `.gitlab/` directory
- Inside the `docs/` directory
# All group members as Code Owners of a directory
directory @groupname
```
The `CODEOWNERS` file is valid for the branch where it lives. For example, if you change the code owners
in a feature branch, the changes aren't valid in the main branch until the feature branch is merged.
The Code Owners are displayed in the UI by the files or directory they apply to.
These owners apply to this branch only. When you add new files to the repository,
you should update the `CODEOWNERS` file.
If you introduce new files to your repository and you want to identify the code owners for that file,
you must update `CODEOWNERS` accordingly. If you update the code owners when you are adding the files (in the same
branch), GitLab counts the owners as soon as the branch is merged. If
you don't, you can do that later, but your new files don't belong to anyone until you update your
`CODEOWNERS` file in the TARGET branch.
## When a file matches multiple `CODEOWNERS` entries
When a file matches multiple entries in the `CODEOWNERS` file,
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:
the users from last pattern matching the file are used.
For example, in the following `CODEOWNERS` file:
```plaintext
README.md @user1
......@@ -94,7 +94,7 @@ without using [Approval Rules](merge_requests/approvals/rules.md):
1. Create the file in one of the three locations specified above.
1. Set the code owners as required approvers for
[protected branches](protected_branches.md#require-code-owner-approval-on-a-protected-branch).
1. Use [the syntax of Code Owners files](code_owners.md#the-syntax-of-code-owners-files)
1. Use [the syntax of Code Owners files](code_owners.md)
to specify the actual owners and granular permissions.
Using Code Owners in conjunction with [protected branches](protected_branches.md#require-code-owner-approval-on-a-protected-branch)
......@@ -107,20 +107,7 @@ Code Owners is required.
[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35097) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5, users and groups who are allowed to push to protected branches do not require a merge request to merge their feature branches. Thus, they can skip merge request approval rules, Code Owners included.
## 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 one or more of:
- A user's `@username`.
- A user's email address.
- The `@name` of one or more groups that should be owners of the file.
- Lines starting with `#` are ignored.
The path definition order is significant: the last pattern
matching a given path is used to find the code owners.
### Groups as Code Owners
## Groups as Code Owners
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53182) in GitLab 12.1.
> - Group and subgroup hierarchy support was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32432) in GitLab 13.0.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment