Points de terminaison d’API REST pour les clés de déploiement

À propos des clés de déploiement

Vous pouvez lancer des projets à partir d’un référentiel sur GitHub.com sur votre serveur à l’aide d’une clé de déploiement, qui est une clé SSH accordant l’accès à un seul référentiel. GitHub attache la partie publique de la clé directement à votre dépôt, au lieu d’un compte personnel, tandis que la partie privée de la clé reste sur votre serveur. Pour plus d’informations, consultez « Livraison de déploiements ».

Les clés de déploiement peuvent être configurées à l’aide des points de terminaison d’API suivants ou à l’aide de l’interface web GitHub. Pour savoir comment configurer des clés de déploiement dans l’interface web, consultez « Gestion des clés de déploiement ».

Il existe quelques cas où une clé de déploiement sera supprimée par d’autres activités :

Si la clé de déploiement est créée avec personal access token, la suppression de personal access token supprimera également la clé de déploiement. La régénération de personal access token ne supprimera pas la clé de déploiement.
Si la clé de déploiement est créée avec un jeton OAuth app, la révocation du jeton supprimera également la clé de déploiement.

À l’inverse, ces activités ne supprimeront pas une clé de déploiement :

Si la clé de déploiement est créée avec un jeton d’accès utilisateur GitHub App, la révocation du jeton ne supprimera pas la clé de déploiement.
Si la clé de déploiement est créée avec un jeton d’accès d’installation GitHub App, la désinstallation ou la suppression du jeton d’accès ne supprimera pas la clé de déploiement.
Si la clé de déploiement est créée avec un personal access token, la régénération de personal access token ne supprimera pas la clé de déploiement.

List deploy keys

Jetons d’accès affinés pour « List deploy keys »

Ce point de terminaison fonctionne avec les types de jetons suivants:

Le jeton doit avoir l’ensemble d’autorisations suivant:

administration:read

Paramètres pour « List deploy keys »

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 de requête
Nom, Type, Description
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`

Codes d’état de la réponse HTTP pour « List deploy keys »

Code d’état	Description
`200`	OK

Exemples de code pour « List deploy keys »

Exemple de requête

get/repos/{owner}/{repo}/keys

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/keys

Response

Status: 200

[
  {
    "id": 1,
    "key": "ssh-rsa AAA...",
    "url": "https://api.github.com/repos/octocat/Hello-World/keys/1",
    "title": "octocat@octomac",
    "verified": true,
    "created_at": "2014-12-10T15:53:42Z",
    "read_only": true,
    "added_by": "octocat",
    "last_used": "2022-01-10T15:53:42Z"
  }
]

Create a deploy key

You can create a read-only deploy key.

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

Ce point de terminaison fonctionne avec les types de jetons suivants:

Le jeton doit avoir l’ensemble d’autorisations suivant:

administration:write

Paramètres pour « Create a deploy key »

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
`title` string A name for the key.
`key` string Obligatoire The contents of the key.
`read_only` boolean If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write. Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see "Repository permission levels for an organization" and "Permission levels for a user account repository."

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

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

Exemples de code pour « Create a deploy key »

Exemple de requête

post/repos/{owner}/{repo}/keys

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/keys \
  -d '{"title":"octocat@octomac","key":"ssh-rsa AAA...","read_only":true}'

Response

Status: 201

{
  "id": 1,
  "key": "ssh-rsa AAA...",
  "url": "https://api.github.com/repos/octocat/Hello-World/keys/1",
  "title": "octocat@octomac",
  "verified": true,
  "created_at": "2014-12-10T15:53:42Z",
  "read_only": true,
  "added_by": "octocat",
  "last_used": "2022-01-10T15:53:42Z"
}

Get a deploy key

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

Ce point de terminaison fonctionne avec les types de jetons suivants:

Le jeton doit avoir l’ensemble d’autorisations suivant:

administration:read

Paramètres pour « Get a deploy key »

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.
`key_id` integer Obligatoire The unique identifier of the key.

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

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

Exemples de code pour « Get a deploy key »

Exemple de requête

get/repos/{owner}/{repo}/keys/{key_id}

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/keys/KEY_ID

Response

Status: 200

{
  "id": 1,
  "key": "ssh-rsa AAA...",
  "url": "https://api.github.com/repos/octocat/Hello-World/keys/1",
  "title": "octocat@octomac",
  "verified": true,
  "created_at": "2014-12-10T15:53:42Z",
  "read_only": true,
  "added_by": "octocat",
  "last_used": "2022-01-10T15:53:42Z"
}

Delete a deploy key

Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.

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

Ce point de terminaison fonctionne avec les types de jetons suivants:

Le jeton doit avoir l’ensemble d’autorisations suivant:

administration:write

Paramètres pour « Delete a deploy key »

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.
`key_id` integer Obligatoire The unique identifier of the key.

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

Code d’état	Description
`204`	No Content

Exemples de code pour « Delete a deploy key »

Exemple de requête

delete/repos/{owner}/{repo}/keys/{key_id}

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/keys/KEY_ID

Response

Status: 204