diff --git a/doc/user/project/codeowners/index.md b/doc/user/project/codeowners/index.md index f37c910384e6e1bb1a65bafce51f1a95ce0d0d01..d30f51d5bbe4a953f01c876cd26854a2e866adeb 100644 --- a/doc/user/project/codeowners/index.md +++ b/doc/user/project/codeowners/index.md @@ -111,6 +111,10 @@ file.md @group-x/subgroup-y file.md @group-x @group-x/subgroup-y ``` +When a group is invited to a parent group higher in your project's hierarchy, +and added to the `CODEOWNERS` file, that group becomes a Code Owner for all subgroups. +For more information, see [Inviting subgroups to parent groups](#invite-subgroups-to-parent-groups). + NOTE: You cannot set a member of a group or subgroup as a Code Owner if [Global SAML group memberships lock](../../group/saml_sso/group_sync.md#global-saml-group-memberships-lock) is enabled. @@ -129,7 +133,7 @@ graph TD In this example: -- **Parent group X** (`group-x`) owns **Project A**. +- **Parent group X** owns **Project A**. - **Parent group X** also contains a subgroup, **Subgroup Y**. (`group-x/subgroup-y`) - **Subgroup Y** owns **Project B**. @@ -138,10 +142,46 @@ The eligible Code Owners are: - **Project A**: the members of **Group X** only, because **Project A** doesn't belong to **Subgroup Y**. - **Project B**: the members of both **Group X** and **Subgroup Y**. -##### Inviting subgroups to projects in parent groups +##### Invite subgroups to parent groups + +Groups invited to parent groups are valid Code Owners for projects in subgroups. +Inviting **Subgroup Y** to a parent group of **Project A** +[is supported](https://gitlab.com/gitlab-org/gitlab/-/issues/498117). +When a parent group of **Project A** invites another group, the invited group is Code Owner eligible. +You must also add the group to the `CODEOWNERS` file to make it a Code Owner. + +The following is an example of how this works in a multi-level group structure: + +```mermaid +%%{init: { "fontFamily": "GitLab Sans" }}%% +graph LR + accTitle: Diagram of inviting subgroups to parent groups + A[Parent group X] --> |owns| B[Subgroup 1] + A --> |owns| C[Subgroup 2] + B --> |contains| D[Project A] + C --> |contains| E[Project B] + A -.-> |invites| F[Other group] + F -.-> |Code Owner| D + F -.-> |Code Owner| E +``` + +In this example: + +- The **Parent group X** has two subgroups: **Subgroup 1** and **Subgroup 2**. +- Each subgroup contains a project: **Project A** and **Project B**. +- **Other group** is invited to the **Parent group X**. +- As a result, the **Other group** is a valid Code Owner for both **Project A** and **Project B**. + +NOTE: +To require approvals, Code Owners groups must have a direct membership +or inherited membership in the project. + +##### Invite subgroups to projects in parent groups You can [invite](../members/sharing_projects_groups.md) **Subgroup Y** to **Project A** -so that their members also become eligible Code Owners. +to make it Code Owner eligible. You must also add the group to the `CODEOWNERS` file to make it a Code Owner. + +Here is an example of subgroup inheritance in a multi-level group structure: ```mermaid %%{init: { "fontFamily": "GitLab Sans" }}%% @@ -156,20 +196,8 @@ graph LR F -.-> |Add Subgroup Y
as Code Owners to Project A| J[Approvals can only
be optional] -.-> B ``` -If you do not invite **Subgroup Y** to **Project A**, but make them Code Owners, their approval -of the merge request becomes optional. - -##### Inviting subgroups to parent groups - -Inviting **Subgroup Y** to a parent group of **Project A** -[is not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/288851). To set **Subgroup Y** as -Code Owners, [invite this group directly to the project](#inviting-subgroups-to-projects-in-parent-groups) itself. - -NOTE: -For approval to be required, groups as Code Owners must have a direct membership -(not inherited membership) in the project. Approval can only be optional for groups -that inherit membership. Members in the Code Owners group also must be direct members, -and not inherit membership from any parent groups. +If you do not invite **Subgroup Y** to **Project A**, but add it to the `CODEOWNERS` file, +the group's approval of the merge request is optional. ### Define more specific owners for more specifically defined files or directories