Groups

In GitLab, you use groups to manage one or more related projects at the same time.

You can use groups to communicate with all group members and manage permissions for your projects. If someone has access to the group, they get access to all the projects in the group.

You can also view all of the issues and merge requests for the projects in the group, and analytics about the group’s activity.

For larger organizations, you can also create subgroups.

For more information about creating and managing your groups, see Manage groups.

Group hierarchy

Groups are organized in a tree structure:

• A top-level group is a group created at the “root” of the organization. An organization can have one or more top-level groups. A top-level group can contain one or more subgroups.
• A parent group is a group that contains one or more subgroups.
• A subgroup is a group that is part of another group.

For example, in the following diagram:

• The organization has four groups: one top-level group (T), which contains one subgroup (G), and two subgroups within G (A and B).
• T is a top-level group and the parent group of G.
• G is a subgroup (child) of T and the parent group of A and B.
• A and B are subgroups (children) of G.

%%{init: { "fontFamily": "GitLab Sans", 'theme':'neutral' }}%%
flowchart TD
  accTitle: Group hierarchy
  accDescr: Example of a group hierarchy in an organization

  subgraph Organization
    T[Group T] --> G[Group G]
    G --> A[Group A]
    G --> B[Group B]
end

Group structure

The way to set up a group depends on your use cases, team size, and access requirements. The following table describes the most common models of structuring groups.

Recommended limits for group structure

Groups have no enforced limits on membership, hierarchy depth, or the number of group shares. However, large or deeply nested structures can degrade performance. Dashboards can load slowly, permission calculations can time out, and some operations can return 500 errors. To keep a group responsive, stay within the following recommended limits:

Recommended limits differ from maximum limits. A maximum limit is a technical ceiling that GitLab enforces. If a group is beyond a recommended limit, it is still supported.

Performance issues are most severe when these limits combine. For example, a group that has both deep nesting and many child groups can cause database query timeouts sooner than either condition alone.

The recommended limits reflect current performance behavior. For details on planned work to help you move from a large, deeply nested structure to a more performant one, see epic 21582.

Stay within the recommended limits

If a group approaches or exceeds the recommended limits, you can use the following workarounds to reduce the performance impact.

For large group membership:

• Split a group that has more than 1,000 members into smaller functional groups, each with 500 members or fewer. For example, replace a single group of all engineers with separate groups for frontend, backend, and infrastructure engineers.
• Share each smaller group individually with projects and groups, rather than sharing one large group.
• For bulk member changes, use the group members API with delays between requests to stay within the member management rate limits.

For deep or wide hierarchies:

• Keep hierarchies to five levels or fewer.
• Use separate top-level groups for parts of your organization that do not need to share inherited membership, rather than nesting everything under one hierarchy.
• Reduce the number of direct child groups under a single parent group.

For group shares:

• Add a group directly to a project instead of sharing through nested group shares when you need to manage individual member permissions.
• If a new subgroup does not inherit permissions from a shared group, change the share’s role to a different value and then back again to trigger a permission recalculation.
• When you perform many group-share operations at once, such as bulk operations or automation, run them one at a time or with limited concurrency instead of all in parallel. Many simultaneous share operations against a group with large membership can create database contention and degrade instance responsiveness.
• Expect access from a group-to-group (nested) share to take longer to propagate than a direct project share, because it is applied as a delayed batch update.

For large hierarchies synced from an identity provider:

• Configure LDAP sync intervals to avoid rate limiting on the identity provider. Rate limit errors during a sync can block users or remove group memberships.

Group visibility

Like projects, a group can be configured to be visible to:

• Anonymous users.
• All authenticated users.
• Only explicit group members.

The restriction for visibility levels on the application setting level also applies to groups. If set to internal, the explore page is empty for anonymous users. The group page has a visibility level icon.

Users cannot create a subgroup or project with a higher visibility level than that of the immediate parent group.

Explore groups

To explore all public or internal groups:

1. In the top bar, select Search or go to.
2. From the dropdown, select Explore.
3. In the left sidebar, select Groups.

View groups you are a member of

To view groups where you have direct or indirect membership:

1. In the top bar, select Search or go to.
2. From the dropdown, select View all my groups.

This page shows groups that you are a member of through:

• Membership of a subgroup’s parent group.
• Direct or inherited membership of a project in the group or subgroup.

View inactive groups

A group is inactive when it is either pending deletion or it has been archived.

To view all inactive groups:

1. In the top bar, select Search or go to.
2. From the dropdown, select either:
   • View all my groups to filter groups you are a member of.
   • Explore to filter public or internal groups.
3. Select the Inactive tab.

Each inactive group in the list displays a badge to indicate that the group is either archived or pending deletion.

If the group is pending deletion, the list also shows:

• The time the group is scheduled for final deletion.
• A Restore action. When you restore a group:
  • The Pending deletion label is removed. The group is no longer scheduled for deletion.
  • The group is removed from the Inactive tab.

View a group

The group overview page displays information about the group and its members, subgroups, and projects, such as:

• Group description
• Recent activity
• Number of merge requests and issues created
• Number of members added
• Subgroups and projects
• Shared projects
• Archived projects

To view a group:

• In the top bar, select Search or go to and find your group.

You can search for the subgroups and projects of the group and sort them in ascending or descending order.

You can access a group by using its ID instead of its name at https://gitlab.example.com/-/g/<id>. For example, if your group example-group has an ID 123456, you can access the group either at https://gitlab.example.com/example-group or https://gitlab.example.com/-/g/123456.

Find the Group ID

You might need the group ID if you want to interact with it using the GitLab API.

To find the Group ID:

1. In the top bar, select Search or go to and find your group.
2. On the Group overview page, in the upper-right corner, select Actions ( ).
3. Select Copy Group ID.

View group activity

To view the activity of a group:

1. In the top bar, select Search or go to and find your group.

2. In the left sidebar, select Manage > Activity.

3. Optional. To filter activity by contribution type, select a tab:

   • All: All contributions by group members in the group and group’s projects.
   • Push events: Push events in the group’s projects.
   • Merge events: Accepted merge requests in the group’s projects.
   • Issue events: Issues opened and closed in the group’s projects.