Tags

Use this API to manage Git tags. This API also returns X.509 signature information from signed tags.

List all project repository tags

GET /api/v4/projects/{id}/repository/tags

Lists all repository tags from a project, sorted by update date and time in descending order.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`sort` Query	String	Return tags sorted in updated by `asc` or `desc` order Allowed values: `asc`, `desc` Default: `desc`
`order_by` Query	String	Return tags ordered by `name`, `updated`, `version` fields Allowed values: `name`, `updated`, `version` Default: `updated`
`search` Query	String	Return list of tags matching the search criteria
`page_token` Query	String	Name of tag to start the pagination from
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesTag
`400`	Bad Request	—
`403`	Unauthenticated	—
`404`	Not found	—
`422`	Unprocessable entity	—
`503`	Service unavailable	—

Create a tag

POST /api/v4/projects/{id}/repository/tags

Creates a tag in the repository that points to a specified reference.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`message`	String	Specifying a message creates an annotated tag Example: `Release 1.0.0`
`ref` Required	String	The commit sha or branch name Example: `2695effb5807a22ff3d138d593fd856244e155e7`
`tag_name` Required	String	The name of the tag Example: `v.1.0.0`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesTag
`400`	Bad request	—
`403`	Unauthenticated	—
`404`	Not found	—
`429`	Too many requests	—

Retrieve a single repository tag

GET /api/v4/projects/{id}/repository/tags/{tag_name}

Retrieves a repository tag with a specified name. This endpoint can be accessed without authentication if the repository is publicly accessible.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The name of the tag

Responses

Code	Description	Schema
`200`	OK	APIEntitiesTag
`400`	Bad Request	—
`403`	Unauthenticated	—
`404`	Not found	—

Delete a tag

DELETE /api/v4/projects/{id}/repository/tags/{tag_name}

Deletes a specified repository tag.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The name of the tag

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad request	—
`403`	Unauthenticated	—
`404`	Not found	—
`412`	Precondition failed	—

Retrieve X.509 signature of a tag

GET /api/v4/projects/{id}/repository/tags/{tag_name}/signature

Retrieves the X.509 signature from a signed tag. Unsigned tags return a 404 Not Found response.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`tag_name` Path, required	String	The name of the tag

Responses

Code	Description	Schema
`200`	OK	APIEntitiesTagSignature
`400`	Bad Request	—
`404`	Not found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCommit

Property	Type	Description
`author_email`	String	Example: `john@example.com`
`author_name`	String	Example: `John Smith`
`authored_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committed_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committer_email`	String	Example: `jack@example.com`
`committer_name`	String	Example: `Jack Smith`
`created_at`	String (date-time)	Example: `2017-07-26T11:08:53.000+02:00`
`extended_trailers`	Object	Example: `{"Signed-off-by":["John Doe \u003cjohndoe@gitlab.com\u003e","Jane Doe \u003cjanedoe@gitlab.com\u003e"]}`
`id`	String	Example: `2695effb5807a22ff3d138d593fd856244e155e7`
`message`	String	Example: `Initial commit`
`parent_ids`	Array of strings	Example: `["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]`
`short_id`	String	Example: `2695effb`
`title`	String	Example: `Initial commit`
`trailers`	Object	Example: `{"Merged-By":"Jane Doe janedoe@gitlab.com"}`
`web_url`	String	Example: `https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746`

APIEntitiesTag

Property	Type	Description
`commit`	APIEntitiesCommit	—
`created_at`	String (date-time)	Example: `2023-10-12T02:16:52.000Z`
`message`	String	Example: `Release v1.0.0`
`name`	String	Example: `v1.0.0`
`protected`	Boolean	Example: `true`
`release`	APIEntitiesTagRelease	—
`target`	String	Example: `2695effb5807a22ff3d138d593fd856244e155e7`

APIEntitiesTagRelease

Property	Type	Description
`description`	String	Example: `Amazing release. Wow`
`tag_name`	String	Example: `1.0.0`

APIEntitiesTagSignature

Property	Type	Description
`signature`	Object	—
`signature_type`	String	Example: `PGP`

List all project repository tags

Create a tag

Retrieve a single repository tag

Delete a tag

Retrieve X.509 signature of a tag

Schemas

APIEntitiesCommit

APIEntitiesTag

APIEntitiesTagRelease

APIEntitiesTagSignature

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC compliance report

Thank you

Error

Request partner program details

Request received

Error