Tags API (FREE)

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:

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 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	This parameter is deprecated for use in GitLab 11.7, and is planned for removal in GitLab 14.0. Use the Releases API instead.

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 is null when creating a lightweight tag. Otherwise, it contains the annotation.

The target contains the tag objects ID when creating annotated tags, otherwise it contains 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:

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 a tag

Create a new release

WARNING: This feature is in its end-of-life process. It is deprecated for use in GitLab 11.7, and is planned for removal in GitLab 14.0. Use the Releases API instead.

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:

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 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

WARNING: This feature is in its end-of-life process. It is deprecated for use in GitLab 11.7, and is planned for removal in GitLab 14.0. Use the Releases API instead.

Updates the release notes of a given release.

PUT /projects/:id/repository/tags/:tag_name/release

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