doc/user/group/_index.md
{{< details >}}
{{< /details >}}
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.
Groups are organized in a tree structure:
For example, in the following diagram:
%%{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
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.
<!-- vale gitlab_base.Simplicity = NO -->| Model | Structure | Use cases |
|---|---|---|
| Simple | One group for all your projects. | Work in a small team or on specific solutions (for example, a marketing website) that require seamless collaboration and access to resources. |
| Team | Different groups or subgroups for different types of teams (for example, product and engineering). | Work in a large organization where some teams work autonomously or require centralized resources and limited access from external team members. |
| Client | One group for each client. | Provide custom solutions for multiple clients that require different resources and access levels. |
| Functionality | One group or subgroup for one type of functionality (for example, AI/ML). | Develop complex products where one functionality requires specific resources and collaboration of subject-matter experts. |
[!note] On GitLab Self-Managed, if you want to see an overview of your entire organization, you should create one top-level group. For more information about efforts to create an organization view of all groups, see epic 9266. A top-level group offers insights in your entire organization through a complete Security Dashboard and Center, Vulnerability report, compliance center, and value stream analytics.
Like projects, a group can be configured to be visible to:
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.
To explore all public or internal groups:
{{< history >}}
your_work_groups_vue. Disabled by default.your_work_groups_vue removed.{{< /history >}}
To view groups where you have direct or indirect membership:
This page shows groups that you are a member of through:
{{< history >}}
your_work_groups_vue. Disabled by default.your_work_groups_vue removed.explore_groups_vue. Disabled by default.explore_groups_vue removed.{{< /history >}}
A group is inactive when it is either pending deletion or it has been archived.
To view all inactive groups:
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:
{{< history >}}
{{< /history >}}
The group overview page displays information about the group and its members, subgroups, and projects, such as:
To view a 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.
You might need the group ID if you want to interact with it using the GitLab API.
To find the Group ID:
To view the activity of a group:
In the top bar, select Search or go to and find your group.
Select Manage > Activity.
Optional. To filter activity by contribution type, select a tab:
To create a group:
<!-- vale gitlab_base.FutureTense = NO --><i class="fa-youtube-play" aria-hidden="true"></i> For details about groups, watch GitLab Namespaces (users, groups and subgroups).
You can edit your group details from the group general settings.
Prerequisites:
To edit group details:
{{< history >}}
{{< /history >}}
When you leave a group:
To leave a group:
{{< history >}}
{{< /history >}}
By default, when you delete a group for the first time, it enters a pending deletion state. Delete a group again to remove it immediately.
Prerequisites:
To delete a group and its contents:
You can also delete a group from the groups dashboard:
This action adds a background job to schedule a group for deletion. On GitLab.com, the group is deleted after 30 days. On GitLab Self-Managed, you can modify the retention period through the instance settings.
When a group is scheduled for deletion, scheduled CI/CD pipelines stop running.
If the user who scheduled the group deletion loses access to the group (for example, by leaving the group, having their role downgraded, or being banned from the group) before the deletion occurs, the deletion job instead restores the group, and the group is no longer scheduled for deletion.
[!warning] If the user who scheduled the group deletion regains Owner role or administrator access before the job runs, then the job removes the group permanently.
{{< history >}}
{{< /history >}}
If you don't want to wait, you can delete a group immediately.
Prerequisites:
To permanently delete a group scheduled for deletion:
This action deletes the group, its subgroups, projects, and all related resources, including issues and merge requests.
To restore a group that is scheduled for deletion:
You can view a list of all your groups and manage them with the Actions menu.
Prerequisites:
To access the Actions menu for groups:
The following actions are available, depending on the state of the group:
| Group state | Actions available |
|---|---|
| Active | Edit, Archive, Transfer, Leave group, Delete |
| Archived | Unarchive, Leave group, Delete |
| Pending deletion | Restore, Leave group |
As a user, you can request to be a member of a group, if an administrator allows it.
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.
To view members of a group:
A table displays the member's:
[!note] The display of group members' Source might be inconsistent. For more information, see issue 23020.
To view all namespace members (and their respective occupied seats), in the top-level namespace, view the Usage quotas page.
To find members in a group, you can sort, filter, or search.
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:
You can search for members by name, username, or public email.
You can sort members by Account, Access granted, Role, or Last sign-in.
{{< history >}}
{{< /history >}}
You can give a user access to all projects in a group.
Prerequisites:
In the top bar, select Search or go to and find your group.
Select Manage > Members.
Select Invite members.
If the user:
Select a default role or custom role.
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] Maintainers have full permissions until their role expires, including the ability to extend their own access expiration date.
Select Invite. If you invite the user by their:
Members that are not automatically added are displayed on the Invited tab. This tab includes users who:
If administrator approval for role promotions is turned on, membership requests that promote existing users into a billable role require administrator approval.
To view users pending promotion:
If the Role promotions tab is not displayed, the group has no pending promotions.
Prerequisites:
To remove a member from a group:
GitLab administrators can also ensure removed users cannot invite themselves back.
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.
By default, users with at least the:
To specify which roles can create projects in a group:
For more information about changing this setting globally, see default minimum role required to create projects.