--- 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. 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. 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. 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. By default: - In GitLab 12.2 or later, both Owners and Maintainers can create subgroups. - In GitLab 12.1 or earlier, only Owners can create subgroups. You can change this setting: - As group owner: 1. Select the group. 1. On the left sidebar, select **Settings > General**. 1. Expand **Permissions and group features**. - 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**. 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. 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. In addition, maintainers of projects that belong to subgroups can see the details of runners registered to parent group(s). 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. You can tell if a member has inherited the permissions from a parent group by looking at the group's **Members** page. ![Group members page](img/group_members_v14_4.png) From the image above, we can deduce the following things: - 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**. Members can be [filtered by inherited or direct membership](../index.md#filter-a-group). ### Overriding the ancestor group membership NOTE: You must be an Owner of a group to be able to add members to it. 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. 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. ## Mentioning subgroups 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. ![Mentioning subgroups](img/mention_subgroups.png) ## Limitations Here's a list of what you can't do with 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`.