{{< 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 。仅限旗舰版。 |
脚注:
- 按
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 >}}
- 在极狐GitLab 16.6 中引入。该功能是一个试验性功能。
{{< /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"
转移群组
将群组转移到新的父群组或将子群组变为顶级群组。对管理员和用户可用:
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"
}
]