Lasciare che un LLM Revisioni le Nostre Pull Request (Così Non Devi Farlo Tu)

Adoriamo l’automazione. La usiamo per alimentare la nostra infrastruttura, per ridurre i carichi di lavoro a zero e—sempre più spesso—per diminuire l’attenzione umana necessaria a rilasciare codice di alta qualità. Un ambito che ancora ci sembrava ostinatamente manuale erano le revisioni delle pull request. Tra Cursor come nostro IDE, ChatGPT/Codex per il prototipo e gemini-cli per controlli rapidi, i nostri workflow locali erano veloci—ma la CI aspettava ancora un umano.

Così ci siamo posti una domanda semplice: potevamo lasciare che un modello di linguaggio ampio leggesse il diff, individuasse problemi e commentasse direttamente sulla PR?

Si è scoperto: sì. Sono bastate poche righe di colla con GitHub Actions per ottenere revisioni utili e strutturate su ogni pull request.

The goal

Non volevamo sostituire gli umani. Volevamo un primo passaggio che:

• leggesse il diff effettivo di una PR (non l’intero repository),
• evidenziasse errori ovvi e cambiamenti rischiosi,
• suggerisse piccole rifattorizzazioni o test mancanti,
• categoria i risultati per priorità,
• e pubblicasse i risultati proprio dove già guardiamo: nella conversazione della PR e nel riepilogo delle Actions.

Se un cambiamento va bene, vogliamo che il bot lo dica semplicemente e si faccia da parte.

The tools in our stack

• GitHub Actions per l’orchestrazione CI.
• Cursor (il nostro IDE quotidiano).
• ChatGPT/Codex per ideazione e revisioni veloci offline.
• @google/gemini-cli dentro la CI per eseguire il passo di revisione automatizzato.
• La GitHub CLI (gh) per commentare sulla PR.
• Un piccolo ma importante ingrediente: un prompt che guida il modello a produrre feedback utili e azionabili.

The workflow, end to end

Ecco l’Action completa che stiamo eseguendo. Inseriscila in .github/workflows/gemini-pr.yml:

name: gemini-pr
on:
  workflow_dispatch:
  pull_request:
jobs:
  build:
    permissions: write-all
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
      with:
        submodules: 'true'
        fetch-depth: 0
    - uses: actions-rust-lang/setup-rust-toolchain@v1
      with:
        components: rustfmt, clippy
        cache: false
    - uses: actions/setup-node@v4
      with:
        node-version: 20
    - name: install gemini
      run: |
        npm install -g @google/gemini-cli
    - name: gemini
      run: |
        echo "merging into ${{ github.base_ref }}"
        git diff origin/${{ github.base_ref }} > pr.diff
        echo $PROMPT | gemini > review.md
        cat review.md >> $GITHUB_STEP_SUMMARY
        gh pr comment ${{ github.event.pull_request.number }} --body-file review.md
      env:
        GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        PROMPT: >
          please review the changes of @pr.diff (this pull request) and suggest improvements or provide insights into potential issues. 
          do not document or comment on existing changes, if everything looks good, just say so.
          can you categorise the changes and improvesments into low, medium and high priority?
          Whenever you find an issue, please always provide an file and line number as reference information. if multiple files are affected, please provide a list of files and line numbers.
          provide the output in markdown format and do not include any other text.

What each part does

• Checkout con fetch-depth: 0 così possiamo fare diff affidabili contro il branch base della PR.

• Toolchain Rust installa rustfmt e clippy perché i nostri repo spesso includono codice Rust; questi strumenti girano anche in altri punti della pipeline, ma mantenere la configurazione qui evita sorprese.

• Node è richiesto per gemini-cli.

• Installiamo @google/gemini-cli globalmente nel runner.

• Creiamo un file diff:

  git diff origin/${{ github.base_ref }} > pr.diff
  

  Così il modello vede solo le modifiche in revisione.

• Pipiamo il prompt dentro gemini (la CLI legge @pr.diff inline come riferimento file) e catturiamo l’output markdown del modello in review.md.

• Aggiungiamo la review al Riepilogo del Job ($GITHUB_STEP_SUMMARY) così è visibile nell’interfaccia delle Actions.

• Commentiamo sulla PR usando gh pr comment … --body-file review.md.

The prompt that makes it useful

Gli output di LLM sono validi quanto le istruzioni che ricevono. Il nostro mantiene le cose pratiche:

• Campo di applicazione: Revisione solo di ciò che è cambiato. Non ridocumentare il repository.
• Segnale: Dire “looks good” se non c’è nulla da aggiungere. Niente creatività forzata.
• Azionabilità: Includere sempre file + numeri di linea per i riscontri.
• Priorità: Raggruppare per basso / medio / alto per aiutare a scansionare rapidamente.
• Formato: Solo Markdown, così si incolla pulito nei commenti PR e rende bene nel riepilogo.

Abbiamo iterato un po’ per arrivare a questo. Le modifiche più incisive sono state: insistere su riferimenti file/linea e vietare testi extra.

What the review looks like

Su una PR tipica vediamo sezioni come:

• Alto: Cambiamenti sensibili alla sicurezza, gestione errori rotta, validazione input mancante, segreti accidentalmente esposti o test rimossi.
• Medio: Casi limite, rischi di concorrenza, messaggi d’errore discutibili, Rust/Go/TS non idiomatici che potrebbero dare problemi dopo.
• Basso: Nomi, commenti, piccole rifattorizzazioni o suggerimenti per un test breve a confermare un comportamento.

Se tutto va bene, otteniamo una frase singola: “Looks good.” Perfetto—è proprio quello che vogliamo.

Gotchas and practical notes

• Secrets: Ti servono GEMINI_API_KEY e GITHUB_TOKEN nei secrets del repo o dell’organizzazione. Mantieni gli scope stretti. L’Action imposta permissions: write-all perché pubblica un commento; restringi se la tua policy lo richiede.
• Fonte del diff: Per merge complessi, git diff origin/${{ github.base_ref }} fornisce il contesto corretto. Se il tuo workflow scarica solo il commit di merge, assicurati che il branch base sia disponibile o adatta a github.event.pull_request.base.sha.
• Fork: Se accetti PR da fork, rivedi come gestisci i secrets. Puoi voler eseguire questa azione su pull_request_target con un rafforzamento attento, o limitare la revisione dietro certi label.
• Controllo del rumore: Abbiamo trovato utile lasciare che il modello non dica nulla se non “looks good” su cambiamenti banali. Questo riduce molto la fatica del revisore.
• Costi e quote: Le chiamate al modello non sono gratuite. Limitiamo la dimensione del diff inviato ed eseguiamo questo solo su pull_request (non su ogni push).
• Privacy: Stai inviando il tuo diff a un provider esterno di modelli. Se il tuo codice è sensibile o soggetto a restrizioni di esportazione, valuta i rischi e scegli un provider/modello di deployment conforme.

Why this matters (beyond convenience)

Le revisioni automatiche rendono gli umani più selettivi nell’attenzione. Passiamo meno tempo su “rinomina questa variabile” e più su architettura, flussi di dati e confini di sicurezza. Questo significa:

• Feedback più rapido per i contributori.
• Meno cicli di revisione su dettagli minori.
• Storia commit più pulita con problemi catturati prima.
• Più tempo per il lavoro di sostenibilità che ci interessa davvero—come ridurre i watt di un servizio o diminuire l’egresso di rete.

È anche sorprendentemente bravo a garantire la coerenza. Un LLM non dimentica il pattern di gestione errori concordato tra servizi o la nostra struttura log preferita; applica quei controlli uniformemente su ogni PR.

Variations you might try

Questo schema funziona con quasi ogni modello o CLI. Alcune estensioni facili:

• Multi-model voting: Chiamare due modelli con lo stesso prompt e tenere solo i riscontri su cui sono concordi.
• Passaggi sensibili al linguaggio: Se il tuo repo mescola linguaggi, esegui prompt specifici per linguaggio (es. uno tarato per Rust con suggerimenti clippy, uno per TypeScript).
• Gate “Fallimento su Alto”: Usa un piccolo parser per rilevare una sezione “Alto” e fare fallire il job per bloccare i merge fino alla risoluzione.
• Revisione inline: Converti riferimenti file/linea in commenti di revisione GitHub (la CLI gh lo supporta) per feedback ancora più puntuale.
• Controllo con label PR: Esegui solo quando un maintainer aggiunge un label ai-review, o aggiungi automaticamente un label needs-attention se compaiono riscontri ad alta priorità.

Results so far

• Cicli di revisione più brevi su cambiamenti semplici.
• Diff più puliti perché i contributori correggono problemi minori prima che li veda un umano.
• Onboarding migliore: i nuovi membri ottengono consigli concreti che riflettono cosa direbbero i revisori senior.
• Nessun dramma: se il bot non ha nulla da aggiungere, sta zitto.

Niente di tutto ciò sostituisce un umano che approva un merge. È un filtro leggero che si ripaga dal primo giorno.