Puntos de conexión de la API de REST para referencias de Git

Acerca de las referencias de Git

Una referencia de Git (git ref) es un archivo que contiene un hash SHA-1 de una confirmación de Git. Al hacer referencia a una confirmación de Git, puede usar la referencia de Git, que es un nombre fácil de recordar, en lugar del hash. La referencia de Git se puede reescribir para apuntar a una confirmación nueva. Una rama es una referencia de Git que almacena el hash de la nueva confirmación de Git. Estos puntos de conexión permiten leer y escribir referencias en la base de datos de Git en 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 acceso específicos para "List matching references"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Contents" repository permissions (read)

Este punto de conexión se puede usar sin autenticación o los permisos mencionados anteriormente si solo se solicitan recursos públicos.

Parámetros para "List matching references"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`owner` string Requerido The account owner of the repository. The name is not case sensitive.
`repo` string Requerido The name of the repository without the `.git` extension. The name is not case sensitive.
`ref` string Requerido The Git reference. For more information, see "Git References" in the Git documentation.

Códigos de estado de respuesta HTTP para "List matching references"

status code	Descripción
`200`	OK
`409`	Conflict

Ejemplos de código para "List matching references"

Ejemplo de solicitud

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 acceso específicos para "Get a reference"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Contents" repository permissions (read)

Este punto de conexión se puede usar sin autenticación o los permisos mencionados anteriormente si solo se solicitan recursos públicos.

Parámetros para "Get a reference"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`owner` string Requerido The account owner of the repository. The name is not case sensitive.
`repo` string Requerido The name of the repository without the `.git` extension. The name is not case sensitive.
`ref` string Requerido The Git reference. For more information, see "Git References" in the Git documentation.

Códigos de estado de respuesta HTTP para "Get a reference"

status code	Descripción
`200`	OK
`404`	Resource not found
`409`	Conflict

Ejemplos de código para "Get a reference"

Ejemplo de solicitud

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 acceso específicos para "Create a reference"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener al menos uno de los siguientes conjuntos de permisos:

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

Parámetros para "Create a reference"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`owner` string Requerido The account owner of the repository. The name is not case sensitive.
`repo` string Requerido The name of the repository without the `.git` extension. The name is not case sensitive.

Parámetros del cuerpo
Nombre, Tipo, Descripción
`ref` string Requerido 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 Requerido The SHA1 value for this reference.

Códigos de estado de respuesta HTTP para "Create a reference"

status code	Descripción
`201`	Created
`409`	Conflict
`422`	Validation failed, or the endpoint has been spammed.

Ejemplos de código para "Create a reference"

Ejemplo de solicitud

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 acceso específicos para "Update a reference"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener al menos uno de los siguientes conjuntos de permisos:

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

Parámetros para "Update a reference"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`owner` string Requerido The account owner of the repository. The name is not case sensitive.
`repo` string Requerido The name of the repository without the `.git` extension. The name is not case sensitive.
`ref` string Requerido The Git reference. For more information, see "Git References" in the Git documentation.

Parámetros del cuerpo
Nombre, Tipo, Descripción
`sha` string Requerido 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. Valor predeterminado: `false`

Códigos de estado de respuesta HTTP para "Update a reference"

status code	Descripción
`200`	OK
`409`	Conflict
`422`	Validation failed, or the endpoint has been spammed.

Ejemplos de código para "Update a reference"

Ejemplo de solicitud

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 acceso específicos para "Delete a reference"

Este punto de conexión funciona con los siguientes tipos de token pormenorizados:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Contents" repository permissions (write)

Parámetros para "Delete a reference"

Encabezados
Nombre, Tipo, Descripción
`accept` string Setting to `application/vnd.github+json` is recommended.

Parámetros de la ruta de acceso
Nombre, Tipo, Descripción
`owner` string Requerido The account owner of the repository. The name is not case sensitive.
`repo` string Requerido The name of the repository without the `.git` extension. The name is not case sensitive.
`ref` string Requerido The Git reference. For more information, see "Git References" in the Git documentation.

Códigos de estado de respuesta HTTP para "Delete a reference"

status code	Descripción
`204`	No Content
`409`	Conflict
`422`	Validation failed, or the endpoint has been spammed.

Ejemplos de código para "Delete a reference"

Ejemplo de solicitud

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