Benefícios da migração de OAuth apps para GitHub Apps
Os GitHub Apps são a forma recomendada de integrar-se com o 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 integrados
Para saber mais, confira AUTOTITLE.
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. Revise 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 endpoints da API REST que não estão disponíveis para os OAuth apps. Verifique se todos os endpoints REST que você usa estão disponíveis para os GitHub Apps revisando AUTOTITLE.
2. Registrar um GitHub App
Registre um novo GitHub App. Para saber mais, confira AUTOTITLE.
Em comparação com um OAuth app, você tem mais controle sobre as configurações de um 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 AUTOTITLE.
-
Você pode usar webhooks para notificar o GitHub App quando eventos específicos ocorrerem. Ao contrário dos webhooks para OAuth apps, que devem ser configurados por meio da API para cada repositório ou organização, os webhooks já vêm 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 AUTOTITLE.
-
Com um OAuth app, você solicita permissões 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 AUTOTITLE.
3. Modificar o código do aplicativo
Depois de registrar um GitHub App, adapte o código do OAuth app antigo para funcionar 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:
- Como o próprio aplicativo, para obter ou modificar detalhes sobre o registro do GitHub App ou para gerar um token de acesso à instalação. Para saber mais, confira AUTOTITLE.
- Como uma instalação de aplicativo, para executar ações em nome de si mesmo. Para saber mais, confira AUTOTITLE.
- Em nome de um usuário, para atribuir ações a um usuário. Para saber mais, confira AUTOTITLE.
Se você estiver usando a biblioteca oficial Octokit.js de GitHub, pode usar o objeto incorporado para autenticar. Para obter exemplos, veja AUTOTITLE e AUTOTITLE.
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 AUTOTITLE.
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 AUTOTITLE. Para obter mais informações sobre como usar webhooks com o GitHub App, confira AUTOTITLE e AUTOTITLE.
Testar seu código
Teste o novo GitHub App para verificar se o código funciona conforme o esperado.
4. Divulgue seu novo GitHub App
Se você quiser que outras contas possam usar seu novo GitHub App, verifique se o aplicativo é público.Para obter mais informações, confira AUTOTITLE.
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 é . Substitua 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 GitHub App.
Para selecionar previamente todos os repositórios aos quais seu OAuth app teve acesso, acrescente e consulte parâmetros à URL de instalação. Isso ajuda os usuários a conceder acesso ao GitHub App aos repositórios aos quais o OAuth app já tem acesso. Os parâmetros de consulta são:
- : a ID do usuário ou da organização que está instalando seu GitHub App. Este parâmetro é necessário.
- : 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 obter uma lista de repositórios aos quais o OAuth app tem acesso, use os endpoints de Listar repositórios do usuário autenticado e Listar repositórios da organização.
Por exemplo: .
Para mais informações sobre a instalação dos GitHub Apps, consulte AUTOTITLE e AUTOTITLE.
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 AUTOTITLE.
Para obter mais informações sobre como autorizar GitHub Apps, confira AUTOTITLE.
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 AUTOTITLE.
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 os webhooks do seu 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, você pode monitorar o webhook associado a uma ação específica. Quando o GitHub App receber esse evento, você poderá utilizar a API REST para excluir o webhook nesses repositórios do OAuth app. Para saber mais, confira AUTOTITLE e AUTOTITLE.
Da mesma forma, para remover webhooks da organização, escute o webhook com a ação . 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 nos repositórios correspondentes do OAuth app. Para saber mais, confira AUTOTITLE, AUTOTITLE e AUTOTITLE.
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 AUTOTITLE. 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.