Subgroups

You can organize GitLab groups into 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 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. To avoid performance problems, nest groups to a maximum of five levels or fewer. For more information, see recommended limits for group structure.
• Use runners registered to parent groups:
  • Secrets configured for the parent group are available to subgroup jobs.
  • Users with the Maintainer or Owner role in projects that belong to subgroups can see the details of runners registered to parent groups.

For example:

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
accTitle: Parent and subgroup nesting
accDescr: How parent groups, subgroups, and projects nest.

    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

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. In the top bar, select Search or go to and find your group.
2. In the left sidebar, select the Subgroups and projects tab.
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. All users can view the expand option ( ), but only direct or inherited members of the private subgroup can view the private group.

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:
  • The Maintainer or Owner role for a group.
  • 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.

To create a subgroup:

1. In the top bar, select Search or go to and find the group you want to create the subgroup in.
2. On the parent group’s overview page, in the upper-right corner, select New subgroup.
3. Fill in the fields. View a list of reserved names that cannot be used as group names.
4. Select Create subgroup.

Change who can create subgroups

Prerequisites:

• You must have the Maintainer or Owner 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. In the top bar, select Search or go to and find your group.
  2. Select Settings > General.
  3. Expand Permissions and group features.