L’API REST est maintenant versionnée. Pour plus d’informations, consultez « À propos des versions de l’API ».

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

Utilisez l’API REST pour créer et gérer des clés de déploiement.

À propos des clés de déploiement

Vous pouvez lancer des projets à partir d’un référentiel sur votre instance GitHub Enterprise Server 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, et 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 GitHub web. Pour savoir comment configurer des clés de déploiement dans l’interface web, consultez Gestion des clés de déploiement.

Vous ne pourrez peut-être pas créer de clés de déploiement si votre organisation ou propriétaire d’entreprise a défini une stratégie pour restreindre leur utilisation. De plus, si cette stratégie est activée au niveau de l’organisation ou de l’entreprise, les clés de déploiement existantes peuvent être désactivées. Pour plus d’informations, consultez « Application de stratégies de gestion des dépôts dans votre entreprise » et « Restriction des clés de déploiement dans votre organisation ».

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 un personal access token, la suppression de personal access token entraînera également la suppression de la clé de déploiement. Régénérer le personal access token ne supprimera pas la clé de déploiement.
Si la clé de déploiement est créée avec un OAuth app jeton, la révocation du jeton supprime é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 GitHub App utilisateur, la révocation du jeton ne supprime pas la clé de déploiement.
Si la clé de déploiement est créée avec un jeton d’accès GitHub App d’installation, la désinstallation ou la suppression de l’application ne supprime pas la clé de déploiement.
Si la clé de déploiement est créée avec un personal access token, régénérer la personal access token clé ne supprime pas la clé de déploiement.

List deploy keys

Jetons d'accès granulaires pour «List deploy keys»

Ce point de terminaison fonctionne avec les types de tokens à granularité fine suivants:

Le token à granularité fine doit disposer de l’ensemble d’autorisations suivant:

"Administration" repository permissions (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 Requis The account owner of the repository. The name is not case sensitive.
`repo` string Requis 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." Par défaut: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Par défaut: `1`

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

Code de statut	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" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/keys

Response

Status: 200

[
  {
    "id": 1,
    "key": "ssh-rsa AAA...",
    "url": "https://HOSTNAME/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",
    "enabled": true
  }
]

Create a deploy key

You can create a read-only deploy key.

Jetons d'accès granulaires pour «Create a deploy key»

Ce point de terminaison fonctionne avec les types de tokens à granularité fine suivants:

Le token à granularité fine doit disposer de l’ensemble d’autorisations suivant:

"Administration" repository permissions (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 Requis The account owner of the repository. The name is not case sensitive.
`repo` string Requis 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 Requis 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 réponse HTTP pour «Create a deploy key »

Code de statut	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" \
  http(s)://HOSTNAME/api/v3/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://HOSTNAME/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",
  "enabled": true
}

Get a deploy key

Jetons d'accès granulaires pour «Get a deploy key»

Ce point de terminaison fonctionne avec les types de tokens à granularité fine suivants:

Le token à granularité fine doit disposer de l’ensemble d’autorisations suivant:

"Administration" repository permissions (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 Requis The account owner of the repository. The name is not case sensitive.
`repo` string Requis The name of the repository without the `.git` extension. The name is not case sensitive.
`key_id` integer Requis The unique identifier of the key.

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

Code de statut	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" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/keys/KEY_ID

Response

Status: 200

{
  "id": 1,
  "key": "ssh-rsa AAA...",
  "url": "https://HOSTNAME/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",
  "enabled": true
}

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 granulaires pour «Delete a deploy key»

Ce point de terminaison fonctionne avec les types de tokens à granularité fine suivants:

Le token à granularité fine doit disposer de l’ensemble d’autorisations suivant:

"Administration" repository permissions (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 Requis The account owner of the repository. The name is not case sensitive.
`repo` string Requis The name of the repository without the `.git` extension. The name is not case sensitive.
`key_id` integer Requis The unique identifier of the key.

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

Code de statut	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" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/keys/KEY_ID

Response

Status: 204