Git

Download Spec

Raw Git functionality.

Create a blob

post /repos/{owner}/{repo}/git/blobs

owner

string

required

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

repo

string

required

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

content

string

required

The new blob's content.

encoding

string

The encoding used for content. Currently, "utf-8" and "base64" are supported.

Default
"utf-8"

Request

{
  "content": "Content of the blob",
  "encoding": "utf-8"
}

Response

Examples Schema

Response

{
  "url": "https://api.github.com/repos/octocat/example/git/blobs/3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15",
  "sha": "3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15"
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

Conflict

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

Forbidden

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

Validation failed, or the endpoint has been spammed.

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

url

string

required

sha

string

required

Location

string

message

string

documentation_url

string

url

string

status

string

message

string

documentation_url

string

url

string

status

string

message

string

documentation_url

string

url

string

status

string

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

Get a blob

get /repos/{owner}/{repo}/git/blobs/{file_sha}

The content in the response will always be Base64 encoded.

Note: This API supports blobs up to 100 megabytes in size.

owner

string

required

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

repo

string

required

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

file_sha

string

required

Response

Examples Schema

Response

{
  "content": "Q29udGVudCBvZiB0aGUgYmxvYg==",
  "encoding": "base64",
  "url": "https://api.github.com/repos/octocat/example/git/blobs/3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15",
  "sha": "3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15",
  "size": 19,
  "node_id": "Q29udGVudCBvZiB0aGUgYmxvYg=="
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

Validation failed, or the endpoint has been spammed.

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

Forbidden

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

content

string

required

encoding

string

required

url

string

uri

required

sha

string

required

size

int or null

required

node_id

string

required

highlighted_content

string

message

string

documentation_url

string

url

string

status

string

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

message

string

documentation_url

string

url

string

status

string

Create a commit

post /repos/{owner}/{repo}/git/commits

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

owner

string

required

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

repo

string

required

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

message

string

required

The commit message

tree

string

required

The SHA of the tree object this commit points to

parents

array[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.

string

author

object (author)

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

string

required

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

email

string

required

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

date

string

date-time

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

committer

object (committer)

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

string

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

email

string

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

date

string

date-time

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

signature

string

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.

Request

{
  "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

Examples Schema

Response

{
  "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"
}

Validation failed, or the endpoint has been spammed.

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

sha

string

required

SHA for the commit

Example
"7638417db6d59f3c431d3e1f261cc637155684cd"

node_id

string

required

url

string

uri

required

author

object (author)

required

Identifying information for the git-user

date

string

date-time

required

Timestamp of the commit

Example
"2014-08-09T08:02:04+12:00"

email

string

required

Git email address of the user

Example
"monalisa.octocat@example.com"

name

string

required

Name of the git user

Example
"Monalisa Octocat"

committer

object (committer)

required

Identifying information for the git-user

date

string

date-time

required

Timestamp of the commit

Example
"2014-08-09T08:02:04+12:00"

email

string

required

Git email address of the user

Example
"monalisa.octocat@example.com"

name

string

required

Name of the git user

Example
"Monalisa Octocat"

message

string

required

Message describing the purpose of the commit

Example
"Fix #42"

tree

object (tree)

required

sha

string

required

SHA for the commit

Example
"7638417db6d59f3c431d3e1f261cc637155684cd"

url

string

uri

required

parents

array[object]

required

object

sha

string

required

SHA for the commit

Example
"7638417db6d59f3c431d3e1f261cc637155684cd"

url

string

uri

required

html_url

string

uri

required

verification

object (verification)

required

verified

boolean

required

reason

string

required

signature

string or null

required

payload

string or null

required

html_url

string

uri

required

Location

string

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

message

string

documentation_url

string

url

string

status

string

Get a commit

get /repos/{owner}/{repo}/git/commits/{commit_sha}

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

owner

string

required

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

repo

string

required

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

commit_sha

string

required

The SHA of the commit.

Response

Examples Schema

Response

{
  "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
  }
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

sha

string

required

SHA for the commit

Example
"7638417db6d59f3c431d3e1f261cc637155684cd"

node_id

string

required

url

string

uri

required

author

object (author)

required

Identifying information for the git-user

date

string

date-time

required

Timestamp of the commit

Example
"2014-08-09T08:02:04+12:00"

email

string

required

Git email address of the user

Example
"monalisa.octocat@example.com"

name

string

required

Name of the git user

Example
"Monalisa Octocat"

committer

object (committer)

required

Identifying information for the git-user

date

string

date-time

required

Timestamp of the commit

Example
"2014-08-09T08:02:04+12:00"

email

string

required

Git email address of the user

Example
"monalisa.octocat@example.com"

name

string

required

Name of the git user

Example
"Monalisa Octocat"

message

string

required

Message describing the purpose of the commit

Example
"Fix #42"

tree

object (tree)

required

sha

string

required

SHA for the commit

Example
"7638417db6d59f3c431d3e1f261cc637155684cd"

url

string

uri

required

parents

array[object]

required

object

sha

string

required

SHA for the commit

Example
"7638417db6d59f3c431d3e1f261cc637155684cd"

url

string

uri

required

html_url

string

uri

required

verification

object (verification)

required

verified

boolean

required

reason

string

required

signature

string or null

required

payload

string or null

required

html_url

string

uri

required

message

string

documentation_url

string

url

string

status

string

List matching references

get /repos/{owner}/{repo}/git/matching-refs/{ref}

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.

owner

string

required

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

repo

string

required

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

ref

string

required

ref parameter

Response

Examples Schema

Response

[
  {
    "ref": "refs/heads/feature-a",
    "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWE=",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-a",
    "object": {
      "type": "commit",
      "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
    }
  },
  {
    "ref": "refs/heads/feature-b",
    "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWI=",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-b",
    "object": {
      "type": "commit",
      "sha": "612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac"
    }
  }
]

array[object (Git Reference)]

Git Reference

object (Git Reference)

Git references within a repository

ref

string

required

node_id

string

required

url

string

uri

required

object

object (object)

required

type

string

required

sha

string

required

SHA for the reference

Min Length
40
Max Length
40
Example
"7638417db6d59f3c431d3e1f261cc637155684cd"

url

string

uri

required

Link

string

Get a reference

get /repos/{owner}/{repo}/git/ref/{ref}

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

owner

string

required

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

repo

string

required

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

ref

string

required

ref parameter

Response

Examples Schema

Response

{
  "ref": "refs/heads/featureA",
  "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA",
  "object": {
    "type": "commit",
    "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
  }
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

ref

string

required

node_id

string

required

url

string

uri

required

object

object (object)

required

type

string

required

sha

string

required

SHA for the reference

Min Length
40
Max Length
40
Example
"7638417db6d59f3c431d3e1f261cc637155684cd"

url

string

uri

required

message

string

documentation_url

string

url

string

status

string

Create a reference

post /repos/{owner}/{repo}/git/refs

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.

owner

string

required

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

repo

string

required

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

ref

string

required

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.

sha

string

required

The SHA1 value for this reference.

Request

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

Response

Examples Schema

Response

{
  "ref": "refs/heads/featureA",
  "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA",
  "object": {
    "type": "commit",
    "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
  }
}

Validation failed, or the endpoint has been spammed.

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

ref

string

required

node_id

string

required

url

string

uri

required

object

object (object)

required

type

string

required

sha

string

required

SHA for the reference

Min Length
40
Max Length
40
Example
"7638417db6d59f3c431d3e1f261cc637155684cd"

url

string

uri

required

Location

string

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

Delete a reference

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

owner

string

required

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

repo

string

required

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

ref

string

required

ref parameter

Response

Examples Schema

Response

Empty response

Validation failed, or the endpoint has been spammed.

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

No schema

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

Update a reference

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

owner

string

required

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

repo

string

required

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

ref

string

required

The name of the fully qualified reference to update. For example, refs/heads/master. If the value doesn't start with refs and have at least two slashes, it will be rejected.

Example
"refs/head/master"

sha

string

required

The SHA1 value to set this reference to

force

boolean

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

Request

{
  "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
  "force": true
}

Response

Examples Schema

Response

{
  "ref": "refs/heads/featureA",
  "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA",
  "object": {
    "type": "commit",
    "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
  }
}

Validation failed, or the endpoint has been spammed.

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

ref

string

required

node_id

string

required

url

string

uri

required

object

object (object)

required

type

string

required

sha

string

required

SHA for the reference

Min Length
40
Max Length
40
Example
"7638417db6d59f3c431d3e1f261cc637155684cd"

url

string

uri

required

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

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.

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.

owner

string

required

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

repo

string

required

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

tag

string

required

The tag's name. This is typically a version (e.g., "v0.0.1").

message

string

required

The tag message.

object

string

required

The SHA of the git object this is tagging.

type

string

required

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

Enum
  • commit
  • tree
  • blob

tagger

object (tagger)

An object with information about the individual creating the tag.

name

string

required

The name of the author of the tag

email

string

required

The email of the author of the tag

date

string

date-time

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

Request

{
  "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"
  }
}

Response

Examples Schema

Response

{
  "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
  }
}

Validation failed, or the endpoint has been spammed.

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

node_id

string

required

Example
"MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw=="

tag

string

required

Name of the tag

Example
"v0.0.1"

sha

string

required

Example
"940bd336248efae0f9ee5bc7b2d5c985887b16ac"

url

string

uri

required

URL for the tag

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

message

string

required

Message describing the purpose of the tag

Example
"Initial public release"

tagger

object (tagger)

required

date

string

required

email

string

required

name

string

required

object

object (object)

required

sha

string

required

type

string

required

url

string

uri

required

verification

object (verification)

verified

boolean

required

reason

string

required

payload

string or null

required

signature

string or null

required

Location

string

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

Get a tag

get /repos/{owner}/{repo}/git/tags/{tag_sha}

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

owner

string

required

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

repo

string

required

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

tag_sha

string

required

Response

Examples Schema

Response

{
  "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
  }
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

node_id

string

required

Example
"MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw=="

tag

string

required

Name of the tag

Example
"v0.0.1"

sha

string

required

Example
"940bd336248efae0f9ee5bc7b2d5c985887b16ac"

url

string

uri

required

URL for the tag

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

message

string

required

Message describing the purpose of the tag

Example
"Initial public release"

tagger

object (tagger)

required

date

string

required

email

string

required

name

string

required

object

object (object)

required

sha

string

required

type

string

required

url

string

uri

required

verification

object (verification)

verified

boolean

required

reason

string

required

payload

string or null

required

signature

string or null

required

message

string

documentation_url

string

url

string

status

string

Create a tree

post /repos/{owner}/{repo}/git/trees

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

Returns an error if you try to delete a file that does not exist.

owner

string

required

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

repo

string

required

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

tree

array[object]

required

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

object

path

string

The file referenced in the tree.

mode

string

The file mode; one of 100644 for file (blob), 100755 for executable (blob), 040000 for subdirectory (tree), 160000 for submodule (commit), or 120000 for a blob that specifies the path of a symlink.

Enum
  • 100644
  • 100755
  • 040000
  • 160000
  • 120000

type

string

Either blob, tree, or commit.

Enum
  • blob
  • tree
  • commit

sha

string or null

The SHA1 checksum ID of the object in the tree. Also called tree.sha. If the value is null then the file will be deleted.

Note: Use either tree.sha or content to specify the contents of the entry. Using both tree.sha and content will return an error.

content

string

The content you want this file to have. GitHub will write this blob out and use that SHA for this entry. Use either this, or tree.sha.

Note: Use either tree.sha or content to specify the contents of the entry. Using both tree.sha and content will return an error.

base_tree

string

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.

Request

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

Response

Examples Schema

Response

{
  "sha": "cd8274d15fa3ae2ab983129fb037999f264ba9a7",
  "url": "https://api.github.com/repos/octocat/Hello-World/trees/cd8274d15fa3ae2ab983129fb037999f264ba9a7",
  "tree": [
    {
      "path": "file.rb",
      "mode": "100644",
      "type": "blob",
      "size": 132,
      "sha": "7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b"
    }
  ],
  "truncated": true
}

Validation failed, or the endpoint has been spammed.

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

Forbidden

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

sha

string

required

url

string

uri

required

truncated

boolean

required

tree

array[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" ] } ]

object

path

string

Example
"test/file.rb"

mode

string

Example
"040000"

type

string

Example
"tree"

sha

string

Example
"23f6827669e43831def8a7ad935069c8bd418261"

size

int

Example
12

url

string

Example
"https://api.github.com/repos/owner-482f3203ecf01f67e9deb18e/BBB_Private_Repo/git/blobs/23f6827669e43831def8a7ad935069c8bd418261"

Location

string

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

message

string

documentation_url

string

url

string

status

string

message

string

documentation_url

string

url

string

status

string

Get a tree

get /repos/{owner}/{repo}/git/trees/{tree_sha}

Returns a single tree using the SHA1 value for that tree.

If truncated is true in the response then the number of items in the tree array exceeded our maximum limit. If you need to fetch more items, use the non-recursive method of fetching trees, and fetch one sub-tree at a time.

Note: The limit for the tree array is 100,000 entries with a maximum size of 7 MB when using the recursive parameter.

owner

string

required

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

repo

string

required

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

tree_sha

string

required

recursive

string

Setting this parameter to any value returns the objects or subtrees referenced by the tree specified in :tree_sha. For example, setting recursive to any of the following will enable returning objects or subtrees: 0, 1, "true", and "false". Omit this parameter to prevent recursively returning objects or subtrees.

Response

Examples Schema

Response

{
  "sha": "9fb037999f264ba9a7fc6274d15fa3ae2ab98312",
  "url": "https://api.github.com/repos/octocat/Hello-World/trees/9fb037999f264ba9a7fc6274d15fa3ae2ab98312",
  "tree": [
    {
      "path": "file.rb",
      "mode": "100644",
      "type": "blob",
      "size": 30,
      "sha": "44b4fc6d56897b048c772eb4087f854f46256132",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/44b4fc6d56897b048c772eb4087f854f46256132"
    },
    {
      "path": "subdir",
      "mode": "040000",
      "type": "tree",
      "sha": "f484d249c660418515fb01c2b9662073663c242e",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/f484d249c660418515fb01c2b9662073663c242e"
    },
    {
      "path": "exec_file",
      "mode": "100755",
      "type": "blob",
      "size": 75,
      "sha": "45b983be36b73c0788dc9cbcb76cbb80fc7bb057",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/blobs/45b983be36b73c0788dc9cbcb76cbb80fc7bb057"
    }
  ],
  "truncated": false
}
{
  "sha": "fc6274d15fa3ae2ab983129fb037999f264ba9a7",
  "url": "https://api.github.com/repos/octocat/Hello-World/trees/fc6274d15fa3ae2ab983129fb037999f264ba9a7",
  "tree": [
    {
      "path": "subdir/file.txt",
      "mode": "100644",
      "type": "blob",
      "size": 132,
      "sha": "7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b"
    }
  ],
  "truncated": false
}

Validation failed, or the endpoint has been spammed.

{
  "message": "string",
  "documentation_url": "string",
  "errors": [
    {
      "resource": "string",
      "field": "string",
      "message": "string",
      "code": "string",
      "index": 123,
      "value": "string"
    }
  ]
}

Resource not found

{
  "message": "string",
  "documentation_url": "string",
  "url": "string",
  "status": "string"
}

sha

string

required

url

string

uri

required

truncated

boolean

required

tree

array[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" ] } ]

object

path

string

Example
"test/file.rb"

mode

string

Example
"040000"

type

string

Example
"tree"

sha

string

Example
"23f6827669e43831def8a7ad935069c8bd418261"

size

int

Example
12

url

string

Example
"https://api.github.com/repos/owner-482f3203ecf01f67e9deb18e/BBB_Private_Repo/git/blobs/23f6827669e43831def8a7ad935069c8bd418261"

message

string

required

documentation_url

string

required

errors

array[object]

object

resource

string

field

string

message

string

code

string

required

index

int

value

One Of

string or null

int or null

array[string] or null

string

message

string

documentation_url

string

url

string

status

string

Was this page helpful?