Registrando um App do GitHub a partir de um manifesto

Sobre GitHub App manifestos

Quando alguém registra um GitHub App de um manifesto, ele só precisa 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 de manifesto cria o GitHub App registro e gera o segredo do webhook do aplicativo, a chave privada (arquivo PEM), o segredo do cliente e a GitHub App ID. A pessoa que cria o GitHub App registro do manifesto será proprietária do GitHub App registro e poderá optar por editar as configurações do registro, excluí-lo ou transferi-lo para outra pessoa.GitHub

Você pode usar o Probot para começar a usar GitHub App Manifestos ou ver uma implementação de exemplo. Consulte Como usar o Probot para implementar o fluxo do GitHub App Manifesto para saber mais.

Aqui estão alguns cenários em que você pode usar GitHub App Manifestos para registrar aplicativos pré-configurados:

Ajude os novos membros da equipe a se integrar rapidamente ao desenvolver GitHub Apps.
Permitir que outras pessoas estendam um GitHub App usando as APIs do GitHub sem exigir que elas configurem um aplicativo.
Crie GitHub App designs de referência para compartilhar com a GitHub comunidade.
Certifique-se de implantar GitHub Apps em ambientes de desenvolvimento e produção usando a mesma configuração.
Acompanhe as revisões de uma GitHub App configuração.

Implementando o fluxo de GitHub App manifesto

O GitHub App fluxo de manifesto usa um processo de handshaking semelhante ao fluxo OAuth. O fluxo usa um manifesto para registrar um GitHub App e recebe um elemento temporário code usado para recuperar a chave privada do aplicativo, o segredo do webhook e a ID do aplicativo.

Observação

Você deve concluir todas as três etapas no fluxo de GitHub App Manifesto dentro de uma hora.

Siga estas etapas para implementar o fluxo de GitHub App Manifest:

Você redireciona as pessoas para GitHub para registrar um novo GitHub App.

       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 pessoas para o GitHub para registrar um novo GitHub App

Para redirecionar as pessoas para registrar um novo GitHub App, forneça um link para que elas cliquem e enviem uma POST solicitação para https://github.com/settings/apps/new uma conta pessoal ou https://github.com/organizations/ORGANIZATION/settings/apps/new para uma conta da organização, substituindo ORGANIZATION pelo nome da conta da organização em que o aplicativo será registrado.

Você deve incluir os GitHub App parâmetros de Manifesto como uma cadeia de caracteres codificada em JSON em um parâmetro chamado manifest. Você também pode incluir um stateparâmetro para segurança adicional.

A pessoa que registrar o aplicativo será redirecionada para uma GitHub página com um campo de entrada em que poderá editar o nome do aplicativo incluído no manifest parâmetro. Se você não incluir um name no manifest, eles poderão definir o próprio nome para o aplicativo neste campo.

          GitHub App Parâmetros de manifesto

Nome	Tipo	Descrição
`name`	`string`	O nome do GitHub App.
`url`	`string`

          **Obrigatório.** A página inicial do seu GitHub App.

hook_attributes | object | A configuração do webhook do GitHub App. redirect_url | string | A URL completa para a qual redirecionar após um usuário iniciar o registro de um GitHub App de 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 a qual redirecionar os usuários após a instalação GitHub App se for necessária uma configuração adicional. description | string | Uma descrição do GitHub App. public | boolean | Defina true quando seu GitHub App estiver disponível para o público ou false quando estiver acessível apenas ao proprietário do aplicativo. default_events | array | A lista de eventos aos quais o GitHub App se inscreve. default_permissions | object | O conjunto de permissões necessárias para o 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 saber mais, confira Escolhendo permissões para um aplicativo GitHub. Para ver a lista de permissões disponíveis para uso e seus nomes parametrizados, confira Gerenciar seus tokens de acesso pessoal. request_oauth_on_install | boolean | Após GitHub App ser instalado, defina para true solicitar que o usuário autorize o GitHub App. setup_on_update | boolean | Defina true para redirecionar os usuários para setup_url após eles atualizarem sua instalação GitHub App.

O objeto hook_attributes tem as chaves a seguir.

Nome	Tipo	Descrição
`url`	`string`

          **Obrigatório.** A URL do servidor que receberá as requisições de webhook `POST`.

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, GitHub redireciona de volta ao redirect_url com um temporário code 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 para o endpoint Criar um GitHub App a partir de um manifesto. A resposta incluirá a id (GitHub App ID), pem (chave privada) e webhook_secret. 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.

Você precisa concluir esta etapa do fluxo do GitHub App Manifesto dentro de uma hora.

Observação

Esse ponto de extremidade tem uma taxa limitada. 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, consulte Criar um GitHub App a partir de um manifesto.

Quando a etapa final no fluxo de manifesto for concluída, a pessoa que registrar o aplicativo no fluxo será proprietária de um GitHub App registrado que poderá instalar em qualquer uma de suas contas. Eles podem optar por estender o aplicativo usando as GitHub APIs, transferir a propriedade para outra pessoa ou excluí-lo a qualquer momento.

Usando o Probot para implementar o fluxo do Manifesto GitHub App

          [O Probot](https://probot.github.io/) é uma estrutura criada com [Node.js](https://nodejs.org/) que executa muitas das tarefas necessárias para todos GitHub Apps, como validar webhooks e executar a autenticação. O Probot implementa o [GitHub App fluxo de manifesto](#implementing-the-github-app-manifest-flow), facilitando a criação e o compartilhamento de GitHub App designs de referência com a GitHub comunidade.

Para criar um aplicativo Probot que você pode compartilhar, siga estas etapas:

       [Gerar um novo GitHub App](https://probot.github.io/docs/development/#generating-a-new-app).

Abra o projeto que você criou e personalize as configurações no arquivo app.yml. O Probot usa as configurações em app.yml como os GitHub App parâmetros do Manifesto.
Adicione o código personalizado do seu aplicativo.

       [Execute o localmente ou hospede-o GitHub App](https://probot.github.io/docs/development/#running-the-app-locally) em qualquer lugar que você gostaria. Ao navegar até a URL do aplicativo hospedado, você encontrará uma página da Web com um botão **Registrar GitHub App** que as pessoas podem clicar para registrar um 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.

Registrando um App do GitHub a partir de um manifesto

Neste artigo