Subgroups
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:
- 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 different permissions depending on their group membership.
Database Requirements
Subgroups are only supported when you use PostgreSQL. Supporting subgroups on MySQL in an efficient way is not possible due to MySQL’s limitations.
See the following links for more information:
- https://gitlab.com/gitlab-org/gitlab-ce/issues/30472
- https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10885
Overview
A group can have many subgroups inside it, and at the same time a group can have only 1 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
- Category Subgroup - Packages
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
- Category Subgroup - Marketing
The maximum subgroups a group can have, including the first one in the hierarchy, is 21.
Actions such as transferring or importing a project inside subgroups, work like
when performing these actions the traditional way with the group/project
structure.
Creating a subgroup
To create a subgroup:
-
In the group’s dashboard expand the New project split button, select New subgroup and click the New subgroup button.
-
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.
-
Click the Create group button and you will be taken to the new group’s dashboard page.
Follow the same process to create any subsequent groups.
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.
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.
From the image above, we can deduce the following things:
- There are 5 members that have access to the group
four
. - User0 is a Reporter and has inherited their permissions from group
one
which is above the hierarchy of groupfour
. - User1 is a Developer and has inherited their permissions from group
one/two
which is above the hierarchy of groupfour
. - User2 is a Developer and has inherited their permissions from group
one/two/three
which is above the hierarchy of groupfour
. - For User3 there is no indication of a parent group, 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 User3, there is no indication of an ancestor group.
Overriding the ancestor group membership
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 User0 was first added to group group-1/group-1-1
with Developer
permissions, then they will inherit those permissions in every other subgroup
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,
the permissions will fallback 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.
Limitations
Here’s a list of what you can’t do with subgroups:
- GitLab Pages supports projects hosted under a subgroup, but not subgroup websites. That means that only the highest-level group supports group websites, 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 withgroup
, but can be shared withgroup/subgroup02
orgroup/subgroup01/subgroup03
.
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc