Groups

DETAILS: Tier: Free, Premium, Ultimate Offering: SaaS, self-managed

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

You can use groups to 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 view analytics that show the group's activity.

You can use groups to communicate with all of the members of the group at once.

For larger organizations, you can also create subgroups.

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

NOTE: For self-managed customers it could be beneficial to create one single top-level group, so you can see an overview of your entire organization. For more information about efforts to create an organization view of all groups, see epic 9266. A single top-level group provides insights in your entire organization via a complete Security Dashboard and Center, Vulnerability and Compliance center, and Value stream analytics.

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.

View groups

To explore all public groups you are a member of:

1. On the left sidebar, select Search or go to.
2. Select View all my groups.
3. In the upper right, select Explore groups.

To view groups where you have direct or indirect membership:

1. On the left sidebar, select Search or go to.
2. 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 group activity

To view the activity of a group:

1. On the left sidebar, select Search or go to and find your group.

2. 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.
   • Comments: Comments posted by group members in the group's projects.
   • Wiki: Updates to wiki pages in the group.
   • Designs: Designs added, updated, and removed in the group's projects.
   • Team: Group members who joined and left the group's projects.

Create a group

To create a group:

1. On the left sidebar, at the top, select Create new ({plus}) and New group.
2. Select Create group.
3. In the Group name text box, enter the name of the group. For a list of words that cannot be used as group names, see reserved names.
4. In the Group URL text box, enter the path for the group used for the namespace.
5. Select the Visibility level of the group.
6. Optional. To personalize your GitLab experience:
   • From the Role dropdown list, select your role.
   • For Who will be using this group?, select an option.
   • From the What will you use this group for? dropdown list, select an option.
7. Optional. To invite members to the group, in the Email 1 text box, enter the email address of the user you want to invite. To invite more users, select Invite another member and enter the user's email address.
8. Select Create group.

For details about groups, watch GitLab Namespaces (users, groups and subgroups).

Edit group name and description

You can edit your group details from the group general settings.

Prerequisites:

• You must have the Owner role for the group.

To edit group details:

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > General.
3. In the Group name text box, enter your group name. See the limitations on group names.
4. Optional. In the Group description (optional) text box, enter your group description. The description is limited to 500 characters.
5. Select Save changes.

Leave a group

• The button to leave a group moved to the Actions menu in GitLab 16.7.

When you leave a group:

• You are no longer a member of the group, its subgroups, and projects, and cannot contribute.
• All the issues and merge requests that were assigned to you are unassigned.

To leave a group:

1. On the left sidebar, select Search or go to and find your group.
2. On the group overview page, in the upper-right corner, select Actions ({ellipsis_v}).
3. Select Leave group, then Leave group again.

Remove a group

• Enabled delayed deletion by default and removed the option to delete immediately on GitLab.com and on self-managed in GitLab 16.0.

To remove a group and its contents:

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > General.
3. Expand the Advanced section.
4. In the Remove group section, select Remove group.
5. On the confirmation dialog, type the group name and select Confirm.

You can also remove a group from the groups dashboard:

1. On the left sidebar, select Search or go to.
2. Select View all my groups.
3. Select ({ellipsis_v}) for the group you want to delete.
4. Select Delete.
5. In the Remove group section, select Remove group.
6. On the confirmation dialog, type the group name and select Confirm.

In GitLab 12.8 and later, on GitLab Premium and Ultimate, this action adds a background job to mark a group for deletion. By default, the job schedules the deletion seven days in the future. You can modify this retention period through the instance settings.

In GitLab 13.6 and later, if the user who sets up the deletion is removed from the group before the deletion happens, the job is cancelled, and the group is no longer scheduled for deletion.

Remove a group immediately

DETAILS: Tier: Premium, Ultimate Offering: SaaS, self-managed

• Introduced in GitLab 14.2.
• Enabled delayed deletion by default and removed the option to delete immediately on GitLab.com and on self-managed in GitLab 16.0.

If you don't want to wait, you can remove a group immediately.

Prerequisites:

• You must have the Owner role for a group.
• You have marked the group for deletion.

To immediately remove a group marked for deletion:

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > General.
3. Expand Advanced.
4. In the Permanently remove group section, select Remove group.
5. Confirm the action when asked to.

This action deletes the group, its subgroups, projects, and all related resources, including issues and merge requests.

Restore a group

DETAILS: Tier: Premium, Ultimate Offering: SaaS, self-managed

• Introduced in GitLab 12.8.

To restore a group that is marked for deletion:

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > General.
3. Expand the Advanced section.
4. In the Restore group section, select Restore group.

Request access to a group

As a user, you can request to be a member of a group, if an administrator allows it.

1. On the left sidebar, select Search or go to.
2. Select View all my groups.
3. In the upper right, select Explore groups.
4. In the Search by name text box, enter the name of the group you want to join.
5. In the search results, select the name of the group.
6. On the group page, under the group name, select Request Access.

Up to ten of the most recently active group owners receive an email with your request. Any group owner can approve or decline the request.

If you change your mind before your request is approved, select Withdraw Access Request.

View group members

To view a group's members:

1. On the left sidebar, select Search or go to and find your group.
2. Select Manage > Members.

A table displays the member's:

• Account name and username.
• Source of their membership. For transparency, GitLab displays all membership sources of group members. Members who have multiple membership sources are displayed and counted as separate members. For example, if a member has been added to the group both directly and through inheritance, the member is displayed twice in the Members table, with different sources, and is counted as two individual members of the group.
• Max role in the group.
• Expiration date of their group membership.
• Activity related to their account.

NOTE: The display of group members' Source might be inconsistent. For more information, see issue 23020.

Filter and sort members in a group

• Introduced in GitLab 12.6.
• Improved in GitLab 13.7.
• Feature flag removed in GitLab 13.8.

To find members in a group, you can sort, filter, or search.

Filter a group

Filter a group to find members. By default, all members in the group and subgroups are displayed.

In lists of group members, entries can display the following badges:

• SAML, to indicate the member has a SAML account connected to them.
• Enterprise, to indicate that the member of the top-level group is an enterprise user.

1. On the left sidebar, select Search or go to and find your group.
2. Select Manage > Members.
3. Above the list of members, in the Filter members text box, enter your search criteria. To view:
   • Direct members of the group, select Membership = Direct.
   • Members of the group and its subgroups, select Membership = Inherited.
   • Members with two-factor authentication enabled or disabled, select 2FA = Enabled or 2FA = Disabled.
   • Members of the top-level group who are enterprise users, select Enterprise = true.

Search a group

You can search for members by name, username, or public email.

1. On the left sidebar, select Search or go to and find your group.
2. Select Manage > Members.
3. Above the list of members, in the Filter members box, enter search criteria.
4. To the right of the Filter members box, select the magnifying glass ({search}).

Sort members in a group

You can sort members by Account, Access granted, Max role, or Last sign-in.

1. On the left sidebar, select Search or go to and find your group.
2. Select Manage > Members.
3. Above the list of members, in the upper-right corner, from the Account list, select the criteria to filter by.
4. To switch the sort between ascending and descending, to the right of the Account list, select the arrow ({sort-lowest} or {sort-highest}).

Add users to a group

• Expiring access email notification introduced in GitLab 16.2.

You can give a user access to all projects in a group.

Prerequisites:

• You must have the Owner role for the group.

1. On the left sidebar, select Search or go to and find your group.

2. Select Manage > Members.

3. Select Invite members.

4. If the user:

   • Has a GitLab account, enter the user's username.
   • Doesn't have a GitLab account, enter the user's email address.

5. Select a default role or custom role.

6. Optional. For Access expiration date, enter or select a date. From that date onward, the user can no longer access the project.

   If you enter an access expiration date, the group member gets an email notification seven days before their access expires.

   WARNING: If you give a member the Maintainer role and enter an expiration date, that member has full permissions as long as they are in the role. These permissions include the member's ability to extend their own time in the Maintainer role.

7. Select Invite. If you invite the user by their:

   • GitLab username, the user is added to the member list.
   • Email address, the user receives an email invitation and is prompted to create an account. If the invitation is not accepted, GitLab sends reminder emails two, five, and ten days later. Unaccepted invites are automatically deleted after 90 days.

Members that are not automatically added are displayed on the Invited tab. This tab includes users who:

• Have not yet accepted the invitation.
• Are waiting for approval from an administrator.
• Exceed the group user cap.

Remove a member from the group

Prerequisites:

• You must have the Owner role.
• The member must have direct membership in the group. If membership is inherited from a parent group, then the member can be removed from the parent group only.

To remove a member from a group:

1. On the left sidebar, select Search or go to and find your group.
2. Select Manage > Members.
3. Next to the member you want to remove, select the vertical ellipsis ({ellipsis_v}).
4. Select Remove member.
5. Optional. On the Remove member confirmation dialog, select one or both checkboxes:
   • Also remove direct user membership from subgroups and projects
   • Also unassign this user from linked issues and merge requests
6. Select Remove member.

GitLab administrators can also ensure removed users cannot invite themselves back.

Add projects to a group

You can add a new project to a group in two ways:

• Select a group, and then select New project. You can then continue creating your project.

• While you are creating a project, select a group from the dropdown list.

  

Specify who can add projects to a group

By default, users with at least the:

• Developer role can create projects under a group. This default can be changed.
• Maintainer role can fork projects into a group. This default prevents users with the Developer role from forking projects that contain protected branches and cannot be changed.

To change the role that can create projects under a group:

1. On the left sidebar, select Search or go to and find your group.
2. Select Settings > General.
3. Expand the Permissions and group features section.
4. From Roles allowed to create projects, select an option.
5. Select Save changes.

To change this setting globally, see Default project creation protection.

Get the group ID

• Group ID moved to the Actions menu in GitLab 16.7.

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

To copy the group ID:

1. On the left sidebar, select Search or go to and find your group.
2. On the group overview page, in the upper-right corner, select Actions ({ellipsis_v}).
3. Select Copy group ID.