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