- Create a subgroup
- Subgroup membership
- Mention subgroups
Introduced in GitLab 9.0.
You can organize GitLab groups into subgroups. You can use subgroups to:
- Separate internal and external organizations. 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 give different access to parts of the source code.
- Manage people and control visibility. Give a user a different role for each group they’re a member of.
- Belong to one immediate parent group.
- Have many subgroups.
- Be nested up to 20 levels.
- Use runners registered to parent groups:
- Secrets configured for the parent group are available to subgroup jobs.
- Users with the Maintainer role in projects that belong to subgroups can see the details of runners registered to parent groups.
- You must either:
To create a subgroup:
- On the top bar, select Menu > Groups and find and select the parent group to add a subgroup to.
- On the parent group’s overview page, in the top right, select New subgroup.
- Select Create group.
- Fill in the fields. View a list of reserved names that cannot be used as group names.
- Select Create group.
To create a subgroup, you must have at least the Maintainer role on the group, depending on the group’s setting. By default:
To change who can create subgroups on a group:
- As a user with the Owner role on the group:
- On the top bar, select Menu > Groups and find your group.
- On the left sidebar, select Settings > General.
- Expand Permissions and group features.
- Select a role from Roles allowed to create subgroups.
- Select Save changes.
- As an administrator:
- On the top bar, select Menu > Admin.
- On the left sidebar, select Overview > Groups.
- In the group’s row select Edit.
- Select a role from Allowed to create subgroups.
- Select Save changes.
For more information, view the permissions table.
When you add a member to a group, that member is also added to all subgroups. The user’s permissions are inherited from the group’s parent.
Subgroup members can:
- Be direct members of the subgroup.
- Inherit membership of the subgroup from the subgroup’s parent group.
- Be a member of a group that was shared with the subgroup’s top-level group.
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.
To see if a member has inherited the permissions from a parent group:
- On the top bar, select Menu > Groups and find the group.
- Select Group information > Members.
Members list for an example subgroup Four:
In the screenshot above:
- Five members have access to group Four.
- User 0 has the Reporter role on group Four, and has inherited their permissions from group One:
- User 0 is a direct member of group One.
- Group One is above group Four in the hierarchy.
- User 1 has the Developer role on group Four and inherited their permissions from group Two:
- User 0 is a direct member of group Two, which is a subgroup of group One.
- Groups One / Two are above group Four in the hierarchy.
- User 2 has the Developer role on group Four and has inherited their permissions from group Three:
- User 0 is a direct member of group Three, which is a subgroup of group Two. Group Two is a subgroup of group One.
- Groups One / Two / Three are above group Four the hierarchy.
- User 3 is a direct member of group Four. This means they get their Maintainer role directly from group Four.
- Administrator has the Owner role on group Four and is a member of all subgroups. For that reason, as with User 3, the Source column indicates they are a direct member.
Members can be filtered by inherited or direct membership.
Users with the Owner role on a subgroup can add members to it.
You can’t give a user a role on a subgroup that’s lower than the roles they have on ancestor groups. To override a user’s role on an ancestor group, add the user to the subgroup again with a higher role. For example:
- If User 1 is added to group Two with the Developer role, they inherit that role in every subgroup of group Two.
- To give User 1 the Maintainer role on group Four (under One / Two / Three), add them again to group Four with the Maintainer role.
- If User 1 is removed from group Four, their role falls back to their role on group Two. They have the Developer role on group Four again.
Mentioning subgroups (
@<subgroup_name>) in issues, commits, and merge requests
notifies all members of that group. Mentioning works the same as for projects and groups, and you can choose the group
of people to be notified.