groups.md 33.6 KB
Newer Older
1
# Groups API
2
3
4

## List groups

5
6
Get a list of visible groups for the authenticated user. When accessed without
authentication, only public groups are returned.
7

8
9
By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination).

10
11
Parameters:

12
13
14
15
16
17
18
19
20
21
22
| Attribute                | Type              | Required | Description |
| ------------------------ | ----------------- | -------- | ---------- |
| `skip_groups`            | array of integers | no       | Skip the group IDs passed |
| `all_available`          | boolean           | no       | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence |
| `search`                 | string            | no       | Return the list of authorized groups matching the search criteria |
| `order_by`               | string            | no       | Order groups by `name`, `path` or `id`. Default is `name` |
| `sort`                   | string            | no       | Order groups in `asc` or `desc` order. Default is `asc` |
| `statistics`             | boolean           | no       | Include group statistics (admins only) |
| `with_custom_attributes` | boolean           | no       | Include [custom attributes](custom_attributes.md) in response (admins only) |
| `owned`                  | boolean           | no       | Limit to groups explicitly owned by the current user |
| `min_access_level`       | integer           | no       | Limit to groups where current user has at least this [access level](members.md) |
23
24
25
26
27
28
29
30
31
32
33

```
GET /groups
```

```json
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
34
    "description": "An interesting group",
35
    "visibility": "public",
36
37
38
39
40
41
42
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
43
    "mentions_disabled": null,
44
45
46
47
48
    "lfs_enabled": true,
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "full_name": "Foobar Group",
49
    "full_path": "foo-bar",
50
    "file_template_project_id": 1,
51
    "parent_id": null
52
53
54
55
  }
]
```

56
57
58
59
60
61
62
63
64
65
66
67
68
69
When adding the parameter `statistics=true` and the authenticated user is an admin, additional group statistics are returned.

```
GET /groups?statistics=true
```

```json
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
70
71
72
73
74
75
76
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
77
    "mentions_disabled": null,
78
79
80
81
82
83
    "lfs_enabled": true,
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
84
    "file_template_project_id": 1,
85
86
87
88
    "parent_id": null,
    "statistics": {
      "storage_size" : 212,
      "repository_size" : 33,
89
      "wiki_size" : 100,
90
      "lfs_objects_size" : 123,
91
92
      "job_artifacts_size" : 57,
      "packages_size": 0
93
94
95
96
97
    }
  }
]
```

98
99
You can search for groups by name or path, see below.

100
101
102
103
104
105
You can filter by [custom attributes](custom_attributes.md) with:

```
GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value
```

JJ's avatar
JJ committed
106
## List a group's subgroups
107

108
109
> [Introduced][ce-15142] in GitLab 10.3.

110
111
112
Get a list of visible direct subgroups in this group.
When accessed without authentication, only public groups are returned.

113
114
By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination).

115
116
Parameters:

117
118
119
120
| Attribute                | Type              | Required | Description |
| ------------------------ | ----------------- | -------- | ----------- |
| `id`                     | integer/string    | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) of the parent group |
| `skip_groups`            | array of integers | no       | Skip the group IDs passed |
121
| `all_available`          | boolean           | no       | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence |
122
123
124
125
126
127
128
| `search`                 | string            | no       | Return the list of authorized groups matching the search criteria |
| `order_by`               | string            | no       | Order groups by `name`, `path` or `id`. Default is `name` |
| `sort`                   | string            | no       | Order groups in `asc` or `desc` order. Default is `asc` |
| `statistics`             | boolean           | no       | Include group statistics (admins only) |
| `with_custom_attributes` | boolean           | no       | Include [custom attributes](custom_attributes.md) in response (admins only) |
| `owned`                  | boolean           | no       | Limit to groups explicitly owned by the current user |
| `min_access_level`       | integer           | no       | Limit to groups where current user has at least this [access level](members.md) |
129
130
131
132
133
134
135
136
137
138
139
140
141

```
GET /groups/:id/subgroups
```

```json
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
142
143
144
145
146
147
148
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
149
    "mentions_disabled": null,
150
151
152
153
154
155
    "lfs_enabled": true,
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://gitlab.example.com/groups/foo-bar",
    "request_access_enabled": false,
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
156
    "file_template_project_id": 1,
157
158
159
160
161
    "parent_id": 123
  }
]
```

162
163
## List a group's projects

164
165
166
Get a list of projects in this group. When accessed without authentication, only public projects are returned.

By default, this request returns 20 results at a time because the API results [are paginated](README.md#pagination).
167
168
169
170
171
172
173

```
GET /groups/:id/projects
```

Parameters:

174
175
176
177
178
179
180
181
182
183
184
185
186
187
| Attribute                     | Type           | Required | Description |
| ----------------------------- | -------------- | -------- | ----------- |
| `id`                          | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `archived`                    | boolean        | no       | Limit by archived status |
| `visibility`                  | string         | no       | Limit by visibility `public`, `internal`, or `private` |
| `order_by`                    | string         | no       | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` |
| `sort`                        | string         | no       | Return projects sorted in `asc` or `desc` order. Default is `desc` |
| `search`                      | string         | no       | Return list of authorized projects matching the search criteria |
| `simple`                      | boolean        | no       | Return only the ID, URL, name, and path of each project |
| `owned`                       | boolean        | no       | Limit by projects owned by the current user |
| `starred`                     | boolean        | no       | Limit by projects starred by the current user |
| `with_issues_enabled`         | boolean        | no       | Limit by projects with issues feature enabled. Default is `false` |
| `with_merge_requests_enabled` | boolean        | no       | Limit by projects with merge requests feature enabled. Default is `false` |
| `with_shared`                 | boolean        | no       | Include projects shared to this group. Default is `true` |
188
189
| `include_subgroups`           | boolean        | no       | Include projects in subgroups of this group. Default is `false`   |
| `min_access_level`            | integer        | no       | Limit to projects where current user has at least this [access level](members.md) |
190
| `with_custom_attributes`      | boolean        | no       | Include [custom attributes](custom_attributes.md) in response (admins only) |
191
| `with_security_reports`       | boolean        | no       | **(ULTIMATE)** Return only projects that have security reports artifacts present in any of their builds. This means "projects with security reports enabled". Default is `false` |
192
193

Example response:
194
195
196
197
198
199
200
201
202

```json
[
  {
    "id": 9,
    "description": "foo",
    "default_branch": "master",
    "tag_list": [],
    "archived": false,
203
    "visibility": "internal",
204
205
206
207
208
209
210
211
212
213
    "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
    "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
    "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
    "name": "Html5 Boilerplate",
    "name_with_namespace": "Experimental / Html5 Boilerplate",
    "path": "html5-boilerplate",
    "path_with_namespace": "h5bp/html5-boilerplate",
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wiki_enabled": true,
214
    "jobs_enabled": true,
215
216
217
218
219
220
221
222
223
    "snippets_enabled": true,
    "created_at": "2016-04-05T21:40:50.169Z",
    "last_activity_at": "2016-04-06T16:52:08.432Z",
    "shared_runners_enabled": true,
    "creator_id": 1,
    "namespace": {
      "id": 5,
      "name": "Experimental",
      "path": "h5bp",
224
      "kind": "group"
225
226
227
228
229
    },
    "avatar_url": null,
    "star_count": 1,
    "forks_count": 0,
    "open_issues_count": 3,
230
    "public_jobs": true,
231
232
    "shared_with_groups": [],
    "request_access_enabled": false
233
234
235
236
237
238
  }
]
```

## Details of a group

239
Get all details of a group. This endpoint can be accessed without authentication
240
if the group is publicly accessible. In case the user that requests is admin of the group, it will return the `runners_token` for the group too.
241
242
243
244
245
246
247

```
GET /groups/:id
```

Parameters:

248
249
250
251
252
| Attribute                | Type           | Required | Description |
| ------------------------ | -------------- | -------- | ----------- |
| `id`                     | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. |
| `with_custom_attributes` | boolean        | no       | Include [custom attributes](custom_attributes.md) in response (admins only). |
| `with_projects`          | boolean        | no       | Include details from projects that belong to the specified group (defaults to `true`). |
253

254
```shell
255
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4
256
257
```

258
259
260
261
262
263
264
This endpoint returns:

- All projects and shared projects in GitLab 12.5 and earlier.
- A maximum of 100 projects and shared projects [in GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/31031)
  and later. To get the details of all projects within a group, use the
  [list a group's projects endpoint](#list-a-groups-projects) instead.

265
266
267
268
269
270
271
272
Example response:

```json
{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
273
  "visibility": "public",
274
275
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
276
  "request_access_enabled": false,
277
278
  "full_name": "Twitter",
  "full_path": "twitter",
279
  "runners_token": "ba324ca7b1c77fc20bb9",
280
  "file_template_project_id": 1,
281
  "parent_id": null,
282
283
284
285
286
287
288
  "projects": [
    {
      "id": 7,
      "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",
      "default_branch": "master",
      "tag_list": [],
      "archived": false,
289
      "visibility": "public",
290
291
292
293
294
295
296
297
298
299
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/typeahead-js.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/typeahead-js.git",
      "web_url": "https://gitlab.example.com/twitter/typeahead-js",
      "name": "Typeahead.Js",
      "name_with_namespace": "Twitter / Typeahead.Js",
      "path": "typeahead-js",
      "path_with_namespace": "twitter/typeahead-js",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
300
      "jobs_enabled": true,
301
302
303
304
305
306
307
308
309
310
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:25.578Z",
      "last_activity_at": "2016-06-17T07:47:25.881Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
311
        "kind": "group"
312
313
314
315
316
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 3,
317
      "public_jobs": true,
318
319
      "shared_with_groups": [],
      "request_access_enabled": false
320
321
322
323
324
325
326
    },
    {
      "id": 6,
      "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.",
      "default_branch": "master",
      "tag_list": [],
      "archived": false,
327
      "visibility": "internal",
328
329
330
331
332
333
334
335
336
337
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/flight.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/flight.git",
      "web_url": "https://gitlab.example.com/twitter/flight",
      "name": "Flight",
      "name_with_namespace": "Twitter / Flight",
      "path": "flight",
      "path_with_namespace": "twitter/flight",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
338
      "jobs_enabled": true,
339
340
341
342
343
344
345
346
347
348
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:24.661Z",
      "last_activity_at": "2016-06-17T07:47:24.838Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
349
        "kind": "group"
350
351
352
353
354
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 8,
355
      "public_jobs": true,
356
357
      "shared_with_groups": [],
      "request_access_enabled": false
358
359
360
361
362
363
364
365
366
    }
  ],
  "shared_projects": [
    {
      "id": 8,
      "description": "Velit eveniet provident fugiat saepe eligendi autem.",
      "default_branch": "master",
      "tag_list": [],
      "archived": false,
367
      "visibility": "private",
368
369
370
371
372
373
374
375
376
377
      "ssh_url_to_repo": "git@gitlab.example.com:h5bp/html5-boilerplate.git",
      "http_url_to_repo": "https://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "https://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "H5bp / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
378
      "jobs_enabled": true,
379
380
381
382
383
384
385
386
387
388
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:27.089Z",
      "last_activity_at": "2016-06-17T07:47:27.310Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "H5bp",
        "path": "h5bp",
389
        "kind": "group"
390
391
392
393
394
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 4,
395
      "public_jobs": true,
396
397
398
399
      "shared_with_groups": [
        {
          "group_id": 4,
          "group_name": "Twitter",
400
          "group_full_path": "twitter",
401
402
          "group_access_level": 30,
          "expires_at": null
403
404
405
406
        },
        {
          "group_id": 3,
          "group_name": "Gitlab Org",
407
          "group_full_path": "gitlab-org",
408
409
          "group_access_level": 10,
          "expires_at": "2018-08-14"
410
411
412
413
414
415
416
        }
      ]
    }
  ]
}
```

417
418
419
Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters:

420
Additional response parameters:
421
422

```json
423
424
425
{
  "id": 4,
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
426
427
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
428
429
  ...
}
430
431
```

432
433
When adding the parameter `with_projects=false`, projects will not be returned.

434
```shell
435
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4?with_projects=false
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
```

Example response:

```json
{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "full_name": "Twitter",
  "full_path": "twitter",
452
  "file_template_project_id": 1,
453
454
455
456
  "parent_id": null
}
```

457
458
459
460
461
462
463
464
465
466
467
468
### Disabling the results limit

The 100 results limit can be disabled if it breaks integrations developed using GitLab
12.4 and earlier.

To disable the limit while migrating to using the [list a group's projects](#list-a-groups-projects) endpoint, ask a GitLab administrator
with Rails console access to run the following command:

```ruby
Feature.disable(:limit_projects_in_groups_api)
```

469
470
471
472
473
474
475
476
477
478
## New group

Creates a new project group. Available only for users who can create groups.

```
POST /groups
```

Parameters:

479
480
481
482
483
484
| Attribute                            | Type    | Required | Description |
| ------------------------------------ | ------- | -------- | ----------- |
| `name`                               | string  | yes      | The name of the group. |
| `path`                               | string  | yes      | The path of the group. |
| `description`                        | string  | no       | The group's description. |
| `visibility`                         | string  | no       | The group's visibility. Can be `private`, `internal`, or `public`. |
485
486
487
488
489
| `share_with_group_lock`              | boolean | no       | Prevent sharing a project with another group within this group. |
| `require_two_factor_authentication`  | boolean | no       | Require all users in this group to setup Two-factor authentication. |
| `two_factor_grace_period`            | integer | no       | Time before Two-factor authentication is enforced (in hours). |
| `project_creation_level`             | string  | no       | Determine if developers can create projects in the group. Can be `noone` (No one), `maintainer` (Maintainers), or `developer` (Developers + Maintainers). |
| `auto_devops_enabled`                | boolean | no       | Default to Auto DevOps pipeline for all projects within this group. |
490
| `subgroup_creation_level`            | string  | no       | Allowed to create subgroups. Can be `owner` (Owners), or `maintainer` (Maintainers). |
491
| `emails_disabled`                    | boolean | no       | Disable email notifications |
492
| `mentions_disabled`                  | boolean | no       | Disable the capability of a group from getting mentioned |
493
494
495
| `lfs_enabled`                        | boolean | no       | Enable/disable Large File Storage (LFS) for the projects in this group. |
| `request_access_enabled`             | boolean | no       | Allow users to request member access. |
| `parent_id`                          | integer | no       | The parent group ID for creating nested group. |
496
497
| `shared_runners_minutes_limit`       | integer | no       | **(STARTER ONLY)** Pipeline minutes quota for this group. |
| `extra_shared_runners_minutes_limit` | integer | no       | **(STARTER ONLY)** Extra pipeline minutes quota for this group. |
498
499
500
501
502
503
504
505
506
507
508

## Transfer project to group

Transfer a project to the Group namespace. Available only for admin

```
POST  /groups/:id/projects/:project_id
```

Parameters:

509
510
511
512
| Attribute    | Type           | Required | Description |
| ------------ | -------------- | -------- | ----------- |
| `id`         | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user |
| `project_id` | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
513
514
515
516
517
518
519
520
521

## Update group

Updates the project group. Only available to group owners and administrators.

```
PUT /groups/:id
```

522
523
524
525
526
527
| Attribute                            | Type    | Required | Description |
| ------------------------------------ | ------- | -------- | ----------- |
| `id`                                 | integer | yes      | The ID of the group. |
| `name`                               | string  | no       | The name of the group. |
| `path`                               | string  | no       | The path of the group. |
| `description`                        | string  | no       | The description of the group. |
528
| `membership_lock`                    | boolean | no       | **(STARTER)** Prevent adding new members to project membership within this group. |
529
530
| `share_with_group_lock`              | boolean | no       | Prevent sharing a project with another group within this group. |
| `visibility`                         | string  | no       | The visibility level of the group. Can be `private`, `internal`, or `public`. |
531
532
533
534
535
| `share_with_group_lock`              | boolean | no       | Prevent sharing a project with another group within this group. |
| `require_two_factor_authentication`  | boolean | no       | Require all users in this group to setup Two-factor authentication. |
| `two_factor_grace_period`            | integer | no       | Time before Two-factor authentication is enforced (in hours). |
| `project_creation_level`             | string  | no       | Determine if developers can create projects in the group. Can be `noone` (No one), `maintainer` (Maintainers), or `developer` (Developers + Maintainers). |
| `auto_devops_enabled`                | boolean | no       | Default to Auto DevOps pipeline for all projects within this group. |
536
| `subgroup_creation_level`            | string  | no       | Allowed to create subgroups. Can be `owner` (Owners), or `maintainer` (Maintainers). |
537
| `emails_disabled`                    | boolean | no       | Disable email notifications |
538
| `mentions_disabled`                  | boolean | no       | Disable the capability of a group from getting mentioned |
539
540
| `lfs_enabled` (optional)             | boolean | no       | Enable/disable Large File Storage (LFS) for the projects in this group. |
| `request_access_enabled`             | boolean | no       | Allow users to request member access. |
541
542
543
| `file_template_project_id`           | integer | no       | **(PREMIUM)** The ID of a project to load custom file templates from. |
| `shared_runners_minutes_limit`       | integer | no       | **(STARTER ONLY)** Pipeline minutes quota for this group. |
| `extra_shared_runners_minutes_limit` | integer | no       | **(STARTER ONLY)** Extra pipeline minutes quota for this group. |
544

545
```shell
546
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental"
547
548
549

```

550
551
552
553
554
555
556
This endpoint returns:

- All projects and shared projects in GitLab 12.5 and earlier.
- A maximum of 100 projects and shared projects [in GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/31031)
  and later. To get the details of all projects within a group, use the
  [list a group's projects endpoint](#list-a-groups-projects) instead.

557
558
559
560
561
562
563
564
Example response:

```json
{
  "id": 5,
  "name": "Experimental",
  "path": "h5bp",
  "description": "foo",
565
  "visibility": "internal",
566
567
  "avatar_url": null,
  "web_url": "http://gitlab.example.com/groups/h5bp",
568
  "request_access_enabled": false,
569
570
  "full_name": "Foobar Group",
  "full_path": "foo-bar",
571
  "file_template_project_id": 1,
572
  "parent_id": null,
573
574
575
576
577
578
579
580
  "projects": [
    {
      "id": 9,
      "description": "foo",
      "default_branch": "master",
      "tag_list": [],
      "public": false,
      "archived": false,
581
      "visibility": "internal",
582
583
584
585
586
587
588
589
590
591
      "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
      "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "Experimental / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
592
      "jobs_enabled": true,
593
594
595
596
597
598
599
600
601
      "snippets_enabled": true,
      "created_at": "2016-04-05T21:40:50.169Z",
      "last_activity_at": "2016-04-06T16:52:08.432Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "Experimental",
        "path": "h5bp",
602
        "kind": "group"
603
604
605
606
607
      },
      "avatar_url": null,
      "star_count": 1,
      "forks_count": 0,
      "open_issues_count": 3,
608
      "public_jobs": true,
609
610
      "shared_with_groups": [],
      "request_access_enabled": false
611
612
613
614
615
    }
  ]
}
```

616
617
618
619
620
621
622
623
624
625
626
627
628
### Disabling the results limit

The 100 results limit can be disabled if it breaks integrations developed using GitLab
12.4 and earlier.

To disable the limit while migrating to using the
[list a group's projects](#list-a-groups-projects) endpoint, ask a GitLab administrator
with Rails console access to run the following command:

```ruby
Feature.disable(:limit_projects_in_groups_api)
```

629
630
## Remove group

631
632
633
634
635
Only available to group owners and administrators.

This endpoint either:

- Removes group, and queues a background job to delete all projects in the group as well.
636
- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/33257), on [Premium or Silver](https://about.gitlab.com/pricing/) or higher tiers, marks a group for deletion. The deletion will happen 7 days later by default, but this can be changed in the [instance settings](../user/admin_area/settings/visibility_and_access_controls.md#default-deletion-adjourned-period-premium-only).
637
638
639
640
641
642
643

```
DELETE /groups/:id
```

Parameters:

644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
| Attribute       | Type           | Required | Description |
| --------------- | -------------- | -------- | ----------- |
| `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |

The response will be `202 Accepted` if the user has authorization.

## Restore group marked for deletion **(PREMIUM)**

> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/33257) in GitLab 12.8.

Restores a group marked for deletion.

```plaintext
POST /groups/:id/restore
```

Parameters:
661

662
663
664
| Attribute       | Type           | Required | Description |
| --------------- | -------------- | -------- | ----------- |
| `id`            | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
Stan Hu's avatar
Stan Hu committed
665

666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
## Search for group

Get all groups that match your string in their name or path.

```
GET /groups?search=foobar
```

```json
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group"
  }
]
```

685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
## Hooks

Also called Group Hooks and Webhooks.
These are different from [System Hooks](system_hooks.md) that are system wide and [Project Hooks](projects.md#hooks) that are limited to one project.

### List group hooks

Get a list of group hooks

```
GET /groups/:id/hooks
```

| Attribute | Type            | Required | Description |
| --------- | --------------- | -------- | ----------- |
| `id`      | integer/string  | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |

### Get group hook

Get a specific hook for a group.

| Attribute | Type           | Required | Description |
| --------- | -------------- | -------- | ----------- |
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
| `hook_id` | integer        | yes      | The ID of a group hook |

```
GET /groups/:id/hooks/:hook_id
```

```json
{
  "id": 1,
  "url": "http://example.com/hook",
  "group_id": 3,
  "push_events": true,
  "issues_events": true,
  "confidential_issues_events": true,
  "merge_requests_events": true,
  "tag_push_events": true,
  "note_events": true,
  "job_events": true,
  "pipeline_events": true,
  "wiki_page_events": true,
  "enable_ssl_verification": true,
  "created_at": "2012-10-12T17:04:47Z"
}
```

### Add group hook

Adds a hook to a specified group.

```
POST /groups/:id/hooks
```

| Attribute                    | Type           | Required | Description |
| -----------------------------| -------------- | ---------| ----------- |
| `id`                         | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
| `url`                        | string         | yes      | The hook URL |
| `push_events`                | boolean        | no       | Trigger hook on push events |
| `issues_events`              | boolean        | no       | Trigger hook on issues events |
| `confidential_issues_events` | boolean        | no       | Trigger hook on confidential issues events |
| `merge_requests_events`      | boolean        | no       | Trigger hook on merge requests events |
| `tag_push_events`            | boolean        | no       | Trigger hook on tag push events |
| `note_events`                | boolean        | no       | Trigger hook on note events |
| `job_events`                 | boolean        | no       | Trigger hook on job events |
| `pipeline_events`            | boolean        | no       | Trigger hook on pipeline events |
| `wiki_page_events`           | boolean        | no       | Trigger hook on wiki events |
| `enable_ssl_verification`    | boolean        | no       | Do SSL verification when triggering the hook |
| `token`                      | string         | no       | Secret token to validate received payloads; this will not be returned in the response |

### Edit group hook

Edits a hook for a specified group.

```
PUT /groups/:id/hooks/:hook_id
```

| Attribute                    | Type           | Required | Description |
| ---------------------------- | -------------- | -------- | ----------- |
| `id`                         | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
| `hook_id`                    | integer        | yes      | The ID of the group hook |
| `url`                        | string         | yes      | The hook URL |
| `push_events`                | boolean        | no       | Trigger hook on push events |
| `issues_events`              | boolean        | no       | Trigger hook on issues events |
| `confidential_issues_events` | boolean        | no       | Trigger hook on confidential issues events |
| `merge_requests_events`      | boolean        | no       | Trigger hook on merge requests events |
| `tag_push_events`            | boolean        | no       | Trigger hook on tag push events |
| `note_events`                | boolean        | no       | Trigger hook on note events |
| `job_events`                 | boolean        | no       | Trigger hook on job events |
| `pipeline_events`            | boolean        | no       | Trigger hook on pipeline events |
| `wiki_events`                | boolean        | no       | Trigger hook on wiki events |
| `enable_ssl_verification`    | boolean        | no       | Do SSL verification when triggering the hook |
| `token`                      | string         | no       | Secret token to validate received payloads; this will not be returned in the response |

### Delete group hook

Removes a hook from a group. This is an idempotent method and can be called multiple times.
Either the hook is available or not.

```
DELETE /groups/:id/hooks/:hook_id
```

| Attribute | Type           | Required | Description |
| --------- | -------------- | -------- | ----------- |
| `id`      | integer/string | yes      | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) |
| `hook_id` | integer        | yes      | The ID of the group hook. |

797
798
799
800
## Group Audit Events **(STARTER)**

Group audit events can be accessed via the [Group Audit Events API](audit_events.md#group-audit-events-starter)

801
## Sync group with LDAP **(CORE ONLY)**
802
803
804
805
806
807
808
809
810
811
812

Syncs the group with its linked LDAP group. Only available to group owners and administrators.

```
POST /groups/:id/ldap_sync
```

Parameters:

- `id` (required) - The ID or path of a user group

813
814
## Group members

815
Please consult the [Group Members](members.md) documentation.
816

817
### Add LDAP group link **(CORE ONLY)**
818
819
820
821
822
823
824
825
826
827
828
829
830
831

Adds an LDAP group link.

```
POST /groups/:id/ldap_group_links
```

Parameters:

- `id` (required) - The ID of a group
- `cn` (required) - The CN of a LDAP group
- `group_access` (required) - Minimum access level for members of the LDAP group
- `provider` (required) - LDAP provider for the LDAP group

832
### Delete LDAP group link **(CORE ONLY)**
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856

Deletes an LDAP group link.

```
DELETE /groups/:id/ldap_group_links/:cn
```

Parameters:

- `id` (required) - The ID of a group
- `cn` (required) - The CN of a LDAP group

Deletes a LDAP group link for a specific LDAP provider

```
DELETE /groups/:id/ldap_group_links/:provider/:cn
```

Parameters:

- `id` (required) - The ID of a group
- `cn` (required) - The CN of a LDAP group
- `provider` (required) - Name of a LDAP provider

857
858
859
860
861
## Namespaces in groups

By default, groups only get 20 namespaces at a time because the API results are paginated.

To get more (up to 100), pass the following as an argument to the API call:
862

863
864
865
866
867
```
/groups?per_page=100
```

And to switch pages add:
868

869
870
871
```
/groups?per_page=100&page=2
```
872

873
[ce-15142]: https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15142
874
875
876
877

## Group badges

Read more in the [Group Badges](group_badges.md) documentation.