index.md 16.7 KB
Newer Older
1 2 3 4
---
type: reference, howto
---

Marcia Ramos's avatar
Marcia Ramos committed
5 6
# Groups

7 8 9 10
With GitLab Groups, you can:

- Assemble related projects together.
- Grant members access to several projects at once.
Marcia Ramos's avatar
Marcia Ramos committed
11

12 13
For a video introduction to GitLab Groups, see [GitLab University: Repositories, Projects and Groups](https://www.youtube.com/watch?v=4TWfh1aKHHw).

Marcia Ramos's avatar
Marcia Ramos committed
14 15
Groups can also be nested in [subgroups](subgroups/index.md).

16
Find your groups by clicking **Groups > Your Groups** in the top navigation.
Marcia Ramos's avatar
Marcia Ramos committed
17 18 19

![GitLab Groups](img/groups.png)

20 21 22
> The **Groups** dropdown in the top navigation was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/36234) in [GitLab 11.1](https://about.gitlab.com/2018/07/22/gitlab-11-1-released/#groups-dropdown-in-navigation).

The **Groups** page displays:
23

24 25
- All groups you are a member of, when **Your groups** is selected.
- A list of public groups, when **Explore public groups** is selected.
26

27
Each group on the **Groups** page is listed with:
28

29 30 31 32 33 34
- How many subgroups it has.
- How many projects it contains.
- How many members the group has, not including members inherited from parent groups.
- The group's visibility.
- A link to the group's settings, if you have sufficient permissions.
- A link to leave the group, if you are a member.
Marcia Ramos's avatar
Marcia Ramos committed
35 36 37

## Use cases

38 39 40 41 42 43 44
You can create groups for numerous reasons. To name a couple:

- Grant access to multiple projects and multiple team members in fewer steps by organizing related projects under the same [namespace](#namespaces) and adding members to the top-level group.
- Make it easier to `@mention` all of your team at once in issues and merge requests by creating a group and including the appropriate members.

For example, you could create a group for your company members, and create a [subgroup](subgroups/index.md) for each individual team. Let's say you create a group called `company-team`, and you create subgroups in this group for the individual teams `backend-team`, `frontend-team`, and `production-team`.
    - When you start a new implementation from an issue, you add a comment:
Marcia Ramos's avatar
Marcia Ramos committed
45
        _"`@company-team`, let's do it! `@company-team/backend-team` you're good to go!"_
46
    - When your backend team needs help from frontend, they add a comment:
Marcia Ramos's avatar
Marcia Ramos committed
47
        _"`@company-team/frontend-team` could you help us here please?"_
48
    - When the frontend team completes their implementation, they comment:
Marcia Ramos's avatar
Marcia Ramos committed
49 50 51 52 53 54 55 56 57 58
        _"`@company-team/backend-team`, it's done! Let's ship it `@company-team/production-team`!"_

## Namespaces

In GitLab, a namespace is a unique name to be used as a user name, a group name, or a subgroup name.

- `http://gitlab.example.com/username`
- `http://gitlab.example.com/groupname`
- `http://gitlab.example.com/groupname/subgroup_name`

59
For example, consider a user named Alex:
Marcia Ramos's avatar
Marcia Ramos committed
60

61
1. Alex creates an account on GitLab.com with the username `alex`;
62
   their profile will be accessed under `https://gitlab.example.com/alex`
63
1. Alex creates a group for their team with the group name `alex-team`;
64
   the group and its projects will be accessed under `https://gitlab.example.com/alex-team`
65
1. Alex creates a subgroup of `alex-team` with the subgroup name `marketing`;
66
   this subgroup and its projects will be accessed under `https://gitlab.example.com/alex-team/marketing`
Marcia Ramos's avatar
Marcia Ramos committed
67 68 69

By doing so:

70 71 72
- Any team member mentions Alex with `@alex`
- Alex mentions everyone from their team with `@alex-team`
- Alex mentions only the marketing team with `@alex-team/marketing`
Marcia Ramos's avatar
Marcia Ramos committed
73

Marcia Ramos's avatar
Marcia Ramos committed
74
## Issues and merge requests within a group
Victor Wu's avatar
Victor Wu committed
75

76 77
Issues and merge requests are part of projects. For a given group, you can view all of the
[issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/index.md#merge-requests-per-group) across all projects in that group,
Marcia Ramos's avatar
Marcia Ramos committed
78
together in a single list view.
Victor Wu's avatar
Victor Wu committed
79

Marcia Ramos's avatar
Marcia Ramos committed
80 81
## Create a new group

Evan Read's avatar
Evan Read committed
82 83
> For a list of words that are not allowed to be used as group names see the
> [reserved names](../reserved_names.md).
84

85
To create a new Group, either:
Marcia Ramos's avatar
Marcia Ramos committed
86

87
- In the top menu, click **Groups** and then **Your Groups**, and click the green button **New group**.
Marcia Ramos's avatar
Marcia Ramos committed
88 89 90

    ![new group from groups page](img/new_group_from_groups.png)

91
- Or, in the top menu, expand the `plus` sign and choose **New group**.
Marcia Ramos's avatar
Marcia Ramos committed
92 93 94 95 96 97 98

    ![new group from elsewhere](img/new_group_from_other_pages.png)

Add the following information:

![new group info](img/create_new_group_info.png)

99 100
1. The **Group name** will automatically populate the URL. Optionally, you can change it.
   This is the name that displays in group views.
Evan Read's avatar
Evan Read committed
101
   The name can contain only:
102 103 104 105 106
     - Alphanumeric characters
     - Underscores
     - Dashes and dots
     - Spaces
1. The **Group URL** is the namespace under which your projects will be hosted.
Evan Read's avatar
Evan Read committed
107
   The URL can contain only:
108 109 110
     - Alphanumeric characters
     - Underscores
     - Dashes and dots (it cannot start with dashes or end in a dot)
Evan Read's avatar
Evan Read committed
111
1. Optionally, you can add a brief description to tell others
Marcia Ramos's avatar
Marcia Ramos committed
112
   what this group is about.
Evan Read's avatar
Evan Read committed
113
1. Optionally, choose an avatar for your group.
Marcia Ramos's avatar
Marcia Ramos committed
114 115
1. Choose the [visibility level](../../public_access/public_access.md).

116 117
For more details on creating groups, watch the video [GitLab Namespaces (users, groups and subgroups)](https://youtu.be/r0sJgjR2f5A).

Marcia Ramos's avatar
Marcia Ramos committed
118 119
## Add users to a group

120 121
A benefit of putting multiple projects in one group is that you can
give a user to access to all projects in the group with one action.
Marcia Ramos's avatar
Marcia Ramos committed
122

123
Add members to a group by navigating to the group's dashboard and clicking **Members**.
Marcia Ramos's avatar
Marcia Ramos committed
124

125
![add members to group](img/add_new_members.png)
Marcia Ramos's avatar
Marcia Ramos committed
126

127
Select the [permission level](../permissions.md#permissions), and add the new member. You can also set the expiring date for that user; this is the date on which they will no longer have access to your group.
Marcia Ramos's avatar
Marcia Ramos committed
128

129
Consider a group with two projects:
Marcia Ramos's avatar
Marcia Ramos committed
130

131
- On the **Group Members** page, you can now add a new user to the group.
132
- Now, because this user is a **Developer** member of the group, they automatically
133
  gets **Developer** access to **all projects** within that group.
Marcia Ramos's avatar
Marcia Ramos committed
134

135 136
To increase the access level of an existing user for a specific project,
add them again as a new member to the project with the desired permission level.
Marcia Ramos's avatar
Marcia Ramos committed
137 138 139

## Request access to a group

140 141
As a group owner, you can enable or disable the ability for non members to request access to
your group. Go to the group settings, and click **Allow users to request access**.
Marcia Ramos's avatar
Marcia Ramos committed
142

143
As a user, you can request to be a member of a group, if that setting is enabled. Go to the group for which you'd like to be a member, and click the **Request Access** button on the right
Marcia Ramos's avatar
Marcia Ramos committed
144 145 146 147
side of your screen.

![Request access button](img/request_access_button.png)

Mark Chao's avatar
doc  
Mark Chao committed
148
Group owners and maintainers will be notified of your request and will be able to approve or
Marcia Ramos's avatar
Marcia Ramos committed
149 150 151 152 153 154 155 156 157 158 159 160 161
decline it on the members page.

![Manage access requests](img/access_requests_management.png)

If you change your mind before your request is approved, just click the
**Withdraw Access Request** button.

![Withdraw access request button](img/withdraw_access_request_button.png)

## Add projects to a group

There are two different ways to add a new project to a group:

162
- Select a group, and then click **New project**. You can then continue [creating your project](../../gitlab-basics/create-project.md).
Marcia Ramos's avatar
Marcia Ramos committed
163 164 165 166 167 168 169 170

    ![New project](img/create_new_project_from_group.png)

- While you are creating a project, select a group namespace
  you've already created from the dropdown menu.

    ![Select group](img/select_group_dropdown.png)

171
### Default project-creation level
Gosia Ksionek's avatar
Gosia Ksionek committed
172

173 174 175 176
> [Introduced][ee-2534] in [GitLab Premium][ee] 10.5.
> Brought to [GitLab Starter][ee] in 10.7.
> [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25975) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.10.

177
Group owners and administrators can allow users with the
Gosia Ksionek's avatar
Gosia Ksionek committed
178 179
Developer role to create projects under groups.

180 181 182
By default, [Developers and Maintainers](../permissions.md#group-members-permissions) can create projects under a group. You can change this setting for a specific group within the group settings, or
you can set this option globally in the Admin area
at **Settings > General > Visibility and access controls** (you must be a GitLab administrator).
Gosia Ksionek's avatar
Gosia Ksionek committed
183 184 185

Available settings are `No one`, `Maintainers`, or `Developers + Maintainers`.

186
## Transfer projects into groups
Marcia Ramos's avatar
Marcia Ramos committed
187

188
Learn how to [transfer a project into a group](../project/settings/index.md#transferring-an-existing-project-into-another-namespace).
Marcia Ramos's avatar
Marcia Ramos committed
189

190 191 192
## Sharing a project with a group

You can [share your projects with a group](../project/members/share_project_with_groups.md)
193
and give all group members access to the project at once.
194

195
Alternatively, you can [lock the sharing with group feature](#share-with-group-lock).
196

Marcia Ramos's avatar
Marcia Ramos committed
197 198
## Manage group memberships via LDAP

199
In GitLab Enterprise Edition, it is possible to manage GitLab group memberships using LDAP groups.
Marcia Ramos's avatar
Marcia Ramos committed
200 201
See [the GitLab Enterprise Edition documentation](../../integration/ldap.md) for more information.

202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
## Epics **[ULTIMATE]**

> Introduced in [GitLab Ultimate][ee] 10.2.

Epics let you manage your portfolio of projects more efficiently and with less
effort by tracking groups of issues that share a theme, across projects and
milestones.

[Learn more about Epics.](epics/index.md)

## Group Security Dashboard **[ULTIMATE]**

Get an overview of the vulnerabilities of all the projects in a group and its subgroups.

[Learn more about the Group Security Dashboard.](security_dashboard/index.md)

## Insights **[ULTIMATE]**

> Introduced in [GitLab Ultimate][ee] 11.9 behind the `insights` feature flag.

222
Configure the Insights that matter for your groups or projects, allowing users to explore data
223
such as:
224 225 226 227 228

- Triage hygiene
- Issues created/closed per a given period
- Average time for merge requests to be merged
- Much more
229 230 231

[Learn more about Insights](insights/index.md).

232
## Transferring groups
233

234
From GitLab 10.5, you can transfer groups in the following ways:
235

236 237 238
- Transfer a subgroup to a new parent group.
- Convert a top-level group into a subgroup by transfering it to the desired group.
- Convert a subgroup into a top-level group by transfering it out of its current group.
239

240
When transferring groups, note:
241

242
- Changing a group's parent can have unintended side effects. See [Redirects when changing repository paths](../project/index.md#redirects-when-changing-repository-paths).
243
- You can only transfer groups to groups you manage.
244 245 246
- You must update your local repositories to point to the new location.
- If the parent group's visibility is lower than the group's current visibility, visibility levels for subgroups and projects will change to match the new parent group's visibility.
- Only explicit group membership is transferred, not inherited membership. If the group's owners have only inherited membership, this leaves the group without an owner. In this case, the user transferring the group becomes the group's owner.
247

Marcia Ramos's avatar
Marcia Ramos committed
248 249
## Group settings

250
After creating a group, you can manage its settings by navigating to
Marcia Ramos's avatar
Marcia Ramos committed
251 252 253 254 255 256
the group's dashboard, and clicking **Settings**.

![group settings](img/group_settings.png)

### General settings

257
In addition to editing any settings you previously
Marcia Ramos's avatar
Marcia Ramos committed
258 259 260
set when [creating the group](#create-a-new-group), you can also
access further configurations for your group.

261 262
#### Changing a group's path

263 264 265 266 267
Changing a group's path can have unintended side effects. Read
[how redirects will behave](../project/index.md#redirects-when-changing-repository-paths)
before proceeding.

If you are vacating the path so it can be claimed by another group or user,
268
you may need to rename the group, too, since both names and paths must
269
be unique.
270

271
To change your group path:
272

273
1. Navigate to your group's **Settings > General**.
274 275
1. Enter a new name under **Group path**.
1. Click **Save group**.
276

277 278 279 280 281 282 283 284 285
CAUTION: **Caution:**
It is currently not possible to rename a namespace if it contains a
project with [Container Registry](../project/container_registry.md) tags,
because the project cannot be moved.

TIP: **TIP:**
If you want to retain ownership over the original namespace and
protect the URL redirects, then instead of changing a group's path or renaming a
username, you can create a new group and transfer projects to it.
286

Marcia Ramos's avatar
Marcia Ramos committed
287 288
#### Enforce 2FA to group members

289
Add a security layer to your group by
Marcia Ramos's avatar
Marcia Ramos committed
290
[enforcing two-factor authentication (2FA)](../../security/two_factor_authentication.md#enforcing-2fa-for-all-users-in-a-group)
291
for all group members.
Marcia Ramos's avatar
Marcia Ramos committed
292

293 294 295
#### Share with group lock

Prevent projects in a group from [sharing
296
a project with another group](../project/members/share_project_with_groups.md) to enable tighter control over project access.
297

298
For example, let's say you have two distinct teams (Group A and Group B) working together in a project, and to inherit the group membership, you share the project between the
299
two groups A and B. **Share with group lock** prevents any project within
300 301
the group from being shared with another group,
guaranteeing that only the right group members have access to those projects.
302 303 304 305 306 307

To enable this feature, navigate to the group settings page. Select
**Share with group lock** and **Save the group**.

![Checkbox for share with group lock](img/share_with_group_lock.png)

308
#### Member Lock **[STARTER]**
309

310 311
Member lock lets a group owner prevent any new project membership to all of the
projects within a group, allowing tighter control over project membership.
Marcia Ramos's avatar
Marcia Ramos committed
312

313
For example, if you want to lock the group for an [Audit Event](../../administration/audit_events.md),
314
enable Member lock to guarantee that project membership cannot be modified during that audit.
Marcia Ramos's avatar
Marcia Ramos committed
315

316
To enable this feature:
317

318
1. Navigate to the group's **Settings > General** page.
319 320
1. Expand the **Permissions, LFS, 2FA** section, and select **Member lock**.
1. Click **Save changes**.
321

322 323 324
![Checkbox for membership lock](img/member_lock.png)

This will disable the option for all users who previously had permissions to
325
operate project memberships, so no new users can be added. Furthermore, any
326 327 328 329 330 331
request to add a new user to a project through API will not be possible.

#### Group file templates **[PREMIUM]**

Group file templates allow you to share a set of templates for common file
types with every project in a group. It is analogous to the
332
[instance template repository](../admin_area/settings/instance_template_repository.md)
333 334 335
feature, and the selected project should follow the same naming conventions as
are documented on that page.

336 337
You can only choose projects in the group as the template source.
This includes projects shared with the group, but it **excludes** projects in
338 339
subgroups or parent groups of the group being configured.

340
You can configure this feature for both subgroups and parent groups. A project
341 342 343 344 345 346 347 348 349 350
in a subgroup will have access to the templates for that subgroup, as well as
any parent groups.

![Group file template dropdown](img/group_file_template_dropdown.png)

To enable this feature, navigate to the group settings page, expand the
**Templates** section, choose a project to act as the template repository, and
**Save group**.

![Group file template settings](img/group_file_template_settings.png)
351

352 353
#### Group-level project templates **[PREMIUM]**

354
Define project templates at a group level by setting a group as the template source.
355
[Learn more about group-level project templates](custom_project_templates.md).
356

Marcia Ramos's avatar
Marcia Ramos committed
357 358
### Advanced settings

359
- **Projects**: View all projects within that group, add members to each project,
360
  access each project's settings, and remove any project, all from the same screen.
361 362
- **Webhooks**: Configure [webhooks](../project/integrations/webhooks.md) for your group.
- **Kubernetes cluster integration**: Connect your GitLab group with [Kubernetes clusters](clusters/index.md).
363
- **Audit Events**: View [Audit Events](../../administration/audit_events.md)
364
  for the group. **[STARTER ONLY]**
365
- **Pipelines quota**: Keep track of the [pipeline quota](../admin_area/settings/continuous_integration.md) for the group.
366 367 368

## User contribution analysis **[STARTER]**

369
With [GitLab Contribution Analytics](contribution_analytics/index.md),
370 371 372 373 374
you have an overview of the contributions (pushes, merge requests,
and issues) performed by your group members.

## Issues analytics **[PREMIUM]**

375
With [GitLab Issues Analytics](issues_analytics/index.md), you can see a bar chart of the number of issues created each month in your groups.
376

377 378 379 380
## Dependency Proxy **[PREMIUM]**

Use GitLab as a [dependency proxy](dependency_proxy/index.md) for upstream Docker images.

381 382 383 384 385 386 387 388 389 390 391 392
<!-- ## Troubleshooting

Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.

Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->

393 394
[ee]: https://about.gitlab.com/pricing/
[ee-2534]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2534