Introdução
Este guia irá ajudá-lo a criar um aplicativo GitHub e executá-lo em um servidor. O aplicativo que você criar adicionará uma etiqueta a todos os novos problemas abertos no repositório onde o aplicativo está instalado.
Este projeto orientará você no seguinte:
- Programar seu aplicativo para ouvir eventos
- Usar a biblioteca do Octokit.rb para realizar operações da API REST
Observação: este guia demonstra o processo de desenvolvimento de aplicativos usando a linguagem de programação Ruby. No entanto, há muitas variantes do Octokit. Se preferir o JavaScript, use o Probot e o Node.js para desenvolver Aplicativos do GitHub.
Uma concluídas as etapas, você estará pronto para desenvolver outros tipos de integrações usando o conjunto completo das APIS do GitHub.
Pré-requisitos
Você pode achar útil ter um entendimento básico do seguinte:
Mas é possível acompanhar o processo em qualquer nível de experiência. Nós vamos nos conectar a informações de que você precisa ao longo do caminho!
Antes de começar, você precisará fazer o seguinte:
-
Clone o repositório Como usar a API do GitHub no seu aplicativo.
$ git clone https://github.com/github-developer/using-the-github-api-in-your-app.git
Dentro do diretório, você encontrará um arquivo
template_server.rb
com o código de modelo que será usado neste guia de início rápido e um arquivoserver.rb
com o código do projeto concluído. -
Siga as etapas descritas no guia de início rápido Como configurar seu ambiente de desenvolvimento para configurar e executar o servidor de aplicativos
template_server.rb
. Se você já concluiu um guia de início rápido do Aplicativo do GitHub além do guia Como configurar seu ambiente de desenvolvimento, registre um novo Aplicativo do GitHub e inicie um novo canal do Smee para usá-lo com este guia de início rápido.Este guia de início rápido inclui o mesmo código
template_server.rb
do guia de início rápido Como configurar seu ambiente de desenvolvimento. Observação: ao acompanhar o guia de início rápido Como configurar seu ambiente de desenvolvimento, use os arquivos de projeto incluídos no repositório Como usar a API do GitHub no seu aplicativo.Confira a seção Solução de problemas se você estiver tendo problemas ao configurar seu modelo de Aplicativo do GitHub.
Criar o aplicativo
Agora que você está familiarizado com o código template_server.rb
, crie um código que adiciona automaticamente o rótulo needs-response
a todos os problemas em aberto no repositório no qual o aplicativo está instalado.
O arquivo template_server.rb
contém o código do modelo de aplicativo que ainda não foi personalizado. Neste arquivo, você verá um espaço reservado para manipular eventos de webhook e outro código para inicializar um cliente Octokit.rb.
Observação: template_server.rb
contém muitos comentários sobre o código que complementam este guia e explicam detalhes técnicos adicionais. Você pode considerar útil ler os comentários do arquivo antes de seguir com esta seção, para obter uma visão geral de como o código funciona.
O código personalizado final que você criará até o final deste guia é fornecido em server.rb
. Mas espere até o final para olhar isso!
Estas são as etapas que você concluirá para criar seu primeiro aplicativo GitHub:
- Atualizar as permissões do aplicativo
- Adicionar um tratamento de evento
- Criar um novo rótulo
- Adicionar um tratamento de rótulo
Etapa 1. Atualizar as permissões do aplicativo
Quando você registrou seu aplicativo pela primeira vez, aceitou as permissões padrão, o que significa que o aplicativo não tem acesso à maioria dos recursos. Para este exemplo, seu aplicativo precisará de permissão para ler problemas e escrever etiquetas.
Para atualizar as permissões do aplicativo:
- Selecione seu aplicativo na página de configurações do aplicativo e clique em Permissões e Webhooks na barra lateral.
- Na seção "Permissões", encontre "Problemas" e selecione Leitura e Gravação na lista suspensa "Acesso" ao lado. A descrição diz que esta opção concede acesso a problemas e etiquetas, o que é exatamente o que você precisa.
- Na seção "Inscrever-se em eventos", selecione Problemas para se inscrever no evento.
- Clique em Salvar alterações na parte inferior da página.
- Se você instalou o aplicativo na sua conta, verifique seu e-mail e siga o link para aceitar novas permissões. Sempre que você alterar as permissões ou webhooks do seu aplicativo, os usuários que instalaram o aplicativo (incluindo você mesmo) precisarão aceitar as novas permissões antes que as alterações tenham efeito. Você também pode aceitar as novas permissões navegando até a página de instalações e clicando em "Configurar" ao lado do aplicativo. Você verá um banner no topo da página, permitindo que você saiba que o aplicativo está solicitando diferentes permissões. Clique em "Details" e clique em "Accept new permissions."
Ótimo! Seu aplicativo tem permissão para realizar as tarefas que você deseja que ele realize. Agora você pode adicionar o código para que ele funcione.
Etapa 2. Adicionar gerenciamento de evento
A primeira coisa que seu aplicativo precisa fazer é ouvir novos problemas que estão abertos. Agora que você se inscreveu no evento Problemas, começará a receber o webhook issues
, que é disparado quando determinadas ações relacionadas a problemas ocorrem. Você pode filtrar este tipo de evento para a ação específica que você deseja no seu código.
O GitHub envia as cargas de webhook como solicitações POST
. Como você encaminhou as cargas do webhook do Smee para o http://localhost/event_handler:3000
, o servidor receberá as cargas da solicitação POST
na rota post '/event_handler'
.
Uma rota post '/event_handler'
vazia já está incluída no arquivo template_server.rb
, que você baixou na seção Pré-requisitos. O encaminhamento vazio tem a seguinte forma:
post '/event_handler' do
# # # # # # # # # # # #
# ADD YOUR CODE HERE #
# # # # # # # # # # # #
200 # success status
end
Use essa rota para tratar o evento issues
adicionando o seguinte código:
case request.env['HTTP_X_GITHUB_EVENT']
when 'issues'
if @payload['action'] === 'opened'
handle_issue_opened_event(@payload)
end
end
Cada evento enviado pelo GitHub inclui um cabeçalho de solicitação chamado HTTP_X_GITHUB_EVENT
, que indica o tipo de evento na solicitação POST
. Por enquanto, você só está interessado nos tipos de eventos issues
. Cada evento tem um campo action
adicional que indica o tipo de ação que disparou os eventos. Para issues
, o campo action
pode ser assigned
, unassigned
, labeled
, unlabeled
, opened
, edited
, milestoned
, demilestoned
, closed
ou reopened
.
Para testar seu gerenciador de eventos, tente adicionar um método auxiliar temporário. Você atualizará isso mais tarde quando Adicionar um tratamento de rótulo. Por enquanto, adicione o código a seguir na seção helpers do
do código. Você pode colocar o novo método acima ou abaixo de qualquer outro método de ajuda. A ordem não importa.
def handle_issue_opened_event(payload)
logger.debug 'An issue was opened!'
end
Este método recebe uma carga de eventos formatada em JSON como argumento. Isso significa que você pode analisar a carga no método e detalhar os dados específicos de que você precisa. Você pode achar útil inspecionar a carga completa em algum momento: experimente alterar logger.debug 'An issue was opened!
para logger.debug payload
. A estrutura da carga observada deve corresponder ao que é mostrado na documentação do evento de webhook issues
.
Ótimo! É hora de testar as alterações.
Observação: você precisará reiniciar o servidor do Sinatra para testar as alterações. Insira Ctrl-C
para interromper o servidor e execute ruby template_server.rb
novamente. Caso não deseje fazer isso toda vez que alterar o código do aplicativo, observe o recarregamento.
No seu navegador, acesse o repositório onde você instalou seu aplicativo. Abra um novo problema neste repositório. O problema pode dizer o que você quiser. É apenas para teste.
Ao olhar novamente para o terminal, na saída, você verá a mensagem "An issue was opened!
Parabéns! Você adicionou um gerenciador de eventos ao seu aplicativo. 💪
Etapa 3. Criar um novo rótulo
Ok, seu aplicativo pode dizer quando os problemas estão abertos. Agora você deseja que ele adicione o rótulo needs-response
a qualquer problema recém-aberto em um repositório no qual o aplicativo está instalado.
Para que o rótulo seja adicionado em qualquer lugar, você precisará criar o rótulo personalizado no seu repositório. Você só terá de fazer isso uma vez. Para fins deste guia, crie a etiqueta manualmente no GitHub. No repositório, clique em Problemas, em Rótulos e clique em Novo rótulo. Dê ao novo rótulo o nome needs-response
.
Dica: não seria ótimo se o aplicativo pudesse criar o rótulo por meio de programação? Ele pode! Adicione o código para fazer isso por conta própria depois de concluir as etapas deste guia.
Agora que o rótulo existe, você pode programar seu aplicativo para usar a API REST a fim de adicionar o rótulo a qualquer problema recém-aberto.
Etapa 4. Adicionar gerenciamento de etiqueta
Parabéns! Você chegou à etapa final: adicionando o gerenciamento de etiquetas ao seu aplicativo. Para essa tarefa, o ideal será usar a biblioteca Octokit.rb do Ruby.
Na documentação do Octokit.rb, encontre a lista de métodos de rótulos. O método que recomendamos usar é o add_labels_to_an_issue
.
De volta a template_server.rb
, localize o método que você definiu anteriormente:
def handle_issue_opened_event(payload)
logger.debug 'An issue was opened!'
end
A documentação de add_labels_to_an_issue
mostra que você precisará transmitir três argumentos para este método:
- Repositório (cadeia de caracteres no formato
"owner/name"
) - Número do problema (inteiro)
- Etiquetas (array)
Você pode analisar a carga para obter o repositório e o número do problema. Como o nome do rótulo será sempre o mesmo (needs-response
) você pode transmiti-lo como uma cadeia de caracteres embutida em código na matriz de rótulos. Ao juntar essas peças, seu método atualizado pode parecer com isto:
# When an issue is opened, add a label
def handle_issue_opened_event(payload)
repo = payload['repository']['full_name']
issue_number = payload['issue']['number']
@installation_client.add_labels_to_an_issue(repo, issue_number, ['needs-response'])
end
Tente abrir um novo problema no seu repositório de teste e veja o que acontece! Se nada acontecer imediatamente, tente atualizar.
Você não verá muitas coisas no terminal, mas verá que o GitHub App adicionou um rótulo ao problema.
Se for assim, parabéns! Você construiu um aplicativo funcional com sucesso! 🎉
Você poderá ver o código final em server.rb
no repositório de modelo de aplicativo.
Confira "Próximas etapas" para descobrir ideias sobre o que você pode fazer em seguida.
Solução de problemas
Aqui estão alguns problemas comuns e algumas soluções sugeridas. Se você tiver qualquer outro problema, poderá pedir ajuda ou orientação em Discussões sobre APIs e integrações na Comunidade do GitHub.
-
P: Meu servidor não está ouvindo eventos. O cliente da Smee está sendo executado em uma janela de Terminal, e eu estou enviando eventos para o github.com. abrindo novos problemas, mas não vejo nenhuma saída na janela do Terminal onde estou executando o servidor.
R: Talvez você não tenha o domínio correto do Smee nas configurações do aplicativo. Acesse a página de configurações do aplicativo e verifique os campos mostrados em "Configurar seu ambiente de desenvolvimento para criar um aplicativo GitHub". Verifique se o domínio nesses campos corresponde ao domínio usado no comando
smee -u <unique_channel>
em "Configurar seu ambiente de desenvolvimento para criar um aplicativo GitHub". -
P: Meu aplicativo não funciona. Eu abri um novo problema, mas mesmo depois de atualizado, nenhuma etiqueta foi adicionado a ele.
R: Verifique se todos os seguintes itens são verdadeiros:
- Você instalou o aplicativo no repositório em que está abrindo o problema.
- O cliente do Smee está em execução em uma janela do terminal.
- O servidor Web está em execução sem erros em outra janela do terminal.
- Seu aplicativo tem permissões de leitura e gravação em problemas e está inscrito para emitir eventos.
- Você verificou seu email depois de atualizar as permissões e aceitou as novas permissões.
Conclusão
Depois de analisar este guia, você aprendeu os componentes básicos para o desenvolvimento dos aplicativos GitHub! Para resumir, você:
- Programou seu aplicativo para ouvir eventos
- Usou a biblioteca do Octokit.rb para fazer operações da API REST
Próximas etapas
Aqui estão algumas ideias do que você pode fazer a seguir:
- Reescreva seu aplicativo usando o GraphQL.
- Reescreva seu aplicativo em Node.js usando o Probot.
- Faça o aplicativo verificar se o rótulo
needs-response
já existe no problema e, em caso negativo, adicione-o. - Quando o bot adiciona a etiqueta com sucesso, é exibida uma mensagem no Terminal. (Dica: compare a ID do rótulo
needs-response
com a ID do rótulo na carga como uma condição para a mensagem, de modo que ela só seja exibida quando o rótulo relevante for adicionado e não qualquer outro rótulo). - Adicione uma página de aterrissagem ao aplicativo e conecte uma rota do Sinatra a ele.
- Mova o seu código para um servidor hospedado (como o Heroku). Não se esqueça de atualizar as configurações do seu aplicativo com o novo domínio.
- Compartilhe seu projeto ou receba orientações na Discussões sobre APIs e integrações na Comunidade do GitHub