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

A integração com o GitLab cobre os controles de desenvolvimento seguro: exigência de autenticação em duas etapas, proteção de branches e quem tem acesso de proprietário.

Ela funciona tanto com o GitLab em nuvem quanto com instalações próprias.

O que ela monitora

A conexão monitora a exigência de autenticação em duas etapas, as branches protegidas e o acesso de proprietários no seu grupo.

O que criar do lado do GitLab

Gere um token de acesso pessoal com o escopo de leitura da interface de programação, em uma conta que tenha papel de proprietário no grupo.

O papel de proprietário importa: as verificações de exigência de autenticação e de controle de acesso consultam configurações de grupo que só um proprietário alcança.

Existe também um caminho por autorização direta, Conectar com GitLab, disponível apenas para o GitLab em nuvem e dependente de configuração prévia. O método por token é o indicado como recomendado e é o que funciona em qualquer cenário, incluindo instalação própria.

Os campos, e o que realmente é opcional

A plataforma explica a lógica: grupo e projeto delimitam o escopo das verificações, e as verificações que precisam deles são ignoradas até que sejam informados.

Traduzindo o que isso significa na prática: sem o ID do grupo, as verificações de autenticação forte e de controle de acesso não rodam. A integração conecta, o teste passa, e o resultado que você queria não aparece.

Este é o erro mais comum desta integração. O ID do grupo é um número que aparece na página inicial do grupo no GitLab.

Quando informar o projeto

O ID do projeto é útil em dois casos:

Você quer delimitar a um repositório específico, tipicamente o que vai para produção, em vez de avaliar o grupo inteiro.

Verificações de nível de projeto, como proteção de branch, precisam saber em qual projeto olhar.

Se a sua empresa tem um repositório principal claramente identificável, informar o projeto melhora a precisão da evidência. Se são muitos repositórios equivalentes, o grupo é o recorte melhor.

Instalação própria

Se você usa GitLab instalado na sua infraestrutura, informe a URL base da sua instância. Sem isso, a plataforma tenta o serviço em nuvem e a autenticação falha.

Vale conferir também que a sua instância é alcançável pela internet. Uma instalação em rede fechada, sem exposição externa, não pode ser consultada, e nesse caso os controles precisam de evidência manual.

Boas práticas

Use uma conta de serviço com papel de proprietário no grupo, em vez do token pessoal de alguém. Assim a coleta não para quando uma pessoa sai.

Anote a validade do token. Tokens do GitLab têm prazo de expiração, e o vencimento é a principal causa de coleta interrompida.

Revogar é imediato. Apagar o token do lado do GitLab interrompe a coleta.

Depois de conectar

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

O diagnóstico aqui é direto: se o teste de conexão passa mas quase nada é verificado, falta o ID do grupo. Se as verificações de grupo rodam mas as de branch não, informe o ID do projeto. Se nada conecta em instalação própria, confira a URL base.

Problemas comuns

Erro ao conectar. Token incorreto ou sem o escopo de leitura da interface de programação.

Conectou e nada é verificado. ID do grupo em branco. É a causa mais frequente.

Verificações de autenticação forte não executam. Além do ID do grupo, confira se a conta do token é proprietária.

Proteção de branch não é verificada. Informe o ID do projeto.

Instalação própria não conecta. Falta a URL base, ou a instância não é alcançável de fora.

Funcionava e parou. Token expirado. Gere um novo e atualize apenas esse campo.