Groups API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Interact with groups by using the REST API.

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

Get a single group

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 and enabled_git_access_protocol 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.
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 in a group, use the list a group’s projects endpoint.)

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 a maximum of 100 projects and shared projects. To get the details of all projects within a group, use the list a group’s projects endpoint instead.

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,
  "enabled_git_access_protocol": "all",
  "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,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false
}

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
  • duo_features_enabled
  • lock_duo_features_enabled
  • duo_availability
  • experiment_features_enabled

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",
  "duo_features_enabled": true,
  "lock_duo_features_enabled": false,
  "duo_availability": "default_on",
  "experiment_features_enabled": false,
  ...
}

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
}

List groups

List groups.

List all groups

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. Default is name
sortstringnoOrder groups in asc or desc order. Default is asc
statisticsbooleannoInclude group statistics (administrators only).
Note: For top-level groups, the response returns the full root_storage_statistics data displayed in the UI. Introduced in GitLab 17.4.
visibilitystringnoLimit to groups with public, internal, or private visibility.
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_storagestringnoFilter by repository storage used by the group (administrators only). Introduced in GitLab 16.3. Premium and Ultimate only.
marked_for_deletion_ondatenoFilter by date when group was marked for deletion. Introduced in GitLab 17.1. Premium and Ultimate only.
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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "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. For top-level groups, root_storage_statistics are added as well.

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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "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
    },
    "root_storage_statistics": {
      "build_artifacts_size": 0,
      "container_registry_size": 0,
      "container_registry_size_is_estimated": false,
      "dependency_proxy_size": 0,
      "lfs_objects_size": 0,
      "packages_size": 0,
      "pipeline_artifacts_size": 0,
      "repository_size": 0,
      "snippets_size": 0,
      "storage_size": 0,
      "uploads_size": 0,
      "wiki_size": 0
  },
    "wiki_access_level": "private",
    "duo_features_enabled": true,
    "lock_duo_features_enabled": false,
    "duo_availability": "default_on",
    "experiment_features_enabled": false,
  }
]

Users of GitLab Premium or Ultimate also see the wiki_access_level, duo_features_enabled, lock_duo_features_enabled, duo_availability, and experiment_features_enabled attributes.

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

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

Search for a 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 group details

List details of the group.

List 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
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, star_count 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_reportsbooleannoReturn only projects that have security reports artifacts present in any of their builds. This means “projects with security reports enabled”. Default is false. Ultimate only.

Footnotes:

  1. Orders the results by a similarity score calculated from the search URL parameter. When you use 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
  }
]

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 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
archivedbooleannoLimit by archived status
visibilitystringnoLimit by visibility public, internal, or private
order_bystringnoReturn projects ordered by id, name, path, created_at, updated_at, star_count 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,
      "emails_enabled": 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"
   }
]

List provisioned users

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Get a list of users provisioned by a given group. Does not include subgroups.

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
  },
  ...
]

List users

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
  • Status: Experiment
History

Get a list of users for a group. This endpoint returns users that are related to a top-level group regardless of their current membership. For example, users that have a SAML identity connected to the group, or service accounts created by the group or subgroups.

This endpoint is an experiment and might be changed or removed without notice.

Requires Owner role for the group.

GET /groups/:id/users
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/345/users?include_saml_users=true&include_service_accounts=true"

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesID or URL-encoded path of the group.
include_saml_usersbooleanyes (see description)Include users with a SAML identity. Either this value or include_service_accounts must be true.
include_service_accountsbooleanyes (see description)Include service account users. Either this value or include_saml_users must be true.
searchstringnoSearch users by name, email, username.

If successful, returns 200 OK and the following response attributes:

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
  },
  ...
]

List 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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "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, duo_features_enabled, lock_duo_features_enabled, duo_availability, and experiment_features_enabled attributes.

List descendant groups

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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "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, duo_features_enabled, lock_duo_features_enabled, duo_availability, and experiment_features_enabled attributes.

List shared groups

Get a list of groups where the given group has been invited. When accessed without authentication, only public shared 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
skip_groupsarray of integersnoSkip the specified group IDs
searchstringnoReturn the list of authorized groups matching the search criteria
order_bystringnoOrder groups by name, path, id, or similarity. Default is name
sortstringnoOrder groups in asc or desc order. Default is asc
visibilitystringnoLimit to groups with public, internal, or private visibility.
min_access_levelintegernoLimit to groups where current user has at least the specified role (access_level)
with_custom_attributesbooleannoInclude custom attributes in response (administrators only)
GET /groups/:id/groups/shared

Example response:

[
  {
    "id": 101,
    "web_url": "http://gitlab.example.com/groups/some_path",
    "name": "group1",
    "path": "some_path",
    "description": "",
    "visibility": "public",
    "share_with_group_lock": "false",
    "require_two_factor_authentication": "false",
    "two_factor_grace_period": 48,
    "project_creation_level": "maintainer",
    "auto_devops_enabled": "nil",
    "subgroup_creation_level": "maintainer",
    "emails_disabled": "false",
    "emails_enabled": "true",
    "mentions_disabled": "nil",
    "lfs_enabled": "true",
    "math_rendering_limits_enabled": "true",
    "lock_math_rendering_limits_enabled": "false",
    "default_branch": "nil",
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
        "allowed_to_push": [
          {
              "access_level": 30
          }
        ],
        "allow_force_push": "true",
        "allowed_to_merge": [
          {
              "access_level": 30
          }
        ],
        "developer_can_initial_push": "false",
        "code_owner_approval_required": "false"
    },
    "avatar_url": "http://gitlab.example.com/uploads/-/system/group/avatar/101/banana_sample.gif",
    "request_access_enabled": "true",
    "full_name": "group1",
    "full_path": "some_path",
    "created_at": "2024-06-06T09:39:30.056Z",
    "parent_id": "nil",
    "organization_id": 1,
    "shared_runners_setting": "enabled",
    "ldap_cn": "nil",
    "ldap_access": "nil",
    "wiki_access_level": "enabled"
  }
]

List invited groups

Get a list of invited groups in the given group. When accessed without authentication, only public invited groups are returned. This endpoint is rate-limited to 60 requests per minute per user (for authenticated users) or IP (for unauthenticated users).

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
searchstringnoReturn the list of authorized groups matching the search criteria
min_access_levelintegernoLimit to groups where current user has at least the specified role (access_level)
relationarray of stringsnoFilter the groups by relation (direct or inherited)
with_custom_attributesbooleannoInclude custom attributes in response (administrators only)
GET /groups/:id/invited_groups

Example response:

[
  {
    "id": 33,
    "web_url": "http://gitlab.example.com/groups/flightjs",
    "name": "Flightjs",
    "path": "flightjs",
    "description": "Illo dolorum tempore eligendi minima ducimus provident.",
    "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": "maintainer",
    "emails_disabled": false,
    "emails_enabled": true,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "math_rendering_limits_enabled": true,
    "lock_math_rendering_limits_enabled": false,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
        {
          "access_level": 40
        }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
        {
          "access_level": 40
        }
      ],
      "developer_can_initial_push": false
    },
    "avatar_url": null,
    "request_access_enabled": true,
    "full_name": "Flightjs",
    "full_path": "flightjs",
    "created_at": "2024-07-09T10:31:08.307Z",
    "parent_id": null,
    "organization_id": 1,
    "shared_runners_setting": "enabled",
    "ldap_cn": null,
    "ldap_access": null,
    "wiki_access_level": "enabled"
  }
]

List audit events

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

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

Manage groups

Create a group

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.
default_branchstringnoThe default branch name for group’s projects. Introduced in GitLab 16.11.
default_branch_protectionintegernoDeprecated in GitLab 17.0. Use default_branch_protection_defaults instead.
default_branch_protection_defaultshashnoIntroduced in GitLab 17.0. For available options, see Options for default_branch_protection_defaults.
descriptionstringnoThe group’s description.
enabled_git_access_protocolstringnoEnabled protocols for Git access. Allowed values are: ssh, http, and all to allow both protocols. Introduced in GitLab 16.9.
emails_disabledbooleanno(Deprecated in GitLab 16.5.) Disable email notifications. Use emails_enabled instead.
emails_enabledbooleannoEnable 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.
organization_idintegernoThe organization ID for the group.
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 set up 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_lockbooleannoUsers cannot be added to projects in this group. Premium and Ultimate only.
extra_shared_runners_minutes_limitintegernoCan be set by administrators only. Additional compute minutes for this group. GitLab Self-Managed, Premium and Ultimate only.
shared_runners_minutes_limitintegernoCan 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. GitLab Self-Managed, Premium and Ultimate only.
wiki_access_levelstringnoThe wiki access level. Can be disabled, private, or enabled. Premium and Ultimate only.
duo_availabilitystringnoDuo availability setting. Valid values are: default_on, default_off, never_on. Note: In the UI, never_on is displayed as “Always Off”.
experiment_features_enabledbooleannoEnable experiment features for this group.

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

Options for default_branch_protection_defaults

History

The default_branch_protection_defaults attribute describes the default branch protection defaults. All parameters are optional.

KeyTypeDescription
allowed_to_pusharrayAn array of access levels allowed to push. Supports Developer (30) or Maintainer (40).
allow_force_pushbooleanAllow force push for all users with push access.
allowed_to_mergearrayAn array of access levels allowed to merge. Supports Developer (30) or Maintainer (40).
developer_can_initial_pushbooleanAllow developers to initial push.

Create a 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/"

Sync a group with LDAP

  • Tier: Premium, Ultimate
  • Offering: GitLab Self-Managed

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

Update group attributes

History

On GitLab Self-Managed, 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.
default_branchstringnoThe default branch name for group’s projects. Introduced in GitLab 16.11.
default_branch_protectionintegernoDeprecated in GitLab 17.0. Use default_branch_protection_defaults instead.
default_branch_protection_defaultshashnoIntroduced in GitLab 17.0. For available options, see Options for default_branch_protection_defaults.
descriptionstringnoThe description of the group.
enabled_git_access_protocolstringnoEnabled protocols for Git access. Allowed values are: ssh, http, and all to allow both protocols. Introduced in GitLab 16.9.
emails_disabledbooleanno(Deprecated in GitLab 16.5.) Disable email notifications. Use emails_enabled instead.
emails_enabledbooleannoEnable 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.
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 set up two-factor authentication.
shared_runners_settingstringnoSee Options for shared_runners_setting. Enable or disable instance 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_limitintegernoCan be set by administrators only. Additional compute minutes for this group. GitLab Self-Managed, Premium and Ultimate only.
file_template_project_idintegernoThe ID of a project to load custom file templates from. Premium and Ultimate only.
membership_lockbooleannoUsers cannot be added to projects in this group. Premium and Ultimate only.
prevent_forking_outside_groupbooleannoWhen enabled, users can not fork projects from this group to external namespaces. Premium and Ultimate only.
shared_runners_minutes_limitintegernoCan 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. GitLab Self-Managed, Premium and Ultimate only.
unique_project_download_limitintegernoMaximum 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. Ultimate only.
unique_project_download_limit_interval_in_secondsintegernoTime 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). Ultimate only.
unique_project_download_limit_allowlistarray of stringsnoList of usernames excluded from the unique project download limit. Available only on top-level groups. Default: [], Maximum: 100 usernames. Ultimate only.
unique_project_download_limit_alertlistarray 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. Ultimate only.
auto_ban_user_on_excessive_projects_downloadbooleannoWhen 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. Ultimate only.
ip_restriction_rangesstringnoComma-separated list of IP addresses or subnet masks to restrict group access. Introduced in GitLab 15.4. Premium and Ultimate only.
allowed_email_domains_liststringnoComma-separated list of email address domains to allow group access. Introduced in 17.4. GitLab Premium and Ultimate only.
wiki_access_levelstringnoThe wiki access level. Can be disabled, private, or enabled. Premium and Ultimate only.
duo_availabilitystringnoDuo availability setting. Valid values are: default_on, default_off, never_on. Note: In the UI, never_on is displayed as “Always Off”.
experiment_features_enabledbooleannoEnable experiment features for this group.
math_rendering_limits_enabledbooleannoIndicates if math rendering limits are used for this group.
lock_math_rendering_limits_enabledbooleannoIndicates if math rendering limits are locked for all descendent groups.
duo_features_enabledbooleannoIndicates whether GitLab Duo features are enabled for this group. Introduced in GitLab 16.10. GitLab Self-Managed, Premium and Ultimate only.
lock_duo_features_enabledbooleannoIndicates whether the GitLab Duo features enabled setting is enforced for all subgroups. Introduced in GitLab 16.10. GitLab Self-Managed, Premium and Ultimate only.
max_artifacts_sizeintegerNoThe maximum file size in megabytes for individual job artifacts.

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 a maximum of 100 projects and shared projects. To get the details of all projects in a group, use the list a group’s projects endpoint instead.

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,
  "enabled_git_access_protocol": "all",
  "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,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false
}

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, duo_features_enabled, lock_duo_features_enabled, duo_availability, and experiment_features_enabled attributes.

Options for shared_runners_setting

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

ValueDescription
enabledEnables instance runners for all projects and subgroups in this group.
disabled_and_overridableDisables instance runners for all projects and subgroups in this group, but allows subgroups to override this setting.
disabled_and_unoverridableDisables instance 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 instance runners for all projects and subgroups in this group, but allows subgroups to override this setting.

Group members

See the Group Members documentation.

Update group avatars

Update group avatars.

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"

Upload a group avatar

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

History

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="

Delete a group

History

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, deletes 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_removeboolean/stringnoImmediately deletes a subgroup if it is marked for deletion. Introduced in GitLab 15.4. Premium and Ultimate only.
full_pathstringnoFull path of subgroup to use with permanently_remove. Introduced in GitLab 15.4. To find the subgroup path, see the group details. Premium and Ultimate only.

The response is 202 Accepted if the user has authorization.

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

Restore a group marked for deletion

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Restores a group marked for deletion.

POST /groups/:id/restore

Parameters:

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

Revoke a token

History

The availability of this feature is controlled by a feature flag. For more information, see the history.

Revoke a token, if it has access to the group or any of its subgroups and projects. If the token is revoked, or was already revoked, its details are returned in the response.

The following criteria must be met:

  • The group must be a top-level group.
  • You must have the Owner role for the group.
  • The token type is one of:
    • Personal access token
    • Group access token
    • Project access token
    • Group deploy token
    • User feed tokens

Additional token types may be supported at a later date.

POST /groups/:id/tokens/revoke
AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group.
tokenstringYesThe plaintext token.

If successful, returns 200 OK and a JSON representation of the token. The attributes returned will vary by token type.

Example request

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"token":"glpat-EXAMPLE"}' \
  --url "https://gitlab.example.com/api/v4/groups/63/tokens/revoke"

Example response:

{
    "id": 9,
    "name": "my-subgroup-deploytoken",
    "username": "gitlab+deploy-token-9",
    "expires_at": null,
    "scopes":
    [
        "read_repository",
        "read_package_registry",
        "write_package_registry"
    ],
    "revoked": true,
    "expired": false
}

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
member_role_idintegernoThe ID of a Custom Role to assign to the invited group

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

Transfer a project to a 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"

Transfer a group

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"

List locations available for group transfer

History

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"
  }
]