Sobre o GitHub Apps
Um GitHub App é um tipo de integração que você pode criar para interagir e estender a funcionalidade de GitHub. Você pode criar um GitHub App para fornecer flexibilidade e reduzir o atrito em seus processos, sem a necessidade de entrar em um usuário ou criar uma conta de serviço.
Casos de uso comuns para GitHub Apps incluem:
- Automação de tarefas ou de processos em segundo plano
- Compatibilidade com "Entrar com GitHub", que permite que os usuários façam login com a conta GitHub para informar sua identidade no seu ecossistema
- Como ferramenta de desenvolvedor, permitindo que os usuários trabalhem com GitHub ao fazer login na sua GitHub App, que então pode agir em nome deles
- Integrando sua ferramenta ou serviço externo com GitHub
Assim como OAuth apps, GitHub Apps usam o OAuth 2.0 e podem atuar em nome de um usuário. Ao contrário OAuth apps, GitHub Apps também pode agir independentemente de um usuário.
GitHub Apps pode ser instalado diretamente em empresas, organizações e contas pessoais e concedido acesso a repositórios específicos. Eles vêm com webhooks integrados e permissões específicas e restritas.
Você também pode criar um GitHub App de propriedade da empresa que só pode ser instalado na própria empresa ou em organizações da sua empresa e que só pode ser autorizado por membros da sua empresa. Para saber mais, confira Criando aplicativos GitHub para sua empresa.
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.
Criando um GitHub App
Para criar um GitHub App, primeiro você precisa registrar um GitHub App. Para saber mais, confira Registrando um aplicativo GitHub.
Em seguida, você precisa escrever código para adicionar funcionalidade à sua GitHub App. Você pode usar as credenciais de seu GitHub App registro para fazer solicitações autenticadas para GitHubAPIs. Para obter mais informações sobre como escrever código para o seu GitHub App, consulte 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 seu GitHub Appaplicativo, seu 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 Serviço de Aplicativo do Azure. Se o aplicativo for um aplicativo do lado do cliente, ele poderá ser executado no dispositivo do usuário.
Para usar seu GitHub App, você precisa instalá-lo na sua empresa, organização ou conta pessoal.
- Se o seu GitHub App for privado, você só poderá instalá-lo na conta proprietária do aplicativo.
- Se o seu GitHub App for público, outras contas também poderão instalá-lo.
- Se o seu GitHub App pertence a uma empresa, você pode instalá-lo na própria empresa ou em qualquer organização dessa empresa. Somente os membros da empresa podem entrar nele.
Para saber mais, confira Instalando seu próprio aplicativo GitHub e Compartilhando seu Aplicativo GitHub.
Entendendo que tipo de GitHub App criar
Há várias maneiras de criar um GitHub App que você desejará considerar, com base na funcionalidade que você deseja que o aplicativo tenha.
GitHub Apps que atuam 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 atua em nome de um usuário, incluem:
- Um GitHub App que usa GitHub como um provedor de identidade para seu ecossistema.
- Um GitHub App que adiciona um serviço sobre GitHub e que pode ser útil para um usuário de GitHub. Você pode compartilhar o aplicativo com outros desenvolvedores por meio GitHub Marketplace ou tornando o aplicativo público.
GitHub Apps que atuam 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 atua em seu próprio nome, incluem:
- Um GitHub App que usa webhooks para reagir a um evento com base em um determinado conjunto de critérios. Por exemplo, você pode criar uma automação para os endpoints da API REST de análise de solicitações de fine-grained personal access token que aprova uma solicitação de acordo com 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.
- Um GitHub App que gera tokens de curta duração para fornecer a outras ferramentas de CI/CD ou para extrair informações de um repositório.
GitHub Apps que respondem a webhooks
Se você quiser que seu aplicativo responda a eventos em GitHub, ele deverá se inscrever em 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 aplicativos instalados em empresas atualmente não dão suporte a webhooks e devem ser instalados em uma organização para recebê-los.
GitHub Apps que podem tomar determinadas ações
Ao configurar seu 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 GitHub API, 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.