Puntos de conexión de la API de REST para claves de implementación
Usa la API REST para crear y administrar claves de implementación.
About deploy keys
You can launch projects from a repository on GitHub.com to your server by using a deploy key, which is an SSH key that grants access to a single repository. GitHub Enterprise Cloud attaches the public part of the key directly to your repository instead of a personal account, and the private part of the key remains on your server. For more information, see "Delivering deployments."
Deploy keys can either be set up using the following API endpoints, or by using the GitHub web interface. To learn how to set deploy keys up in the web interface, see "Managing deploy keys."
You may be unable to create deploy keys if your organization or enterprise owner has set a policy to restrict their use. Furthermore, if this policy is enabled at the organization or enterprise level, existing deploy keys may be disabled. For more information, see "Enforcing repository management policies in your enterprise" and "Restricting deploy keys in your organization."
There are a few cases when a deploy key will be deleted by other activity:
- If the deploy key is created with a personal access token, deleting the personal access token will also delete the deploy key. Regenerating the personal access token will not delete the deploy key.
- If the deploy key is created with an OAuth app token, revoking the token will also delete the deploy key.
Conversely, these activities will not delete a deploy key:
- If the deploy key is created with a GitHub App user access token, revoking the token will not delete the deploy key.
- If the deploy key is created with a GitHub App installation access token, uninstalling or deleting the app will not delete the deploy key.
- If the deploy key is created with a personal access token, regenerating the personal access token will not delete the deploy key.
List deploy keys
Tokens de acceso específicos para "List deploy keys"
Este punto de conexión funciona con los siguientes tipos de token pormenorizados:
- Tokens de acceso de usuario de la aplicación de GitHub
- Token de acceso a la instalación de la aplicación de GitHub
- Tokens de acceso personal específico
El token pormenorizado debe tener el siguiente conjunto de permisos:
- "Administration" repository permissions (read)
Parámetros para "List deploy keys"
Nombre, Tipo, Descripción |
---|
accept string Setting to |
Nombre, Tipo, Descripción |
---|
owner string RequeridoThe account owner of the repository. The name is not case sensitive. |
repo string RequeridoThe name of the repository without the |
Nombre, Tipo, Descripción |
---|
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Valor predeterminado: |
page integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Valor predeterminado: |
Códigos de estado de respuesta HTTP para "List deploy keys"
status code | Descripción |
---|---|
200 | OK |
Ejemplos de código para "List deploy keys"
If you access GitHub at GHE.com, replace api.github.com
with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com
.
Ejemplo de solicitud
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",
"enabled": true
}
]
Create a deploy key
You can create a read-only deploy key.
Tokens de acceso específicos para "Create a deploy key"
Este punto de conexión funciona con los siguientes tipos de token pormenorizados:
- Tokens de acceso de usuario de la aplicación de GitHub
- Token de acceso a la instalación de la aplicación de GitHub
- Tokens de acceso personal específico
El token pormenorizado debe tener el siguiente conjunto de permisos:
- "Administration" repository permissions (write)
Parámetros para "Create a deploy key"
Nombre, Tipo, Descripción |
---|
accept string Setting to |
Nombre, Tipo, Descripción |
---|
owner string RequeridoThe account owner of the repository. The name is not case sensitive. |
repo string RequeridoThe name of the repository without the |
Nombre, Tipo, Descripción |
---|
title string A name for the key. |
key string RequeridoThe contents of the key. |
read_only boolean If 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." |
Códigos de estado de respuesta HTTP para "Create a deploy key"
status code | Descripción |
---|---|
201 | Created |
422 | Validation failed, or the endpoint has been spammed. |
Ejemplos de código para "Create a deploy key"
If you access GitHub at GHE.com, replace api.github.com
with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com
.
Ejemplo de solicitud
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",
"enabled": true
}
Get a deploy key
Tokens de acceso específicos para "Get a deploy key"
Este punto de conexión funciona con los siguientes tipos de token pormenorizados:
- Tokens de acceso de usuario de la aplicación de GitHub
- Token de acceso a la instalación de la aplicación de GitHub
- Tokens de acceso personal específico
El token pormenorizado debe tener el siguiente conjunto de permisos:
- "Administration" repository permissions (read)
Parámetros para "Get a deploy key"
Nombre, Tipo, Descripción |
---|
accept string Setting to |
Nombre, Tipo, Descripción |
---|
owner string RequeridoThe account owner of the repository. The name is not case sensitive. |
repo string RequeridoThe name of the repository without the |
key_id integer RequeridoThe unique identifier of the key. |
Códigos de estado de respuesta HTTP para "Get a deploy key"
status code | Descripción |
---|---|
200 | OK |
404 | Resource not found |
Ejemplos de código para "Get a deploy key"
If you access GitHub at GHE.com, replace api.github.com
with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com
.
Ejemplo de solicitud
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",
"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.
Tokens de acceso específicos para "Delete a deploy key"
Este punto de conexión funciona con los siguientes tipos de token pormenorizados:
- Tokens de acceso de usuario de la aplicación de GitHub
- Token de acceso a la instalación de la aplicación de GitHub
- Tokens de acceso personal específico
El token pormenorizado debe tener el siguiente conjunto de permisos:
- "Administration" repository permissions (write)
Parámetros para "Delete a deploy key"
Nombre, Tipo, Descripción |
---|
accept string Setting to |
Nombre, Tipo, Descripción |
---|
owner string RequeridoThe account owner of the repository. The name is not case sensitive. |
repo string RequeridoThe name of the repository without the |
key_id integer RequeridoThe unique identifier of the key. |
Códigos de estado de respuesta HTTP para "Delete a deploy key"
status code | Descripción |
---|---|
204 | No Content |
Ejemplos de código para "Delete a deploy key"
If you access GitHub at GHE.com, replace api.github.com
with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com
.
Ejemplo de solicitud
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