标签 API

Tier: 基础版，专业版，旗舰版
Offering: JihuLab.com, 私有化部署

列出项目仓库标签#

History

version 属性的 order_by 值在极狐GitLab 15.4 引入。
created_at 响应属性在极狐GitLab 16.11 引入。

获取项目的仓库标签列表，按更新时间和日期降序排列。

如果仓库是公开访问的，则不需要进行认证 (`--header "PRIVATE-TOKEN: "`)。

plaintext
GET /projects/:id/repository/tags

参数：

属性	类型	必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
order_by	string	否	返回按 name、updated 或 version 排序的标签。默认为 updated。
sort	string	否	返回按 asc 或 desc 排序的标签。默认为 desc。
search	string	否	返回符合搜索条件的标签列表。可以使用 ^term 和 term$ 来查找以 term 开头或结尾的标签。不支持其他正则表达式。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/projects/5/repository/tags"

示例响应：

json
1[
2  {
3    "commit": {
4      "id": "2695effb5807a22ff3d138d593fd856244e155e7",
5      "short_id": "2695effb",
6      "title": "Initial commit",
7      "created_at": "2017-07-26T11:08:53.000+02:00",
8      "parent_ids": [
9        "2a4b78934375d7f53875269ffd4f45fd83a84ebe"
10      ],
11      "message": "Initial commit",
12      "author_name": "John Smith",
13      "author_email": "john@example.com",
14      "authored_date": "2012-05-28T04:42:42-07:00",
15      "committer_name": "Jack Smith",
16      "committer_email": "jack@example.com",
17      "committed_date": "2012-05-28T04:42:42-07:00"
18    },
19    "release": {
20      "tag_name": "1.0.0",
21      "description": "Amazing release. Wow"
22    },
23    "name": "v1.0.0",
24    "target": "2695effb5807a22ff3d138d593fd856244e155e7",
25    "message": null,
26    "protected": true,
27    "created_at": "2017-07-26T11:08:53.000+02:00"
28  }
29]

获取单个仓库标签#

History

created_at 响应属性在极狐GitLab 16.11 引入。

根据标签名称获取特定的仓库标签。如果仓库是公开访问的，则可以不进行认证访问此端点。

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

参数：

属性	类型	必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
tag_name	string	是	标签的名称。

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

示例响应：

json
1{
2  "name": "v5.0.0",
3  "message": null,
4  "target": "60a8ff033665e1207714d6670fcd7b65304ec02f",
5  "commit": {
6    "id": "60a8ff033665e1207714d6670fcd7b65304ec02f",
7    "short_id": "60a8ff03",
8    "title": "Initial commit",
9    "created_at": "2017-07-26T11:08:53.000+02:00",
10    "parent_ids": [
11      "f61c062ff8bcbdb00e0a1b3317a91aed6ceee06b"
12    ],
13    "message": "v5.0.0\n",
14    "author_name": "Arthur Verschaeve",
15    "author_email": "contact@arthurverschaeve.be",
16    "authored_date": "2015-02-01T21:56:31.000+01:00",
17    "committer_name": "Arthur Verschaeve",
18    "committer_email": "contact@arthurverschaeve.be",
19    "committed_date": "2015-02-01T21:56:31.000+01:00"
20  },
21  "release": null,
22  "protected": false,
23  "created_at": "2017-07-26T11:08:53.000+02:00"
24}

创建新标签#

History

created_at 响应属性在极狐GitLab 16.11 引入。

在仓库中创建一个指向给定 ref 的新标签。

plaintext
POST /projects/:id/repository/tags

参数：

属性	类型	必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
tag_name	string	是	标签的名称。
ref	string	是	从提交 SHA、另一个标签名或分支名创建标签。
message	string	否	创建注释标签。

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

示例响应：

json
1{
2  "commit": {
3    "id": "2695effb5807a22ff3d138d593fd856244e155e7",
4    "short_id": "2695effb",
5    "title": "Initial commit",
6    "created_at": "2017-07-26T11:08:53.000+02:00",
7    "parent_ids": [
8      "2a4b78934375d7f53875269ffd4f45fd83a84ebe"
9    ],
10    "message": "Initial commit",
11    "author_name": "John Smith",
12    "author_email": "john@example.com",
13    "authored_date": "2012-05-28T04:42:42-07:00",
14    "committer_name": "Jack Smith",
15    "committer_email": "jack@example.com",
16    "committed_date": "2012-05-28T04:42:42-07:00"
17  },
18  "release": null,
19  "name": "v1.0.0",
20  "target": "2695effb5807a22ff3d138d593fd856244e155e7",
21  "message": null,
22  "protected": false,
23  "created_at": null
24}

创建的标签类型决定了 created_at、target 和 message 的内容：

对于注释标签：
- created_at 包含标签创建的时间戳。
- message 包含注释。
- target 包含标签对象的 ID。
对于轻量标签：
- created_at 为 null。
- message 为 null。
- target 包含提交 ID。

错误返回状态码 405 和解释性错误信息。

删除标签#

删除给定名称的仓库标签。

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

参数：

属性	类型	必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
tag_name	string	是	标签的名称。

获取标签的 X.509 签名#

History

在极狐GitLab 15.7 引入。

获取标签的 X.509 签名，如果它已签名。未签名的标签返回 404 Not Found 响应。

plaintext
GET /projects/:id/repository/tags/:tag_name/signature

参数：

属性	类型	必需	描述
id	integer 或 string	是	项目的 ID 或 URL 编码路径。
tag_name	string	是	标签的名称。

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/repository/tags/v1.1.1/signature"

如果标签是 X.509 签名的示例响应：

json
1{
2  "signature_type": "X509",
3  "verification_status": "unverified",
4  "x509_certificate": {
5    "id": 1,
6    "subject": "CN=gitlab@example.org,OU=Example,O=World",
7    "subject_key_identifier": "BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC",
8    "email": "gitlab@example.org",
9    "serial_number": 278969561018901340486471282831158785578,
10    "certificate_status": "good",
11    "x509_issuer": {
12      "id": 1,
13      "subject": "CN=PKI,OU=Example,O=World",
14      "subject_key_identifier": "AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB",
15      "crl_url": "http://example.com/pki.crl"
16    }
17  }
18}

如果标签是未签名的示例响应：

json
{
  "message": "404 GPG Signature Not Found"
}