Sobre a autenticação como uma instalação do GitHub App
Depois que o GitHub App estiver instalado em uma conta, você poderá fazer com que ele seja autenticado como uma instalação de aplicativo para solicitações de API. Isso permite que o aplicativo acesse recursos pertencentes a essa instalação desde que o aplicativo tenha recebido o acesso e as permissões necessárias do repositório. As solicitações de API feitas por uma instalação de aplicativo são atribuídas a ele. Para obter mais informações sobre como instalar o GitHub Apps, confira "Como instalar aplicativos do GitHub".
Por exemplo, para que seu aplicativo altere o Status
campo de um problema em um projeto pertencente a uma organização chamada "octo-org", você deverá realizar a autenticação como a instalação octo-org do seu aplicativo. A linha do tempo do problema indicaria que seu aplicativo atualizou o status.
Para fazer uma solicitação de API como uma instalação, primeiro você deve gerar um token de acesso de instalação. Em seguida, envie o token de acesso de instalação no cabeçalho Authorization
das solicitações de API subsequentes. Você também pode usar os SDKs do Octokit do GitHub, que podem gerar um token de acesso de instalação para você.
Alguns pontos de extremidade da API REST não aceitam tokens de acesso à instalação, e a maioria dos pontos de extremidade da API REST requerem que o aplicativo tenha determinadas permissões para usar um ponto de extremidade. Para visualizar se um ponto de extremidade da API REST aceita tokens de acesso à instalação e quais permissões são necessárias, veja a documentação para o ponto de extremidade.
As instalações de aplicativo também podem usar a API do GraphQL. Semelhante à API REST, o aplicativo deve ter determinadas permissões para acessar objetos na API do GraphQL. Para solicitações do GraphQL, você deve testar se o seu aplicativo possui as permissões necessárias para as consultas e mutações do GraphQL que você deseja realizar.
Você também pode usar um token de acesso de instalação para autenticar para acesso Git baseado em HTTP. O aplicativo deve ter a permissão do repositório "Conteúdo". Você pode então usar o token de acesso da instalação como a senha HTTP. Substitua TOKEN
pelo token de acesso de instalação: git clone https://x-access-token:TOKEN@github.com/owner/repo.git
.
As solicitações feitas com um token de acesso de instalação às vezes são chamadas de solicitações "servidor a servidor".
Para obter mais informações sobre como realizar a autenticação como um aplicativo em nome de um usuário e não como uma instalação de aplicativo, confira "Autenticação com um aplicativo GitHub em nome de um usuário".
Como usar um token de acesso de instalação para autenticar como uma instalação de aplicativo
Para realizar a autenticação como uma instalação com um token de acesso de instalação, primeiro use a API REST para gerar o token. Em seguida, use esse token de acesso de instalação no cabeçalho Authorization
de uma API REST ou solicitação de API do GraphQL. O token de acesso de instalação expirará após 1 hora.
Como gerar um token de acesso de instalação
-
Gere um JWT (token Web JSON) para seu aplicativo. Para obter mais informações, confira "Como gerar um JWT (Token Web JSON) para um Aplicativo GitHub".
-
Obtenha o ID da instalação com a qual você deseja autenticar.
Se você estiver respondendo a um evento de webhook, a carga útil do webhook incluirá o ID de instalação.
Você também pode usar a API REST para localizar o ID de uma instalação do seu aplicativo. Você pode obter uma ID de instalação com os pontos de extremidade
GET /users/{username}/installation
,GET /repos/{owner}/{repo}/installation
,GET /orgs/{org}/installation
ouGET /app/installations
. Para obter mais informações, confira "Pontos de extremidade da API REST para o GitHub Apps".Você também pode encontrar a ID do aplicativo acessando a página de configurações dele. A ID do aplicativo é diferente da ID do cliente. Para saber como acessar a página de configurações do GitHub App, confira "Modificar um registro do Aplicativo GitHub".
-
Envie uma solicitação de
POST
da REST API para/app/installations/INSTALLATION_ID/access_tokens
. Inclua o token Web JSON no cabeçalhoAuthorization
da solicitação. SubstituaINSTALLATION_ID
pela ID de instalação com a qual você deseja autenticar.Por exemplo, envie esta solicitação de curl. Substitua
INSTALLATION_ID
pela ID da instalação eJWT
pelo token Web JSON:curl --request POST \ --url "http(s)://<em>HOSTNAME</em>/api/v3/app/installations/INSTALLATION_ID/access_tokens" \ --header "Accept: application/vnd.github+json" \ --header "Authorization: Bearer JWT"
Opcionalmente, você pode usar os parâmetros de corpo
repositories
ourepository_ids
para especificar repositórios individuais que o token de acesso de instalação pode acessar. Se você não usarrepositories
ourepository_ids
para conceder acesso a repositórios específicos, o token de acesso de instalação poderá acessar todos os repositórios com permissão padrão da instalação. O token de acesso de instalação não pode receber acesso a repositórios que não receberam acesso da instalação. Você pode listar até 500 repositórios.Opcionalmente, use o corpo do parâmetro
permissions
para especificar as permissões que o token de acesso de instalação deve ter. Sepermissions
não for especificado, o token de acesso de instalação receberá todas as permissões que foram concedidas ao aplicativo. O token de acesso de instalação não pode receber permissões que o aplicativo não recebeu.Ao usar os parâmetros
permissions
para reduzir o acesso do token, a complexidade do token é aumentada devido ao número de permissões na solicitação e ao número de repositórios aos quais o token terá acesso. Se a complexidade for muito grande, você receberá uma mensagem de erro que indica o número máximo de repositórios que podem ser suportados. Nesse caso, você deve solicitar menos permissões com o parâmetropermissions
, use o parâmetrorepositories
ourepository_ids
para solicitar menos repositórios ou instalar o aplicativo em repositóriosall
em sua organização.A resposta incluirá um token de acesso à instalação, a hora em que o token expira, as permissões que o token possui e os repositórios que o token pode acessar. O token de acesso de instalação expirará após 1 hora.
Para obter mais informações sobre esse ponto de extremidade, confira "Pontos de extremidade da API REST para o GitHub Apps".
Observação: Na maioria dos casos, você pode usar
Authorization: Bearer
ouAuthorization: token
a fim de passar um token. No entanto, se estiver passando um JWT (token Web JSON), você deverá usarAuthorization: Bearer
.
Autenticação com um token de acesso de instalação
Para realizar a autenticação com um token de acesso de instalação, inclua-o no cabeçalho Authorization
de uma solicitação de API. O token de acesso funcionará com a API do GraphQL e a API REST.
Seu aplicativo deve ter as permissões necessárias para usar o ponto de extremidade. Para obter mais informações, confira "Escolhendo permissões para um Aplicativo GitHub".
No exemplo a seguir, substitua INSTALLATION_ACCESS_TOKEN
por um token de acesso de instalação:
curl --request GET \
--url "http(s)://<em>HOSTNAME</em>/api/v3/meta" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer INSTALLATION_ACCESS_TOKEN"
Como usar o SDK do Octokit.js para autenticar como uma instalação de aplicativo
Você pode usar o SDK do Octokit.js do GitHub para realizar a autenticação como uma instalação de aplicativo. Uma vantagem de usar o SDK para autenticação é que você não precisa gerar um JWT (token Web JSON) por conta própria. Além disso, o SDK cuidará da regeneração de um token de acesso de instalação para você não precisar se preocupar com a expiração de uma hora.
Você precisa instalar e importar octokit
para usar a biblioteca do Octokit.js. O exemplo a seguir usa instruções de importação de acordo com o ES6. Para obter mais informações sobre diferentes métodos de instalação e importação, confira a seção Uso do arquivo LEIAME do Octokit.js.
Como usar Octokit.js para realizar a autenticação com uma ID de instalação
-
Obtenha a ID do GitHub App. Encontre a ID do aplicativo na página de configuração do GitHub App. Para saber como acessar a página de configurações do GitHub App, confira "Modificar um registro do Aplicativo GitHub".
-
Gere uma chave privada. Para obter mais informações, confira "Como gerenciar chaves privadas para Aplicativos GitHub".
-
Obtenha o ID da instalação com a qual você deseja autenticar.
Se você estiver respondendo a um evento de webhook, a carga útil do webhook incluirá o ID de instalação.
Você também pode usar a API REST para localizar o ID de uma instalação do seu aplicativo. Você pode obter uma ID de instalação com os pontos de extremidade
GET /users/{username}/installation
,GET /repos/{owner}/{repo}/installation
,GET /orgs/{org}/installation
ouGET /app/installations
. Para obter mais informações, confira "Pontos de extremidade da API REST para o GitHub Apps". -
Importar
App
deoctokit
. Crie uma nova instância doApp
. No exemplo a seguir, substituaAPP_ID
por uma referência à ID do seu aplicativo. SubstituaPRIVATE_KEY
por uma referência à chave privada do seu aplicativo.JavaScript import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, });
import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, });
-
Use o método
getInstallationOctokit
para criar uma instância deoctokit
autenticada. No seguinte exemplo, substituaINSTALLATION_ID
pela ID de instalação do seu aplicativo em nome do qual deseja se autenticar.JavaScript const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
const octokit = await app.getInstallationOctokit(INSTALLATION_ID);
-
Use um método
octokit
para fazer uma solicitação à API.Seu aplicativo deve ter as permissões necessárias para usar o ponto de extremidade. Para obter mais informações, confira "Escolhendo permissões para um Aplicativo GitHub".
Por exemplo, para fazer uma solicitação à API do GraphQL:
JavaScript await octokit.graphql(` query { viewer { login } } `)
await octokit.graphql(` query { viewer { login } } `)
Por exemplo, para fazer uma solicitação à API REST:
JavaScript await octokit.request("GET /meta")
await octokit.request("GET /meta")
Como usar o Octokit.js na autenticação em resposta a um evento de webhook
O SDK do Octokit.js também passa uma instância de octokit
pré-autenticada para manipuladores de eventos de webhook.
-
Obtenha a ID do GitHub App. Encontre a ID do aplicativo na página de configuração do GitHub App. Para saber como acessar a página de configurações do GitHub App, confira "Modificar um registro do Aplicativo GitHub".
-
Gere uma chave privada. Para obter mais informações, confira "Como gerenciar chaves privadas para Aplicativos GitHub".
-
Obtenha o segredo do webhook especificado nas configurações do aplicativo. Para saber mais sobre segredos do webhook, confira "Usar webhooks com aplicativos GitHub".
-
Importar
App
deoctokit
. Crie uma nova instância doApp
. No exemplo a seguir, substituaAPP_ID
por uma referência à ID do seu aplicativo. SubstituaPRIVATE_KEY
por uma referência à chave privada do seu aplicativo. SubstituaWEBHOOK_SECRET
pelo segredo do webhook do aplicativo.JavaScript import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, webhooks: { WEBHOOK_SECRET }, });
import { App } from "octokit"; const app = new App({ appId: APP_ID, privateKey: PRIVATE_KEY, webhooks: { WEBHOOK_SECRET }, });
-
Use um método
app.webhooks.*
para lidar com eventos de webhook. Para obter mais informações, confira a seção Webhooks README do Octokit.js. Por exemplo, para criar um comentário sobre um problema quando ele for aberto:app.webhooks.on("issues.opened", ({ octokit, payload }) => { await octokit.request("POST /repos/{owner}/{repo}/issues/{issue_number}/comments", { owner: payload.repository.owner.login, repo: payload.repository.name, issue_number: payload.issue.number, body: `This is a bot post in response to this issue being opened.`, } ) });