Migrar aplicativos OAuth para aplicativos GitHub

Conheça as vantagens de migrar seu OAuth app para um GitHub App e saiba como migrar seu OAuth app.

Neste artigo

Benefícios da migração de OAuth apps para GitHub Apps

Os GitHub Apps são a maneira recomendada de se integrar ao GitHub. GitHub Apps oferecem muitas vantagens sobre OAuth apps, incluindo:

  • recursos de segurança aprimorados, como permissões refinadas, escolha sobre o acesso ao repositório e tokens de curta duração
  • a capacidade de agir de maneira independente de um usuário ou em nome dele
  • limites de taxa escalonáveis
  • webhooks internos

Para saber mais, confira Sobre a criação de Aplicativos do GitHub.

Como converter um OAuth app em um GitHub App

As etapas a seguir fornecem uma visão geral de como migrar de um OAuth app para um GitHub App. As etapas específicas dependem do aplicativo.

1. Revisar seu OAuth app

Familiarize-se novamente com o código do OAuth app. As solicitações de API que o OAuth app faz ajudarão você a decidir as permissões que devem ser selecionadas para o GitHub App.

Além disso, há alguns pontos de extremidade da API REST que não estão disponíveis para os OAuth apps. Verifique se todos os pontos de extremidade REST que você usa estão disponíveis para os GitHub Apps examinando Pontos de extremidade disponíveis para tokens de acesso de instalação do aplicativo GitHub.

2. Registrar um GitHub App

Registre um novo GitHub App. Para saber mais, confira Registrar um Aplicativo GitHub.

Em comparação com um OAuth app, você tem mais controle sobre as configurações do GitHub App. Algumas das principais adições são:

  • Ao contrário de um OAuth app, que sempre age em nome de um usuário, você pode fazer com que o GitHub App execute ações como si mesmo ou em nome de um usuário. Se você não quiser que o novo GitHub App execute ações em nome de um usuário, ignore as configurações "Identificação e autorização de usuários". Para saber mais, confira Sobre a autenticação com um GitHub App.

  • Use webhooks para notificar o GitHub App quando ocorrerem eventos específicos. Ao contrário dos webhooks dos OAuth apps, que você precisa configurar por meio da API para cada repositório ou organização, os webhooks são integrados aos GitHub Apps. Ao registrar seu GitHub App, você pode selecionar os eventos de webhook que deseja receber. Além disso, se atualmente o OAuth app usar a sondagem para determinar se um evento ocorreu, considere a possibilidade de assinar webhooks para ajudar seu GitHub App a permanecer dentro do limite de taxa. Para saber mais, confira Usar webhooks com aplicativos GitHub.

  • Com um OAuth app, você solicita escopos quando um usuário autoriza seu aplicativo. Com um GitHub App, você especifica permissões nas configurações do aplicativo. Essas permissões são mais granulares do que os escopos e permitem que você selecione apenas as permissões de que seu aplicativo precisa. Além disso, essas permissões são mapeadas para pontos de extremidade da API REST e eventos de webhook, para que você possa determinar com facilidade as permissões que o GitHub App precisa para acessar um ponto de extremidade específico da API REST ou assinar um webhook específico. No momento, as permissões não estão documentadas para solicitações do GraphQL. Para saber mais, confira Escolhendo permissões para um Aplicativo GitHub.

3. Modificar o código do aplicativo

Depois de registrar um GitHub App, adapte o código do OAuth app antigo para trabalhar com o novo GitHub App.

Atualizar autenticação

Você precisará atualizar o código do aplicativo para lidar com a autenticação de API para o GitHub App. Um GitHub App pode ser autenticado de três maneiras:

Se você estiver usando a biblioteca oficial do Octokit.js do GitHub, use o objeto interno App para autenticar. Para obter exemplos, confira Scripts com a API REST e o JavaScript e Criar um Aplicativo GitHub que responde a eventos de webhook.

Revisar limites de taxa

Confira as diferenças de limites de taxa entre os OAuth apps e os GitHub Apps. Os GitHub Apps usam regras deslizantes para limites de taxa, que podem aumentar de acordo com o número de repositórios e de usuários na organização. Para saber mais, confira Limites de taxa para aplicativos GitHub.

Se possível, considere o uso de solicitações condicionais e a possibilidade de assinar webhooks em vez de sondagem para ajudar você a permanecer dentro dos limites de taxa. Para obter mais informações sobre as solicitações condicionais, confira Práticas recomendadas para usar a API REST. Para obter mais informações sobre como usar webhooks com o GitHub App, confira Usar webhooks com aplicativos GitHub e Criar um Aplicativo GitHub que responde a eventos de webhook.

Testar seu código

Teste o novo GitHub App para verificar se o código funciona conforme o esperado.

4. Divulgar seu novo GitHub App

Se você quiser que outras contas possam usar seu novo GitHub App, verifique se o aplicativo é público. Se você quiser tornar seu GitHub App mais detectável, liste o aplicativo no GitHub Marketplace. Para obter mais informações, confira Sobre o GitHub Marketplace para aplicativos e Tornar um aplicativo do GitHub público ou privado.

5. Instruir os usuários a fazer a migração

Depois que o novo GitHub App estiver pronto, instrua os usuários do OAuth app antigo a migrar para o novo GitHub App. Não há uma forma de migrar automaticamente os usuários. Cada usuário precisa instalar e/ou autorizar seu GitHub App por conta própria.

Como proprietário do aplicativo, você deve incluir chamadas à ação para incentivar os usuários a instalar/autorizar o novo GitHub App e revogar a autorização para o OAuth app antigo. Você também deve atualizar qualquer documentação ou elementos de interface do usuário.

Solicitar aos usuários que instalem seu GitHub App

Se você desejar que o GitHub App faça solicitações de API em nome próprio ou acesse recursos da organização ou do repositório, o usuário precisará instalar o GitHub App. Quando um usuário instala um GitHub App na respectiva conta ou organização, ele escolhe quais repositórios o aplicativo pode acessar e concede ao aplicativo as permissões de organização e repositório solicitadas.

Para ajudar os usuários a instalar o GitHub App, adicione um link à página da Web do aplicativo em que os usuários podem clicar para instalar o GitHub App. O formato da URL de instalação é https://github.com/apps/YOUR_APP_NAME/installations/new. Substitua YOUR_APP_NAME pelo nome do slug do seu GitHub App, que você pode encontrar no campo "Link público" na página de configurações do GitHub App.

Para selecionar previamente todos os repositórios aos quais seu OAuth app teve acesso, acrescente /permissions e consulte parâmetros à URL de instalação. Isso ajuda os usuários a permitir acesso ao GitHub App nos repositórios aos quais o OAuth app já têm acesso. Os parâmetros de consulta são:

  • suggested_target_id: a ID do usuário ou da organização que está instalando seu GitHub App. Este parâmetro é necessário.
  • repository_ids[]: as IDs do repositório a serem selecionadas para a instalação. Se isso for omitido, todos os repositórios serão selecionados. O número máximo de repositórios que pode ser pré-selecionado é 100. Para ver a lista de repositórios aos quais o OAuth app tem acesso, use os pontos de extremidade Listar os repositórios do usuário autenticado e Listar os repositórios da organização.

Por exemplo: https://github.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID.

Para obter mais informações sobre como instalar os GitHub Apps, confira Instalando um Aplicativo GitHub por meio do GitHub Marketplace em sua conta pessoal, Instalando um Aplicativo GitHub por meio do GitHub Marketplace em suas organizações, Instalando um Aplicativo GitHub de terceiros e Instalando seu próprio Aplicativo GitHub.

Solicitar aos usuários que autorizem seu aplicativo

Se você quiser que o GitHub App faça solicitações de API em nome de um usuário, o usuário precisará autorizar o aplicativo. Quando um usuário autoriza um aplicativo, ele concede ao aplicativo permissão para agir no nome dele e concede as permissões de conta solicitadas pelo aplicativo. Se o aplicativo estiver instalado em uma conta da organização, cada usuário dessa organização precisará autorizar o aplicativo para que o aplicativo aja no respectivo nome.

Para solicitar aos usuários que autorizem seu aplicativo, você os conduzirá pelo fluxo do aplicativo Web ou pelo fluxo do dispositivo. Para saber mais, confira Como gerar um token de acesso do usuário para um GitHub App.

Para obter mais informações sobre como autorizar GitHub Apps, confira Autorizando aplicativos GitHub.

Incentivar os usuários a revogar o acesso ao OAuth app

Você também deve incentivar os usuários a revogar o acesso ao OAuth app antigo. Isso ajudará você a descontinuar o uso por completo do OAuth app e ajudará a manter os dados dos usuários em segurança. Para saber mais, confira Revisar aplicativos OAuth autorizados.

Atualizar as interfaces ou a documentação

Você deve atualizar qualquer interface do usuário ou documentação relacionada ao seu aplicativo para refletir a mudança de um OAuth app para um GitHub App.

6. Remover webhooks do OAuth app antigo

Quando um usuário instala seu GitHub App e permite acesso a um repositório, você deve remover todos os webhooks do OAuth app antigo. Se o novo GitHub App e o OAuth app antigo responderem a webhooks para o mesmo evento, o usuário poderá observar um comportamento duplicado.

Para remover webhooks do repositório, escute o webhook installation_repositories com a ação added. Quando o GitHub App receber esse evento, você poderá usar a API REST para excluir o webhook nesses repositórios do OAuth app. Para saber mais, confira Eventos e cargas de webhook e Pontos de extremidade da API REST para webhooks de repositório.

Da mesma forma, para remover webhooks da organização, escute o webhook installation com a ação created. Quando o GitHub App recebe esse evento para uma organização, você pode usar a API REST para excluir o webhook nessa organização e os repositórios correspondentes do OAuth app. Para saber mais, confira Eventos e cargas de webhook, Pontos de extremidade de API REST para webhooks da organização e Pontos de extremidade da API REST para webhooks de repositório.

7. Excluir o OAuth app antigo

Depois que os usuários migrarem para o novo GitHub App, você deverá excluir o OAuth app antigo. Isso ajudará a evitar o abuso das credenciais do OAuth app. Essa ação também revogará todas as autorizações restantes do OAuth app. Para saber mais, confira Excluir um aplicativo OAuth. Caso o OAuth app esteja listado no GitHub Marketplace, talvez seja necessário entrar em contato com o Suporte do GitHub para remover seu aplicativo do marketplace primeiro.