Skip to content
forgit api docs

Create a tag object

POST
/repos/{owner}/{repo}/git/tags

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.

Signature verification object

The response will include a verification object that describes the result of verifying the commit’s signature. The following fields are included in the verification object:

Name Type Description
verified boolean Indicates whether GitHub considers the signature in this commit to be verified.
reason string The reason for verified value. Possible values and their meanings are enumerated in table below.
signature string The signature that was extracted from the commit.
payload string The value that was signed.
verified_at string The date the signature was verified by GitHub.

These are the possible values for reason 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.
unknown_signature_type A non-PGP signature was found in the commit.
no_user No user was associated with the committer email address in the commit.
unverified_email The committer email address in the commit was associated with a user, but the email address is not verified on their account.
bad_email The committer email address in the commit 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.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
owner
required
string

The account owner of the repository. The name is not case sensitive.

repo
required
string

The name of the repository without the .git extension. The name is not case sensitive.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
tag
required

The tag’s name. This is typically a version (e.g., “v0.0.1”).

string
message
required

The tag message.

string
object
required

The SHA of the git object this is tagging.

string
type
required

The type of the object we’re tagging. Normally this is a commit but it can also be a tree or a blob.

string
Allowed values: commit tree blob
tagger

An object with information about the individual creating the tag.

object
name
required

The name of the author of the tag

string
email
required

The email of the author of the tag

string
date

When this object was tagged. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

string format: date-time
Examples
Example default 
{
  "tag": "v0.0.1",
  "message": "initial version",
  "object": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
  "type": "commit",
  "tagger": {
    "name": "Monalisa Octocat",
    "email": "octocat@github.com",
    "date": "2011-06-17T14:53:35-07:00"
  }
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Response

Media type application/json
Git Tag

Metadata for a Git tag

object
node_id
required
string
tag
required

Name of the tag

string
sha
required
string
url
required

URL for the tag

string format: uri
message
required

Message describing the purpose of the tag

string
tagger
required
object
date
required
string
email
required
string
name
required
string
object
required
object
sha
required
string
type
required
string
url
required
string format: uri
verification
Verification
object
verified
required
boolean
reason
required
string
payload
required
string
nullable
signature
required
string
nullable
verified_at
required
string
nullable
Examples
Example default 
{
  "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": "Monalisa Octocat",
    "email": "octocat@github.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,
    "verified_at": null
  }
}

Headers

Section titled “ Headers ”
Location
string
Example 
https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac

409

Section titled “ 409 ”

Conflict

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

422

Section titled “ 422 ”

Validation failed, or the endpoint has been spammed.

Media type application/json
Validation Error

Validation Error

object
message
required
string
documentation_url
required
string
errors
Array<object>
object
resource
string
field
string
message
string
code
required
string
index
integer
value
One of:
string
nullable
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    {
      "resource": "example",
      "field": "example",
      "message": "example",
      "code": "example",
      "index": 1,
      "value": [
        "example"
      ]
    }
  ]
}