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 GitHub", que permite aos usuários entrarem com a conta do GitHub para confirmar sua identidade no seu ecossistema
- Como ferramenta de desenvolvimento, permite que os usuários trabalhem com GitHub fazendo login no seu GitHub App, que então pode agir em nome deles.
- Integração da sua ferramenta ou de um serviço externo ao GitHub
Assim como os OAuth apps, os GitHub Apps usam o OAuth 2.0 e podem agir em nome de um usuário. Ao contrário dos OAuth apps, os GitHub Apps também podem agir independentemente de um usuário.
GitHub Apps podem ser instalados diretamente em organizações e contas pessoais e ter acesso concedido a repositórios específicos. Eles vêm com webhooks integrados e permissões específicas e restritas.
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 Funções em uma organização.
Compilar um GitHub App
Para compilar o GitHub App, primeiro você precisa registrar o GitHub App. Para saber mais, confira Registrando um aplicativo GitHub.
Em seguida, você precisa escrever o código para adicionar uma funcionalidade ao seu GitHub App. Você pode usar as credenciais do registro do GitHub App para fazer solicitações autenticadas para as APIs dos GitHub. Para obter mais informações sobre como escrever código para o GitHub App, confira Sobre como escrever código para um aplicativo GitHub. Para obter mais informações sobre fazer as solicitações autenticadas, confira Sobre a autenticação com um aplicativo GitHub.
Depois de escrever o código para o GitHub App, o aplicativo precisará ser executado em algum lugar. Se seu aplicativo for um site ou aplicativo Web, você poderá hospedar seu aplicativo em um servidor como Azure App Service. Se o aplicativo for um aplicativo do lado do cliente, ele poderá ser executado no dispositivo do usuário.
Para usar o GitHub App, você precisa instalá-lo em sua organização ou conta pessoal.
- Se o GitHub App for privado, ele só poderá ser instalado na conta que possui o aplicativo.
- Se o GitHub App for público, outras contas também poderão instalá-lo.
Para saber mais, confira Instalando seu próprio aplicativo GitHub e Compartilhando seu Aplicativo GitHub.
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 saber mais, 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 GitHub como provedor de identidade para seu ecossistema.
- Um GitHub App que adiciona um serviço ao GitHub 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 em seu 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 saber mais, 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ê poderia criar uma automação para os pontos de extremidade da API REST para revisar solicitações de fine-grained personal access token que aprova uma solicitação dada uma determinada política.
- 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.
- O 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.
Os GitHub Apps que respondem a webhooks
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 saber mais, confira Usando webhooks com aplicativos GitHub.
Os GitHub Apps que podem executar determinadas ações
Ao configurar o GitHub App, você pode selecionar permissões específicas 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. Para saber mais, confira Escolhendo permissões para um aplicativo GitHub.