Subgroups

Introduced in GitLab 9.0.

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:

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:

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:

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

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

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

To create a subgroup you must either be an Owner or a Maintainer of the group, depending on the group's setting.

By default, groups created in:

This setting can be for any group by an Owner or Administrator.

For more information check the permissions table. For a list of words that are not allowed to be used as group names see the reserved names.

Users can always create subgroups if they are explicitly added as an Owner (or Maintainer, if that setting is enabled) to a parent group, even if group creation is disabled by an administrator in their settings.

To create a subgroup:

  1. In the group's dashboard expand the New project split button, select New subgroup and click the New subgroup button.

Subgroups page

  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.

Subgroups page

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

Jobs for pipelines in subgroups can use Runners registered to the parent group. 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 groups.

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 deduce the following things:

From GitLab 12.6, you can filter this list using dropdown on the right side:

Group members filter

Overriding the ancestor group membership

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

NOTE: 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 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.

Mentioning subgroups

Limitations

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