diff options
Diffstat (limited to 'doc/user/group/subgroups/index.md')
| -rw-r--r-- | doc/user/group/subgroups/index.md | 263 |
1 files changed, 125 insertions, 138 deletions
diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 46dea81ae9f..a98f213bb3f 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -2,189 +2,176 @@ stage: Manage group: Authentication and Authorization info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto, concepts --- # Subgroups **(FREE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2772) in GitLab 9.0. -GitLab supports up to 20 levels of subgroups, also known as nested groups or hierarchical groups. - -By using subgroups you can do the following: - -- **Separate internal / external organizations.** Since every group - can have its own visibility level ([public, internal, or private](../../../development/permissions.md#general-permissions)), - you're able to host groups for different purposes under the same umbrella. -- **Organize large projects.** For large projects, subgroups makes it - potentially easier to separate permissions on parts of the source code. -- **Make it easier to manage people and control visibility.** Give people - different [permissions](../../permissions.md#group-members-permissions) depending on their group [membership](#membership). - -For more information on allowed permissions in groups and projects, see -[visibility levels](../../../development/permissions.md#general-permissions). - -## Overview - -A group can have many subgroups inside it, and at the same time a group can have -only one immediate parent group. It resembles a directory behavior or a nested items list: - -- Group 1 - - Group 1.1 - - Group 1.2 - - Group 1.2.1 - - Group 1.2.2 - - Group 1.2.2.1 - -In a real world example, imagine maintaining a GNU/Linux distribution with the -first group being the name of the distribution, and subsequent groups split as follows: - -- Organization Group - GNU/Linux distro - - Category Subgroup - Packages - - (project) Package01 - - (project) Package02 - - Category Subgroup - Software - - (project) Core - - (project) CLI - - (project) Android app - - (project) iOS app - - Category Subgroup - Infra tools - - (project) Ansible playbooks - -Another example of GitLab as a company would be the following: - -- Organization Group - GitLab - - Category Subgroup - Marketing - - (project) Design - - (project) General - - Category Subgroup - Software - - (project) GitLab CE - - (project) GitLab EE - - (project) Omnibus GitLab - - (project) GitLab Runner - - (project) GitLab Pages daemon - - Category Subgroup - Infra tools - - (project) Chef cookbooks - - Category Subgroup - Executive team - -When performing actions such as transferring or importing a project between -subgroups, the behavior is the same as when performing these actions at the -`group/project` level. - -## Creating a subgroup - -Users can create subgroups if they are explicitly added as an Owner (or -Maintainer, if that setting is enabled) to an immediate parent group, even if group -creation is disabled by an administrator in their settings. +You can organize GitLab [groups](../index.md) into subgroups. You can use subgroups to: + +- Separate internal and external organizations. Because every subgroup can have its own + [visibility level](../../../development/permissions.md#general-permissions), you can host groups for different + purposes under the same parent group. +- Organize large projects. You can use subgroups to give different access to parts of + the source code. +- Manage people and control visibility. Give a user a different + [role](../../permissions.md#group-members-permissions) for each group they're [a member of](#subgroup-membership). + +Subgroups can: + +- Belong to one immediate parent group. +- Have many subgroups. +- Be nested up to 20 levels. +- Use [runners](../../../ci/runners/index.md) registered to parent groups: + - Secrets configured for the parent group are available to subgroup jobs. + - Users with the Maintainer role in projects that belong to subgroups can see the details of runners registered to + parent groups. + +For example: + +```mermaid +graph TD + subgraph "Parent group" + subgraph "Subgroup A" + subgraph "Subgroup A1" + G["Project E"] + end + C["Project A"] + D["Project B"] + E["Project C"] + end + subgraph "Subgroup B" + F["Project D"] + end + end +``` + +## Create a subgroup + +Users with the at least the Maintainer role on a group can create subgroups immediately below the group, unless +[configured otherwise](#change-who-can-create-subgroups). These users can create subgroups even if group creation is +[disabled by an Administrator](../../admin_area/index.md#prevent-a-user-from-creating-groups) in the user's settings. To create a subgroup: -1. On the top bar, select **Menu > Groups** and find the parent group. -1. In the top right, select **New subgroup**. +1. On the top bar, select **Menu > Groups** and find and select the parent group to add a subgroup to. +1. On the parent group's overview page, in the top right, select **New subgroup**. 1. Select **Create group**. -1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) - that cannot be used as group names. +1. Fill in the fields. View a list of [reserved names](../../reserved_names.md) that cannot be used as group names. 1. Select **Create group**. ### Change who can create subgroups -To create a subgroup you must either be an Owner or a Maintainer of the -group, depending on the group's setting. +To create a subgroup, you must have at least the Maintainer role on the group, depending on the group's setting. By +default: -By default: +- In GitLab 12.2 or later, users with at least the Maintainer role can create subgroups. +- In GitLab 12.1 or earlier, only users with the Owner role can create subgroups. -- In GitLab 12.2 or later, both Owners and Maintainers can create subgroups. -- In GitLab 12.1 or earlier, only Owners can create subgroups. +To change who can create subgroups on a group: -You can change this setting: - -- As group owner: - 1. Select the group. +- As a user with the Owner role on the group: + 1. On the top bar, select **Menu > Groups** and find the group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. + 1. Select a role from the **Allowed to create subgroups** dropdown. - As an administrator: 1. On the top bar, select **Menu > Admin**. 1. On the left sidebar, select **Overview > Groups**. 1. Select the group, and select **Edit**. + 1. Select a role from the **Allowed to create subgroups** dropdown. For more information, view the [permissions table](../../permissions.md#group-members-permissions). -## Membership - -When you add a member to a group, that member is also added to all subgroups. -Permission level is inherited from the group's parent. This model allows access to -subgroups if you have membership in one of its parents. +## Subgroup membership -Jobs for pipelines in subgroups can use [runners](../../../ci/runners/index.md) registered to the parent group(s). -This means secrets configured for the parent group are available to subgroup jobs. +When you add a member to a group, that member is also added to all subgroups. The user's permissions are inherited from +the group's parent. -In addition, maintainers of projects that belong to subgroups can see the details of runners registered to parent group(s). +Subgroup members can: -The group permissions for a member can be changed only by Owners, and only on -the **Members** page of the group the member was added. +1. Be [direct members](../../project/members/index.md#add-users-to-a-project) of the subgroup. +1. [Inherit membership](../../project/members/index.md#inherited-membership) of the subgroup from the subgroup's parent group. +1. Be a member of a group that was [shared with the subgroup's top-level group](../index.md#share-a-group-with-another-group). -You can tell if a member has inherited the permissions from a parent group by -looking at the group's **Members** page. +```mermaid +flowchart RL + subgraph Group A + A(Direct member) + B{{Shared member}} + subgraph Subgroup A + H(1. Direct member) + C{{2. Inherited member}} + D{{Inherited member}} + E{{3. Shared member}} + end + A-->|Direct membership of Group A\nInherited membership of Subgroup A|C + end + subgraph Group C + G(Direct member) + end + subgraph Group B + F(Direct member) + end + F-->|Group B\nshared with\nGroup A|B + B-->|Inherited membership of Subgroup A|D + G-->|Group C shared with Subgroup A|E +``` - +Group permissions for a member can be changed only by: -From the image above, we can deduce the following things: +- Users with the Owner role on the group. +- Changing the configuration of the group the member was added to. -- There are 5 members that have access to the group `four`. -- User 0 is a Reporter and has inherited their permissions from group `one` - which is above the hierarchy of group `four`. -- User 1 is a Developer and has inherited their permissions from group - `one/two` which is above the hierarchy of group `four`. -- User 2 is a Developer and has inherited their permissions from group - `one/two/three` which is above the hierarchy of group `four`. -- For User 3 the **Source** column indicates **Direct member**, therefore they belong to - group `four`, the one we're inspecting. -- Administrator is the Owner and member of **all** subgroups and for that reason, - as with User 3, the **Source** column indicates **Direct member**. +### Determine membership inheritance -Members can be [filtered by inherited or direct membership](../index.md#filter-a-group). +To see if a member has inherited the permissions from a parent group: -### Overriding the ancestor group membership +1. On the top bar, select **Menu > Groups** and find the group. +1. Select **Group information > Members**. -NOTE: -You must be an Owner of a group to be able to add members to it. +Members list for an example subgroup _Four_: -NOTE: -A user's permissions in a subgroup cannot be lower than in any of its ancestor groups. -Therefore, you cannot reduce a user's permissions in a subgroup with respect to its ancestor groups. + -To override a user's membership of an ancestor group (the first group they were -added to), add the user to the new subgroup again with a higher set of permissions. +In the screenshot above: + +- Five members have access to group _Four_. +- User 0 has the Reporter role on group _Four_, and has inherited their permissions from group _One_: + - User 0 is a direct member of group _One_. + - Group _One_ is above group _Four_ in the hierarchy. +- User 1 has the Developer role on group _Four_ and inherited their permissions from group _Two_: + - User 0 is a direct member of group _Two_, which is a subgroup of group _One_. + - Groups _One / Two_ are above group _Four_ in the hierarchy. +- User 2 has the Developer role on group _Four_ and has inherited their permissions from group _Three_: + - User 0 is a direct member of group _Three_, which is a subgroup of group _Two_. Group _Two_ is a subgroup of group + _One_. + - Groups _One / Two / Three_ are above group _Four_ the hierarchy. +- User 3 is a direct member of group _Four_. This means they get their Maintainer role directly from group _Four_. +- Administrator has the Owner role on group _Four_ and is a member of all subgroups. For that reason, as with User 3, + the **Source** column indicates they are a direct member. -For example, if User 1 was first added to group `one/two` with Developer -permissions, then they inherit those permissions in every other subgroup -of `one/two`. To give them the Maintainer role for group `one/two/three/four`, -you would add them again in that group as Maintainer. Removing them from that group, -the permissions fall back to those of the ancestor group. +Members can be [filtered by inherited or direct membership](../index.md#filter-a-group). -## Mentioning subgroups +### Override ancestor group membership -Mentioning groups (`@group`) in issues, commits and merge requests, would -notify all members of that group. Now with subgroups, there is more granular -support if you want to split your group's structure. Mentioning works as before -and you can choose the group of people to be notified. +Users with the Owner role on a subgroup can add members to it. - +You can't give a user a role on a subgroup that's lower than the roles they have on ancestor groups. To override a user's +role on an ancestor group, add the user to the subgroup again with a higher role. For example: -## Limitations +- If User 1 is added to group _Two_ with the Developer role, they inherit that role in every subgroup of group _Two_. +- To give User 1 the Maintainer role on group _Four_ (under _One / Two / Three_), add them again to group _Four_ with + the Maintainer role. +- If User 1 is removed from group _Four_, their role falls back to their role on group _Two_. They have the Developer + role on group _Four_ again. -Here's a list of what you can't do with subgroups: +## Mention subgroups -- [GitLab Pages](../../project/pages/index.md) supports projects hosted under - a subgroup, but not subgroup websites. - That means that only the highest-level group supports - [group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names), - although you can have project websites under a subgroup. -- It is not possible to share a project with a group that's an ancestor of - the group the project is in. That means you can only share as you walk down - the hierarchy. For example, `group/subgroup01/project` **cannot** be shared - with `group`, but can be shared with `group/subgroup02` or - `group/subgroup01/subgroup03`. +Mentioning subgroups ([`@<subgroup_name>`](../../discussions/index.md#mentions)) in issues, commits, and merge requests +notifies all members of that group. Mentioning works the same as for projects and groups, and you can choose the group +of people to be notified. <!-- ## Troubleshooting |