Passa al contenuto principale

Integrazione GitLab

Connetti i tuoi repository GitLab ad ArchiCore per l'analisi automatica.

Funzionalità​

  • Supporto self-hosted — Connetti gitlab.com o la tua istanza GitLab
  • Istanze multiple — Connetti più server GitLab contemporaneamente
  • Repository privati — Accesso completo ai progetti privati
  • Selezione branch — Scegli quale branch analizzare
  • Auto-analisi — Analisi automatica sugli eventi push
  • Revisioni Merge Request — Revisioni codice alimentate da IA sulle MR

Configurazione​

Passo 1: Creare un Personal Access Token​

  1. Vai nel tuo GitLab → Impostazioni → Access Tokens
  2. Crea un nuovo token con questi scope obbligatori:
    • api — Obbligatorio per accesso API completo (repository privati, webhook, commenti MR)
    • read_repository — Obbligatorio per leggere il contenuto del repository
Scope Obbligatori

Per i repository privati, lo scope api è obbligatorio. Senza di esso, ArchiCore non può accedere ai progetti privati anche se sei il proprietario o amministratore del repository.

  1. Copia il token (non lo vedrai più!)

Passo 2: Connettere l'Istanza GitLab​

Via Interfaccia Web:

  1. Vai in ArchiCore → Impostazioni → Integrazioni
  2. Clicca Aggiungi GitLab
  3. Inserisci l'URL del tuo GitLab (es. https://gitlab.com o https://gitlab.azienda.com)
  4. Incolla il tuo Personal Access Token
  5. Clicca Connetti

Via API:

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

Passo 3: Connettere un Repository​

  1. Dopo aver connesso l'istanza GitLab, clicca Aggiungi Progetto
  2. Seleziona l'istanza GitLab
  3. Cerca il tuo repository
  4. Seleziona un branch
  5. Clicca Connetti

GitLab Self-Hosted​

ArchiCore supporta completamente le istanze GitLab self-hosted.

Certificati SSL​

Se il tuo GitLab usa un certificato autofirmato:

  1. Durante la connessione, abilita "Consenti certificati autofirmati"
  2. O imposta rejectUnauthorizedSSL: false nella chiamata API

Accesso di Rete​

Perché i webhook funzionino, la tua istanza GitLab deve poter raggiungere l'endpoint webhook di ArchiCore:

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

Se anche ArchiCore è self-hosted, configura GITLAB_WEBHOOK_URL nel tuo ambiente.

Istanze Multiple​

Puoi connettere più istanze GitLab:

  • gitlab.com (pubblico)
  • gitlab.azienda.com (aziendale)
  • gitlab.cliente.com (progetti cliente)

Ogni istanza è gestita separatamente con le proprie credenziali.

Webhooks​

ArchiCore può creare automaticamente webhook per:

  • Eventi Push — Attivare l'analisi quando viene pushato codice
  • Eventi Merge Request — Aggiungere commenti di revisione IA alle MR

Configurazione Webhook​

I webhook vengono creati automaticamente quando connetti un repository con "Auto-analisi" abilitato.

Configurazione manuale webhook:

  1. Vai nel tuo progetto GitLab → Impostazioni → Webhooks
  2. Aggiungi URL: https://api.archicore.io/api/gitlab/webhook
  3. Secret Token: (fornito da ArchiCore)
  4. Abilita: eventi Push, eventi Merge request

Riferimento API​

Elenco Istanze​

GET /api/gitlab/instances

Aggiungi Istanza​

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

{
  "instanceUrl": "https://gitlab.azienda.com",
  "accessToken": "glpat-xxxxxxxxxxxx",
  "name": "Il Mio GitLab",
  "rejectUnauthorizedSSL": true
}

Elenco Progetti​

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

Elenco Branch​

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

Connetti Repository​

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

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

Disconnetti Repository​

DELETE /api/gitlab/repositories/{repoId}

Risoluzione Problemi​

"Token non valido"​

  • Verifica scadenza — Assicurati che il tuo PAT non sia scaduto
  • Verifica scope — Il token deve avere gli scope api e read_repository
  • Verifica URL — Per GitLab self-hosted, assicurati che l'URL sia corretto (includi https://)
  • Rigenera token — Se i problemi persistono, crea un nuovo token con gli scope corretti

"Errore certificato SSL"​

  • Abilita "Consenti certificati autofirmati" durante la connessione
  • O aggiungi il tuo certificato CA al trust store di sistema

"Webhook non riceve eventi"​

  • Verifica che il tuo GitLab possa raggiungere l'URL del webhook
  • Controlla GitLab → Progetto → Impostazioni → Webhooks → Consegne recenti
  • Assicurati che il secret del webhook corrisponda

"Repository non trovato"​

  • Verifica scope del token — Per i repository privati, il tuo PAT deve avere lo scope api. Lo scope read_api da solo non è sufficiente.
  • Verifica permessi del token — Anche se sei amministratore o proprietario del repository, un token con scope errati non può accedere ai progetti privati.
  • Inserisci percorso completo — Durante la connessione, usa il percorso completo del repository (es. gruppo/sottogruppo/nome-progetto), non solo il nome del progetto.
  • Verifica archiviazione — I repository archiviati potrebbero non apparire nei risultati di ricerca.
  • Verifica istanza corretta — Assicurati di guardare il server GitLab corretto (gitlab.com vs self-hosted).