Dejando que un LLM revise nuestros pull requests (para que tú no tengas que hacerlo)

Nos encanta la automatización. La usamos para potenciar nuestra infraestructura, para escalar cargas de trabajo hasta cero y —cada vez más— para reducir la atención humana necesaria para entregar código de alta calidad. Un lugar que aún parecía terco y manual eran las revisiones de pull requests. Entre Cursor como nuestro IDE, ChatGPT/Codex para prototipos y gemini-cli para revisiones rápidas, nuestros flujos locales eran veloces—pero la CI todavía esperaba por un humano.

Así que hicimos una pregunta sencilla: ¿podríamos dejar que un modelo de lenguaje grande lea el diff, detecte problemas y comente directamente en el PR?

Resulta que: sí. Solo tomó unas pocas líneas de pegamento en GitHub Actions para obtener revisiones estructuradas y útiles en cada pull request.

The goal

No queríamos reemplazar humanos. Queríamos un primer filtro que:

• lea el diff real de un PR (no todo el repositorio),
• señale errores evidentes y cambios riesgosos,
• sugiera pequeñas refactorizaciones o pruebas faltantes,
• categorice los hallazgos por prioridad,
• y publique los resultados justo donde ya miramos: en la conversación del PR y en el resumen de Actions.

Si un cambio está bien, queremos que el bot simplemente lo diga y se haga a un lado.

The tools in our stack

• GitHub Actions para orquestación de CI.
• Cursor (nuestro IDE diario).
• ChatGPT/Codex para ideación y revisiones rápidas off-line.
• @google/gemini-cli dentro de CI para ejecutar el paso de revisión automatizada.
• El GitHub CLI (gh) para comentar en el PR.
• Un ingrediente pequeño pero importante: un prompt que dirige al modelo a producir retroalimentación útil y accionable.

The workflow, end to end

Aquí está la Action completa que estamos ejecutando. Colócala en .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 para poder hacer diff con la rama base del PR de manera fiable.

• Rust toolchain instala rustfmt y clippy porque nuestros repos a menudo incluyen código Rust; esos se ejecutan en otra parte de nuestro pipeline, pero mantener la configuración aquí evita sorpresas.

• Node es requerido para gemini-cli.

• Instalamos @google/gemini-cli globalmente dentro del runner.

• Creamos un archivo diff:

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

  Esto asegura que el modelo vea solo los cambios en revisión.

• Pipeteamos el prompt hacia gemini (la CLI lee @pr.diff inline como referencia de archivo) y capturamos la salida markdown del modelo en review.md.

• Añadimos la revisión al Resumen del Job ($GITHUB_STEP_SUMMARY) para que sea visible en la UI de Actions.

• Comentamos en el PR usando gh pr comment … --body-file review.md.

The prompt that makes it useful

Los outputs del LLM son tan buenos como las instrucciones. El nuestro mantiene las cosas prácticas:

• Alcance: Solo revisa lo que cambió. No documentes el repositorio entero.
• Señal: Di “looks good” cuando no haya nada que agregar. Sin creatividad forzada.
• Accionabilidad: Incluye siempre archivo + número de línea para los hallazgos.
• Prioridades: Agrupa en baja / media / alta para ayudar a los revisores a escanear rápido.
• Formato: Solo Markdown, para que se pegue limpio en comentarios de PR y se renderice bien en el resumen.

Iteramos un poco para llegar a esto. Los ajustes más impactantes fueron: insistir en referencias de archivo/línea y prohibir prosa adicional.

What the review looks like

En un PR típico, vemos secciones como:

• Alta: Cambios sensibles en seguridad, manejo de errores roto, validación de entrada faltante, secretos accidentales o pruebas removidas.
• Media: Casos límite, riesgos de concurrencia, mensajes de error cuestionables, Rust/Go/TS no idiomáticos que podrían causar problemas luego.
• Baja: Nombres, comentarios, pequeñas refactorizaciones o sugerencias de pruebas breves para asegurar un comportamiento.

Si todo está bien, recibimos una línea: “Looks good.” Perfecto—eso es exactamente lo que queremos.

Gotchas and practical notes

• Secrets: Necesitas GEMINI_API_KEY y GITHUB_TOKEN en secretos del repo u organización. Mantén alcances estrictos. La Action establece permissions: write-all porque publica un comentario; restríngelo si tu política lo requiere.
• Fuente del diff: Para merges complejos, git diff origin/${{ github.base_ref }} da el contexto correcto. Si tu flujo solo obtiene el commit de merge, asegúrate que la rama base esté disponible o ajusta a github.event.pull_request.base.sha.
• Forks: Si aceptas PRs de forks, revisa cómo manejas secretos. Quizá quieras correr esto en pull_request_target con cuidado y endurecimiento, o guardar la revisión detrás de etiquetas.
• Control de ruido: Nos resultó útil permitir que el modelo no diga nada más que “looks good” cuando un cambio es trivial. Eso solo reduce la fatiga del revisor.
• Costos y cuotas: Las llamadas al modelo no son gratis. Limitamos el tamaño del diff que enviamos y solo ejecutamos esto en pull_request (no en cada push).
• Privacidad: Estás enviando tu diff a un proveedor externo. Si tu código es sensible o tiene restricciones de exportación, evalúa riesgos y elige un proveedor/despliegue que cumpla con tus necesidades de cumplimiento.

Why this matters (beyond convenience)

Las revisiones automatizadas hacen que los humanos sean más selectivos con su atención. Pasamos menos tiempo en “renombrar esta variable” y más en arquitectura, flujos de datos y límites de seguridad. Eso significa:

• Ciclos de retroalimentación más rápidos para colaboradores.
• Menos rondas de revisión por detalles menores.
• Un historial de commits más limpio con problemas detectados temprano.
• Más tiempo para el trabajo de sostenibilidad que realmente importa—como ahorrar watts en un servicio o reducir egress de red.

También es sorprendentemente bueno para la consistencia. Un LLM no olvidará el patrón acordado de manejo de errores entre servicios o nuestra estructura preferida de logs; aplica esos controles uniformemente en cada PR.

Variations you might try

Este patrón funciona con casi cualquier modelo o CLI. Algunas extensiones fáciles:

• Votación multmodelo: Llama a dos modelos con el mismo prompt y mantén solo los hallazgos en que coincidan.
• Pasadas conscientes del lenguaje: Si tu repo mezcla lenguajes, ejecuta prompts específicos por lenguaje (ej., uno ajustado para Rust con sugerencias de clippy, otro para TypeScript).
• Puertas de “Fallar en Alta”: Usa un pequeño parser para detectar una sección “Alta” y marcar el job como failed para bloquear merges hasta resolver.
• Revisión inline: Convierte referencias archivo/línea en comentarios de revisión en GitHub (el CLI gh lo soporta) para feedback aún más directo.
• Control por etiquetas de PR: Solo corre cuando un mantenedor añade una etiqueta ai-review, o añade automáticamente una etiqueta needs-attention cuando aparecen hallazgos de alta prioridad.

Results so far

• Ciclos de revisión más cortos en cambios sencillos.
• Diffs más limpios porque los colaboradores arreglan temas simples antes de que un humano mire.
• Mejor onboarding: los nuevos reciben consejos concretos que reflejan lo que dirían revisores senior.
• Sin drama: si el bot no tiene nada que añadir, se mantiene callado.

Nada de esto reemplaza la aprobación humana para un merge. Es un filtro ligero que se paga a sí mismo desde el primer día.