Groups API

Interact with groups by using the REST API.

The fields returned in responses vary based on the permissions of the authenticated user.

List groups

Support for keyset pagination introduced in GitLab 14.3.

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

By default, this request returns 20 results at a time because the API results are paginated.

When accessed without authentication, this endpoint also supports keyset pagination:

Parameters:

AttributeTypeRequiredDescription
skip_groupsarray of integersnoSkip the group IDs passed
all_availablebooleannoShow all the groups you have access to (defaults to false for authenticated users, true for administrators); Attributes owned and min_access_level have precedence
searchstringnoReturn the list of authorized groups matching the search criteria
order_bystringnoOrder groups by name, path, id, or similarity (if searching, introduced in GitLab 14.1). Default is name
sortstringnoOrder groups in asc or desc order. Default is asc
statisticsbooleannoInclude group statistics (administrators only).
Note: The REST API response does not provide the full RootStorageStatistics data that is shown in the UI. To match the data in the UI, use GraphQL instead of REST. For more information, see the Group GraphQL API resources.
with_custom_attributesbooleannoInclude custom attributes in response (administrators only)
ownedbooleannoLimit to groups explicitly owned by the current user
min_access_levelintegernoLimit to groups where current user has at least this role (access_level)
top_level_onlybooleannoLimit to top level groups, excluding all subgroups
repository_storage stringnoFilter by repository storage used by the group (administrators only). Introduced in GitLab 16.3
GET /groups

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "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,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z",
    "ip_restriction_ranges": null
  }
]

When adding the parameter statistics=true and the authenticated user is an administrator, additional group statistics are returned.

GET /groups?statistics=true

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "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,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z",
    "statistics": {
      "storage_size": 363,
      "repository_size": 33,
      "wiki_size": 100,
      "lfs_objects_size": 123,
      "job_artifacts_size": 57,
      "pipeline_artifacts_size": 0,
      "packages_size": 0,
      "snippets_size": 50,
      "uploads_size": 0
    },
    "wiki_access_level": "private"
  }
]

Users of GitLab Premium or Ultimate also see the wiki_access_level attribute.

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

You can filter by custom attributes with:

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

List a group’s subgroups

Get a list of visible direct subgroups in this group.

By default, this request returns 20 results at a time because the API results are paginated.

If you request this list as:

  • An unauthenticated user, the response returns only public groups.
  • An authenticated user, the response returns only the groups you’re a member of and does not include public groups.

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group of the immediate parent group
skip_groupsarray of integersnoSkip the group IDs passed
all_availablebooleannoShow all the groups you have access to (defaults to false for authenticated users, true for administrators); Attributes owned and min_access_level have precedence
searchstringnoReturn the list of authorized groups matching the search criteria. Only subgroup short paths are searched (not full paths)
order_bystringnoOrder groups by name, path or id. Default is name
sortstringnoOrder groups in asc or desc order. Default is asc
statisticsbooleannoInclude group statistics (administrators only)
with_custom_attributesbooleannoInclude custom attributes in response (administrators only)
ownedbooleannoLimit to groups explicitly owned by the current user
min_access_levelintegernoLimit to groups where current user has at least this role (access_level) 
GET /groups/:id/subgroups

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "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,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "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,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]

Users of GitLab Premium or Ultimate also see the wiki_access_level attribute.

List a group’s descendant groups

Introduced in GitLab 13.5

Get a list of visible descendant groups of this group. When accessed without authentication, only public groups are returned.

By default, this request returns 20 results at a time because the API results are paginated.

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group of the immediate parent group
skip_groupsarray of integersnoSkip the group IDs passed
all_availablebooleannoShow all the groups you have access to (defaults to false for authenticated users, true for administrators). Attributes owned and min_access_level have precedence
searchstringnoReturn the list of authorized groups matching the search criteria. Only descendant group short paths are searched (not full paths)
order_bystringnoOrder groups by name, path, or id. Default is name
sortstringnoOrder groups in asc or desc order. Default is asc
statisticsbooleannoInclude group statistics (administrators only)
with_custom_attributesbooleannoInclude custom attributes in response (administrators only)
ownedbooleannoLimit to groups explicitly owned by the current user
min_access_levelintegernoLimit to groups where current user has at least this role (access_level) 
GET /groups/:id/descendant_groups

[
  {
    "id": 2,
    "name": "Bar Group",
    "path": "bar",
    "description": "A subgroup of Foo Group",
    "visibility": "public",
    "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,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg",
    "web_url": "http://gitlab.example.com/groups/foo/bar",
    "request_access_enabled": false,
    "full_name": "Bar Group",
    "full_path": "foo/bar",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  },
  {
    "id": 3,
    "name": "Baz Group",
    "path": "baz",
    "description": "A subgroup of Bar Group",
    "visibility": "public",
    "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,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/baz.jpg",
    "web_url": "http://gitlab.example.com/groups/foo/bar/baz",
    "request_access_enabled": false,
    "full_name": "Baz Group",
    "full_path": "foo/bar/baz",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]

Users of GitLab Premium or Ultimate also see the wiki_access_level attribute.

List a group’s projects

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.

GET /groups/:id/projects

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group owned by the authenticated user
archivedbooleannoLimit by archived status
visibilitystringnoLimit by visibility public, internal, or private
order_bystringnoReturn projects ordered by id, name, path, created_at, updated_at, similarity (1), or last_activity_at fields. Default is created_at
sortstringnoReturn projects sorted in asc or desc order. Default is desc
searchstringnoReturn list of authorized projects matching the search criteria
simplebooleannoReturn only limited fields for each project. This is a no-op without authentication where only simple fields are returned.
ownedbooleannoLimit by projects owned by the current user
starredbooleannoLimit by projects starred by the current user
topicstringnoReturn projects matching the topic
with_issues_enabledbooleannoLimit by projects with issues feature enabled. Default is false
with_merge_requests_enabledbooleannoLimit by projects with merge requests feature enabled. Default is false
with_sharedbooleannoInclude projects shared to this group. Default is true
include_subgroupsbooleannoInclude projects in subgroups of this group. Default is false
min_access_levelintegernoLimit to projects where current user has at least this role (access_level)
with_custom_attributesbooleannoInclude custom attributes in response (administrators only)
with_security_reports booleannoReturn only projects that have security reports artifacts present in any of their builds. This means “projects with security reports enabled”. Default is false
  1. Order by similarity: Orders the results by a similarity score calculated from the provided search URL parameter. When using order_by=similarity, the sort parameter is ignored. When the search parameter is not provided, the API returns the projects ordered by name.

Example response:

[
  {
    "id": 9,
    "description": "foo",
    "default_branch": "main",
    "tag_list": [], //deprecated, use `topics` instead
    "topics": [],
    "archived": false,
    "visibility": "internal",
    "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,
    "jobs_enabled": true,
    "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",
      "kind": "group"
    },
    "avatar_url": null,
    "star_count": 1,
    "forks_count": 0,
    "open_issues_count": 3,
    "public_jobs": true,
    "shared_with_groups": [],
    "request_access_enabled": false
  }
]
note
To 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.

List a group’s shared projects

Get a list of projects shared to this group. When accessed without authentication, only public shared projects are returned.

By default, this request returns 20 results at a time because the API results are paginated.

GET /groups/:id/projects/shared

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group owned by the authenticated user
archivedbooleannoLimit by archived status
visibilitystringnoLimit by visibility public, internal, or private
order_bystringnoReturn projects ordered by id, name, path, created_at, updated_at, or last_activity_at fields. Default is created_at
sortstringnoReturn projects sorted in asc or desc order. Default is desc
searchstringnoReturn list of authorized projects matching the search criteria
simplebooleannoReturn only limited fields for each project. This is a no-op without authentication where only simple fields are returned.
starredbooleannoLimit by projects starred by the current user
with_issues_enabledbooleannoLimit by projects with issues feature enabled. Default is false
with_merge_requests_enabledbooleannoLimit by projects with merge requests feature enabled. Default is false
min_access_levelintegernoLimit to projects where current user has at least this role (access_level)
with_custom_attributesbooleannoInclude custom attributes in response (administrators only)

Example response:

[
   {
      "id":8,
      "description":"Shared project for Html5 Boilerplate",
      "name":"Html5 Boilerplate",
      "name_with_namespace":"H5bp / Html5 Boilerplate",
      "path":"html5-boilerplate",
      "path_with_namespace":"h5bp/html5-boilerplate",
      "created_at":"2020-04-27T06:13:22.642Z",
      "default_branch":"main",
      "tag_list":[], //deprecated, use `topics` instead
      "topics":[],
      "ssh_url_to_repo":"ssh://git@gitlab.com/h5bp/html5-boilerplate.git",
      "http_url_to_repo":"https://gitlab.com/h5bp/html5-boilerplate.git",
      "web_url":"https://gitlab.com/h5bp/html5-boilerplate",
      "readme_url":"https://gitlab.com/h5bp/html5-boilerplate/-/blob/main/README.md",
      "avatar_url":null,
      "star_count":0,
      "forks_count":4,
      "last_activity_at":"2020-04-27T06:13:22.642Z",
      "namespace":{
         "id":28,
         "name":"H5bp",
         "path":"h5bp",
         "kind":"group",
         "full_path":"h5bp",
         "parent_id":null,
         "avatar_url":null,
         "web_url":"https://gitlab.com/groups/h5bp"
      },
      "_links":{
         "self":"https://gitlab.com/api/v4/projects/8",
         "issues":"https://gitlab.com/api/v4/projects/8/issues",
         "merge_requests":"https://gitlab.com/api/v4/projects/8/merge_requests",
         "repo_branches":"https://gitlab.com/api/v4/projects/8/repository/branches",
         "labels":"https://gitlab.com/api/v4/projects/8/labels",
         "events":"https://gitlab.com/api/v4/projects/8/events",
         "members":"https://gitlab.com/api/v4/projects/8/members"
      },
      "empty_repo":false,
      "archived":false,
      "visibility":"public",
      "resolve_outdated_diff_discussions":false,
      "container_registry_enabled":true,
      "container_expiration_policy":{
         "cadence":"7d",
         "enabled":true,
         "keep_n":null,
         "older_than":null,
         "name_regex":null,
         "name_regex_keep":null,
         "next_run_at":"2020-05-04T06:13:22.654Z"
      },
      "issues_enabled":true,
      "merge_requests_enabled":true,
      "wiki_enabled":true,
      "jobs_enabled":true,
      "snippets_enabled":true,
      "can_create_merge_request_in":true,
      "issues_access_level":"enabled",
      "repository_access_level":"enabled",
      "merge_requests_access_level":"enabled",
      "forking_access_level":"enabled",
      "wiki_access_level":"enabled",
      "builds_access_level":"enabled",
      "snippets_access_level":"enabled",
      "pages_access_level":"enabled",
      "security_and_compliance_access_level":"enabled",
      "emails_disabled":null,
      "shared_runners_enabled":true,
      "lfs_enabled":true,
      "creator_id":1,
      "import_status":"failed",
      "open_issues_count":10,
      "ci_default_git_depth":50,
      "ci_forward_deployment_enabled":true,
      "ci_forward_deployment_rollback_allowed": true,
      "ci_allow_fork_pipelines_to_run_in_parent_project":true,
      "public_jobs":true,
      "build_timeout":3600,
      "auto_cancel_pending_pipelines":"enabled",
      "ci_config_path":null,
      "shared_with_groups":[
         {
            "group_id":24,
            "group_name":"Commit451",
            "group_full_path":"Commit451",
            "group_access_level":30,
            "expires_at":null
         }
      ],
      "only_allow_merge_if_pipeline_succeeds":false,
      "request_access_enabled":true,
      "only_allow_merge_if_all_discussions_are_resolved":false,
      "remove_source_branch_after_merge":true,
      "printing_merge_request_link_enabled":true,
      "merge_method":"merge",
      "suggestion_commit_message":null,
      "auto_devops_enabled":true,
      "auto_devops_deploy_strategy":"continuous",
      "autoclose_referenced_issues":true,
      "repository_storage":"default"
   }
]

Details of a group

The membership_lock field was introduced in GitLab 14.10.

Get all details of a group. This endpoint can be accessed without authentication if the group is publicly accessible. In case the user that requests is an administrator if the group is publicly accessible. With authentication, it returns the runners_token for the group too, if the user is an administrator or group owner.

GET /groups/:id

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group owned by the authenticated user.
with_custom_attributesbooleannoInclude custom attributes in response (administrators only).
with_projectsbooleannoInclude details from projects that belong to the specified group (defaults to true). (Deprecated, scheduled for removal in API v5. To get the details of all projects within a group, use the list a group’s projects endpoint.)
note
The projects and shared_projects attributes in the response are deprecated and scheduled for removal in API v5. To get the details of all projects within a group, use either the list a group’s projects or the list a group’s shared projects endpoint.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4"

This endpoint returns:

Example response:

{
  "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,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "runners_token": "ba324ca7b1c77fc20bb9",
  "file_template_project_id": 1,
  "parent_id": null,
  "created_at": "2020-01-15T12:36:29.590Z",
  "shared_with_groups": [
    {
      "group_id": 28,
      "group_name": "H5bp",
      "group_full_path": "h5bp",
      "group_access_level": 20,
      "expires_at": null
    }
  ],
  "prevent_sharing_groups_outside_hierarchy": false,
  "projects": [ // Deprecated and will be removed in API v5
    {
      "id": 7,
      "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "public",
      "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,
      "jobs_enabled": true,
      "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",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    },
    {
      "id": 6,
      "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "internal",
      "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,
      "jobs_enabled": true,
      "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",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 8,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "shared_projects": [ // Deprecated and will be removed in API v5
    {
      "id": 8,
      "description": "Velit eveniet provident fugiat saepe eligendi autem.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "private",
      "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,
      "jobs_enabled": true,
      "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",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 4,
      "public_jobs": true,
      "shared_with_groups": [
        {
          "group_id": 4,
          "group_name": "Twitter",
          "group_full_path": "twitter",
          "group_access_level": 30,
          "expires_at": null
        },
        {
          "group_id": 3,
          "group_name": "Gitlab Org",
          "group_full_path": "gitlab-org",
          "group_access_level": 10,
          "expires_at": "2018-08-14"
        }
      ]
    }
  ],
  "ip_restriction_ranges": null
}

The prevent_sharing_groups_outside_hierarchy attribute is present only on top-level groups.

Users of GitLab Premium or Ultimate also see the attributes:

  • shared_runners_minutes_limit
  • extra_shared_runners_minutes_limit
  • marked_for_deletion_on
  • membership_lock
  • wiki_access_level

Additional response attributes:

{
  "id": 4,
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  "marked_for_deletion_on": "2020-04-03",
  "membership_lock": false,
  "wiki_access_level": "disabled",
  ...
}

When adding the parameter with_projects=false, projects aren’t returned.

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4?with_projects=false"

Example response:

{
  "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,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "file_template_project_id": 1,
  "parent_id": null
}

Download a Group avatar

Get a group avatar. This endpoint can be accessed without authentication if the group is publicly accessible.

GET /groups/:id/avatar
AttributeTypeRequiredDescription
idinteger/stringyesID of the group

Example:

curl --header "PRIVATE-TOKEN: $GITLAB_LOCAL_TOKEN" \
  --remote-header-name \
  --remote-name \
  "https://gitlab.example.com/api/v4/groups/4/avatar"

Disable the results limit

The 100 results limit can break integrations developed using GitLab 12.4 and earlier.

For GitLab 12.5 to GitLab 13.12, the limit can be disabled while migrating to using the list a group’s projects endpoint.

Ask a GitLab administrator with Rails console access to run the following command:

Feature.disable(:limit_projects_in_groups_api)

For GitLab 14.0 and later, the limit cannot be disabled.

New group

note
On GitLab SaaS, you must use the GitLab UI to create groups without a parent group. You cannot use the API to do this.

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

POST /groups

Parameters:

AttributeTypeRequiredDescription
namestringyesThe name of the group.
pathstringyesThe path of the group.
auto_devops_enabledbooleannoDefault to Auto DevOps pipeline for all projects within this group.
avatarmixednoImage file for avatar of the group. Introduced in GitLab 12.9
default_branch_protectionintegernoSee Options for default_branch_protection. Default to the global level default branch protection setting.
descriptionstringnoThe group’s description.
emails_disabledbooleannoDisable email notifications.
lfs_enabledbooleannoEnable/disable Large File Storage (LFS) for the projects in this group.
mentions_disabledbooleannoDisable the capability of a group from getting mentioned.
parent_idintegernoThe parent group ID for creating nested group.
project_creation_levelstringnoDetermine 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).
request_access_enabledbooleannoAllow users to request member access.
require_two_factor_authenticationbooleannoRequire all users in this group to setup Two-factor authentication.
share_with_group_lockbooleannoPrevent sharing a project with another group within this group.
subgroup_creation_levelstringnoAllowed to create subgroups. Can be owner (Owners), or maintainer (users with the Maintainer role).
two_factor_grace_periodintegernoTime before Two-factor authentication is enforced (in hours).
visibilitystringnoThe group’s visibility. Can be private, internal, or public.
membership_lock booleannoUsers cannot be added to projects in this group.
extra_shared_runners_minutes_limit integernoCan be set by administrators only. Additional compute minutes for this group.
shared_runners_minutes_limit integernoCan be set by administrators only. Maximum number of monthly compute minutes for this group. Can be nil (default; inherit system default), 0 (unlimited), or > 0.
wiki_access_level stringnoThe wiki access level. Can be disabled, private, or enabled.

Options for default_branch_protection

The default_branch_protection attribute determines whether users with the Developer or Maintainer role can push to the applicable default branch, as described in the following table:

ValueDescription
0No protection. Users with the Developer or Maintainer role can:
- Push new commits
- Force push changes
- Delete the branch
1Partial protection. Users with the Developer or Maintainer role can:
- Push new commits
2Full protection. Only users with the Maintainer role can:
- Push new commits
3Protected against pushes. Users with the Maintainer role can:
- Push new commits
- Force push changes
- Accept merge requests
Users with the Developer role can:
- Accept merge requests
4Full protection after initial push. User with the Developer role can:
- Push commit to empty repository.
Users with the Maintainer role can:
- Push new commits
- Accept merge requests

New Subgroup

This is similar to creating a New group. You need the parent_id from the List groups call. You can then enter the desired:

  • subgroup_path
  • subgroup_name
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-Type: application/json" \
     --data '{"path": "<subgroup_path>", "name": "<subgroup_name>", "parent_id": <parent_group_id> }' \
     "https://gitlab.example.com/api/v4/groups/"

Transfer project to group

Transfer a project to the Group namespace. Available only to instance administrators, although an alternative API endpoint is available which does not require administrator access on the instance. Transferring projects may fail when tagged packages exist in the project’s repository.

POST  /groups/:id/projects/:project_id

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the target group
project_idinteger/stringyesThe ID or URL-encoded path of the project 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/4/projects/56"

Get groups to which a user can transfer a group

Introduced in GitLab 15.4

Retrieve a list of groups to which the user can transfer a group.

GET /groups/:id/transfer_locations
AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group to be transferred.
searchstringNoThe group names to search for.

Example request:

curl --request GET "https://gitlab.example.com/api/v4/groups/1/transfer_locations"

Example response:

[
  {
    "id": 27,
    "web_url": "https://gitlab.example.com/groups/gitlab",
    "name": "GitLab",
    "avatar_url": null,
    "full_name": "GitLab",
    "full_path": "GitLab"
  },
  {
    "id": 31,
    "web_url": "https://gitlab.example.com/groups/foobar",
    "name": "FooBar",
    "avatar_url": null,
    "full_name": "FooBar",
    "full_path": "FooBar"
  }
]

Transfer a group to a new parent group / Turn a subgroup to a top-level group

Introduced in GitLab 14.6.

Transfer a group to a new parent group or turn a subgroup to a top-level group. Available to administrators and users:

POST  /groups/:id/transfer

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of the group to transfer.
group_idintegernoID of the new parent group. When not specified, the group to transfer is instead turned into a top-level group.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/4/transfer?group_id=7"

Update group

unique_project_download_limit, unique_project_download_limit_interval_in_seconds, and unique_project_download_limit_allowlist introduced in GitLab 15.3 with a flag named limit_unique_project_downloads_per_namespace_user. Disabled by default.

On self-managed GitLab, by default unique_project_download_limit, unique_project_download_limit_interval_in_seconds, unique_project_download_limit_allowlist and auto_ban_user_on_excessive_projects_download are not available. To make them available, an administrator can enable the feature flag named limit_unique_project_downloads_per_namespace_user.

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

PUT /groups/:id
AttributeTypeRequiredDescription
idintegeryesThe ID of the group.
namestringnoThe name of the group.
pathstringnoThe path of the group.
auto_devops_enabledbooleannoDefault to Auto DevOps pipeline for all projects within this group.
avatarmixednoImage file for avatar of the group. Introduced in GitLab 12.9
default_branch_protectionintegernoSee Options for default_branch_protection.
descriptionstringnoThe description of the group.
emails_disabledbooleannoDisable email notifications.
lfs_enabledbooleannoEnable/disable Large File Storage (LFS) for the projects in this group.
mentions_disabledbooleannoDisable the capability of a group from getting mentioned.
prevent_sharing_groups_outside_hierarchybooleannoSee Prevent group sharing outside the group hierarchy. This attribute is only available on top-level groups. Introduced in GitLab 14.1
project_creation_levelstringnoDetermine 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).
request_access_enabledbooleannoAllow users to request member access.
require_two_factor_authenticationbooleannoRequire all users in this group to setup Two-factor authentication.
shared_runners_settingstringnoSee Options for shared_runners_setting. Enable or disable shared runners for a group’s subgroups and projects.
share_with_group_lockbooleannoPrevent sharing a project with another group within this group.
subgroup_creation_levelstringnoAllowed to create subgroups. Can be owner (Owners), or maintainer (users with the Maintainer role).
two_factor_grace_periodintegernoTime before Two-factor authentication is enforced (in hours).
visibilitystringnoThe visibility level of the group. Can be private, internal, or public.
extra_shared_runners_minutes_limit integernoCan be set by administrators only. Additional compute minutes for this group.
file_template_project_id integernoThe ID of a project to load custom file templates from.
membership_lock booleannoUsers cannot be added to projects in this group.
prevent_forking_outside_group booleannoWhen enabled, users can not fork projects from this group to external namespaces.
shared_runners_minutes_limit integernoCan be set by administrators only. Maximum number of monthly compute minutes for this group. Can be nil (default; inherit system default), 0 (unlimited), or > 0.
unique_project_download_limit integernoMaximum number of unique projects a user can download in the specified time period before they are banned. Available only on top-level groups. Default: 0, Maximum: 10,000.
unique_project_download_limit_interval_in_seconds integernoTime period during which a user can download a maximum amount of projects before they are banned. Available only on top-level groups. Default: 0, Maximum: 864,000 seconds (10 days).
unique_project_download_limit_allowlist array of stringsnoList of usernames excluded from the unique project download limit. Available only on top-level groups. Default: [], Maximum: 100 usernames.
unique_project_download_limit_alertlist array of integersnoList of user IDs that are emailed when the unique project download limit is exceeded. Available only on top-level groups. Default: [], Maximum: 100 user IDs. Introduced in GitLab 15.9.
auto_ban_user_on_excessive_projects_download booleannoWhen enabled, users are automatically banned from the group when they download more than the maximum number of unique projects specified by unique_project_download_limit and unique_project_download_limit_interval_in_seconds. Introduced in GitLab 15.4.
ip_restriction_ranges stringnoComma-separated list of IP addresses or subnet masks to restrict group access. Introduced in GitLab 15.4.
wiki_access_level stringnoThe wiki access level. Can be disabled, private, or enabled.
note
The projects and shared_projects attributes in the response are deprecated and scheduled for removal in API v5. To get the details of all projects within a group, use either the list a group’s projects or the list a group’s shared projects endpoint.
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/5?name=Experimental"

This endpoint returns:

Example response:

{
  "id": 5,
  "name": "Experimental",
  "path": "h5bp",
  "description": "foo",
  "visibility": "internal",
  "avatar_url": null,
  "web_url": "http://gitlab.example.com/groups/h5bp",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Foobar Group",
  "full_path": "h5bp",
  "file_template_project_id": 1,
  "parent_id": null,
  "created_at": "2020-01-15T12:36:29.590Z",
  "prevent_sharing_groups_outside_hierarchy": false,
  "projects": [ // Deprecated and will be removed in API v5
    {
      "id": 9,
      "description": "foo",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "public": false,
      "archived": false,
      "visibility": "internal",
      "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,
      "jobs_enabled": true,
      "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",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 1,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "ip_restriction_ranges": null
}

The prevent_sharing_groups_outside_hierarchy attribute is present in the response only for top-level groups.

Users of GitLab Premium or Ultimate also see the wiki_access_level attribute.

Disable the results limit

The 100 results limit can break integrations developed using GitLab 12.4 and earlier.

For GitLab 12.5 to GitLab 13.12, the limit can be disabled while migrating to using the list a group’s projects endpoint.

Ask a GitLab administrator with Rails console access to run the following command:

Feature.disable(:limit_projects_in_groups_api)

For GitLab 14.0 and later, the limit cannot be disabled.

Options for shared_runners_setting

The shared_runners_setting attribute determines whether shared runners are enabled for a group’s subgroups and projects.

ValueDescription
enabledEnables shared runners for all projects and subgroups in this group.
disabled_and_overridableDisables shared runners for all projects and subgroups in this group, but allows subgroups to override this setting.
disabled_and_unoverridableDisables shared runners for all projects and subgroups in this group, and prevents subgroups from overriding this setting.
disabled_with_override(Deprecated. Use disabled_and_overridable) Disables shared runners for all projects and subgroups in this group, but allows subgroups to override this setting.

Upload a group avatar

Introduced in GitLab 12.9.

To upload an avatar file from your file system, use the --form argument. This causes curl to post data using the header Content-Type: multipart/form-data. The file= parameter must point to a file on your file system and be preceded by @. For example:

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22" \
     --form "avatar=@/tmp/example.png"

Remove a group avatar

Introduced in GitLab 15.4.

To remove a group avatar, use a blank value for the avatar attribute.

Example request:

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/22" \
     --data "avatar="

Remove group

Version history
  • Immediately deleting subgroups was introduced in GitLab 15.3 with a flag named immediate_delete_subgroup_api. Disabled by default.
  • Immediately deleting subgroups was enabled on GitLab.com and self-managed in GitLab 15.4.
  • Immediately deleting subgroups was enabled by default in GitLab 15.4.
  • The flag immediate_delete_subgroup_api for immediately deleting subgroups was removed in GitLab 15.9.

Only available to group owners and administrators.

This endpoint:

  • On Premium and Ultimate tiers, marks the group for deletion. The deletion happens 7 days later by default, but you can change the retention period in the instance settings.
  • On Free tier, removes the group immediately and queues a background job to delete all projects in the group.
  • Deletes a subgroup immediately if the subgroup is marked for deletion (GitLab 15.4 and later). The endpoint does not immediately delete top-level groups.
DELETE /groups/:id

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
permanently_remove boolean/stringnoImmediately deletes a subgroup if it is marked for deletion. Introduced in GitLab 15.4
full_path stringnoFull path of subgroup to use with permanently_remove. Introduced in GitLab 15.4. To find the subgroup path, see the group details

The response is 202 Accepted if the user has authorization.

note
A GitLab.com group can’t be removed if it is linked to a subscription. To remove such a group, first link the subscription with a different group.

Restore group marked for deletion

Introduced in GitLab 12.8.

Restores a group marked for deletion.

POST /groups/:id/restore

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group

Search for group

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

GET /groups?search=foobar

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

List provisioned users

Introduced in GitLab 14.8.

Get a list of users provisioned by a given group. Does not include subgroups. Users in this list are considered enterprise users.

Requires at least the Maintainer role on the group.

GET /groups/:id/provisioned_users

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesID or URL-encoded path of the group
usernamestringnoReturn single user with a specific username
searchstringnoSearch users by name, email, username
activebooleannoReturn only active users
blockedbooleannoReturn only blocked users
created_afterdatetimenoReturn users created after the specified time
created_beforedatetimenoReturn users created before the specified time

Example response:

[
  {
    "id": 66,
    "username": "user22",
    "name": "John Doe22",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
    "web_url": "http://my.gitlab.com/user22",
    "created_at": "2021-09-10T12:48:22.381Z",
    "bio": "",
    "location": null,
    "public_email": "",
    "skype": "",
    "linkedin": "",
    "twitter": "",
    "website_url": "",
    "organization": null,
    "job_title": "",
    "pronouns": null,
    "bot": false,
    "work_information": null,
    "followers": 0,
    "following": 0,
    "local_time": null,
    "last_sign_in_at": null,
    "confirmed_at": "2021-09-10T12:48:22.330Z",
    "last_activity_on": null,
    "email": "user22@example.org",
    "theme_id": 1,
    "color_scheme_id": 1,
    "projects_limit": 100000,
    "current_sign_in_at": null,
    "identities": [ ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": false,
    "external": false,
    "private_profile": false,
    "commit_email": "user22@example.org",
    "shared_runners_minutes_limit": null,
    "extra_shared_runners_minutes_limit": null
  },
  ...
]

Service Accounts

Create Service Account User

Introduced in GitLab 16.1.

Creates a service account user with an auto-generated email address and username.

POST /groups/:id/service_accounts

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/service_accounts"

Example response:

{
  "id": 57,
  "username": "service_account_group_345_6018816a18e515214e0c34c2b33523fc",
  "name": "Service account user"
}

Create Personal Access Token for Service Account User

Introduced in GitLab 16.1.

POST /groups/:id/service_accounts/:user_id/personal_access_tokens

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens" --data "scopes[]=api" --data "name=service_accounts_token"

Example response:

{
  "id":6,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:47:13.900Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2024-06-12",
  "token":"<token_value>"
}

Rotate a Personal Access Token for Service Account User

Introduced in GitLab 16.1.

POST /groups/:id/service_accounts/:user_id/personal_access_tokens/:token_id/rotate

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/35/service_accounts/71/personal_access_tokens/6/rotate"

Example response:

{
  "id":7,
  "name":"service_accounts_token",
  "revoked":false,
  "created_at":"2023-06-13T07:54:49.962Z",
  "scopes":["api"],
  "user_id":71,
  "last_used_at":null,
  "active":true,
  "expires_at":"2023-06-20",
  "token":"<token_value>"
}

Hooks

Also called Group Hooks and Webhooks. These are different from System Hooks that are system wide and Project Hooks that are limited to one project.

List group hooks

Get a list of group hooks

GET /groups/:id/hooks
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group

Get group hook

Get a specific hook for a group.

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
hook_idintegeryesThe ID of a group hook
GET /groups/:id/hooks/:hook_id

{
  "id": 1,
  "url": "http://example.com/hook",
  "group_id": 3,
  "push_events": true,
  "push_events_branch_filter": "",
  "issues_events": true,
  "confidential_issues_events": true,
  "merge_requests_events": true,
  "tag_push_events": true,
  "note_events": true,
  "confidential_note_events": true,
  "job_events": true,
  "pipeline_events": true,
  "wiki_page_events": true,
  "deployment_events": true,
  "releases_events": true,
  "subgroup_events": true,
  "enable_ssl_verification": true,
  "repository_update_events": false,
  "alert_status": "executable",
  "disabled_until": null,
  "url_variables": [ ],
  "created_at": "2012-10-12T17:04:47Z"
}

Add group hook

Adds a hook to a specified group.

POST /groups/:id/hooks
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
urlstringyesThe hook URL
push_eventsbooleannoTrigger hook on push events
push_events_branch_filterstringNoTrigger hook on push events for matching branches only.
issues_eventsbooleannoTrigger hook on issues events
confidential_issues_eventsbooleannoTrigger hook on confidential issues events
merge_requests_eventsbooleannoTrigger hook on merge requests events
tag_push_eventsbooleannoTrigger hook on tag push events
note_eventsbooleannoTrigger hook on note events
confidential_note_eventsbooleannoTrigger hook on confidential note events
job_eventsbooleannoTrigger hook on job events
pipeline_eventsbooleannoTrigger hook on pipeline events
wiki_page_eventsbooleannoTrigger hook on wiki page events
deployment_eventsbooleannoTrigger hook on deployment events
releases_eventsbooleannoTrigger hook on release events
subgroup_eventsbooleannoTrigger hook on subgroup events
enable_ssl_verificationbooleannoDo SSL verification when triggering the hook
tokenstringnoSecret token to validate received payloads; not returned in the response

Edit group hook

Edits a hook for a specified group.

PUT /groups/:id/hooks/:hook_id
AttributeTypeRequiredDescription
idinteger or stringyesThe ID or URL-encoded path of the group.
hook_idintegeryesThe ID of the group hook.
urlstringyesThe hook URL.
push_eventsbooleannoTrigger hook on push events.
push_events_branch_filterstringNoTrigger hook on push events for matching branches only.
issues_eventsbooleannoTrigger hook on issues events.
confidential_issues_eventsbooleannoTrigger hook on confidential issues events.
merge_requests_eventsbooleannoTrigger hook on merge requests events.
tag_push_eventsbooleannoTrigger hook on tag push events.
note_eventsbooleannoTrigger hook on note events.
confidential_note_eventsbooleannoTrigger hook on confidential note events.
job_eventsbooleannoTrigger hook on job events.
pipeline_eventsbooleannoTrigger hook on pipeline events.
wiki_page_eventsbooleannoTrigger hook on wiki page events.
deployment_eventsbooleannoTrigger hook on deployment events.
releases_eventsbooleannoTrigger hook on release events.
subgroup_eventsbooleannoTrigger hook on subgroup events.
enable_ssl_verificationbooleannoDo SSL verification when triggering the hook.
tokenstringnoSecret token to validate received payloads. Not returned in the response. When you change the webhook URL, the secret token is reset and not retained.

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
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
hook_idintegeryesThe ID of the group hook.

Group Audit Events

Group audit events can be accessed via the Group Audit Events API

Sync group with LDAP

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

Group members

See the Group Members documentation.

List, add, and delete LDAP group links.

Lists LDAP group links.

GET /groups/:id/ldap_group_links
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group

Adds an LDAP group link using a CN or filter. Adding a group link by filter is only supported in the Premium tier and above.

POST /groups/:id/ldap_group_links
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
cnstringnoThe CN of an LDAP group
filterstringnoThe LDAP filter for the group
group_accessintegeryes Role (access_level) for members of the LDAP group
providerstringyesLDAP provider for the LDAP group link
note
To define the LDAP group link, provide either a cn or a filter, but not both.

Deletes an LDAP group link. Deprecated. Scheduled for removal in a future release.

DELETE /groups/:id/ldap_group_links/:cn
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
cnstringyesThe CN of an LDAP group

Deletes an LDAP group link for a specific LDAP provider. Deprecated. Scheduled for removal in a future release.

DELETE /groups/:id/ldap_group_links/:provider/:cn
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
cnstringyesThe CN of an LDAP group
providerstringyesLDAP provider for the LDAP group link

Deletes an LDAP group link using a CN or filter. Deleting by filter is only supported in the Premium tier and above.

DELETE /groups/:id/ldap_group_links
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
cnstringnoThe CN of an LDAP group
filterstringnoThe LDAP filter for the group
providerstringyesLDAP provider for the LDAP group link
note
To delete the LDAP group link, provide either a cn or a filter, but not both.
Version history
  • Introduced in GitLab 15.3.0.
  • access_level type changed from string to integer in GitLab 15.3.3.

List, get, add, and delete SAML group links.

Lists SAML group links.

GET /groups/:id/saml_group_links

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesID or URL-encoded path of the group

If successful, returns 200 and the following response attributes:

AttributeTypeDescription
[].namestringName of the SAML group
[].access_levelinteger Role (access_level) for members of the SAML group. The attribute had a string type from GitLab 15.3.0 to GitLab 15.3.3

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links"

Example response:

[
  {
    "name": "saml-group-1",
    "access_level": 10
  },
  {
    "name": "saml-group-2",
    "access_level": 40
  }
]

Get a SAML group link for the group.

GET /groups/:id/saml_group_links/:saml_group_name

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesID or URL-encoded path of the group
saml_group_namestringyesName of an SAML group

If successful, returns 200 and the following response attributes:

AttributeTypeDescription
namestringName of the SAML group
access_levelinteger Role (access_level) for members of the SAML group. The attribute had a string type from GitLab 15.3.0 to GitLab 15.3.3

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1"

Example response:

{
"name": "saml-group-1",
"access_level": 10
}

Adds a SAML group link for a group.

POST /groups/:id/saml_group_links

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringyesID or URL-encoded path of the group
saml_group_namestringyesName of a SAML group
access_levelintegeryes Role (access_level) for members of the SAML group

If successful, returns 201 and the following response attributes:

AttributeTypeDescription
namestringName of the SAML group
access_levelinteger Role (access_level) for members of the for members of the SAML group. The attribute had a string type from GitLab 15.3.0 to GitLab 15.3.3

Example request:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{ "saml_group_name": "<your_saml_group_name`>", "access_level": <chosen_access_level> }' --url  "https://gitlab.example.com/api/v4/groups/1/saml_group_links"

Example response:

{
"name": "saml-group-1",
"access_level": 10
}

Deletes a SAML group link for the group.

DELETE /groups/:id/saml_group_links/:saml_group_name

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesID or URL-encoded path of the group
saml_group_namestringyesName of a SAML group

If successful, returns 204 status code without any response body.

Example request:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/saml_group_links/saml-group-1"

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:

/groups?per_page=100

And to switch pages add:

/groups?per_page=100&page=2

Group badges

Read more in the Group Badges documentation.

Group Import/Export

Read more in the Group Import/Export and Group Relations Export documentation.

Share Groups with Groups

These endpoints create and delete links for sharing a group with another group. For more information, see the related discussion in the GitLab Groups page.

Share group with another group. Returns 200 and the group details on success.

POST /groups/:id/share
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
group_idintegeryesThe ID of the group to share with
group_accessintegeryesThe role (access_level) to grant the group
expires_atstringnoShare expiration date in ISO 8601 format: 2016-09-26

Unshare the group from another group. Returns 204 and no content on success.

DELETE /groups/:id/share/:group_id
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
group_idintegeryesThe ID of the group to share with

Push Rules

Introduced in GitLab 13.4.

Get group push rules

Get the push rules of a group.

Only available to group owners and administrators.

GET /groups/:id/push_rule
AttributeTypeRequiredDescription
idinteger/stringyesThe ID of the group or URL-encoded path of the group 
{
  "id": 2,
  "created_at": "2020-08-17T19:09:19.580Z",
  "commit_message_regex": "[a-zA-Z]",
  "commit_message_negative_regex": "[x+]",
  "branch_name_regex": "[a-z]",
  "deny_delete_tag": true,
  "member_check": true,
  "prevent_secrets": true,
  "author_email_regex": "^[A-Za-z0-9.]+@gitlab.com$",
  "file_name_regex": "(exe)$",
  "max_file_size": 100
}

Users on GitLab Premium or Ultimate also see the commit_committer_check and reject_unsigned_commits parameters:

{
  "id": 2,
  "created_at": "2020-08-17T19:09:19.580Z",
  "commit_committer_check": true,
  "reject_unsigned_commits": false,
  ...
}

Add group push rule

Adds push rules to the specified group.

Only available to group owners and administrators.

POST /groups/:id/push_rule
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
deny_delete_tagbooleannoDeny deleting a tag
member_checkbooleannoAllows only GitLab users to author commits
prevent_secretsbooleanno Files that are likely to contain secrets are rejected
commit_message_regexstringnoAll commit messages must match the regular expression provided in this attribute, for example, Fixed \d+\..*
commit_message_negative_regexstringnoCommit messages matching the regular expression provided in this attribute aren’t allowed, for example, ssh\:\/\/
branch_name_regexstringnoAll branch names must match the regular expression provided in this attribute, for example, (feature|hotfix)\/*
author_email_regexstringnoAll commit author emails must match the regular expression provided in this attribute, for example, @my-company.com$
file_name_regexstringnoFilenames matching the regular expression provided in this attribute are not allowed, for example, (jar|exe)$
max_file_sizeintegernoMaximum file size (MB) allowed
commit_committer_checkbooleannoOnly commits pushed using verified emails are allowed
reject_unsigned_commitsbooleannoOnly commits signed through GPG are allowed
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule"

Response:

{
    "id": 19,
    "created_at": "2020-08-31T15:53:00.073Z",
    "commit_message_regex": "[a-zA-Z]",
    "commit_message_negative_regex": "[x+]",
    "branch_name_regex": null,
    "deny_delete_tag": false,
    "member_check": false,
    "prevent_secrets": false,
    "author_email_regex": "^[A-Za-z0-9.]+@gitlab.com$",
    "file_name_regex": null,
    "max_file_size": 100
}

Edit group push rule

Edit push rules for a specified group.

Only available to group owners and administrators.

PUT /groups/:id/push_rule
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group
deny_delete_tagbooleannoDeny deleting a tag
member_checkbooleannoRestricts commits to be authored by existing GitLab users only
prevent_secretsbooleanno Files that are likely to contain secrets are rejected
commit_message_regexstringnoAll commit messages must match the regular expression provided in this attribute, for example, Fixed \d+\..*
commit_message_negative_regexstringnoCommit messages matching the regular expression provided in this attribute aren’t allowed, for example, ssh\:\/\/
branch_name_regexstringnoAll branch names must match the regular expression provided in this attribute, for example, (feature|hotfix)\/*
author_email_regexstringnoAll commit author emails must match the regular expression provided in this attribute, for example, @my-company.com$
file_name_regexstringnoFilenames matching the regular expression provided in this attribute are not allowed, for example, (jar|exe)$
max_file_sizeintegernoMaximum file size (MB) allowed
commit_committer_checkbooleannoOnly commits pushed using verified emails are allowed
reject_unsigned_commitsbooleannoOnly commits signed through GPG are allowed
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/19/push_rule"

Response:

{
    "id": 19,
    "created_at": "2020-08-31T15:53:00.073Z",
    "commit_message_regex": "[a-zA-Z]",
    "commit_message_negative_regex": "[x+]",
    "branch_name_regex": null,
    "deny_delete_tag": false,
    "member_check": false,
    "prevent_secrets": false,
    "author_email_regex": "^[A-Za-z0-9.]+@staging.gitlab.com$",
    "file_name_regex": null,
    "max_file_size": 100
}

Delete group push rule

Deletes the push rules of a group.

Only available to group owners and administrators.

DELETE /groups/:id/push_rule
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group