Git Tags

A Git tag is similar to a Git reference, but the Git commit that it points to never changes. Git tags are helpful when you want to point to specific releases. These endpoints allow you to read and write tag objects to your Git database on GitHub. See the Git Database API for more details. The Git tags API only supports annotated tag objects, not lightweight tags.

• Get a tag
• Create a tag object
• Tag signature verification

Get a tag

GET /repos/:owner/:repo/git/tags/:tag_sha

Response

Status: 200 OK

{
  "node_id": "MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw==",
  "tag": "v0.0.1",
  "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "message": "initial version",
  "tagger": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com",
    "date": "2014-11-07T22:01:45Z"
  },
  "object": {
    "type": "commit",
    "sha": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c"
  },
  "verification": {
    "verified": false,
    "reason": "unsigned",
    "signature": null,
    "payload": null
  }
}

Create a tag object

Note that creating a tag object does not create the reference that makes a tag in Git. If you want to create an annotated tag in Git, you have to do this call to create the tag object, and then create the refs/tags/[tag] reference. If you want to create a lightweight tag, you only have to create the tag reference - this call would be unnecessary.

POST /repos/:owner/:repo/git/tags

Parameters

Name	Type	Description
tag	string	Required. The tag's name. This is typically a version (e.g., "v0.0.1").
message	string	Required. The tag message.
object	string	Required. The SHA of the git object this is tagging.
type	string	Required. The type of the object we're tagging. Normally this is a commit but it can also be a tree or a blob.
tagger	object	An object with information about the individual creating the tag.

The tagger object contains the following keys:

Name	Type	Description
name	string	The name of the author of the tag
email	string	The email of the author of the tag
date	string	When this object was tagged. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

Example input

{
  "tag": "v0.0.1",
  "message": "initial version\n",
  "object": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
  "type": "commit",
  "tagger": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com",
    "date": "2011-06-17T14:53:35-07:00"
  }
}

Response

Status: 201 Created
Location: https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac

{
  "node_id": "MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw==",
  "tag": "v0.0.1",
  "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "message": "initial version",
  "tagger": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com",
    "date": "2014-11-07T22:01:45Z"
  },
  "object": {
    "type": "commit",
    "sha": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c"
  },
  "verification": {
    "verified": false,
    "reason": "unsigned",
    "signature": null,
    "payload": null
  }
}

Tag signature verification

GET /repos/:owner/:repo/git/tags/:tag_sha

Response

Status: 200 OK

{
  "node_id": "MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw==",
  "tag": "v0.0.1",
  "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac",
  "message": "initial version",
  "tagger": {
    "name": "Scott Chacon",
    "email": "schacon@gmail.com",
    "date": "2014-11-07T22:01:45Z"
  },
  "object": {
    "type": "commit",
    "sha": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c"
  },
  "verification": {
    "verified": true,
    "reason": "valid",
    "signature": "-----BEGIN PGP MESSAGE-----\n...\n-----END PGP MESSAGE-----",
    "payload": "object c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c\n..."
  }
}

The verification object

The response will include a verification field whose value is an object describing the result of verifying the tag's signature. The following fields are included in the verification object:

Name	Type	Description
verified	boolean	Does GitHub consider the signature in this tag to be verified?
reason	string	The reason for verified value. Possible values and their meanings are enumerated in the table below.
signature	string	The signature that was extracted from the tag.
payload	string	The value that was signed.

The reason field

The following are possible reasons that may be included in the verification object:

Value	Description
expired_key	The key that made the signature is expired.
not_signing_key	The "signing" flag is not among the usage flags in the GPG key that made the signature.
gpgverify_error	There was an error communicating with the signature-verification service.
gpgverify_unavailable	The signature-verification service is currently unavailable.
unsigned	The object does not include a signature.
unkown_signature_type	A non-PGP signature was found in the tag.
no_user	No user was associated with the tagger email address in the tag.
unverified_email	The tagger email address in the tag was associated with a user, but the email address is not verified on her/his account.
bad_email	The tagger email address in the tag is not included in the identities of the PGP key that made the signature.
unknown_key	The key that made the signature has not been registered with any user's account.
malformed_signature	There was an error parsing the signature.
invalid	The signature could not be cryptographically verified using the key whose key-id was found in the signature.
valid	None of the above errors applied, so the signature is considered to be verified.