{{< details >}}

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 极狐GitLab私有化部署, 极狐GitLab Dedicated

{{< /details >}}

使用此 API 查看和管理极狐GitLab群组。更多信息，请参见群组。

端点响应可能会根据群组中经过身份验证的用户的权限而有所不同。

获取单个群组

获取群组的所有详细信息。此端点可以在群组公开访问的情况下无需身份验证进行访问。如果请求的用户是管理员且群组公开访问，则返回 runners_token 和 enabled_git_access_protocol，如果用户是管理员或群组所有者。

GET /groups/:id

参数：

属性 类型 是否必需 描述
id integer/string 是 群组的 ID 或 URL 编码路径。
with_custom_attributes boolean 否 在响应中包含自定义属性（仅限管理员）。
with_projects boolean 否 包含属于指定群组的项目的详细信息（默认为 true）。(已弃用，计划在 API v5 中移除。要获取群组中所有项目的详细信息，请使用列出群组的项目端点。)

{{< alert type=”note” >}}

响应中的 projects 和 shared_projects 属性已弃用，并且计划在 API v5 中移除。要获取群组中所有项目的详细信息，请使用 列出群组的项目 或 列出群组的共享项目 端点。

{{< /alert >}}

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

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

示例响应：

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

额外的响应属性：

{
  "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 结果是分页的。

在无需身份验证的情况下访问时，此端点还支持键集分页：

  • 当请求连续页面的结果时，您应该使用键集分页。
  • 超过特定偏移限制（由REST API 的最大偏移量限制指定）时，偏移分页不可用。

参数：

属性 类型 是否必需 描述
skip_groups array of integers 否 跳过传递的群组 ID
all_available boolean 否 当为 true 时，返回所有可访问的群组。当为 false 时，仅返回用户是成员的群组。对于用户默认为 false，对于管理员默认为 true。未经身份验证的请求始终返回所有公共群组。owned 和 min_access_level 属性优先。
search string 否 返回符合搜索条件的授权群组列表
order_by string 否 按 name、path、id 或 similarity 排序群组。默认是 name
sort string 否 按 asc 或 desc 顺序排序群组。默认是 asc
statistics boolean 否 包含群组统计信息（仅限管理员）。
注意：对于顶级群组，响应返回 UI 中显示的完整 root_storage_statistics 数据。在极狐GitLab 17.4 中引入。
visibility string 否 限制为具有 public、internal 或 private 可见性的群组。
with_custom_attributes boolean 否 在响应中包含自定义属性（仅限管理员）
owned boolean 否 限制为当前用户显式拥有的群组
min_access_level integer 否 限制为当前用户至少具有此角色（access_level）的群组
top_level_only boolean 否 仅限顶级群组，排除所有子群组
repository_storage string 否 按群组使用的存储库存储进行过滤_（仅限管理员）_。在极狐GitLab 16.3 中引入。仅限专业版和旗舰版。
marked_for_deletion_on date 否 按群组标记为删除的日期进行过滤。在极狐GitLab 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,
    "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
  }
]

添加参数 statistics=true 且经过身份验证的用户是管理员时，将返回额外的群组统计信息。对于顶级群组，还会添加 root_storage_statistics。

GET /groups?statistics=true

当使用参数 statistics=true 且经过身份验证的用户是管理员时，响应包括有关容器注册表存储大小的信息：

  • container_registry_size：群组及其子群组中的所有容器存储库使用的总存储大小（以字节为单位）。计算为群组项目和子群组中的所有存储库大小之和。仅在启用容器注册表元数据数据库时可用。

  • container_registry_size_is_estimated：指示大小是基于所有存储库的实际数据的精确计算（false）还是由于性能限制而估算的（true）。

对于极狐GitLab私有化部署实例，必须启用容器注册表元数据数据库才能包含容器注册表大小属性。

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

极狐GitLab专业版或旗舰版用户还可以看到 wiki_access_level、duo_features_enabled、lock_duo_features_enabled、duo_availability 和 experiment_features_enabled 属性。

您可以按名称或路径搜索群组，见下文。

您可以通过以下方式按自定义属性进行过滤：

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 是 群组的 ID 或 URL 编码路径
archived boolean 否 按归档状态限制
visibility string 否 按可见性 public、internal 或 private 限制
order_by string 否 按 id、name、path、created_at、updated_at、similarity 1、star_count 或 last_activity_at 字段排序项目。默认是 created_at
sort string 否 按 asc 或 desc 顺序排序项目。默认是 desc
search string 否 返回符合搜索条件的授权项目列表
simple boolean 否 仅返回每个项目的有限字段。在无需身份验证的情况下，仅返回简单字段。
owned boolean 否 按当前用户拥有的项目进行限制
starred boolean 否 按当前用户加星的项目进行限制
topic string 否 返回与主题匹配的项目
with_issues_enabled boolean 否 按启用议题功能的项目进行限制。默认是 false
with_merge_requests_enabled boolean 否 按启用合并请求功能的项目进行限制。默认是 false
with_shared boolean 否 包含共享给此群组的项目。默认是 true
include_subgroups boolean 否 包含此群组的子群组中的项目。默认是 false
min_access_level integer 否 限制为当前用户至少具有此角色（access_level）的项目
with_custom_attributes boolean 否 在响应中包含自定义属性（仅限管理员）
with_security_reports boolean 否 仅返回在其任何构建中存在安全报告产物的项目。这意味着“启用了安全报告的项目”。默认是 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
  }
]

{{< alert type=”note” >}}

为了区分群组中的项目和共享给群组的项目，可以使用 namespace 属性。当项目已共享给群组时，其 namespace 与请求所在群组不同。

{{< /alert >}}

列出共享项目

获取共享给此群组的项目列表。在无需身份验证的情况下访问时，仅返回公共共享项目。

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

GET /groups/:id/projects/shared

参数：

属性 类型 是否必需 描述
id integer/string 是 群组的 ID 或 URL 编码路径
archived boolean 否 按归档状态限制
visibility string 否 按可见性 public、internal 或 private 限制
order_by string 否 按 id、name、path、created_at、updated_at、star_count 或 last_activity_at 字段排序项目。默认是 created_at
sort string 否 按 asc 或 desc 顺序排序项目。默认是 desc
search string 否 返回符合搜索条件的授权项目列表
simple boolean 否 仅返回每个项目的有限字段。在无需身份验证的情况下，仅返回简单字段。
starred boolean 否 按当前用户加星的项目进行限制
with_issues_enabled boolean 否 按启用议题功能的项目进行限制。默认是 false
with_merge_requests_enabled boolean 否 按启用合并请求功能的项目进行限制。默认是 false
min_access_level integer 否 限制为当前用户至少具有此角色（access_level）的项目
with_custom_attributes boolean 否 在响应中包含自定义属性（仅限管理员）

示例响应：

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

列出配置的用户

{{< details >}}

  • Tier: 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

{{< /details >}}

获取由指定群组配置的用户列表。不包括子群组。

需要在群组中至少具有维护者角色。

GET /groups/:id/provisioned_users

参数：

属性 类型 是否必需 描述
id integer/string 是 ID 或 URL 编码路径
username string 否 返回具有特定用户名的单个用户
search string 否 按名称、电子邮件、用户名搜索用户
active boolean 否 仅返回活动用户
blocked boolean 否 仅返回被阻止的用户
created_after datetime 否 返回在指定时间之后创建的用户
created_before datetime 否 返回在指定时间之前创建的用户

示例响应：

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

列出用户

{{< details >}}

  • Tier: 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署
  • Status: 试验

{{< /details >}}

{{< history >}}

{{< /history >}}

获取群组的用户列表。此端点返回与顶级群组相关的用户，无论他们当前的成员身份如何。例如，与群组连接了 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 是 ID 或 URL 编码路径。
include_saml_users boolean 是 (见描述) 包含具有 SAML 身份的用户。此值或 include_service_accounts 必须为 true。
include_service_accounts boolean 是 (见描述) 包含服务帐户用户。此值或 include_saml_users 必须为 true。
search string 否 按名称、电子邮件、用户名搜索用户。

如果成功，返回 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 是 直接父群组的 ID 或 URL 编码路径
skip_groups array of integers 否 跳过传递的群组 ID
all_available boolean 否 显示您可以访问的所有群组（对于经过身份验证的用户默认为 false，对于管理员默认为 true）；属性 owned 和 min_access_level 优先
search string 否 返回符合搜索条件的授权群组列表。仅搜索子群组短路径（不搜索完整路径）
order_by string 否 按 name、path 或 id 排序群组。默认是 name
sort string 否 按 asc 或 desc 顺序排序群组。默认是 asc
statistics boolean 否 包含群组统计信息（仅限管理员）
with_custom_attributes boolean 否 在响应中包含自定义属性（仅限管理员）
owned boolean 否 限制为当前用户显式拥有的群组
min_access_level integer 否 限制为当前用户至少具有此角色（access_level）的群组
all_available boolean 否 当为 true 时，返回所有可访问的群组。当为 false 时，仅返回用户是成员的群组。对于用户默认为 false，对于管理员默认为 true。未经身份验证的请求始终返回所有公共群组。owned 和 min_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"
  }
]

极狐GitLab专业版或旗舰版用户还可以看到 wiki_access_level、lock_duo_features_enabled 和 experiment_features_enabled 属性。

列出子群组

获取此群组的可见子群组列表。未认证访问时，仅返回公共群组。

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

参数：

属性 类型 必需 描述
id integer/string 是 群组的 ID 或群组的 URL 编码路径
skip_groups array of integers 否 跳过传递的群组 ID
all_available boolean 否 当 true 时，返回所有可访问的群组。当 false 时，仅返回用户为成员的群组。对用户默认为 false，对管理员默认为 true。未认证请求始终返回所有公共群组。owned 和 min_access_level 属性优先。
search string 否 返回符合搜索条件的授权群组列表。仅搜索子群组短路径（不搜索完整路径）
order_by string 否 按 name、path 或 id 排列群组。默认是 name
sort string 否 按 asc 或 desc 排列群组。默认是 asc
statistics boolean 否 包含群组统计信息（仅管理员）
with_custom_attributes boolean 否 在响应中包含自定义属性（仅管理员）
owned boolean 否 限制为当前用户明确拥有的群组
min_access_level integer 否 限制为当前用户至少拥有此角色（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"
  }
]

极狐GitLab专业版或旗舰版的用户还会看到 wiki_access_level、experiment_features_enabled 等属性。

列出共享群组

获取被邀请的群组列表。未认证访问时，仅返回公共共享群组。

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

参数：

属性 类型 必需 描述
id integer/string 是 群组的 ID 或群组的 URL 编码路径
skip_groups array of integers 否 跳过指定的群组 ID
search string 否 返回符合搜索条件的授权群组列表
order_by string 否 按 name、path、id 或 similarity 排列群组。默认是 name
sort string 否 按 asc 或 desc 排列群组。默认是 asc
visibility string 否 限制为具有 public、internal 或 private 可见性的群组
min_access_level integer 否 限制为当前用户至少拥有指定角色（access_level）的群组
with_custom_attributes boolean 否 在响应中包含自定义属性（仅管理员） 
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 是 群组的 ID 或群组的 URL 编码路径
search string 否 返回符合搜索条件的授权群组列表
min_access_level integer 否 限制为当前用户至少拥有指定角色（access_level）的群组
relation array of strings 否 按关系（直接或继承）过滤群组
with_custom_attributes boolean 否 在响应中包含自定义属性（仅管理员） 
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"
  }
]

列出审计事件

{{< details >}}

  • 层级：专业版，旗舰版
  • 提供：JihuLab.com，私有化部署

{{< /details >}}

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

管理群组

创建群组

{{< alert type=”note” >}}

在极狐GitLab SaaS 上，您必须使用极狐GitLab UI 来创建没有父群组的群组。您不能使用 API 来实现。

{{< /alert >}}

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

POST /groups

参数：

属性 类型 必需 描述
name string 是 群组的名称。
path string 是 群组的路径。
auto_devops_enabled boolean 否 默认开启群组内所有项目的 Auto DevOps 流水线。
avatar mixed 否 群组头像的图片文件。
default_branch string 否 群组项目的默认分支名称。极狐GitLab 16.11 中引入。
default_branch_protection integer 否 极狐GitLab 17.0 中弃用。请使用 default_branch_protection_defaults。
default_branch_protection_defaults hash 否 极狐GitLab 17.0 中引入。可用选项请参见默认分支保护默认值的选项。
description string 否 群组的描述。
enabled_git_access_protocol string 否 启用的 Git 访问协议。允许值为：ssh、http 和 all，以允许两种协议。极狐GitLab 16.9 中引入。
emails_disabled boolean 否 （极狐GitLab 16.5 中弃用） 禁用电子邮件通知。请使用 emails_enabled。
emails_enabled boolean 否 启用电子邮件通知。
lfs_enabled boolean 否 为群组中的项目启用/禁用大文件存储（LFS）。
mentions_disabled boolean 否 禁止群组被提及的功能。
organization_id integer 否 群组的组织 ID。
parent_id integer 否 用于创建嵌套群组的父群组 ID。
project_creation_level string 否 决定开发人员是否可以在群组中创建项目。可以是 noone（没人）、maintainer（拥有维护者角色的用户）或 developer（拥有开发者或维护者角色的用户）。
request_access_enabled boolean 否 允许用户请求成员访问。
require_two_factor_authentication boolean 否 要求此群组中的所有用户设置双重身份验证。
share_with_group_lock boolean 否 防止在此群组内与另一个群组共享项目。
subgroup_creation_level string 否 允许创建子群组。可以是 owner（所有者）或 maintainer（拥有维护者角色的用户）。
two_factor_grace_period integer 否 强制执行双因素认证之前的时间（以小时为单位）。
visibility string 否 群组的可见性。可以是 private、internal 或 public。
membership_lock boolean 否 用户无法被添加到此群组中的项目中。仅限专业版和旗舰版。
extra_shared_runners_minutes_limit integer 否 仅限管理员设置。为此群组添加额外的计算分钟数。极狐GitLab私有化部署，专业版和旗舰版。
shared_runners_minutes_limit integer 否 仅限管理员设置。此群组的最大每月计算分钟数。可以是 nil（默认；继承系统默认值）、0（无限制）或 > 0。极狐GitLab私有化部署，专业版和旗舰版。
wiki_access_level string 否 维基访问级别。可以是 disabled、private 或 enabled。仅限专业版和旗舰版。
experiment_features_enabled boolean 否 为此群组启用实验功能。

default_branch_protection 的选项

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

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

default_branch_protection_defaults 的选项

{{< history >}}

  • 极狐GitLab 17.0 中引入。

{{< /history >}}

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

键 类型 描述
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

{{< details >}}

  • 层级：专业版，旗舰版
  • 提供：私有化部署

{{< /details >}}

同步群组与其关联的 LDAP 群组。仅对群组所有者和管理员可用。

POST /groups/:id/ldap_sync

参数：

  • id（必需）- 用户群组的 ID 或路径

更新群组属性

{{< history >}}

  • 极狐GitLab 15.3 中引入的 unique_project_download_limit、unique_project_download_limit_interval_in_seconds 和 unique_project_download_limit_allowlist 使用名为 limit_unique_project_downloads_per_namespace_user 的标志。默认情况下禁用。

{{< /history >}}

{{< alert type=”flag” >}}

在极狐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。

{{< /alert >}}

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

PUT /groups/:id
属性 类型 必需 描述
id integer 是 群组的 ID。
name string 否 群组的名称。
path string 否 群组的路径。
auto_devops_enabled boolean 否 默认开启群组内所有项目的 Auto DevOps 流水线。
avatar mixed 否 群组头像的图片文件。
default_branch string 否 群组项目的默认分支名称。极狐GitLab 16.11 中引入。
default_branch_protection integer 否 极狐GitLab 17.0 中弃用。请使用 default_branch_protection_defaults。
default_branch_protection_defaults hash 否 极狐GitLab 17.0 中引入。可用选项请参见默认分支保护默认值的选项。
description string 否 群组的描述。
enabled_git_access_protocol string 否 启用的 Git 访问协议。允许值为：ssh、http 和 all，以允许两种协议。极狐GitLab 16.9 中引入。
emails_disabled boolean 否 （极狐GitLab 16.5 中弃用） 禁用电子邮件通知。请使用 emails_enabled。
emails_enabled boolean 否 启用电子邮件通知。
lfs_enabled boolean 否 为群组中的项目启用/禁用大文件存储（LFS）。
mentions_disabled boolean 否 禁止群组被提及的功能。
prevent_sharing_groups_outside_hierarchy boolean 否 请参见防止群组共享到群组层次结构之外。此属性仅适用于顶级群组。
project_creation_level string 否 决定开发人员是否可以在群组中创建项目。可以是 noone（没人）、maintainer（拥有维护者角色的用户）或 developer（拥有开发者或维护者角色的用户）。
request_access_enabled boolean 否 允许用户请求成员访问。
require_two_factor_authentication boolean 否 要求此群组中的所有用户设置双重身份验证。
shared_runners_setting string 否 请参见共享 runners 设置的选项。为群组的子群组和项目启用或禁用实例 runners。
share_with_group_lock boolean 否 防止在此群组内与另一个群组共享项目。
subgroup_creation_level string 否 允许创建子群组。可以是 owner（所有者）或 maintainer（拥有维护者角色的用户）。
two_factor_grace_period integer 否 强制执行双因素认证之前的时间（以小时为单位）。
visibility string 否 群组的可见性级别。可以是 private、internal 或 public。
extra_shared_runners_minutes_limit integer 否 仅限管理员设置。为此群组添加额外的计算分钟数。极狐GitLab私有化部署，专业版和旗舰版。
file_template_project_id integer 否 用于加载自定义文件模板的项目 ID。仅限专业版和旗舰版。
membership_lock boolean 否 用户无法被添加到此群组中的项目中。仅限专业版和旗舰版。
prevent_forking_outside_group boolean 否 启用时，用户不能将此群组中的项目 fork 到外部命名空间。仅限专业版和旗舰版。
shared_runners_minutes_limit integer 否 仅限管理员设置。此群组的最大每月计算分钟数。可以是 nil（默认；继承系统默认值）、0（无限制）或 > 0。极狐GitLab私有化部署，专业版和旗舰版。
unique_project_download_limit integer 否 在指定时间内用户可以下载的唯一项目的最大数量，超过后将被禁止。仅适用于顶级群组。默认值：0，最大值：10,000。仅限旗舰版。
unique_project_download_limit_interval_in_seconds integer 否 用户在下载最大数量的项目之前可以下载的唯一项目的时间周期。仅适用于顶级群组。默认值：0，最大值：864,000 秒（10 天）。仅限旗舰版。
unique_project_download_limit_allowlist array of strings 否 从唯一项目下载限制中排除的用户名列表。仅适用于顶级群组。默认值：[]，最大值：100 个用户名。仅限旗舰版。
unique_project_download_limit_alertlist array of integers 否 超过唯一项目下载限制时收到电子邮件的用户 ID 列表。仅适用于顶级群组。默认值：[]，最大值：100 个用户 ID。极狐GitLab 15.9 中引入。仅限旗舰版。
auto_ban_user_on_excessive_projects_download boolean 否 启用时，当用户下载的唯一项目数量超过 unique_project_download_limit 和 unique_project_download_limit_interval_in_seconds 指定的最大数量时，用户将自动被禁止。极狐GitLab 15.4 中引入。仅限旗舰版。
ip_restriction_ranges string 否 用于限制群组访问的 IP 地址或子网掩码的逗号分隔列表。极狐GitLab 15.4 中引入。仅限专业版和旗舰版。
allowed_email_domains_list string 否 允许群组访问的电子邮件地址域的逗号分隔列表。极狐GitLab 专业版和旗舰版。
wiki_access_level string 否 维基访问级别。可以是 disabled、private 或 enabled。仅限专业版和旗舰版。
experiment_features_enabled boolean 否 为此群组启用实验功能。
math_rendering_limits_enabled boolean 否 指示是否对该群组使用数学渲染限制。
lock_math_rendering_limits_enabled boolean 否 指示是否对所有子群组锁定数学渲染限制。
max_artifacts_size integer 否 单个作业产物的最大文件大小（以 MB 为单位）。

{{< alert type=”note” >}}

响应中的 projects 和 shared_projects 属性已弃用，并计划在 API v5 中删除。要获取群组中所有项目的详细信息，请使用列出群组的项目或列出群组的共享项目端点。

{{< /alert >}}

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": [ // 已弃用，将在 API v5 中删除
    {
      "id": 9,
      "description": "foo",
      "default_branch": "main",
      "tag_list": [], // 已弃用，请使用 `topics`
      "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 属性仅对顶级群组存在。

极狐GitLab专业版或旗舰版的用户还会看到 wiki_access_level、experiment_features_enabled 等属性。

shared_runners_setting 的选项

shared_runners_setting 属性决定了实例 runners 是否对群组的子群组和项目启用。

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

群组成员

请参阅群组成员文档。

更新群组头像

更新群组头像。

下载群组头像

获取群组头像。如果群组是公开访问的，则可以在没有认证的情况下访问此端点。

GET /groups/:id/avatar
属性 类型 必需 描述
id integer/string 是 群组的 ID

示例：

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"

删除群组头像

{{< history >}}

  • 极狐GitLab 15.4 中引入。

{{< /history >}}

要删除群组头像，请使用 avatar 属性的空值。

示例请求：

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

删除群组

{{< history >}}

  • 极狐GitLab 15.3 中引入的立即删除子群组使用名为 immediate_delete_subgroup_api 的标志。默认情况下禁用。
  • 极狐GitLab 15.4 中启用了 JihuLab.com 和极狐GitLab 私有化部署上的立即删除子群组。
  • 极狐GitLab 15.4 中默认启用了立即删除子群组。
  • 极狐GitLab 15.9 中移除了立即删除子群组的 immediate_delete_subgroup_api 标志。

{{< /history >}}

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

此端点：

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

参数：

属性 类型 必需 描述
id integer/string 是 群组的 ID 或群组的 URL 编码路径
permanently_remove boolean/string 否 如果子群组被标记为删除，则立即删除子群组。极狐GitLab 15.4 中引入。仅限专业版和旗舰版。
full_path string 否 使用 permanently_remove 的子群组的完整路径。极狐GitLab 15.4 中引入。要查找子群组路径，请参阅群组详情。仅限专业版和旗舰版。

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

{{< alert type=”note” >}}

如果极狐GitLab.com 群组与订阅链接，则无法删除。要删除此类群组，请先将订阅链接到另一个群组。

{{< /alert >}}

恢复标记为删除的群组

{{< details >}}

  • 层级：专业版，旗舰版
  • 提供：JihuLab.com，私有化部署

{{< /details >}}

恢复标记为删除的群组。

POST /groups/:id/restore

参数：

属性 类型 必需 描述
id integer/string 是 群组的 ID 或群组的 URL 编码路径

撤销令牌

{{< history >}}

  • 极狐GitLab 17.2 中引入，使用名为 group_agnostic_token_revocation 的功能标志。默认禁用。
  • 极狐GitLab 17.3 中引入了用户的 feed 令牌撤销。

{{< /history >}}

{{< alert type=”flag” >}}

此功能的可用性由功能标志控制。有关更多信息，请参见历史记录。

{{< /alert >}}

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

必须满足以下条件：

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

稍后可能支持其他令牌类型。

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

如果成功，则返回 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 是 群组的 ID 或群组的 URL 编码路径
group_id integer 是 要与之共享的群组 ID
group_access integer 是 向群组授予的角色（access_level）
expires_at string 否 共享过期日期，格式为 ISO 8601：2016-09-26
member_role_id integer 否 要分配给被邀请群组的自定义角色的 ID

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

从另一个群组取消共享该群组。成功时返回 204，且无内容。

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

将项目转移到群组

将项目转移到群组命名空间。仅对实例管理员可用，虽然有一个替代的 API 端点可用，该端点不需要实例上的管理员访问权限。当项目的存储库中存在标记的软件包时，项目转移可能会失败。

POST /groups/:id/projects/:project_id

参数：

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

转移群组

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

  1. 拥有要转移的群组的 所有者 角色。
  2. 如果转移群组，则有权限在新的父群组中创建子群组。
  3. 如果将子群组变为顶级群组，则有创建顶级群组的权限。
POST /groups/:id/transfer

参数：

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

列出可用于群组转移的位置

{{< history >}}

  • 引入于极狐GitLab 15.4。

{{< /history >}}

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

GET /groups/:id/transfer_locations
属性 类型 是否必需 描述
id 整数或字符串 是 要转移的群组的 ID 或 URL 编码路径。
search 字符串 否 要搜索的群组名称。

示例请求：

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