# Claude Code GitHub Actions: configuración y workflows

URL: https://agentvera.dev/es/blog/claude-code-github-actions/ · Publicado: 2026-10-27

Configura Claude Code GitHub Actions: /install-github-app o a mano, menciones @claude, un workflow de revisión automática de PR, secrets, costes y permisos.

**En resumen:**

- Ejecuta /install-github-app dentro de Claude Code para instalar la Claude GitHub App, guardar tu key como secret y abrir un PR con los archivos del workflow, o haz esos tres pasos a mano.
- Sin el input prompt, la action espera a @claude en comentarios de issues y PR; con un prompt se ejecuta sola, y así se monta una revisión automática de PR o un informe diario.
- Cada ejecución cuesta minutos de Actions más tokens, así que limítala con --max-turns en claude_args, timeouts del job, concurrency y un --allowedTools estrecho; el trabajo exploratorio, en local.

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](/es/blog/auto-fix-ci-failures-with-ai/ "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:

```text
/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:

```yaml
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:

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

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

```text
@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`:

```yaml
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](/es/blog/ai-code-review/ "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í:

```yaml
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:

| Input | Qué hace |
| --- | --- |
| `prompt` | Texto de la tarea o un comando slash. Si se define, la action funciona en modo automatización. |
| `claude_args` | Cualquier flag de la CLI de Claude Code, como `--max-turns`, `--model`, `--allowedTools`, `--mcp-config`, `--append-system-prompt`. |
| `anthropic_api_key` | API key para la Claude API. |
| `claude_code_oauth_token` | Token de `claude setup-token`, como alternativa a la API key. |
| `github_token` | Tu propio token, si no quieres que actúe la Claude GitHub App. |
| `trigger_phrase` | La palabra de mención. Por defecto, `@claude`. |
| `settings` | Ajustes de Claude Code como JSON o ruta de archivo, para permisos, hooks y entorno. |
| `plugin_marketplaces`, `plugins` | Cargan plugins como `code-review`. |
| `use_bedrock`, `use_vertex`, `use_foundry` | Ejecutan a través de un proveedor cloud en lugar de la Claude API. |

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](/es/glossary/prompt-injection/ "Inyección de prompts") y [seguridad de los agentes de programación con IA](/es/blog/ai-coding-agent-security/ "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:

```yaml
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](/es/blog/claude-md-agents-md/ "Cómo escribir CLAUDE.md y AGENTS.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](/es/glossary/git-worktree/ "Qué es un git worktree"), y consulta diffs y commits en el panel [Git y GitHub](/es/features/git-and-github/ "Git y GitHub").
- **[Revisión de código automática](/es/features/code-review/ "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](/es/features/ci-cd-center/ "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](/es/features/automations/ "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](/es/blog/how-to-use-opencode/ "Cómo usar opencode") muestra esa parte con un agente que no depende de ningún proveedor. [Descarga AgentVera](/es/download/ "Descargar 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.

## Preguntas frecuentes

**¿Claude Code GitHub Actions es gratis?** Añadir la action no cuesta nada, pero cada ejecución consume minutos de GitHub Actions en tu runner y uso de Claude. Con una API key pagas por token; con un CLAUDE_CODE_OAUTH_TOKEN creado con claude setup-token, las ejecuciones cuentan contra tu suscripción Pro, Max, Team o Enterprise.

**¿Por qué no pasa nada cuando escribo @claude?** Comprueba que el comentario contiene @claude como palabra completa (no /claude ni @claude-bot), que tienes acceso de escritura al repositorio, que la Claude GitHub App está instalada en el repo, que el archivo del workflow está en la rama por defecto y que existe el secret con la API key o el token OAuth.

**¿Claude puede revisar pull requests automáticamente?** Sí. Un workflow que se dispara con pull_request y un prompt que ejecuta el plugin code-review revisa cada PR nuevo o actualizado y publica comentarios en línea. Los PR en borrador, cerrados y triviales se saltan. Anthropic también vende un producto gestionado aparte, Code Review, que no necesita workflow.

**¿Uso una API key o un token OAuth?** Para un repositorio personal sirve cualquiera. Para una organización, la documentación recomienda una API key de la Claude Console guardada como secret de organización, porque un token OAuth está ligado a la suscripción de una persona y deja de funcionar si esa persona se va.

**¿Por qué mis checks de CI no se ejecutan con los commits que sube Claude?** GitHub no inicia workflows para commits hechos con el GITHUB_TOKEN por defecto. Quita github_token: ${{ secrets.GITHUB_TOKEN }} de los inputs de la action para que use la Claude GitHub App, o pásale un token de tu propia GitHub App.

---

**Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/