Skip to main content

This version of GitHub Enterprise was discontinued on 2022-10-12. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Git commits

The Git commits API lets you read and write commit objects to your Git database on GitHub Enterprise Server.

About the Git commits API

A Git commit is a snapshot of the hierarchy (Git tree) and the contents of the files (Git blob) in a Git repository. These endpoints allow you to read and write commit objects to your Git database on GitHub Enterprise Server.

Create a commit

Works with GitHub Apps

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:

NameTypeDescription
verifiedbooleanIndicates whether GitHub considers the signature in this commit to be verified.
reasonstringThe reason for verified value. Possible values and their meanings are enumerated in the table below.
signaturestringThe signature that was extracted from the commit.
payloadstringThe value that was signed.

These are the possible values for reason in the verification object:

ValueDescription
expired_keyThe key that made the signature is expired.
not_signing_keyThe "signing" flag is not among the usage flags in the GPG key that made the signature.
gpgverify_errorThere was an error communicating with the signature verification service.
gpgverify_unavailableThe signature verification service is currently unavailable.
unsignedThe object does not include a signature.
unknown_signature_typeA non-PGP signature was found in the commit.
no_userNo user was associated with the committer email address in the commit.
unverified_emailThe committer email address in the commit was associated with a user, but the email address is not verified on her/his account.
bad_emailThe committer email address in the commit is not included in the identities of the PGP key that made the signature.
unknown_keyThe key that made the signature has not been registered with any user's account.
malformed_signatureThere was an error parsing the signature.
invalidThe signature could not be cryptographically verified using the key whose key-id was found in the signature.
validNone of the above errors applied, so the signature is considered to be verified.

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

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

repostringRequired

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

Body parameters
Name, Type, Description
messagestringRequired

The commit message

treestringRequired

The SHA of the tree object this commit points to

parentsarray of strings

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.

Name, Type, Description
namestringRequired

The name of the author (or committer) of the commit

emailstringRequired

The email of the author (or committer) of the commit

datestring

Indicates when this commit was authored (or committed). This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

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.

Name, Type, Description
namestring

The name of the author (or committer) of the commit

emailstring

The email of the author (or committer) of the commit

datestring

Indicates when this commit was authored (or committed). This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

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.

HTTP response status codes

Status codeDescription
201

Created

404

Resource not found

422

Validation failed, or the endpoint has been spammed.

Code samples

post/repos/{owner}/{repo}/git/commits
curl \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/git/commits \ -d '{"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"}'

Response

Status: 201
{ "sha": "7638417db6d59f3c431d3e1f261cc637155684cd", "node_id": "MDY6Q29tbWl0NzYzODQxN2RiNmQ1OWYzYzQzMWQzZTFmMjYxY2M2MzcxNTU2ODRjZA==", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd", "author": { "date": "2014-11-07T22:01:45Z", "name": "Monalisa Octocat", "email": "octocat@github.com" }, "committer": { "date": "2014-11-07T22:01:45Z", "name": "Monalisa Octocat", "email": "octocat@github.com" }, "message": "my commit message", "tree": { "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/827efc6d56897b048c772eb4087f854f46256132", "sha": "827efc6d56897b048c772eb4087f854f46256132" }, "parents": [ { "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7d1b31e74ee336d15cbd21741bc88a537ed063a0", "sha": "7d1b31e74ee336d15cbd21741bc88a537ed063a0", "html_url": "https://github.com/octocat/Hello-World/commit/7d1b31e74ee336d15cbd21741bc88a537ed063a0" } ], "verification": { "verified": false, "reason": "unsigned", "signature": null, "payload": null }, "html_url": "https://github.com/octocat/Hello-World/commit/7638417db6d59f3c431d3e1f261cc637155684cd" }

Get a commit

Works with GitHub Apps

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:

NameTypeDescription
verifiedbooleanIndicates whether GitHub considers the signature in this commit to be verified.
reasonstringThe reason for verified value. Possible values and their meanings are enumerated in the table below.
signaturestringThe signature that was extracted from the commit.
payloadstringThe value that was signed.

These are the possible values for reason in the verification object:

ValueDescription
expired_keyThe key that made the signature is expired.
not_signing_keyThe "signing" flag is not among the usage flags in the GPG key that made the signature.
gpgverify_errorThere was an error communicating with the signature verification service.
gpgverify_unavailableThe signature verification service is currently unavailable.
unsignedThe object does not include a signature.
unknown_signature_typeA non-PGP signature was found in the commit.
no_userNo user was associated with the committer email address in the commit.
unverified_emailThe committer email address in the commit was associated with a user, but the email address is not verified on her/his account.
bad_emailThe committer email address in the commit is not included in the identities of the PGP key that made the signature.
unknown_keyThe key that made the signature has not been registered with any user's account.
malformed_signatureThere was an error parsing the signature.
invalidThe signature could not be cryptographically verified using the key whose key-id was found in the signature.
validNone of the above errors applied, so the signature is considered to be verified.

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
ownerstringRequired

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

repostringRequired

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

commit_shastringRequired

The SHA of the commit.

HTTP response status codes

Status codeDescription
200

OK

404

Resource not found

Code samples

get/repos/{owner}/{repo}/git/commits/{commit_sha}
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/git/commits/COMMIT_SHA

Response

Status: 200
{ "sha": "7638417db6d59f3c431d3e1f261cc637155684cd", "node_id": "MDY6Q29tbWl0NmRjYjA5YjViNTc4NzVmMzM0ZjYxYWViZWQ2OTVlMmU0MTkzZGI1ZQ==", "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd", "html_url": "https://github.com/octocat/Hello-World/commit/7638417db6d59f3c431d3e1f261cc637155684cd", "author": { "date": "2014-11-07T22:01:45Z", "name": "Monalisa Octocat", "email": "octocat@github.com" }, "committer": { "date": "2014-11-07T22:01:45Z", "name": "Monalisa Octocat", "email": "octocat@github.com" }, "message": "added readme, because im a good github citizen", "tree": { "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/691272480426f78a0138979dd3ce63b77f706feb", "sha": "691272480426f78a0138979dd3ce63b77f706feb" }, "parents": [ { "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/1acc419d4d6a9ce985db7be48c6349a0475975b5", "sha": "1acc419d4d6a9ce985db7be48c6349a0475975b5", "html_url": "https://github.com/octocat/Hello-World/commit/7638417db6d59f3c431d3e1f261cc637155684cd" } ], "verification": { "verified": false, "reason": "unsigned", "signature": null, "payload": null } }