Sobre Manifestos do GitHub App
Quando alguém registra um GitHub App em um manifesto, é necessário apenas seguir uma URL e nomear o aplicativo. O manifesto inclui as permissões, eventos e URL do webhook necessários para registrar o aplicativo automaticamente. O fluxo do manifesto cria o registro do GitHub App e gera o segredo do webhook do aplicativo, a chave privada (arquivo PEM), o segredo do cliente e o ID do GitHub App. A pessoa que criar o registro GitHub App no manifesto será proprietária do registro GitHub App e poderá optar por editar as configurações do registro, excluí-lo ou transferi-lo para outra pessoa no GitHub.
Use o Probot para começar a usar os Manifestos GitHub App ou para ver um exemplo de implementação. Confira "Usar o Probot para implementar o fluxo do Manifesto GitHub App" para saber mais.
Aqui estão alguns cenários em que você pode usar os Manifestos GitHub App para registrar aplicativos pré-configurados:
- Ajude novos membros da equipe a familiarizar-se rapidamente quando desenvolverem GitHub Apps.
- Permita que outras pessoas estendam um GitHub App usando as APIs GitHub sem exigir que configurem um aplicativo.
- Crie designs de referência GitHub App para compartilhar com a comunidade GitHub.
- Implemente GitHub Apps em ambientes de desenvolvimento e produção usando a mesma configuração.
- Monitore as revisões com a configuração do GitHub App.
Implementar o fluxo do manifesto GitHub App
O fluxo do Manifesto GitHub App usa um processo de handshake semelhante ao fluxo OAuth. O fluxo usa um manifesto para registrar um GitHub App e receber um code
temporário usado para recuperar a chave privada, o segredo do webhook e a ID do aplicativo.
Note
Você precisa concluir as três etapas do fluxo do Manifesto GitHub App em uma hora.
Siga estas etapas para implementar o fluxo do Manifesto GitHub App:
- Você redireciona as pessoas ao GitHub para registrar um novo GitHub App.
- O GitHub redireciona as pessoas de volta ao seu site.
- Você troca o código temporário para recuperar a configuração do aplicativo.
1. Você redireciona as pessoas ao GitHub para registrar um novo GitHub App
Para redirecionar pessoas para registrar um novo GitHub App, forneça um link para que elas possam enviar uma solicitação POST
ao https://github.com/settings/apps/new
para uma conta pessoal ou https://github.com/organizations/ORGANIZATION/settings/apps/new
para uma conta de organização, substituindo ORGANIZATION
pelo nome da conta da organização na qual o aplicativo será registrado.
Inclua os parâmetros do Manifesto GitHub App como uma cadeia de caracteres codificada em JSON em um parâmetro chamado manifest
. Você também pode incluir um state
parâmetro para segurança adicional.
A pessoa que estiver registrando o aplicativo será redirecionada para uma página do GitHub com um campo de entrada, no qual poderá editar o nome do aplicativo que você incluiu no parâmetro manifest
. Se você não incluir um name
no manifest
, ela poderá definir o nome dela para o aplicativo nesse campo.
Parâmetros do manifesto GitHub App
Nome | Tipo | Descrição |
---|---|---|
name | string | O nome do GitHub App. |
url | string | Necessário. A home page do seu GitHub App. |
hook_attributes | object | A configuração do webhook do GitHub App. |
redirect_url | string | A URL completa para a qual fazer o redirecionamento após um usuário iniciar o registro do GitHub App com base em um manifesto. |
callback_urls | array of strings | Uma URL completa para a qual redirecionar após alguém autorizar uma instalação. Você pode fornecer até 10 URLs de retorno de chamada. |
setup_url | string | Uma URL completa para redirecionar os usuários após a instalação do GitHub App, caso seja necessária uma configuração adicional. |
description | string | Uma descrição do GitHub App. |
public | boolean | Defina essa opção como true quando o GitHub App estiver disponível para o público ou como false quando ele só for acessível pelo proprietário do aplicativo. |
default_events | array | A lista de eventos que o GitHub App assina. |
default_permissions | object | O conjunto de permissões exigidas pelo GitHub App. O formato do objeto usa o nome da permissão para a chave (por exemplo, issues ) e o tipo de acesso para o valor (por exemplo, write ). Para obter mais informações, confira "Escolhendo permissões para um Aplicativo GitHub". |
request_oauth_on_install | boolean | Defina como true para solicitar que o usuário autorize o GitHub App, depois que o GitHub App for instalado. |
setup_on_update | boolean | Defina como true para redirecionar os usuários para o setup_url depois que eles atualizarem a instalação do GitHub App. |
O objeto hook_attributes
tem as chaves a seguir.
Nome | Tipo | Descrição |
---|---|---|
url | string | Necessário. A URL do servidor que receberá as solicitações POST de webhook. |
active | boolean | Implementar detalhes do evento quando esse hook é acionado. O padrão é verdadeiro. |
Parâmetros
Nome | Tipo | Descrição |
---|---|---|
state | string | Uma string aleatória indescritível. É usado para proteger contra ataques de falsificação de pedidos entre sites. |
Exemplos
Este exemplo usa um formulário em uma página da Web com um botão que dispara a solicitação POST
para uma conta pessoal:
<form action="https://github.com/settings/apps/new?state=abc123" method="post">
Register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
<input type="submit" value="Submit">
</form>
<script>
input = document.getElementById("manifest")
input.value = JSON.stringify({
"name": "Octoapp",
"url": "https://www.example.com",
"hook_attributes": {
"url": "https://example.com/github/events",
},
"redirect_url": "https://example.com/redirect",
"callback_urls": [
"https://example.com/callback"
],
"public": true,
"default_permissions": {
"issues": "write",
"checks": "write"
},
"default_events": [
"issues",
"issue_comment",
"check_suite",
"check_run"
]
})
</script>
Este exemplo usa um formulário em uma página da Web com um botão que dispara a solicitação POST
para uma conta de organização. Substitua ORGANIZATION
pelo nome da conta de organização em que deseja registrar o aplicativo.
<form action="https://github.com/organizations/ORGANIZATION/settings/apps/new?state=abc123" method="post">
register a GitHub App Manifest: <input type="text" name="manifest" id="manifest"><br>
<input type="submit" value="Submit">
</form>
<script>
input = document.getElementById("manifest")
input.value = JSON.stringify({
"name": "Octoapp",
"url": "https://www.example.com",
"hook_attributes": {
"url": "https://example.com/github/events",
},
"redirect_url": "https://example.com/redirect",
"callback_urls": [
"https://example.com/callback"
],
"public": true,
"default_permissions": {
"issues": "write",
"checks": "write"
},
"default_events": [
"issues",
"issue_comment",
"check_suite",
"check_run"
]
})
</script>
2. GitHub redireciona as pessoas de volta ao seu site
Quando a pessoa clica em Criar GitHub App, o GitHub redireciona de volta para o redirect_url
com um code
temporário em um parâmetro de código. Por exemplo:
https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679
Se você fornecer um parâmetro state
, também verá esse parâmetro na redirect_url
. Por exemplo:
https://example.com/redirect?code=a180b1a3d263c81bc6441d7b990bae27d4c10679&state=abc123
3. Você troca o código temporário para recuperar a configuração do aplicativo
Para concluir o handshake, envie o code
temporário em uma solicitação POST
ao ponto de extremidade Criar um GitHub App por meio de um manifesto. A resposta incluirá o id
(GitHub App ID), pem
(chave privada) e webhook_secret
. O GitHub cria automaticamente um segredo de webhook para o aplicativo. Você pode armazenar esses valores em variáveis de ambiente no servidor do aplicativo. Por exemplo, se o seu aplicativo usar o dotenv para armazenar variáveis de ambiente, você armazenará as variáveis no arquivo .env
do aplicativo.
Conclua esta etapa do fluxo do manifesto do GitHub App em uma hora.
Observação: esse ponto de extremidade tem limite de taxa. Confira Limites de taxa para saber como obter o status do limite de taxa atual.
POST /app-manifests/{code}/conversions
Para obter mais informações sobre a resposta do ponto de extremidade, confira Criar um GitHub App com base em um manifesto.
Quando a etapa final do fluxo do manifesto for concluída, a pessoa que estiver registrando o aplicativo com base no fluxo será proprietária de um GitHub App registrado e poderá instalar em qualquer um dos seus repositórios pessoais. A pessoa pode optar por estender o aplicativo usando as APIs do GitHub, transferir a propriedade para outra pessoa ou excluí-lo a qualquer momento.
Usar o Probot para implementar o fluxo do manifesto GitHub App
O Probot é uma estrutura criada com o Node.js que executa muitas das tarefas exigidas pelos GitHub Apps, como validar webhooks e realizar a autenticação. O Probot implementa o fluxo de manifesto GitHub App, facilitando a criação e o compartilhamento dos designs de referência do GitHub App com a comunidade GitHub.
Para criar um aplicativo Probot que você pode compartilhar, siga estas etapas:
- Gerar um novo GitHub App.
- Abra o projeto que você criou e personalize as configurações no arquivo
app.yml
. O Probot usa as configurações emapp.yml
como os parâmetros do Manifesto do GitHub App. - Adicione o código personalizado do seu aplicativo.
- Execute o GitHub App localmente ou hospede-o onde desejar. Ao navegar até a URL do aplicativo hospedado, você encontrará uma página da Web com um botão Registrar o GitHub App, no qual as pessoas podem clicar para registrar o aplicativo pré-configurado.
Usando o dotenv, o Probot cria um arquivo .env
e define as variáveis de ambiente APP_ID
, PRIVATE_KEY
e WEBHOOK_SECRET
com os valores recuperados da configuração do aplicativo.
Hospedar seu aplicativo com Glitch
Veja um exemplo de aplicativo do Probot que usa o Glitch para hospedar e compartilhar o aplicativo. O exemplo usa a API de Verificações e seleciona as permissões e os eventos da API de Verificações necessários no arquivo app.yml
. Glitch é uma ferramenta que permite que você "mescle seus próprios aplicativos". Mesclar um aplicativo cria uma cópia do aplicativo que a Glitch hospeda e implementa. Confira "Sobre o Glitch" para saber mais sobre como remixar aplicativos do Glitch.