References - GitHub Docs

A Git reference (git ref) is just a file that contains a Git commit SHA-1 hash.

When referring to a Git commit, you can use the Git reference, which is an easy-to-remember name, rather than the hash. The Git reference can be rewritten to point to a new commit. A branch is just a Git reference that stores the new Git commit hash. These endpoints allow you to read and write references to your Git database on GitHub Enterprise Cloud.

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 /repos/{owner}/{repo}/git/matching-refs/{ref}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`ref`	string	path	ref parameter
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page number of the results to fetch. Default: `1`

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/git/matching-refs/REF

JavaScript @octokit/core.js

await octokit.request('GET /repos/{owner}/{repo}/git/matching-refs/{ref}', {
  owner: 'OWNER',
  repo: 'REPO',
  ref: 'REF'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/git/matching-refs/REF

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

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.

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

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`ref`	string	path	ref parameter

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/git/ref/REF

JavaScript @octokit/core.js

await octokit.request('GET /repos/{owner}/{repo}/git/ref/{ref}', {
  owner: 'OWNER',
  repo: 'REPO',
  ref: 'REF'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/git/ref/REF

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK
`404`	Resource not found

Notes

Works with GitHub Apps

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 /repos/{owner}/{repo}/git/refs

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`ref`	string	body	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	body	Required. The SHA1 value for this reference.
`key`	string	body

Code samples

Example

Shell

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/git/refs \
  -d '{"ref":"refs/heads/featureA","sha":"aa218f56b14c9653891f9e74264a383fa43fefbd"}'

JavaScript @octokit/core.js

await octokit.request('POST /repos/{owner}/{repo}/git/refs', {
  owner: 'OWNER',
  repo: 'REPO',
  ref: 'refs/heads/featureA',
  sha: 'aa218f56b14c9653891f9e74264a383fa43fefbd'
})

GitHub CLI gh api

gh api \
  --method POST \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/git/refs \
  -f ref='refs/heads/featureA' -f sha='aa218f56b14c9653891f9e74264a383fa43fefbd'

Response

Status: 201

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

Status codes

HTTP Status Code	Description
`201`	Created
`422`	Validation failed

Notes

Works with GitHub Apps

Update a reference

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

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`ref`	string	path	ref parameter
`sha`	string	body	Required. The SHA1 value to set this reference to
`force`	boolean	body	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.

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/git/refs/REF \
  -d '{"sha":"aa218f56b14c9653891f9e74264a383fa43fefbd","force":true}'

JavaScript @octokit/core.js

await octokit.request('PATCH /repos/{owner}/{repo}/git/refs/{ref}', {
  owner: 'OWNER',
  repo: 'REPO',
  ref: 'REF',
  sha: 'aa218f56b14c9653891f9e74264a383fa43fefbd',
  force: true
})

GitHub CLI gh api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/git/refs/REF \
  -f sha='aa218f56b14c9653891f9e74264a383fa43fefbd' -F force=true

Response

Status: 200

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

Status codes

HTTP Status Code	Description
`200`	OK
`422`	Validation failed

Notes

Works with GitHub Apps

Delete a reference

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

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`owner`	string	path
`repo`	string	path
`ref`	string	path	ref parameter

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/OWNER/REPO/git/refs/REF

JavaScript @octokit/core.js

await octokit.request('DELETE /repos/{owner}/{repo}/git/refs/{ref}', {
  owner: 'OWNER',
  repo: 'REPO',
  ref: 'REF'
})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  /repos/OWNER/REPO/git/refs/REF

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content
`422`	Validation failed

Notes

Works with GitHub Apps