Claude Code GitHub Actions: configuración y workflows

Claude Code GitHub Actions te permite ejecutar Claude Code dentro de un workflow de GitHub. Mencionas a @claude en una issue o un pull request, y Claude lee el código, responde, escribe una corrección en una rama nueva o revisa el diff, todo en un runner de GitHub. La forma más rápida de configurarlo es abrir Claude Code en tu repositorio y ejecutar /install-github-app. Instala la Claude GitHub App, guarda tu key como secret del repositorio y abre un pull request con los archivos del workflow.

Esta guía cubre las dos vías de configuración, los inputs de la action oficial anthropics/claude-code-action, los dos modos (menciones y automatización), un workflow de revisión de PR listo para usar, los secrets, el control de costes y permisos, y los casos en los que es mejor ejecutar Claude en local. Todo sigue la documentación de Anthropic y el README de la action a octubre de 2026. Si lo que buscas es un agente que arregle solo las builds de CI en rojo, tiene su propio artículo: corregir fallos de CI automáticamente con IA.

Qué hace la action

anthropics/claude-code-action@v1 es una GitHub Action que ejecuta el agente Claude Code en tu propio runner de GitHub. Funciona en dos modos:

• Interactivo (menciones). Si no le das un prompt, espera una frase de activación, @claude por defecto. La frase puede estar en un comentario de una issue o un PR, en una revisión de PR o en el título o el cuerpo de una issue nueva. Claude responde en un comentario y puede subir una rama con cambios.
• Automatización. Si defines prompt, Claude ejecuta esa tarea en cuanto se dispara el workflow, sin necesidad de mencionarlo. Los resultados van al log de la ejecución, salvo que el prompt o un plugin le digan a Claude que publique en otro sitio. Así se montan revisiones de PR, informes programados y la clasificación de issues.

El agente sigue las mismas reglas que en tu terminal. Lee CLAUDE.md, usa las herramientas que permites y se detiene en el límite de turnos que fijes.

Paso 1: configuración rápida con /install-github-app

Abre Claude Code en el repositorio y ejecuta:

/install-github-app

Antes de empezar, comprueba tres cosas:

• Eres administrador del repositorio. Tanto instalar la app como añadir secrets requieren permisos de administrador.
• El repositorio está en github.com. Si el remoto está en gitlab.com o bitbucket.org, el comando muestra un aviso y termina.
• La CLI de GitHub tiene la sesión iniciada. Ejecuta antes gh auth login si no lo has hecho.

El comando te guía paso a paso. Instala la Claude GitHub App en el repo y te pregunta cómo debe autenticarse Claude. Después guarda como secret del repositorio ANTHROPIC_API_KEY (una API key) o CLAUDE_CODE_OAUTH_TOKEN (un token ligado a tu suscripción de Claude). Si ya existe una key, puede reutilizarla. Por último, sube una rama con los archivos del workflow y abre un pull request para que lo fusiones.

Obtienes dos workflows: claude.yml responde a las menciones de @claude y claude-code-review.yml revisa los pull requests. Pulsa Esc para parar a mitad, o elige “Skip for now” una vez instalada la app si prefieres escribir los workflows tú. Si vuelves a ejecutar el comando más adelante, te ofrece actualizar el archivo del workflow a la última versión.

La configuración rápida funciona con la Claude API y con las suscripciones de Claude. Si usas Amazon Bedrock, Google Cloud o Microsoft Foundry, sigue la vía manual y la sección de proveedores cloud de la documentación.

Paso 2: configuración manual

Si el comando no encaja con tu caso, estos son los mismos tres pasos a mano:

1. Instala la Claude GitHub App desde github.com/apps/claude en el repositorio. La action usa sus permisos Contents, Issues y Pull requests, cada uno con acceso de lectura y escritura.
2. Añade un secret en Settings → Secrets and variables → Actions:
   • ANTHROPIC_API_KEY: una API key de la Claude Console, facturada por token, o
   • CLAUDE_CODE_OAUTH_TOKEN: ejecuta claude setup-token en local para crear uno; funciona con los planes Pro, Max, Team y Enterprise.
3. Copia el workflow de ejemplo claude.yml de la carpeta examples/ de la action a .github/workflows/.

Este es un workflow de menciones que funciona:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Hay dos permisos fáciles de pasar por alto. id-token: write es necesario para la autenticación por defecto con la GitHub App. actions: read permite a Claude leer los resultados de CI, así que puedes preguntarle por qué ha fallado un check. Si usas un token de suscripción, cambia la última línea por claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

Para una organización, la documentación sugiere instalar la app a nivel de organización, guardar la key en un secret de Actions de la organización y llamar a un workflow reutilizable desde cada repo. También recomienda una API key en lugar de un token OAuth para los secrets compartidos, porque un token pertenece a la suscripción de una persona. Si prefieres no guardar ninguna key de larga duración, la action admite workload identity federation (OIDC) mediante los inputs anthropic_federation_rule_id y anthropic_organization_id.

Paso 3: usa @claude en issues y pull requests

Cuando el workflow esté en la rama por defecto, escribe un comentario:

@claude why does the checkout test fail on Node 22? Fix it if the cause is in our code.

@claude implement this issue. Keep the public API unchanged and add tests.

@claude review the error handling in src/payments/ and suggest changes inline.

Claude responde en un comentario. Cuando cambia código, sube los cambios a una rama que empieza por claude/ (el input branch_prefix lo cambia) y te da un enlace para abrir el pull request. Unas cuantas reglas deciden quién puede iniciar una ejecución:

• Quien comenta necesita acceso de escritura. Los usuarios sin él se ignoran, salvo que los incluyas en allowed_non_write_users, que además necesita tu propio github_token.
• Los bots se ignoran, salvo que los nombres en allowed_bots. Ponerlo en "*" acepta cualquier bot, algo que el README desaconseja en repositorios públicos.
• La frase de activación es una palabra completa. @claude funciona; /claude y @claude-bot, no. Cámbiala con trigger_phrase si lo necesitas.

También existen assignee_trigger (se inicia cuando una issue se asigna a un usuario concreto) y label_trigger (se inicia cuando se añade una etiqueta, claude por defecto). Combínalos con los tipos de evento de issues adecuados en on:.

Paso 4: un workflow de revisión automática de PR

El workflow de revisión de abajo es el que incluye la documentación. Se ejecuta en cada pull request abierto, actualizado, reabierto o marcado como listo para revisión, sin que nadie escriba @claude:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      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 }}
          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: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Qué hace cada parte:

• plugin_marketplaces y plugins cargan el plugin oficial code-review.
• prompt ejecuta su comando sobre el PR actual. --comment publica los hallazgos como comentarios en línea, o como un único comentario de resumen.
• La línea claude_args es obligatoria. Sin --allowedTools para la herramienta de comentarios en línea, el servidor MCP que publica los comentarios no arranca.

El plugin se salta los PR en borrador, cerrados y triviales, y los PR en los que ya ha comentado. Los pull requests desde forks de un repositorio público no reciben los secrets del repositorio, así que la revisión no se ejecuta en ellos. Anthropic también ofrece un producto gestionado aparte llamado Code Review que revisa PR sin ningún archivo de workflow. La action es la que controlas tú y ejecutas en tu propio runner.

Para ver con más amplitud qué detecta y qué se le escapa a la revisión con IA, consulta revisión de código con IA.

Paso 5: automatizaciones programadas y personalizadas

Con prompt puedes ejecutar cualquier tarea en cualquier evento de GitHub. Un resumen diario se ve así:

name: Daily report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Summarize yesterday's commits and open issues"
          claude_args: |
            --model claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

Recuerda que, con un prompt simple, Claude no tiene shell ni acceso a la API de GitHub hasta que le concedes herramientas con --allowedTools o con una regla permissions.allow en el input settings. Los workflows programados solo se ejecutan desde la rama por defecto, y GitHub los desactiva en repositorios públicos tras 60 días sin actividad.

Los inputs que de verdad usarás

La action tiene muchos inputs. Estos son los habituales:

Otros útiles del README: base_branch y branch_prefix para decidir dónde sube Claude los cambios, use_sticky_comment para mantener un único comentario que se va actualizando, track_progress para publicar comentarios de seguimiento en eventos de PR e issues, use_commit_signing para firmar commits y additional_permissions (por ejemplo actions: read). La action también devuelve outputs como branch_name, session_id y structured_output para los pasos siguientes.

Si usabas la beta, la actualización es mecánica. Cambia @beta por @v1, quita mode, renombra direct_prompt a prompt, mueve max_turns y model a claude_args y convierte custom_instructions en --append-system-prompt.

Secrets: qué va en cada sitio

• Nunca pongas una key en un archivo de workflow. Usa ${{ secrets.ANTHROPIC_API_KEY }} o ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.
• Guarda los secrets en el nivel más restringido que funcione: un secret de repositorio para un solo repo, un secret de organización limitado a repositorios seleccionados para varios.
• Deja show_full_output desactivado en repos públicos. El README avisa de que la salida completa en los logs puede exponer secrets.
• Trata el texto de las issues como entrada no fiable. Cualquiera que pueda escribir una issue puede intentar dirigir a Claude con instrucciones escondidas en ella. La regla del acceso de escritura es tu defensa principal, así que no relajes allowed_non_write_users ni allowed_bots a la ligera. Inyección de prompts y seguridad de los agentes de programación con IA tratan los riesgos con más detalle.

Controlar costes y permisos

Cada ejecución cuesta dos veces: minutos de GitHub Actions en el runner y tokens de Claude (o uso de la suscripción si usas un token OAuth). Las palancas que recomienda la documentación:

• Limita los turnos: claude_args: "--max-turns 5" evita que una ejecución entre en bucle.
• Pon un timeout al job con timeout-minutes en el job.
• Usa concurrency para que una ráfaga de pushes no lance cinco revisiones del mismo PR:

concurrency:
  group: claude-${{ github.event.pull_request.number || github.event.issue.number }}
  cancel-in-progress: true

• Restringe las herramientas. Da a --allowedTools solo los comandos que necesita la tarea y deja los permissions del job en solo lectura para los jobs de revisión, como en el workflow de arriba.
• Mantén CLAUDE.md corto y concreto. Claude lo carga en cada ejecución, así que uno largo cuesta tokens cada vez. Cómo escribir CLAUDE.md incluye una plantilla.
• Escribe peticiones concretas. “@claude fix the null check in parseDate” sale más barato que “@claude look at this”. Las plantillas de issues ayudan a que la gente escriba mejores peticiones.

Errores habituales

• El workflow no está en la rama por defecto. Los workflows de issue_comment solo se ejecutan desde la rama por defecto, así que fusiona primero el PR de configuración.
• La CI no se ejecuta con los commits de Claude. GitHub no inicia workflows para commits hechos con el GITHUB_TOKEN por defecto. Quita github_token: ${{ secrets.GITHUB_TOKEN }} para que la action use la Claude GitHub App, o pásale un token de tu propia app.
• La revisión no publica nada. Revisa la línea --allowedTools "mcp__github_inline_comment__create_inline_comment" y comprueba si el PR es un borrador o viene de un fork.
• Claude dice que no puede ejecutar comandos. En modo automatización no hay nada permitido por defecto. Añade las herramientas a --allowedTools.

Cuándo es mejor ejecutar Claude en local

La action va bien en tareas donde un disparador fijo lleva a un trabajo acotado: responder una pregunta, implementar una issue pequeña, revisar un diff, escribir un resumen diario. Encaja mal cuando:

• Quieres ir guiándolo sobre la marcha. Un hilo de comentarios es lento si tienes que corregir al agente cada pocos minutos. Una sesión local te deja interrumpir, aprobar y reconducir.
• La tarea necesita tu entorno: una base de datos en marcha, un servicio local, secrets que no deben ir a la CI o una interfaz gráfica que tienes que mirar.
• Estás explorando. Una investigación larga quema minutos del runner y tokens sin que nadie la vigile. En local ves cuándo se desvía y la paras.
• Quieres varios agentes a la vez, cada uno en su propio worktree, comparando enfoques.

Muchos equipos usan las dos cosas. La action se encarga de las revisiones rutinarias y las issues pequeñas, y el trabajo más pesado ocurre en local, donde alguien lo vigila.

La parte local con AgentVera

AgentVera es una app de escritorio que ejecuta Claude Code, Codex, opencode y otras CLI de agentes de programación una al lado de otra, en terminales reales, con tus propias instalaciones e inicios de sesión. Cubre la parte local del reparto anterior:

• Agentes en paneles y worktrees. Ejecuta varios agentes de Claude Code uno junto a otro, cada uno en su propio git worktree, y consulta diffs y commits en el panel Git y GitHub.
• Revisión de código automática antes de hacer push: cuando un agente termina un turno, un modelo de Claude que eliges revisa lo que ha escrito y lista los hallazgos con su gravedad y archivo:línea. Puede devolvérselos al agente. Está en el plan gratuito.
• El centro de CI/CD reúne en un solo lugar las ejecuciones de GitHub Actions, GitLab CI y Jenkins. Los logs de una ejecución fallida pasan a un agente nuevo con un clic.
• Las automatizaciones (Pro y Team) pueden iniciar un agente cuando la CI se pone en rojo o cuando un miembro del repo comenta en un PR abierto. El agente trabaja en su propio worktree, y AgentVera nunca sube cambios directamente a la rama por defecto.

Como AgentVera ejecuta cualquier CLI de agentes, la misma configuración sirve también para otros agentes. Cómo usar opencode muestra esa parte con un agente que no depende de ningún proveedor. Descarga AgentVera para probarlo.

Conclusión

Para llevar Claude Code a GitHub Actions, ejecuta /install-github-app, fusiona el PR que abre y escribe @claude en una issue. Para las revisiones automáticas, añade el workflow del plugin code-review con su línea --allowedTools. Después mantenlo acotado con --max-turns, timeouts del job, concurrency, permisos de solo lectura donde puedas y secrets que nunca toquen el archivo del workflow. Deja el trabajo largo, exploratorio y muy dependiente del entorno para una sesión local donde puedas vigilarlo.