GitLab¶

Guida dettagliata per l'integrazione con GitLab CI.

Token¶

Personal Access Token (PAT)¶

Consigliato per tutti i piani GitLab (incluso Free).

CI_JOB_TOKEN non funziona

Il CI_JOB_TOKEN automatico di GitLab non puo pubblicare commenti sulle Merge Request (l'API Notes richiede lo scope api, che CI_JOB_TOKEN non possiede). Devi usare un Personal Access Token o un Project Access Token.

Come creare:

Vai su User Settings → Access Tokens → Add new token
- URL: https://gitlab.com/-/user_settings/personal_access_tokens
Compila i campi:
- Token name: ai-code-reviewer
- Expiration date: imposta secondo necessita (es. 1 anno)
- Scopes: seleziona api
Clicca Create personal access token
Copia il token immediatamente — GitLab lo mostra una sola volta!

Come usare in CI:

Vai su Settings → CI/CD → Variables → Add variable
Aggiungi la variabile:
- Key: AI_REVIEWER_GITLAB_TOKEN
- Value: incolla il tuo token
- Flags: seleziona Masked, deseleziona Protected
La variabile sarà disponibile automaticamente per tutti i job — non serve il mapping YAML variables:.

Deseleziona «Protected»!

Per impostazione predefinita, GitLab contrassegna le nuove variabili come Protected. Le variabili Protected sono disponibili solo nei branch protetti (es. main).

Le pipeline MR vengono eseguite su branch sorgente non protetti — la variabile sarà vuota e otterrai 401 Unauthorized.

Deseleziona sempre «Protected» per AI_REVIEWER_GITLAB_TOKEN e AI_REVIEWER_GOOGLE_API_KEY.

Salva il token

GitLab mostra il token una sola volta. Salvalo immediatamente in un luogo sicuro.

Project Access Token ( Premium/Ultimate)¶

Disponibile solo sui piani GitLab Premium e Ultimate. Una buona scelta se preferisci un token con ambito di progetto invece di uno personale.

Vantaggi rispetto al PAT:

Limitato a un singolo progetto (nessun accesso ad altri progetti)
Puo essere revocato dai maintainer del progetto (nessuna dipendenza da un utente specifico)
Migliore per i team — non legato a un account personale

Come creare:

Vai su Project → Settings → Access Tokens
- URL: https://gitlab.com/<owner>/<repo>/-/settings/access_tokens
Compila i campi:
- Token name: ai-code-reviewer
- Role: Developer (minimo richiesto)
- Scopes: seleziona api
Clicca Create project access token
Copia il token immediatamente

Come usare in CI:

Come il PAT — aggiungi come AI_REVIEWER_GITLAB_TOKEN nelle CI/CD Variables:

Key: AI_REVIEWER_GITLAB_TOKEN
Value: incolla il tuo Project Access Token

Quale token scegliere?

	Personal Access Token	Project Access Token
Piano	Tutti (incluso Free)	Solo Premium/Ultimate
Configurazione	Manuale	Manuale
Ambito	Tutti i progetti dell'utente	Singolo progetto
Commenti inline
Ideale per	Piano Free + funzionalita completa	Team su Premium/Ultimate

Variabili CI/CD¶

Aggiungere Variabili¶

Settings → CI/CD → Variables → Add variable

Variabile	Valore	Opzioni
`AI_REVIEWER_GOOGLE_API_KEY`	Chiave API Gemini	Masked, Uncheck Protected
`AI_REVIEWER_GITLAB_TOKEN`	PAT o Project Access Token	Masked, Uncheck Protected

Masked

Abilita sempre Masked per i secret — non verranno mostrati nei log.

Trigger¶

Trigger Consigliato¶

rules:
  - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Questo esegue il job solo per le pipeline di Merge Request.

Trigger Alternativo (only/except)¶

only:
  - merge_requests

rules vs only

rules — sintassi piu recente, consigliata da GitLab.

Esempi Job¶

Minimo¶

ai-review:
  image: ghcr.io/konstziv/ai-code-reviewer:1
  script:
    - ai-review
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Le variabili CI/CD AI_REVIEWER_GOOGLE_API_KEY e AI_REVIEWER_GITLAB_TOKEN vengono ereditate automaticamente.

Completo (consigliato)¶

ai-review:
  image: ghcr.io/konstziv/ai-code-reviewer:1
  stage: test
  script:
    - ai-review
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  allow_failure: true
  timeout: 10m
  variables:
    AI_REVIEWER_LANGUAGE: uk
    AI_REVIEWER_LANGUAGE_MODE: adaptive
  interruptible: true

Cosa fa:

allow_failure: true — la MR non viene bloccata se la revisione fallisce
timeout: 10m — massimo 10 minuti
interruptible: true — puo essere cancellato con un nuovo commit

Con Stage Personalizzato¶

stages:
  - test
  - review
  - deploy

ai-review:
  stage: review
  image: ghcr.io/konstziv/ai-code-reviewer:1
  script:
    - ai-review
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  needs: []  # Non aspettare gli stage precedenti

GitLab Self-hosted¶

Configurazione¶

variables:
  AI_REVIEWER_GITLAB_URL: https://gitlab.mycompany.com

Docker Registry¶

Se il tuo GitLab non ha accesso a ghcr.io, crea un mirror:

# Su una macchina con accesso
docker pull ghcr.io/konstziv/ai-code-reviewer:1
docker tag ghcr.io/konstziv/ai-code-reviewer:1 \
    gitlab.mycompany.com:5050/devops/ai-code-reviewer:latest
docker push gitlab.mycompany.com:5050/devops/ai-code-reviewer:latest

ai-review:
  image: gitlab.mycompany.com:5050/devops/ai-code-reviewer:latest

Variabili CI GitLab¶

AI Code Reviewer usa automaticamente:

Variabile	Descrizione
`CI_PROJECT_PATH`	`owner/repo`
`CI_MERGE_REQUEST_IID`	Numero MR
`CI_SERVER_URL`	URL GitLab

Non hai bisogno di passare --repo e --pr — vengono presi automaticamente dalla CI.

Configurazione tramite Variabili CI/CD¶

Usa le CI/CD Variables per passare da un provider LLM e modello all'altro senza modificare .gitlab-ci.yml. Utile per confrontare la qualità della revisione di diversi modelli sullo stesso MR.

Configurazione¶

CI/CD Variables (Settings → CI/CD → Variables):

Variabile	Descrizione	Opzioni
`AI_REVIEWER_GOOGLE_API_KEY`	Chiave API Gemini	Masked, Deselezionare Protected
`AI_REVIEWER_MISTRAL_API_KEY`	Chiave API Mistral	Masked, Deselezionare Protected
`AI_REVIEWER_GITLAB_TOKEN`	Token GitLab	Masked, Deselezionare Protected
`AI_REVIEWER_LLM_PROVIDER`	Provider principale (`google`, `mistral`)	Deselezionare Protected
`AI_REVIEWER_LLM_FALLBACK_PROVIDER`	Provider di fallback	Deselezionare Protected
`AI_REVIEWER_MISTRAL_MODEL`	Modello Mistral	Deselezionare Protected
`AI_REVIEWER_MISTRAL_API_URL`	URL API personalizzato (per Codestral free tier)	Deselezionare Protected

Configurazione del job¶

ai-review:
  image: ghcr.io/konstziv/ai-code-reviewer:1
  stage: review
  script:
    - ai-review
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  allow_failure: true
  interruptible: true

Nessuna sezione variables: necessaria — tutte le variabili CI/CD AI_REVIEWER_* vengono ereditate automaticamente.

Cambiare preset¶

Modifica le CI/CD Variables nell'interfaccia GitLab e clicca su Retry nella pipeline dello stesso MR:

Preset	`AI_REVIEWER_LLM_PROVIDER`	`AI_REVIEWER_MISTRAL_MODEL`	`AI_REVIEWER_MISTRAL_API_URL`	`AI_REVIEWER_LLM_FALLBACK_PROVIDER`
Gemini (predefinito)	`google`	(vuoto)	(vuoto)	(vuoto)
Mistral Large	`mistral`	`mistral-large-latest`	(vuoto)	`google`
Codestral free	`mistral`	`codestral-latest`	`https://codestral.mistral.ai`	`google`
Devstral	`mistral`	`devstral-latest`	(vuoto)	`google`

Chiave Codestral free tier

Per il preset "Codestral free", AI_REVIEWER_MISTRAL_API_KEY deve contenere una chiave da codestral.mistral.ai, non da console.mistral.ai.

Non serve codificare nel YAML

A differenza di GitHub Actions (dove gli input devono essere mappati esplicitamente), GitLab CI passa automaticamente tutte le variabili CI/CD come variabili d'ambiente. Basta impostarle nell'interfaccia — l'applicazione le rileva tramite il prefisso AI_REVIEWER_*.

Risultato della Review¶

Note (commenti)¶

AI Review pubblica commenti sulla MR come note.

Discussioni (inline)¶

Per commenti inline, hai bisogno di un Personal Access Token o Project Access Token con scope api.

I commenti inline appaiono direttamente accanto alle righe di codice nella vista diff.

Summary¶

Alla fine della revisione, viene pubblicata una nota Summary con:

Statistiche generali
Metriche
Good practice

Troubleshooting¶

La Review Non Pubblica Commenti¶

Controlla:

La variabile AI_REVIEWER_GOOGLE_API_KEY e impostata
AI_REVIEWER_GITLAB_TOKEN ha permessi sufficienti (scope: api)
La pipeline e in esecuzione per una MR (non per un branch)

"401 Unauthorized"¶

Causa: Token non valido.

Soluzione:

Controlla che il token non sia scaduto
Controlla lo scope (serve api)

"403 Forbidden"¶

Causa: Permessi insufficienti.

Soluzione:

Controlla che il token abbia scope api
Controlla che il token abbia accesso al progetto

"404 Not Found"¶

Causa: MR non trovata.

Soluzione:

Controlla che la pipeline sia in esecuzione per una MR
Controlla CI_MERGE_REQUEST_IID

Rate Limit (429)¶

Causa: Limite API superato.

Soluzione:

AI Code Reviewer riprova automaticamente con backoff esponenziale
Se persiste — aspetta o aumenta i limiti

Best Practice¶

1. Usa PAT per funzionalita completa¶

2. Aggiungi allow_failure¶

allow_failure: true

La MR non verra bloccata se la revisione fallisce.

3. Imposta timeout¶

timeout: 10m

4. Rendi il job interrompibile¶

interruptible: true

La vecchia revisione verra cancellata con un nuovo commit.

5. Non aspettare altri stage¶

needs: []

La revisione partira immediatamente, senza aspettare build/test.

GitLab¶

Token¶

Personal Access Token (PAT)¶

Project Access Token ( Premium/Ultimate)¶

Variabili CI/CD¶

Aggiungere Variabili¶

Trigger¶

Trigger Consigliato¶

Trigger Alternativo (only/except)¶

Esempi Job¶

Minimo¶

Completo (consigliato)¶

Con Stage Personalizzato¶

GitLab Self-hosted¶

Configurazione¶

Docker Registry¶

Variabili CI GitLab¶

Configurazione tramite Variabili CI/CD¶

Configurazione¶

Configurazione del job¶

Cambiare preset¶

Risultato della Review¶

Note (commenti)¶

Discussioni (inline)¶

Summary¶

Troubleshooting¶

La Review Non Pubblica Commenti¶

"401 Unauthorized"¶

"403 Forbidden"¶

"404 Not Found"¶

Rate Limit (429)¶

Best Practice¶

1. Usa PAT per funzionalita completa¶

2. Aggiungi allow_failure¶

3. Imposta timeout¶

4. Rendi il job interrompibile¶

5. Non aspettare altri stage¶

Prossimo Passo¶