Lasciare che un LLM revisioni le nostre pull request (così non devi farlo tu)

Amiamo l’automazione. La usiamo per alimentare la nostra infrastruttura, per scalare i carichi di lavoro fino a zero e—sempre più spesso—per ridurre la quantità di attenzione umana necessaria per consegnare codice di alta qualità. Un ambito che restava ostinatamente manuale erano le review delle pull request. Tra Cursor come IDE, ChatGPT/Codex per il prototipaggio e gemini-cli per controlli rapidi, i nostri flussi locali erano veloci—ma la CI continuava a dipendere da un umano.

Ci siamo quindi posti una domanda semplice: potevamo permettere a un modello di linguaggio di leggere il diff, individuare problemi e commentare direttamente la PR?

Risultato: sì. Sono bastate poche righe di “colla” in GitHub Actions per ottenere revisioni utili e strutturate su ogni pull request.

L’obiettivo

Non cercavamo di sostituire gli esseri umani. Volevamo un primo passaggio che:

• leggesse il diff reale di una PR (non l’intero repo),
• evidenziasse errori evidenti e cambi rischiosi,
• suggerisse piccoli refactor o test mancanti,
• classificasse i riscontri per priorità,
• e pubblichi i risultati dove già li guardiamo: nella conversazione della PR e nel riepilogo delle Actions.

Se una modifica va bene, vogliamo che il bot lo dica semplicemente e si tolga di mezzo.

Gli strumenti nel nostro stack

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

Il flusso di lavoro, end to end

Ecco l’Action completa che eseguiamo. 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.

Cosa fa ogni parte

• Checkout con fetch-depth: 0 così possiamo fare il diff rispetto al branch base della PR in modo affidabile.

• Toolchain Rust installa rustfmt e clippy perché i nostri repository spesso contengono codice Rust; quelli girano altrove nella pipeline, ma impostare la toolchain qui evita sorprese.

• Node è necessario per il gemini-cli.

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

• Creiamo un file diff:

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

  Questo garantisce che il modello veda solo le modifiche in revisione.

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

• Applichiamo la review al Job Summary ($GITHUB_STEP_SUMMARY) così è visibile nell’interfaccia delle Actions.

• Comentiamo la PR usando gh pr comment … --body-file review.md.

Il prompt che lo rende utile

Gli output degli LLM sono buoni quanto le istruzioni. Il nostro mantiene le cose pratiche:

• Ambito: Revisiona solo ciò che è cambiato. Non ridocumentare il repository.
• Segnale: Di’ “looks good” quando non c’è nulla da aggiungere. Niente creatività forzata.
• Attuabilità: Includi sempre file + numero di riga per i riscontri.
• Priorità: Raggruppa per basso / medio / alto per aiutare i revisori a scansionare rapidamente.
• Formato: Solo Markdown, così si incolla pulito nei commenti PR e rende bene nel riepilogo.

Abbiamo iterato un po’ per arrivarci. Le modifiche più influenti sono state: insistere sulle referenze file/linea e vietare prose extra.

Come appare la revisione

Su una PR tipica, vediamo sezioni come:

• High: Cambiamenti sensibili alla sicurezza, gestione degli errori rotta, mancanza di validazione degli input, segreti accidentali o test rimossi.
• Medium: Casi limite, rischi di concorrenza, messaggi di errore discutibili, Rust/Go/TS non idiomatici che potrebbero creare problemi in futuro.
• Low: Nomi, commenti, piccoli refactor o suggerire un breve test per fissare un comportamento.

Se tutto va bene, otteniamo una riga: “Looks good.” Perfetto—è esattamente ciò che vogliamo.

Avvertenze e note pratiche

• Segreti: Hai bisogno di GEMINI_API_KEY e GITHUB_TOKEN nei segreti del repo o dell’organizzazione. Mantieni gli scope ristretti. L’Action imposta permissions: write-all perché pubblica un commento; limita questo se la tua policy lo richiede.
• Sorgente del diff: Per merge complessi, git diff origin/${{ github.base_ref }} dà il contesto giusto. Se il tuo workflow scarica solo il commit di merge, assicurati che il branch base sia disponibile o aggiusta su github.event.pull_request.base.sha.
• Fork: Se accetti PR da fork, rivedi come gestisci i segreti. Potresti voler eseguire questo su pull_request_target con attenta hardening, o porre la review dietro a etichette.
• Controllo del rumore: Abbiamo trovato utile lasciare che il modello non dica altro oltre a “looks good” quando una modifica è banale. Solo questo riduce l’affaticamento dei revisori.
• Costi e quote: Le chiamate al modello non sono gratuite. Limitiamo la dimensione del diff che inviamo ed eseguiamo questo solo su pull_request (non ad ogni push).
• Privacy: Stai inviando il tuo diff a un provider di modelli esterno. Se il tuo codice è sensibile o soggetto a restrizioni all’esportazione, valuta il rischio e scegli un provider/modello di deployment che soddisfi i requisiti di compliance.

Perché è importante (oltre la comodità)

Le revisioni automatiche rendono gli esseri umani più selettivi con la loro attenzione. Diminuiamo il tempo speso su “rinomina questa variabile” e lo rivediamo su architettura, flussi di dati e confini di sicurezza. Questo significa:

• Cicli di feedback più rapidi per i contributori.
• Meno iterazioni di review su dettagli minuti.
• Una storia dei commit più pulita con problemi intercettati prima.
• Più tempo per il lavoro di sostenibilità che conta davvero—come ridurre i watt di un servizio o diminuire l’egress di rete.

È anche sorprendentemente efficace per la coerenza. Un LLM non dimenticherà il pattern concordato di gestione degli errori tra i servizi o la nostra struttura di logging preferita; applica quei controlli in modo uniforme su ogni PR.

Variazioni che potresti provare

Questo schema funziona con quasi qualsiasi modello o CLI. Alcune estensioni semplici:

• Voto multi-modello: Interroga due modelli con lo stesso prompt e conserva solo i riscontri su cui concordano.
• Passaggi specifici per lingua: Se il tuo repo mescola linguaggi, esegui prompt specifici per lingua (es. uno ottimizzato per Rust con suggerimenti di clippy, uno per TypeScript).
• Gate “Fail on High”: Usa un piccolo parser per rilevare una sezione “High” e far fallire il job per bloccare i merge fino alla risoluzione.
• Review inline: Converte i riferimenti file/riga in commenti di review su GitHub (la CLI gh lo supporta) per feedback ancora più mirati.
• Controllo etichette PR: Esegui solo quando un manutentore aggiunge l’etichetta ai-review, o aggiungi automaticamente needs-attention quando compaiono riscontri ad alta priorità.

Risultati finora

• Cicli di review più brevi su modifiche semplici.
• Diff più puliti perché i contributori correggono elementi triviali prima che un umano guardi.
• Migliore onboarding: i nuovi membri ottengono consigli concreti che rispecchiano ciò che direbbero i revisori senior.
• Niente drama: se il bot non ha nulla da aggiungere, resta silenzioso.

Niente di tutto questo sostituisce l’approvazione umana di un merge. È un filtro leggero che si ripaga già dal primo giorno.