O que são as Aplicações GitHub?
Aqui, discutimos o que são aplicativos GitHub, como eles funcionam e como você pode usá-los para melhorar seus fluxos de trabalho. Quer esteja a adotar uma solução construída por outra pessoa ou a desenvolver uma para satisfazer as suas necessidades exatas, há sempre espaço para melhorar os seus processos.
Estenda a plataforma por meio da API do GitHub
O GitHub fornece uma API robusta que permite que os desenvolvedores façam praticamente qualquer coisa na plataforma. A API é exposta através de terminais REST, pelo que é fácil de integrar a partir de qualquer plataforma ou linguagem de programação. No entanto, o acesso à API não se sustenta por si só. Os desenvolvedores que desejam compartilhar seus recursos com outras pessoas ainda precisam empacotá-los como um aplicativo e publicá-los antes que alguém possa usá-los.
Há vários fatores a considerar ao escolher entre incorporar um aplicativo OAuth ou um aplicativo GitHub em seu fluxo de trabalho. Nesta seção, apresentamos os aplicativos GitHub e os aplicativos OAuth, suas diferenças de uso e permissão e 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 mercado GitHub. Em geral, você pode usar melhor scripts para essas tarefas únicas. Para ações que são 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á muitas diferenças que afetam a forma como você decide entre usar um aplicativo GitHub ou um aplicativo OAuth. Entender essas diferenças de antemão pode reduzir algumas dores de cabeça e retrabalho no futuro, além de ajudá-lo a encontrar o melhor aplicativo para seu caso de uso específico dentro 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.
Conceder acesso e permissões
Uma das considerações mais importantes para permitir que uma aplicação aceda a um repositório GitHub são as permissões de que necessita para funcionar. Algumas aplicações são fáceis de confiar, mas outras podem ser suspeitas. Certifique-se sempre de que está confortável com as permissões que concede a uma aplicação.
Nota
Cada aplicação utiliza uma chave de API única para efetuar pedidos para os dados no seu repositório. Ao autorizar o acesso, está a autorizar a chave. Você pode revogar o acesso à chave de um aplicativo a qualquer momento nas configurações do repositório.
Aplicações OAuth
Os aplicativos OAuth fornecem uma maneira 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ê pode criar e registrar um aplicativo 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 repositório que ele exige. Os usuários autorizam o OAuth Apps, o que dá ao aplicativo a capacidade de agir como o usuário autenticado, como ler ou modificar dados. Essa abordagem é essencialmente uma maneira automatizada de ler, gravar ou editar dados do GitHub como usuário. Também é importante notar que a autorização é limitada aos recursos acessíveis ao usuário. No entanto, o aplicativo OAuth também tem acesso a todos os recursos que estão disponíveis para o usuário.
Nota
O nível de acesso é limitado pelo escopo do token (usuário, organização, repositório).
Para organizações com restrições de acesso ao aplicativo OAuth, o administrador pode conceder aprovação para usar o aplicativo. Com as subscrições de eventos, as Aplicações OAuth respondem à atividade à medida que esta acontece.
Aplicativos GitHub
Por outro lado, os aplicativos GitHub são instalados em sua conta pessoal, organizações que você possui ou repositórios específicos nos quais você tem acesso de administrador. Os aplicativos GitHub são instalados e interagem com o GitHub como um serviço, não com um usuário individual como com os aplicativos OAuth. Um benefício dos aplicativos GitHub é que, ao contrário dos aplicativos OAuth, os aplicativos GitHub não consomem uma licença do GitHub.
Os aplicativos GitHub acessam dados em nome do próprio aplicativo por meio de uma chave privada usada para assinar um 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 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 GitHub têm permissões personalizáveis para dados de repositório, problemas e solicitações pull. A personalização permite que você conceda permissões mais granulares, limitando o aplicativo a ler e gravar apenas 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.
Você pode encontrar e instalar aplicativos GitHub a partir do GitHub Marketplace. Ao pesquisar por Aplicativos GitHub, lembre-se de 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 propriedade do domínio da organização é verificada.
- O Suporte do GitHub confirma os endereços de e-mail da organização.
- A organização requer autenticação de dois fatores.
- Um administrador pode conceder permissões em relação à administração do repositório, verificações, conteúdo do repositório, implantações e problemas (As alterações do administrador exigem aceitação do usuário)
- Um administrador pode conceder ao utilizador da aplicação permissões para bloquear outro utilizador, e-mails, seguidores, chaves GPG, chaves SSH do Git, marcar como favorito e seguir (As alterações do administrador exigem aceitação do utilizador)
- Assinaturas de eventos: Aviso de segurança, Check suite, Criar, Implantação, Bifurcação, Rótulo, Membro, Check-in, Confirmar comentário, Excluir, Status da implantação, Marco, Associação, Organização (o administrador configura na interface do usuário do GH Apps e pode ser alterado)
Escolha entre aplicativos GitHub e aplicativos OAuth
Embora os aplicativos GitHub sejam uma maneira ideal de integração ao seu fluxo de trabalho em algumas situações, organizações maiores podem achar 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 ao optar por usar essas ferramentas.
Nota
Como administrador do sistema, você deve trabalhar com seus desenvolvedores para encontrar as opções 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, aqui estão algumas perguntas importantes a serem consideradas:
- Quero que a aplicação atue como utilizador?
- Qual deve ser o limite da taxa?
- Que acesso quero que a aplicação tenha na organização e nos repositórios?
- Esta aplicação está em conformidade com a nossa política de segurança?
Aqui estão algumas características-chave e diferenças a serem consideradas ao escolher entre um aplicativo GitHub ou um aplicativo OAuth.
| Aplicativos GitHub | Aplicações OAuth |
|---|---|
| A instalação de um aplicativo GitHub concede ao aplicativo acesso aos repositórios escolhidos por uma conta de usuário ou organização. | Autorizar um aplicativo OAuth concede ao aplicativo acesso aos recursos acessíveis do usuário; por exemplo, repositórios que eles podem acessar. |
| Os tokens de acesso à instalação são limitados a 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 GitHub Apps. | Um token de acesso identifica o aplicativo como o usuário que concedeu o token ao aplicativo. |
| Os aplicativos GitHub usam permissões direcionadas que permitem que eles solicitem acesso apenas 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 aplicativos da organização. Um aplicativo GitHub só tem acesso aos repositórios concedidos por um proprietário da organização. | Se uma política de aplicativo da organização estiver ativa, somente o proprietário de uma organização poderá autorizar a instalação de um aplicativo OAuth. Se instalado, o aplicativo OAuth ganha 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 tanto no nível dos aplicativos GitHub (afetando todas as instalações) quanto no nível de instalação individual. | Os aumentos do limite de taxa são concedidos por aplicativo OAuth. Cada token concedido a esse aplicativo OAuth recebe o limite aumentado. |
| Os aplicativos GitHub podem se autenticar em nome do usuário, o que é chamado de solicitações de usuário para servidor. O fluxo para autorizar é o mesmo que o fluxo de autorização do aplicativo OAuth. Os tokens de usuário para servidor podem expirar e ser renovados com um token de atualização. | O fluxo OAuth usado pelos 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 pedem permissão de conteúdo do repositório e usam seu token de instalação para autenticar via Git baseado em HTTP. | Os aplicativos OAuth pedem write:public_key escopo e criam uma chave de implantação por meio da API. Em seguida, você pode usar essa chave para executar comandos Git. |
Acesso e permissões de aplicativos
Uma das considerações mais importantes para permitir que uma aplicação aceda a um repositório GitHub são as permissões de que necessita para funcionar. Algumas aplicações são fáceis de confiar, mas outras podem ser suspeitas. Certifique-se sempre de que está confortável com as permissões que concede a uma aplicação.
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 sua equipe a usar a ferramenta com o menor escopo para realizar a tarefa. Um aplicativo OAuth tem acesso a todos os recursos de um usuário ou 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 GitHub acesso a uma conta sem ter acesso a outra
Segurança de aplicações
Quando você encontrar uma vulnerabilidade em seu aplicativo, deve ser uma prioridade e dentro de sua política de segurança informar os usuários do seu projeto. Comunicar rapidamente um problema de segurança pode significar a diferença entre os usuários serem capazes de revogar um token comprometido ou terem dados confidenciais expostos. Embora os tokens sejam muito mais seguros do que as senhas, a segurança ainda pode ser comprometida e é importante que sua organização esteja preparada.
Além de um arquivo README.md, recomendamos adicionar um arquivo SECURITY.md aos seus repositórios. O arquivo SECURITY.md destaca informações relacionadas à segurança do repositório. O ficheiro deve incluir os contactos de segurança, as políticas da sua organização e detalhar a resposta que planeia dar quando for descoberta uma vulnerabilidade.
Reagir aos eventos
As Aplicações GitHub são concebidas para serem passivas. Eles esperam que algo aconteça e, em seguida, reagem, geralmente por meio da API do GitHub. Ao aguardarem que os eventos aconteçam no GitHub, existem duas abordagens: webhooks e consultas.
Nota
As Aplicações GitHub não se limitam a trabalhar com dados do GitHub. Você pode facilmente aguardar eventos que acontecem de outras fontes ou executar ações que atualizam outros serviços.
Utilizar webhooks do GitHub
Os webhooks são a abordagem preferida para o tratamento de eventos. Quando algo acontece no GitHub dentro do escopo de um webhook, um evento é gerado imediatamente. Webhooks notificações push que seu aplicativo pode ouvir e processar em tempo real. Pode configurar webhooks nas definições do repositório, incluindo os tipos de eventos, a autenticação e a forma como as notificações HTTP são entregues.
Consultas
Às vezes, os webhooks não são uma opção. Seu aplicativo pode precisar viver atrás de um firewall corporativo onde o GitHub não pode acessá-lo diretamente. Nesse caso, uma alternativa consiste na consulta dos dados que está a seguir através da API do GitHub.
Reencaminhamento de webhooks
Uma alternativa ao polling para aplicações por trás de 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 recebidos para um serviço cliente executado atrás do firewall. Esse serviço cliente envia as notificações para a sua aplicação em execução como se fossem provenientes da fonte original.