Criar um aplicativo do GitHub a partir de um manifesto

Sobre os manifestos do aplicativo GitHub

Quando alguém cria um aplicativo GitHub a partir de 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 aplicativo GitHub e recupera o segredo do webhook do aplicativo, a chave privada (arquivo PEM) e o ID do aplicativo GitHub. A pessoa que cria o aplicativo a partir do manifesto será proprietária do aplicativo e poderá escolher editar as configurações do aplicativo, excluí-lo ou transferi-lo para outra pessoa no GitHub.

Você pode usar o Probot para começar com manifestos do aplicativo GitHub ou ver um exemplo de implementação. Consulte "Usando o Probot para implementar o fluxo do manifesto do aplicativo GitHub" para saber mais.

Aqui estão alguns cenários em que você pode usar manifestos do aplicativo GitHub para criar aplicativos pré-configurados:

• Ajude novos membros da equipe a familiarizar-se rapidamente ao desenvolver os aplicativos GitHub.
• Permita que outras pessoas estendam o aplicativo GitHub usando as APIs do GitHub sem exigir que configurem um aplicativo.
• Crie desenhos de referência do aplicativo GitHub para compartilhar com a comunidade do GitHub.
• Certifique-se de implementar os aplicativos GitHub em ambientes de desenvolvimento e produção usando a mesma configuração.
• Monitore as revisões de configuração do aplicativo GitHub.

Implemente o fluxo do manifesto do aplicativo GitHub

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

Siga estas etapas para implementar o fluxo do Manifesto do aplicativo GitHub:

1. Você redireciona as pessoas para o GitHub para criar um novo aplicativo GitHub.
2. O GitHub redireciona as pessoas de volta para o seu site.
3. Você troca o código temporário para recuperar a configuração do aplicativo.

1. Você redireciona as pessoas para o GitHub para criar um novo aplicativo GitHub

Para redirecionar as pessoas para criar um novo aplicativo GitHub, fornece um link para que cliquem que envia uma solicitação POST para https://github. om/settings/apps/new para uma conta de usuário ou https://github. om/organizações/ORGANIZAÇÃO/configurações/apps/novo para uma conta de organização substituindo ORGANIZAÇÃO pelo nome da conta da organização, em que o aplicativo será criado.

Você deve incluir os parâmetros do manifesto do aplicativo GitHub como uma string codificada por JSON em um parâmetro denominado manifesto. Você também pode incluir um parâmetro estado para segurança adicional.

A pessoa que está criando o aplicativo será redirecionada para uma página do GitHub com um campo de entrada em que poderá editar o nome do aplicativo que você incluiu no parâmetro do manifesto. Se você não incluir um nome no manifesto, será possível definir seu próprio nome para o aplicativo neste campo.

Parâmetros do manifesto do aplicativo GitHub

O objeto hook_attributes tem a chave a seguir:

Parâmetros

Exemplos

Este exemplo usa um formulário em uma página web com um botão que aciona a solicitação POST para uma conta de usuário:

<form action="https://github.com/settings/apps/new?state=abc123" method="post">
 Criar um manifesto do aplicativo GitHub: <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/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 web com um botão que aciona a solicitação POST para uma conta da organização. Substitua ORGANIZAÇÃO pelo nome da conta da organização em que você deseja criar o aplicativo.

<form action="https://github.com/organizations/<em>ORGANIZATION</em>/settings/apps/new?state=abc123" method="post">
 Criar um manifesto do aplicativo GitHub: <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/callback",
   "public": true,
   "default_permissions": {
     "issues": "write",
     "checks": "write"
   },
   "default_events": [
     "issues",
     "issue_comment",
     "check_suite",
     "check_run"
   ]
 })
</script>

2. O GitHub redireciona as pessoas de volta para o seu site

Quando a pessoa clica em Criar aplicativo GitHub, O GitHub redireciona para o redirect_url com um código temporário em um parâmetro de código. Como por exemplo:

https://example.com/callback?code=a180b1a3d263c81bc6441d7b990bae27d4c10679

Se você forneceu um parâmetro estado, você também verá esse parâmetro em redirect_url. Como por exemplo:

https://example.com/callback?code=a180b1a3d263c81bc6441d7b990bae27d4c10679&state=abc123

3. Você troca o código temporário para recuperar a configuração do aplicativo

Para concluir o handshake, enviar o código temporário `em uma solicitaçãoPOSTpara [Criar um aplicativo GitHub a partir do ponto final](/v3/apps/#create-a-github-app-from-a-manifest) de um manifesto. A resposta incluirá oid(ID do aplicativo GitHub),pem(chave privada) ewebhook_secret. O GitHub cria um segredo webhook para o aplicativo automaticamente. Você pode armazenar esses valores em variáveis de ambiente no servidor do aplicativo. Por exemplo, se o aplicativo usar [dotenv](https://github.com/bkeepers/dotenv) para armazenar variáveis de ambiente, você armazenará as variáveis no arquivo .env` do seu aplicativo.

Você deve concluir esta etapa do fluxo do manifesto do aplicativo GitHub em uma hora.

application/vnd.github.fury-preview+json

POST /app-manifests/:code/conversions

Para obter mais informações sobre a resposta do ponto final, consulte Criar um aplicativo GitHub a partir de um manifesto.

Quando a etapa final do fluxo de manifesto for concluída, a pessoa que estiver criando o aplicativo a partir do fluxo será proprietária de um aplicativo GitHub 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 de manifesto do aplicativo GitHub

Probot é uma estrutura construído com Node.js que realiza muitas das tarefas necessárias para todos os aplicativos GitHub, como, por exemplo, validar webhooks e efetuar a autenticação. O Probot implementa fluxo do manifesto do aplicativo GitHub, facilitando a criação e o compartilhamento dos designs de referência do aplicativo GitHub com a comunidade do GitHub.

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

1. Gerar um novo aplicativo GitHub.
2. Abra o projeto que você criou e personalize as configurações no arquivo app.yml. O Probot usa as configurações no app.yml como parâmetros do manifesto do aplicativo GitHub.
3. Adicione o código personalizado do seu aplicativo.
4. Execute o aplicativo GitHub localmente ou hospede-o em qualquer lugar que desejar. Ao acessar a URL do aplicativo hospedado, você encontrará uma página web com o botão de Registrar o aplicativo GitHub, em que as pessoas podem clicar para criar um aplicativo pré-configurado. A página abaixo é a implementação do Probot da etapa 1 no fluxo do manifesto do aplicativo GitHub:

Ao usar dotenv, o Probot cria um arquivo .env e define o APP_ID, a PRIVATE_KEY, e as variáveis de ambiente WEBHOOK_SECRET com os valores recuperados da configuração do aplicativo.

Hospedar seu aplicativo com Glitch

Você pode ver um exemplo do aplicativo Probot que usa o Glitch para hospedar e compartilhar o aplicativo. O exemplo usa a API de verificação e seleciona as verificações e permissões necessárias dos eventos da API e 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. Consulte "Sobre a Glitch" para aprender sobre como mesclar aplicativos Glitch.