Usar a API do GitHub no seu aplicativo

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

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:

• Aplicativos GitHub
• Webhooks
• A linguagem de programação Ruby
• APIs REST
• Sinatra

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:

1. 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 arquivo server.rb com o código do projeto concluído.

2. 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.

Estas são as etapas que você concluirá para criar seu primeiro aplicativo GitHub:

1. Atualizar as permissões do aplicativo
2. Adicionar um tratamento de evento
3. Criar um novo rótulo
4. 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:

1. Selecione seu aplicativo na página de configurações do aplicativo e clique em Permissões e Webhooks na barra lateral.
2. 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.
3. Na seção "Inscrever-se em eventos", selecione Problemas para se inscrever no evento.
4. Clique em Salvar alterações na parte inferior da página.
5. 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.

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.

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