Commit 5aa5cb40 authored by Marcia Ramos's avatar Marcia Ramos

Merge branch 'docs-codeowners-update' into 'master'

Docs: update Code Owners

Closes #9517

See merge request gitlab-org/gitlab!18683
parents 5cf87e7d 076f88dc
---
type: reference
---
# Code Owners **(STARTER)** # Code Owners **(STARTER)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/6916) > - [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/6916)
in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. 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. > - [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.
You can use a `CODEOWNERS` file to specify users or You can use a `CODEOWNERS` file to specify users or
[shared groups](members/share_project_with_groups.md) [shared groups](members/share_project_with_groups.md)
...@@ -10,9 +15,9 @@ that are responsible for certain files in a repository. ...@@ -10,9 +15,9 @@ that are responsible for certain files in a repository.
You can choose and add the `CODEOWNERS` file in three places: You can choose and add the `CODEOWNERS` file in three places:
- to the root directory of the repository - To the root directory of the repository
- inside the `.gitlab/` directory - Inside the `.gitlab/` directory
- inside the `docs/` directory - Inside the `docs/` directory
The `CODEOWNERS` file is scoped to a branch, which means that with the The `CODEOWNERS` file is scoped to a branch, which means that with the
introduction of new files, the person adding the new content can introduction of new files, the person adding the new content can
...@@ -23,6 +28,18 @@ When a file matches multiple entries in the `CODEOWNERS` file, ...@@ -23,6 +28,18 @@ When a file matches multiple entries in the `CODEOWNERS` file,
the users from all entries are displayed on the blob page of the users from all entries are displayed on the blob page of
the given file. the given file.
## Approvals by Code Owners
Once you've set Code Owners to a project, you can configure it to
receive approvals:
- As [merge request eligible approvers](merge_requests/merge_request_approvals.md#code-owners-as-eligible-approvers-starter). **(STARTER)**
- As required approvers for [protected branches](protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)**
Once set, Code Owners are displayed in merge requests widgets:
![MR widget - Code Owners](img/code_owners_mr_widget_v12_4.png)
## The syntax of Code Owners files ## The syntax of Code Owners files
Files can be specified using the same kind of patterns you would use Files can be specified using the same kind of patterns you would use
......
...@@ -101,7 +101,7 @@ any [eligible approver](#eligible-approvers) may approve. ...@@ -101,7 +101,7 @@ any [eligible approver](#eligible-approvers) may approve.
The following can approve merge requests: The following can approve merge requests:
- Users being added as approvers at project or merge request level. - Users being added as approvers at project or merge request level.
- [Code owners](../code_owners.md) related to the merge request ([introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5). - [Code owners](#code-owners-as-eligible-approvers-starter) to the files changed by the merge request.
An individual user can be added as an approver for a project if they are a member of: An individual user can be added as an approver for a project if they are a member of:
...@@ -119,6 +119,31 @@ if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-thei ...@@ -119,6 +119,31 @@ if [**Prevent author approval**](#allowing-merge-request-authors-to-approve-thei
and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default) and [**Prevent committers approval**](#prevent-approval-of-merge-requests-by-their-committers) (disabled by default)
are enabled on the project settings. are enabled on the project settings.
### Code Owners as eligible approvers **(STARTER)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/7933) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5.
Once you've added [Code Owners](../code_owners.md) to your
repository, the owners to the corresponding files will become
eligible approvers, together with members with Developer or
higher permissions.
To enable this merge request approval rule:
1. Navigate to your project's **Settings > General** and expand
**Merge request approvals**.
1. Locate **All members with Developer role or higher and code owners (if any)** and click **Edit** to choose the number of approvals required.
![MR approvals by Code Owners](img/mr_approvals_by_code_owners_v12_4.png)
Once set, merge requests can only be merged once approved by the
number of approvals you've set. GitLab will accept approvals from
users with Developer or higher permissions, as well as by Code Owners,
indistinguishably.
Alternatively, you can **require**
[Code Owner's approvals for Protected Branches](../protected_branches.md#protected-branches-approval-by-code-owners-premium). **(PREMIUM)**
### Implicit approvers ### Implicit approvers
If the number of required approvals is greater than the number of approvers, If the number of required approvals is greater than the number of approvers,
...@@ -162,26 +187,6 @@ are other conditions that may block it, such as merge conflicts, ...@@ -162,26 +187,6 @@ are other conditions that may block it, such as merge conflicts,
[pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved) [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved)
or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md).
## Code Owners approvals **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4418) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.9.
It is possible to require at least one approval for each entry in the
[`CODEOWNERS` file](../code_owners.md) that matches a file changed in
the merge request. To enable this feature:
1. Navigate to your project's **Settings > General** and expand
**Merge request approvals**.
1. Tick the **Require approval from code owners** checkbox.
1. Click **Save changes**.
When this feature is enabled, all merge requests will need approval
from one code owner per matched rule before it can be merged.
NOTE: **Note:** Only the `CODEOWNERS` file on the default branch is evaluated for
Merge Request approvals. If `CODEOWNERS` is changed on a non-default branch, those
changes will not affect approvals until merged to the default branch.
## Overriding the merge request approvals default settings ## Overriding the merge request approvals default settings
> Introduced in GitLab Enterprise Edition 9.4. > Introduced in GitLab Enterprise Edition 9.4.
......
...@@ -86,20 +86,6 @@ Click **Protect** and the branch will appear in the "Protected branch" list. ...@@ -86,20 +86,6 @@ Click **Protect** and the branch will appear in the "Protected branch" list.
![Roles and users list](img/protected_branches_select_roles_and_users_list.png) ![Roles and users list](img/protected_branches_select_roles_and_users_list.png)
## Code Owners approvals **(PREMIUM)**
It is possible to require at least one approval for each entry in the
[`CODEOWNERS` file](code_owners.md) that matches a file changed in
the merge request. To enable this feature:
1. Toggle the **Require approval from code owners** slider.
1. Click **Protect**.
When this feature is enabled, all merge requests need approval
from one code owner per matched rule before they can be merged. Additionally,
pushes to the protected branch are denied if a rule is matched.
## Wildcard protected branches ## Wildcard protected branches
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/4665) in GitLab 8.10. > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/4665) in GitLab 8.10.
...@@ -166,6 +152,35 @@ Deleting a protected branch is only allowed via the web interface, not via Git. ...@@ -166,6 +152,35 @@ Deleting a protected branch is only allowed via the web interface, not via Git.
This means that you can't accidentally delete a protected branch from your This means that you can't accidentally delete a protected branch from your
command line or a Git client application. command line or a Git client application.
## Protected Branches approval by Code Owners **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13251) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4.
It is possible to require at least one approval by a
[Code Owner](code_owners.md) to a file changed by the
merge request. You can either set Code Owners approvals
at the time you protect a new branch, or set it to a branch
already protected, as described below.
To protect a new branch and enable Code Owner's approval:
1. Navigate to your project's **Settings > Repository** and expand **Protected branches**.
1. Scroll down to **Protect a branch**, select a **Branch** or wildcard you'd like to protect, select who's **Allowed to merge** and **Allowed to push**, and toggle the **Require approval from code owners** slider.
1. Click **Protect**.
![Code Owners approval - new protected branch](img/code_owners_approval_new_protected_branch_v12_4.png)
To enable Code Owner's approval to branches already protected:
1. Navigate to your project's **Settings > Repository** and expand **Protected branches**.
1. Scroll down to **Protected branch** and toggle the **Code owner approval** slider for the chosen branch.
![Code Owners approval - branch already protected](img/code_owners_approval_protected_branch_v12_4.png)
When enabled, all merge requests targeting these branches will require approval
by a Code Owner per matched rule before they can be merged.
Additionally, direct pushes to the protected branch are denied if a rule is matched.
## Running pipelines on protected branches ## Running pipelines on protected branches
The permission to merge or push to protected branches is used to define if a user can The permission to merge or push to protected branches is used to define if a user can
......
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