1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
|
---
stage: Data Stores
group: Tenant Scale
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Groups **(FREE)**
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](subgroups/index.md).
For more information about creating and managing your groups, see [Manage groups](manage.md).
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](https://gitlab.com/groups/gitlab-org/-/epics/9266).
A single top-level group provides insights in your entire organization via a complete
[Security Dashboard and Center](../application_security/security_dashboard/index.md),
[Vulnerability](../application_security/vulnerability_report/index.md#vulnerability-report) and
[Compliance Report](../compliance/compliance_report/index.md), and
[Value stream analytics](../group/value_stream_analytics/index.md).
## Group visibility
Like projects, a group can be configured to limit the visibility of it to:
- Anonymous users.
- All authenticated users.
- Only explicit group members.
The restriction for [visibility levels](../admin_area/settings/visibility_and_access_controls.md#restrict-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.
Administrator 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:
1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
1. Select **View all your groups**.
1. At the top right, select **Explore groups**.
To view groups where you have a direct or indirect membership:
1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
1. Select **View all your groups**.
This page shows groups that you are a member of:
- Through membership of a subgroup's parent group.
- Through direct or inherited membership of a project in the group or subgroup.
## Create a group
To create a group:
1. On the left sidebar, at the top, select **Create new...** (**{plus}**) and **New group**.
1. Select **Create group**.
1. Enter a name for the group in **Group name**. For a list of words that cannot be used as group names, see
[reserved names](../reserved_names.md).
1. Enter a path for the group in **Group URL**, which is used for the [namespace](../namespace/index.md).
1. Choose the [visibility level](../public_access.md).
1. Personalize your GitLab experience by answering the following questions:
- What is your role?
- Who is using this group?
- What are you using this group for?
1. Invite GitLab members or other users to join the group.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For details about groups, watch [GitLab Namespaces (users, groups and subgroups)](https://youtu.be/r0sJgjR2f5A).
## Remove a group
> Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) in GitLab 16.0.
To remove a group and its contents:
1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group.
1. On the left sidebar, select **Settings > General**.
1. Expand the **Advanced** section.
1. In the **Remove group** section, select **Remove group**.
1. Type the group name.
1. Select **Confirm**.
A group can also be removed from the groups dashboard:
1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
1. Select **View all your groups**.
1. Select (**{ellipsis_v}**) for the group you want to delete.
1. Select **Delete**.
1. In the Remove group section, select **Remove group**.
1. Type the group name.
1. Select **Confirm**.
This action removes the group. It also adds a background job to delete all projects in the group.
In [GitLab 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on GitLab [Premium](https://about.gitlab.com/pricing/premium/) and [Ultimate](https://about.gitlab.com/pricing/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](../admin_area/settings/visibility_and_access_controls.md#deletion-protection).
In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/39504), 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 **(PREMIUM)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/336985) in GitLab 14.2.
> - Enabled delayed deletion by default and removed the option to delete immediately [on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/393622) and [on self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119606) 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](#remove-a-group).
To immediately remove a group marked for deletion:
1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group.
1. Select **Settings > General**.
1. Expand **Advanced**.
1. In the "Permanently remove group" section, select **Remove group**.
1. Confirm the action when asked to.
Your group, its subgroups, projects, and all related resources, including issues and merge requests,
are deleted.
## Restore a group **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) in GitLab 12.8.
To restore a group that is marked for deletion:
1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group.
1. Select **Settings > General**.
1. Expand the **Advanced** section.
1. 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, expand the top-most chevron (**{chevron-down}**).
1. Select **View all your groups**.
1. At the top right side, select **Explore groups**.
1. Under the group name, select **Request Access**.
As many as 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**.
## Filter and sort members in a group
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21727) in GitLab 12.6.
> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/228675) in GitLab 13.7.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289911) 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](saml_sso/index.md) connected to them.
- **Enterprise**, to indicate that the member is an [enterprise user](../enterprise_user/index.md).
1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group.
1. Select **Manage > Members**.
1. Above the list of members, in the **Filter members** box, enter filter criteria.
- To view members in the group only, select **Membership = Direct**.
- To view members of the group and its subgroups, select **Membership = Inherited**.
- To view members with two-factor authentication enabled or disabled, select **2FA = Enabled** or **Disabled**.
- [In GitLab 14.0 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/349887), to view GitLab users created by [SAML SSO](saml_sso/index.md) or [SCIM provisioning](saml_sso/scim_setup.md) select **Enterprise = true**.
### Search a group
You can search for members by name, username, or email.
1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group.
1. Select **Manage > Members**.
1. Above the list of members, in the **Filter members** box, enter search criteria.
1. 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, at the top, select **Search GitLab** (**{search}**) to find your group.
1. Select **Manage > Members**.
1. Above the list of members, in the upper-right corner, from the **Account** list, select
the criteria to filter by.
1. 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
You can give a user access to all projects in a group.
Prerequisite:
- You must have the Owner role.
1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group.
1. Select **Manage > Members**.
1. Select **Invite members**.
1. Fill in the fields.
- The role applies to all projects in the group. For more information, see [permissions](../permissions.md).
- On the **Access expiration date**, the user can no longer access projects in the group.
1. Select **Invite**.
Members that are not automatically added are displayed on the **Invited** tab.
Users can be on this tab because they:
- Have not yet accepted the invitation.
- Are waiting for [approval from an administrator](../admin_area/moderate_users.md).
- [Exceed the group user cap](manage.md#user-cap-for-groups).
## 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, at the top, select **Search GitLab** (**{search}**) to find your group.
1. Select **Manage > Members**.
1. Next to the member you want to remove, select the vertical ellipsis (**{ellipsis_v}**).
1. Select **Remove member**.
1. Optional. On the **Remove member** confirmation box:
- To remove direct user membership from subgroups and projects, select the **Also remove direct user membership from subgroups and projects** checkbox.
- To unassign the user from linked issues and merge requests, select the **Also unassign this user from linked issues and merge requests** checkbox.
1. Select **Remove member**.
## Ensure removed users cannot invite themselves back
Malicious users with the Maintainer or Owner role could exploit a race condition that allows
them to invite themselves back to a group or project that a GitLab administrator has removed them from.
To avoid this problem, GitLab administrators can [ensure removed users cannot invite themselves back](../project/members/index.md#ensure-removed-users-cannot-invite-themselves-back).
## Add projects to a group
There are two different ways to add a new project to a group:
- Select a group, and then select **New project**. You can then continue [creating your project](../../user/project/index.md#create-a-project).
- While you are creating a project, select a group from the dropdown list.
![Select group](img/select_group_dropdown_13_10.png)
### Specify who can add projects to a group
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/2534) in GitLab 10.5.
> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25975) from GitLab Premium to GitLab Free in 11.10.
By default, users with at least the Developer role can create projects under a group.
To change this setting for a specific group:
1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group.
1. Select **Settings > General**.
1. Expand the **Permissions and group features** section.
1. Select the desired option in the **Roles allowed to create projects** dropdown list.
1. Select **Save changes**.
To change this setting globally, see [Default project creation protection](../admin_area/settings/visibility_and_access_controls.md#define-which-roles-can-create-projects).
|