GitLab Documentation


Introduced in GitLab 9.0.

With subgroups (aka nested groups or hierarchical groups) you can have up to 20 levels of nested groups, which among other things can help you to:


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:

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

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

The maximum nested groups a group can have, including the first one in the hierarchy, is 21.

Things like transferring or importing a project inside nested groups, work like when performing these actions the traditional way with the group/project structure.

Creating a subgroup


To create a subgroup:

  1. In the group's dashboard go to the Subgroups page and click Create subgroup.

    Subgroups page

  2. 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.

    Subgroups page

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

You can follow the same process to create any subsequent groups.


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.

Group members page

From the image above, we can deduct the following things:

Overriding the ancestor group membership

Note: You need to be an Owner of a group in order to be able to add members to it.

To override a user's membership of an ancestor group (the first group they were added to), simply add the user in the new subgroup again, but with different 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 Master access to group-1/group-1-1/group1-1-1, you would add them again in that group as Master. 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 a 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


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