Skip to main content
O controle de versão da API REST já foi feito. Para obter mais informações, confira "Sobre o controle de versão da API".

Pontos de extremidade da API REST para referências Git

Use a API REST para interagir com referências em seu banco de dados Git no GitHub

Sobre referências do Git

Uma referência do Git (git ref) é um arquivo que contém um hash SHA-1 de commit do Git. Ao referir-se a um commit do Git, você pode usar a referência do Git, que é um nome fácil de lembrar, em vez do hash. A referência do Git pode ser reescrita para apontar para um novo commit. Um branch é uma referência do Git que armazena o novo hash de commit do Git. Esses pontos de extremidade permitem que você leia e grave referências no banco de dados do Git do GitHub.

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.

Tokens de acesso refinados para "List matching references"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Contents" repository permissions (read)

Esse ponto de extremidade pode ser usado sem autenticação ou as permissões acima mencionadas se apenas recursos públicos forem solicitados.

Parâmetros para "List matching references"

Cabeçalhos
Nome, Tipo, Descrição
accept string

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

Parâmetros de caminho
Nome, Tipo, Descrição
owner string Obrigatório

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

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

ref string Obrigatório

The Git reference. For more information, see "Git References" in the Git documentation.

Códigos de status de resposta HTTP para "List matching references"

Código de statusDescrição
200

OK

409

Conflict

Exemplos de código para "List matching references"

Exemplo de solicitação

get/repos/{owner}/{repo}/git/matching-refs/{ref}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/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" } } ]

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

Tokens de acesso refinados para "Get a reference"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Contents" repository permissions (read)

Esse ponto de extremidade pode ser usado sem autenticação ou as permissões acima mencionadas se apenas recursos públicos forem solicitados.

Parâmetros para "Get a reference"

Cabeçalhos
Nome, Tipo, Descrição
accept string

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

Parâmetros de caminho
Nome, Tipo, Descrição
owner string Obrigatório

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

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

ref string Obrigatório

The Git reference. For more information, see "Git References" in the Git documentation.

Códigos de status de resposta HTTP para "Get a reference"

Código de statusDescrição
200

OK

404

Resource not found

409

Conflict

Exemplos de código para "Get a reference"

Exemplo de solicitação

get/repos/{owner}/{repo}/git/ref/{ref}
curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/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" } }

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.

Tokens de acesso refinados para "Create a reference"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter pelo menos um dos seguintes conjuntos de permissões:

  • "Contents" repository permissions (write)
  • "Contents" repository permissions (write) and "Workflows" repository permissions (write)

Parâmetros para "Create a reference"

Cabeçalhos
Nome, Tipo, Descrição
accept string

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

Parâmetros de caminho
Nome, Tipo, Descrição
owner string Obrigatório

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

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

Parâmetros do corpo
Nome, Tipo, Descrição
ref string Obrigatório

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 Obrigatório

The SHA1 value for this reference.

Códigos de status de resposta HTTP para "Create a reference"

Código de statusDescrição
201

Created

409

Conflict

422

Validation failed, or the endpoint has been spammed.

Exemplos de código para "Create a reference"

Exemplo de solicitação

post/repos/{owner}/{repo}/git/refs
curl -L \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/git/refs \ -d '{"ref":"refs/heads/featureA","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" } }

Update a reference

Updates the provided reference to point to a new SHA. For more information, see "Git References" in the Git documentation.

Tokens de acesso refinados para "Update a reference"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter pelo menos um dos seguintes conjuntos de permissões:

  • "Contents" repository permissions (write)
  • "Contents" repository permissions (write) and "Workflows" repository permissions (write)

Parâmetros para "Update a reference"

Cabeçalhos
Nome, Tipo, Descrição
accept string

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

Parâmetros de caminho
Nome, Tipo, Descrição
owner string Obrigatório

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

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

ref string Obrigatório

The Git reference. For more information, see "Git References" in the Git documentation.

Parâmetros do corpo
Nome, Tipo, Descrição
sha string Obrigatório

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.

Padrão: false

Códigos de status de resposta HTTP para "Update a reference"

Código de statusDescrição
200

OK

409

Conflict

422

Validation failed, or the endpoint has been spammed.

Exemplos de código para "Update a reference"

Exemplo de solicitação

patch/repos/{owner}/{repo}/git/refs/{ref}
curl -L \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/git/refs/REF \ -d '{"sha":"aa218f56b14c9653891f9e74264a383fa43fefbd","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" } }

Delete a reference

Deletes the provided reference.

Tokens de acesso refinados para "Delete a reference"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Contents" repository permissions (write)

Parâmetros para "Delete a reference"

Cabeçalhos
Nome, Tipo, Descrição
accept string

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

Parâmetros de caminho
Nome, Tipo, Descrição
owner string Obrigatório

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

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

ref string Obrigatório

The Git reference. For more information, see "Git References" in the Git documentation.

Códigos de status de resposta HTTP para "Delete a reference"

Código de statusDescrição
204

No Content

409

Conflict

422

Validation failed, or the endpoint has been spammed.

Exemplos de código para "Delete a reference"

Exemplo de solicitação

delete/repos/{owner}/{repo}/git/refs/{ref}
curl -L \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/git/refs/REF

Response

Status: 204