# Tags API

> 原文：[https://docs.gitlab.com/ee/api/tags.html](https://docs.gitlab.com/ee/api/tags.html)

*   [List project repository tags](#list-project-repository-tags)
*   [Get a single repository tag](#get-a-single-repository-tag)
*   [Create a new tag](#create-a-new-tag)
*   [Delete a tag](#delete-a-tag)
*   [Create a new release](#create-a-new-release)
*   [Update a release](#update-a-release)

# Tags API[](#tags-api "Permalink")

## List project repository tags[](#list-project-repository-tags "Permalink")

从项目中获取存储库标签的列表，按名称以相反的字母顺序排序. 如果可公开访问该存储库，则无需身份验证即可访问此端点.

```
GET /projects/:id/repository/tags 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `order_by` | string | no | 返回按`name`或`updated`字段排序的标签. 默认值已`updated` |
| `sort` | string | no | 返回按`asc`或`desc`顺序排序的标签. 默认为`desc` |
| `search` | string | no | 返回符合搜索条件的标签列表. 您可以使用`^term`和`term$`查找分别以`term`开头和结尾的标签. |

在 GitLab 11.8 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54401)了对`search`支持.

```
[  {  "commit":  {  "id":  "2695effb5807a22ff3d138d593fd856244e155e7",  "short_id":  "2695effb",  "title":  "Initial commit",  "created_at":  "2017-07-26T11:08:53.000+02:00",  "parent_ids":  [  "2a4b78934375d7f53875269ffd4f45fd83a84ebe"  ],  "message":  "Initial commit",  "author_name":  "John Smith",  "author_email":  "john@example.com",  "authored_date":  "2012-05-28T04:42:42-07:00",  "committer_name":  "Jack Smith",  "committer_email":  "jack@example.com",  "committed_date":  "2012-05-28T04:42:42-07:00"  },  "release":  {  "tag_name":  "1.0.0",  "description":  "Amazing release. Wow"  },  "name":  "v1.0.0",  "target":  "2695effb5807a22ff3d138d593fd856244e155e7",  "message":  null,  "protected":  true  }  ] 
```

## Get a single repository tag[](#get-a-single-repository-tag "Permalink")

获取由其名称确定的特定存储库标签. 如果可公开访问该存储库，则无需身份验证即可访问此端点.

```
GET /projects/:id/repository/tags/:tag_name 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `tag_name` | string | yes | 标签名称 |

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/tags/v1.0.0" 
```

示例响应：

```
{  "name":  "v5.0.0",  "message":  null,  "target":  "60a8ff033665e1207714d6670fcd7b65304ec02f",  "commit":  {  "id":  "60a8ff033665e1207714d6670fcd7b65304ec02f",  "short_id":  "60a8ff03",  "title":  "Initial commit",  "created_at":  "2017-07-26T11:08:53.000+02:00",  "parent_ids":  [  "f61c062ff8bcbdb00e0a1b3317a91aed6ceee06b"  ],  "message":  "v5.0.0\n",  "author_name":  "Arthur Verschaeve",  "author_email":  "contact@arthurverschaeve.be",  "authored_date":  "2015-02-01T21:56:31.000+01:00",  "committer_name":  "Arthur Verschaeve",  "committer_email":  "contact@arthurverschaeve.be",  "committed_date":  "2015-02-01T21:56:31.000+01:00"  },  "release":  null,  "protected":  false  } 
```

## Create a new tag[](#create-a-new-tag "Permalink")

在存储库中创建一个新标签，该标签指向提供的参考.

```
POST /projects/:id/repository/tags 
```

Parameters:

*   `id` （必填）-经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding)
*   `tag_name` （必需）-标签的名称
*   `ref` （必需）-使用提交 SHA，另一个标签名称或分支名称创建标签.
*   `message` （可选）-创建带注释的标签.
*   `release_description` （可选）-将发行说明添加到 Git 标签并将其存储在 GitLab 数据库中.

```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/tags?tag_name=test&ref=master" 
```

响应示例：

```
{  "commit":  {  "id":  "2695effb5807a22ff3d138d593fd856244e155e7",  "short_id":  "2695effb",  "title":  "Initial commit",  "created_at":  "2017-07-26T11:08:53.000+02:00",  "parent_ids":  [  "2a4b78934375d7f53875269ffd4f45fd83a84ebe"  ],  "message":  "Initial commit",  "author_name":  "John Smith",  "author_email":  "john@example.com",  "authored_date":  "2012-05-28T04:42:42-07:00",  "committer_name":  "Jack Smith",  "committer_email":  "jack@example.com",  "committed_date":  "2012-05-28T04:42:42-07:00"  },  "release":  {  "tag_name":  "1.0.0",  "description":  "Amazing release. Wow"  },  "name":  "v1.0.0",  "target":  "2695effb5807a22ff3d138d593fd856244e155e7",  "message":  null,  "protected":  false  } 
```

创建轻量级标签时，该消息将为`null` ，否则将包含注释.

在创建带注释的标签时，目标将包含标签对象 ID，否则在创建轻量级标签时将包含提交 ID.

如果出现错误，则返回带有解释性错误消息的状态代码`405` .

## Delete a tag[](#delete-a-tag "Permalink")

删除具有给定名称的存储库的标记.

```
DELETE /projects/:id/repository/tags/:tag_name 
```

Parameters:

*   `id` （必填）-经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding)
*   `tag_name` （必需）-标签的名称

## Create a new release[](#create-a-new-release "Permalink")

将发行说明添加到现有的 Git 标签. 如果给定标签已经存在发行版，则返回状态码`409` .

```
POST /projects/:id/repository/tags/:tag_name/release 
```

Parameters:

*   `id` （必填）-经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding)
*   `tag_name` （必需）-标签的名称

要求正文：

*   `description` （必需）-具有 Markdown 支持的发行说明

```
{  "description":  "Amazing release. Wow"  } 
```

Response:

```
{  "tag_name":  "1.0.0",  "description":  "Amazing release. Wow"  } 
```

## Update a release[](#update-a-release "Permalink")

更新给定发行版的发行说明.

```
PUT /projects/:id/repository/tags/:tag_name/release 
```

Parameters:

*   `id` （必填）-经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding)
*   `tag_name` （必需）-标签的名称

要求正文：

*   `description` （必需）-具有 Markdown 支持的发行说明

```
{  "description":  "Amazing release. Wow"  } 
```

Response:

```
{  "tag_name":  "1.0.0",  "description":  "Amazing release. Wow"  } 
```