Skip to main content
O ZeroPath se conecta ao GitLab.com e ao GitLab Self-Managed com um token de acesso de projeto, de grupo ou pessoal (PAT). A configuração recomendada é o escopo api com acesso Maintainer aos projetos aprovados. O ZeroPath não exige uma credencial de administrador do GitLab.

​
Requisitos

  • Uma organização no ZeroPath e permissão para criar integrações e adicionar repositórios.
  • Um token de acesso válido do GitLab com o escopo api e pelo menos acesso Reporter a cada repositório que você pretende escanear. Defina uma validade que siga a política da sua organização e os limites do GitLab; o ZeroPath não exige validade de um ano.
  • Um hostname HTTPS do GitLab acessível a partir da sua implantação do ZeroPath. Para scans automáticos de MRs, o GitLab também precisa conseguir entregar webhooks ao ZeroPath.
  • Uma branch com pelo menos um commit antes de executar um scan. Repositórios vazios podem ser importados, mas precisam de código para serem escaneados.

​
Permissões

Os escopos do token e os papéis do GitLab são controles separados. O escopo api permite leituras e escritas na API dentro do acesso da credencial; ele não eleva o papel do token no projeto. Use api nesta integração, em vez de substituir esse escopo por escopos somente de leitura para escritas de webhooks ou status. Veja a documentação de escopos do GitLab. Os comentários exigem que os recursos de revisão correspondentes estejam habilitados no ZeroPath. O acesso Reporter não permite enviar branches de correção. Regras de branches protegidas e pipelines podem restringir ainda mais a publicação de status e a remediação. Confira as permissões em cada projeto, inclusive quando um token abrange vários projetos. Veja os papéis e permissões do GitLab.
Reporter é o mínimo para escanear repositórios. Para scans automáticos de MRs com um token Reporter, um Maintainer ou Owner do projeto precisa configurar o webhook, deve existir um pipeline para o commit escaneado e Check status posting deve estar desabilitado. Use Developer ou Maintainer quando precisar de status de commits no GitLab. Veja Pipelines de merge requests.

​
Webhooks de projeto e de grupo

Maintainer é suficiente para gerenciar webhooks de projeto. Os webhooks de grupo opcionais exigem o papel Owner no grupo e um plano elegível do GitLab. Os webhooks de projeto permitem manter a credencial da integração como Maintainer. Se a configuração no nível do grupo exibir um aviso de permissões, verifique a entrega dos webhooks de projeto em cada repositório importado antes de depender dos scans de MRs. Veja os requisitos de webhooks do GitLab.

​
Escolha um token e limite o acesso

Um Owner do grupo no GitLab do cliente cria o token de grupo; um Maintainer ou Owner do projeto cria o token de projeto. O próprio token pode receber um papel inferior. No GitLab.com, tokens de grupo e de projeto geralmente exigem Premium ou Ultimate. No Self-Managed, estão disponíveis com qualquer licença. Configurações da organização podem restringir a criação de tokens. Veja os guias de tokens de grupo e tokens de projeto. Para restringir a integração a um subconjunto de repositórios:
  • Use tokens de projeto ou coloque os projetos aprovados em um subgrupo dedicado e conceda acesso nesse subgrupo. Evite conceder à conta dedicada acesso amplo em um grupo pai.
  • Considere o acesso herdado. Tokens de grupo abrangem projetos descendentes e futuros no grupo; um PAT segue as associações da conta.
  • Selecione apenas os repositórios aprovados ao importar no ZeroPath e revise as configurações de importação automática, se habilitadas. A seleção e o caminho de grupo/projeto informado no ZeroPath não reduzem as permissões de uma credencial mais ampla no GitLab.
Em instâncias do GitLab que usam visibilidade Internal, tokens de grupo e de projeto criados por um usuário interno podem acessar outros projetos Internal. Revise a visibilidade dos projetos e as associações do token quando for necessário impor um limite estrito de acesso. O GitLab documenta esse comportamento nos guias de tokens de grupo e tokens de projeto.

​
Conecte o GitLab

1

Crie a credencial

Para um token de grupo ou de projeto, abra Settings → Access tokens no recurso do GitLab. Para um PAT de uma conta dedicada, use as configurações de token pessoal dessa conta. Defina um nome, validade, escopo api e o papel necessário para seu fluxo. Insira a credencial diretamente no ZeroPath ou use um canal seguro aprovado se outra equipe fizer a configuração.
2

Abra a configuração do GitLab

Na sua implantação do ZeroPath, acesse Add Repositories → GitLab → Setup GitLab Integration. Para a implantação padrão em nuvem, abra Add Repositories.
3

Escolha o tipo de token e informe os dados da conexão

Selecione Group, Project ou Personal Access Token e cole o token.
  • GitLab Domain: gitlab.com ou o hostname da sua instância, como gitlab.example.com. Uma porta HTTPS configurada pode ser incluída. Não inclua caminhos de repositório aqui.
  • Group Name: para conexões Group, o caminho completo do grupo ou subgrupo, como engineering/approved, em vez do nome de exibição.
  • Project Path: para conexões Project, o caminho completo do projeto, como engineering/approved/service.
Conexões Personal Access Token não exigem um caminho de grupo ou de projeto.
4

Adicione os repositórios

Selecione os projetos aprovados em Accessible repositories e adicione-os. Se o ZeroPath informar que a configuração do webhook não pôde ser concluída, siga a Configuração manual de webhooks de projeto.
5

Habilite os scans e verifique

Habilite PR scanning para revisar MRs nas configurações de scan do repositório. Habilite Check status posting quando o token tiver acesso Developer ou Maintainer. Execute um scan completo e abra ou atualize um MR real para verificar os fluxos desejados.

​
Pipelines de merge requests

Os scans automáticos de MRs precisam de um pipeline do GitLab para o commit escaneado. O ZeroPath procura:
  1. Um pipeline de MR existente para esse commit.
  2. Um pipeline de branch existente para esse commit.
  3. Um pipeline externo criado pela publicação de um status de commit, se Check status posting estiver habilitado e a credencial puder publicar status.
Se as configurações de scan exigirem um pipeline de CI (requireCiPipeline), um pipeline de MR existente é obrigatório; pipelines de branch e externos não são usados como alternativas. Se não for possível localizar ou criar um pipeline adequado, o scan automático do MR não começa. Um token Reporter não pode criar um pipeline externo pela API de status de commits. Com acesso Reporter, providencie um pipeline existente para cada commit escaneado e desabilite Check status posting. Um webhook manual sozinho não atende ao requisito de pipeline. Scans completos do repositório não exigem um pipeline do GitLab. Para bloquear merges com base nos resultados dos scans, use acesso Developer ou Maintainer para publicar status e configure as merge checks do GitLab. Veja as merge checks do GitLab.

​
Configuração manual de webhooks de projeto

Quando a integração tem acesso Maintainer, o ZeroPath pode configurar webhooks de projeto durante a importação. Se a configuração automática falhar, ou a credencial tiver acesso Reporter ou Developer, peça a um Maintainer ou Owner do projeto para criar o webhook:
  1. Copie a URL e o segredo específico do repositório do diálogo GitLab Webhook Setup Required do ZeroPath.
  2. No projeto do GitLab, abra Settings → Webhooks → Add new webhook.
  3. Configure os campos abaixo e salve o webhook.
Esses eventos correspondem à configuração automática de webhooks de projeto do ZeroPath. Eventos de issues, páginas wiki, tag pushes e jobs não são necessários. Repita a configuração para cada projeto importado que precise de um webhook manual.
Se sua versão do GitLab oferecer Signing token e Secret token, mantenha o valor do ZeroPath em Secret token. A integração autentica o cabeçalho X-Gitlab-Token; configurar apenas um signing token não substitui esse requisito.
Teste a entrega no GitLab e abra ou atualize um MR real. A entrega bem-sucedida de um webhook, sozinha, não confirma que um scan foi executado; confira o scan e o commit no ZeroPath.

​
Rede e TLS

Conexões com GitLab Self-Managed precisam de acesso de rede nas duas direções: O DNS precisa resolver corretamente e os certificados TLS devem ser confiáveis em cada direção. Use o hostname HTTPS da instância do GitLab, sem caminho de grupo/projeto nem sufixo /api/v4. Para hosts GitLab acessíveis apenas por rede privada, autoridades de certificação internas ou listas de IPs permitidos, coordene o acesso de rede e a confiança nos certificados com o administrador da implantação ou com o suporte do ZeroPath antes de conectar. O acesso a endereços privados depende da política de rede da sua implantação do ZeroPath. O diálogo de configuração do GitLab não oferece um campo de upload de bundle de CA; a confiança nos certificados precisa ser configurada para a implantação.

​
Substitua ou rotacione um token

Antes da expiração, abra um repositório conectado no ZeroPath e selecione Settings → GitLab Installation Token → Update Token. Selecione a conexão existente e forneça o token substituto, mantendo a instância do GitLab e o acesso aos repositórios desejados. A atualização se aplica a todos os repositórios que usam essa conexão e preserva o histórico de scans, os findings e as configurações de repositório. Quando a política permitir, crie um token substituto, atualize o ZeroPath e verifique o acesso antes de revogar o token antigo. A ação Rotate do GitLab invalida o token anterior imediatamente; atualize o ZeroPath logo após usá-la. Veja a documentação de rotação de tokens de grupo e de projeto. Se a conexão do ZeroPath já tiver sido excluída, crie uma substituta com acesso aos mesmos projetos. Ao sincronizar os projetos correspondentes na mesma instância do GitLab, o ZeroPath pode reconectar os repositórios preservados com seu histórico e configurações. Projetos inacessíveis ao novo token ou hospedados em outra instância permanecem desconectados.

​
Valide e resolva problemas

Confirme que os repositórios importados correspondem ao escopo aprovado, que um scan completo é concluído e que uma atualização real de MR inicia um scan para o commit mais recente. Quando a publicação de status estiver habilitada, verifique se ZeroPath Security Scan (ou o nome personalizado do check da sua implantação) aparece no pipeline que o GitLab avalia para o MR. Os comentários dependem das configurações de revisão habilitadas e dos findings do scan.