• View subgroups of a group
  • Private subgroups in public parent groups
• Create a subgroup
  • Change who can create subgroups
• Subgroup membership
  • Determine membership inheritance
  • Override ancestor group membership
• Mention subgroups

Subgroups

You can organize GitLabgroupsinto subgroups. You can use subgroups to:

• Separate internal and external content. Because every subgroup can have its own visibility level,you can host groups for different purposes under the same parent group.
• Organize large projects. You can use subgroups to manage who can access parts of the source code.
• Manage permissions. Give a user a different rolefor each group they’rea member of.

Subgroups can:

• Belong to one immediate parent group.
• Have many subgroups.
• Be nested up to 20 levels.
• Userunnersregistered to parent groups:
  • Secrets configured for the parent group are available to subgroup jobs.
  • Users with at least the Maintainer role in projects that belong to subgroups can see the details of runners registered to parent groups.

For example:

View subgroups of a group

Prerequisites:

• To view private nested subgroups, you must be a direct or inherited member of the private subgroup.

To view the subgroups of a group:

1. On the left sidebar, selectSearch or go toand find your group.
2. Select theSubgroups and projectstab.
3. Select the subgroup you want to view. To view nested subgroups, expand () a subgroup.

Private subgroups in public parent groups

In the hierarchy list, public groups with private subgroups have an expand option (), which indicates the group has nested subgroups. The expand option () is visible to all users, but the private group is displayed only to users who are direct or inherited members of the private subgroup.

If you prefer to keep information about the presence of nested subgroups private, you should add private subgroups only to private parent groups.

Create a subgroup

Prerequisites:

• You must have either:
  • At least the Maintainer role for a group.
  • Therole determined by a setting.These users can create subgroups even if group creation is disabled by an Administratorin the user’s settings.

To create a subgroup:

1. On the left sidebar, selectSearch or go toand find the group you want to create the subgroup in.
2. On the parent group’s overview page, in the upper-right corner, selectNew subgroup.
3. Fill in the fields. View a list ofreserved namesthat cannot be used as group names.
4. SelectCreate subgroup.

Change who can create subgroups

Prerequisites:

• You must have at least the Maintainer role on the group, depending on the group’s setting.

To change who can create subgroups on a group:

• As a user with the Owner role on the group:
  1. On the left sidebar, selectSearch or go toand find your group.
  2. SelectSettings > General.
  3. ExpandPermissions and group features.
  4. FromRoles allowed to create subgroups,select an option.
  5. SelectSave changes.
• As an administrator:
  1. On the left sidebar, at the bottom, selectAdmin.
  2. On the left sidebar, selectOverview > Groupsand find your group.
  3. In the group’s row, selectEdit.
  4. From theAllowed to create subgroupsdropdown list, select an option.
  5. SelectSave changes.

For more information, view thepermissions table.

Subgroup membership

When you add a member to a group, that member is also added to all subgroups of that group. The member’s permissions are inherited from the group into all subgroups.

Subgroup members can be:

1. Direct membersof the subgroup.
2. Inherited membersof the subgroup from the subgroup’s parent group.
3. Members of a group that wasshared with the subgroup’s top-level group.
4. Indirect membersinclude inherited members and members of a group that wasinvited to the subgroup or its ancestors.

Group permissions for a member can be changed only by:

• Users with the Owner role on the group.
• Changing the configuration of the group the member was added to.

Determine membership inheritance

To see if a member has inherited the permissions from a parent group:

1. On the left sidebar, selectSearch or go toand find your group.
2. SelectManage > Members. The member’s inheritance is displayed in theSourcecolumn.

Members list for an example subgroupFour:

In the screenshot above:

• Five members have access to groupFour.
• User 0 has the Reporter role on groupFour,and has inherited their permissions from groupOne:
  • User 0 is a direct member of groupOne.
  • GroupOneis above groupFourin the hierarchy.
• User 1 has the Developer role on groupFourand inherited their permissions from groupTwo:
  • User 0 is a direct member of groupTwo,which is a subgroup of groupOne.
  • GroupsOne / Twoare above groupFourin the hierarchy.
• User 2 has the Developer role on groupFourand has inherited their permissions from groupThree:
  • User 0 is a direct member of groupThree,which is a subgroup of groupTwo.GroupTwois a subgroup of group One.
  • GroupsOne / Two / Threeare above groupFourthe hierarchy.
• User 3 is a direct member of groupFour.This means they get their Maintainer role directly from groupFour.
• Administrator has the Owner role on groupFourand is a member of all subgroups. For that reason, as with User 3, theSourcecolumn indicates they are a direct member.

Members can befiltered by inherited or direct membership.

Override ancestor group membership

Users with the Owner role in a subgroup can add members to it.

You can’t give a user a role in a subgroup that is lower than the roles the user has in parent groups. To override a user’s role in a parent group, add the user to the subgroup again with a higher role. For example:

• If User 1 is added to groupTwowith the Developer role, User 1 inherits that role in every subgroup of groupTwo.
• To give User 1 the Maintainer role in groupFour(underOne / Two / Three), add User 1 again to groupFourwith the Maintainer role.
• If User 1 is removed from groupFour,the user’s role falls back to their role in groupTwo.User 1 has the Developer role in groupFouragain.

Mention subgroups

Mentioning subgroups (@<subgroup_name>) in epics, issues, commits, and merge requests notifies all direct members of that group. Inherited members of a subgroup are not notified by mentions. Mentioning works the same as for projects and groups, and you can choose the group of members to be notified.