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
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.
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.
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 obter mais informações, confira "Registrar 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ódigos com o GitHub App, confira "Sobre 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 GitHub App".
Depois de escrever o código para o GitHub App, o aplicativo precisará ser executado em algum lugar. Se o 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, é necessário instalar o aplicativo na sua conta pessoal ou da organização. Se o GitHub App for privado, só será possível instalar o GitHub App na conta que possui o aplicativo. Se o GitHub App for público, outros usuários e organizações poderão instalar seu aplicativo. Para obter mais informações, 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 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.
- 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 obter mais informações, confira "Usar webhooks com aplicativos GitHub".
Os GitHub Apps que podem executar determinadas ações
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. Para obter mais informações, confira "Escolhendo permissões para um Aplicativo GitHub".