Tags

This tags API only deals with tag objects - so only annotated tags, not lightweight tags.

Note: To help with migrating from our REST API v3 to GraphQL API v4, we're introducing a preview period to include the GraphQL node_id in the response for many REST API v3 resources. See the blog post for full details. To access node_id during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.jean-grey-preview+json

Warning: The API may change without advance notice during the preview period. Preview features are not supported for production use. If you experience any issues, contact GitHub support.

Get a Tag 

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

Response

Status: 200 OK

{
  "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 The tag
message string The tag message
object string The SHA of the git object this is tagging
type string 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

{
  "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/:sha

Response

Status: 200 OK

{
  "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.