Esta versão do GitHub Enterprise foi descontinuada em 2021-09-23. Nenhum lançamento de patch será feito, mesmo para questões críticas de segurança. Para obter melhor desempenho, melhorar a segurança e novos recursos, upgrade to the latest version of GitHub Enterprise. Para ajuda com a atualização, contact GitHub Enterprise support.

Criar um aplicativo do GitHub a partir de um manifesto

Um manifesto do aplicativo GitHub é um aplicativo GitHub pré-configurado que você pode compartilhar com qualquer pessoa que queira usar seu aplicativo em seus repositórios pessoais. O fluxo do manifesto permite que alguém crie, instale, e comece a estender rapidamente um aplicativo GitHub sem a necessidade de registrar o aplicativo ou conectar o registro ao código do aplicativo hospedado.

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.

Observação: Você deve concluir todos os três passos do fluxo do manifesto do aplicativo GitHub dentro de uma hora.

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.

Criar um manifesto do aplicativo GitHub

Parâmetros do manifesto do aplicativo GitHub

NomeTipoDescrição
namestringO nome do aplicativo GitHub.
urlstringObrigatório. A página inicial do seu aplicativo GitHub.
hook_attributesobjetoA configuração do webhook do aplicativo GitHub.
redirect_urlstringO URL completo para onde redirecionar um usuário iniciar a criação de um aplicativo GitHub a partir de um manifesto.
callback_urlstringUma URL completa para a qual redirecionar após alguém autorizar uma instalação.
descriçãostringUma descrição do aplicativo GitHub.
públicobooleanDefina como verdadeiro quando o seu aplicativo GitHub estiver disponível para o público ou falso quando for acessível somente pelo proprietário do aplicativo.
default_eventsarrayLista de eventos assinada pelo aplicativo GitHub.
default_permissionsobjetoO conjunto de permissões exigido pelo aplicativo GitHub. O formato do objeto usa o nome de permissão para a chave (por exemplo, problemas) e o tipo de acesso para o valor (por exemplo, gravar).

O objeto hook_attributes tem a chave a seguir:

NomeTipoDescrição
urlstringObrigatório. A URL do servidor que receberá as solicitações POST do webhook.
ativobooleanImplementar detalhes do evento quando esse hook é acionado. O padrão é verdadeiro.

Parâmetros

NomeTipoDescrição
estadostringUma 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 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">
 Create 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_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/ORGANIZATION/settings/apps/new?state=abc123" method="post">
 Create 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_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. Por exemplo:

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

Se você forneceu um parâmetro estado, você também verá esse parâmetro em 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, enviar o código temporário `em uma solicitaçãoPOSTpara [Criar um aplicativo GitHub a partir do ponto de extremidade](/rest/reference/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.

Observação: Esse ponto final tem limite de taxa. Consulte Limites de taxa para saber como obter seu status atual do limite de taxa.

POST /app-manifests/{code}/conversions

Para obter mais informações sobre a resposta do ponto de extremidade, 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:

Registrar um aplicativo GitHub do Probot

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.