index.md 7.38 KB
Newer Older
1 2 3 4
---
type: reference, howto, concepts
---

5 6
# Subgroups

7
NOTE: **Note:**
8
[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2772) in GitLab 9.0.
9

10 11 12 13
Subgroups, also known as nested groups or hierarchical groups, allow you to have up to 20
levels of groups.

By using subgroups you can do the following:
14 15 16 17 18 19 20

- **Separate internal / external organizations.** Since every group
  can have its own visibility level, you are 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
21
  different [permissions](../../permissions.md#group-members-permissions) depending on their group [membership](#membership).
22 23 24 25

## Overview

A group can have many subgroups inside it, and at the same time a group can have
26
only 1 parent group. It resembles a directory behavior or a nested items list:
27

28 29 30
- Group 1
  - Group 1.1
  - Group 1.2
31 32 33
    - Group 1.2.1
    - Group 1.2.2
      - Group 1.2.2.1
34 35

In a real world example, imagine maintaining a GNU/Linux distribution with the
36
first group being the name of the distribution, and subsequent groups split as follows:
37

38 39
- Organization Group - GNU/Linux distro
  - Category Subgroup - Packages
40 41
    - (project) Package01
    - (project) Package02
42
  - Category Subgroup - Software
43 44 45 46
    - (project) Core
    - (project) CLI
    - (project) Android app
    - (project) iOS app
47
  - Category Subgroup - Infra tools
48
    - (project) Ansible playbooks
49 50 51

Another example of GitLab as a company would be the following:

52
- Organization Group - GitLab
Pascal Borreli's avatar
Pascal Borreli committed
53
  - Category Subgroup - Marketing
54 55
    - (project) Design
    - (project) General
56
  - Category Subgroup - Software
57 58 59 60 61
    - (project) GitLab CE
    - (project) GitLab EE
    - (project) Omnibus GitLab
    - (project) GitLab Runner
    - (project) GitLab Pages daemon
62
  - Category Subgroup - Infra tools
63
    - (project) Chef cookbooks
64
  - Category Subgroup - Executive team
65 66 67

---

68
The maximum subgroups a group can have, including the first one in the
69 70
hierarchy, is 21.

71
Actions such as transferring or importing a project inside subgroups, work like
72 73 74 75 76
when performing these actions the traditional way with the `group/project`
structure.

## Creating a subgroup

77
NOTE: **Note:**
78
You must be an Owner of a group to create a subgroup. For
79
more information check the [permissions table](../../permissions.md#group-members-permissions).
80
For a list of words that are not allowed to be used as group names see the
81
[reserved names](../../reserved_names.md).
82
Users can always create subgroups if they are explicitly added as an Owner to
83
a parent group, even if group creation is disabled by an administrator in their
84
settings.
85 86 87

To create a subgroup:

James Ramsay's avatar
James Ramsay committed
88 89
1. In the group's dashboard expand the **New project** split button, select
   **New subgroup** and click the **New subgroup** button.
90

91
   ![Subgroups page](img/create_subgroup_button.png)
92 93 94 95 96

1. Create a new group like you would normally do. Notice that the parent group
   namespace is fixed under **Group path**. The visibility level can differ from
   the parent group.

97
   ![Subgroups page](img/create_new_group.png)
98 99 100 101

1. Click the **Create group** button and you will be taken to the new group's
   dashboard page.

102
Follow the same process to create any subsequent groups.
103 104 105 106 107 108 109

## Membership

When you add a member to a subgroup, they inherit the membership and permission
level from the parent group. This model allows access to nested groups if you
have membership in one of its parents.

110
The group permissions for a member can be changed only by Owners, and only on
111 112
the **Members** page of the group the member was added.

113 114 115 116 117
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.png)

118
From the image above, we can deduce the following things:
119

120
- There are 5 members that have access to the group `four`.
121
- User0 is a Reporter and has inherited their permissions from group `one`
122
  which is above the hierarchy of group `four`.
123
- User1 is a Developer and has inherited their permissions from group
124
  `one/two` which is above the hierarchy of group `four`.
125
- User2 is a Developer and has inherited their permissions from group
126
  `one/two/three` which is above the hierarchy of group `four`.
127
- For User3 there is no indication of a parent group, therefore they belong to
128
  group `four`, the one we're inspecting.
129
- Administrator is the Owner and member of **all** subgroups and for that reason,
130
  as with User3, there is no indication of an ancestor group.
131

132 133
### Overriding the ancestor group membership

134
NOTE: **Note:**
135
You must be an Owner of a group to be able to add members to it.
136

137
NOTE: **Note:**
dappelt's avatar
dappelt committed
138 139 140
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.

141
To override a user's membership of an ancestor group (the first group they were
dappelt's avatar
dappelt committed
142
added to), add the user to the new subgroup again with a higher set of permissions.
143

144
For example, if User0 was first added to group `group-1/group-1-1` with Developer
145
permissions, then they will inherit those permissions in every other subgroup
Mark Chao's avatar
Mark Chao committed
146 147
of `group-1/group-1-1`. To give them Maintainer access to `group-1/group-1-1/group1-1-1`,
you would add them again in that group as Maintainer. Removing them from that group,
148
the permissions will fallback to those of the ancestor group.
149 150 151 152

## Mentioning subgroups

Mentioning groups (`@group`) in issues, commits and merge requests, would
153
notify all members of that group. Now with subgroups, there is more granular
154
support if you want to split your group's structure. Mentioning works as before
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
155
and you can choose the group of people to be notified.
156 157 158 159 160 161 162

![Mentioning subgroups](img/mention_subgroups.png)

## Limitations

Here's a list of what you can't do with subgroups:

163 164 165
- [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
Marcia Ramos's avatar
Marcia Ramos committed
166
  [group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-domain-names),
167
  although you can have project websites under a subgroup.
168 169 170 171 172 173 174
- 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`.

[ce-2772]: https://gitlab.com/gitlab-org/gitlab-ce/issues/2772
175
[permissions]: ../../permissions.md#group-members-permissions
176
[reserved]:  ../../reserved_names.md
177
[issue]: https://gitlab.com/gitlab-org/gitlab-ce/issues/30472#note_27747600
178 179 180 181 182 183 184 185 186 187 188 189

<!-- ## Troubleshooting

Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.

Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->