O que são Aplicativos do GitHub?
Aqui, discutimos o que são os Aplicativos GitHub, como eles funcionam e como você pode usá-los para melhorar seus fluxos de trabalho. Independentemente se você estiver adotando uma solução criada por outra pessoa ou desenvolvendo uma para atender às suas necessidades exatas, sempre haverá espaço para aprimorar seus processos.
Estender a plataforma por meio da API do GitHub
O GitHub fornece uma API robusta que permite aos desenvolvedores fazer praticamente de tudo na plataforma. A API é exposta por meio de pontos de extremidade REST, o que facilita a integração a partir de qualquer plataforma ou linguagem de programação. No entanto, o acesso à API não tem suporte próprio. Os desenvolvedores que desejam compartilhar os respectivos recursos com outras pessoas ainda precisam empacotá-los como um aplicativo e publicá-lo para uso compartilhado.
Há vários fatores a serem considerados ao escolher entre incorporar um aplicativo OAuth ou aplicativo GitHub ao fluxo de trabalho. Nesta seção, apresentamos GitHub Apps e OAuth Apps, suas diferenças em termos de uso e permissões, e as assinaturas de eventos.
Ao personalizar um fluxo de trabalho do GitHub, você tem vários recursos disponíveis. Por exemplo, escrever scripts personalizados, criar e autorizar seus próprios Aplicativos OAuth ou instalar aplicativos GitHub disponíveis no marketplace do GitHub. Em geral, os scripts podem ser melhor usados para essas tarefas pontuais. Para ações executadas com mais frequência, a automação dos Aplicativos OAuth e GitHub pode ajudar você e sua equipe a economizar tempo, mantendo o nível ideal de segurança em seus fluxos de trabalho. Há várias diferenças que afetam como você decide se vai usar um Aplicativo do GitHub ou um Aplicativo OAuth. Se você entender essas diferenças com antecedência, isso poderá reduzir as dores de cabeça e o retrabalho e ainda ajudar a encontrar o melhor aplicativo para o caso de uso específico do seu fluxo de trabalho.
No final desta seção, você deve ter uma boa compreensão das diferenças entre um Aplicativo GitHub e um Aplicativo OAuth e saber como escolher melhor um aplicativo para a situação certa.
Como permitir o acesso e conceder permissões
Uma das considerações mais importantes para permitir que um aplicativo acesse um repositório GitHub é quais são as permissões necessárias para operar. Alguns aplicativos são fáceis de confiar, mas outros podem ser suspeitos. Sempre se certifique de que você esteja familiarizado com as permissões concedidas a um aplicativo.
Observação
Cada aplicativo usa uma chave de API exclusiva para solicitar dados no seu repositório. Quando você autoriza o acesso, está autorizando a chave. Você pode revogar o acesso à chave de um aplicativo a qualquer momento das configurações do repositório.
Aplicativos OAuth
Os aplicativos OAuth oferecem uma forma de acessar dados do GitHub em nome de um usuário. Como ele está agindo em nome do usuário, é importante observar que ele consome uma licença do GitHub. Você poderá criar e registrar um Aplicativo do OAuth em sua conta pessoal ou no nível da organização se tiver acesso administrativo. Um aplicativo OAuth que se integra ao GitHub divulga o tipo de acesso à organização ou ao repositório necessário. Os usuários autorizam aplicativos OAuth, o que oferece ao aplicativo a capacidade de atuar como o usuário autenticado, para ler ou modificar dados, por exemplo. Essa abordagem é basicamente uma forma automatizada de ler, gravar ou editar dados do GitHub como um usuário. Também é importante observar que a autorização é limitada aos recursos acessíveis ao usuário. No entanto, o Aplicativo OAuth também obtém acesso a todos os recursos que estão disponíveis para o usuário.
Observação
O nível de acesso é limitado pelo escopo do token (usuário, organização ou repositório).
Para organizações com restrições de acesso de aplicativo OAuth, o administrador pode conceder aprovação para usar o aplicativo. Com as assinaturas de evento, os aplicativos OAuth respondem à atividade conforme ela acontece.
Aplicativos GitHub
Por outro lado, os Aplicativos do GitHub são instalados em sua conta pessoal, nas organizações que você tem ou nos repositórios específicos que você acessa como administrador. Os Aplicativos do GitHub são instalados e interagem com o GitHub como um serviço, não como um usuário individual, como é o caso dos Aplicativos do OAuth. Um benefício dos Aplicativos do GitHub é que, ao contrário dos aplicativos OAuth, os Aplicativos GitHub não consomem uma licença do GitHub.
Os Aplicativos do GitHub acessam dados em nome do próprio aplicativo por meio de uma chave privada usada para assinar um Token Web JSON. Como eles estão instalados em repositórios específicos, os usuários podem escolher quais repositórios o aplicativo pode acessar, o que limita a quantidade de dados que o aplicativo pode acessar. As permissões definem quais recursos o aplicativo GitHub pode acessar por meio da API. Ao contrário dos Aplicativos OAuth, os Aplicativos do GitHub têm permissões personalizáveis para dados de repositório, problemas e solicitações de pull. A personalização permite que você conceda permissões mais granulares, limitando o aplicativo a ler e gravar somente nos repositórios que você permite que ele acesse. Somente os proprietários da organização podem gerenciar a configuração dos aplicativos GitHub em uma organização.
Encontre e instale Aplicativos do GitHub no GitHub Marketplace. Ao pesquisar aplicativos github, tenha em mente que alguns Aplicativos têm um selo verificado. Um selo verificado indica o seguinte sobre o aplicativo e a organização que o possui:
- A organização tem a propriedade de seu próprio domínio verificada.
- O Suporte do GitHub confirma os endereços de email da organização.
- A organização requer autenticação de dois fatores.
- Um administrador pode conceder permissões relacionadas a administração do repositório, verificações, conteúdo do repositório, implantações e problemas (as alterações do administrador exigem a aceitação do usuário)
- Um administrador pode conceder as permissões de usuário do aplicativo para bloquear outro usuário, emails, seguidores, chaves GPG, chaves SSH do git e as capacidades de observar e assistir (as alterações do administrador exigem a aceitação do usuário)
- Assinaturas de evento: avisos de segurança, conjunto de verificações, criação, implantação, bifurcação, rótulo, membro, check-in, commit de comentário, exclusão, status da implantação, marco, associação, organização (o administrador configura isso na interface do usuário dos aplicativos GH e pode ser alterado)
Escolher entre aplicativos GitHub e OAuth
Embora os Aplicativos do GitHub sejam uma maneira ideal de se integrar ao fluxo de trabalho em algumas situações, organizações maiores podem achar desafiador fazer a transição do uso tradicional dos Aplicativos OAuth para automação. Por exemplo, uma restrição de política de segurança também pode limitar as opções de um administrador ao optar por usar essas ferramentas.
Observação
Como administrador do sistema, você deve trabalhar com seus desenvolvedores para encontrar opções que são as mais adequadas para automação usando esses aplicativos enquanto ainda segue sua política de segurança.
Para determinar qual aplicativo é a solução certa para sua situação, veja algumas perguntas importantes a serem consideradas:
- Quero que o aplicativo atue como um usuário?
- Qual deve ser o limite de taxa?
- Qual acesso eu quero que o aplicativo tenha na organização e nos repositórios?
- Este aplicativo está em conformidade com nossa política de segurança?
Veja algumas das principais características e diferenças a serem consideradas ao escolher entre um aplicativo GitHub ou OAuth.
| Aplicativos GitHub | Aplicativos OAuth |
|---|---|
| A instalação de um aplicativo GitHub permite ao aplicativo acesso a repositórios escolhidos de uma conta de usuário ou da organização. | A autorização de um Aplicativo do OAuth permite ao aplicativo acessar os recursos acessíveis do usuário. Por exemplo, os repositórios que eles podem acessar. |
| Os tokens de acesso de instalação são limitados aos repositórios especificados com as permissões escolhidas pelo criador do aplicativo. | Um token de acesso OAuth é limitado por meio de escopos. |
| Um token de instalação identifica o aplicativo como o bot de aplicativos GitHub. | Um token de acesso identifica o aplicativo como o usuário que concedeu o token ao aplicativo. |
| Os Aplicativos do GitHub usam permissões direcionadas que permitem que eles solicitem acesso somente ao que precisam. | Os aplicativos OAuth não podem usar permissões granulares. |
| Os aplicativos GitHub não estão sujeitos às políticas de aplicativo da organização. Um aplicativo GitHub só tem acesso aos repositórios que um proprietário da organização concede. | Se uma política de aplicativo da organização estiver ativa, somente um proprietário da organização poderá autorizar a instalação de um aplicativo OAuth. Se instalado, o aplicativo OAuth obterá acesso a qualquer coisa visível para o token que o proprietário da organização tem dentro da organização aprovada. |
| Os aumentos de limite de taxa podem ser concedidos no nível dos aplicativos GitHub (afetando todas as instalações) e no nível da instalação individual. | Os aumentos de limite de taxa são concedidos para cada aplicativo OAuth. Cada token concedido a esse aplicativo OAuth obtém o aumento do limite. |
| Os aplicativos GitHub podem ser autenticados em nome do usuário, o que é chamado de solicitações de usuário para servidor. O fluxo de autorização é igual ao do aplicativo OAuth. Os tokens de usuário para servidor podem expirar e serem renovados com um token de atualização. | O fluxo OAuth usado por aplicativos OAuth autoriza um aplicativo OAuth em nome do usuário. Esse fluxo é o mesmo usado na autorização de usuário para servidor do Aplicativo GitHub. |
| Os aplicativos GitHub solicitam a permissão de conteúdo do repositório e usam seu token de instalação para fazer a autenticação por meio do Git baseado em HTTP. | Os aplicativos OAuth solicitam o escopo da write:public_key e criam uma chave de implantação por meio da API. Depois, você pode usar essa chave para executar comandos do Git. |
Acesso e permissões do aplicativo
Uma das considerações mais importantes para permitir que um aplicativo acesse um repositório GitHub é quais são as permissões necessárias para operar. Alguns aplicativos são fáceis de confiar, mas outros podem ser suspeitos. Sempre se certifique de que você esteja familiarizado com as permissões concedidas a um aplicativo.
Tomar a decisão de usar um aplicativo GitHub ou um aplicativo OAuth pode depender do nível de acesso que você deseja que o aplicativo acesse. Em geral, você deve incentivar a equipe a usar a ferramenta com o menor escopo possível para realizar a tarefa. Um aplicativo OAuth tem acesso a todos os recursos de um usuário ou de um proprietário da organização.
- Os aplicativos OAuth podem ter acesso de leitura ou gravação aos seus dados do GitHub
- Você pode conceder a um Aplicativo do GitHub o acesso a uma conta sem receber acesso a outra
Segurança de aplicativos
Quando você encontra uma vulnerabilidade no aplicativo, ela deve ser prioridade e estar dentro da política de segurança para ser informada aos usuários do projeto. A comunicação rápida de um problema de segurança pode significar a diferença entre os usuários conseguirem revogar um token comprometido ou arcarem com a exposição de dados confidenciais. Embora os tokens sejam muito mais seguros do que as senhas, a segurança ainda pode ser comprometida, e é importante que a organização esteja preparada.
Além de um arquivo README.md, é recomendável adicionar um arquivo SECURITY.md aos seus repositórios. O arquivo SECURITY.md realça as informações relacionadas à segurança do repositório. O arquivo deve incluir os contatos de segurança, as políticas de sua organização e detalhar a resposta que você planeja executar quando uma vulnerabilidade é descoberta.
Reação a eventos
Os Aplicativos do GitHub são projetados para serem passivos. Eles esperam que algo aconteça e depois reagem, normalmente por meio da API do GitHub. Ao aguardar a ocorrência de eventos no GitHub, há duas abordagens: webhooks e sondagem.
Observação
Os Aplicativos do GitHub não são limitados a trabalhar com os dados do GitHub. Você pode aguardar facilmente os eventos que ocorrem de outras fontes ou executar ações que atualizem outros serviços.
Usando os webhooks do GitHub
Os webhooks são a abordagem preferencial para manipulação de eventos. Quando algo acontece no GitHub dentro do escopo de um webhook, um evento é gerado imediatamente. Os webhooks enviam notificações por push que seu aplicativo pode escutar e processar em tempo real. Você pode configurar webhooks nas configurações do repositório, incluindo os tipos de eventos, autenticação e como as notificações HTTP são entregues.
Sondagem
Às vezes, os webhooks não são uma opção. Seu aplicativo pode precisar funcionar com a proteção de um firewall corporativo, em que o GitHub não pode acessá-lo diretamente. Nesse caso, uma alternativa é sondar os dados que você está acompanhando usando a API do GitHub.
Retransmissão de webhook
Uma alternativa à sondagem de aplicativos protegidos por um firewall é usar um serviço de encaminhamento de webhook, como smee.io. Com essa abordagem, o serviço público assina o webhook do repositório e, em seguida, retransmite os dados de entrada para um serviço cliente em execução atrás do firewall. Em seguida, esse serviço de cliente envia por push as notificações para o aplicativo em execução como se elas fossem provenientes da fonte original.