Points de terminaison d’API REST pour les références Git

À propos des références Git

Une référence Git (git ref) est un fichier qui contient un hachage SHA-1 de validation Git. Lorsque vous faites référence à une validation Git, vous pouvez utiliser la référence Git, qui est un nom facile à mémoriser, plutôt que le hachage. La référence Git peut être réécrite pour pointer vers une nouvelle validation. Une branche est une référence Git qui stocke le nouveau hachage de validation Git. Ces points de terminaison vous permettent de lire et d’écrire des références à votre base de données Git sur 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.

Jetons d’accès affinés pour « List matching references »

Ce point de terminaison fonctionne avec les types de jetons précis suivants:

Le jeton précis doit avoir l’ensemble d’autorisations suivant:

"Contents" repository permissions (read)

Ce point de terminaison peut être utilisé sans authentification ou sans les autorisations mentionnées ci-dessus si seules les ressources publiques sont demandées.

Paramètres pour « List matching references »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`owner` string Obligatoire The account owner of the repository. The name is not case sensitive.
`repo` string Obligatoire The name of the repository without the `.git` extension. The name is not case sensitive.
`ref` string Obligatoire The Git reference. For more information, see "Git References" in the Git documentation.

Codes d’état de la réponse HTTP pour « List matching references »

Code d’état	Description
`200`	OK
`409`	Conflict

Exemples de code pour « List matching references »

Exemple de requête

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

Jetons d’accès affinés pour « Get a reference »

Ce point de terminaison fonctionne avec les types de jetons précis suivants:

Le jeton précis doit avoir l’ensemble d’autorisations suivant:

"Contents" repository permissions (read)

Ce point de terminaison peut être utilisé sans authentification ou sans les autorisations mentionnées ci-dessus si seules les ressources publiques sont demandées.

Paramètres pour « Get a reference »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`owner` string Obligatoire The account owner of the repository. The name is not case sensitive.
`repo` string Obligatoire The name of the repository without the `.git` extension. The name is not case sensitive.
`ref` string Obligatoire The Git reference. For more information, see "Git References" in the Git documentation.

Codes d’état de la réponse HTTP pour « Get a reference »

Code d’état	Description
`200`	OK
`404`	Resource not found
`409`	Conflict

Exemples de code pour « Get a reference »

Exemple de requête

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.

Jetons d’accès affinés pour « Create a reference »

Ce point de terminaison fonctionne avec les types de jetons précis suivants:

Le jeton précis doit avoir au moins l’un des ensembles d’autorisations suivants:

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

Paramètres pour « Create a reference »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`owner` string Obligatoire The account owner of the repository. The name is not case sensitive.
`repo` string Obligatoire The name of the repository without the `.git` extension. The name is not case sensitive.

Paramètres du corps
Nom, Type, Description
`ref` string Obligatoire 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 Obligatoire The SHA1 value for this reference.

Codes d’état de la réponse HTTP pour « Create a reference »

Code d’état	Description
`201`	Created
`409`	Conflict
`422`	Validation failed, or the endpoint has been spammed.

Exemples de code pour « Create a reference »

Exemple de requête

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.

Jetons d’accès affinés pour « Update a reference »

Ce point de terminaison fonctionne avec les types de jetons précis suivants:

Le jeton précis doit avoir au moins l’un des ensembles d’autorisations suivants:

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

Paramètres pour « Update a reference »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`owner` string Obligatoire The account owner of the repository. The name is not case sensitive.
`repo` string Obligatoire The name of the repository without the `.git` extension. The name is not case sensitive.
`ref` string Obligatoire The Git reference. For more information, see "Git References" in the Git documentation.

Paramètres du corps
Nom, Type, Description
`sha` string Obligatoire 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`

Codes d’état de la réponse HTTP pour « Update a reference »

Code d’état	Description
`200`	OK
`409`	Conflict
`422`	Validation failed, or the endpoint has been spammed.

Exemples de code pour « Update a reference »

Exemple de requête

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.

Jetons d’accès affinés pour « Delete a reference »

Ce point de terminaison fonctionne avec les types de jetons précis suivants:

Le jeton précis doit avoir l’ensemble d’autorisations suivant:

"Contents" repository permissions (write)

Paramètres pour « Delete a reference »

En-têtes
Nom, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Paramètres de chemin d’accès
Nom, Type, Description
`owner` string Obligatoire The account owner of the repository. The name is not case sensitive.
`repo` string Obligatoire The name of the repository without the `.git` extension. The name is not case sensitive.
`ref` string Obligatoire The Git reference. For more information, see "Git References" in the Git documentation.

Codes d’état de la réponse HTTP pour « Delete a reference »

Code d’état	Description
`204`	No Content
`409`	Conflict
`422`	Validation failed, or the endpoint has been spammed.

Exemples de code pour « Delete a reference »

Exemple de requête

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