Far revisionare le nostre Pull Request da un LLM (così non dovrai farlo tu)

Amiamo l’automazione. La utilizziamo per alimentare la nostra infrastruttura, per scalare i carichi di lavoro fino a zero e—sempre di più—per ridurre la quantità di attenzione umana necessaria per rilasciare codice di alta qualità. Un aspetto che sembrava ancora ostinatamente manuale erano le revisioni delle pull request. Tra Cursor come nostro IDE, ChatGPT/Codex per prototipazione, 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 di grandi dimensioni leggesse il diff, individuasse problemi, e commentasse direttamente sulla PR?

Risultato: sì. Sono bastate poche righe di “colla” 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 reale di una PR (non l’intero repo),
• evidenziasse errori ovvi e cambiamenti rischiosi,
• suggerisse piccoli refactor o test mancanti,
• categorizzasse i risultati per priorità,
• e pubblicasse i risultati esattamente dove già guardiamo: nella conversazione della PR e nel sommario di Actions.

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

The tools in our stack

• GitHub Actions per l’orchestrazione della CI.
• Cursor (il nostro IDE quotidiano).
• ChatGPT/Codex per idee e rapide revisioni offline.
• @google/gemini-cli dentro la CI per eseguire il passaggio di revisione automatica.
• Il 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 ramo base della PR.

• Toolchain Rust installa rustfmt e clippy perché i nostri repo spesso includono codice Rust; questi vengono eseguiti altrove nella pipeline, ma mantenere la setup qui evita sorprese.

• Node è necessario per il gemini-cli.

• Installiamo @google/gemini-cli globalmente dentro il runner.

• Creiamo un file diff:

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

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

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

• Aggiungiamo la revisione al Sommario del Job ($GITHUB_STEP_SUMMARY) così è visibile nell’interfaccia di Actions.

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

The prompt that makes it useful

Gli output LLM sono validi quanto le istruzioni. Il nostro mantiene tutto pratico:

• Scope: Rivedi solo ciò che è cambiato. Non documentare di nuovo il repository.
• Segnale: Dì “looks good” quando non c’è nulla da aggiungere. Niente creatività forzata.
• Azione: Includi sempre file + numeri di linea per i risultati.
• Priorità: Raggruppa per bassa / media / alta per aiutare i revisori a scansionare rapidamente.
• Formato: Solo Markdown, così si incolla pulito nei commenti PR e si rende bene nel sommario.

Abbiamo iterato un po’ per arrivarci. Le modifiche più impattanti sono state insistere sui riferimenti a file/linee e vietare prose aggiuntive.

What the review looks like

In una PR tipica, vediamo sezioni come:

• High: Cambiamenti sensibili alla sicurezza, gestione errori rotta, validazione input mancante, segreti accidentali, o test rimossi.
• Medium: Casi limite, rischi di concorrenza, messaggi d’errore discutibili, Rust/Go/TS non idiomatici che potrebbero causare problemi in seguito.
• Low: Nomi, commenti, piccoli refactor, o suggerimenti per test brevi per bloccare un comportamento.

Se tutto va bene, riceviamo una riga: “Looks good.” Perfetto—è esattamente quello che vogliamo.

Gotchas and practical notes

• Secrets: Serve GEMINI_API_KEY e GITHUB_TOKEN nei segreti del repo o dell’organizzazione. Mantieni gli scope limitati. L’Action imposta permissions: write-all perché pubblica commenti; restringi questo se la tua policy lo richiede.
• Fonte diff: Per merge complessi, git diff origin/${{ github.base_ref }} dà il contesto corretto. Se il tuo workflow recupera solo il commit di merge, assicurati che il ramo base sia disponibile o usa github.event.pull_request.base.sha.
• Fork: Se accetti PR da fork, valuta come gestire i segreti. Potresti voler eseguire questo su pull_request_target con un hardening attento, o limitare la revisione tramite label.
• Controllo rumore: Abbiamo trovato utile lasciare che il modello non dica altro oltre a “looks good” se la modifica è banale. Solo questo abbassa la fatica dei revisori.
• Costi e quote: Le chiamate modello non sono gratis. Limitiamo la dimensione del diff inviato e facciamo girare questo solo su pull_request (non a ogni push).
• Privacy: Stai inviando il diff a un provider di modelli esterno. Se il tuo codice è sensibile o soggetto a restrizioni di esportazione, valuta il rischio e scegli provider/modello di deployment che rispettino le tue esigenze di compliance.

Why this matters (beyond convenience)

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

• Feedback più veloci per i contributori.
• Meno cicli di revisione su dettagli superflui.
• Una storia dei commit più pulita con problemi catturati prima.
• Più tempo per il lavoro di sostenibilità a cui teniamo davvero—come ridurre i watt di un servizio o diminuire l’egress di rete.

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

Variations you might try

Questo schema funziona con quasi tutti i modelli o CLI. Alcune estensioni facili:

• Voto multi-modello: Chiama due modelli con lo stesso prompt e conserva solo i risultati su cui concordano.
• Passaggi specifici per lingua: Se il repo mescola linguaggi, esegui prompt specifici per lingua (es. uno ottimizzato per Rust con suggerimenti clippy, uno per TypeScript).
• Blocchi “Fail on High”: Usa un piccolo parser per individuare una sezione “High” e impostare il job su failed per bloccare i merge fino alla risoluzione.
• Revisione inline: Trasforma i riferimenti a file/linea in commenti di revisione GitHub (supportato da CLI gh) per feedback ancora più puntuali.
• Controllo tramite label PR: Esegui solo quando un manutentore aggiunge la label ai-review, oppure aggiungi automaticamente una label needs-attention se appaiono rilevazioni ad alta priorità.

Results so far

• Cicli di revisione più brevi su modifiche semplici.
• Diff più puliti perché i contributori sistemano gli aspetti più semplici prima che un umano guardi.
• Onboarding migliore: nuovi membri ricevono consigli concreti che rispecchiano quelli dei revisori senior.
• Nessun dramma: se il bot non ha nulla da aggiungere, resta silenzioso.

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