GitHub¶

Guida dettagliata per l'integrazione con GitHub Actions.

Permessi¶

Permessi Minimi¶

permissions:
  contents: read        # Leggi codice
  pull-requests: write  # Pubblica commenti

GITHUB_TOKEN in Actions¶

In GitHub Actions, GITHUB_TOKEN e automaticamente disponibile:

env:
  GITHUB_TOKEN: ${{ github.token }}

Permessi automatici del token:

Permesso	Stato	Nota
`contents: read`		Default
`pull-requests: write`		Deve essere specificato in `permissions`

PR da Fork

Per PR da repository fork, GITHUB_TOKEN ha permessi solo lettura.

AI Review non puo pubblicare commenti per PR da fork.

Come Ottenere un Personal Access Token¶

Per esecuzioni locali, hai bisogno di un Personal Access Token (PAT):

Vai su Settings → Developer settings → Personal access tokens
Scegli Fine-grained tokens (consigliato) o Classic
Clicca Generate new token

Fine-grained token (consigliato):

Impostazione	Valore
Repository access	Only select repositories → il tuo repository
Permissions	`Pull requests: Read and write`

Classic token:

Scope	Descrizione
`repo`	Accesso completo al repository

Clicca Generate token
Copia il token e salvalo come GITHUB_TOKEN

Salva il token

GitHub mostra il token una sola volta. Salvalo immediatamente.

Trigger¶

Trigger Consigliato¶

on:
  pull_request:
    types: [opened, synchronize, reopened]

Tipo	Quando si attiva
`opened`	PR creato
`synchronize`	Nuovi commit nel PR
`reopened`	PR riaperto

Filtro File¶

Esegui la revisione solo per file specifici:

on:
  pull_request:
    paths:
      - '**.py'
      - '**.js'
      - '**.ts'

Filtro Branch¶

on:
  pull_request:
    branches:
      - main
      - develop

Secret¶

Aggiungere Secret¶

Settings → Secrets and variables → Actions → New repository secret

Secret	Necessario	Descrizione
`AI_REVIEWER_GOOGLE_API_KEY`		Chiave API Gemini

Utilizzo¶

env:
  AI_REVIEWER_GOOGLE_API_KEY: ${{ secrets.AI_REVIEWER_GOOGLE_API_KEY }}

Mai hardcodare i secret

# ❌ SBAGLIATO
env:
  AI_REVIEWER_GOOGLE_API_KEY: AIza...

# ✅ CORRETTO
env:
  AI_REVIEWER_GOOGLE_API_KEY: ${{ secrets.AI_REVIEWER_GOOGLE_API_KEY }}

Esempi Workflow¶

Minimo¶

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: KonstZiv/ai-code-reviewer@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          google_api_key: ${{ secrets.AI_REVIEWER_GOOGLE_API_KEY }}

Informazioni su GITHUB_TOKEN

secrets.GITHUB_TOKEN e un token automatico che GitHub crea per ogni esecuzione del workflow. Non e necessario aggiungerlo manualmente ai secret — e gia disponibile.

I permessi del token sono definiti dalla sezione permissions nel file workflow.

GitHub Docs: Automatic token authentication

Con Concurrency (consigliato)¶

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

concurrency:
  group: ai-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.full_name == github.repository
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: KonstZiv/ai-code-reviewer@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          google_api_key: ${{ secrets.AI_REVIEWER_GOOGLE_API_KEY }}
          language: uk
          language_mode: adaptive

Cosa fa la concurrency:

Se un nuovo commit viene pushato mentre la revisione e ancora in esecuzione — la vecchia revisione viene cancellata
Risparmia risorse e chiamate API

Con Filtro PR da Fork¶

jobs:
  review:
    runs-on: ubuntu-latest
    # Non eseguire per PR da fork (nessun accesso ai secret)
    if: github.event.pull_request.head.repo.full_name == github.repository

Input della GitHub Action¶

Input	Descrizione	Default
`google_api_key`	Chiave API Gemini	necessario
`github_token`	Token GitHub	`${{ github.token }}`
`language`	Lingua risposte	`en`
`language_mode`	Modalità lingua	`adaptive`
`gemini_model`	Modello Gemini	`gemini-2.5-flash`
`log_level`	Livello log	`INFO`
`review_max_comment_chars`	Max caratteri commento MR nel prompt	`3000`
`review_include_bot_comments`	Includi commenti bot nel prompt	`true`
`review_post_inline_comments`	Pubblica commenti inline sulle righe	`true`
`gemini_model_fallback`	Catena di modelli di fallback (separati da virgola)	`gemini-3-flash-preview`
`review_enable_dialogue`	Raggruppare i commenti in dialoghi	`true`
`discovery_enabled`	Attivare project discovery	`true`
`discovery_verbose`	Pubblicare sempre il commento discovery	`false`
`discovery_timeout`	Timeout discovery in secondi	`30`

Variabili d'ambiente

La Action mappa gli input alle variabili d'ambiente AI_REVIEWER_* internamente. Quando si esegue al di fuori della Action, usa direttamente le variabili AI_REVIEWER_* (i vecchi nomi come GOOGLE_API_KEY funzionano ancora come fallback).

Configurazione tramite Variables¶

Usa le Repository Variables per passare da un provider LLM e modello all'altro senza modificare il file workflow. Utile per confrontare la qualità della revisione di diversi modelli sullo stesso PR.

Configurazione¶

Secrets (impostare una volta):

Secret	Descrizione
`AI_REVIEWER_GOOGLE_API_KEY`	Chiave API Gemini
`AI_REVIEWER_MISTRAL_API_KEY`	Chiave API Mistral

Variables (Settings → Secrets and variables → Actions → Variables):

Variable	Descrizione	Predefinito
`LLM_PROVIDER`	Provider principale (`google`, `mistral`)	`google`
`LLM_FALLBACK_PROVIDER`	Provider di fallback	(nessuno)
`MISTRAL_MODEL`	Modello Mistral	`mistral-large-latest`
`MISTRAL_API_URL`	URL API personalizzato (per Codestral free tier)	(nessuno)

Workflow¶

name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

concurrency:
  group: ai-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    runs-on: ubuntu-latest
    if: github.event.pull_request.head.repo.full_name == github.repository
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: KonstZiv/ai-code-reviewer@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          google_api_key: ${{ secrets.AI_REVIEWER_GOOGLE_API_KEY }}
          mistral_api_key: ${{ secrets.AI_REVIEWER_MISTRAL_API_KEY }}
          llm_provider: ${{ vars.LLM_PROVIDER || 'google' }}
          llm_fallback_provider: ${{ vars.LLM_FALLBACK_PROVIDER || '' }}
          mistral_model: ${{ vars.MISTRAL_MODEL || 'mistral-large-latest' }}
          mistral_api_url: ${{ vars.MISTRAL_API_URL || '' }}

Cambiare preset¶

Modifica le Variables nell'interfaccia GitHub, poi esegui di nuovo (Re-run) il workflow sullo stesso PR:

Preset	`LLM_PROVIDER`	`MISTRAL_MODEL`	`MISTRAL_API_URL`	`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.

Variables vs Secrets

Secrets — crittografati, nascosti nei log — per le chiavi API. Variables — visibili nei log — per configurazione non sensibile (nomi dei modelli).

Risultato della Review¶

Commenti Inline¶

AI Review pubblica commenti direttamente sulle righe di codice:

CRITICAL — problemi critici (sicurezza, bug)
WARNING — raccomandazioni
INFO — note educative

Apply Suggestion¶

Ogni commento con un suggerimento di codice ha un pulsante "Apply suggestion":

fixed_code_here

GitHub lo renderizza automaticamente come pulsante interattivo.

Summary¶

Alla fine della revisione, viene pubblicato un Summary con:

Statistiche generali dei problemi
Metriche (tempo, token, costo)
Good practice (feedback positivo)

Troubleshooting¶

La Review Non Pubblica Commenti¶

Controlla:

permissions: pull-requests: write e nel workflow
Il secret AI_REVIEWER_GOOGLE_API_KEY e impostato
Il PR non e da un repository fork

"Resource not accessible by integration"¶

Causa: Permessi insufficienti.

Soluzione: Aggiungi i permessi:

permissions:
  contents: read
  pull-requests: write

Rate Limit da Gemini¶

Causa: Limite free tier superato (15 RPM).

Soluzione:

Aspetta un minuto
Aggiungi concurrency per cancellare le vecchie esecuzioni
Considera il tier a pagamento

Best Practice¶

1. Usa sempre concurrency¶

concurrency:
  group: ai-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

2. Filtra PR da fork¶

if: github.event.pull_request.head.repo.full_name == github.repository

3. Imposta timeout¶

jobs:
  review:
    timeout-minutes: 10

4. Rendi il job non bloccante¶

jobs:
  review:
    continue-on-error: true

GitHub¶

Permessi¶

Permessi Minimi¶

GITHUB_TOKEN in Actions¶

Come Ottenere un Personal Access Token¶

Trigger¶

Trigger Consigliato¶

Filtro File¶

Filtro Branch¶

Secret¶

Aggiungere Secret¶

Utilizzo¶

Esempi Workflow¶

Minimo¶

Con Concurrency (consigliato)¶

Con Filtro PR da Fork¶

Input della GitHub Action¶

Configurazione tramite Variables¶

Configurazione¶

Workflow¶

Cambiare preset¶

Risultato della Review¶

Commenti Inline¶

Apply Suggestion¶

Summary¶

Troubleshooting¶

La Review Non Pubblica Commenti¶

"Resource not accessible by integration"¶

Rate Limit da Gemini¶

Best Practice¶

1. Usa sempre concurrency¶

2. Filtra PR da fork¶

3. Imposta timeout¶

4. Rendi il job non bloccante¶

Prossimo Passo¶