极狐 GitLab Logo

群组 API

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

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

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

获取单个群组#

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

plaintext
GET /groups/:id

参数：

属性类型是否必需描述
idinteger/string是群组的 ID 或 URL 编码路径。
with_custom_attributesboolean否在响应中包含自定义属性（仅限管理员）。
with_projectsboolean否包含属于指定群组的项目的详细信息（默认为 true）。(已弃用，计划在 API v5 中移除。要获取群组中所有项目的详细信息，请使用列出群组的项目端点。)
响应中的 `projects` 和 `shared_projects` 属性已弃用，并且[计划在 API v5 中移除](https://jihulab.com/gitlab-cn/gitlab/-/issues/213797)。要获取群组中所有项目的详细信息，请使用 [列出群组的项目](#list-projects) 或 [列出群组的共享项目](#list-shared-projects) 端点。
shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4"

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

示例响应：

json
1{
2  "id": 4,
3  "name": "Twitter",
4  "path": "twitter",
5  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
6  "visibility": "public",
7  "avatar_url": null,
8  "web_url": "https://gitlab.example.com/groups/twitter",
9  "request_access_enabled": false,
10  "repository_storage": "default",
11  "full_name": "Twitter",
12  "full_path": "twitter",
13  "runners_token": "ba324ca7b1c77fc20bb9",
14  "file_template_project_id": 1,
15  "parent_id": null,
16  "enabled_git_access_protocol": "all",
17  "created_at": "2020-01-15T12:36:29.590Z",
18  "shared_with_groups": [
19    {
20      "group_id": 28,
21      "group_name": "H5bp",
22      "group_full_path": "h5bp",
23      "group_access_level": 20,
24      "expires_at": null
25    }
26  ],
27  "prevent_sharing_groups_outside_hierarchy": false,
28  "projects": [ // Deprecated and will be removed in API v5
29    {
30      "id": 7,
31      "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",
32      "default_branch": "main",
33      "tag_list": [], //deprecated, use `topics` instead
34      "topics": [],
35      "archived": false,
36      "visibility": "public",
37      "ssh_url_to_repo": "git@gitlab.example.com:twitter/typeahead-js.git",
38      "http_url_to_repo": "https://gitlab.example.com/twitter/typeahead-js.git",
39      "web_url": "https://gitlab.example.com/twitter/typeahead-js",
40      "name": "Typeahead.Js",
41      "name_with_namespace": "Twitter / Typeahead.Js",
42      "path": "typeahead-js",
43      "path_with_namespace": "twitter/typeahead-js",
44      "issues_enabled": true,
45      "merge_requests_enabled": true,
46      "wiki_enabled": true,
47      "jobs_enabled": true,
48      "snippets_enabled": false,
49      "container_registry_enabled": true,
50      "created_at": "2016-06-17T07:47:25.578Z",
51      "last_activity_at": "2016-06-17T07:47:25.881Z",
52      "shared_runners_enabled": true,
53      "creator_id": 1,
54      "namespace": {
55        "id": 4,
56        "name": "Twitter",
57        "path": "twitter",
58        "kind": "group"
59      },
60      "avatar_url": null,
61      "star_count": 0,
62      "forks_count": 0,
63      "open_issues_count": 3,
64      "public_jobs": true,
65      "shared_with_groups": [],
66      "request_access_enabled": false
67    },
68    {
69      "id": 6,
70      "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.",
71      "default_branch": "main",
72      "tag_list": [], //deprecated, use `topics` instead
73      "topics": [],
74      "archived": false,
75      "visibility": "internal",
76      "ssh_url_to_repo": "git@gitlab.example.com:twitter/flight.git",
77      "http_url_to_repo": "https://gitlab.example.com/twitter/flight.git",
78      "web_url": "https://gitlab.example.com/twitter/flight",
79      "name": "Flight",
80      "name_with_namespace": "Twitter / Flight",
81      "path": "flight",
82      "path_with_namespace": "twitter/flight",
83      "issues_enabled": true,
84      "merge_requests_enabled": true,
85      "wiki_enabled": true,
86      "jobs_enabled": true,
87      "snippets_enabled": false,
88      "container_registry_enabled": true,
89      "created_at": "2016-06-17T07:47:24.661Z",
90      "last_activity_at": "2016-06-17T07:47:24.838Z",
91      "shared_runners_enabled": true,
92      "creator_id": 1,
93      "namespace": {
94        "id": 4,
95        "name": "Twitter",
96        "path": "twitter",
97        "kind": "group"
98      },
99      "avatar_url": null,
100      "star_count": 0,
101      "forks_count": 0,
102      "open_issues_count": 8,
103      "public_jobs": true,
104      "shared_with_groups": [],
105      "request_access_enabled": false
106    }
107  ],
108  "shared_projects": [ // Deprecated and will be removed in API v5
109    {
110      "id": 8,
111      "description": "Velit eveniet provident fugiat saepe eligendi autem.",
112      "default_branch": "main",
113      "tag_list": [], //deprecated, use `topics` instead
114      "topics": [],
115      "archived": false,
116      "visibility": "private",
117      "ssh_url_to_repo": "git@gitlab.example.com:h5bp/html5-boilerplate.git",
118      "http_url_to_repo": "https://gitlab.example.com/h5bp/html5-boilerplate.git",
119      "web_url": "https://gitlab.example.com/h5bp/html5-boilerplate",
120      "name": "Html5 Boilerplate",
121      "name_with_namespace": "H5bp / Html5 Boilerplate",
122      "path": "html5-boilerplate",
123      "path_with_namespace": "h5bp/html5-boilerplate",
124      "issues_enabled": true,
125      "merge_requests_enabled": true,
126      "wiki_enabled": true,
127      "jobs_enabled": true,
128      "snippets_enabled": false,
129      "container_registry_enabled": true,
130      "created_at": "2016-06-17T07:47:27.089Z",
131      "last_activity_at": "2016-06-17T07:47:27.310Z",
132      "shared_runners_enabled": true,
133      "creator_id": 1,
134      "namespace": {
135        "id": 5,
136        "name": "H5bp",
137        "path": "h5bp",
138        "kind": "group"
139      },
140      "avatar_url": null,
141      "star_count": 0,
142      "forks_count": 0,
143      "open_issues_count": 4,
144      "public_jobs": true,
145      "shared_with_groups": [
146        {
147          "group_id": 4,
148          "group_name": "Twitter",
149          "group_full_path": "twitter",
150          "group_access_level": 30,
151          "expires_at": null
152        },
153        {
154          "group_id": 3,
155          "group_name": "Gitlab Org",
156          "group_full_path": "gitlab-org",
157          "group_access_level": 10,
158          "expires_at": "2018-08-14"
159        }
160      ]
161    }
162  ],
163  "ip_restriction_ranges": null,
164  "math_rendering_limits_enabled": true,
165  "lock_math_rendering_limits_enabled": false
166}

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

额外的响应属性：

json
1{
2  "id": 4,
3  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
4  "shared_runners_minutes_limit": 133,
5  "extra_shared_runners_minutes_limit": 133,
6  "marked_for_deletion_on": "2020-04-03",
7  "membership_lock": false,
8  "wiki_access_level": "disabled",
9  "duo_features_enabled": true,
10  "lock_duo_features_enabled": false,
11  "duo_availability": "default_on",
12  "experiment_features_enabled": false,
13  ...
14}

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

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

示例响应：

json
1{
2  "id": 4,
3  "name": "Twitter",
4  "path": "twitter",
5  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
6  "visibility": "public",
7  "avatar_url": null,
8  "web_url": "https://gitlab.example.com/groups/twitter",
9  "request_access_enabled": false,
10  "repository_storage": "default",
11  "full_name": "Twitter",
12  "full_path": "twitter",
13  "file_template_project_id": 1,
14  "parent_id": null
15}

列出群组#

列出群组。

列出所有群组#

获取经过身份验证用户可见的群组列表。在无需身份验证的情况下访问时，仅返回公共群组。

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

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

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

参数：

属性类型是否必需描述
skip_groupsarray of integers否跳过传递的群组 ID
all_availableboolean否当为 true 时，返回所有可访问的群组。当为 false 时，仅返回用户是成员的群组。对于用户默认为 false，对于管理员默认为 true。未经身份验证的请求始终返回所有公共群组。owned 和 min_access_level 属性优先。
searchstring否返回符合搜索条件的授权群组列表
order_bystring否按 name、path、id 或 similarity 排序群组。默认是 name
sortstring否按 asc 或 desc 顺序排序群组。默认是 asc
statisticsboolean否包含群组统计信息（仅限管理员）。
*注意：*对于顶级群组，响应返回 UI 中显示的完整 root_storage_statistics 数据。在极狐GitLab 17.4 中引入。
visibilitystring否限制为具有 public、internal 或 private 可见性的群组。
with_custom_attributesboolean否在响应中包含自定义属性（仅限管理员）
ownedboolean否限制为当前用户显式拥有的群组
min_access_levelinteger否限制为当前用户至少具有此角色（access_level）的群组
top_level_onlyboolean否仅限顶级群组，排除所有子群组
repository_storagestring否按群组使用的存储库存储进行过滤_（仅限管理员）_。在极狐GitLab 16.3 中引入。仅限专业版和旗舰版。
marked_for_deletion_ondate否按群组标记为删除的日期进行过滤。在极狐GitLab 17.1 中引入。仅限专业版和旗舰版。
plaintext
GET /groups
json
1[
2  {
3    "id": 1,
4    "name": "Foobar Group",
5    "path": "foo-bar",
6    "description": "An interesting group",
7    "visibility": "public",
8    "share_with_group_lock": false,
9    "require_two_factor_authentication": false,
10    "two_factor_grace_period": 48,
11    "project_creation_level": "developer",
12    "auto_devops_enabled": null,
13    "subgroup_creation_level": "owner",
14    "emails_disabled": null,
15    "emails_enabled": null,
16    "mentions_disabled": null,
17    "lfs_enabled": true,
18    "default_branch": null,
19    "default_branch_protection": 2,
20    "default_branch_protection_defaults": {
21      "allowed_to_push": [
22          {
23              "access_level": 40
24          }
25      ],
26      "allow_force_push": false,
27      "allowed_to_merge": [
28          {
29              "access_level": 40
30          }
31      ]
32    },
33    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
34    "web_url": "http://localhost:3000/groups/foo-bar",
35    "request_access_enabled": false,
36    "repository_storage": "default",
37    "full_name": "Foobar Group",
38    "full_path": "foo-bar",
39    "file_template_project_id": 1,
40    "parent_id": null,
41    "created_at": "2020-01-15T12:36:29.590Z",
42    "ip_restriction_ranges": null
43  }
44]

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

plaintext
GET /groups?statistics=true

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

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

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

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

json
1[
2  {
3    "id": 1,
4    "name": "Foobar Group",
5    "path": "foo-bar",
6    "description": "An interesting group",
7    "visibility": "public",
8    "share_with_group_lock": false,
9    "require_two_factor_authentication": false,
10    "two_factor_grace_period": 48,
11    "project_creation_level": "developer",
12    "auto_devops_enabled": null,
13    "subgroup_creation_level": "owner",
14    "emails_disabled": null,
15    "emails_enabled": null,
16    "mentions_disabled": null,
17    "lfs_enabled": true,
18    "default_branch": null,
19    "default_branch_protection": 2,
20    "default_branch_protection_defaults": {
21      "allowed_to_push": [
22          {
23              "access_level": 40
24          }
25      ],
26      "allow_force_push": false,
27      "allowed_to_merge": [
28          {
29              "access_level": 40
30          }
31      ]
32    },
33    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
34    "web_url": "http://localhost:3000/groups/foo-bar",
35    "request_access_enabled": false,
36    "repository_storage": "default",
37    "full_name": "Foobar Group",
38    "full_path": "foo-bar",
39    "file_template_project_id": 1,
40    "parent_id": null,
41    "created_at": "2020-01-15T12:36:29.590Z",
42    "statistics": {
43      "storage_size": 363,
44      "repository_size": 33,
45      "wiki_size": 100,
46      "lfs_objects_size": 123,
47      "job_artifacts_size": 57,
48      "pipeline_artifacts_size": 0,
49      "packages_size": 0,
50      "snippets_size": 50,
51      "uploads_size": 0
52    },
53    "root_storage_statistics": {
54      "build_artifacts_size": 0,
55      "container_registry_size": 0,
56      "container_registry_size_is_estimated": false,
57      "dependency_proxy_size": 0,
58      "lfs_objects_size": 0,
59      "packages_size": 0,
60      "pipeline_artifacts_size": 0,
61      "repository_size": 0,
62      "snippets_size": 0,
63      "storage_size": 0,
64      "uploads_size": 0,
65      "wiki_size": 0
66  },
67    "wiki_access_level": "private",
68    "duo_features_enabled": true,
69    "lock_duo_features_enabled": false,
70    "duo_availability": "default_on",
71    "experiment_features_enabled": false,
72  }
73]

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

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

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

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

群组中的命名空间#

默认情况下，群组一次只能获取 20 个命名空间，因为 API 结果是分页的。

要获取更多（最多 100 个），请将以下内容作为参数传递给 API 调用：

plaintext
/groups?per_page=100

要切换页面，请添加：

plaintext
/groups?per_page=100&page=2

搜索群组#

获取名称或路径中与您的字符串匹配的所有群组。

plaintext
GET /groups?search=foobar
json
1[
2  {
3    "id": 1,
4    "name": "Foobar Group",
5    "path": "foo-bar",
6    "description": "An interesting group"
7  }
8]

列出群组详情#

列出群组的详细信息。

列出项目#

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

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

plaintext
GET /groups/:id/projects

参数：

属性类型是否必需描述
idinteger/string是群组的 ID 或 URL 编码路径
archivedboolean否按归档状态限制
visibilitystring否按可见性 public、internal 或 private 限制
order_bystring否按 id、name、path、created_at、updated_at、similarity 1、star_count 或 last_activity_at 字段排序项目。默认是 created_at
sortstring否按 asc 或 desc 顺序排序项目。默认是 desc
searchstring否返回符合搜索条件的授权项目列表
simpleboolean否仅返回每个项目的有限字段。在无需身份验证的情况下，仅返回简单字段。
ownedboolean否按当前用户拥有的项目进行限制
starredboolean否按当前用户加星的项目进行限制
topicstring否返回与主题匹配的项目
with_issues_enabledboolean否按启用议题功能的项目进行限制。默认是 false
with_merge_requests_enabledboolean否按启用合并请求功能的项目进行限制。默认是 false
with_sharedboolean否包含共享给此群组的项目。默认是 true
include_subgroupsboolean否包含此群组的子群组中的项目。默认是 false
min_access_levelinteger否限制为当前用户至少具有此角色（access_level）的项目
with_custom_attributesboolean否在响应中包含自定义属性（仅限管理员）
with_security_reportsboolean否仅返回在其任何构建中存在安全报告产物的项目。这意味着“启用了安全报告的项目”。默认是 false。仅限旗舰版。

脚注：

  1. 按 search URL 参数计算的相似度得分对结果进行排序。 使用 order_by=similarity 时，sort 参数将被忽略。 如果未提供 search 参数，API 将按 name 排序返回项目。

示例响应：

json
1[
2  {
3    "id": 9,
4    "description": "foo",
5    "default_branch": "main",
6    "tag_list": [], //deprecated, use `topics` instead
7    "topics": [],
8    "archived": false,
9    "visibility": "internal",
10    "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
11    "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
12    "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
13    "name": "Html5 Boilerplate",
14    "name_with_namespace": "Experimental / Html5 Boilerplate",
15    "path": "html5-boilerplate",
16    "path_with_namespace": "h5bp/html5-boilerplate",
17    "issues_enabled": true,
18    "merge_requests_enabled": true,
19    "wiki_enabled": true,
20    "jobs_enabled": true,
21    "snippets_enabled": true,
22    "created_at": "2016-04-05T21:40:50.169Z",
23    "last_activity_at": "2016-04-06T16:52:08.432Z",
24    "shared_runners_enabled": true,
25    "creator_id": 1,
26    "namespace": {
27      "id": 5,
28      "name": "Experimental",
29      "path": "h5bp",
30      "kind": "group"
31    },
32    "avatar_url": null,
33    "star_count": 1,
34    "forks_count": 0,
35    "open_issues_count": 3,
36    "public_jobs": true,
37    "shared_with_groups": [],
38    "request_access_enabled": false
39  }
40]
为了区分群组中的项目和共享给群组的项目，可以使用 `namespace` 属性。当项目已共享给群组时，其 `namespace` 与请求所在群组不同。

列出共享项目#

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

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

plaintext
GET /groups/:id/projects/shared

参数：

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

示例响应：

json
1[
2   {
3      "id":8,
4      "description":"Shared project for Html5 Boilerplate",
5      "name":"Html5 Boilerplate",
6      "name_with_namespace":"H5bp / Html5 Boilerplate",
7      "path":"html5-boilerplate",
8      "path_with_namespace":"h5bp/html5-boilerplate",
9      "created_at":"2020-04-27T06:13:22.642Z",
10      "default_branch":"main",
11      "tag_list":[], //deprecated, use `topics` instead
12      "topics":[],
13      "ssh_url_to_repo":"ssh://git@gitlab.com/h5bp/html5-boilerplate.git",
14      "http_url_to_repo":"https://gitlab.com/h5bp/html5-boilerplate.git",
15      "web_url":"https://gitlab.com/h5bp/html5-boilerplate",
16      "readme_url":"https://gitlab.com/h5bp/html5-boilerplate/-/blob/main/README.md",
17      "avatar_url":null,
18      "star_count":0,
19      "forks_count":4,
20      "last_activity_at":"2020-04-27T06:13:22.642Z",
21      "namespace":{
22         "id":28,
23         "name":"H5bp",
24         "path":"h5bp",
25         "kind":"group",
26         "full_path":"h5bp",
27         "parent_id":null,
28         "avatar_url":null,
29         "web_url":"https://gitlab.com/groups/h5bp"
30      },
31      "_links":{
32         "self":"https://gitlab.com/api/v4/projects/8",
33         "issues":"https://gitlab.com/api/v4/projects/8/issues",
34         "merge_requests":"https://gitlab.com/api/v4/projects/8/merge_requests",
35         "repo_branches":"https://gitlab.com/api/v4/projects/8/repository/branches",
36         "labels":"https://gitlab.com/api/v4/projects/8/labels",
37         "events":"https://gitlab.com/api/v4/projects/8/events",
38         "members":"https://gitlab.com/api/v4/projects/8/members"
39      },
40      "empty_repo":false,
41      "archived":false,
42      "visibility":"public",
43      "resolve_outdated_diff_discussions":false,
44      "container_registry_enabled":true,
45      "container_expiration_policy":{
46         "cadence":"7d",
47         "enabled":true,
48         "keep_n":null,
49         "older_than":null,
50         "name_regex":null,
51         "name_regex_keep":null,
52         "next_run_at":"2020-05-04T06:13:22.654Z"
53      },
54      "issues_enabled":true,
55      "merge_requests_enabled":true,
56      "wiki_enabled":true,
57      "jobs_enabled":true,
58      "snippets_enabled":true,
59      "can_create_merge_request_in":true,
60      "issues_access_level":"enabled",
61      "repository_access_level":"enabled",
62      "merge_requests_access_level":"enabled",
63      "forking_access_level":"enabled",
64      "wiki_access_level":"enabled",
65      "builds_access_level":"enabled",
66      "snippets_access_level":"enabled",
67      "pages_access_level":"enabled",
68      "security_and_compliance_access_level":"enabled",
69      "emails_disabled":null,
70      "emails_enabled": null,
71      "shared_runners_enabled":true,
72      "lfs_enabled":true,
73      "creator_id":1,
74      "import_status":"failed",
75      "open_issues_count":10,
76      "ci_default_git_depth":50,
77      "ci_forward_deployment_enabled":true,
78      "ci_forward_deployment_rollback_allowed": true,
79      "ci_allow_fork_pipelines_to_run_in_parent_project":true,
80      "public_jobs":true,
81      "build_timeout":3600,
82      "auto_cancel_pending_pipelines":"enabled",
83      "ci_config_path":null,
84      "shared_with_groups":[
85         {
86            "group_id":24,
87            "group_name":"Commit451",
88            "group_full_path":"Commit451",
89            "group_access_level":30,
90            "expires_at":null
91         }
92      ],
93      "only_allow_merge_if_pipeline_succeeds":false,
94      "request_access_enabled":true,
95      "only_allow_merge_if_all_discussions_are_resolved":false,
96      "remove_source_branch_after_merge":true,
97      "printing_merge_request_link_enabled":true,
98      "merge_method":"merge",
99      "suggestion_commit_message":null,
100      "auto_devops_enabled":true,
101      "auto_devops_deploy_strategy":"continuous",
102      "autoclose_referenced_issues":true,
103      "repository_storage":"default"
104   }
105]

列出配置的用户#

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

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

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

plaintext
GET /groups/:id/provisioned_users

参数：

属性类型是否必需描述
idinteger/string是ID 或 URL 编码路径
usernamestring否返回具有特定用户名的单个用户
searchstring否按名称、电子邮件、用户名搜索用户
activeboolean否仅返回活动用户
blockedboolean否仅返回被阻止的用户
created_afterdatetime否返回在指定时间之后创建的用户
created_beforedatetime否返回在指定时间之前创建的用户

示例响应：

json
1[
2  {
3    "id": 66,
4    "username": "user22",
5    "name": "John Doe22",
6    "state": "active",
7    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
8    "web_url": "http://my.gitlab.com/user22",
9    "created_at": "2021-09-10T12:48:22.381Z",
10    "bio": "",
11    "location": null,
12    "public_email": "",
13    "skype": "",
14    "linkedin": "",
15    "twitter": "",
16    "website_url": "",
17    "organization": null,
18    "job_title": "",
19    "pronouns": null,
20    "bot": false,
21    "work_information": null,
22    "followers": 0,
23    "following": 0,
24    "local_time": null,
25    "last_sign_in_at": null,
26    "confirmed_at": "2021-09-10T12:48:22.330Z",
27    "last_activity_on": null,
28    "email": "user22@example.org",
29    "theme_id": 1,
30    "color_scheme_id": 1,
31    "projects_limit": 100000,
32    "current_sign_in_at": null,
33    "identities": [ ],
34    "can_create_group": true,
35    "can_create_project": true,
36    "two_factor_enabled": false,
37    "external": false,
38    "private_profile": false,
39    "commit_email": "user22@example.org",
40    "shared_runners_minutes_limit": null,
41    "extra_shared_runners_minutes_limit": null
42  },
43  ...
44]

列出用户#

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

获取群组的用户列表。此端点返回与顶级群组相关的用户，无论他们当前的成员身份如何。例如，与群组连接了 SAML 身份的用户，或由群组或子群组创建的服务帐户。

此端点是一个试验，可能会在没有通知的情况下更改或删除。

需要群组的所有者角色。

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

参数：

属性类型是否必需描述
idinteger/string是ID 或 URL 编码路径。
include_saml_usersboolean是 (见描述)包含具有 SAML 身份的用户。此值或 include_service_accounts 必须为 true。
include_service_accountsboolean是 (见描述)包含服务帐户用户。此值或 include_saml_users 必须为 true。
searchstring否按名称、电子邮件、用户名搜索用户。

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

示例响应：

json
1[
2  {
3    "id": 66,
4    "username": "user22",
5    "name": "John Doe22",
6    "state": "active",
7    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
8    "web_url": "http://my.gitlab.com/user22",
9    "created_at": "2021-09-10T12:48:22.381Z",
10    "bio": "",
11    "location": null,
12    "public_email": "",
13    "skype": "",
14    "linkedin": "",
15    "twitter": "",
16    "website_url": "",
17    "organization": null,
18    "job_title": "",
19    "pronouns": null,
20    "bot": false,
21    "work_information": null,
22    "followers": 0,
23    "following": 0,
24    "local_time": null,
25    "last_sign_in_at": null,
26    "confirmed_at": "2021-09-10T12:48:22.330Z",
27    "last_activity_on": null,
28    "email": "user22@example.org",
29    "theme_id": 1,
30    "color_scheme_id": 1,
31    "projects_limit": 100000,
32    "current_sign_in_at": null,
33    "identities": [ ],
34    "can_create_group": true,
35    "can_create_project": true,
36    "two_factor_enabled": false,
37    "external": false,
38    "private_profile": false,
39    "commit_email": "user22@example.org",
40    "shared_runners_minutes_limit": null,
41    "extra_shared_runners_minutes_limit": null
42  },
43  ...
44]

列出子群组#

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

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

如果您请求此列表作为：

  • 未经身份验证的用户，响应仅返回公共群组。
  • 经身份验证的用户，响应仅返回您是成员的群组，不包括公共群组。

参数：

属性类型是否必需描述
idinteger/string是直接父群组的 ID 或 URL 编码路径
skip_groupsarray of integers否跳过传递的群组 ID
all_availableboolean否显示您可以访问的所有群组（对于经过身份验证的用户默认为 false，对于管理员默认为 true）；属性 owned 和 min_access_level 优先
searchstring否返回符合搜索条件的授权群组列表。仅搜索子群组短路径（不搜索完整路径）
order_bystring否按 name、path 或 id 排序群组。默认是 name
sortstring否按 asc 或 desc 顺序排序群组。默认是 asc
statisticsboolean否包含群组统计信息（仅限管理员）
with_custom_attributesboolean否在响应中包含自定义属性（仅限管理员）
ownedboolean否限制为当前用户显式拥有的群组
min_access_levelinteger否限制为当前用户至少具有此角色（access_level）的群组
all_availableboolean否当为 true 时，返回所有可访问的群组。当为 false 时，仅返回用户是成员的群组。对于用户默认为 false，对于管理员默认为 true。未经身份验证的请求始终返回所有公共群组。owned 和 min_access_level 属性优先。
plaintext
GET /groups/:id/subgroups
json
1[
2  {
3    "id": 1,
4    "name": "Foobar Group",
5    "path": "foo-bar",
6    "description": "An interesting group",
7    "visibility": "public",
8    "share_with_group_lock": false,
9    "require_two_factor_authentication": false,
10    "two_factor_grace_period": 48,
11    "project_creation_level": "developer",
12    "auto_devops_enabled": null,
13    "subgroup_creation_level": "owner",
14    "emails_disabled": null,
15    "emails_enabled": null,
16    "mentions_disabled": null,
17    "lfs_enabled": true,
18    "default_branch": null,
19    "default_branch_protection": 2,
20    "default_branch_protection_defaults": {
21      "allowed_to_push": [
22          {
23              "access_level": 40
24          }
25      ],
26      "allow_force_push": false,
27      "allowed_to_merge": [
28          {
29              "access_level": 40
30          }
31      ]
32    },
33    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/foo.jpg",
34    "web_url": "http://gitlab.example.com/groups/foo-bar",
35    "request_access_enabled": false,
36    "repository_storage": "default",
37    "full_name": "Foobar Group",
38    "full_path": "foo-bar",
39    "file_template_project_id": 1,
40    "parent_id": 123,
41    "created_at": "2020-01-15T12:36:29.590Z"
42  }
43]

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

列出子群组#

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

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

参数：

属性类型必需描述
idinteger/string是群组的 ID 或群组的 URL 编码路径
skip_groupsarray of integers否跳过传递的群组 ID
all_availableboolean否当 true 时，返回所有可访问的群组。当 false 时，仅返回用户为成员的群组。对用户默认为 false，对管理员默认为 true。未认证请求始终返回所有公共群组。owned 和 min_access_level 属性优先。
searchstring否返回符合搜索条件的授权群组列表。仅搜索子群组短路径（不搜索完整路径）
order_bystring否按 name、path 或 id 排列群组。默认是 name
sortstring否按 asc 或 desc 排列群组。默认是 asc
statisticsboolean否包含群组统计信息（仅管理员）
with_custom_attributesboolean否在响应中包含自定义属性（仅管理员）
ownedboolean否限制为当前用户明确拥有的群组
min_access_levelinteger否限制为当前用户至少拥有此角色（access_level）的群组
plaintext
GET /groups/:id/descendant_groups
json
1[
2  {
3    "id": 2,
4    "name": "Bar Group",
5    "path": "bar",
6    "description": "A subgroup of Foo Group",
7    "visibility": "public",
8    "share_with_group_lock": false,
9    "require_two_factor_authentication": false,
10    "two_factor_grace_period": 48,
11    "project_creation_level": "developer",
12    "auto_devops_enabled": null,
13    "subgroup_creation_level": "owner",
14    "emails_disabled": null,
15    "emails_enabled": null,
16    "mentions_disabled": null,
17    "lfs_enabled": true,
18    "default_branch": null,
19    "default_branch_protection": 2,
20    "default_branch_protection_defaults": {
21      "allowed_to_push": [
22          {
23              "access_level": 40
24          }
25      ],
26      "allow_force_push": false,
27      "allowed_to_merge": [
28          {
29              "access_level": 40
30          }
31      ]
32    },
33    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg",
34    "web_url": "http://gitlab.example.com/groups/foo/bar",
35    "request_access_enabled": false,
36    "full_name": "Bar Group",
37    "full_path": "foo/bar",
38    "file_template_project_id": 1,
39    "parent_id": 123,
40    "created_at": "2020-01-15T12:36:29.590Z"
41  },
42  {
43    "id": 3,
44    "name": "Baz Group",
45    "path": "baz",
46    "description": "A subgroup of Bar Group",
47    "visibility": "public",
48    "share_with_group_lock": false,
49    "require_two_factor_authentication": false,
50    "two_factor_grace_period": 48,
51    "project_creation_level": "developer",
52    "auto_devops_enabled": null,
53    "subgroup_creation_level": "owner",
54    "emails_disabled": null,
55    "emails_enabled": null,
56    "mentions_disabled": null,
57    "lfs_enabled": true,
58    "default_branch": null,
59    "default_branch_protection": 2,
60    "default_branch_protection_defaults": {
61      "allowed_to_push": [
62          {
63              "access_level": 40
64          }
65      ],
66      "allow_force_push": false,
67      "allowed_to_merge": [
68          {
69              "access_level": 40
70          }
71      ]
72    },
73    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/baz.jpg",
74    "web_url": "http://gitlab.example.com/groups/foo/bar/baz",
75    "request_access_enabled": false,
76    "full_name": "Baz Group",
77    "full_path": "foo/bar/baz",
78    "file_template_project_id": 1,
79    "parent_id": 123,
80    "created_at": "2020-01-15T12:36:29.590Z"
81  }
82]

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

列出共享群组#

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

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

参数：

属性类型必需描述
idinteger/string是群组的 ID 或群组的 URL 编码路径
skip_groupsarray of integers否跳过指定的群组 ID
searchstring否返回符合搜索条件的授权群组列表
order_bystring否按 name、path、id 或 similarity 排列群组。默认是 name
sortstring否按 asc 或 desc 排列群组。默认是 asc
visibilitystring否限制为具有 public、internal 或 private 可见性的群组
min_access_levelinteger否限制为当前用户至少拥有指定角色（access_level）的群组
with_custom_attributesboolean否在响应中包含自定义属性（仅管理员）
plaintext
GET /groups/:id/groups/shared

示例响应：

json
1[
2  {
3    "id": 101,
4    "web_url": "http://gitlab.example.com/groups/some_path",
5    "name": "group1",
6    "path": "some_path",
7    "description": "",
8    "visibility": "public",
9    "share_with_group_lock": "false",
10    "require_two_factor_authentication": "false",
11    "two_factor_grace_period": 48,
12    "project_creation_level": "maintainer",
13    "auto_devops_enabled": "nil",
14    "subgroup_creation_level": "maintainer",
15    "emails_disabled": "false",
16    "emails_enabled": "true",
17    "mentions_disabled": "nil",
18    "lfs_enabled": "true",
19    "math_rendering_limits_enabled": "true",
20    "lock_math_rendering_limits_enabled": "false",
21    "default_branch": "nil",
22    "default_branch_protection": 2,
23    "default_branch_protection_defaults": {
24        "allowed_to_push": [
25          {
26              "access_level": 30
27          }
28        ],
29        "allow_force_push": "true",
30        "allowed_to_merge": [
31          {
32              "access_level": 30
33          }
34        ],
35        "developer_can_initial_push": "false",
36        "code_owner_approval_required": "false"
37    },
38    "avatar_url": "http://gitlab.example.com/uploads/-/system/group/avatar/101/banana_sample.gif",
39    "request_access_enabled": "true",
40    "full_name": "group1",
41    "full_path": "some_path",
42    "created_at": "2024-06-06T09:39:30.056Z",
43    "parent_id": "nil",
44    "organization_id": 1,
45    "shared_runners_setting": "enabled",
46    "ldap_cn": "nil",
47    "ldap_access": "nil",
48    "wiki_access_level": "enabled"
49  }
50]

列出被邀请的群组#

获取给定群组中的被邀请群组列表。未认证访问时，仅返回公共被邀请群组。此端点的速率限制为每分钟每个用户（对于认证用户）或 IP（对于未认证用户）60 次请求。

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

参数：

属性类型必需描述
idinteger/string是群组的 ID 或群组的 URL 编码路径
searchstring否返回符合搜索条件的授权群组列表
min_access_levelinteger否限制为当前用户至少拥有指定角色（access_level）的群组
relationarray of strings否按关系（直接或继承）过滤群组
with_custom_attributesboolean否在响应中包含自定义属性（仅管理员）
plaintext
GET /groups/:id/invited_groups

示例响应：

json
1[
2  {
3    "id": 33,
4    "web_url": "http://gitlab.example.com/groups/flightjs",
5    "name": "Flightjs",
6    "path": "flightjs",
7    "description": "Illo dolorum tempore eligendi minima ducimus provident.",
8    "visibility": "public",
9    "share_with_group_lock": false,
10    "require_two_factor_authentication": false,
11    "two_factor_grace_period": 48,
12    "project_creation_level": "developer",
13    "auto_devops_enabled": null,
14    "subgroup_creation_level": "maintainer",
15    "emails_disabled": false,
16    "emails_enabled": true,
17    "mentions_disabled": null,
18    "lfs_enabled": true,
19    "math_rendering_limits_enabled": true,
20    "lock_math_rendering_limits_enabled": false,
21    "default_branch": null,
22    "default_branch_protection": 2,
23    "default_branch_protection_defaults": {
24      "allowed_to_push": [
25        {
26          "access_level": 40
27        }
28      ],
29      "allow_force_push": false,
30      "allowed_to_merge": [
31        {
32          "access_level": 40
33        }
34      ],
35      "developer_can_initial_push": false
36    },
37    "avatar_url": null,
38    "request_access_enabled": true,
39    "full_name": "Flightjs",
40    "full_path": "flightjs",
41    "created_at": "2024-07-09T10:31:08.307Z",
42    "parent_id": null,
43    "organization_id": 1,
44    "shared_runners_setting": "enabled",
45    "ldap_cn": null,
46    "ldap_access": null,
47    "wiki_access_level": "enabled"
48  }
49]

列出审计事件#

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

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

管理群组#

创建群组#

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

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

plaintext
POST /groups

参数：

属性类型必需描述
namestring是群组的名称。
pathstring是群组的路径。
auto_devops_enabledboolean否默认开启群组内所有项目的 Auto DevOps 流水线。
avatarmixed否群组头像的图片文件。
default_branchstring否群组项目的默认分支名称。极狐GitLab 16.11 中引入。
default_branch_protectioninteger否极狐GitLab 17.0 中弃用。请使用 default_branch_protection_defaults。
default_branch_protection_defaultshash否极狐GitLab 17.0 中引入。可用选项请参见默认分支保护默认值的选项。
descriptionstring否群组的描述。
enabled_git_access_protocolstring否启用的 Git 访问协议。允许值为：ssh、http 和 all，以允许两种协议。极狐GitLab 16.9 中引入。
emails_disabledboolean否（极狐GitLab 16.5 中弃用） 禁用电子邮件通知。请使用 emails_enabled。
emails_enabledboolean否启用电子邮件通知。
lfs_enabledboolean否为群组中的项目启用/禁用大文件存储（LFS）。
mentions_disabledboolean否禁止群组被提及的功能。
organization_idinteger否群组的组织 ID。
parent_idinteger否用于创建嵌套群组的父群组 ID。
project_creation_levelstring否决定开发人员是否可以在群组中创建项目。可以是 noone（没人）、maintainer（拥有维护者角色的用户）或 developer（拥有开发者或维护者角色的用户）。
request_access_enabledboolean否允许用户请求成员访问。
require_two_factor_authenticationboolean否要求此群组中的所有用户设置双重身份验证。
share_with_group_lockboolean否防止在此群组内与另一个群组共享项目。
subgroup_creation_levelstring否允许创建子群组。可以是 owner（所有者）或 maintainer（拥有维护者角色的用户）。
two_factor_grace_periodinteger否强制执行双因素认证之前的时间（以小时为单位）。
visibilitystring否群组的可见性。可以是 private、internal 或 public。
membership_lockboolean否用户无法被添加到此群组中的项目中。仅限专业版和旗舰版。
extra_shared_runners_minutes_limitinteger否仅限管理员设置。为此群组添加额外的计算分钟数。极狐GitLab私有化部署，专业版和旗舰版。
shared_runners_minutes_limitinteger否仅限管理员设置。此群组的最大每月计算分钟数。可以是 nil（默认；继承系统默认值）、0（无限制）或 > 0。极狐GitLab私有化部署，专业版和旗舰版。
wiki_access_levelstring否维基访问级别。可以是 disabled、private 或 enabled。仅限专业版和旗舰版。
experiment_features_enabledboolean否为此群组启用实验功能。

default_branch_protection 的选项#

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

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

default_branch_protection_defaults 的选项#

History
    • 极狐GitLab 17.0 中引入。

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

键类型描述
allowed_to_pusharray一个允许推送的访问级别数组。支持开发者 (30) 或维护者 (40)。
allow_force_pushboolean允许具有推送权限的所有用户强制推送。
allowed_to_mergearray一个允许合并的访问级别数组。支持开发者 (30) 或维护者 (40)。
developer_can_initial_pushboolean允许开发人员初始推送。

创建子群组#

这类似于创建新群组。您需要从列出群组调用中获取 parent_id。然后您可以输入所需的：

  • subgroup_path
  • subgroup_name
shell
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 群组。仅对群组所有者和管理员可用。

plaintext
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 的标志。默认情况下禁用。
在极狐GitLab 私有化部署上，默认情况下 `unique_project_download_limit`、`unique_project_download_limit_interval_in_seconds`、`unique_project_download_limit_allowlist` 和 `auto_ban_user_on_excessive_projects_download` 是不可用的。 要使它们可用，管理员可以[启用功能标志](../administration/feature_flags.md)名为 `limit_unique_project_downloads_per_namespace_user`。

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

plaintext
PUT /groups/:id
属性类型必需描述
idinteger是群组的 ID。
namestring否群组的名称。
pathstring否群组的路径。
auto_devops_enabledboolean否默认开启群组内所有项目的 Auto DevOps 流水线。
avatarmixed否群组头像的图片文件。
default_branchstring否群组项目的默认分支名称。极狐GitLab 16.11 中引入。
default_branch_protectioninteger否极狐GitLab 17.0 中弃用。请使用 default_branch_protection_defaults。
default_branch_protection_defaultshash否极狐GitLab 17.0 中引入。可用选项请参见默认分支保护默认值的选项。
descriptionstring否群组的描述。
enabled_git_access_protocolstring否启用的 Git 访问协议。允许值为：ssh、http 和 all，以允许两种协议。极狐GitLab 16.9 中引入。
emails_disabledboolean否（极狐GitLab 16.5 中弃用） 禁用电子邮件通知。请使用 emails_enabled。
emails_enabledboolean否启用电子邮件通知。
lfs_enabledboolean否为群组中的项目启用/禁用大文件存储（LFS）。
mentions_disabledboolean否禁止群组被提及的功能。
prevent_sharing_groups_outside_hierarchyboolean否请参见防止群组共享到群组层次结构之外。此属性仅适用于顶级群组。
project_creation_levelstring否决定开发人员是否可以在群组中创建项目。可以是 noone（没人）、maintainer（拥有维护者角色的用户）或 developer（拥有开发者或维护者角色的用户）。
request_access_enabledboolean否允许用户请求成员访问。
require_two_factor_authenticationboolean否要求此群组中的所有用户设置双重身份验证。
shared_runners_settingstring否请参见共享 runners 设置的选项。为群组的子群组和项目启用或禁用实例 runners。
share_with_group_lockboolean否防止在此群组内与另一个群组共享项目。
subgroup_creation_levelstring否允许创建子群组。可以是 owner（所有者）或 maintainer（拥有维护者角色的用户）。
two_factor_grace_periodinteger否强制执行双因素认证之前的时间（以小时为单位）。
visibilitystring否群组的可见性级别。可以是 private、internal 或 public。
extra_shared_runners_minutes_limitinteger否仅限管理员设置。为此群组添加额外的计算分钟数。极狐GitLab私有化部署，专业版和旗舰版。
file_template_project_idinteger否用于加载自定义文件模板的项目 ID。仅限专业版和旗舰版。
membership_lockboolean否用户无法被添加到此群组中的项目中。仅限专业版和旗舰版。
prevent_forking_outside_groupboolean否启用时，用户不能将此群组中的项目 fork 到外部命名空间。仅限专业版和旗舰版。
shared_runners_minutes_limitinteger否仅限管理员设置。此群组的最大每月计算分钟数。可以是 nil（默认；继承系统默认值）、0（无限制）或 > 0。极狐GitLab私有化部署，专业版和旗舰版。
unique_project_download_limitinteger否在指定时间内用户可以下载的唯一项目的最大数量，超过后将被禁止。仅适用于顶级群组。默认值：0，最大值：10,000。仅限旗舰版。
unique_project_download_limit_interval_in_secondsinteger否用户在下载最大数量的项目之前可以下载的唯一项目的时间周期。仅适用于顶级群组。默认值：0，最大值：864,000 秒（10 天）。仅限旗舰版。
unique_project_download_limit_allowlistarray of strings否从唯一项目下载限制中排除的用户名列表。仅适用于顶级群组。默认值：[]，最大值：100 个用户名。仅限旗舰版。
unique_project_download_limit_alertlistarray of integers否超过唯一项目下载限制时收到电子邮件的用户 ID 列表。仅适用于顶级群组。默认值：[]，最大值：100 个用户 ID。极狐GitLab 15.9 中引入。仅限旗舰版。
auto_ban_user_on_excessive_projects_downloadboolean否启用时，当用户下载的唯一项目数量超过 unique_project_download_limit 和 unique_project_download_limit_interval_in_seconds 指定的最大数量时，用户将自动被禁止。极狐GitLab 15.4 中引入。仅限旗舰版。
ip_restriction_rangesstring否用于限制群组访问的 IP 地址或子网掩码的逗号分隔列表。极狐GitLab 15.4 中引入。仅限专业版和旗舰版。
allowed_email_domains_liststring否允许群组访问的电子邮件地址域的逗号分隔列表。极狐GitLab 专业版和旗舰版。
wiki_access_levelstring否维基访问级别。可以是 disabled、private 或 enabled。仅限专业版和旗舰版。
experiment_features_enabledboolean否为此群组启用实验功能。
math_rendering_limits_enabledboolean否指示是否对该群组使用数学渲染限制。
lock_math_rendering_limits_enabledboolean否指示是否对所有子群组锁定数学渲染限制。
max_artifacts_sizeinteger否单个作业产物的最大文件大小（以 MB 为单位）。
响应中的 `projects` 和 `shared_projects` 属性已弃用，并计划在 API v5 中删除。要获取群组中所有项目的详细信息，请使用[列出群组的项目](#list-projects)或[列出群组的共享项目](#list-shared-projects)端点。
shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/5?name=Experimental"

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

示例响应：

json
1{
2  "id": 5,
3  "name": "Experimental",
4  "path": "h5bp",
5  "description": "foo",
6  "visibility": "internal",
7  "avatar_url": null,
8  "web_url": "http://gitlab.example.com/groups/h5bp",
9  "request_access_enabled": false,
10  "repository_storage": "default",
11  "full_name": "Foobar Group",
12  "full_path": "h5bp",
13  "file_template_project_id": 1,
14  "parent_id": null,
15  "enabled_git_access_protocol": "all",
16  "created_at": "2020-01-15T12:36:29.590Z",
17  "prevent_sharing_groups_outside_hierarchy": false,
18  "projects": [ // 已弃用，将在 API v5 中删除
19    {
20      "id": 9,
21      "description": "foo",
22      "default_branch": "main",
23      "tag_list": [], // 已弃用，请使用 `topics`
24      "topics": [],
25      "public": false,
26      "archived": false,
27      "visibility": "internal",
28      "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
29      "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
30      "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
31      "name": "Html5 Boilerplate",
32      "name_with_namespace": "Experimental / Html5 Boilerplate",
33      "path": "html5-boilerplate",
34      "path_with_namespace": "h5bp/html5-boilerplate",
35      "issues_enabled": true,
36      "merge_requests_enabled": true,
37      "wiki_enabled": true,
38      "jobs_enabled": true,
39      "snippets_enabled": true,
40      "created_at": "2016-04-05T21:40:50.169Z",
41      "last_activity_at": "2016-04-06T16:52:08.432Z",
42      "shared_runners_enabled": true,
43      "creator_id": 1,
44      "namespace": {
45        "id": 5,
46        "name": "Experimental",
47        "path": "h5bp",
48        "kind": "group"
49      },
50      "avatar_url": null,
51      "star_count": 1,
52      "forks_count": 0,
53      "open_issues_count": 3,
54      "public_jobs": true,
55      "shared_with_groups": [],
56      "request_access_enabled": false
57    }
58  ],
59  "ip_restriction_ranges": null,
60  "math_rendering_limits_enabled": true,
61  "lock_math_rendering_limits_enabled": false
62}

响应中的 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，但允许子群组覆盖此设置。

群组成员#

请参阅群组成员文档。

更新群组头像#

更新群组头像。

下载群组头像#

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

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

示例：

shell
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= 参数必须指向文件系统上的文件，并以 @ 作为前缀。例如：

shell
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 中引入。

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

示例请求：

shell
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 标志。

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

此端点：

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

参数：

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

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

如果极狐GitLab.com 群组与订阅链接，则无法删除。要删除此类群组，请先将订阅[链接到另一个群组](../subscriptions/gitlab_com/_index.md#link-subscription-to-a-group)。

恢复标记为删除的群组#

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

恢复标记为删除的群组。

plaintext
POST /groups/:id/restore

参数：

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

撤销令牌#

History
    • 极狐GitLab 17.2 中引入，使用名为 group_agnostic_token_revocation 的功能标志。默认禁用。
    • 极狐GitLab 17.3 中引入了用户的 feed 令牌撤销。
此功能的可用性由功能标志控制。有关更多信息，请参见历史记录。

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

必须满足以下条件：

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

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

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

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

示例请求

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

示例响应：

json
1{
2    "id": 9,
3    "name": "my-subgroup-deploytoken",
4    "username": "gitlab+deploy-token-9",
5    "expires_at": null,
6    "scopes":
7    [
8        "read_repository",
9        "read_package_registry",
10        "write_package_registry"
11    ],
12    "revoked": true,
13    "expired": false
14}

与群组共享群组#

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

创建链接以将群组与另一个群组共享#

与另一个群组共享群组。成功时返回 200 和群组详情。

plaintext
POST /groups/:id/share
属性类型必需描述
idinteger/string是群组的 ID 或群组的 URL 编码路径
group_idinteger是要与之共享的群组 ID
group_accessinteger是向群组授予的角色（access_level）
expires_atstring否共享过期日期，格式为 ISO 8601：2016-09-26
member_role_idinteger否要分配给被邀请群组的自定义角色的 ID

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

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

将项目转移到群组#

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

plaintext
POST /groups/:id/projects/:project_id

参数：

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

转移群组#

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

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

参数：

属性类型必需描述
id整数是要转移的群组的 ID。
group_id整数否新父群组的 ID。如果未指定，则要转移的群组将变为顶级群组。
shell
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。

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

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

示例请求：

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

示例响应：

json
1[
2  {
3    "id": 27,
4    "web_url": "https://gitlab.example.com/groups/gitlab",
5    "name": "GitLab",
6    "avatar_url": null,
7    "full_name": "GitLab",
8    "full_path": "GitLab"
9  },
10  {
11    "id": 31,
12    "web_url": "https://gitlab.example.com/groups/foobar",
13    "name": "FooBar",
14    "avatar_url": null,
15    "full_name": "FooBar",
16    "full_path": "FooBar"
17  }
18]