Help us learn about your current experience with the documentation. Take the survey.

Tags API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

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

List all project repository tags

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

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`order_by`	string	No	Return tags ordered by `name`, `updated`, or `version`. `version` sorts by semantic version number. Default is `updated`.
`page`	integer	No	Current page number for pagination. Default is `1`.
`page_token`	string	No	Name of tag to start the pagination from. Used for keyset pagination.
`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.
`sort`	string	No	Return tags sorted in `asc` or `desc` order. Default is `desc`.

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`commit`	object	Commit information associated with the tag.
`commit.author_email`	string	Email address of the commit author.
`commit.author_name`	string	Name of the commit author.
`commit.authored_date`	string	Date when the commit was authored in ISO 8601 format.
`commit.committed_date`	string	Date when the commit was committed in ISO 8601 format.
`commit.committer_email`	string	Email address of the committer.
`commit.committer_name`	string	Name of the committer.
`commit.created_at`	string	Date when the commit was created in ISO 8601 format.
`commit.id`	string	Full SHA of the commit.
`commit.message`	string	Commit message.
`commit.parent_ids`	array	Array of parent commit SHAs.
`commit.short_id`	string	Short SHA of the commit.
`commit.title`	string	Title of the commit.
`created_at`	string	Date when the tag was created in ISO 8601 format.
`message`	string	Tag message.
`name`	string	Name of the tag.
`protected`	boolean	If `true`, the tag is protected.
`release`	object	Release information associated with the tag.
`release.description`	string	Description of the release.
`release.tag_name`	string	Tag name of the release.
`target`	string	SHA that the tag points to.

Example request:

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

Retrieve a single repository tag

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

GET /projects/:id/repository/tags/:tag_name

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`tag_name`	string	Yes	Name of a tag.

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`commit`	object	Commit information associated with the tag.
`commit.author_email`	string	Email address of the commit author.
`commit.author_name`	string	Name of the commit author.
`commit.authored_date`	string	Date when the commit was authored in ISO 8601 format.
`commit.committed_date`	string	Date when the commit was committed in ISO 8601 format.
`commit.committer_email`	string	Email address of the committer.
`commit.committer_name`	string	Name of the committer.
`commit.created_at`	string	Date when the commit was created in ISO 8601 format.
`commit.id`	string	Full SHA of the commit.
`commit.message`	string	Commit message.
`commit.parent_ids`	array	Array of parent commit SHAs.
`commit.short_id`	string	Short SHA of the commit.
`commit.title`	string	Title of the commit.
`created_at`	string	Date when the tag was created in ISO 8601 format.
`message`	string	Tag message.
`name`	string	Name of the tag.
`protected`	boolean	If `true`, the tag is protected.
`release`	object	Release information associated with the tag.
`target`	string	SHA that the tag points to.

Example request:

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

This endpoint is rate limited for each project. The default is 100 requests every 30 minutes, configurable with the tags_create_limit application setting. Set the limit to 0 to disable it. The limit is shared between this endpoint, the GraphQL tagCreate mutation, tag creation in the UI, and the /tag quick action. The limit applies to the project, not to you. You can receive 429 Too Many Requests after other users of the project reach the limit.```

POST /projects/:id/repository/tags

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`ref`	string	Yes	Create a tag from a commit SHA, another tag name, or branch name.
`tag_name`	string	Yes	Name of a tag.
`message`	string	No	Create an annotated tag.

If successful, returns 201 Created and the following response attributes:

Attribute	Type	Description
`commit`	object	Commit information associated with the tag.
`commit.author_email`	string	Email address of the commit author.
`commit.author_name`	string	Name of the commit author.
`commit.authored_date`	string	Date when the commit was authored in ISO 8601 format.
`commit.committed_date`	string	Date when the commit was committed in ISO 8601 format.
`commit.committer_email`	string	Email address of the committer.
`commit.committer_name`	string	Name of the committer.
`commit.created_at`	string	Date when the commit was created in ISO 8601 format.
`commit.id`	string	Full SHA of the commit.
`commit.message`	string	Commit message.
`commit.parent_ids`	array	Array of parent commit SHAs.
`commit.short_id`	string	Short SHA of the commit.
`commit.title`	string	Title of the commit.
`created_at`	string	Date when the tag was created in ISO 8601 format.
`message`	string	Tag message.
`name`	string	Name of the tag.
`protected`	boolean	If `true`, the tag is protected.
`release`	object	Release information associated with the tag.
`target`	string	SHA that the tag points to.

Example request:

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 repository tag with the specified name.

DELETE /projects/:id/repository/tags/:tag_name

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`tag_name`	string	Yes	Name of a tag.

Retrieve X.509 signature of a tag

Retrieves 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

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`tag_name`	string	Yes	Name of a tag.

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`signature_type`	string	Type of signature (`X509`).
`verification_status`	string	Verification status of the signature.
`x509_certificate`	object	X.509 certificate information.
`x509_certificate.certificate_status`	string	Status of the certificate.
`x509_certificate.email`	string	Email address from the certificate.
`x509_certificate.id`	integer	ID of the certificate.
`x509_certificate.serial_number`	integer	Serial number of the certificate.
`x509_certificate.subject`	string	Subject of the certificate.
`x509_certificate.subject_key_identifier`	string	Subject key identifier of the certificate.
`x509_certificate.x509_issuer`	object	Issuer information of the certificate.
`x509_certificate.x509_issuer.crl_url`	string	Certificate revocation list URL.
`x509_certificate.x509_issuer.id`	integer	ID of the issuer.
`x509_certificate.x509_issuer.subject`	string	Subject of the issuer.
`x509_certificate.x509_issuer.subject_key_identifier`	string	Subject key identifier of the issuer.

Example request:

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