群组标记 API

引入于极狐GitLab 11.8。

此 API 支持管理群组标签。 它允许用户列出、创建、更新和删除群组标签。此外,用户可以订阅或取消订阅群组标签。

notedescription_html - 于极狐GitLab 12.7 添加到响应 JSON 中。

列出群组标记

获取特定群组的所有标记。

GET /groups/:id/labels
参数 类型 是否必需 描述
id integer/string yes 授权用户拥有的 ID 或 URL 编码的群组路径
with_counts boolean no 是否包括议题和合并请求的数量。默认为 false。引入于极狐GitLab 12.2
include_ancestor_groups boolean no 包括上级群组。默认为 true
include_descendant_groups boolean no 包括下级群组。默认为 false。引入于极狐GitLab 13.6
only_group_labels boolean no 是否只包括群组标记。默认为 true。引入于极狐GitLab 13.6
search string no 筛选标记的关键字。引入于极狐GitLab 13.6
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels?with_counts=true"

响应示例:

[
  {
    "id": 7,
    "name": "bug",
    "color": "#FF0000",
    "text_color" : "#FFFFFF",
    "description": null,
    "description_html": null,
    "open_issues_count": 0,
    "closed_issues_count": 0,
    "open_merge_requests_count": 0,
    "subscribed": false
  },
  {
    "id": 4,
    "name": "feature",
    "color": "#228B22",
    "text_color" : "#FFFFFF",
    "description": null,
    "description_html": null,
    "open_issues_count": 0,
    "closed_issues_count": 0,
    "open_merge_requests_count": 0,
    "subscribed": false
  }
]

获取单个群组标记

获取特定群组的单个标记。

GET /groups/:id/labels/:label_id
参数 类型 是否必需 描述
id integer or string yes 授权用户拥有的 ID 或 URL 编码的群组路径
label_id integer or string yes 群组标记的 ID 或标题
include_ancestor_groups boolean no 包括上级群组。默认为 true
include_descendant_groups boolean no 包括下级群组。默认为 false。引入于极狐GitLab 13.6
only_group_labels boolean no 是否只包括群组标记。默认为 true。引入于极狐GitLab 13.6
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug"

响应示例:

{
  "id": 7,
  "name": "bug",
  "color": "#FF0000",
  "text_color" : "#FFFFFF",
  "description": null,
  "description_html": null,
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false
}

创建新的群组标记

为特定群组创建新的群组标记。

POST /groups/:id/labels
参数 类型 是否必需 描述
id integer/string yes 授权用户拥有的 ID 或 URL 编码的群组路径
name string yes 标记名称
color string yes 以 6 位十六进制表示法呈现的标记颜色,带有前导 ‘#’ 符号(例如,#FFAABB)或 CSS 颜色名称之一
description string no 标记描述
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
     --data '{"name": "Feature Proposal", "color": "#FFA500", "description": "Describes new ideas" }' \
     "https://gitlab.example.com/api/v4/groups/5/labels"

响应示例:

{
  "id": 9,
  "name": "Feature Proposal",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false
}

更新群组标记

更新现存的群组标记。至少需要一个参数以更新群组标记。

PUT /groups/:id/labels/:label_id
参数 类型 是否必需 描述
id integer or string yes 授权用户拥有的 ID 或 URL 编码的群组路径
label_id integer or string yes 群组标记的 ID 或标题
new_name string no 标记的新名称
color string no 以 6 位十六进制表示法呈现的标记颜色,带有前导 ‘#’ 符号(例如,#FFAABB)或 CSS 颜色名称之一
description string no 标记描述
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
     --data '{"new_name": "Feature Idea" }' "https://gitlab.example.com/api/v4/groups/5/labels/Feature%20Proposal"

响应示例:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false
}
note参数中带有 name 的旧的端点 PUT /groups/:id/labels 仍可用,但已被废弃。

删除群组标记

删除特定名称的群组标记。

DELETE /groups/:id/labels/:label_id
参数 类型 是否必需 描述
id integer or string yes 授权用户拥有的 ID 或 URL 编码的群组路径
label_id integer or string yes 群组标记的 ID 或标题
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/bug"
note参数中带有 name 的旧的端点 DELETE /groups/:id/labels 仍可用,但已被废弃。

订阅群组标记

为授权用户订阅群组标记以接收通知。如果用户已经订阅了该标记,则返回状态码 304

POST /groups/:id/labels/:label_id/subscribe
参数 类型 是否必需 描述
id integer or string yes 授权用户拥有的 ID 或 URL 编码的群组路径
label_id integer or string yes 群组标记的 ID 或标题
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/9/subscribe"

响应示例:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": true
}

取消订阅群组标记

取消订阅群组标记的授权用户不再接收其通知。如果用户没有订阅标记,则返回状态码 304

POST /groups/:id/labels/:label_id/unsubscribe
参数 类型 是否必需 描述
id integer or string yes 授权用户拥有的 ID 或 URL 编码的群组路径
label_id integer or string yes 群组标记的 ID 或标题
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/labels/9/unsubscribe"

响应示例:

{
  "id": 9,
  "name": "Feature Idea",
  "color": "#FFA500",
  "text_color" : "#FFFFFF",
  "description": "Describes new ideas",
  "description_html": "Describes new ideas",
  "open_issues_count": 0,
  "closed_issues_count": 0,
  "open_merge_requests_count": 0,
  "subscribed": false
}