2020-07-30 12:09:33 +00:00
---
stage: Create
group: Source Code
2020-11-26 06:09:20 +00:00
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
2020-07-30 12:09:33 +00:00
type: reference, api
---
2017-05-18 08:49:03 +00:00
# Tags API
2015-11-12 14:41:13 +00:00
## List project repository tags
2016-12-02 13:33:29 +00:00
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.
2015-11-12 14:41:13 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2015-11-12 14:41:13 +00:00
GET /projects/:id/repository/tags
```
Parameters:
2017-12-14 13:42:15 +00:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string| yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) 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` |
2019-11-05 12:06:20 +00:00
| `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. |
2019-01-21 10:01:00 +00:00
2020-05-21 06:08:25 +00:00
> Support for `search` was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54401) in GitLab 11.8.
2015-11-12 14:41:13 +00:00
```json
[
{
"commit": {
2017-07-26 13:53:07 +00:00
"id": "2695effb5807a22ff3d138d593fd856244e155e7",
"short_id": "2695effb",
"title": "Initial commit",
"created_at": "2017-07-26T11:08:53.000+02:00",
"parent_ids": [
"2a4b78934375d7f53875269ffd4f45fd83a84ebe"
],
"message": "Initial commit",
2015-11-12 14:41:13 +00:00
"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",
2017-07-26 13:53:07 +00:00
"committed_date": "2012-05-28T04:42:42-07:00"
2015-11-12 14:41:13 +00:00
},
2015-11-12 22:52:02 +00:00
"release": {
2015-11-21 16:29:26 +00:00
"tag_name": "1.0.0",
2015-11-12 22:52:02 +00:00
"description": "Amazing release. Wow"
},
2015-11-12 14:41:13 +00:00
"name": "v1.0.0",
2018-04-06 14:58:45 +00:00
"target": "2695effb5807a22ff3d138d593fd856244e155e7",
2019-09-08 18:49:29 +00:00
"message": null,
"protected": true
2015-11-12 14:41:13 +00:00
}
]
```
2016-04-06 11:59:50 +00:00
## Get a single repository tag
2016-12-02 13:33:29 +00:00
Get a specific repository tag determined by its name. This endpoint can be
accessed without authentication if the repository is publicly accessible.
2016-04-06 11:59:50 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2016-04-06 11:59:50 +00:00
GET /projects/:id/repository/tags/:tag_name
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2017-04-08 08:54:00 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
2016-04-06 11:59:50 +00:00
| `tag_name` | string | yes | The name of the tag |
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/repository/tags/v1.0.0"
2016-04-06 11:59:50 +00:00
```
Example Response:
```json
{
"name": "v5.0.0",
"message": null,
2018-04-06 14:58:45 +00:00
"target": "60a8ff033665e1207714d6670fcd7b65304ec02f",
2016-04-06 11:59:50 +00:00
"commit": {
"id": "60a8ff033665e1207714d6670fcd7b65304ec02f",
2017-07-26 13:53:07 +00:00
"short_id": "60a8ff03",
"title": "Initial commit",
"created_at": "2017-07-26T11:08:53.000+02:00",
2016-04-06 11:59:50 +00:00
"parent_ids": [
"f61c062ff8bcbdb00e0a1b3317a91aed6ceee06b"
],
2017-07-26 13:53:07 +00:00
"message": "v5.0.0\n",
2016-04-06 11:59:50 +00:00
"author_name": "Arthur Verschaeve",
"author_email": "contact@arthurverschaeve.be",
2017-07-26 13:53:07 +00:00
"authored_date": "2015-02-01T21:56:31.000+01:00",
2016-04-06 11:59:50 +00:00
"committer_name": "Arthur Verschaeve",
2017-07-26 13:53:07 +00:00
"committer_email": "contact@arthurverschaeve.be",
"committed_date": "2015-02-01T21:56:31.000+01:00"
2016-04-06 11:59:50 +00:00
},
2019-09-08 18:49:29 +00:00
"release": null,
"protected": false
2016-04-06 11:59:50 +00:00
}
```
2015-11-12 14:41:13 +00:00
## Create a new tag
2015-11-16 09:11:16 +00:00
Creates a new tag in the repository that points to the supplied ref.
2015-11-12 14:41:13 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2015-11-12 14:41:13 +00:00
POST /projects/:id/repository/tags
```
Parameters:
2020-09-08 15:08:41 +00:00
| Attribute | Type | Required | Description |
| --------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `tag_name` | string | yes | The name of a tag |
| `ref` | string | yes | Create tag using commit SHA, another tag name, or branch name |
| `message` | string | no | Creates annotated tag |
| `release_description` | string | no | Add release notes to the Git tag and store it in the GitLab database |
2015-11-12 14:41:13 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-09-19 09:06:27 +00:00
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:
2015-11-12 14:41:13 +00:00
```json
{
"commit": {
2017-07-26 13:53:07 +00:00
"id": "2695effb5807a22ff3d138d593fd856244e155e7",
"short_id": "2695effb",
"title": "Initial commit",
"created_at": "2017-07-26T11:08:53.000+02:00",
"parent_ids": [
"2a4b78934375d7f53875269ffd4f45fd83a84ebe"
],
"message": "Initial commit",
2015-11-12 14:41:13 +00:00
"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",
2017-07-26 13:53:07 +00:00
"committed_date": "2012-05-28T04:42:42-07:00"
2015-11-12 14:41:13 +00:00
},
2015-11-12 22:52:02 +00:00
"release": {
2015-11-21 16:29:26 +00:00
"tag_name": "1.0.0",
2015-11-12 22:52:02 +00:00
"description": "Amazing release. Wow"
},
2015-11-12 14:41:13 +00:00
"name": "v1.0.0",
2018-10-26 07:42:54 +00:00
"target": "2695effb5807a22ff3d138d593fd856244e155e7",
2019-09-08 18:49:29 +00:00
"message": null,
"protected": false
2015-11-12 14:41:13 +00:00
}
```
2019-07-12 08:09:23 +00:00
2017-09-18 07:20:09 +00:00
The message will be `null` when creating a lightweight tag otherwise
2015-11-12 14:41:13 +00:00
it will contain the annotation.
2018-04-06 14:58:45 +00:00
The target will contain the tag objects ID when creating annotated tags,
otherwise it will contain the commit ID when creating lightweight tags.
2016-11-24 17:28:52 +00:00
In case of an error,
status code `405` with an explaining error message is returned.
2015-11-12 22:52:02 +00:00
2016-01-08 09:10:04 +00:00
## Delete a tag
2016-11-24 17:28:52 +00:00
Deletes a tag of a repository with given name.
2016-01-08 09:10:04 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2016-01-08 09:10:04 +00:00
DELETE /projects/:id/repository/tags/:tag_name
```
Parameters:
2020-09-08 15:08:41 +00:00
| Attribute | Type | Required | Description |
| ---------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `tag_name` | string | yes | The name of a tag |
2016-01-08 09:10:04 +00:00
2015-11-21 17:51:41 +00:00
## Create a new release
2015-11-12 22:52:02 +00:00
2019-08-23 08:50:24 +00:00
Add release notes to the existing Git tag. If there
2016-11-24 17:28:52 +00:00
already exists a release for the given tag, status code `409` is returned.
2015-11-12 22:52:02 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2015-11-21 17:51:41 +00:00
POST /projects/:id/repository/tags/:tag_name/release
2015-11-12 22:52:02 +00:00
```
Parameters:
2020-09-08 15:08:41 +00:00
| Attribute | Type | Required | Description |
| ---------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `tag_name` | string | yes | The name of a tag |
2018-05-03 08:53:20 +00:00
Request body:
2019-11-28 03:06:32 +00:00
- `description` (required) - Release notes with Markdown support
2015-11-12 22:52:02 +00:00
2018-05-03 08:53:20 +00:00
```json
{
"description": "Amazing release. Wow"
}
```
Response:
2015-11-12 22:52:02 +00:00
```json
{
2015-11-21 16:29:26 +00:00
"tag_name": "1.0.0",
2015-11-12 22:52:02 +00:00
"description": "Amazing release. Wow"
}
```
2015-11-21 21:34:53 +00:00
## Update a release
2016-11-24 17:28:52 +00:00
Updates the release notes of a given release.
2015-11-21 21:34:53 +00:00
2020-02-29 03:07:51 +00:00
```plaintext
2015-11-21 21:34:53 +00:00
PUT /projects/:id/repository/tags/:tag_name/release
```
Parameters:
2020-09-08 15:08:41 +00:00
| Attribute | Type | Required | Description |
| ---------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `tag_name` | string | yes | The name of a tag |
2018-05-03 08:53:20 +00:00
Request body:
2019-11-28 03:06:32 +00:00
- `description` (required) - Release notes with Markdown support
2015-11-21 21:34:53 +00:00
2018-05-03 08:53:20 +00:00
```json
{
"description": "Amazing release. Wow"
}
```
Response:
2015-11-21 21:34:53 +00:00
```json
{
"tag_name": "1.0.0",
"description": "Amazing release. Wow"
}
2016-04-06 11:59:50 +00:00
```