Tags API · Gitlab 中文文档

# 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" } ```