Puntos de conexión de la API de REST para claves de implementación

Acerca de las claves de implementación

Puedes iniciar proyectos hacia tu servidor desde un repositorio de tu instancia de GitHub Enterprise Server utilizando una clave de implementación, que es una clave SSH que otorga acceso a un único repositorio. GitHub adjunta la parte pública de la llave directamente en tu repositorio en vez de hacerlo a una cuenta personal, mientras que la parte privada de la clave permanece en tu servidor. Para más información, consulta Realizar despliegues.

Las claves de implementación se pueden configurar mediante los siguientes puntos de conexión de API o mediante la interfaz web de GitHub. Para obtener información sobre cómo configurar las claves de implementación en la interfaz web, consulta Administrar las llaves de despliegue.

Es posible que no pueda crear claves de implementación si su organización o el propietario de la empresa ha establecido una directiva para restringir su uso. Además, si esta directiva está habilitada a nivel de organización o de empresa, se pueden deshabilitar las claves de implementación existentes. Para más información, consulta Implantar políticas de gestión de repositorios en su empresa y Restricción de las claves de implementación en su organización.

Hay algunos casos en los que otra actividad eliminará una clave de implementación:

Si la clave de implementación se crea con personal access token, la eliminación de personal access token también eliminará la clave de implementación. La regeneración de personal access token no eliminará la clave de implementación.
Si la clave de implementación se crea con un token de OAuth app, revocar el token también eliminará la clave de implementación.

Por el contrario, estas actividades no eliminarán una clave de implementación:

Si la clave de implementación se crea con un token de acceso de usuario de GitHub App, revocar el token no eliminará la clave de implementación.
Si la clave de implementación se crea con un token de acceso de instalación de GitHub App, la desinstalación o eliminación de la aplicación no eliminará la clave de implementación.
Si la clave de implementación se crea con personal access token, la regeneración de personal access token no eliminará la clave de implementación.

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:

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Administration" repository permissions (read)

Parámetros para "List deploy keys"

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 Obligatorio The account owner of the repository. The name is not case sensitive.
`repo` string Obligatorio The name of the repository without the `.git` extension. The name is not case sensitive.

Parámetros de consulta
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: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Valor predeterminado: `1`

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"

Ejemplo de solicitud

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.

Tokens de acceso específicos para "Create a deploy key"

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

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Administration" repository permissions (write)

Parámetros para "Create a deploy key"

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 Obligatorio The account owner of the repository. The name is not case sensitive.
`repo` string Obligatorio The name of the repository without the `.git` extension. The name is not case sensitive.

Parámetros del cuerpo
Nombre, Tipo, Descripción
`title` string A name for the key.
`key` string Obligatorio 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."

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"

Ejemplo de solicitud

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

Tokens de acceso específicos para "Get a deploy key"

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

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Administration" repository permissions (read)

Parámetros para "Get a deploy key"

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 Obligatorio The account owner of the repository. The name is not case sensitive.
`repo` string Obligatorio The name of the repository without the `.git` extension. The name is not case sensitive.
`key_id` integer Obligatorio The 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"

Ejemplo de solicitud

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.

Tokens de acceso específicos para "Delete a deploy key"

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

El token pormenorizado debe tener el siguiente conjunto de permisos:

"Administration" repository permissions (write)

Parámetros para "Delete a deploy key"

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 Obligatorio The account owner of the repository. The name is not case sensitive.
`repo` string Obligatorio The name of the repository without the `.git` extension. The name is not case sensitive.
`key_id` integer Obligatorio The 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"

Ejemplo de solicitud

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