Skip to main content
O controle de versão da API REST já foi feito. Para obter mais informações, confira "Sobre o controle de versão da API".

Pontos de extremidade da API REST para chaves de implantação

Use a API REST para criar e gerenciar chaves de implantação.

Sobre as chaves de implantação

É possível iniciar projetos por meio de um repositório no GitHub.com ao servidor usando uma chave de implantação, que é uma chave SSH que concede acesso a um só repositório. GitHub anexa a parte pública da chave diretamente ao repositório em vez de uma conta pessoal, e a parte privada da chave permanece no seu servidor. Para obter mais informações, confira "Entregar implantações".

As chaves de implantação podem ser configuradas usando os pontos de extremidade da API a seguir ou usando a interface da Web de GitHub Para saber como configurar chaves de implantação na interface da Web, confira "Gerenciar chaves de implantação".

Há alguns casos em que uma chave de implantação será excluída por outra atividade:

  • Se a chave de implantação for criada com um personal access token, a exclusão do personal access token também excluirá a chave de implantação. A regeneração do personal access token não excluirá a chave de implantação.
  • Se a chave de implantação for criada com um token {do OAuth app, a revogação do token também excluirá a chave de implantação.

Por outro lado, essas atividades não excluirão uma chave de implantação:

  • Se a chave de implantação for criada com um token de acesso de usuário do GitHub App, a revogação do token não excluirá a chave de implantação.
  • Se a chave de implantação for criada com um token de acesso de instalação do GitHub App, a desinstalação ou exclusão do aplicativo não excluirá a chave de implantação.
  • Se a chave de implantação for criada com um personal access token, a regeneração do personal access token não excluirá a chave de implantação.

List deploy keys

Tokens de acesso refinados para "List deploy keys"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Administration" repository permissions (read)

Parâmetros para "List deploy keys"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

Parâmetros de consulta
Nome, Tipo, Descrição
per_page integer

The number of results per page (max 100). For more information, see "Using pagination in the REST API."

Padrão: 30

page integer

The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Padrão: 1

Códigos de status de resposta HTTP para "List deploy keys"

Código de statusDescrição
200

OK

Exemplos de código para "List deploy keys"

Exemplo de solicitação

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", "enabled": true } ]

Create a deploy key

You can create a read-only deploy key.

Tokens de acesso refinados para "Create a deploy key"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Administration" repository permissions (write)

Parâmetros para "Create a deploy key"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

Parâmetros do corpo
Nome, Tipo, Descrição
title string

A name for the key.

key string Obrigatório

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 status de resposta HTTP para "Create a deploy key"

Código de statusDescrição
201

Created

422

Validation failed, or the endpoint has been spammed.

Exemplos de código para "Create a deploy key"

Exemplo de solicitação

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", "enabled": true }

Get a deploy key

Tokens de acesso refinados para "Get a deploy key"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Administration" repository permissions (read)

Parâmetros para "Get a deploy key"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

key_id integer Obrigatório

The unique identifier of the key.

Códigos de status de resposta HTTP para "Get a deploy key"

Código de statusDescrição
200

OK

404

Resource not found

Exemplos de código para "Get a deploy key"

Exemplo de solicitação

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", "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 acesso refinados para "Delete a deploy key"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

  • "Administration" repository permissions (write)

Parâmetros para "Delete a deploy key"

Cabeçalhos
Nome, Tipo, Descrição
accept string

Setting to application/vnd.github+json is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
owner string Obrigatório

The account owner of the repository. The name is not case sensitive.

repo string Obrigatório

The name of the repository without the .git extension. The name is not case sensitive.

key_id integer Obrigatório

The unique identifier of the key.

Códigos de status de resposta HTTP para "Delete a deploy key"

Código de statusDescrição
204

No Content

Exemplos de código para "Delete a deploy key"

Exemplo de solicitação

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