- List project repository tags
- Get a single repository tag
- Create a new tag
- Delete a tag
- Create a new release
- Update a release
Tags API
List project repository tags
Get a list of repository tags from a project, sorted by name in reverse alphabetical order. This endpoint can be accessed without authentication if the repository is publicly accessible.
GET /projects/:id/repository/tags
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
order_by
| string | no | Return tags ordered by name or updated fields. Default is updated
|
sort
| string | no | Return tags sorted in asc or desc order. Default is desc
|
search
| string | no | Return list of tags matching the search criteria. You can use ^term and term$ to find tags that begin and end with term respectively.
|
Support for search
was introduced in GitLab 11.8.
[
{
"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 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/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
tag_name
| string | yes | The name of the tag |
curl --header "PRIVATE-TOKEN: <your_access_token>" 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
}
Create a new tag
Creates a new tag in the repository that points to the supplied ref.
POST /projects/:id/repository/tags
Parameters:
-
id
(required) - The ID or URL-encoded path of the project owned by the authenticated user -
tag_name
(required) - The name of a tag -
ref
(required) - Create tag using commit SHA, another tag name, or branch name. -
message
(optional) - Creates annotated tag. -
release_description
(optional) - Add release notes to the Git tag and store it in the GitLab database.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/tags?tag_name=test&ref=master"
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": false
}
The message will be null
when creating a lightweight tag otherwise
it will contain the annotation.
The target will contain the tag objects ID when creating annotated tags, otherwise it will contain the commit ID when creating lightweight tags.
In case of an error,
status code 405
with an explaining error message is returned.
Delete a tag
Deletes a tag of a repository with given name.
DELETE /projects/:id/repository/tags/:tag_name
Parameters:
-
id
(required) - The ID or URL-encoded path of the project owned by the authenticated user -
tag_name
(required) - The name of a tag
Create a new release
Add release notes to the existing Git tag. If there
already exists a release for the given tag, status code 409
is returned.
POST /projects/:id/repository/tags/:tag_name/release
Parameters:
-
id
(required) - The ID or URL-encoded path of the project owned by the authenticated user -
tag_name
(required) - The name of a tag
Request body:
-
description
(required) - Release notes with Markdown support
{
"description": "Amazing release. Wow"
}
Response:
{
"tag_name": "1.0.0",
"description": "Amazing release. Wow"
}
Update a release
Updates the release notes of a given release.
PUT /projects/:id/repository/tags/:tag_name/release
Parameters:
-
id
(required) - The ID or URL-encoded path of the project owned by the authenticated user -
tag_name
(required) - The name of a tag
Request body:
-
description
(required) - Release notes with Markdown support
{
"description": "Amazing release. Wow"
}
Response:
{
"tag_name": "1.0.0",
"description": "Amazing release. Wow"
}
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc