{{< details >}}
- Tier: 基础版,专业版,旗舰版
- Offering: JihuLab.com,私有化部署
{{< /details >}}
使用 REST API 与标签进行交互。
列出标签
获取给定项目的所有标签。
默认情况下,此请求一次返回 20 个结果,因为 API 结果是分页的。
GET /projects/:id/labels
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目的 ID 或URL 编码路径 |
with_counts |
boolean | 否 | 是否包含议题和合并请求计数。默认为 false 。 |
include_ancestor_groups |
boolean | 否 | 包含祖先群组。默认为 true 。 |
search |
string | 否 | 按关键字过滤标签。 |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels?with_counts=true"
示例响应:
[
{
"id" : 1,
"name" : "bug",
"color" : "#d9534f",
"text_color" : "#FFFFFF",
"description": "Bug reported by user",
"description_html": "Bug reported by user",
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 1,
"subscribed": false,
"priority": 10,
"is_project_label": true
},
{
"id" : 4,
"color" : "#d9534f",
"text_color" : "#FFFFFF",
"name" : "confirmed",
"description": "Confirmed issue",
"description_html": "Confirmed issue",
"open_issues_count": 2,
"closed_issues_count": 5,
"open_merge_requests_count": 0,
"subscribed": false,
"priority": null,
"is_project_label": true
},
{
"id" : 7,
"name" : "critical",
"color" : "#d9534f",
"text_color" : "#FFFFFF",
"description": "Critical issue. Need fix ASAP",
"description_html": "Critical issue. Need fix ASAP",
"open_issues_count": 1,
"closed_issues_count": 3,
"open_merge_requests_count": 1,
"subscribed": false,
"priority": null,
"is_project_label": true
},
{
"id" : 8,
"name" : "documentation",
"color" : "#f0ad4e",
"text_color" : "#FFFFFF",
"description": "Issue about documentation",
"description_html": "Issue about documentation",
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 2,
"subscribed": false,
"priority": null,
"is_project_label": false
},
{
"id" : 9,
"color" : "#5cb85c",
"text_color" : "#FFFFFF",
"name" : "enhancement",
"description": "Enhancement proposal",
"description_html": "Enhancement proposal",
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 1,
"subscribed": true,
"priority": null,
"is_project_label": true
}
]
获取单个项目标签
获取给定项目的单个标签。
GET /projects/:id/labels/:label_id
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或URL 编码路径 |
label_id |
integer or string | 是 | 项目标签的 ID 或标题。 |
include_ancestor_groups |
boolean | 否 | 包含祖先群组。默认为 true 。 |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/bug"
示例响应:
{
"id" : 1,
"name" : "bug",
"color" : "#d9534f",
"text_color" : "#FFFFFF",
"description": "Bug reported by user",
"description_html": "Bug reported by user",
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 1,
"subscribed": false,
"priority": 10,
"is_project_label": true
}
创建新标签
为给定的仓库创建具有指定名称和颜色的新标签。
POST /projects/:id/labels
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | 是 | 项目的 ID 或URL 编码路径 |
name |
string | 是 | 标签的名称 |
color |
string | 是 | 标签的颜色,使用 6 位十六进制表示法,前面加 ‘#’ 符号(例如,#FFAABB)或使用 CSS 颜色名称 |
description |
string | 否 | 标签的描述 |
priority |
integer | 否 | 标签的优先级。必须大于或等于零,或为 null 以移除优先级。 |
curl --data "name=feature&color=#5843AD" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels"
示例响应:
{
"id" : 10,
"name" : "feature",
"color" : "#5843AD",
"text_color" : "#FFFFFF",
"description":null,
"description_html":null,
"open_issues_count": 0,
"closed_issues_count": 0,
"open_merge_requests_count": 0,
"subscribed": false,
"priority": null,
"is_project_label": true
}
删除标签
删除具有指定名称的标签。
DELETE /projects/:id/labels/:label_id
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或URL 编码路径 |
label_id |
integer or string | 是 | 群组标签的 ID 或标题。 |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/bug"
{{< alert type=”note” >}}
较旧的端点 DELETE /projects/:id/labels
,参数中包含 name
仍然可用,但已被弃用。
{{< /alert >}}
编辑现有标签
使用新名称或新颜色更新现有标签。至少需要一个参数来更新标签。
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 以移除优先级。 |
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"
示例响应:
{
"id" : 8,
"name" : "docs",
"color" : "#8E44AD",
"text_color" : "#FFFFFF",
"description": "Documentation",
"description_html": "Documentation",
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 2,
"subscribed": false,
"priority": null,
"is_project_label": true
}
{{< alert type=”note” >}}
较旧的端点 PUT /projects/:id/labels
,参数中包含 name
或 label_id
仍然可用,但已被弃用。
{{< /alert >}}
将项目标签提升为群组标签
将项目标签提升为群组标签。标签保留其 ID。
PUT /projects/:id/labels/:label_id/promote
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或URL 编码路径 |
label_id |
integer or string | 是 | 群组标签的 ID 或标题。 |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels/documentation/promote"
示例响应:
{
"id" : 8,
"name" : "documentation",
"color" : "#8E44AD",
"description": "Documentation",
"description_html": "Documentation",
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 2,
"subscribed": false
}
{{< alert type=”note” >}}
较旧的端点 PUT /projects/:id/labels/promote
,参数中包含 name
仍然可用,但已被弃用。
{{< /alert >}}
订阅标签
订阅认证用户以接收标签通知。如果用户已订阅该标签,则返回状态代码 304
。
POST /projects/:id/labels/:label_id/subscribe
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或URL 编码路径 |
label_id |
integer or string | 是 | 项目标签的 ID 或标题 |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/labels/1/subscribe"
示例响应:
{
"id" : 1,
"name" : "bug",
"color" : "#d9534f",
"text_color" : "#FFFFFF",
"description": "Bug reported by user",
"description_html": "Bug reported by user",
"open_issues_count": 1,
"closed_issues_count": 0,
"open_merge_requests_count": 1,
"subscribed": true,
"priority": null,
"is_project_label": true
}
取消订阅标签
取消认证用户对标签的订阅,停止接收通知。如果用户未订阅该标签,则返回状态代码 304
。
POST /projects/:id/labels/:label_id/unsubscribe
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer or string | 是 | 项目的 ID 或URL 编码路径 |
label_id |
integer or string | 是 | 项目标签的 ID 或标题 |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/labels/1/unsubscribe"