Search
K
GitHub v3 REST API

Get a reference

Returns a single reference from your Git database. The :ref in the URL must be formatted as heads/<branch name> for branches and tags/<tag name> for tags. If the :ref doesn’t match an existing ref, a 404 is returned.

Note: You need to explicitly request a pull request to trigger a test merge commit, which checks the mergeability of pull requests. For more information, see “Checking mergeability of pull requests”.

get
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/git/ref/{ref}

Path Parameters

ownerstringrequired
repostringrequired
refstringrequired

ref parameter

Response

application/json

Response

Git Reference

Git references within a repository

refstringrequired
node_idstringrequired
urlstring(uri)required
objectobjectrequired
Show Child Parameters
get/repos/{owner}/{repo}/git/ref/{ref}
 
application/json

Create a reference

Creates a reference for your repository. You are unable to create new references for empty repositories, even if the commit SHA-1 hash used exists. Empty repositories are repositories without branches.

post
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/git/refs

Path Parameters

ownerstringrequired
repostringrequired

Body

application/json
refstringrequired

The name of the fully qualified reference (ie: refs/heads/master). If it doesn’t start with ‘refs’ and have at least two slashes, it will be rejected.

shastringrequired

The SHA1 value for this reference.

keystring

Example:"refs/heads/newbranch"

Response

application/json

Response

Git Reference

Git references within a repository

refstringrequired
node_idstringrequired
urlstring(uri)required
objectobjectrequired
Show Child Parameters
post/repos/{owner}/{repo}/git/refs

Body

{ "ref": "refs/heads/featureA", "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd" }
 
application/json

Update a reference

patch
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/git/refs/{ref}

Path Parameters

ownerstringrequired
repostringrequired
refstringrequired

ref parameter

Body

application/json
shastringrequired

The SHA1 value to set this reference to

forceboolean

Indicates whether to force the update or to make sure the update is a fast-forward update. Leaving this out or setting it to false will make sure you’re not overwriting work.

Default:false

Response

application/json

Response

Git Reference

Git references within a repository

refstringrequired
node_idstringrequired
urlstring(uri)required
objectobjectrequired
Show Child Parameters
patch/repos/{owner}/{repo}/git/refs/{ref}

Body

{ "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd", "force": true }
 
application/json

Delete a reference

delete
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/git/refs/{ref}

Path Parameters

ownerstringrequired
repostringrequired
refstringrequired

ref parameter

Response

Response

delete/repos/{owner}/{repo}/git/refs/{ref}
 

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.

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.

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 her/his 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.
post
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/git/tags

Path Parameters

ownerstringrequired
repostringrequired

Body

application/json
tagstringrequired

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

messagestringrequired

The tag message.

objectstringrequired

The SHA of the git object this is tagging.

typestringrequired

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

Allowed values:committreeblob

taggerobject

An object with information about the individual creating the tag.

Show Child Parameters

Response

application/json

Response

Git Tag

Metadata for a Git tag

node_idstringrequired

Example:MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw==

tagstringrequired

Name of the tag

Example:v0.0.1

shastringrequired

Example:940bd336248efae0f9ee5bc7b2d5c985887b16ac

urlstring(uri)required

URL for the tag

Example:https://api.github.com/repositories/42/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac

messagestringrequired

Message describing the purpose of the tag

Example:Initial public release

taggerobjectrequired
Show Child Parameters
objectobjectrequired
Show Child Parameters
verificationobject
Show Child Parameters
post/repos/{owner}/{repo}/git/tags

Body

{ "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" } }
 
application/json