Search
K
GitHub v3 REST API

Update a reference

patch
http://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
http://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
http://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

Get a tag

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.
get
http://HOSTNAME/api/v3/repos/{owner}/{repo}/git/tags/{tag_sha}

Path Parameters

ownerstringrequired
repostringrequired
tag_shastringrequired

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
get/repos/{owner}/{repo}/git/tags/{tag_sha}
 
application/json

Create a tree

The tree creation API accepts nested entries. If you specify both a tree and a nested path modifying that tree, this endpoint will overwrite the contents of the tree with the new path contents, and create a new tree structure.

If you use this endpoint to add, delete, or modify the file contents in a tree, you will need to commit the tree and then update a branch to point to the commit. For more information see “Create a commit” and “Update a reference.”

post
http://HOSTNAME/api/v3/repos/{owner}/{repo}/git/trees

Path Parameters

ownerstringrequired
repostringrequired

Body

application/json
treearray[object]required

Objects (of path, mode, type, and sha) specifying a tree structure.

Show Child Parameters
base_treestring

The SHA1 of an existing Git tree object which will be used as the base for the new tree. If provided, a new Git tree object will be created from entries in the Git tree object pointed to by base_tree and entries defined in the tree parameter. Entries defined in the tree parameter will overwrite items from base_tree with the same path. If you’re creating new changes on a branch, then normally you’d set base_tree to the SHA1 of the Git tree object of the current latest commit on the branch you’re working on.
If not provided, GitHub will create a new Git tree object from only the entries defined in the tree parameter. If you create a new commit pointing to such a tree, then all files which were a part of the parent commit’s tree and were not defined in the tree parameter will be listed as deleted by the new commit.

Response

application/json

Response

Git Tree

The hierarchy between files in a Git repository.

shastringrequired
urlstring(uri)required
truncatedbooleanrequired
treearray[object]required

Objects specifying a tree structure

Example:[{"path":"file.rb","mode":"100644","type":"blob","size":30,"sha":"44b4fc6d56897b048c772eb4087f854f46256132","url":"https://api.github.com/repos/octocat/Hello-World/git/blobs/44b4fc6d56897b048c772eb4087f854f46256132","properties":{"path":{"type":"string"},"mode":{"type":"string"},"type":{"type":"string"},"size":{"type":"integer"},"sha":{"type":"string"},"url":{"type":"string"}},"required":["path","mode","type","sha","url","size"]}]

Show Child Parameters
post/repos/{owner}/{repo}/git/trees

Body

{ "base_tree": "9fb037999f264ba9a7fc6274d15fa3ae2ab98312", "tree": [ { "path": "file.rb", "mode": "100644", "type": "blob", "sha": "44b4fc6d56897b048c772eb4087f854f46256132" } ] }
 
application/json