Integrações – Como adicionar uma integração com o GitHub

A integração com o GitHub cobre os controles de desenvolvimento seguro: quem tem acesso a quê, como o código é protegido antes de ir para produção, e o registro de atividades da organização.

Ela tem uma particularidade boa: existem dois caminhos de conexão, e um deles é claramente melhor.

O que ela monitora

A conexão sincroniza controles de acesso a repositórios e configurações de segurança: membros e permissões da organização, autenticação forte, proteção de branches, alertas de vulnerabilidade e registro de auditoria.

Prefira instalar o aplicativo

O caminho recomendado é usar Conectar com GitHub, que instala o aplicativo da plataforma na sua organização.

Duas vantagens decisivas sobre o token:

Não expira. Um token pessoal vence ou é revogado quando a pessoa que o criou sai da empresa, e a coleta para em silêncio. O aplicativo continua funcionando.

Não depende de uma pessoa. O acesso é da organização para a plataforma, e não da conta de alguém. Isso é melhor de auditar e melhor de manter.

Se por política interna a sua empresa não instala aplicativos de terceiros, existe o caminho alternativo com token, disponível como usar token pessoal em vez disso.

Se for pelo token: o que criar

Gere um token de acesso pessoal do tipo clássico, e faça isso a partir de uma conta proprietária da organização.

Os escopos necessários:

Sobre o segundo escopo: ele é necessário para alcançar repositórios privados. Se a sua organização tem apenas repositórios públicos, o escopo restrito a públicos é suficiente.

Por que o token precisa ser de um proprietário

Esta é a informação que mais economiza tempo nesta integração.

Ler proteção de branch e alertas de vulnerabilidade exige permissão de administração no repositório. Um token criado por um membro comum recebe recusa de acesso nesses pontos, e essas verificações ficam não executadas.

O sintoma é característico: a integração conecta, o teste passa, algumas verificações rodam, e justamente as mais importantes para conformidade não. Se você está vendo isso, a causa quase sempre é o nível da conta que gerou o token.

Os campos a preencher

O registro de auditoria depende do plano

A interface de programação do registro de auditoria da organização existe apenas no plano corporativo em nuvem do GitHub.

Fora dele, a verificação correspondente orienta a conferência manual em vez de reprovar. Você não é penalizado por não ter o plano, e pode comprovar esse ponto enviando uma exportação do histórico como evidência, quando ela estiver disponível para o seu plano.

Boas práticas

Se usar token, prefira uma conta de serviço com propriedade na organização, em vez do token pessoal de um administrador. Assim a saída de uma pessoa não interrompe a coleta.

Anote a validade do token. Tokens clássicos podem ter prazo. Renovar antes de vencer evita o intervalo silencioso sem evidência.

Revogar é imediato. Apagar o token, ou desinstalar o aplicativo, interrompe a coleta na hora.

Depois de conectar

Use Testar Conexão antes de salvar, aguarde o primeiro ciclo e confira os testes.

Se as verificações de proteção de branch e de vulnerabilidades não executarem, revise o nível da conta que gerou o token. Se as de repositórios privados não executarem, revise o escopo de acesso a repositórios.

Problemas comuns

Erro ao conectar pelo aplicativo. A instalação pode ter sido cancelada ou interrompida. Refaça o processo de instalação na organização.

Não autorizado. A conta usada não tem permissão suficiente na organização. Use uma conta proprietária.

Proteção de branch não é verificada. O token não tem permissão de administração nos repositórios. É o problema mais comum aqui.

Repositórios privados não aparecem. Falta o escopo de acesso a repositórios.

A verificação de registro de auditoria não executa. Ela depende do plano corporativo em nuvem. Comprove manualmente.

Funcionava e parou. Token expirado ou revogado, tipicamente porque a pessoa que o criou saiu. É o argumento para migrar para a instalação do aplicativo.