1--- 2stage: Manage 3group: Access 4info: 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 5type: reference, howto, concepts 6--- 7 8# Subgroups **(FREE)** 9 10> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/2772) in GitLab 9.0. 11 12GitLab supports up to 20 levels of subgroups, also known as nested groups or hierarchical groups. 13 14By using subgroups you can do the following: 15 16- **Separate internal / external organizations.** Since every group 17 can have its own visibility level ([public, internal, or private](../../../development/permissions.md#general-permissions)), 18 you're able to host groups for different purposes under the same umbrella. 19- **Organize large projects.** For large projects, subgroups makes it 20 potentially easier to separate permissions on parts of the source code. 21- **Make it easier to manage people and control visibility.** Give people 22 different [permissions](../../permissions.md#group-members-permissions) depending on their group [membership](#membership). 23 24For more information on allowed permissions in groups and projects, see 25[visibility levels](../../../development/permissions.md#general-permissions). 26 27## Overview 28 29A group can have many subgroups inside it, and at the same time a group can have 30only one immediate parent group. It resembles a directory behavior or a nested items list: 31 32- Group 1 33 - Group 1.1 34 - Group 1.2 35 - Group 1.2.1 36 - Group 1.2.2 37 - Group 1.2.2.1 38 39In a real world example, imagine maintaining a GNU/Linux distribution with the 40first group being the name of the distribution, and subsequent groups split as follows: 41 42- Organization Group - GNU/Linux distro 43 - Category Subgroup - Packages 44 - (project) Package01 45 - (project) Package02 46 - Category Subgroup - Software 47 - (project) Core 48 - (project) CLI 49 - (project) Android app 50 - (project) iOS app 51 - Category Subgroup - Infra tools 52 - (project) Ansible playbooks 53 54Another example of GitLab as a company would be the following: 55 56- Organization Group - GitLab 57 - Category Subgroup - Marketing 58 - (project) Design 59 - (project) General 60 - Category Subgroup - Software 61 - (project) GitLab CE 62 - (project) GitLab EE 63 - (project) Omnibus GitLab 64 - (project) GitLab Runner 65 - (project) GitLab Pages daemon 66 - Category Subgroup - Infra tools 67 - (project) Chef cookbooks 68 - Category Subgroup - Executive team 69 70When performing actions such as transferring or importing a project between 71subgroups, the behavior is the same as when performing these actions at the 72`group/project` level. 73 74## Creating a subgroup 75 76Users can create subgroups if they are explicitly added as an Owner (or 77Maintainer, if that setting is enabled) to an immediate parent group, even if group 78creation is disabled by an administrator in their settings. 79 80To create a subgroup: 81 821. On the top bar, select **Menu > Groups** and find the parent group. 831. In the top right, select **New subgroup**. 841. Select **Create group**. 851. Fill in the fields. View a list of [reserved names](../../reserved_names.md) 86 that cannot be used as group names. 871. Select **Create group**. 88 89### Change who can create subgroups 90 91To create a subgroup you must either be an Owner or a Maintainer of the 92group, depending on the group's setting. 93 94By default: 95 96- In GitLab 12.2 or later, both Owners and Maintainers can create subgroups. 97- In GitLab 12.1 or earlier, only Owners can create subgroups. 98 99You can change this setting: 100 101- As group owner: 102 1. Select the group. 103 1. On the left sidebar, select **Settings > General**. 104 1. Expand **Permissions, LFS, 2FA**. 105- As an administrator: 106 1. On the top bar, select **Menu > Admin**. 107 1. On the left sidebar, select **Overview > Groups**. 108 1. Select the group, and select **Edit**. 109 110For more information, view the [permissions table](../../permissions.md#group-members-permissions). 111 112## Membership 113 114When you add a member to a group, that member is also added to all subgroups. 115Permission level is inherited from the group's parent. This model allows access to 116subgroups if you have membership in one of its parents. 117 118Jobs for pipelines in subgroups can use [runners](../../../ci/runners/index.md) registered to the parent group(s). 119This means secrets configured for the parent group are available to subgroup jobs. 120 121In addition, maintainers of projects that belong to subgroups can see the details of runners registered to parent group(s). 122 123The group permissions for a member can be changed only by Owners, and only on 124the **Members** page of the group the member was added. 125 126You can tell if a member has inherited the permissions from a parent group by 127looking at the group's **Members** page. 128 129![Group members page](img/group_members_v14_4.png) 130 131From the image above, we can deduce the following things: 132 133- There are 5 members that have access to the group `four`. 134- User 0 is a Reporter and has inherited their permissions from group `one` 135 which is above the hierarchy of group `four`. 136- User 1 is a Developer and has inherited their permissions from group 137 `one/two` which is above the hierarchy of group `four`. 138- User 2 is a Developer and has inherited their permissions from group 139 `one/two/three` which is above the hierarchy of group `four`. 140- For User 3 the **Source** column indicates **Direct member**, therefore they belong to 141 group `four`, the one we're inspecting. 142- Administrator is the Owner and member of **all** subgroups and for that reason, 143 as with User 3, the **Source** column indicates **Direct member**. 144 145Members can be [filtered by inherited or direct membership](../index.md#filter-a-group). 146 147### Overriding the ancestor group membership 148 149NOTE: 150You must be an Owner of a group to be able to add members to it. 151 152NOTE: 153A user's permissions in a subgroup cannot be lower than in any of its ancestor groups. 154Therefore, you cannot reduce a user's permissions in a subgroup with respect to its ancestor groups. 155 156To override a user's membership of an ancestor group (the first group they were 157added to), add the user to the new subgroup again with a higher set of permissions. 158 159For example, if User 1 was first added to group `one/two` with Developer 160permissions, then they inherit those permissions in every other subgroup 161of `one/two`. To give them the [Maintainer role](../../permissions.md) for group `one/two/three/four`, 162you would add them again in that group as Maintainer. Removing them from that group, 163the permissions fall back to those of the ancestor group. 164 165## Mentioning subgroups 166 167Mentioning groups (`@group`) in issues, commits and merge requests, would 168notify all members of that group. Now with subgroups, there is more granular 169support if you want to split your group's structure. Mentioning works as before 170and you can choose the group of people to be notified. 171 172![Mentioning subgroups](img/mention_subgroups.png) 173 174## Limitations 175 176Here's a list of what you can't do with subgroups: 177 178- [GitLab Pages](../../project/pages/index.md) supports projects hosted under 179 a subgroup, but not subgroup websites. 180 That means that only the highest-level group supports 181 [group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-default-domain-names), 182 although you can have project websites under a subgroup. 183- It is not possible to share a project with a group that's an ancestor of 184 the group the project is in. That means you can only share as you walk down 185 the hierarchy. For example, `group/subgroup01/project` **cannot** be shared 186 with `group`, but can be shared with `group/subgroup02` or 187 `group/subgroup01/subgroup03`. 188 189<!-- ## Troubleshooting 190 191Include any troubleshooting steps that you can foresee. If you know beforehand what issues 192one might have when setting this up, or when something is changed, or on upgrading, it's 193important to describe those, too. Think of things that may go wrong and include them here. 194This is important to minimize requests for support, and to avoid doc comments with 195questions that you know someone might ask. 196 197Each scenario can be a third-level heading, e.g. `### Getting error message X`. 198If you have none to add when creating a doc, leave this section in place 199but commented out to help encourage others to add to it in the future. --> 200