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 a 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 se sentía obstinadamente 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 rápidos, pero la CI aún esperaba a un humano.

Así que nos hicimos una pregunta simple: ¿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 útiles y estructuradas en cada pull request.

The goal

No intentábamos reemplazar a los humanos. Queríamos un primer filtro que:

• lea el diff real de un PR (no todo el repositorio),
• señale errores obvios y cambios riesgosos,
• sugiera refactorizaciones pequeñas o pruebas faltantes,
• categorice los hallazgos por prioridad,
• y publique resultados justo donde ya miramos: en la conversación del PR y 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 orquestar la CI.
• Cursor (nuestro IDE diario).
• ChatGPT/Codex para ideación y revisiones rápidas offline.
• @google/gemini-cli dentro de la 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 guía al modelo para producir feedback útil y accionable.

The workflow, end to end

Aquí está la Action completa que estamos ejecutando. Ponla 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 comparar con la rama base del PR de manera fiable.

• El toolchain de Rust instala rustfmt y clippy porque nuestros repositorios suelen incluir código Rust; estos se ejecutan en otras partes de la pipeline, pero mantener la configuración aquí evita sorpresas.

• Node es necesario 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 bajo revisión.

• Canalizamos el prompt a gemini (la CLI lee @pr.diff en línea como referencia de archivo) y capturamos la salida en markdown en review.md.

• Adjuntamos 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

Las salidas de los LLM solo son tan buenas como las instrucciones. Las nuestras se mantienen prácticas:

• Alcance: Revisa solo lo que cambió. No documentes de nuevo el repositorio.
• Señal: Di “looks good” cuando no haya nada que añadir. 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 del PR y renderice bien en el resumen.

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

What the review looks like

En un PR típico, vemos secciones como:

• Alta: Cambios sensibles en seguridad, manejo roto de errores, validación de input faltante, secretos accidentales o tests eliminados.
• 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, refactorizaciones pequeñas o sugerencias de pruebas cortas para fijar 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 los secretos del repositorio u organización. Mantén los permisos ajustados. La Action usa permissions: write-all porque publica un comentario; restringe esto si tu política lo requiere.
• Fuente del diff: Para merges complejos, git diff origin/${{ github.base_ref }} da el contexto correcto. Si tu workflow solo trae el commit mergeado, asegúrate que la rama base esté disponible o ajusta a github.event.pull_request.base.sha.
• Forks: Si aceptas PRs desde forks, revisa cómo manejas secretos. Quizá quieras correr esto en pull_request_target con endurecimiento cuidadoso, o condicionar la revisión por etiquetas.
• Control de ruido: Nos fue útil dejar que el modelo no diga nada más que “looks good” cuando el 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 y ejecutamos solo 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 proveedor/modelo de despliegue que cumpla tus normativas.

Why this matters (beyond convenience)

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

• Ciclos de retroalimentación más rápidos para contribuyentes.
• Menos ciclos de revisión por nimiedades.
• Un historial de commits más limpio con problemas detectados antes.
• Más tiempo para trabajo de sostenibilidad que realmente importa—como reducir consumo de energía o egress de red.

También es sorprendentemente bueno en consistencia. Un LLM no olvida el patrón acordado de manejo de errores entre servicios ni nuestra estructura preferida de logs; aplica esas revisiones de modo uniforme en cada PR.

Variations you might try

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

• Votación multi-modelo: Llama a dos modelos con el mismo prompt y conserva solo hallazgos coincidentes.
• Pasadas específicas por idioma: Si tu repo mezcla lenguajes, corre prompts específicos (p.ej., uno afinado para Rust con sugerencias de clippy, otro para TypeScript).
• Puertas “Fail on High”: Usa un pequeño parser para detectar sección “Alta” y marcar el job como failed para bloquear merges hasta corregir.
• Revisión inline: Convierte referencias de archivo/línea en comentarios de revisión de GitHub (el CLI gh lo soporta) para feedback aún más directo.
• Control por etiqueta en PR: Ejecuta solo si un mantenedor agrega etiqueta ai-review, o añade automáticamente needs-attention si hay hallazgos de alta prioridad.

Results so far

• Ciclos de revisión más cortos en cambios directos.
• Diffs más limpios porque los contribuyentes corrigen detalles fáciles antes de que un humano los vea.
• Mejor incorporación: los nuevos obtienen consejos concretos que reflejan lo que dirían los revisores senior.
• Sin dramas: si el bot no tiene nada que añadir, permanece en silencio.

Nada de esto reemplaza que un humano apruebe un merge. Es un filtro ligero que se paga solo desde el primer día.