Sobre os GitHub Apps
Um GitHub App é um tipo de integração que você pode criar para interagir com a funcionalidade do GitHub e estendê-la. Você pode criar um GitHub App para fornecer flexibilidade e reduzir o atrito nos processos, sem precisar conectar um usuário nem criar uma conta de serviço.
Os casos de uso comuns para osGitHub Apps incluem:
- Automação de tarefas ou de processos em segundo plano
- Suporte ao recurso "Entrar com o GitHub", que permite que os usuários entrem com a conta do GitHub para fornecer a identidade no seu ecossistema
- Como uma ferramenta de desenvolvedor, permissão de que os usuários trabalhem com o GitHub entrando no seu GitHub App, que, em seguida, pode agir em nome deles
- Integração da sua ferramenta ou de um serviço externo ao GitHub
Os GitHub Apps são atores independentes no GitHub. Um GitHub App age no próprio nome, o que significa que você não precisa manter um bot ou uma conta de serviço como um usuário separado. Eles também podem se autenticar como um usuário e agir em nome do usuário, usando as permissões concedidas a ele.
Um usuário ou uma organização pode ter até 100 GitHub Apps, mas não há limite de quantos podem ser instalados em uma conta.
Se você quiser que o seu aplicativo responda a eventos no GitHub, o aplicativo deverá assinar webhooks. Por exemplo, o ideal é que o seu aplicativo deixe um comentário quando uma solicitação de pull for aberta. Para obter mais informações, confira "Usar webhooks com aplicativos GitHub".
Durante o desenvolvimento, você pode executar seu aplicativo localmente para desenvolvimento. Depois que o aplicativo estiver pronto para uso em produção, você deverá implantar seu aplicativo em um servidor dedicado. Por exemplo, você pode usar o Serviço de Aplicativo do Azure.
Permissões e visibilidade para GitHub Apps
O GitHub Apps pode ser instalado diretamente em organizações e contas pessoais e conceder acesso a repositórios específicos. Eles vêm com webhooks integrados e permissões específicas e restritas. Ao configurar o GitHub App, você pode selecionar repositórios específicos para o aplicativo. Essas permissões determinam o que o aplicativo pode fazer por meio da API do GitHub, o que eles podem fazer em nome de um usuário conectado e quais webhooks o aplicativo pode receber. Quando o aplicativo é instalado em uma conta do usuário ou da organização, a pessoa que instala o aplicativo decide quais repositórios o aplicativo pode acessar nessa conta. Para obter mais informações, confira "Escolhendo permissões para um Aplicativo GitHub".
Por padrão, somente proprietários da organização podem gerenciar as configurações dos aplicativos GitHub em uma organização. Para permitir que usuários adicionais alterem as configurações de desenvolvedor dos aplicativos GitHub pertencentes à organização, um proprietário pode conceder a eles permissões de gerente do aplicativo GitHub. Os gerentes de aplicativos GitHub não podem gerenciar aplicativos de terceiros. Para saber como adicionar e remover gerentes de aplicativos GitHub em sua organização, confira "Gerentes de aplicativos GitHub".
Você pode definir a visibilidade do aplicativo para controlar quem pode instalá-lo. Você pode torná-lo público para que outros usuários ou organizações do GitHub possam instalar o aplicativo ou privado para que você só possa instalá-lo na conta que é proprietária do aplicativo. Para obter mais informações, confira "Tornar um aplicativo do GitHub público ou privado".
Quando usar os GitHub Apps
Ao criar uma integração, você deve considerar o uso de um GitHub App nos cenários a seguir em vez de um OAuth App, um personal access token ou um GitHub Actions.
Como usar um GitHub App em vez de um OAuth App
Em geral, GitHub Apps são mais indicados que OAuth Apps.
Para obter mais informações, confira "Diferenças entre Aplicativos do GitHub e Aplicativos OAuth".
Para obter informações sobre como migrar um OAuth App existente para um GitHub App, confira "Migrar aplicativos OAuth para aplicativos GitHub".
Os GitHub Apps oferecem segurança aprimorada
Os GitHub Apps fornecem mais controle sobre o que o aplicativo pode fazer. Em vez dos escopos amplos usados pelos OAuth Apps, os GitHub Apps usam permissões refinadas. Por exemplo, se o seu aplicativo precisar ler o conteúdo de um repositório, um OAuth App exigirá o escopo repo, o que também permitirá ao aplicativo editar o conteúdo e as configurações do repositório. Um GitHub App pode solicitar o acesso somente leitura ao conteúdo do repositório, o que não permitirá que o aplicativo execute ações mais privilegiadas, como editar o conteúdo ou as configurações do repositório.
Os GitHub Apps também oferecem mais controle sobre o acesso ao repositório. Com um GitHub App, o usuário ou o proprietário da organização que instalou o aplicativo pode decidir quais repositórios o aplicativo pode acessar. Por outro lado, um OAuth App pode acessar todos os repositórios que o usuário que autorizou o aplicativo pode acessar.
Os GitHub Apps usam tokens de curta duração. Se o token for vazado, ele será válido por um período menor, o que reduz os danos que podem ser causados. Por outro lado, os tokens do OAuth App só expiram quando a pessoa que autorizou o OAuth App revoga o token.
Esses recursos de segurança ajudam a fortalecer a segurança do seu GitHub App, limitando o dano que poderia ser causado se as credenciais do seu aplicativo vazassem. Além disso, isso permite que as organizações com políticas de segurança mais rigorosas usem seu aplicativo.
Os GitHub Apps podem agir de maneira independente de um usuário ou em nome dele
Os GitHub Apps podem agir de maneira independente de um usuário. Isso é útil para automações que não exigem a entrada de usuário.
Semelhante aos OAuth Apps, os GitHub Apps ainda podem executar ações em nome de um usuário. Ao contrário dos OAuth Apps, que não indicam que a ação foi executada pelo aplicativo, os GitHub Apps indicam que a ação foi executada pelo aplicativo em nome do usuário.
Os GitHub Apps não estão vinculados a uma conta de usuário e não consomem uma estação no GitHub Enterprise Server. Os GitHub Apps permanecem instalados mesmo quando a pessoa que inicialmente instalou o aplicativo deixa a organização. Isso permite que suas integrações continuem funcionando mesmo que as pessoas saiam da sua equipe.
Os GitHub Apps têm limites de taxa escalonáveis
O limite de taxa dos GitHub Apps que usam um token de acesso de instalação é escalado com o número de repositórios e o número de usuários da organização. Por outro lado, os OAuth Apps têm limites de taxa mais baixos e não são escalados. Para obter mais informações, confira "Limites de taxa para aplicativos GitHub".
Os GitHub Apps têm webhooks internos
Os GitHub Apps têm webhooks internos e centralizados. Os GitHub Apps podem receber eventos de webhook relativos a todos os repositórios e organizações que o aplicativo pode acessar. Por outro lado, os OAuth Apps precisam configurar webhooks individualmente para cada repositório e organização.
O acesso à API é um pouco diferente
Em geral, os GitHub Apps e os OAuth Apps podem fazer as mesmas solicitações de API. No entanto, há algumas diferenças:
- A API REST usada para gerenciar as execuções de verificação e os pacotes de verificação só está disponível para os GitHub Apps.
- Os recursos corporativos só estão disponíveis para os OAuth Apps.
- Algumas solicitações podem retornar dados incompletos dependendo das permissões e do acesso ao repositório que foi permitido a um GitHub App. Por exemplo, se o aplicativo fizer uma solicitação para obter todos os repositórios aos quais um usuário pode acessar, a resposta incluirá apenas os repositórios aos quais o aplicativo também recebeu acesso.
Para obter mais informações sobre os pontos de extremidade da API REST disponíveis para os GitHub Apps, confira "Pontos de extremidade disponíveis para aplicativos GitHub".
Como escolher entre um GitHub App ou um personal access token
Caso você deseje acessar os recursos do GitHub em nome de um usuário ou em uma organização, ou se você prevê uma integração de longa duração, recomendamos criar um GitHub App.
Use personal access tokens para testes de API ou scripts de curta duração. Como um personal access token está associado a um usuário, sua automação pode ser interrompida se o usuário não tiver mais acesso aos recursos de que você precisa. Um GitHub App instalado em uma organização não depende de um usuário. Além disso, ao contrário de um usuário, um GitHub App não consome um estação GitHub.
O GitHub dá suporte a dois tipos de personal access tokens, mas recomenda que você use fine-grained personal access tokens em vez de personal access tokens sempre que possível. Para obter mais informações sobre os personal access tokens, confira "Criando um token de acesso pessoal".
Como escolher entre um GitHub App ou um GitHub Actions
Os GitHub Apps e o GitHub Actions fornecem maneiras de criar ferramentas de automação e fluxo de trabalho.
O GitHub Actions fornece automação que pode executar trabalhos como integração contínua, tarefas de implantação e gerenciamento de projetos em um repositório. Eles são executados diretamente em computadores do executor hospedado no GitHub ou em executores auto-hospedados configurados pelo administrador. O GitHub Actions não é executado de maneira persistente. Eles são executados em resposta a eventos que ocorrem no repositório e só têm acesso aos recursos do repositório para os quais estão configurados. No entanto, eles podem ser compartilhados entre repositórios e organizações, permitindo que os desenvolvedores reutilizem e modifiquem as ações existentes de acordo com as necessidades. O GitHub Actions também é fornecido com um gerenciamento de segredos interno, que você pode usar para interagir com segurança com serviços de terceiros e gerenciar chaves de implantação com segurança.
Os GitHub Apps são executados de maneira persistente em um servidor ou em uma infraestrutura de computação fornecida por você, e eles reagem a eventos de webhook, bem como eventos de fora do ecossistema do GitHub. Elas são uma boa opção para operações que abrangem vários repositórios ou organizações ou para fornecer serviços hospedados a outras organizações. Um GitHub App é a melhor opção ao criar uma ferramenta com funções que ocorrem principalmente fora do GitHub ou que exigem mais tempo do que uma ação alocada para execução.
Para obter mais informações sobre como comparar o GitHub Actions com o GitHub Apps, confira "Sobre ações personalizadas".
É possível usar um GitHub App para autenticar em um fluxo de trabalho GitHub Actions se o GITHUB_TOKEN integrado não tiver permissões suficientes. Para obter mais informações, confira "Fazer solicitações de API autenticadas com um Aplicativo do GitHub em um fluxo de trabalho do GitHub Actions".
Noções básicas sobre o tipo de GitHub App a ser criado
Há várias maneiras de criar um GitHub App que será interessante considerar, de acordo com a funcionalidade que você deseja que o aplicativo tenha.
GitHub Apps que agem em nome de um usuário
Se você quiser que o seu aplicativo execute ações em nome de um usuário, use um token de acesso de usuário para autenticação. Esse tipo de solicitação às vezes é chamado de "usuário para servidor", e isso significa que o aplicativo será limitado pelas permissões que foram dadas ao aplicativo, bem como pela permissão do usuário. Com esse padrão, o usuário precisa autorizar o aplicativo para que o aplicativo possa executar uma ação. Para obter mais informações, confira "Autenticação com um aplicativo GitHub em nome de um usuário".
Alguns exemplos de automações que você pode criar com um GitHub App, em que o aplicativo age em nome de um usuário, incluem:
- Um GitHub App que usa o GitHub como um provedor de identidade para seu ecossistema
- Um GitHub App que adiciona um serviço com base no GitHub.com que pode ser útil para um usuário do GitHub. Você pode compartilhar o aplicativo com outros desenvolvedores por meio do GitHub Marketplace ou tornando o aplicativo público
GitHub Apps que agem no próprio nome
Se você quiser que o seu aplicativo execute ações em nome de si mesmo, em vez de um usuário, use um token de acesso de instalação para autenticação. Esse tipo de solicitação às vezes é chamado de "servidor para servidor", e isso significa que o aplicativo será limitado pelas permissões que foram dadas ao aplicativo. Para obter mais informações, confira "Como autenticar como uma instalação de Aplicativo GitHub".
Alguns exemplos de automações que você pode criar com um GitHub App, em que o aplicativo age no próprio nome, incluem:
- Um GitHub App que usa webhooks para reagir a um evento considerando determinado conjunto de critérios. Por exemplo, você pode criar uma automação que usa os pontos de extremidade da API REST para rótulos a fim de adicionar um rótulo a cada problema criado em um repositório, considerando determinado conjunto de critérios
- Um GitHub App que ajuda os colaboradores do repositório. Por exemplo, o aplicativo pode postar recursos úteis depois que um contribuidor cria uma solicitação de pull ou faz um comentário
- Um GitHub App que gera tokens de curta duração para fornecê-los a outras ferramentas de CI/CD ou para extrair informações de um repositório