Como autenticar como uma instalação de Aplicativo GitHub

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 ou GET /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çalho Authorization da solicitação. Substitua INSTALLATION_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 e JWT 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 ou repository_ids para especificar repositórios individuais que o token de acesso de instalação pode acessar. Se você não usar repositories ou repository_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. Se permissions 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âmetro permissions, use o parâmetro repositories ou repository_ids para solicitar menos repositórios ou instalar o aplicativo em repositórios all 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 ou Authorization: token a fim de passar um token. No entanto, se estiver passando um JWT (token Web JSON), você deverá usar Authorization: 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 ou GET /app/installations. Para obter mais informações, confira "Pontos de extremidade da API REST para o GitHub Apps".

Importar App de octokit. Crie uma nova instância do App. No exemplo a seguir, substitua APP_ID por uma referência à ID do seu aplicativo. Substitua PRIVATE_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 de octokit autenticada. No seguinte exemplo, substitua INSTALLATION_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".