Skip to content
GitLab

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:

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:

Group members page

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.