O que são Aplicativos do GitHub?
Aqui, vamos discutir o que são os Aplicativos do GitHub, como eles funcionam e como podem ser usados para aprimorar os 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. Ele é exposto por meio de pontos de extremidade REST, portanto, é fácil integrá-lo 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, vamos apresentar os Aplicativos do GitHub e os Aplicativos do OAuth, as diferenças de uso e permissão deles, além das assinaturas de evento.
Quando um fluxo de trabalho do GitHub é personalizado, há vários recursos disponíveis, como escrever scripts personalizados, criar e autorizar seus Aplicativos OAuth ou instalar os Aplicativos do GitHub disponíveis no GitHub Marketplace. Em geral, os scripts podem ser melhor usados para essas tarefas pontuais. Para ações que precisam ser executadas com mais frequência, você pode usar a automação de aplicativos OAuth e GitHub para que você e sua equipe economizem tempo e mantenham o nível ideal de segurança nos 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ê terá uma boa compreensão sobre as diferenças entre os Aplicativos do GitHub e do OAuth e saberá a melhor forma de escolher 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 nas 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 age em nome do usuário, é importante observar que ele consumirá uma estação licenciada 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 divulgará o tipo de acesso à organização ou ao repositório que é 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 salientar que a autorização se limita aos recursos que são acessíveis para o usuário. No entanto, o Aplicativo do 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. Ao contrário dos Aplicativos do OAuth, um benefício dos Aplicativos do GitHub é que estes não consomem uma estação licenciada do GitHub.
Os Aplicativos do GitHub acessam dados em nome do próprio aplicativo por meio de uma chave privada que é usada para assinar um token JWT (Token Web JSON). Como eles são instalados em repositórios específicos, os usuários podem escolher quais repositórios o aplicativo pode acessar, o que limita o volume 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. Isso permite que você dê permissões mais granulares, limitando o aplicativo a ler e gravar somente nos repositórios que ele tem permissão para acessar. 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 procurar aplicativos GitHub, tenha em mente que alguns deles têm uma notificação de verificação. Essa notificação mostra que o aplicativo pertence a uma organização que verificou a propriedade do domínio, confirmou os endereços de email com suporte do GitHub e requer autenticação de dois fatores para sua organização.
- 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 GitHub sejam ideias para fazer a integração ao fluxo de trabalho em algumas situações, nas organizações maiores pode ser difícil fazer a transição do uso tradicional de 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 na hora de escolher usar essas ferramentas.
Observação
Como administrador do sistema, você deve trabalhar com os desenvolvedores para encontrar as opções mais adequadas para a automação por meio do uso desses aplicativos sem deixar de seguir a política de segurança da empresa.
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?
- Quais serão as necessidades de 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 GitHub têm permissões direcionadas que permitem solicitar acesso apenas para o 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 algum proprietário da organização concedeu. | 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 é o mesmo fluxo 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.
A decisão de usar um aplicativo GitHub ou OAuth depende do nível de acesso que você quer que o aplicativo tenha. 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 e as políticas da organização, além de detalhar a resposta que será dada quando uma vulnerabilidade for 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ê também pode esperar os eventos que ocorrem de outras fontes ou executar ações que atualizam 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, ele é acionado 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 assinará o webhook do repositório e retransmitirá os dados de entrada para um serviço de cliente em execução protegido por um 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.