Help us learn about your current experience with the documentation. Take the survey.

标签 API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用 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"

带有参数中 name 的旧端点 DELETE /projects/:id/labels 仍然可用，但已弃用。

编辑现有标签

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

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
}

带有参数中 name 或 label_id 的旧端点 PUT /projects/:id/labels 仍然可用，但已弃用。

将项目标签提升为组标签

将项目标签提升为组标签。标签保持其 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
}

带有参数中 name 的旧端点 PUT /projects/:id/labels/promote 仍然可用，但已弃用。

订阅标签

将已认证的用户订阅到标签以接收通知。如果用户已经订阅了该标签，则返回状态码 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"