Pular para o conteúdo principal

Integração GitLab

Conecte seus repositórios GitLab ao ArchiCore para análise automática.

Recursos​

  • Suporte auto-hospedado — Conecte gitlab.com ou sua própria instância GitLab
  • Múltiplas instâncias — Conecte vários servidores GitLab simultaneamente
  • Repositórios privados — Acesso completo a projetos privados
  • Seleção de branch — Escolha qual branch analisar
  • Auto-análise — Análise automática em eventos de push
  • Revisões de Merge Request — Revisões de código com IA em MRs

Configuração​

Passo 1: Criar um Token de Acesso Pessoal​

  1. Vá para seu GitLab → Configurações → Tokens de Acesso
  2. Crie um novo token com estes escopos obrigatórios:
    • api — Obrigatório para acesso API completo (repositórios privados, webhooks, comentários MR)
    • read_repository — Obrigatório para ler conteúdo do repositório
Escopos Obrigatórios

Para repositórios privados, o escopo api é obrigatório. Sem ele, ArchiCore não pode acessar projetos privados mesmo se você for o proprietário ou administrador do repositório.

  1. Copie o token (você não o verá novamente!)

Passo 2: Conectar Instância GitLab​

Via Interface Web:

  1. Vá para ArchiCore → Configurações → Integrações
  2. Clique em Adicionar GitLab
  3. Digite sua URL do GitLab (ex. https://gitlab.com ou https://gitlab.empresa.com)
  4. Cole seu Token de Acesso Pessoal
  5. Clique em Conectar

Via API:

curl -X POST https://api.archicore.io/api/gitlab/instances \
  -H "Authorization: Bearer SEU_TOKEN_ARCHICORE" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceUrl": "https://gitlab.empresa.com",
    "accessToken": "SEU_PAT_GITLAB",
    "name": "GitLab Empresa"
  }'

Passo 3: Conectar um Repositório​

  1. Após conectar sua instância GitLab, clique em Adicionar Projeto
  2. Selecione a instância GitLab
  3. Procure seu repositório
  4. Selecione um branch
  5. Clique em Conectar

GitLab Auto-hospedado​

ArchiCore suporta totalmente instâncias GitLab auto-hospedadas.

Certificados SSL​

Se seu GitLab usa um certificado autoassinado:

  1. Ao conectar, habilite "Permitir certificados autoassinados"
  2. Ou defina rejectUnauthorizedSSL: false na chamada API

Acesso à Rede​

Para que os webhooks funcionem, sua instância GitLab deve conseguir alcançar o endpoint de webhook do ArchiCore:

https://api.archicore.io/api/gitlab/webhook

Se ArchiCore também é auto-hospedado, configure GITLAB_WEBHOOK_URL em seu ambiente.

Múltiplas Instâncias​

Você pode conectar múltiplas instâncias GitLab:

  • gitlab.com (público)
  • gitlab.empresa.com (corporativo)
  • gitlab.cliente.com (projetos de clientes)

Cada instância é gerenciada separadamente com suas próprias credenciais.

Webhooks​

ArchiCore pode criar webhooks automaticamente para:

  • Eventos de Push — Acionar análise quando código é enviado
  • Eventos de Merge Request — Adicionar comentários de revisão IA a MRs

Configuração de Webhook​

Webhooks são criados automaticamente quando você conecta um repositório com "Auto-análise" habilitado.

Configuração manual de webhook:

  1. Vá para seu projeto GitLab → Configurações → Webhooks
  2. Adicione URL: https://api.archicore.io/api/gitlab/webhook
  3. Token Secreto: (fornecido pelo ArchiCore)
  4. Habilite: eventos de Push, eventos de Merge request

Referência da API​

Listar Instâncias​

GET /api/gitlab/instances

Adicionar Instância​

POST /api/gitlab/instances
Content-Type: application/json

{
  "instanceUrl": "https://gitlab.empresa.com",
  "accessToken": "glpat-xxxxxxxxxxxx",
  "name": "Meu GitLab",
  "rejectUnauthorizedSSL": true
}

Listar Projetos​

GET /api/gitlab/instances/{instanceId}/projects?search=meuprojeto

Listar Branches​

GET /api/gitlab/instances/{instanceId}/projects/{projectId}/branches

Conectar Repositório​

POST /api/gitlab/repositories/connect
Content-Type: application/json

{
  "instanceId": "uuid",
  "projectId": 123,
  "autoAnalyze": true,
  "analyzeMRs": true,
  "branch": "main"
}

Desconectar Repositório​

DELETE /api/gitlab/repositories/{repoId}

Solução de Problemas​

"Token inválido"​

  • Verificar expiração — Certifique-se de que seu PAT não expirou
  • Verificar escopos — O token deve ter os escopos api e read_repository
  • Verificar URL — Para GitLab auto-hospedado, certifique-se de que a URL está correta (inclua https://)
  • Regenerar token — Se os problemas persistirem, crie um novo token com os escopos corretos

"Erro de certificado SSL"​

  • Habilite "Permitir certificados autoassinados" ao conectar
  • Ou adicione seu certificado CA ao repositório de confiança do sistema

"Webhook não recebendo eventos"​

  • Verifique se seu GitLab consegue alcançar a URL do webhook
  • Verifique GitLab → Projeto → Configurações → Webhooks → Entregas recentes
  • Certifique-se de que o segredo do webhook corresponde

"Repositório não encontrado"​

  • Verificar escopos do token — Para repositórios privados, seu PAT deve ter o escopo api. O escopo read_api sozinho não é suficiente.
  • Verificar permissões do token — Mesmo se você for administrador ou proprietário do repositório, um token com escopos incorretos não pode acessar projetos privados.
  • Inserir caminho completo — Ao conectar, use o caminho completo do repositório (ex. grupo/subgrupo/nome-projeto), não apenas o nome do projeto.
  • Verificar arquivamento — Repositórios arquivados podem não aparecer nos resultados de pesquisa.
  • Verificar instância correta — Certifique-se de estar olhando o servidor GitLab correto (gitlab.com vs auto-hospedado).