2017-09-10 17:25:29 +05:30
# Groups API
2016-09-13 17:45:13 +05:30
## List groups
2018-03-17 18:26:18 +05:30
Get a list of visible groups for the authenticated user. When accessed without
authentication, only public groups are returned.
2017-08-17 22:00:37 +05:30
2020-01-01 13:55:28 +05:30
By default, this request returns 20 results at a time because the API results [are paginated ](README.md#pagination ).
2017-08-17 22:00:37 +05:30
Parameters:
2019-09-30 21:07:59 +05:30
| 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 ) |
2016-09-13 17:45:13 +05:30
```
GET /groups
```
```json
[
{
"id": 1,
"name": "Foobar Group",
"path": "foo-bar",
2017-08-17 22:00:37 +05:30
"description": "An interesting group",
"visibility": "public",
2019-12-21 20:55:43 +05:30
"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,
2020-03-09 13:42:32 +05:30
"mentions_disabled": null,
2017-08-17 22:00:37 +05:30
"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",
2018-12-13 13:39:08 +05:30
"file_template_project_id": 1,
2017-08-17 22:00:37 +05:30
"parent_id": null
2016-09-13 17:45:13 +05:30
}
]
```
2018-03-17 18:26:18 +05:30
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",
2019-12-21 20:55:43 +05:30
"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,
2020-03-09 13:42:32 +05:30
"mentions_disabled": null,
2018-03-17 18:26:18 +05:30
"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",
2018-12-13 13:39:08 +05:30
"file_template_project_id": 1,
2018-03-17 18:26:18 +05:30
"parent_id": null,
"statistics": {
"storage_size" : 212,
"repository_size" : 33,
2019-09-04 21:01:54 +05:30
"wiki_size" : 100,
2018-03-17 18:26:18 +05:30
"lfs_objects_size" : 123,
2019-09-30 21:07:59 +05:30
"job_artifacts_size" : 57,
"packages_size": 0
2018-03-17 18:26:18 +05:30
}
}
]
```
2016-09-13 17:45:13 +05:30
You can search for groups by name or path, see below.
2018-03-17 18:26:18 +05:30
You can filter by [custom attributes ](custom_attributes.md ) with:
```
GET /groups?custom_attributes[key]=value& custom_attributes[other_key]=other_value
```
2018-11-20 20:47:30 +05:30
## List a group's subgroups
2018-03-17 18:26:18 +05:30
> [Introduced][ce-15142] in GitLab 10.3.
Get a list of visible direct subgroups in this group.
When accessed without authentication, only public groups are returned.
2020-01-01 13:55:28 +05:30
By default, this request returns 20 results at a time because the API results [are paginated ](README.md#pagination ).
2018-03-17 18:26:18 +05:30
Parameters:
2019-09-30 21:07:59 +05:30
| 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 |
2020-03-09 13:42:32 +05:30
| `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 |
2019-09-30 21:07:59 +05:30
| `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 ) |
2018-03-17 18:26:18 +05:30
```
GET /groups/:id/subgroups
```
```json
[
{
"id": 1,
"name": "Foobar Group",
"path": "foo-bar",
"description": "An interesting group",
"visibility": "public",
2019-12-21 20:55:43 +05:30
"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,
2020-03-09 13:42:32 +05:30
"mentions_disabled": null,
2018-03-17 18:26:18 +05:30
"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",
2018-12-13 13:39:08 +05:30
"file_template_project_id": 1,
2018-03-17 18:26:18 +05:30
"parent_id": 123
}
]
```
2016-09-13 17:45:13 +05:30
## List a group's projects
2020-01-01 13:55:28 +05:30
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 ).
2016-09-13 17:45:13 +05:30
```
GET /groups/:id/projects
```
Parameters:
2019-09-30 21:07:59 +05:30
| 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` |
2019-12-04 20:38:33 +05:30
| `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 ) |
2019-09-30 21:07:59 +05:30
| `with_custom_attributes` | boolean | no | Include [custom attributes ](custom_attributes.md ) in response (admins only) |
2019-12-04 20:38:33 +05:30
| `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` |
2017-08-17 22:00:37 +05:30
Example response:
2016-09-13 17:45:13 +05:30
```json
[
{
"id": 9,
"description": "foo",
"default_branch": "master",
"tag_list": [],
"archived": false,
2017-08-17 22:00:37 +05:30
"visibility": "internal",
2016-09-13 17:45:13 +05:30
"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,
2017-08-17 22:00:37 +05:30
"jobs_enabled": true,
2016-09-13 17:45:13 +05:30
"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",
2017-08-17 22:00:37 +05:30
"kind": "group"
2016-09-13 17:45:13 +05:30
},
"avatar_url": null,
"star_count": 1,
"forks_count": 0,
"open_issues_count": 3,
2017-08-17 22:00:37 +05:30
"public_jobs": true,
2016-09-29 09:46:39 +05:30
"shared_with_groups": [],
"request_access_enabled": false
2016-09-13 17:45:13 +05:30
}
]
```
## Details of a group
2018-03-17 18:26:18 +05:30
Get all details of a group. This endpoint can be accessed without authentication
2019-12-04 20:38:33 +05:30
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.
2016-09-13 17:45:13 +05:30
```
GET /groups/:id
```
Parameters:
2019-09-30 21:07:59 +05:30
| 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` ). |
2016-09-13 17:45:13 +05:30
2020-03-09 13:42:32 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/groups/4
2016-09-13 17:45:13 +05:30
```
2020-01-01 13:55:28 +05:30
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.
2016-09-13 17:45:13 +05:30
Example response:
```json
{
"id": 4,
"name": "Twitter",
"path": "twitter",
"description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
2017-08-17 22:00:37 +05:30
"visibility": "public",
2016-09-13 17:45:13 +05:30
"avatar_url": null,
"web_url": "https://gitlab.example.com/groups/twitter",
2016-09-29 09:46:39 +05:30
"request_access_enabled": false,
2017-08-17 22:00:37 +05:30
"full_name": "Twitter",
"full_path": "twitter",
2019-12-04 20:38:33 +05:30
"runners_token": "ba324ca7b1c77fc20bb9",
2018-12-13 13:39:08 +05:30
"file_template_project_id": 1,
2017-08-17 22:00:37 +05:30
"parent_id": null,
2016-09-13 17:45:13 +05:30
"projects": [
{
"id": 7,
"description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",
"default_branch": "master",
"tag_list": [],
"archived": false,
2017-08-17 22:00:37 +05:30
"visibility": "public",
2016-09-13 17:45:13 +05:30
"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,
2017-08-17 22:00:37 +05:30
"jobs_enabled": true,
2016-09-13 17:45:13 +05:30
"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",
2017-08-17 22:00:37 +05:30
"kind": "group"
2016-09-13 17:45:13 +05:30
},
"avatar_url": null,
"star_count": 0,
"forks_count": 0,
"open_issues_count": 3,
2017-08-17 22:00:37 +05:30
"public_jobs": true,
2016-09-29 09:46:39 +05:30
"shared_with_groups": [],
"request_access_enabled": false
2016-09-13 17:45:13 +05:30
},
{
"id": 6,
"description": "Aspernatur omnis repudiandae qui voluptatibus eaque.",
"default_branch": "master",
"tag_list": [],
"archived": false,
2017-08-17 22:00:37 +05:30
"visibility": "internal",
2016-09-13 17:45:13 +05:30
"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,
2017-08-17 22:00:37 +05:30
"jobs_enabled": true,
2016-09-13 17:45:13 +05:30
"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",
2017-08-17 22:00:37 +05:30
"kind": "group"
2016-09-13 17:45:13 +05:30
},
"avatar_url": null,
"star_count": 0,
"forks_count": 0,
"open_issues_count": 8,
2017-08-17 22:00:37 +05:30
"public_jobs": true,
2016-09-29 09:46:39 +05:30
"shared_with_groups": [],
"request_access_enabled": false
2016-09-13 17:45:13 +05:30
}
],
"shared_projects": [
{
"id": 8,
"description": "Velit eveniet provident fugiat saepe eligendi autem.",
"default_branch": "master",
"tag_list": [],
"archived": false,
2017-08-17 22:00:37 +05:30
"visibility": "private",
2016-09-13 17:45:13 +05:30
"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,
2017-08-17 22:00:37 +05:30
"jobs_enabled": true,
2016-09-13 17:45:13 +05:30
"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",
2017-08-17 22:00:37 +05:30
"kind": "group"
2016-09-13 17:45:13 +05:30
},
"avatar_url": null,
"star_count": 0,
"forks_count": 0,
"open_issues_count": 4,
2017-08-17 22:00:37 +05:30
"public_jobs": true,
2016-09-13 17:45:13 +05:30
"shared_with_groups": [
{
"group_id": 4,
"group_name": "Twitter",
2019-03-02 22:35:43 +05:30
"group_full_path": "twitter",
2018-11-20 20:47:30 +05:30
"group_access_level": 30,
"expires_at": null
2016-09-13 17:45:13 +05:30
},
{
"group_id": 3,
"group_name": "Gitlab Org",
2019-03-02 22:35:43 +05:30
"group_full_path": "gitlab-org",
2018-11-20 20:47:30 +05:30
"group_access_level": 10,
"expires_at": "2018-08-14"
2016-09-13 17:45:13 +05:30
}
]
}
]
}
```
2019-09-30 21:07:59 +05:30
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:
Additional response parameters:
```json
{
"id": 4,
"description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
"shared_runners_minutes_limit": 133,
"extra_shared_runners_minutes_limit": 133,
...
}
```
2018-11-18 11:00:15 +05:30
When adding the parameter `with_projects=false` , projects will not be returned.
2020-03-09 13:42:32 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: < your_access_token > " https://gitlab.example.com/api/v4/groups/4?with_projects=false
2018-11-18 11:00:15 +05:30
```
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",
2018-12-13 13:39:08 +05:30
"file_template_project_id": 1,
2018-11-18 11:00:15 +05:30
"parent_id": null
}
```
2020-01-01 13:55:28 +05:30
### 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)
```
2016-09-13 17:45:13 +05:30
## New group
Creates a new project group. Available only for users who can create groups.
```
POST /groups
```
Parameters:
2019-09-30 21:07:59 +05:30
| 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` . |
2019-12-21 20:55:43 +05:30
| `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. |
2020-03-09 13:42:32 +05:30
| `subgroup_creation_level` | string | no | Allowed to create subgroups. Can be `owner` (Owners), or `maintainer` (Maintainers). |
2019-12-21 20:55:43 +05:30
| `emails_disabled` | boolean | no | Disable email notifications |
2020-03-09 13:42:32 +05:30
| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned |
2019-09-30 21:07:59 +05:30
| `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. |
| `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. |
2016-09-13 17:45:13 +05:30
## Transfer project to group
Transfer a project to the Group namespace. Available only for admin
```
POST /groups/:id/projects/:project_id
```
Parameters:
2019-09-30 21:07:59 +05:30
| 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 ) |
2016-09-13 17:45:13 +05:30
## Update group
Updates the project group. Only available to group owners and administrators.
```
PUT /groups/:id
```
2019-09-30 21:07:59 +05:30
| 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. |
| `membership_lock` | boolean | no | ** (STARTER)** Prevent adding new members to project membership within this group. |
| `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` . |
2019-12-21 20:55:43 +05:30
| `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. |
2020-03-09 13:42:32 +05:30
| `subgroup_creation_level` | string | no | Allowed to create subgroups. Can be `owner` (Owners), or `maintainer` (Maintainers). |
2019-12-21 20:55:43 +05:30
| `emails_disabled` | boolean | no | Disable email notifications |
2020-03-09 13:42:32 +05:30
| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned |
2019-09-30 21:07:59 +05:30
| `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. |
| `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. |
2016-09-13 17:45:13 +05:30
2020-03-09 13:42:32 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/5?name=Experimental"
2016-09-13 17:45:13 +05:30
```
2020-01-01 13:55:28 +05:30
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.
2016-09-13 17:45:13 +05:30
Example response:
```json
{
"id": 5,
"name": "Experimental",
"path": "h5bp",
"description": "foo",
2017-08-17 22:00:37 +05:30
"visibility": "internal",
2016-09-13 17:45:13 +05:30
"avatar_url": null,
"web_url": "http://gitlab.example.com/groups/h5bp",
2016-09-29 09:46:39 +05:30
"request_access_enabled": false,
2017-08-17 22:00:37 +05:30
"full_name": "Foobar Group",
"full_path": "foo-bar",
2018-12-13 13:39:08 +05:30
"file_template_project_id": 1,
2017-08-17 22:00:37 +05:30
"parent_id": null,
2016-09-13 17:45:13 +05:30
"projects": [
{
"id": 9,
"description": "foo",
"default_branch": "master",
"tag_list": [],
"public": false,
"archived": false,
2017-08-17 22:00:37 +05:30
"visibility": "internal",
2016-09-13 17:45:13 +05:30
"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,
2017-08-17 22:00:37 +05:30
"jobs_enabled": true,
2016-09-13 17:45:13 +05:30
"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",
2017-08-17 22:00:37 +05:30
"kind": "group"
2016-09-13 17:45:13 +05:30
},
"avatar_url": null,
"star_count": 1,
"forks_count": 0,
"open_issues_count": 3,
2017-08-17 22:00:37 +05:30
"public_jobs": true,
2016-09-29 09:46:39 +05:30
"shared_with_groups": [],
"request_access_enabled": false
2016-09-13 17:45:13 +05:30
}
]
}
```
2020-01-01 13:55:28 +05:30
### 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)
```
2016-09-13 17:45:13 +05:30
## Remove group
2020-03-09 13:42:32 +05:30
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.
- 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 ).
2016-09-13 17:45:13 +05:30
```
DELETE /groups/:id
```
Parameters:
2020-03-09 13:42:32 +05:30
| 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.
2016-09-13 17:45:13 +05:30
2020-03-09 13:42:32 +05:30
```plaintext
POST /groups/:id/restore
```
Parameters:
| Attribute | Type | Required | Description |
| --------------- | -------------- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group ](README.md#namespaced-path-encoding ) |
2018-11-08 19:23:39 +05:30
2016-09-13 17:45:13 +05:30
## 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"
}
]
```
2020-03-09 13:42:32 +05:30
## 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. |
2019-12-26 22:10:19 +05:30
## Group Audit Events **(STARTER)**
Group audit events can be accessed via the [Group Audit Events API ](audit_events.md#group-audit-events-starter )
2020-03-09 13:42:32 +05:30
## Sync group with LDAP **(STARTER)**
2019-09-30 21:07:59 +05:30
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
2016-09-13 17:45:13 +05:30
## Group members
Please consult the [Group Members ](members.md ) documentation.
2020-03-09 13:42:32 +05:30
## LDAP Group Links
List, add, and delete LDAP group links.
### List LDAP group links **(STARTER)**
Lists LDAP group links.
```
GET /groups/:id/ldap_group_links
```
Parameters:
- `id` (required) - The ID of a group
### Add LDAP group link **(STARTER)**
2019-09-30 21:07:59 +05:30
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
2020-03-09 13:42:32 +05:30
### Delete LDAP group link **(STARTER)**
2019-09-30 21:07:59 +05:30
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
2016-09-13 17:45:13 +05:30
## 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:
2019-09-30 21:07:59 +05:30
2016-09-13 17:45:13 +05:30
```
/groups?per_page=100
```
And to switch pages add:
2019-09-30 21:07:59 +05:30
2016-09-13 17:45:13 +05:30
```
/groups?per_page=100& page=2
```
2018-03-17 18:26:18 +05:30
2020-03-09 13:42:32 +05:30
[ce-15142]: https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15142
2018-03-27 19:54:05 +05:30
## Group badges
Read more in the [Group Badges ](group_badges.md ) documentation.
2020-03-09 13:42:32 +05:30
## Group Import/Export
Read more in the [Group Import/Export ](group_import_export.md ) documentation.
