Migrando aplicativos OAuth para aplicativos GitHub

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

Neste artigo

Benefícios de migrar de OAuth apps para GitHub Apps

GitHub Apps são a maneira recomendada de integrar com GitHub. GitHub Apps oferecem muitas vantagens em relação a 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 integrados

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

Convertendo OAuth app em 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. Examine seu OAuth app

Familiarize-se novamente com o código para sua OAuth app. As solicitações de API que você OAuth app faz ajudarão você a decidir quais permissões selecionar para sua GitHub App.

Além disso, há alguns endpoints da API REST que não estão disponíveis para OAuth apps. Verifique se quaisquer endpoints REST que você use estão disponíveis para GitHub Apps consultando 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 Registrando um aplicativo GitHub.

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

  • Ao contrário de um OAuth app, que sempre atua em nome de um usuário, você pode fazer com que seu GitHub App execute ações por conta própria 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 de "Identificar e autorizar usuários". Para saber mais, confira Sobre a autenticação com um aplicativo GitHub.

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

  • Ao usar um OAuth app, você solicita escopos quando um usuário autoriza o seu aplicativo. Com um GitHub App, especifique 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 endpoints da API REST e eventos de webhook, para que você possa determinar facilmente de quais permissões seu GitHub App precisa para acessar um endpoint 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 seu antigo OAuth app para trabalhar com seu novo GitHub App.

Atualizar autenticação

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

Se você estiver usando a biblioteca oficial Octokit.js de GitHub, poderá usar o objeto integrado App para se autenticar. Para obter exemplos, confira Script em API REST e JavaScript e Criando um aplicativo GitHub que responde a eventos de webhook.

Revisar limites de taxa

Examine as diferenças nos limites de taxa entre OAuth apps e GitHub Apps. GitHub Apps use regras deslizantes para limites de taxa, que podem aumentar com base no número de repositórios e no número 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 seu GitHub App, consulte Usando webhooks com aplicativos GitHub e Criando um aplicativo GitHub que responde a eventos de webhook.

Testar seu código

Teste seu novo GitHub App para garantir que seu código funcione conforme o esperado.

4. Divulgue seu novo GitHub App

Se você quiser que outras contas possam usar suas novas GitHub App, verifique se o aplicativo é público.Para obter mais informações, consulte Tornando um aplicativo 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 seu antigo OAuth app a migrar para o novo GitHub App. Não há uma forma de migrar automaticamente os usuários. Cada usuário deve instalar e/ou autorizar o 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 ou autorizar o novo GitHub App e revogar a autorização do antigo OAuth app. Você também deve atualizar qualquer documentação ou elementos de interface do usuário.

Solicitar que os usuários instalem seu GitHub App

Se você quiser que seu GitHub App faça solicitações de API em seu próprio nome ou acesse recursos da organização ou do repositório, o usuário deverá instalar seu GitHub App. Quando um usuário instala uma GitHub App em sua 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 que ele solicitou.

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

Para selecionar previamente todos os repositórios aos quais você OAuth app teve acesso, você pode acrescentar /permissions e consultar parâmetros à URL de instalação. Isso ajuda os usuários a conceder ao seu GitHub App acesso aos repositórios aos quais seu OAuth app já tem acesso. Os parâmetros de consulta são:

  • suggested_target_id: A ID do usuário ou da organização que está instalando sua GitHub App. Este parâmetro é necessário.
  • repository_ids[]: os IDs do repositório a serem selecionados 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 obter uma lista de repositórios aos quais OAuth app tem acesso, use os endpoints Listar repositórios para o usuário autenticado e Listar repositórios da organização.

Por exemplo: http(s)://HOSTNAME/github-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 instalarGitHub Apps, consulte Instalando um Aplicativo GitHub de terceiros e Instalando seu próprio aplicativo GitHub.

Solicitar aos usuários que autorizem seu aplicativo

Se você quiser fazer GitHub App solicitações de API em nome de um usuário, o usuário deverá 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 Gerando um token de acesso do usuário para um aplicativo GitHub.

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

Incentive seus usuários a revogar o acesso OAuth app

Você também deve incentivar seus usuários a revogar o acesso ao seu OAuth app antigo. Isso ajudará você a se afastar totalmente da sua OAuth app e ajudará a manter os dados dos usuários seguros. Para saber mais, confira Revisar aplicações OAuth autorizadas.

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 alteração de um OAuth app para GitHub App.

6. Remova os webhooks do seu antigo OAuth app

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

Para remover webhooks do repositório, escute o webhook installation_repositories com a ação added. Quando seu GitHub App receber esse evento, você poderá usar a API REST para excluir o webhook nesses repositórios do seu 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 seu/sua GitHub App receber esse evento para uma organização, você poderá usar a API REST para excluir o webhook dessa organização e dos repositórios correspondentes da sua 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. Exclua o OAuth app antigo.

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