Search
K
GitHub v3 REST API

Create a commit

Creates a new Git commit object.

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/commits

Path Parameters

ownerstringrequired
repostringrequired

Body

application/json
messagestringrequired

The commit message

treestringrequired

The SHA of the tree object this commit points to

parentsarray[string]

The SHAs of the commits that were the parents of this commit. If omitted or empty, the commit will be written as a root commit. For a single parent, an array of one SHA should be provided; for a merge commit, an array of more than one should be provided.

authorobject

Information about the author of the commit. By default, the author will be the authenticated user and the current date. See the author and committer object below for details.

Show Child Parameters
committerobject

Information about the person who is making the commit. By default, committer will use the information set in author. See the author and committer object below for details.

Show Child Parameters
signaturestring

The PGP signature of the commit. GitHub adds the signature to the gpgsig header of the created commit. For a commit signature to be verifiable by Git or GitHub, it must be an ASCII-armored detached PGP signature over the string commit as it would be written to the object database. To pass a signature parameter, you need to first manually create a valid PGP signature, which can be complicated. You may find it easier to use the command line to create signed commits.

Response

application/json

Response

Git Commit

Low-level Git commit operations within a repository

shastringrequired

SHA for the commit

Example:7638417db6d59f3c431d3e1f261cc637155684cd

node_idstringrequired
urlstring(uri)required
authorobjectrequired

Identifying information for the git-user

Show Child Parameters
committerobjectrequired

Identifying information for the git-user

Show Child Parameters
messagestringrequired

Message describing the purpose of the commit

Example:Fix #42

treeobjectrequired
Show Child Parameters
parentsarray[object]required
Show Child Parameters
verificationobjectrequired
Show Child Parameters
html_urlstring(uri)required
post/repos/{owner}/{repo}/git/commits

Body

{ "message": "my commit message", "author": { "name": "Mona Octocat", "email": "octocat@github.com", "date": "2008-07-09T16:13:30+12:00" }, "parents": [ "7d1b31e74ee336d15cbd21741bc88a537ed063a0" ], "tree": "827efc6d56897b048c772eb4087f854f46256132", "signature": "-----BEGIN PGP SIGNATURE-----\n\niQIzBAABAQAdFiEESn/54jMNIrGSE6Tp6cQjvhfv7nAFAlnT71cACgkQ6cQjvhfv\n7nCWwA//XVqBKWO0zF+bZl6pggvky3Oc2j1pNFuRWZ29LXpNuD5WUGXGG209B0hI\nDkmcGk19ZKUTnEUJV2Xd0R7AW01S/YSub7OYcgBkI7qUE13FVHN5ln1KvH2all2n\n2+JCV1HcJLEoTjqIFZSSu/sMdhkLQ9/NsmMAzpf/iIM0nQOyU4YRex9eD1bYj6nA\nOQPIDdAuaTQj1gFPHYLzM4zJnCqGdRlg0sOM/zC5apBNzIwlgREatOYQSCfCKV7k\nnrU34X8b9BzQaUx48Qa+Dmfn5KQ8dl27RNeWAqlkuWyv3pUauH9UeYW+KyuJeMkU\n+NyHgAsWFaCFl23kCHThbLStMZOYEnGagrd0hnm1TPS4GJkV4wfYMwnI4KuSlHKB\njHl3Js9vNzEUQipQJbgCgTiWvRJoK3ENwBTMVkKHaqT4x9U4Jk/XZB6Q8MA09ezJ\n3QgiTjTAGcum9E9QiJqMYdWQPWkaBIRRz5cET6HPB48YNXAAUsfmuYsGrnVLYbG+\nUpC6I97VybYHTy2O9XSGoaLeMI9CsFn38ycAxxbWagk5mhclNTP5mezIq6wKSwmr\nX11FW3n1J23fWZn5HJMBsRnUCgzqzX3871IqLYHqRJ/bpZ4h20RhTyPj5c/z7QXp\neSakNQMfbbMcljkha+ZMuVQX1K9aRlVqbmv3ZMWh+OijLYVU2bc=\n=5Io4\n-----END PGP SIGNATURE-----\n" }
 
application/json

Get a commit

Gets a Git commit object.

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
{protocol}://{hostname}/api/v3/repos/{owner}/{repo}/git/commits/{commit_sha}

Path Parameters

ownerstringrequired
repostringrequired
commit_shastringrequired

commit_sha parameter

Response

application/json

Response

Git Commit

Low-level Git commit operations within a repository

shastringrequired

SHA for the commit

Example:7638417db6d59f3c431d3e1f261cc637155684cd

node_idstringrequired
urlstring(uri)required
authorobjectrequired

Identifying information for the git-user

Show Child Parameters
committerobjectrequired

Identifying information for the git-user

Show Child Parameters
messagestringrequired

Message describing the purpose of the commit

Example:Fix #42

treeobjectrequired
Show Child Parameters
parentsarray[object]required
Show Child Parameters
verificationobjectrequired
Show Child Parameters
html_urlstring(uri)required
get/repos/{owner}/{repo}/git/commits/{commit_sha}
 
application/json

List matching references

Returns an array of references from your Git database that match the supplied name. 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 exist in the repository, but existing refs start with :ref, they will be returned as an array.

When you use this endpoint without providing a :ref, it will return an array of all the references from your Git database, including notes and stashes if they exist on the server. Anything in the namespace is returned, not just heads and tags.

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”.

If you request matching references for a branch named feature but the branch feature doesn’t exist, the response can still include other matching head refs that start with the word feature, such as featureA and featureB.

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

Query Parameters

per_pageinteger

Results per page (max 100)

Default:30

pageinteger

Page number of the results to fetch.

Default:1

Path Parameters

ownerstringrequired
repostringrequired
refstringrequired

ref parameter

Response

200 application/json

Response

Git references within a repository

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

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