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