1--- 2stage: Manage 3group: Access 4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments 5--- 6 7# Groups API **(FREE)** 8 9## List groups 10 11Get a list of visible groups for the authenticated user. When accessed without 12authentication, only public groups are returned. 13 14By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). 15 16When accessed without authentication, this endpoint also supports [keyset pagination](index.md#keyset-based-pagination): 17 18- When requesting consecutive pages of results, we recommend you use keyset pagination. 19- Beyond a specific offset limit (specified by [max offset allowed by the REST API for offset-based pagination](../administration/instance_limits.md#max-offset-allowed-by-the-rest-api-for-offset-based-pagination)), offset pagination is unavailable. 20 21Parameters: 22 23| Attribute | Type | Required | Description | 24| ------------------------ | ----------------- | -------- | ---------- | 25| `skip_groups` | array of integers | no | Skip the group IDs passed | 26| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators); Attributes `owned` and `min_access_level` have precedence | 27| `search` | string | no | Return the list of authorized groups matching the search criteria | 28| `order_by` | string | no | Order groups by `name`, `path`, `id`, or `similarity` (if searching, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332889) in GitLab 14.1). Default is `name` | 29| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | 30| `statistics` | boolean | no | Include group statistics (administrators only) | 31| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | 32| `owned` | boolean | no | Limit to groups explicitly owned by the current user | 33| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md#valid-access-levels) | 34| `top_level_only` | boolean | no | Limit to top level groups, excluding all subgroups | 35 36```plaintext 37GET /groups 38``` 39 40```json 41[ 42 { 43 "id": 1, 44 "name": "Foobar Group", 45 "path": "foo-bar", 46 "description": "An interesting group", 47 "visibility": "public", 48 "share_with_group_lock": false, 49 "require_two_factor_authentication": false, 50 "two_factor_grace_period": 48, 51 "project_creation_level": "developer", 52 "auto_devops_enabled": null, 53 "subgroup_creation_level": "owner", 54 "emails_disabled": null, 55 "mentions_disabled": null, 56 "lfs_enabled": true, 57 "default_branch_protection": 2, 58 "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg", 59 "web_url": "http://localhost:3000/groups/foo-bar", 60 "request_access_enabled": false, 61 "full_name": "Foobar Group", 62 "full_path": "foo-bar", 63 "file_template_project_id": 1, 64 "parent_id": null, 65 "created_at": "2020-01-15T12:36:29.590Z" 66 } 67] 68``` 69 70When adding the parameter `statistics=true` and the authenticated user is an administrator, additional group statistics are returned. 71 72```plaintext 73GET /groups?statistics=true 74``` 75 76```json 77[ 78 { 79 "id": 1, 80 "name": "Foobar Group", 81 "path": "foo-bar", 82 "description": "An interesting group", 83 "visibility": "public", 84 "share_with_group_lock": false, 85 "require_two_factor_authentication": false, 86 "two_factor_grace_period": 48, 87 "project_creation_level": "developer", 88 "auto_devops_enabled": null, 89 "subgroup_creation_level": "owner", 90 "emails_disabled": null, 91 "mentions_disabled": null, 92 "lfs_enabled": true, 93 "default_branch_protection": 2, 94 "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg", 95 "web_url": "http://localhost:3000/groups/foo-bar", 96 "request_access_enabled": false, 97 "full_name": "Foobar Group", 98 "full_path": "foo-bar", 99 "file_template_project_id": 1, 100 "parent_id": null, 101 "created_at": "2020-01-15T12:36:29.590Z", 102 "statistics": { 103 "storage_size": 363, 104 "repository_size": 33, 105 "wiki_size": 100, 106 "lfs_objects_size": 123, 107 "job_artifacts_size": 57, 108 "pipeline_artifacts_size": 0, 109 "packages_size": 0, 110 "snippets_size": 50, 111 "uploads_size": 0 112 } 113 } 114] 115``` 116 117You can search for groups by name or path, see below. 118 119You can filter by [custom attributes](custom_attributes.md) with: 120 121```plaintext 122GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value 123``` 124 125## List a group's subgroups 126 127> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15142) in GitLab 10.3. 128 129Get a list of visible direct subgroups in this group. 130When accessed without authentication, only public groups are returned. 131 132By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). 133 134Parameters: 135 136| Attribute | Type | Required | Description | 137| ------------------------ | ----------------- | -------- | ----------- | 138| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) of the immediate parent group | 139| `skip_groups` | array of integers | no | Skip the group IDs passed | 140| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators); Attributes `owned` and `min_access_level` have precedence | 141| `search` | string | no | Return the list of authorized groups matching the search criteria. Only subgroup short paths are searched (not full paths) | 142| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` | 143| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | 144| `statistics` | boolean | no | Include group statistics (administrators only) | 145| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | 146| `owned` | boolean | no | Limit to groups explicitly owned by the current user | 147| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md#valid-access-levels) | 148 149```plaintext 150GET /groups/:id/subgroups 151``` 152 153```json 154[ 155 { 156 "id": 1, 157 "name": "Foobar Group", 158 "path": "foo-bar", 159 "description": "An interesting group", 160 "visibility": "public", 161 "share_with_group_lock": false, 162 "require_two_factor_authentication": false, 163 "two_factor_grace_period": 48, 164 "project_creation_level": "developer", 165 "auto_devops_enabled": null, 166 "subgroup_creation_level": "owner", 167 "emails_disabled": null, 168 "mentions_disabled": null, 169 "lfs_enabled": true, 170 "default_branch_protection": 2, 171 "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/foo.jpg", 172 "web_url": "http://gitlab.example.com/groups/foo-bar", 173 "request_access_enabled": false, 174 "full_name": "Foobar Group", 175 "full_path": "foo-bar", 176 "file_template_project_id": 1, 177 "parent_id": 123, 178 "created_at": "2020-01-15T12:36:29.590Z" 179 } 180] 181``` 182 183## List a group's descendant groups 184 185> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217115) in GitLab 13.5 186 187Get a list of visible descendant groups of this group. 188When accessed without authentication, only public groups are returned. 189 190By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). 191 192Parameters: 193 194| Attribute | Type | Required | Description | 195| ------------------------ | ----------------- | -------- | ----------- | 196| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) of the immediate parent group | 197| `skip_groups` | array of integers | no | Skip the group IDs passed | 198| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for administrators). Attributes `owned` and `min_access_level` have precedence | 199| `search` | string | no | Return the list of authorized groups matching the search criteria. Only descendant group short paths are searched (not full paths) | 200| `order_by` | string | no | Order groups by `name`, `path`, or `id`. Default is `name` | 201| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | 202| `statistics` | boolean | no | Include group statistics (administrators only) | 203| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | 204| `owned` | boolean | no | Limit to groups explicitly owned by the current user | 205| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md#valid-access-levels) | 206 207```plaintext 208GET /groups/:id/descendant_groups 209``` 210 211```json 212[ 213 { 214 "id": 2, 215 "name": "Bar Group", 216 "path": "foo/bar", 217 "description": "A subgroup of Foo Group", 218 "visibility": "public", 219 "share_with_group_lock": false, 220 "require_two_factor_authentication": false, 221 "two_factor_grace_period": 48, 222 "project_creation_level": "developer", 223 "auto_devops_enabled": null, 224 "subgroup_creation_level": "owner", 225 "emails_disabled": null, 226 "mentions_disabled": null, 227 "lfs_enabled": true, 228 "default_branch_protection": 2, 229 "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg", 230 "web_url": "http://gitlab.example.com/groups/foo/bar", 231 "request_access_enabled": false, 232 "full_name": "Bar Group", 233 "full_path": "foo/bar", 234 "file_template_project_id": 1, 235 "parent_id": 123, 236 "created_at": "2020-01-15T12:36:29.590Z" 237 }, 238 { 239 "id": 3, 240 "name": "Baz Group", 241 "path": "foo/bar/baz", 242 "description": "A subgroup of Bar Group", 243 "visibility": "public", 244 "share_with_group_lock": false, 245 "require_two_factor_authentication": false, 246 "two_factor_grace_period": 48, 247 "project_creation_level": "developer", 248 "auto_devops_enabled": null, 249 "subgroup_creation_level": "owner", 250 "emails_disabled": null, 251 "mentions_disabled": null, 252 "lfs_enabled": true, 253 "default_branch_protection": 2, 254 "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/baz.jpg", 255 "web_url": "http://gitlab.example.com/groups/foo/bar/baz", 256 "request_access_enabled": false, 257 "full_name": "Baz Group", 258 "full_path": "foo/bar/baz", 259 "file_template_project_id": 1, 260 "parent_id": 123, 261 "created_at": "2020-01-15T12:36:29.590Z" 262 } 263] 264``` 265 266## List a group's projects 267 268Get a list of projects in this group. When accessed without authentication, only public projects are returned. 269 270By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). 271 272```plaintext 273GET /groups/:id/projects 274``` 275 276Parameters: 277 278| Attribute | Type | Required | Description | 279| -------------------------------------- | -------------- | -------- | ----------- | 280| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | 281| `archived` | boolean | no | Limit by archived status | 282| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | 283| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `similarity` (1), or `last_activity_at` fields. Default is `created_at` | 284| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | 285| `search` | string | no | Return list of authorized projects matching the search criteria | 286| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | 287| `owned` | boolean | no | Limit by projects owned by the current user | 288| `starred` | boolean | no | Limit by projects starred by the current user | 289| `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` | 290| `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` | 291| `with_shared` | boolean | no | Include projects shared to this group. Default is `true` | 292| `include_subgroups` | boolean | no | Include projects in subgroups of this group. Default is `false` | 293| `min_access_level` | integer | no | Limit to projects where current user has at least this [access level](members.md#valid-access-levels) | 294| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | 295| `with_security_reports` **(ULTIMATE)** | boolean | no | Return only projects that have security reports artifacts present in any of their builds. This means "projects with security reports enabled". Default is `false` | 296 2971. Order by similarity: Orders the results by a similarity score calculated from the provided `search` 298URL parameter. When using `order_by=similarity`, the `sort` parameter is ignored. When the `search` 299parameter is not provided, the API returns the projects ordered by `name`. 300 301Example response: 302 303```json 304[ 305 { 306 "id": 9, 307 "description": "foo", 308 "default_branch": "master", 309 "tag_list": [], //deprecated, use `topics` instead 310 "topics": [], 311 "archived": false, 312 "visibility": "internal", 313 "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git", 314 "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git", 315 "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate", 316 "name": "Html5 Boilerplate", 317 "name_with_namespace": "Experimental / Html5 Boilerplate", 318 "path": "html5-boilerplate", 319 "path_with_namespace": "h5bp/html5-boilerplate", 320 "issues_enabled": true, 321 "merge_requests_enabled": true, 322 "wiki_enabled": true, 323 "jobs_enabled": true, 324 "snippets_enabled": true, 325 "created_at": "2016-04-05T21:40:50.169Z", 326 "last_activity_at": "2016-04-06T16:52:08.432Z", 327 "shared_runners_enabled": true, 328 "creator_id": 1, 329 "namespace": { 330 "id": 5, 331 "name": "Experimental", 332 "path": "h5bp", 333 "kind": "group" 334 }, 335 "avatar_url": null, 336 "star_count": 1, 337 "forks_count": 0, 338 "open_issues_count": 3, 339 "public_jobs": true, 340 "shared_with_groups": [], 341 "request_access_enabled": false 342 } 343] 344``` 345 346NOTE: 347To distinguish between a project in the group and a project shared to the group, the `namespace` attribute can be used. When a project has been shared to the group, its `namespace` differs from the group the request is being made for. 348 349## List a group's shared projects 350 351Get a list of projects shared to this group. When accessed without authentication, only public shared projects are returned. 352 353By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination). 354 355```plaintext 356GET /groups/:id/projects/shared 357``` 358 359Parameters: 360 361| Attribute | Type | Required | Description | 362| ----------------------------- | -------------- | -------- | ----------- | 363| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user | 364| `archived` | boolean | no | Limit by archived status | 365| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | 366| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | 367| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | 368| `search` | string | no | Return list of authorized projects matching the search criteria | 369| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | 370| `starred` | boolean | no | Limit by projects starred by the current user | 371| `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` | 372| `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` | 373| `min_access_level` | integer | no | Limit to projects where current user has at least this [access level](members.md#valid-access-levels) | 374| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only) | 375 376Example response: 377 378```json 379[ 380 { 381 "id":8, 382 "description":"Shared project for Html5 Boilerplate", 383 "name":"Html5 Boilerplate", 384 "name_with_namespace":"H5bp / Html5 Boilerplate", 385 "path":"html5-boilerplate", 386 "path_with_namespace":"h5bp/html5-boilerplate", 387 "created_at":"2020-04-27T06:13:22.642Z", 388 "default_branch":"master", 389 "tag_list":[], //deprecated, use `topics` instead 390 "topics":[], 391 "ssh_url_to_repo":"ssh://git@gitlab.com/h5bp/html5-boilerplate.git", 392 "http_url_to_repo":"http://gitlab.com/h5bp/html5-boilerplate.git", 393 "web_url":"http://gitlab.com/h5bp/html5-boilerplate", 394 "readme_url":"http://gitlab.com/h5bp/html5-boilerplate/-/blob/master/README.md", 395 "avatar_url":null, 396 "star_count":0, 397 "forks_count":4, 398 "last_activity_at":"2020-04-27T06:13:22.642Z", 399 "namespace":{ 400 "id":28, 401 "name":"H5bp", 402 "path":"h5bp", 403 "kind":"group", 404 "full_path":"h5bp", 405 "parent_id":null, 406 "avatar_url":null, 407 "web_url":"http://gitlab.com/groups/h5bp" 408 }, 409 "_links":{ 410 "self":"http://gitlab.com/api/v4/projects/8", 411 "issues":"http://gitlab.com/api/v4/projects/8/issues", 412 "merge_requests":"http://gitlab.com/api/v4/projects/8/merge_requests", 413 "repo_branches":"http://gitlab.com/api/v4/projects/8/repository/branches", 414 "labels":"http://gitlab.com/api/v4/projects/8/labels", 415 "events":"http://gitlab.com/api/v4/projects/8/events", 416 "members":"http://gitlab.com/api/v4/projects/8/members" 417 }, 418 "empty_repo":false, 419 "archived":false, 420 "visibility":"public", 421 "resolve_outdated_diff_discussions":false, 422 "container_registry_enabled":true, 423 "container_expiration_policy":{ 424 "cadence":"7d", 425 "enabled":true, 426 "keep_n":null, 427 "older_than":null, 428 "name_regex":null, 429 "name_regex_keep":null, 430 "next_run_at":"2020-05-04T06:13:22.654Z" 431 }, 432 "issues_enabled":true, 433 "merge_requests_enabled":true, 434 "wiki_enabled":true, 435 "jobs_enabled":true, 436 "snippets_enabled":true, 437 "can_create_merge_request_in":true, 438 "issues_access_level":"enabled", 439 "repository_access_level":"enabled", 440 "merge_requests_access_level":"enabled", 441 "forking_access_level":"enabled", 442 "wiki_access_level":"enabled", 443 "builds_access_level":"enabled", 444 "snippets_access_level":"enabled", 445 "pages_access_level":"enabled", 446 "emails_disabled":null, 447 "shared_runners_enabled":true, 448 "lfs_enabled":true, 449 "creator_id":1, 450 "import_status":"failed", 451 "open_issues_count":10, 452 "ci_default_git_depth":50, 453 "ci_forward_deployment_enabled":true, 454 "public_jobs":true, 455 "build_timeout":3600, 456 "auto_cancel_pending_pipelines":"enabled", 457 "build_coverage_regex":null, 458 "ci_config_path":null, 459 "shared_with_groups":[ 460 { 461 "group_id":24, 462 "group_name":"Commit451", 463 "group_full_path":"Commit451", 464 "group_access_level":30, 465 "expires_at":null 466 } 467 ], 468 "only_allow_merge_if_pipeline_succeeds":false, 469 "request_access_enabled":true, 470 "only_allow_merge_if_all_discussions_are_resolved":false, 471 "remove_source_branch_after_merge":true, 472 "printing_merge_request_link_enabled":true, 473 "merge_method":"merge", 474 "suggestion_commit_message":null, 475 "auto_devops_enabled":true, 476 "auto_devops_deploy_strategy":"continuous", 477 "autoclose_referenced_issues":true, 478 "repository_storage":"default" 479 } 480] 481``` 482 483## Details of a group 484 485Get all details of a group. This endpoint can be accessed without authentication 486if the group is publicly accessible. In case the user that requests is administrator of the group, it returns the `runners_token` for the group too. 487 488```plaintext 489GET /groups/:id 490``` 491 492Parameters: 493 494| Attribute | Type | Required | Description | 495| ------------------------ | -------------- | -------- | ----------- | 496| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. | 497| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (administrators only). | 498| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use the [list a group's projects endpoint](#list-a-groups-projects).) | 499 500NOTE: 501The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). 502To get the details of all projects within a group, use either the [list a group's projects](#list-a-groups-projects) or the [list a group's shared projects](#list-a-groups-shared-projects) endpoint. 503 504```shell 505curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4" 506``` 507 508This endpoint returns: 509 510- All projects and shared projects in GitLab 12.5 and earlier. 511- A maximum of 100 projects and shared projects [in GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/31031) 512 and later. To get the details of all projects within a group, use the 513 [list a group's projects endpoint](#list-a-groups-projects) instead. 514 515Example response: 516 517```json 518{ 519 "id": 4, 520 "name": "Twitter", 521 "path": "twitter", 522 "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.", 523 "visibility": "public", 524 "avatar_url": null, 525 "web_url": "https://gitlab.example.com/groups/twitter", 526 "request_access_enabled": false, 527 "full_name": "Twitter", 528 "full_path": "twitter", 529 "runners_token": "ba324ca7b1c77fc20bb9", 530 "file_template_project_id": 1, 531 "parent_id": null, 532 "created_at": "2020-01-15T12:36:29.590Z", 533 "shared_with_groups": [ 534 { 535 "group_id": 28, 536 "group_name": "H5bp", 537 "group_full_path": "h5bp", 538 "group_access_level": 20, 539 "expires_at": null 540 } 541 ], 542 "prevent_sharing_groups_outside_hierarchy": false, 543 "projects": [ // Deprecated and will be removed in API v5 544 { 545 "id": 7, 546 "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.", 547 "default_branch": "master", 548 "tag_list": [], //deprecated, use `topics` instead 549 "topics": [], 550 "archived": false, 551 "visibility": "public", 552 "ssh_url_to_repo": "git@gitlab.example.com:twitter/typeahead-js.git", 553 "http_url_to_repo": "https://gitlab.example.com/twitter/typeahead-js.git", 554 "web_url": "https://gitlab.example.com/twitter/typeahead-js", 555 "name": "Typeahead.Js", 556 "name_with_namespace": "Twitter / Typeahead.Js", 557 "path": "typeahead-js", 558 "path_with_namespace": "twitter/typeahead-js", 559 "issues_enabled": true, 560 "merge_requests_enabled": true, 561 "wiki_enabled": true, 562 "jobs_enabled": true, 563 "snippets_enabled": false, 564 "container_registry_enabled": true, 565 "created_at": "2016-06-17T07:47:25.578Z", 566 "last_activity_at": "2016-06-17T07:47:25.881Z", 567 "shared_runners_enabled": true, 568 "creator_id": 1, 569 "namespace": { 570 "id": 4, 571 "name": "Twitter", 572 "path": "twitter", 573 "kind": "group" 574 }, 575 "avatar_url": null, 576 "star_count": 0, 577 "forks_count": 0, 578 "open_issues_count": 3, 579 "public_jobs": true, 580 "shared_with_groups": [], 581 "request_access_enabled": false 582 }, 583 { 584 "id": 6, 585 "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.", 586 "default_branch": "master", 587 "tag_list": [], //deprecated, use `topics` instead 588 "topics": [], 589 "archived": false, 590 "visibility": "internal", 591 "ssh_url_to_repo": "git@gitlab.example.com:twitter/flight.git", 592 "http_url_to_repo": "https://gitlab.example.com/twitter/flight.git", 593 "web_url": "https://gitlab.example.com/twitter/flight", 594 "name": "Flight", 595 "name_with_namespace": "Twitter / Flight", 596 "path": "flight", 597 "path_with_namespace": "twitter/flight", 598 "issues_enabled": true, 599 "merge_requests_enabled": true, 600 "wiki_enabled": true, 601 "jobs_enabled": true, 602 "snippets_enabled": false, 603 "container_registry_enabled": true, 604 "created_at": "2016-06-17T07:47:24.661Z", 605 "last_activity_at": "2016-06-17T07:47:24.838Z", 606 "shared_runners_enabled": true, 607 "creator_id": 1, 608 "namespace": { 609 "id": 4, 610 "name": "Twitter", 611 "path": "twitter", 612 "kind": "group" 613 }, 614 "avatar_url": null, 615 "star_count": 0, 616 "forks_count": 0, 617 "open_issues_count": 8, 618 "public_jobs": true, 619 "shared_with_groups": [], 620 "request_access_enabled": false 621 } 622 ], 623 "shared_projects": [ // Deprecated and will be removed in API v5 624 { 625 "id": 8, 626 "description": "Velit eveniet provident fugiat saepe eligendi autem.", 627 "default_branch": "master", 628 "tag_list": [], //deprecated, use `topics` instead 629 "topics": [], 630 "archived": false, 631 "visibility": "private", 632 "ssh_url_to_repo": "git@gitlab.example.com:h5bp/html5-boilerplate.git", 633 "http_url_to_repo": "https://gitlab.example.com/h5bp/html5-boilerplate.git", 634 "web_url": "https://gitlab.example.com/h5bp/html5-boilerplate", 635 "name": "Html5 Boilerplate", 636 "name_with_namespace": "H5bp / Html5 Boilerplate", 637 "path": "html5-boilerplate", 638 "path_with_namespace": "h5bp/html5-boilerplate", 639 "issues_enabled": true, 640 "merge_requests_enabled": true, 641 "wiki_enabled": true, 642 "jobs_enabled": true, 643 "snippets_enabled": false, 644 "container_registry_enabled": true, 645 "created_at": "2016-06-17T07:47:27.089Z", 646 "last_activity_at": "2016-06-17T07:47:27.310Z", 647 "shared_runners_enabled": true, 648 "creator_id": 1, 649 "namespace": { 650 "id": 5, 651 "name": "H5bp", 652 "path": "h5bp", 653 "kind": "group" 654 }, 655 "avatar_url": null, 656 "star_count": 0, 657 "forks_count": 0, 658 "open_issues_count": 4, 659 "public_jobs": true, 660 "shared_with_groups": [ 661 { 662 "group_id": 4, 663 "group_name": "Twitter", 664 "group_full_path": "twitter", 665 "group_access_level": 30, 666 "expires_at": null 667 }, 668 { 669 "group_id": 3, 670 "group_name": "Gitlab Org", 671 "group_full_path": "gitlab-org", 672 "group_access_level": 10, 673 "expires_at": "2018-08-14" 674 } 675 ] 676 } 677 ] 678} 679``` 680 681The `prevent_sharing_groups_outside_hierarchy` attribute is present only on top-level groups. 682 683Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see 684the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters: 685 686Additional response parameters: 687 688```json 689{ 690 "id": 4, 691 "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.", 692 "shared_runners_minutes_limit": 133, 693 "extra_shared_runners_minutes_limit": 133, 694 ... 695} 696``` 697 698Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see 699the `marked_for_deletion_on` attribute: 700 701```json 702{ 703 "id": 4, 704 "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.", 705 "marked_for_deletion_on": "2020-04-03", 706 ... 707} 708``` 709 710When adding the parameter `with_projects=false`, projects aren't returned. 711 712```shell 713curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4?with_projects=false" 714``` 715 716Example response: 717 718```json 719{ 720 "id": 4, 721 "name": "Twitter", 722 "path": "twitter", 723 "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.", 724 "visibility": "public", 725 "avatar_url": null, 726 "web_url": "https://gitlab.example.com/groups/twitter", 727 "request_access_enabled": false, 728 "full_name": "Twitter", 729 "full_path": "twitter", 730 "file_template_project_id": 1, 731 "parent_id": null 732} 733``` 734 735### Download a Group avatar 736 737Get a group avatar. This endpoint can be accessed without authentication if the 738group is publicly accessible. 739 740```plaintext 741GET /groups/:id/avatar 742``` 743 744| Attribute | Type | Required | Description | 745| --------- | -------------- | -------- | --------------------- | 746| `id` | integer/string | yes | ID of the group | 747 748Example: 749 750```shell 751curl --header "PRIVATE-TOKEN: $GITLAB_LOCAL_TOKEN" \ 752 --remote-header-name \ 753 --remote-name \ 754 "https://gitlab.example.com/api/v4/groups/4/avatar" 755``` 756 757### Disable the results limit **(FREE SELF)** 758 759The 100 results limit can break integrations developed using GitLab 12.4 and earlier. 760 761For GitLab 12.5 to GitLab 13.12, the limit can be disabled while migrating to using the 762[list a group's projects](#list-a-groups-projects) endpoint. 763 764Ask a GitLab administrator with Rails console access to run the following command: 765 766```ruby 767Feature.disable(:limit_projects_in_groups_api) 768``` 769 770For GitLab 14.0 and later, the [limit cannot be disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/257829). 771 772## New group 773 774NOTE: 775On GitLab SaaS, you must use the GitLab UI to create groups without a parent group. You cannot 776use the API to do this. 777 778Creates a new project group. Available only for users who can create groups. 779 780```plaintext 781POST /groups 782``` 783 784Parameters: 785 786| Attribute | Type | Required | Description | 787| ------------------------------------------------------- | ------- | -------- | ----------- | 788| `name` | string | yes | The name of the group. | 789| `path` | string | yes | The path of the group. | 790| `description` | string | no | The group's description. | 791| `membership_lock` **(PREMIUM)** | boolean | no | Prevent adding new members to projects within this group. | 792| `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. | 793| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | 794| `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | 795| `two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours). | 796| `project_creation_level` | string | no | Determine if developers can create projects in the group. Can be `noone` (No one), `maintainer` (users with the Maintainer role), or `developer` (users with the Developer or Maintainer role). | 797| `auto_devops_enabled` | boolean | no | Default to Auto DevOps pipeline for all projects within this group. | 798| `subgroup_creation_level` | string | no | Allowed to [create subgroups](../user/group/subgroups/index.md#creating-a-subgroup). Can be `owner` (Owners), or `maintainer` (users with the Maintainer role). | 799| `emails_disabled` | boolean | no | Disable email notifications | 800| `avatar` | mixed | no | Image file for avatar of the group. [Introduced in GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36681) | 801| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned | 802| `lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group. | 803| `request_access_enabled` | boolean | no | Allow users to request member access. | 804| `parent_id` | integer | no | The parent group ID for creating nested group. | 805| `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). Default to the global level default branch protection setting. | 806| `shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | 807| `extra_shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | 808 809### Options for `default_branch_protection` 810 811The `default_branch_protection` attribute determines whether users with the Developer or [Maintainer role](../user/permissions.md) can push to the applicable [default branch](../user/project/repository/branches/default.md), as described in the following table: 812 813| Value | Description | 814|-------|-------------------------------------------------------------------------------------------------------------| 815| `0` | No protection. Users with the Developer or Maintainer role can: <br>- Push new commits<br>- Force push changes<br>- Delete the branch | 816| `1` | Partial protection. Users with the Developer or Maintainer role can: <br>- Push new commits | 817| `2` | Full protection. Only users with the Maintainer role can: <br>- Push new commits | 818 819## New Subgroup 820 821This is similar to creating a [New group](#new-group). You need the `parent_id` from the [List groups](#list-groups) call. You can then enter the desired: 822 823- `subgroup_path` 824- `subgroup_name` 825 826```shell 827curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ 828 --header "Content-Type: application/json" \ 829 --data '{"path": "<subgroup_path>", "name": "<subgroup_name>", "parent_id": <parent_group_id> }' \ 830 "https://gitlab.example.com/api/v4/groups/" 831``` 832 833## Transfer project to group 834 835Transfer a project to the Group namespace. Available only to instance administrators, although an [alternative API endpoint](projects.md#transfer-a-project-to-a-new-namespace) is available which does not require instance administrator role. Transferring projects may fail when tagged packages exist in the project's repository. 836 837```plaintext 838POST /groups/:id/projects/:project_id 839``` 840 841Parameters: 842 843| Attribute | Type | Required | Description | 844| ------------ | -------------- | -------- | ----------- | 845| `id` | integer/string | yes | The ID or [URL-encoded path of the target group](index.md#namespaced-path-encoding) | 846| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) | 847 848```shell 849curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ 850 "https://gitlab.example.com/api/v4/groups/4/projects/56" 851``` 852 853## Transfer a group to a new parent group / Turn a subgroup to a top-level group 854 855> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23831) in GitLab 14.6. 856 857Transfer a group to a new parent group or turn a subgroup to a top-level group. Available to administrators and users: 858 859- With the Owner role for the group to transfer. 860- With permission to [create a subgroup](../user/group/subgroups/index.md#creating-a-subgroup) in the new parent group if transferring a group. 861- With [permission to create a top-level group](../administration/user_settings.md#prevent-users-from-creating-top-level-groups) if turning a subgroup into a top-level group. 862 863```plaintext 864POST /groups/:id/transfer 865``` 866 867Parameters: 868 869| Attribute | Type | Required | Description | 870| ------------ | -------------- | -------- | ----------- | 871| `id` | integer | yes | ID of the group to transfer. | 872| `group_id` | integer | no | ID of the new parent group. When not specified, the group to transfer is instead turned into a top-level group. | 873 874```shell 875curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ 876 "https://gitlab.example.com/api/v4/groups/4/transfer?group_id=7" 877``` 878 879## Update group 880 881Updates the project group. Only available to group owners and administrators. 882 883```plaintext 884PUT /groups/:id 885``` 886 887| Attribute | Type | Required | Description | 888| ------------------------------------------------------- | ------- | -------- | ----------- | 889| `id` | integer | yes | The ID of the group. | 890| `name` | string | no | The name of the group. | 891| `path` | string | no | The path of the group. | 892| `description` | string | no | The description of the group. | 893| `membership_lock` **(PREMIUM)** | boolean | no | Prevent adding new members to projects within this group. | 894| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | 895| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. | 896| `require_two_factor_authentication` | boolean | no | Require all users in this group to setup Two-factor authentication. | 897| `two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours). | 898| `project_creation_level` | string | no | Determine if developers can create projects in the group. Can be `noone` (No one), `maintainer` (users with the Maintainer role), or `developer` (users with the Developer or Maintainer role). | 899| `auto_devops_enabled` | boolean | no | Default to Auto DevOps pipeline for all projects within this group. | 900| `subgroup_creation_level` | string | no | Allowed to [create subgroups](../user/group/subgroups/index.md#creating-a-subgroup). Can be `owner` (Owners), or `maintainer` (users with the Maintainer role). | 901| `emails_disabled` | boolean | no | Disable email notifications | 902| `avatar` | mixed | no | Image file for avatar of the group. [Introduced in GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/36681) | 903| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned | 904| `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group. | 905| `request_access_enabled` | boolean | no | Allow users to request member access. | 906| `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). | 907| `file_template_project_id` **(PREMIUM)** | integer | no | The ID of a project to load custom file templates from. | 908| `shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Pipeline minutes quota for this group (included in plan). Can be `nil` (default; inherit system default), `0` (unlimited) or `> 0` | 909| `extra_shared_runners_minutes_limit` **(PREMIUM SELF)** | integer | no | Extra pipeline minutes quota for this group (purchased in addition to the minutes included in the plan). | 910| `prevent_forking_outside_group` **(PREMIUM)** | boolean | no | When enabled, users can **not** fork projects from this group to external namespaces 911| `shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](#options-for-shared_runners_setting). Enable or disable shared runners for a group's subgroups and projects. | 912| `prevent_sharing_groups_outside_hierarchy` | boolean | no | See [Prevent group sharing outside the group hierarchy](../user/group/index.md#prevent-group-sharing-outside-the-group-hierarchy). This attribute is only available on top-level groups. [Introduced in GitLab 14.1](https://gitlab.com/gitlab-org/gitlab/-/issues/333721) | 913 914NOTE: 915The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). 916To get the details of all projects within a group, use either the [list a group's projects](#list-a-groups-projects) or the [list a group's shared projects](#list-a-groups-shared-projects) endpoint. 917 918```shell 919curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ 920 "https://gitlab.example.com/api/v4/groups/5?name=Experimental" 921``` 922 923This endpoint returns: 924 925- All projects and shared projects in GitLab 12.5 and earlier. 926- A maximum of 100 projects and shared projects [in GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/31031) 927 and later. To get the details of all projects within a group, use the 928 [list a group's projects endpoint](#list-a-groups-projects) instead. 929 930Example response: 931 932```json 933{ 934 "id": 5, 935 "name": "Experimental", 936 "path": "h5bp", 937 "description": "foo", 938 "visibility": "internal", 939 "avatar_url": null, 940 "web_url": "http://gitlab.example.com/groups/h5bp", 941 "request_access_enabled": false, 942 "full_name": "Foobar Group", 943 "full_path": "foo-bar", 944 "file_template_project_id": 1, 945 "parent_id": null, 946 "created_at": "2020-01-15T12:36:29.590Z", 947 "prevent_sharing_groups_outside_hierarchy": false, 948 "projects": [ // Deprecated and will be removed in API v5 949 { 950 "id": 9, 951 "description": "foo", 952 "default_branch": "master", 953 "tag_list": [], //deprecated, use `topics` instead 954 "topics": [], 955 "public": false, 956 "archived": false, 957 "visibility": "internal", 958 "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git", 959 "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git", 960 "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate", 961 "name": "Html5 Boilerplate", 962 "name_with_namespace": "Experimental / Html5 Boilerplate", 963 "path": "html5-boilerplate", 964 "path_with_namespace": "h5bp/html5-boilerplate", 965 "issues_enabled": true, 966 "merge_requests_enabled": true, 967 "wiki_enabled": true, 968 "jobs_enabled": true, 969 "snippets_enabled": true, 970 "created_at": "2016-04-05T21:40:50.169Z", 971 "last_activity_at": "2016-04-06T16:52:08.432Z", 972 "shared_runners_enabled": true, 973 "creator_id": 1, 974 "namespace": { 975 "id": 5, 976 "name": "Experimental", 977 "path": "h5bp", 978 "kind": "group" 979 }, 980 "avatar_url": null, 981 "star_count": 1, 982 "forks_count": 0, 983 "open_issues_count": 3, 984 "public_jobs": true, 985 "shared_with_groups": [], 986 "request_access_enabled": false 987 } 988 ] 989} 990``` 991 992The `prevent_sharing_groups_outside_hierarchy` attribute is present in the response only for top-level groups. 993 994### Disable the results limit **(FREE SELF)** 995 996The 100 results limit can break integrations developed using GitLab 12.4 and earlier. 997 998For GitLab 12.5 to GitLab 13.12, the limit can be disabled while migrating to using the 999[list a group's projects](#list-a-groups-projects) endpoint. 1000 1001Ask a GitLab administrator with Rails console access to run the following command: 1002 1003```ruby 1004Feature.disable(:limit_projects_in_groups_api) 1005``` 1006 1007For GitLab 14.0 and later, the [limit cannot be disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/257829). 1008 1009### Options for `shared_runners_setting` 1010 1011The `shared_runners_setting` attribute determines whether shared runners are enabled for a group's subgroups and projects. 1012 1013| Value | Description | 1014|-------|-------------------------------------------------------------------------------------------------------------| 1015| `enabled` | Enables shared runners for all projects and subgroups in this group. | 1016| `disabled_with_override` | Disables shared runners for all projects and subgroups in this group, but allows subgroups to override this setting. | 1017| `disabled_and_unoverridable` | Disables shared runners for all projects and subgroups in this group, and prevents subgroups from overriding this setting. | 1018 1019### Upload a group avatar 1020 1021> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36681) in GitLab 12.9. 1022 1023To upload an avatar file from your file system, use the `--form` argument. This causes 1024curl to post data using the header `Content-Type: multipart/form-data`. The 1025`file=` parameter must point to a file on your file system and be preceded by 1026`@`. For example: 1027 1028```shell 1029curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22" \ 1030 --form "avatar=@/tmp/example.png" 1031``` 1032 1033## Remove group 1034 1035Only available to group owners and administrators. 1036 1037This endpoint either: 1038 1039- Removes group, and queues a background job to delete all projects in the group as well. 1040- Since [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/33257), on [Premium](https://about.gitlab.com/pricing/) or higher tiers, marks a group for deletion. The deletion happens 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-delay). 1041 1042```plaintext 1043DELETE /groups/:id 1044``` 1045 1046Parameters: 1047 1048| Attribute | Type | Required | Description | 1049| --------------- | -------------- | -------- | ----------- | 1050| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1051 1052The response is `202 Accepted` if the user has authorization. 1053 1054NOTE: 1055A GitLab.com group can't be removed if it is linked to a subscription. To remove such a group, first [link the subscription](../subscriptions/index.md#change-the-linked-namespace) with a different group. 1056 1057## Restore group marked for deletion **(PREMIUM)** 1058 1059> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) in GitLab 12.8. 1060 1061Restores a group marked for deletion. 1062 1063```plaintext 1064POST /groups/:id/restore 1065``` 1066 1067Parameters: 1068 1069| Attribute | Type | Required | Description | 1070| --------------- | -------------- | -------- | ----------- | 1071| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1072 1073## Search for group 1074 1075Get all groups that match your string in their name or path. 1076 1077```plaintext 1078GET /groups?search=foobar 1079``` 1080 1081```json 1082[ 1083 { 1084 "id": 1, 1085 "name": "Foobar Group", 1086 "path": "foo-bar", 1087 "description": "An interesting group" 1088 } 1089] 1090``` 1091 1092## Hooks **(PREMIUM)** 1093 1094Also called Group Hooks and Webhooks. 1095These are different from [System Hooks](system_hooks.md) that are system wide and [Project Hooks](projects.md#hooks) that are limited to one project. 1096 1097### List group hooks 1098 1099Get a list of group hooks 1100 1101```plaintext 1102GET /groups/:id/hooks 1103``` 1104 1105| Attribute | Type | Required | Description | 1106| --------- | --------------- | -------- | ----------- | 1107| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1108 1109### Get group hook 1110 1111Get a specific hook for a group. 1112 1113| Attribute | Type | Required | Description | 1114| --------- | -------------- | -------- | ----------- | 1115| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1116| `hook_id` | integer | yes | The ID of a group hook | 1117 1118```plaintext 1119GET /groups/:id/hooks/:hook_id 1120``` 1121 1122```json 1123{ 1124 "id": 1, 1125 "url": "http://example.com/hook", 1126 "group_id": 3, 1127 "push_events": true, 1128 "issues_events": true, 1129 "confidential_issues_events": true, 1130 "merge_requests_events": true, 1131 "tag_push_events": true, 1132 "note_events": true, 1133 "confidential_note_events": true, 1134 "job_events": true, 1135 "pipeline_events": true, 1136 "wiki_page_events": true, 1137 "deployment_events": true, 1138 "releases_events": true, 1139 "subgroup_events": true, 1140 "enable_ssl_verification": true, 1141 "created_at": "2012-10-12T17:04:47Z" 1142} 1143``` 1144 1145### Add group hook 1146 1147Adds a hook to a specified group. 1148 1149```plaintext 1150POST /groups/:id/hooks 1151``` 1152 1153| Attribute | Type | Required | Description | 1154| -----------------------------| -------------- | ---------| ----------- | 1155| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1156| `url` | string | yes | The hook URL | 1157| `push_events` | boolean | no | Trigger hook on push events | 1158| `issues_events` | boolean | no | Trigger hook on issues events | 1159| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | 1160| `merge_requests_events` | boolean | no | Trigger hook on merge requests events | 1161| `tag_push_events` | boolean | no | Trigger hook on tag push events | 1162| `note_events` | boolean | no | Trigger hook on note events | 1163| `confidential_note_events` | boolean | no | Trigger hook on confidential note events | 1164| `job_events` | boolean | no | Trigger hook on job events | 1165| `pipeline_events` | boolean | no | Trigger hook on pipeline events | 1166| `wiki_page_events` | boolean | no | Trigger hook on wiki page events | 1167| `deployment_events` | boolean | no | Trigger hook on deployment events | 1168| `releases_events` | boolean | no | Trigger hook on release events | 1169| `subgroup_events` | boolean | no | Trigger hook on subgroup events | 1170| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | 1171| `token` | string | no | Secret token to validate received payloads; not returned in the response | 1172 1173### Edit group hook 1174 1175Edits a hook for a specified group. 1176 1177```plaintext 1178PUT /groups/:id/hooks/:hook_id 1179``` 1180 1181| Attribute | Type | Required | Description | 1182| ---------------------------- | -------------- | -------- | ----------- | 1183| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1184| `hook_id` | integer | yes | The ID of the group hook | 1185| `url` | string | yes | The hook URL | 1186| `push_events` | boolean | no | Trigger hook on push events | 1187| `issues_events` | boolean | no | Trigger hook on issues events | 1188| `confidential_issues_events` | boolean | no | Trigger hook on confidential issues events | 1189| `merge_requests_events` | boolean | no | Trigger hook on merge requests events | 1190| `tag_push_events` | boolean | no | Trigger hook on tag push events | 1191| `note_events` | boolean | no | Trigger hook on note events | 1192| `confidential_note_events` | boolean | no | Trigger hook on confidential note events | 1193| `job_events` | boolean | no | Trigger hook on job events | 1194| `pipeline_events` | boolean | no | Trigger hook on pipeline events | 1195| `wiki_page_events` | boolean | no | Trigger hook on wiki page events | 1196| `deployment_events` | boolean | no | Trigger hook on deployment events | 1197| `releases_events` | boolean | no | Trigger hook on release events | 1198| `subgroup_events` | boolean | no | Trigger hook on subgroup events | 1199| `enable_ssl_verification` | boolean | no | Do SSL verification when triggering the hook | 1200| `token` | string | no | Secret token to validate received payloads; not returned in the response | 1201 1202### Delete group hook 1203 1204Removes a hook from a group. This is an idempotent method and can be called multiple times. 1205Either the hook is available or not. 1206 1207```plaintext 1208DELETE /groups/:id/hooks/:hook_id 1209``` 1210 1211| Attribute | Type | Required | Description | 1212| --------- | -------------- | -------- | ----------- | 1213| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1214| `hook_id` | integer | yes | The ID of the group hook. | 1215 1216## Group Audit Events **(PREMIUM)** 1217 1218Group audit events can be accessed via the [Group Audit Events API](audit_events.md#group-audit-events) 1219 1220## Sync group with LDAP **(PREMIUM SELF)** 1221 1222Syncs the group with its linked LDAP group. Only available to group owners and administrators. 1223 1224```plaintext 1225POST /groups/:id/ldap_sync 1226``` 1227 1228Parameters: 1229 1230- `id` (required) - The ID or path of a user group 1231 1232## Group members 1233 1234Please consult the [Group Members](members.md) documentation. 1235 1236## LDAP Group Links 1237 1238List, add, and delete LDAP group links. 1239 1240### List LDAP group links **(PREMIUM SELF)** 1241 1242Lists LDAP group links. 1243 1244```plaintext 1245GET /groups/:id/ldap_group_links 1246``` 1247 1248| Attribute | Type | Required | Description | 1249| --------- | -------------- | -------- | ----------- | 1250| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1251 1252### Add LDAP group link with CN or filter **(PREMIUM SELF)** 1253 1254Adds an LDAP group link using a CN or filter. Adding a group link by filter is only supported in the Premium tier and above. 1255 1256```plaintext 1257POST /groups/:id/ldap_group_links 1258``` 1259 1260| Attribute | Type | Required | Description | 1261| --------- | -------------- | -------- | ----------- | 1262| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1263| `cn` | string | no | The CN of an LDAP group | 1264| `filter` | string | no | The LDAP filter for the group | 1265| `group_access` | integer | yes | Minimum [access level](members.md#valid-access-levels) for members of the LDAP group | 1266| `provider` | string | yes | LDAP provider for the LDAP group link | 1267 1268NOTE: 1269To define the LDAP group link, provide either a `cn` or a `filter`, but not both. 1270 1271### Delete LDAP group link **(PREMIUM SELF)** 1272 1273Deletes an LDAP group link. Deprecated. Scheduled for removal in a future release. 1274 1275```plaintext 1276DELETE /groups/:id/ldap_group_links/:cn 1277``` 1278 1279| Attribute | Type | Required | Description | 1280| --------- | -------------- | -------- | ----------- | 1281| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1282| `cn` | string | yes | The CN of an LDAP group | 1283 1284Deletes an LDAP group link for a specific LDAP provider. Deprecated. Scheduled for removal in a future release. 1285 1286```plaintext 1287DELETE /groups/:id/ldap_group_links/:provider/:cn 1288``` 1289 1290| Attribute | Type | Required | Description | 1291| --------- | -------------- | -------- | ----------- | 1292| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1293| `cn` | string | yes | The CN of an LDAP group | 1294| `provider` | string | yes | LDAP provider for the LDAP group link | 1295 1296### Delete LDAP group link with CN or filter **(PREMIUM SELF)** 1297 1298Deletes an LDAP group link using a CN or filter. Deleting by filter is only supported in the Premium tier and above. 1299 1300```plaintext 1301DELETE /groups/:id/ldap_group_links 1302``` 1303 1304| Attribute | Type | Required | Description | 1305| --------- | -------------- | -------- | ----------- | 1306| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1307| `cn` | string | no | The CN of an LDAP group | 1308| `filter` | string | no | The LDAP filter for the group | 1309| `provider` | string | yes | LDAP provider for the LDAP group link | 1310 1311NOTE: 1312To delete the LDAP group link, provide either a `cn` or a `filter`, but not both. 1313 1314## Namespaces in groups 1315 1316By default, groups only get 20 namespaces at a time because the API results are paginated. 1317 1318To get more (up to 100), pass the following as an argument to the API call: 1319 1320```plaintext 1321/groups?per_page=100 1322``` 1323 1324And to switch pages add: 1325 1326```plaintext 1327/groups?per_page=100&page=2 1328``` 1329 1330## Group badges 1331 1332Read more in the [Group Badges](group_badges.md) documentation. 1333 1334## Group Import/Export 1335 1336Read more in the [Group Import/Export](group_import_export.md) 1337and [Group Relations Export](group_relations_export.md) 1338documentation. 1339 1340## Share Groups with Groups 1341 1342These endpoints create and delete links for sharing a group with another group. For more information, see the related discussion in the [GitLab Groups](../user/group/index.md#share-a-group-with-another-group) page. 1343 1344### Create a link to share a group with another group 1345 1346Share group with another group. Returns `200` and the [group details](#details-of-a-group) on success. 1347 1348```plaintext 1349POST /groups/:id/share 1350``` 1351 1352| Attribute | Type | Required | Description | 1353| --------- | -------------- | -------- | ----------- | 1354| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1355| `group_id` | integer | yes | The ID of the group to share with | 1356| `group_access` | integer | yes | The [access level](members.md#valid-access-levels) to grant the group | 1357| `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 | 1358 1359### Delete link sharing group with another group 1360 1361Unshare the group from another group. Returns `204` and no content on success. 1362 1363```plaintext 1364DELETE /groups/:id/share/:group_id 1365``` 1366 1367| Attribute | Type | Required | Description | 1368| --------- | -------------- | -------- | ----------- | 1369| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1370| `group_id` | integer | yes | The ID of the group to share with | 1371 1372## Push Rules **(PREMIUM)** 1373 1374> Introduced in GitLab 13.4. 1375 1376### Get group push rules **(PREMIUM)** 1377 1378Get the [push rules](../user/group/index.md#group-push-rules) of a group. 1379 1380Only available to group owners and administrators. 1381 1382```plaintext 1383GET /groups/:id/push_rule 1384``` 1385 1386| Attribute | Type | Required | Description | 1387| --------- | ---- | -------- | ----------- | 1388| `id` | integer/string | yes | The ID of the group or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1389 1390```json 1391{ 1392 "id": 2, 1393 "created_at": "2020-08-17T19:09:19.580Z", 1394 "commit_message_regex": "[a-zA-Z]", 1395 "commit_message_negative_regex": "[x+]", 1396 "branch_name_regex": "[a-z]", 1397 "deny_delete_tag": true, 1398 "member_check": true, 1399 "prevent_secrets": true, 1400 "author_email_regex": "^[A-Za-z0-9.]+@gitlab.com$", 1401 "file_name_regex": "(exe)$", 1402 "max_file_size": 100 1403} 1404``` 1405 1406Users on [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see 1407the `commit_committer_check` and `reject_unsigned_commits` parameters: 1408 1409```json 1410{ 1411 "id": 2, 1412 "created_at": "2020-08-17T19:09:19.580Z", 1413 "commit_committer_check": true, 1414 "reject_unsigned_commits": false, 1415 ... 1416} 1417``` 1418 1419### Add group push rule **(PREMIUM)** 1420 1421Adds [push rules](../user/group/index.md#group-push-rules) to the specified group. 1422 1423Only available to group owners and administrators. 1424 1425```plaintext 1426POST /groups/:id/push_rule 1427``` 1428 1429| Attribute | Type | Required | Description | 1430| --------------------------------------------- | -------------- | -------- | ----------- | 1431| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1432| `deny_delete_tag` | boolean | no | Deny deleting a tag | 1433| `member_check` | boolean | no | Allows only GitLab users to author commits | 1434| `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | 1435| `commit_message_regex` | string | no | All commit messages must match the regular expression provided in this attribute, for example, `Fixed \d+\..*` | 1436| `commit_message_negative_regex` | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, for example, `ssh\:\/\/` | 1437| `branch_name_regex` | string | no | All branch names must match the regular expression provided in this attribute, for example, `(feature|hotfix)\/*` | 1438| `author_email_regex` | string | no | All commit author emails must match the regular expression provided in this attribute, for example, `@my-company.com$` | 1439| `file_name_regex` | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, for example, `(jar|exe)$` | 1440| `max_file_size` | integer | no | Maximum file size (MB) allowed | 1441| `commit_committer_check` | boolean | no | Only commits pushed using verified emails are allowed | 1442| `reject_unsigned_commits` | boolean | no | Only commits signed through GPG are allowed | 1443 1444```shell 1445curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" 1446``` 1447 1448Response: 1449 1450```json 1451{ 1452 "id": 19, 1453 "created_at": "2020-08-31T15:53:00.073Z", 1454 "commit_message_regex": "[a-zA-Z]", 1455 "commit_message_negative_regex": "[x+]", 1456 "branch_name_regex": null, 1457 "deny_delete_tag": false, 1458 "member_check": false, 1459 "prevent_secrets": false, 1460 "author_email_regex": "^[A-Za-z0-9.]+@gitlab.com$", 1461 "file_name_regex": null, 1462 "max_file_size": 100 1463} 1464``` 1465 1466### Edit group push rule **(PREMIUM)** 1467 1468Edit push rules for a specified group. 1469 1470Only available to group owners and administrators. 1471 1472```plaintext 1473PUT /groups/:id/push_rule 1474``` 1475 1476| Attribute | Type | Required | Description | 1477| --------------------------------------------- | -------------- | -------- | ----------- | 1478| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1479| `deny_delete_tag` | boolean | no | Deny deleting a tag | 1480| `member_check` | boolean | no | Restricts commits to be authored by existing GitLab users only | 1481| `prevent_secrets` | boolean | no | [Files that are likely to contain secrets](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/gitlab/checks/files_denylist.yml) are rejected | 1482| `commit_message_regex` | string | no | All commit messages must match the regular expression provided in this attribute, for example, `Fixed \d+\..*` | 1483| `commit_message_negative_regex` | string | no | Commit messages matching the regular expression provided in this attribute aren't allowed, for example, `ssh\:\/\/` | 1484| `branch_name_regex` | string | no | All branch names must match the regular expression provided in this attribute, for example, `(feature|hotfix)\/*` | 1485| `author_email_regex` | string | no | All commit author emails must match the regular expression provided in this attribute, for example, `@my-company.com$` | 1486| `file_name_regex` | string | no | Filenames matching the regular expression provided in this attribute are **not** allowed, for example, `(jar|exe)$` | 1487| `max_file_size` | integer | no | Maximum file size (MB) allowed | 1488| `commit_committer_check` | boolean | no | Only commits pushed using verified emails are allowed | 1489| `reject_unsigned_commits` | boolean | no | Only commits signed through GPG are allowed | 1490 1491```shell 1492curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule" 1493``` 1494 1495Response: 1496 1497```json 1498{ 1499 "id": 19, 1500 "created_at": "2020-08-31T15:53:00.073Z", 1501 "commit_message_regex": "[a-zA-Z]", 1502 "commit_message_negative_regex": "[x+]", 1503 "branch_name_regex": null, 1504 "deny_delete_tag": false, 1505 "member_check": false, 1506 "prevent_secrets": false, 1507 "author_email_regex": "^[A-Za-z0-9.]+@staging.gitlab.com$", 1508 "file_name_regex": null, 1509 "max_file_size": 100 1510} 1511``` 1512 1513### Delete group push rule **(PREMIUM)** 1514 1515Deletes the [push rules](../user/group/index.md#group-push-rules) of a group. 1516 1517Only available to group owners and administrators. 1518 1519```plaintext 1520DELETE /groups/:id/push_rule 1521``` 1522 1523| Attribute | Type | Required | Description | 1524| --------- | ---- | -------- | ----------- | 1525| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) | 1526
