> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração com GitLab

> Configure tokens de acesso, permissões de repositório, webhooks e pipelines do GitLab para os scans do ZeroPath

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](https://docs.gitlab.com/security/tokens/access_token_scopes/).

| Recurso no projeto | Reporter | Developer | Maintainer |
| - | - | - | - |
| Ler código e executar scans completos do repositório | Sim | Sim | Sim |
| Publicar comentários em merge requests | Sim | Sim | Sim |
| Criar ou atualizar status de commits | Não | Sim | Sim |
| Configurar webhooks de projeto automaticamente | Não | Não | Sim |

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](https://docs.gitlab.com/user/permissions/).

> [!NOTE]
>
> **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](#merge-request-pipelines).

### 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](https://docs.gitlab.com/user/project/integrations/webhooks/).

## Escolha um token e limite o acesso

| Credencial | Quando usar | Opção no ZeroPath |
| - | - | - |
| Token de acesso de projeto | Um projeto aprovado | **Project**, com o caminho completo, como `team/service` |
| Token de acesso de grupo | Projetos em um grupo ou subgrupo dedicado, incluindo descendentes | **Group**, com o caminho completo, como `team/approved` |
| PAT de uma conta dedicada | Projetos aprovados em vários grupos; conceda acesso à conta somente onde necessário | **Personal Access Token**, sem caminho de grupo ou projeto |

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](https://docs.gitlab.com/user/group/settings/group_access_tokens/)
e [tokens de projeto](https://docs.gitlab.com/user/project/settings/project_access_tokens/).

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.

> [!NOTE]
>
> 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](https://docs.gitlab.com/user/group/settings/group_access_tokens/) e
> [tokens de projeto](https://docs.gitlab.com/user/project/settings/project_access_tokens/).

## 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](https://zeropath.com/app/repositories?m=AddRepos).

**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](#manual-project-webhook-setup).

**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](/docs/pt/scanning/pr-scanning.md#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.

| Configuração | Valor |
| - | - |
| **URL** | A URL fornecida pela sua implantação do ZeroPath. A URL padrão em nuvem é `https://zeropath.com/api/gitlab/webhook`. |
| **Secret token** | O segredo exato de webhook fornecido pelo ZeroPath para esse repositório, separado do token de acesso do GitLab. |
| **Triggers** | **Merge request events**, **Push events**, **Comments** (note events) e **Pipeline events**. |
| **Enable SSL verification** | Mantenha habilitado; o GitLab precisa confiar no certificado apresentado pelo ZeroPath. |
| **Custom webhook template** | Deixe sem configuração para que o GitLab envie o payload padrão. |

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.

> [!NOTE]
>
> 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:

| Direção | Acesso necessário |
| - | - |
| **ZeroPath → GitLab** | Acesso HTTPS à API do GitLab e aos endpoints dos repositórios Git, normalmente pela porta TCP 443 ou pela porta HTTPS configurada. |
| **GitLab → ZeroPath** | Entrega de POSTs HTTPS à URL de webhook fornecida pelo ZeroPath. Os nós Rails e Sidekiq do GitLab precisam conseguir enviar webhooks. |

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](mailto:support@zeropath.com) 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](https://docs.gitlab.com/user/group/settings/group_access_tokens/#rotate-a-group-access-token)
e de [projeto](https://docs.gitlab.com/user/project/settings/project_access_tokens/#rotate-a-project-access-token).

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.

| Sintoma | O que verificar |
| - | - |
| Um projeto não aparece | Instância e caminho completo de projeto/grupo corretos; validade do token; pelo menos acesso Reporter ao projeto. |
| A clonagem falha | Acesso da credencial, uma branch com commits, DNS, conectividade de rede e confiança TLS. |
| A configuração do webhook retorna 403 | Webhooks de projeto exigem Maintainer ou Owner. Webhooks de grupo exigem Owner do grupo. Use webhooks de projeto para manter a integração como Maintainer. |
| Um scan de MR não começa | PR scanning habilitado, MR elegível conforme as configurações de scan, entrega de webhook bem-sucedida e um pipeline adequado existente ou que possa ser criado. |
| A publicação de status de commit retorna 403 | Acesso Developer ou Maintainer e regras compatíveis de branch/pipeline. Com Reporter, desabilite a publicação de status e providencie um pipeline existente. |
| Os scans param após a rotação do token | Atualize a conexão existente no ZeroPath com o token substituto e confirme que ele ainda acessa os projetos desejados. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.