gitlab-org--gitlab-foss/doc/user/group/subgroups/index.md

stage	group	info
Manage	Workspace	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Subgroups (FREE)

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.

Subgroups can:

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

For example:

graph TD
    subgraph "Parent group"
      subgraph "Subgroup A"
        subgraph "Subgroup A1"
          G["Project E"]
        end
        C["Project A"]
        D["Project B"]
        E["Project C"]
      end
      subgraph "Subgroup B"
        F["Project D"]
      end
    end

Create a subgroup

Prerequisites:

• You must either:
  • Have at least the Maintainer role for a group to create subgroups for it.
  • Have the role determined by a setting. These users can create subgroups even if group creation is disabled by an Administrator in the user's settings.

NOTE: You cannot host a GitLab Pages subgroup website with a top-level domain name. For example, subgroupname.example.io.

To create a subgroup:

1. On the top bar, select Menu > Groups and find and select the parent group to add a subgroup to.
2. On the parent group's overview page, in the top right, select New subgroup.
3. Select Create group.
4. Fill in the fields. View a list of reserved names that cannot be used as group names.
5. Select Create group.

Change who can create subgroups

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:
  1. On the top bar, select Menu > Groups and find your group.
  2. On the left sidebar, select Settings > General.
  3. Expand Permissions and group features.
  4. Select a role from Roles allowed to create subgroups.
  5. Select Save changes.
• As an administrator:
  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Overview > Groups.
  3. In the group's row select Edit.
  4. Select a role from Allowed to create subgroups.
  5. Select Save changes.

For more information, view the permissions table.

Subgroup membership

NOTE: There is a bug that causes some pages in the parent group to be accessible by subgroup members. For more details, see this issue.

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:

1. Be direct members of the subgroup.
2. Inherit membership of the subgroup from the subgroup's parent group.
3. Be a member of a group that was shared with the subgroup's top-level group.

flowchart RL
  subgraph Group A
    A(Direct member)
    B{{Shared member}}
    subgraph Subgroup A
      H(1. Direct member)
      C{{2. Inherited member}}
      D{{Inherited member}}
      E{{3. Shared member}}
    end
    A-->|Direct membership of Group A\nInherited membership of Subgroup A|C
  end
  subgraph Group C
    G(Direct member)
  end
  subgraph Group B
    F(Direct member)
  end
  F-->|Group B\nshared with\nGroup A|B
  B-->|Inherited membership of Subgroup A|D
  G-->|Group C shared with Subgroup A|E

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 top bar, select Menu > Groups and find the group.
2. 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.

Override ancestor group 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.

Mention subgroups

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.