Tags API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
List project repository tags
Get a list of repository tags from a project, sorted by update date and time in descending order.
If the repository is publicly accessible, authentication
(--header "PRIVATE-TOKEN: <your_access_token>"
) is not required.
GET /projects/:id/repository/tags
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project. |
order_by | string | no | Return tags ordered by name , updated , or version . Default is updated . |
sort | string | no | Return tags sorted in asc or desc order. Default is desc . |
search | string | no | Return a list of tags matching the search criteria. You can use ^term and term$ to find tags that begin and end with term . No other regular expressions are supported. |
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/repository/tags"
Example Response:
[
{
"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,
"created_at": "2017-07-26T11:08:53.000+02:00"
}
]
Get a single repository tag
Get a specific repository tag determined by its name. This endpoint can be accessed without authentication if the repository is publicly accessible.
GET /projects/:id/repository/tags/:tag_name
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project. |
tag_name | string | yes | The name of a tag. |
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/5/repository/tags/v1.0.0"
Example Response:
{
"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,
"created_at": "2017-07-26T11:08:53.000+02:00"
}
Create a new tag
Creates a new tag in the repository that points to the supplied ref.
POST /projects/:id/repository/tags
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project. |
tag_name | string | yes | The name of a tag. |
ref | string | yes | Create a tag from a commit SHA, another tag name, or branch name. |
message | string | no | Create an annotated tag. |
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"
Example response:
{
"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": null,
"name": "v1.0.0",
"target": "2695effb5807a22ff3d138d593fd856244e155e7",
"message": null,
"protected": false,
"created_at": null
}
The type of tag created determines the contents of created_at
, target
and message
:
- For annotated tags:
created_at
contains the timestamp of tag creation.message
contains the annotation.target
contains the tag object’s ID.
- For lightweight tags:
created_at
is null.message
is null.target
contains the commit ID.
Errors return status code 405
with an explanatory error message.
Delete a tag
Deletes a tag of a repository with given name.
DELETE /projects/:id/repository/tags/:tag_name
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project. |
tag_name | string | yes | The name of a tag. |
Get X.509 signature of a tag
Get the X.509 signature from a tag,
if it is signed. Unsigned tags return a 404 Not Found
response.
GET /projects/:id/repository/tags/:tag_name/signature
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | yes | The ID or URL-encoded path of the project. |
tag_name | string | yes | The name of a tag. |
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/1/repository/tags/v1.1.1/signature"
Example response if tag is X.509 signed:
{
"signature_type": "X509",
"verification_status": "unverified",
"x509_certificate": {
"id": 1,
"subject": "CN=gitlab@example.org,OU=Example,O=World",
"subject_key_identifier": "BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC",
"email": "gitlab@example.org",
"serial_number": 278969561018901340486471282831158785578,
"certificate_status": "good",
"x509_issuer": {
"id": 1,
"subject": "CN=PKI,OU=Example,O=World",
"subject_key_identifier": "AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB",
"crl_url": "http://example.com/pki.crl"
}
}
}
Example response if tag is unsigned:
{
"message": "404 GPG Signature Not Found"
}
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support