群组 API

使用 REST API 与群组交互。

响应中返回的字段根据经过身份验证的用户的权限而有所不同。

获取单个群组

获取群组的所有详情。如果群组是公开课访问的，则此端点的使用无需认证。有种情况是，如果群组是公开课访问的，且请求用户是管理员。如有认证且用户是管理员或群组拥有者，它会返回群组的 runners_token 和 enabled_git_access_protocol。

GET /groups/:id

参数

属性 类型 是否必需 描述
id integer/string yes ID 或 URL 编码的群组路径。
with_custom_attributes boolean no 在响应中包含自定义属性（仅管理员）。
with_projects boolean no 返回属于特定群组的项目详情（默认为 true）。（已弃用，计划在 API v5 中移除。如要获取群组中所有项目的详情，可以使用列举群组项目的 API 端点。)
note 响应中的 projects 和 shared_projects 属性已被弃用并计划在 API v5 中移除。要获取群组内所有项目的详情，要么使用列举群组项目的 API 端点，要么使用列举群组共享项目的 API 端点。
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4"

此端点返回最大 100个项目和共享项目。要获取群组内所有项目的详情，请使用列举群组项目的 API 端点。

示例响应：

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

prevent_sharing_groups_outside_hierarchy 属性仅在顶级群组呈现。

极狐GitLab 专业版和旗舰版 用户还可以看到以下属性：

  • shared_runners_minutes_limit
  • extra_shared_runners_minutes_limit
  • marked_for_deletion_on
  • membership_lock
  • wiki_access_level

额外的响应属性：

{
  "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,
  ...
}

当添加 with_projects=false 参数时，不会返回项目。

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

示例响应：

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

列出群组

列出群组

列出所有群组

获取经过身份验证的用户的可见群组列表。进行未授权访问时，只返回公共群组。

默认情况下，此请求一次返回 20 个结果，因为 API 结果是分页的。

当进行未授权访问时，此端点还支持键集分页：

参数：

参数 类型 是否必需 描述
skip_groups array of integers no 跳过通过的群组 ID
all_available boolean no 显示所有您可以访问的群组（对于经过身份验证的用户，默认为 false；对于管理员，默认为 true）
search string no 返回匹配搜索条件的授权群组的列表
order_by string no 根据 name、path、id 或 similarity 为群组排序（如果查询，引入于极狐GitLab 14.1）。默认为 name
sort string no 按照 asc 或 desc 顺序为群组排序。默认为 asc
statistics boolean no 包括群组统计（仅对管理员）。
注意： REST API 响应不提供 UI 中显示的完整 RootStorageStatistics 数据。要匹配 UI 中的数据，请使用 GraphQL 而不是 REST
visibility string no 限制群组的可见性，诸如 public、internal 或 private。
with_custom_attributes boolean no 响应中包括自定义属性（仅对管理员）
owned boolean no 限制为当前用户明确拥有的群组
min_access_level integer no 限制为当前用户至少有此角色 (access_level) 的群组
top_level_only boolean no 限制为顶级群组，不包括所有子群组
repository_storage string no 使用群组使用的 (administrators only) 仓库存储进行过滤。引入于 16.3。仅限专业版和旗舰版。
marked_for_deletion_on date no 当群组被标记为删除时，通过日期过滤。引入于 17.1。仅限专业版和旗舰版。 
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,
    "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=true 并且经过身份验证的用户是管理员，会返回额外群组统计。

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

专业版或旗舰版的用户也可以看到 wiki_access_level 参数。

您可以通过名称或路径进行搜索，参见下文。

您可以使用以下内容通过自定义属性进行过滤：

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

群组中的命名空间

默认情况下，群组仅能同时获取 20 个命名空间，因为 API 结果被分页。

要获取更多（上限为 100）的话，给 API 调用传递如下参数：

/groups?per_page=100

增加切换页数：

/groups?per_page=100&page=2

查找群组

获取所有匹配名称或路径的群组：

GET /groups?search=foobar

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

列出群组详情

列出群组详情。

列出项目

获取群组内的项目列表。当使用无认证访问时，仅返回公开项目。

默认情况下，请求同时返回 20 个结果，因为 API 结果被分页。

GET /groups/:id/projects

参数：

属性 类型 是否必需 描述
id integer/string yes ID 或 URL 编码的群组路径
archived boolean no 归档状态限制。
visibility string no 可见性限制，日不public、internal 或 private
order_by string no 按照 id、 name、path、created_at、updated_at、similarity 1、star_count 或 last_activity_at 字段的顺序放回项目。默认为 created_at
sort string no 按照 asc 或 desc 顺序对项目进行排序并返回。默认为 desc
search string no 返回与搜查条件相匹配的认证项目
simple boolean no 返回每个项目的受限制字段。在没有认证的情况下，这是一个无操作（no-op），只返回简单的字段
owned boolean no 仅限当前用户拥有的项目
starred boolean no 仅限当前用户 star 了的项
topic string no 返回与主题相匹配的项目
with_issues_enabled boolean no 仅限启用了议题功能的项目。默认为 false
with_merge_requests_enabled boolean no 仅限启用了合并请求功能的项目。默认为 false
with_shared boolean no 包含共享到群组的项目。默认为 true
include_subgroups boolean no 包含此群组子群组中的项目。默认为 false
min_access_level integer no 限制当前用户至少拥有 (access_level)角色
with_custom_attributes boolean no 在响应中包含自定义属性（仅限管理员）
with_security_reports boolean no 仅返回在其构建中包含安全报告制品的项目。这意味着“项目启用了安全报告”。默认为 false。仅旗舰版可用。

脚注:

  1. 根据 search URL参数计算出的相似度分数对结果进行排序。当使用 order_by=similarity 时，会忽略 sort 参数。当没有提供 search 参数时，API 返回按 name 排序的项目。

示例响应：

[
  {
    "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 要想对群组中项目和共享到群组中的项目做区分，可使用 namespace 属性。当项目被共享到群组中时，它的 namespace 属性会有所不同。

列出共享项目

列出此群组中的共享项目。当使用无认证访问时，仅返回公开的共享项目。

默认情况下，请求同时返回 20 个结果，因为 API 结果被分页。

GET /groups/:id/projects/shared

参数：

属性 类型 是否必需 描述
id integer/string yes ID 或 URL 编码的群组路径
archived boolean no 归档状态限制
visibility string no 可见性限制，诸如 public、internal 或 private
order_by string no 通过 id、name、path、created_at、updated_at、star_count 或 last_activity_at 字段按序返回项目。默认是 created_at
sort string no 按照 asc 或 desc 对项目排序并返回。默认为 desc
search string no 返回与搜索标准相匹配的授权项目列表
simple boolean no 仅返回每个项目的受限字段。在没有认证的情况下，这是一个无操作（no-op），只返回简单的字段。
starred boolean no 返回当前用户 star 了的项目列表
with_issues_enabled boolean no 返回启用了议题功能的项目列表。默认为 false
with_merge_requests_enabled boolean no 返回启用了合并请求功能的项目列表。默认为 false
min_access_level integer no 限制在当前用户至少拥有此角色（access_level）的项目中
with_custom_attributes boolean no 在响应中包括自定义属性（仅管理员）

示例响应：

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

列出配置用户

列出给定群众的配置用户列表。不包括子群组。

至少需要群组的维护者角色。

GET /groups/:id/provisioned_users

参数：

属性 类型 是否必需 描述
id integer/string yes ID 或 URL 编码的群组路径
username string no 返回特定用户名的单个用户
search string no 通过名称、邮箱和用户名搜索用户
active boolean no 仅返回活跃用户
blocked boolean no 仅返回被阻塞的用户
created_after datetime no 返回特定时间后创建的用户
created_before datetime no 返回特定时间前创建的用户

示例响应：

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

列出用户

获取群组的用户列表。此端点返回与顶级群组相关的用户，无论其当前成员资格如何。例如，具有与群组关联的 SAML 身份的用户，或由群组或子组创建的服务帐户。

此端点是一个 实验性功能，可能会在通知之前进行更改或删除。

需要群组的拥有者角色。

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"

参数：

属性 类型 是否必需 描述
id integer/string yes ID 或 URL 编码的群组路径。
include_saml_users boolean yes (see description) 包含具有 SAML 身份识别的用户。此值或 include_service_accounts 必须为 true。
include_service_accounts boolean yes (see description) 包含服务账号用户。此值或 include_saml_users 必须为 true。
search string no 通过名称、邮箱和用户名搜索用户。

如果成功，返回 200 OK 和以下响应属性：

示例响应：

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

列出群组的子群组

获取群组中可见直接子群组的列表。

默认情况下，此请求一次返回 20 个结果，因为 API 结果是分页的。

如果您将此列表请求为：

  • 未经身份验证的用户，响应仅返回公共群组。
  • 经过身份验证的用户，响应仅返回您所在的群组并且不包括公共群组。

参数：

参数 类型 是否必需 描述
id integer/string yes 直系父群组的 ID 或 URL 编码的群组路径
skip_groups array of integers no 跳过通过的群组 ID
all_available boolean no 显示所有您可以访问的群组（对于经过身份验证的用户，默认为 false；对于管理员，默认为 true）
search string no 返回匹配查询条件的授权群组列表。仅搜索子群组短路径（不是完整路径）
order_by string no 根据 name、path 或 id 为群组排序。默认为 name
sort string no 按照 asc 或 desc 顺序为群组排序。默认为 asc
statistics boolean no 包括群组统计（仅为管理员）
with_custom_attributes boolean no 响应中包括自定义属性（仅为管理员）
owned boolean no 限制为当前用户明确拥有的群组
min_access_level integer no 限制为当前用户至少有此角色 (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,
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]

专业版或旗舰版的用户也可以看到 wiki_access_level 参数。

列出群组的下级群组

引入于极狐GitLab 13.5。

获取该群组的可见下级群组列表。当进行未授权的访问时，仅返回公共组。

默认情况下，此请求一次返回 20 个结果，因为 API 结果是分页的。

参数：

参数 类型 是否必需 描述
id integer/string yes 直系父群组的 ID 或 URL 编码的群组路径
skip_groups array of integers no 跳过通过的群组 ID
all_available boolean no 显示所有您可以访问的群组（对于经过身份验证的用户，默认为 false；对于管理员，默认为 true）
search string no 返回匹配查询条件的授权群组列表。仅搜索下级群组短路径（不是完整路径）
order_by string no 根据 name、path 或 id 为群组排序。默认为 name
sort string no 按照 asc 或 desc 顺序为群组排序。默认为 asc
statistics boolean no 包括群组统计（仅为管理员）
with_custom_attributes boolean no 响应中包括自定义属性（仅为管理员）
owned boolean no 限制为当前用户明确拥有的群组
min_access_level integer no 限制为当前用户至少有此角色 (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"
  }
]

专业版或旗舰版的用户也可以看到 wiki_access_level 参数。

列出共享群组

列出已邀请的群组列表。当使用无认证访问时，仅返回公共共享群组。

默认情况下，此请求返回 20 个结果，因为API结果是分页的。

参数

属性 类型 是否必需 描述
id integer/string yes ID URL 编码的群组路径
skip_groups array of integers no 跳过特定的群组 ID
search string no 返回与搜索标准相匹配的授权群组列表
order_by string no 通过 name、path、id 或 similarity 对群组排序。默认是name
sort string no 通过 asc 或 desc 对群组排序。默认是 asc
visibility string no 群组可见性限制，诸如 public、internal 或 private。
min_access_level integer no 限制在当前用户至少拥有指定角色(access_level)的群组中。
with_custom_attributes boolean no 在响应中包含自定义属性（仅管理员） 
GET /groups/:id/groups/shared

示例响应：

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

列出邀请群组

列出已邀请的群组列表。当使用无认证访问时，仅返回公共邀请群组。

此端点的速率限制为每个用户（认证用户）或 IP（针对非认证用户）每分钟 60 个请求。

默认情况下，此请求返回 20 个结果，因为 API 结果 是分页的。

参数：

属性 类型 是否必需 描述
id integer/string yes ID 或 URL 编码的群组路径
search string no 返回和搜索标准相匹配的授权群组列表
min_access_level integer no 限制在当前用户至少拥有指定角色(access_level)的群组中。
relation array of strings no 通过关系（直接或继承）来过滤群组
with_custom_attributes boolean no 在响应中包含自定义属性（仅管理员） 
GET /groups/:id/invited_groups

示例响应：

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

列出审计事件

可以通过群组审计事件 API来访问群组审计事件。

管理群组

创建群组

note 在极狐GitLab SaaS 上，您必须使用极狐GitLab UI 创建没有父群组的群组。您不能使用 API 来执行此操作。

创建一个新的项目组。仅适用于可以创建群组的用户。

POST /groups

参数：

参数 类型 是否必需 描述
name string yes 群组名称
path string yes 群组路径
auto_devops_enabled boolean no 默认为群组内所有项目的 Auto DevOps 流水线
avatar mixed no 群组头像的镜像文件。引入于极狐GitLab 12.9
default_branch string no 群组项目的默认分支名称。引入于 16.11。
default_branch_protection integer no 参见 default_branch_protection 选项。默认为全局级别默认分支保护设置
default_branch_protection_defaults hash no 引入于 17.0。可用选项，可以查看 default_branch_protection_defaults 选项。
enabled_git_access_protocol string no 启用 Git 访问协议。允许值为： ssh、http 和 all，all 意味着同时允许两个协议。引入于 16.9。
description string no 群组描述
emails_disabled boolean no 禁用电子邮件通知
emails_enabled boolean no 启用邮件通知。
lfs_enabled boolean no 为群组中的项目启用/禁用大型文件存储（LFS）
mentions_disabled boolean no 禁用群组被提及的能力
organization_id integer no 群组的组织 ID。
parent_id integer no 创建嵌套群组的父群组 ID
project_creation_level string no 开发者是否能够在群组中创建项目。可以是 noone（没人可以）、maintainer（拥有维护者角色的用户）或 developer（拥有开发者或维护者角色的用户）
request_access_enabled boolean no 允许用户请求成员访问权限
require_two_factor_authentication boolean no 要求群组中的所有用户设置两步验证
share_with_group_lock boolean no 防止在群组中与另一个群组共享项目
subgroup_creation_level string no 允许创建子群组。可以是 owner（拥有者）或 maintainer（拥有维护者角色的用户）
two_factor_grace_period integer no 执行两步验证之前的时间（小时）
visibility string no 群组可见性：private、internal 或 public
membership_lock boolean no 用户无法到此群组的项目中
extra_shared_runners_minutes_limit integer no 仅可由管理员设置。此群组的额外计算分钟数
shared_runners_minutes_limit integer no 仅可由管理员设置。此群组每月最大的计算分钟数，可以是 nil（默认；继承系统默认）、0（无限）或 > 0
wiki_access_level string no Wiki 访问级别，可以是 disabled、private 或 enabled

default_branch_protection 选项

default_branch_protection 参数确定具有开发者或维护者角色的用户是否可以推送到适用的默认分支，如下表所述：

值 描述
0 无保护。具有开发者或维护者角色的用户可以：
- 推送新提交
- 强制推送
- 删除分支
1 部分保护。具有开发者或维护者角色的用户可以：
- 推送新提交
2 完整保护。只有具有维护者角色的用户可以：
- 推送新提交
3 保护以防止推送。具有维护者角色的用户可以：
- 推送新提交
- 强制推送
- 接收合并请求
具有开发者角色的用户可以：
- 接受合并请求
4 防止除初始推送之外的推送。具有开发者权限的用户可以：
- 将提交推送到空仓库。
具有维护者角色的用户可以：
- 推送新提交
- 强制推送更改
- 接受合并请求
具有开发者角色的用户可以：
- 接受合并请求

default_branch_protection_defaults 选项

  • 引入于 GitLab 17.0。

default_branch_protection_defaults 属性描述了默认分支保护默认值。所有参数都是可选的。

Key 类型 描述
allowed_to_push array 允许推送的访问级别数组。支持开发者 （30） 或维护者（40）。
allow_force_push boolean 允许所有具有推送权限的用户进行强制推送。
allowed_to_merge array 允许合并的访问级别数组。支持开发者 （30） 或维护者（40）。
developer_can_initial_push boolean 允许开发者进行初始化推送。

新建子群组

新建子群组与新建群组类似。您需要列出群组调用中的 parent_id。然后您可以输入以下内容：

  • 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/"

同步 LDAP 群组

同步 LDAP 群组。仅对群组所有者和管理员可用。

POST /groups/:id/ldap_sync

参数

  • id (必需) - ID 或用户群组的路径

更新群组属性

  • unique_project_download_limit、unique_project_download_limit_interval_in_seconds 和 unique_project_download_limit_allowlist 引入于极狐GitLab 15.3，功能标志为 limit_unique_project_downloads_per_namespace_user。默认禁用。
在私有化部署的极狐GitLab 上，默认情况下 unique_project_download_limit、unique_project_download_limit_interval_in_seconds、unique_project_download_limit_allowlist 和 auto_ban_user_on_excessive_projects_download 不可用。 要使其可用，管理员可以启用名为 limit_unique_project_downloads_per_namespace_user 的功能标志。

更新项目群组。仅对群组拥有者和管理员可用。

PUT /groups/:id
参数 类型 是否必需 描述
id integer yes 群组 ID
name string no 群组名称
path string no 群组路径
auto_devops_enabled boolean no 默认为群组内所有项目的 Auto DevOps 流水线
avatar mixed no 群组头像的镜像文件。引入于极狐GitLab 12.9
default_branch string no 群组项目的默认分支 名称。引入于 16.11。
default_branch_protection integer no 参见 default_branch_protection 选项
default_branch_protection_defaults hash no 引入于 17.0。可用选项，可查看 default_branch_protection_defaults 选项。
description string no 群组描述
enabled_git_access_protocol string no 启用 Git 访问协议。允许值为：ssh、http 和 all。all 意味着同时支持两个协议。引入于 16.9。
emails_disabled boolean no 禁用电子邮件通知
emails_enabled boolean no 启用邮件通知。
lfs_enabled boolean no 为群组中的项目启用/禁用大型文件存储（LFS）
mentions_disabled boolean no 禁用群组被提及的能力
prevent_sharing_groups_outside_hierarchy boolean no 参见防止群组层次结构外的群组共享。此参数仅对顶级群组可用。引入于极狐GitLab 14.1
project_creation_level string no 开发者是否能够在群组中创建项目。可以是 noone（没人可以）、maintainer（拥有维护者角色的用户）或 developer（拥有开发者或维护者角色的用户）
request_access_enabled boolean no 允许用户请求成员访问权限
require_two_factor_authentication boolean no 要求群组中的所有用户设置两步验证
shared_runners_setting string no 参见 shared_runners_setting 选项。启用或禁用群组的子群组和项目的共享 Runner
share_with_group_lock boolean no 防止在群组中与另一个群组共享项目
subgroup_creation_level string no 允许创建子群组。可以是 owner（拥有者）或 maintainer（拥有维护者角色的用户）
two_factor_grace_period integer no 执行两步验证之前的时间（小时）
visibility string no 群组可见性：private、internal 或 public
extra_shared_runners_minutes_limit integer no 仅可由管理员设置。此群组的额外计算分钟数。仅限私有化部署的专业版和旗舰版。
file_template_project_id integer no 加载自定义文件模板的项目 ID 。仅限专业版和旗舰版。
membership_lock boolean no 用户无法添加到此群组的项目中。仅限专业版和旗舰版。
prevent_forking_outside_group boolean no 如果启用，用户不能从此群组派生项目到外部命名空间。仅限专业版和旗舰版。
shared_runners_minutes_limit integer no 仅可由管理员添加。此群组每月最大的计算分钟数，可以是 nil（默认；继承系统默认）、0（无限）或 > 0。仅限私有化部署的专业版和旗舰版。
unique_project_download_limit integer no 在被禁止之前，用户在指定时间段内可以下载的唯一项目的最大数量。仅适用于顶级群组。默认值：0，最大值：10,000。仅限专业版。
unique_project_download_limit_interval_in_seconds integer no 用户在被禁止之前可以下载最大数量项目的时间段。仅适用于顶级群组。默认值：0，最大值：864,000 秒（10 天）。仅限专业版和旗舰版。
unique_project_download_limit_allowlist array of strings no 从唯一项目下载限制中排除的用户名列表。仅适用于顶级群组。默认值：[]，最大值：100 个用户名。仅限专业版。
unique_project_download_limit_alertlist array of integers no 超过唯一项目下载限制时通过电子邮件发送的用户 ID 列表。仅适用于顶级群组。默认值：[]，最大值：100 个用户 ID。引入于极狐GitLab 15.9。仅限专业版。
auto_ban_user_on_excessive_projects_download boolean no 启用后，当用户下载超过 unique_project_download_limit 和 unique_project_download_limit_interval_in_seconds 指定的最大唯一项目数时，用户将被自动禁止加入该群组。引入于极狐GitLab 15.4。仅限旗舰版。
ip_restriction_ranges string no 以逗号分隔的 IP 地址或子网掩码列表，用于限制群组访问。引入于极狐GitLab 15.4。仅限专业版和旗舰版。
allowed_email_domains_list string no 允许群组访问的邮件地址域名，用逗号分隔。引入于 17.4。仅限专业版和旗舰版。
wiki_access_level string no Wiki 访问级别。可以是 disabled、private 或 enabled。仅限专业版和旗舰版。
math_rendering_limits_enabled boolean no 指示此群组是否使用了数学渲染限制。
lock_math_rendering_limits_enabled boolean no 指示所有子群组是否被数学渲染限制锁定。
note 响应中的 projects 和 shared_projects 参数已被弃用并且计划在 API v5 中删除。 要获取群组内所有项目的详细信息，请使用列出群组的项目或列出群组的共享项目端点。
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/5?name=Experimental"

此端点返回最多 100 个项目和共享项目。要获取群组内所有项目的详细信息，请使用列出群组的项目端点。

  • 响应示例：
{
  "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
}

prevent_sharing_groups_outside_hierarchy 参数仅在顶级群组中的响应中存在。

专业版或旗舰版的用户也可以看到 wiki_access_level 参数。

shared_runners_setting 选项

shared_runners_setting 属性决定是否为群组的子群组和项目启用实例 runner。

值 描述
enabled 为群组的所有子群组和项目启用实例 runner。
disabled_and_overridable 为群组的所有子群组和项目禁用实例 runner，但是允许子群组覆盖此设置。
disabled_and_unoverridable 为群组的所有子群组和项目禁用实例 runner，并阻止子群组对此设置进行覆盖。
disabled_with_override （已启用。使用 disabled_and_overridable） 在群组中为所有项目和子群组禁用实例 runner，但是允许子群组覆盖此设置。

群组成员

查看群组成员文档。

更新群组头像

更新群组头像。

下载群组头像

获取群组头像。如果群组是公开课访问的，则此端点无需身份验证即可访问。

GET /groups/:id/avatar
Attribute Type Required Description
id integer/string yes ID of the group

示例：

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

上传群组头像

要从您的文件系统上传头像文件，可使用 --form 参数。这将导致 curl 使用 Content-Type: multipart/form-data 头部发布数据。file= 参数必须指向您的文件系统上的文件，并且必须以 @ 开头。例如：

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

移除群组头像

  • 引入于 15.4。

要移除群组头像，请使用空值作为 avatar 属性。

示例请求：

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

删除群组

  • 立即删除子群组引入于极狐GitLab 15.3，功能标志为 immediate_delete_subgroup_api。默认禁用。
  • 立即删除子群组在 JihuLab.com 和私有化部署中启用于极狐GitLab 15.4。
  • 立即删除子群组默认启用于极狐GitLab 15.4。
  • 用于立即删除子组的标志 immediate_delete_subgroup_api 移除于极狐GitLab 15.9。

仅对群组所有者和管理员可用。

此端点：

  • 在专业版和旗舰版中，将群组标记为删除。默认情况下，会在 7 天后删除，但您可以在实例设置中更改保留期限。
  • 在基础版本中，立即删除群组并对后台作业进行排队以删除群组中的所有项目。
  • 如果子组被标记为删除（极狐GitLab 15.4 及更高版本），则立即删除该子群组。端点不会立即删除顶级群组。
DELETE /groups/:id

参数：

参数 类型 是否必需 描述
id integer/string yes ID 或 URL 编码的群组路径
permanently_remove boolean/string no 如果标记为删除，则立即删除子群组。引入于极狐GitLab 15.4
full_path string no 使用 permanently_remove 的子群组的完整路径。引入于极狐GitLab 15.4。要找到子群组路径，请查看群组详细信息

如果用户有授权，则响应为 202 Accepted。

NOTE： 如果 JihuLab.com 群组链接到订阅，则无法删除它。要删除这样的群组，首先要将订阅和其他群组进行链接。

还原标记为删除的群组

还原标记为删除的群组。

POST /groups/:id/restore

参数：

参数 类型 是否必需 描述
id integer/string yes ID 或 URL 编码的群组路径

撤销令牌

  • 引入于 17.2，使用名为 group_agnostic_token_revocation 功能标志。默认禁用。
  • 撤销用户的 feed 令牌引入于 17.3。
此功能的可用性受控于功能标志。更多信息可以查看历史。

如果令牌具有访问群组或其任何子组或项目的权限，则撤销令牌。如果令牌被撤销，或者已经被撤销，则返回响应中的令牌详细信息。

必需满足以下标准：

  • 群组必须是顶级群组。
  • 您必须具有群组的拥有者角色。
  • 令牌类型必须是以下之一：
    • 个人访问令牌
    • 群组访问令牌
    • 项目访问令牌
    • 群组部署令牌
    • 用户 feed 令牌

将来可能会支持其他令牌类型。

POST /groups/:id/tokens/revoke
属性 类型 是否必需 描述
id integer or string Yes 群组的 ID 或 URL 编码的路径。
token string Yes 纯文本令牌。

如果成功，则返回 200 OK 和令牌的 JSON 表示。返回的属性将因令牌类型而异。

示例请求：

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"

示例响应：

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

和其他群组共享群组

这些端点创建和删除用于与另一个群组共享群组的链接。有关更多信息，请参见极狐GitLab 群组页面中的相关讨论。

创建和其他群组共享群组的链接

和其他群组共享群组。如果成功，则返回 200 和群组详情。

POST /groups/:id/share
参数 类型 是否必需 描述
id integer/string yes ID 或 URL 编码的群组路径
group_id integer yes 要共享的群组的 ID
group_access integer yes 要授予群组的角色 (access_level
expires_at string no 共享过期日期。ISO 8601 格式：2016-09-26

删除和其他群组共享群组的链接

取消和其他群组共享群组。如果成功，返回 204，不返回任何内容。

DELETE /groups/:id/share/:group_id
参数 类型 是否必需 描述
id integer/string yes ID 或 URL 编码的群组路径
group_id integer yes 要共享的群组 ID

向群组转移项目

将项目转移到群组命名空间。仅对实例管理员可用，尽管不需要管理员实例访问权限的替代 API 端点也可用。 当项目仓库中存在打标签的包时，传输项目可能会失败。

POST  /groups/:id/projects/:project_id

参数：

参数 类型 是否必需 描述
id integer/string yes ID 或 URL 编码的目标群组路径
project_id integer/string yes ID 或 URL 编码的项目路径 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/4/projects/56"

转移群组

向新父群组转移群组或将子群组变更为顶级群组。管理员和用户可用：

  • 具有要转移的群组的所有者角色。
  • 如果转移群组，则有权在新的父群组中创建子群组。
  • 如果将子群组转换为顶级群组，则具有创建顶级群组的权限。
POST  /groups/:id/transfer

参数：

参数 类型 是否必需 描述
id integer yes 要转移群组的 ID
group_id integer no 新父群组的 ID。如果未指定，则将要转移的群组改为顶级组 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/4/transfer?group_id=7"

获取用户可以将群组转移为的群组

引入于极狐GitLab 15.4。

检索用户可以将群组转移到的群组列表。

GET /groups/:id/transfer_locations
参数 类型 是否必需 描述
id integer or string Yes ID 或 URL 编码的要转移的群组路径 .
search string No 要搜索的群组名称

请求示例：

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

响应示例：

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