Revisión de código con IA: Claude Code en GitHub Actions

La ventaja está en quién tiene que seguir pendiente del proceso. Antes, un desarrollador debía abrir el repositorio, iniciar Claude, llevar el resultado a GitHub y mantener activa la sesión local. Con una acción, la persona responsable del repositorio deja una solicitud bien delimitada y vuelve para encontrar un comentario o una propuesta de cambio. El trabajo puede empezar fuera del horario de ese desarrollador; revisar el resultado sigue requiriendo tiempo.

Esta guía se basa en la documentación vigente de Anthropic, consultada el 15 de octubre de 2026. El flujo de trabajo que aparece más abajo es una configuración inicial con restricciones deliberadas; no implica que cualquier incidencia pueda resolverse sin supervisión.

Revisión de código con IA: un asistente de guardia para el repositorio

Piensa en la aplicación de GitHub como una credencial de acceso, en el flujo de trabajo como una orden de trabajo y en el runner como una estación de trabajo temporal. Un flujo de trabajo es el archivo de configuración que indica a GitHub cuándo debe empezar; el runner es la máquina que lo ejecuta.

La acción puede responder a menciones en incidencias y pull requests. Si se le proporciona un prompt, pasa a funcionar como una tarea automática. Para un equipo pequeño, las solicitudes explícitas son la forma más sencilla de descubrir tareas útiles antes de pagar por una revisión en cada cambio. Uso de la acción.

Instala la aplicación e integra el flujo de trabajo

Para usar la instalación guiada necesitas acceso de administrador al repositorio. Autentica la CLI de GitHub ya instalada con gh auth login, abre claude dentro del repositorio y ejecuta /install-github-app. Elige los flujos de trabajo y la autenticación mediante clave de API o suscripción; después, crea e integra la PR preparada con el flujo de trabajo. La instalación se hace en tu equipo; las ejecuciones posteriores tienen lugar en GitHub. Configuración rápida oficial.

La instalación manual lleva al mismo resultado:

1. Instala la aplicación Claude para GitHub en el repositorio elegido.
2. Abre Settings → Secrets and variables → Actions en el repositorio y añade uno de los secretos de autenticación de la siguiente tabla.
3. Copia el ejemplo funcional de Anthropic en .github/workflows/claude.yml, selecciona el parámetro de autenticación correspondiente e integra el archivo.
4. Deja un comentario que incluya @claude y una solicitud concreta.

Estos son los pasos oficiales de configuración manual, con la elección de credenciales indicada de forma explícita. Guía de configuración de la acción.

Para autenticarte con la suscripción, ejecuta claude setup-token en tu equipo y guarda el resultado como secreto. Anthropic documenta este método para los planes Pro, Max, Team y Enterprise. El token generado dura un año, así que asigna a alguien la responsabilidad de renovarlo. Autenticación con token.

La credencial determina la facturación: las ejecuciones con clave de API se facturan por la API; las que usan un token OAuth consumen tu suscripción de Claude. El uso de los runners de GitHub Actions se contabiliza por separado. El token de suscripción pertenece a la persona que lo generó; Anthropic recomienda una clave de API para los secretos compartidos entre repositorios. Autenticación y costos.

La configuración predeterminada con la aplicación no necesita un token de acceso personal de GitHub. El acceso a GitHub y la autenticación de Claude son cosas distintas: la aplicación proporciona el primero y el secreto elegido, la segunda. Parámetros de autenticación.

Empieza con un flujo sencillo que responda a menciones

Usa esta configuración en repositorios de equipos de confianza y para cambios pequeños en archivos. Permite leer y editar archivos, además de crear commits mediante la API de GitHub. Claude no dispone de una herramienta de shell, por lo que no puede ejecutar tus comandos de pruebas con esta configuración. Deja esa tarea a tu CI habitual: las comprobaciones automáticas que se ejecutan sobre los cambios propuestos.

Guarda lo siguiente en .github/workflows/claude.yml. Las referencias a las acciones, actions/checkout@v6 y anthropics/claude-code-action@v1, aparecen en el ejemplo vigente de Anthropic. El límite de cinco turnos y el tiempo máximo de quince minutos son decisiones para empezar, no valores predeterminados de Anthropic. Flujo de trabajo oficial.

name: Claude on request
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    timeout-minutes: 15
    concurrency:
      group: claude-small-team
      cancel-in-progress: false
    permissions:
      contents: write
      issues: write
      pull-requests: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          use_commit_signing: true
          claude_args: |
            --max-turns 5
            --tools "Read,Glob,Grep,Edit,Write"
            --disallowedTools "Bash,WebFetch,WebSearch"

Para facturar mediante la suscripción, sustituye la línea anthropic_api_key por claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}. Utiliza solo uno de los dos métodos. Conserva id-token: write, necesario para la autenticación predeterminada con la aplicación de GitHub. Flujo de trabajo y autenticación oficiales, referencia de parámetros.

Cada control cumple una función distinta:

• --tools selecciona las herramientas integradas que puede usar Claude. Read, Glob y Grep inspeccionan archivos; Edit y Write los modifican. No restringe las herramientas MCP, conectadas por separado, que la acción utiliza para comunicarse con GitHub.
• --allowedTools concede permiso para usar las herramientas indicadas sin pedir confirmación. No constituye una lista completa de las únicas herramientas permitidas. Aquí, la línea explícita --disallowedTools bloquea las herramientas de shell y de acceso web.
• --max-turns limita las iteraciones de trabajo del agente. No fija un máximo de tokens ni de dólares, y alcanzar el límite puede terminar la ejecución con un error y dejar el trabajo sin acabar. Referencia de la CLI.

use_commit_signing: true hace que los commits se creen mediante la API de GitHub. Así, esta configuración puede guardar cambios sin dar a Claude acceso a comandos git a través de la shell. No necesita ningún secreto de firma adicional. Las herramientas de GitHub de la acción siguen disponibles, por lo que esta configuración permite escribir cambios. Firma de commits, implementación de la acción.

El grupo de concurrencia fijo permite que solo se ejecute una tarea de este flujo a la vez en cada repositorio. Con el comportamiento predeterminado de la cola, una nueva solicitud pendiente puede reemplazar a otra anterior que también esté pendiente; no es una cola de tareas persistente. El tiempo máximo limita la duración total de la tarea, incluida la preparación. Concurrencia en GitHub, sintaxis de los flujos de trabajo.

Prueba con @claude review this PR for missing permission checks; report findings without changing files. Para una incidencia, prueba con @claude fix the null handling described above, change only the parser and its regression test, and state which checks were not run.

De forma predeterminada, quien inicia la ejecución necesita acceso de escritura al repositorio y los bots están bloqueados. Al solicitar la corrección de una incidencia, el resultado esperado es una rama y un enlace para que una persona cree la PR. Deja clara esa diferencia en las instrucciones del equipo. Seguridad de la acción.

Activa las revisiones automáticas después de la prueba inicial

Para revisar PR de forma automática, selecciona el flujo de revisión durante la configuración con /install-github-app. Su plugin de revisión de código usa --comment y el permiso para la herramienta de comentarios que se muestra a continuación para publicar los hallazgos. Ejemplo oficial de revisión.

En ese flujo de revisión independiente, los parámetros de la acción incluyen:

plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
plugins: "code-review@claude-code-plugins"
prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
claude_args: >-
  --max-turns 5
  --allowedTools "mcp__github_inline_comment__create_inline_comment"

Usa esos parámetros dentro del flujo oficial de pull_request, no en el flujo por menciones anterior. Conserva su paso de checkout, la autenticación y los permisos de la tarea, añade un tiempo máximo y excluye las PR procedentes de forks con if: github.event.pull_request.head.repo.full_name == github.repository. Considera el límite de turnos como un ajuste para la prueba piloto: una revisión que agota sus turnos queda incompleta. La skill de revisión documentada también omite algunas PR, incluidas las que están en borrador.

Distingue el alcance de la instalación del acceso a herramientas

Empieza por instalar la aplicación solo en los repositorios elegidos. La aplicación oficial de Claude comparte permisos entre varias funciones de Claude, y GitHub no permite aceptar solo una parte de ese conjunto. Un bloque permissions reducido en el YAML no limita el alcance de la instalación de la aplicación. Modelo de permisos de la aplicación.

Si esa instalación concede demasiado acceso, sigue el método de la aplicación personalizada con permisos sobre Contents, Issues y Pull requests. Este método añade los secretos APP_ID y APP_PRIVATE_KEY, además de un paso que crea un token de la aplicación y lo pasa como github_token. Para los equipos que quieran eliminar las claves de API estáticas de Claude, la guía de configuración también documenta la federación de identidades de cargas de trabajo: intercambia la identidad de la tarea de GitHub por acceso de corta duración a la API. Configuración de una aplicación personalizada y de la federación.

Añade un CLAUDE.md breve con las prioridades de revisión, las áreas donde se permiten cambios y las pruebas que debe aportar una corrección. Las instrucciones orientan el trabajo; los permisos del repositorio y las restricciones de herramientas hacen cumplir los límites de acceso. Antes de habilitar ejecuciones sin supervisión, revisa los hooks configurados —comandos que se ejecutan automáticamente en eventos del ciclo de vida— y los servidores de herramientas adicionales. Instrucciones del proyecto. Nuestra reseña de Claude Code amplía la evaluación de la herramienta, y la guía de comandos de barra explica los comandos usados durante la configuración.

Seis tareas que conviene delegar, por orden

Empieza por las tareas cuya solicitud sea fácil de describir y cuyo resultado sea fácil de comprobar. Son propuestas de flujos de trabajo, no ahorros medidos ni garantías.

La configuración inicial no puede instalar dependencias ni ejecutar una batería de pruebas. Si la tarea lo necesita, añade una configuración de ejecución para código de confianza que se haya revisado por separado, con permisos para comandos específicos y límites propios. Un comando de pruebas permitido sigue ejecutando código del repositorio; que su nombre parezca inofensivo no hace seguro ese código.

Resuelve estos fallos antes de añadir más disparadores

Las PR de forks pueden quedarse sin acceso a los secretos. GitHub normalmente no entrega secretos a las ejecuciones de pull_request y pull_request_review_comment activadas desde forks. Que la credencial de Claude esté vacía en esas tareas responde a un límite de confianza. No cambies a pull_request_target para ejecutar el código del fork solo con el fin de obtener secretos. Una tarea de issue_comment iniciada por alguien responsable del repositorio también puede disponer de secretos, así que confiar en quien comenta no convierte los archivos de la PR en código de confianza. Guía de seguridad de GitHub para forks.

Los límites de herramientas no neutralizan el código de inicio del proyecto. La acción restaura determinadas partes de la configuración de Claude desde la rama base, pero los scripts y otros archivos del proyecto pueden seguir procediendo de la PR. Audita los hooks y la configuración de los servidores de herramientas, además de las herramientas permitidas a Claude. Límites de confianza de la acción.

El tiempo de los runners sigue siendo una restricción aparte. Los runners estándar alojados por GitHub son gratuitos para repositorios públicos. Los repositorios privados tienen cuotas incluidas en el plan y cargos por exceso de uso; si se agota la cuota y no hay un método de pago, las tareas pueden detenerse. Consulta la página de uso de Actions junto con el consumo de Claude. Facturación de GitHub Actions.

Los límites de uso pueden interrumpir un flujo válido. Los límites de la API abarcan las solicitudes y los tokens de entrada y salida —los fragmentos de texto que procesa el modelo— por minuto. Si recibes un 429 con retry-after, espera antes de reintentar y reduce las tareas simultáneas. Un 429 por alcanzar el límite de gasto del nivel, sin esa cabecera, exige resolver la facturación o el límite; volver a ejecutar una y otra vez no lo soluciona. La autenticación mediante suscripción sigue sujeta a los límites de uso del plan. Límites de la API, límites de uso de Claude.

Un bot que no responde y una CI que no se ejecuta son fallos distintos. Si no hay respuesta, comprueba que el flujo existe en la rama predeterminada, que Actions está habilitado, que el secreto corresponde al parámetro elegido y que quien comenta tiene acceso de escritura. Usa la mención completa @claude. Si el problema está en la CI posterior, comprueba si alguien sustituyó la autenticación de la aplicación por github_token: ${{ secrets.GITHUB_TOKEN }}: GitHub suprime muchos eventos creados con ese token y algunos flujos de PR requieren aprobación. Comportamiento del token de GitHub.

Dos servicios que podrían construirse sobre este flujo

La oportunidad más sólida es ofrecer una configuración de revisiones gestionada para equipos pequeños. El cliente sería una persona al frente de ingeniería que busca hallazgos útiles, responsabilidades claras y límites operativos previsibles. Las estimaciones de DataForSEO para búsquedas en inglés en Estados Unidos, consultadas el 15 de octubre de 2026, sitúan “ai code review” en 1,300 búsquedas mensuales. Es una señal de interés, no un recuento de clientes. Una primera versión comercial podría configurar un repositorio, plasmar sus prioridades de revisión en instrucciones, evaluar los hallazgos con PR históricas y proporcionar un informe continuo de uso y fallos. La dificultad está en el desgaste que provocan los falsos positivos: el trabajo sostenido consiste en mantener la calidad de las revisiones a medida que cambia el código. Un producto que se limite a envolver un prompt genérico ofrece pocos motivos para seguir usándolo.

Una agencia podría comprar un paquete reutilizable de políticas de revisión para los repositorios de sus clientes. DataForSEO estima 590 búsquedas mensuales para “ai code review tools” y 140 para “github ai code review” en el mismo mercado. El producto mínimo podría combinar un flujo reutilizable, plantillas de instrucciones específicas para cada cliente, registros de quién es responsable de las credenciales y comprobaciones que detecten la ausencia de límites. Podría ayudar a la agencia a mantener configuraciones coherentes cuando cambia el equipo responsable. La dificultad es que los permisos y el entorno de pruebas varían entre clientes; una plantilla necesita mantenimiento y evaluación para seguir siendo útil. Las audiencias de estas consultas se solapan, así que sus volúmenes no deben sumarse para calcular el tamaño del mercado.

Elige dónde ejecutar el trabajo según la tarea

Elige GitHub Actions cuando el trabajo responda a un evento del repositorio y el equipo quiera gestionar la configuración, los permisos y los registros junto con su CI. Elige una sesión en la nube para una tarea puntual que quieras iniciar y dirigir desde el navegador con la computadora portátil cerrada. Elige una rutina programada para una tarea recurrente guardada, como revisar cada noche el trabajo pendiente, si prefieres que Claude aloje la programación y la configuración en lugar de mantener un YAML de flujo de trabajo. Las rutinas también admiten disparadores de GitHub y de API, por lo que necesitar una programación no obliga a usar Actions; las rutinas siguen en fase de vista previa de investigación. Sesiones en la nube, rutinas.

El lunes, pide a quien administra el repositorio que instale la aplicación e integre el flujo con restricciones. Asígnale un error conocido y una solicitud de revisión bien delimitada; después, compara el resultado con el criterio del equipo. Amplía los disparadores solo cuando los resultados justifiquen la atención y el consumo que requieren.

Si quieres que alguien implemente y mantenga este flujo para tu equipo, solicita ayuda con la automatización con IA.