Início Rápido para a criação de Aplicativos do GitHub

Introdução

GitHub Appss permitem automatizar processos ou integrar outras plataformas com GitHub. Para obter mais informações, confira "Sobre a criação de Aplicativos do GitHub".

Este início rápido descreve como criar rapidamente um GitHub App. Quando uma solicitação pull é aberta em um repositório ao qual o aplicativo recebeu acesso, o aplicativo adicionará um comentário à solicitação pull.

Este início rápido usa código predefinido para ajudar você a começar rapidamente. Para obter um tutorial mais detalhado para ajudar você a escrever o código, confira "Criar um Aplicativo GitHub que responde a eventos de webhook".

Pré-requisitos

Seu computador ou codespace deve usar Node.js versão 12 ou superior. Para obter mais informações, confira Node.js.

Etapa 1: clonar o código do aplicativo

Para ajudar você a começar rapidamente, escrevemos o código que você poderá usar. Para aprender a escrever o código por conta própria, confira "Criar um Aplicativo GitHub que responde a eventos de webhook".

Clone o repositório github/github-app-js-sample. Para obter mais informações, confira "Clonar um repositório". Você pode usar um clone local ou GitHub Codespaces.
Na janela do terminal, navegue até o diretório em que o clone está armazenado.
Execute npm install para instalar as dependências.

Etapa 2: obter a URL de proxy de webhook

Para desenvolver seu aplicativo localmente, você pode usar a URL de proxy de webhook para encaminhar webhooks de GitHub para seu computador ou codespace. Este início rápido usa o Smee.io para fornecer a URL de proxy de webhook e encaminhar os webhooks.

No navegador, navegue até https://smee.io/.
Clique em Iniciar um novo canal.
Copie a URL completa em "URL de Proxy de Webhook". Você usará esta URL em uma etapa posterior.

Etapa 3: Registrar o GitHub App

As etapas a seguir orientarão você na definição das configurações de aplicativo necessárias para este início rápido. Para saber mais sobre essas configurações, confira "Registrar um Aplicativo GitHub".

No canto superior direito de qualquer página do GitHub, clique na foto do seu perfil.
Acesse as configurações da sua conta.
- Para um aplicativo de propriedade de uma conta pessoal, clique em Configurações.
- Para um aplicativo de propriedade de uma organização:
  1. Clique em Suas organizações.
  2. À direita da organização, clique em Configurações.
Na barra lateral esquerda, clique em Configurações do desenvolvedor.
Na barra lateral esquerda, clique em GitHub Apps .
Clique em Novo Aplicativo do GitHub.
Em "Nome do GitHub App", insira um nome para seu aplicativo. Por exemplo, USERNAME-quickstart-app em que USERNAME é o nome de usuário do GitHub.
Em "URL da Home Page", insira https://github.com/github/github-app-js-sample#readme.
Ignore as seções "Identificar e autorizar usuários" e "Pós-instalação" deste início rápido. Para saber mais sobre essas configurações, confira "Registrar um Aplicativo GitHub".
Verifique se Ativo está marcado em "Webhooks".
Em "URL de Webhook", insira a URL de proxy de webhook da etapa anterior. Para obter mais informações, confira "Etapa 2: obter uma URL de proxy de webhook".
Em "Segredo do webhook", insira uma cadeia de caracteres aleatória. Você usará esta cadeia de caracteres mais tarde.
Em "Permissões de repositório", ao lado de "Solicitações de pull", selecione Leitura e gravação.
Em "Assinar os eventos", selecione Solicitação de pull.
Em "Em que local este GitHub App pode ser instalado?", selecione Somente nesta conta.
Clique em Criar Aplicativo do GitHub.

Etapa 4: armazenar as informações e credenciais de identificação do aplicativo

Neste início rápido, você armazenará as credenciais de seu aplicativo e as informações de identificação como variáveis de ambiente em um arquivo .env. Quando você implantar seu aplicativo, o ideal será alterar a forma como armazena as credenciais. Para obter mais informações, confira "Implantar seu aplicativo".

Verifique se está em um computador seguro antes de executar essas etapas, pois você armazenará suas credenciais localmente.

Criar um arquivo `.env`

Seu repositório clonado inclui .env no arquivo .gitignore. Isso impedirá você de fazer um commit acidental das credenciais do aplicativo. Para obter mais informações sobre os arquivos .gitignore, confira "Ignorar arquivos".

Navegue até o diretório em que o clone do github/github-app-js-sample está armazenado.
Crie um arquivo chamado .env no nível superior desse diretório.

Adicione o conteúdo a seguir ao arquivo .env. Substitua YOUR_HOSTNAME pelo nome de sua instância do GitHub Enterprise Server. Você atualizará os outros valores em uma etapa posterior.

Text

APP_ID="YOUR_APP_ID"
WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
HOSTNAME="YOUR_HOSTNAME"

APP_ID="YOUR_APP_ID"
WEBHOOK_SECRET="YOUR_WEBHOOK_SECRET"
PRIVATE_KEY_PATH="YOUR_PRIVATE_KEY_PATH"
HOSTNAME="YOUR_HOSTNAME"

Navegue até as configurações de aplicativo

Se você saiu das configurações do aplicativo depois de criá-lo, navegue até a página de configurações do seu aplicativo:

No canto superior direito de qualquer página do GitHub, clique na foto do seu perfil.
Acesse as configurações da sua conta.
- Para um aplicativo de propriedade de uma conta pessoal, clique em Configurações.
- Para um aplicativo de propriedade de uma organização:
  1. Clique em Suas organizações.
  2. À direita da organização, clique em Configurações.
Na barra lateral esquerda, clique em Configurações do desenvolvedor.
Na barra lateral esquerda, clique em GitHub Apps .
Ao lado do nome do aplicativo, clique em Editar.

Obtenha suas credenciais de aplicativo e informações de identificação

Na página de configurações do aplicativo, ao lado de "ID do aplicativo", localize a ID do aplicativo para o seu aplicativo.
No arquivo .env, substitua YOUR_APP_ID pela ID do seu aplicativo.
Na página de configurações do aplicativo, em "Chaves privadas", clique em Gerar uma chave privada. Você verá uma chave privada no formato PEM baixado no seu computador. Para obter mais informações, confira "Como gerenciar chaves privadas para Aplicativos GitHub".
Se você estiver usando um codespace, mova o arquivo PEM baixado para o codespace para que ele possa acessar o arquivo.
No arquivo .env, substitua YOUR_PRIVATE_KEY_PATH pelo caminho completo para a chave privada, incluindo a extensão .pem.
No arquivo .env, substitua YOUR_WEBHOOK_SECRET pelo segredo do webhook do seu aplicativo. Se você esqueceu o segredo do webhook, em "Segredo do webhook (opcional)", clique em Alterar segredo. Insira um novo segredo e clique em Salvar alterações.

Etapa 5: instalar seu aplicativo

Para que seu aplicativo deixe um comentário sobre solicitações de pull em um repositório, ele deve ser instalado na conta que possui o repositório e ter acesso ao mesmo. Como seu aplicativo é privado, ele só pode ser instalado na conta que possui o aplicativo.

Na conta que possui o aplicativo que você criou, crie um repositório para instalar o aplicativo. Para obter mais informações, confira "Criar um repositório".
Se você saiu das configurações do aplicativo depois de criá-lo, volte à página de configurações dele. Para obter mais informações, confira "Navegue até as configurações do aplicativo".
Clique em Página pública.
Clique em Instalar.
Selecione Selecionar apenas repositórios.
Selecione o menu suspenso Selecionar repositórios e clique no repositório escolhido no início desta seção.
Clique em Instalar.

Etapa 6: iniciar o servidor

Para teste, você usará seu computador ou o codespace como servidor. Seu aplicativo só estará ativo quando seu servidor estiver em execução.

Em uma janela de terminal, navegue até o diretório onde seu clone de github/github-app-js-sample está armazenado.
Para receber webhooks encaminhados do Smee.io, execute npx smee -u WEBHOOK_PROXY_URL -t http://localhost:3000/api/webhook. Substitua WEBHOOK_PROXY_URL pela URL de proxy de webhook. Se você esqueceu a URL, poderá encontrá-la no campo "URL do webhook" na página de configurações do aplicativo.

Você deverá ver uma saída semelhante a esta, em que WEBHOOK_PROXY_URL é a URL de proxy de webhook:
```
Forwarding WEBHOOK_PROXY_URL to http://localhost:3000/api/webhook
Connected WEBHOOK_PROXY_URL
```
Em uma segunda janela de terminal, navegue até o diretório onde seu clone do github/github-app-js-sample está armazenado.
Execute npm run server. Seu terminal deve dizer: Server is listening for events at: http://localhost:3000/api/webhook.

Etapa 7: testar o aplicativo

Agora que o servidor está executando e recebendo eventos de webhooks encaminhados, teste o aplicativo abrindo uma solicitação de pull.

Abra uma solicitação de pull no repositório que você criou na Etapa 5: instalar seu aplicativo. Para obter mais informações, confira "Como criar uma solicitação de pull".
Navegue até a URL de proxy de webhook no smee.io. Você deve ver um evento pull_request. Isso indica que GitHub enviou com êxito um evento de solicitação de pull quando você criou a solicitação de pull.
No terminal em que npm run server foi executado, você deverá ver algo como "Recebeu um evento de solicitação de pull para #1" em que o inteiro após o # é o número da solicitação de pull que você abriu.
Na linha do tempo da sua solicitação de pull, você deverá ver um comentário do seu aplicativo. O comentário usa o conteúdo do arquivo message.md em seu repositório clonado.
Em ambas as janelas do terminal, insira Ctrl+C para interromper o servidor e parar de escutar por webhooks encaminhados.

Próximas etapas

Agora que você tem um aplicativo, convém expandir o código do aplicativo, implantá-lo e torná-lo público.

Modificar o código do aplicativo

Bifurque o repositório do github/github-app-js-sample e modifique o código para responder a diferentes eventos de webhook ou fazer solicitações de API diferentes. Para obter mais informações sobre o código, confira "Criar um Aplicativo GitHub que responde a eventos de webhook".

Lembre-se de atualizar as permissões do aplicativo se ele precisar de permissões adicionais para as solicitações de API que você deseja fazer ou os eventos de webhook que você deseja receber. Para obter mais informações, confira "Escolhendo permissões para um Aplicativo GitHub".

Implante seu aplicativo

Este tutorial usou seu computador ou o codespace como servidor. Depois que o aplicativo estiver pronto para uso em produção, você deverá implantar seu aplicativo em um servidor dedicado. Por exemplo, você pode usar o Serviço de Aplicativo do Azure.

Depois de definir um servidor, atualize a URL do webhook nas configurações do aplicativo. Você não deve usar o Smee.io para encaminhar os webhooks em produção.

Você também precisará atualizar as constantes port e host no código. Para obter mais informações, confira "Criar um Aplicativo GitHub que responde a eventos de webhook".

Você nunca deve divulgar a chave privada ou o segredo do webhook do aplicativo. Este tutorial armazenou as credenciais do aplicativo em um arquivo .env gitignored. Ao implantar seu aplicativo, você deve escolher uma forma segura de armazenar as credenciais e atualizar o código para obter o valor de acordo. Por exemplo, você pode armazenar as credenciais em uma variável de ambiente no servidor onde seu aplicativo está implantado. Use também um serviço de gerenciamento de segredos como o Azure Key Vault.

Se você quiser compartilhar seu aplicativo com outros usuários e organizações, torne o aplicativo público. Para obter mais informações, confira "Tornar um aplicativo do GitHub público ou privado".

Seguir as práticas recomendadas

Você deve ter como objetivo seguir as melhores práticas com seu GitHub App. Para obter mais informações, confira "Práticas recomendadas para criar um aplicativo do GitHub".

Início Rápido para a criação de Aplicativos do GitHub

Neste artigo