标记 API

Tier: 基础版，专业版，旗舰版
Offering: JihuLab.com，私有化部署

使用 REST API 与标签进行交互。

列出标签#

获取给定项目的所有标签。

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

plaintext
GET /projects/:id/labels

属性	类型	必需	描述
id	integer/string	是	项目的 ID 或URL 编码路径
with_counts	boolean	否	是否包含议题和合并请求计数。默认为 false。
include_ancestor_groups	boolean	否	包含祖先群组。默认为 true。
search	string	否	按关键字过滤标签。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels?with_counts=true"

示例响应：

json
1[
2  {
3    "id" : 1,
4    "name" : "bug",
5    "color" : "#d9534f",
6    "text_color" : "#FFFFFF",
7    "description": "Bug reported by user",
8    "description_html": "Bug reported by user",
9    "open_issues_count": 1,
10    "closed_issues_count": 0,
11    "open_merge_requests_count": 1,
12    "subscribed": false,
13    "priority": 10,
14    "is_project_label": true
15  },
16  {
17    "id" : 4,
18    "color" : "#d9534f",
19    "text_color" : "#FFFFFF",
20    "name" : "confirmed",
21    "description": "Confirmed issue",
22    "description_html": "Confirmed issue",
23    "open_issues_count": 2,
24    "closed_issues_count": 5,
25    "open_merge_requests_count": 0,
26    "subscribed": false,
27    "priority": null,
28    "is_project_label": true
29  },
30  {
31    "id" : 7,
32    "name" : "critical",
33    "color" : "#d9534f",
34    "text_color" : "#FFFFFF",
35    "description": "Critical issue. Need fix ASAP",
36    "description_html": "Critical issue. Need fix ASAP",
37    "open_issues_count": 1,
38    "closed_issues_count": 3,
39    "open_merge_requests_count": 1,
40    "subscribed": false,
41    "priority": null,
42    "is_project_label": true
43  },
44  {
45    "id" : 8,
46    "name" : "documentation",
47    "color" : "#f0ad4e",
48    "text_color" : "#FFFFFF",
49    "description": "Issue about documentation",
50    "description_html": "Issue about documentation",
51    "open_issues_count": 1,
52    "closed_issues_count": 0,
53    "open_merge_requests_count": 2,
54    "subscribed": false,
55    "priority": null,
56    "is_project_label": false
57  },
58  {
59    "id" : 9,
60    "color" : "#5cb85c",
61    "text_color" : "#FFFFFF",
62    "name" : "enhancement",
63    "description": "Enhancement proposal",
64    "description_html": "Enhancement proposal",
65    "open_issues_count": 1,
66    "closed_issues_count": 0,
67    "open_merge_requests_count": 1,
68    "subscribed": true,
69    "priority": null,
70    "is_project_label": true
71  }
72]

获取单个项目标签#

获取给定项目的单个标签。

plaintext
GET /projects/:id/labels/:label_id

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或URL 编码路径
label_id	integer or string	是	项目标签的 ID 或标题。
include_ancestor_groups	boolean	否	包含祖先群组。默认为 true。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/bug"

示例响应：

json
1{
2  "id" : 1,
3  "name" : "bug",
4  "color" : "#d9534f",
5  "text_color" : "#FFFFFF",
6  "description": "Bug reported by user",
7  "description_html": "Bug reported by user",
8  "open_issues_count": 1,
9  "closed_issues_count": 0,
10  "open_merge_requests_count": 1,
11  "subscribed": false,
12  "priority": 10,
13  "is_project_label": true
14}

创建新标签#

为给定的仓库创建具有指定名称和颜色的新标签。

plaintext
POST /projects/:id/labels

属性	类型	必需	描述
id	integer/string	是	项目的 ID 或URL 编码路径
name	string	是	标签的名称
color	string	是	标签的颜色，使用 6 位十六进制表示法，前面加 '#' 符号（例如，#FFAABB）或使用 CSS 颜色名称
description	string	否	标签的描述
priority	integer	否	标签的优先级。必须大于或等于零，或为 null 以移除优先级。

shell
curl --data "name=feature&color=#5843AD" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels"

示例响应：

json
1{
2  "id" : 10,
3  "name" : "feature",
4  "color" : "#5843AD",
5  "text_color" : "#FFFFFF",
6  "description":null,
7  "description_html":null,
8  "open_issues_count": 0,
9  "closed_issues_count": 0,
10  "open_merge_requests_count": 0,
11  "subscribed": false,
12  "priority": null,
13    "is_project_label": true
14}

删除标签#

删除具有指定名称的标签。

plaintext
DELETE /projects/:id/labels/:label_id

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或URL 编码路径
label_id	integer or string	是	群组标签的 ID 或标题。

shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/bug"

较旧的端点 `DELETE /projects/:id/labels`，参数中包含 `name` 仍然可用，但已被弃用。

编辑现有标签#

使用新名称或新颜色更新现有标签。至少需要一个参数来更新标签。

plaintext
PUT /projects/:id/labels/:label_id

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或URL 编码路径
label_id	integer or string	是	群组标签的 ID 或标题。
new_name	string	如果未提供 color 则为必需	标签的新名称
color	string	如果未提供 new_name 则为必需	标签的颜色，使用 6 位十六进制表示法，前面加 '#' 符号（例如，#FFAABB）或使用 CSS 颜色名称
description	string	否	标签的新描述
priority	integer	否	标签的新优先级。必须大于或等于零，或为 null 以移除优先级。

shell
curl --request PUT --data "new_name=docs&color=#8E44AD&description=Documentation" \
     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/documentation"

示例响应：

json
1{
2  "id" : 8,
3  "name" : "docs",
4  "color" : "#8E44AD",
5  "text_color" : "#FFFFFF",
6  "description": "Documentation",
7  "description_html": "Documentation",
8  "open_issues_count": 1,
9  "closed_issues_count": 0,
10  "open_merge_requests_count": 2,
11  "subscribed": false,
12  "priority": null,
13  "is_project_label": true
14}

较旧的端点 `PUT /projects/:id/labels`，参数中包含 `name` 或 `label_id` 仍然可用，但已被弃用。

将项目标签提升为群组标签#

将项目标签提升为群组标签。标签保留其 ID。

plaintext
PUT /projects/:id/labels/:label_id/promote

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或URL 编码路径
label_id	integer or string	是	群组标签的 ID 或标题。

shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/documentation/promote"

示例响应：

json
1{
2  "id" : 8,
3  "name" : "documentation",
4  "color" : "#8E44AD",
5  "description": "Documentation",
6  "description_html": "Documentation",
7  "open_issues_count": 1,
8  "closed_issues_count": 0,
9  "open_merge_requests_count": 2,
10  "subscribed": false
11}

较旧的端点 `PUT /projects/:id/labels/promote`，参数中包含 `name` 仍然可用，但已被弃用。

订阅认证用户以接收标签通知。如果用户已订阅该标签，则返回状态代码 304。

plaintext
POST /projects/:id/labels/:label_id/subscribe

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或URL 编码路径
label_id	integer or string	是	项目标签的 ID 或标题

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/labels/1/subscribe"

示例响应：

json
1{
2  "id" : 1,
3  "name" : "bug",
4  "color" : "#d9534f",
5  "text_color" : "#FFFFFF",
6  "description": "Bug reported by user",
7  "description_html": "Bug reported by user",
8  "open_issues_count": 1,
9  "closed_issues_count": 0,
10  "open_merge_requests_count": 1,
11  "subscribed": true,
12  "priority": null,
13  "is_project_label": true
14}

取消订阅标签#

取消认证用户对标签的订阅，停止接收通知。如果用户未订阅该标签，则返回状态代码 304。

plaintext
POST /projects/:id/labels/:label_id/unsubscribe

属性	类型	必需	描述
id	integer or string	是	项目的 ID 或URL 编码路径
label_id	integer or string	是	项目标签的 ID 或标题

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/labels/1/unsubscribe"