Lo esencial
- Claude Code GitHub Actions ejecuta Claude Code dentro de workflows de GitHub y permite llamarlo mencionando @claude en issues o pull requests.
- La configuración requiere acceso de administrador al repositorio y puede hacerse con /install-github-app o de forma manual.
- Claude necesita permisos de lectura y escritura sobre contenidos, issues y pull requests para modificar código y responder en GitHub.
- Según la FAQ oficial, Claude no crea pull requests por defecto: empuja commits a una rama y ofrece un enlace de PR pre-rellenada.
- Para desinstalar la integración hay que retirar los workflows, eliminar los secrets y quitar la GitHub App de Claude si procede.
Claude Code GitHub Actions es la integración oficial de Anthropic para ejecutar Claude Code dentro de workflows de GitHub. Te permite mencionar a @claude en issues o pull requests para que analice código, proponga cambios y empuje commits, o lanzarlo automáticamente con un prompt ante eventos de GitHub.
La parte interesante no es solo que Claude escriba código. Lo relevante para un equipo técnico es que la conversación ocurre donde ya se decide el trabajo: en issues, revisiones y pull requests. En proyectos con pymes veo que este detalle cambia la adopción: si la IA exige otra herramienta, se abandona; si vive en GitHub, entra en el hábito del equipo.
Claude Code GitHub Actions: qué es y para qué sirve
Claude Code GitHub Actions es una GitHub Action oficial de Anthropic que ejecuta Claude Code dentro de los flujos de trabajo de un repositorio. La documentación de Anthropic lo define así: ejecuta Claude Code dentro de los workflows del repositorio y permite invocarlo desde comentarios de issues o pull requests.
Según Anthropic, puedes mencionar @claude en un comentario de pull request o issue para que Claude analice el código, implemente cambios y haga push de commits.
En la práctica, esto convierte a Claude en un colaborador técnico dentro del repositorio. Puedes pedirle que investigue un bug, que adapte una función, que añada pruebas o que explique por qué falla una parte del código. No sustituye la revisión humana, pero reduce el tiempo entre detectar una tarea y tener una primera propuesta revisable.
Anthropic documenta dos formas principales de uso: modo interactivo, donde la acción espera una frase de activación como @claude, y modo automatización, donde el workflow incluye un prompt y se ejecuta sin esperar mención. Si ya estás valorando qué significa Claude Code para pymes, esta integración es el paso natural para llevarlo al ciclo real de desarrollo.
- Issues: Claude puede leer el contexto de una incidencia y proponer cambios para resolverla.
- Pull requests: Claude puede comentar, analizar cambios y empujar commits sobre una rama de trabajo.
- Eventos: GitHub Actions puede lanzar Claude automáticamente si el workflow contiene un prompt.
- Tareas recurrentes: Anthropic propone usarlo para convertir issues en pull requests, corregir bugs desde comentarios y automatizar tareas repetidas.
La versión actual documentada usa anthropics/claude-code-action@v1. Según la documentación de Anthropic, los workflows antiguos con @beta deben migrar a @v1, sustituir direct_prompt por prompt y mover opciones como max_turns o model a claude_args.
Cómo configurar Claude Code en GitHub paso a paso
Configurar Claude Code en GitHub exige acceso de administrador al repositorio y puede hacerse con instalación rápida o con configuración manual. Según Anthropic, ambas vías requieren permisos de administrador porque la integración instala una GitHub App, añade autenticación y crea o modifica workflows.
Antes de activarlo, mi recomendación es decidir en qué repositorio tiene sentido empezar. No lo probaría por primera vez en el monorepo crítico de producción. Empezaría por un repositorio con incidencias reales, pruebas automatizadas y reglas de revisión claras.
Opción rápida con /install-github-app
El setup rápido se inicia desde Claude Code con el comando /install-github-app. Según Anthropic, este camino instala la GitHub App de Claude, configura el secret de autenticación y prepara una pull request con el workflow para que el equipo la revise antes de fusionarla.
- Repositorio: abre Claude Code en el repositorio que quieres conectar.
- Comando: ejecuta /install-github-app y sigue los pasos que aparecen.
- Autenticación: Claude Code reutiliza una API key si ya existe o te permite crear una autenticación compatible.
- Workflow: Claude empuja una rama con los archivos de workflow seleccionados.
- Activación: crea y fusiona la pull request preparada para que @claude funcione en el repositorio.
Hay una limitación relevante: según Anthropic, /install-github-app solo funciona con repositorios en github.com. Para GitHub Enterprise Server, Anthropic documenta soporte, pero indica que requiere configuración manual del workflow y que el comando rápido no aplica.
Opción manual con app, secret y workflow
La configuración manual consiste en instalar la GitHub App de Claude, añadir un secret y copiar un workflow en .github/workflows/. Esta vía es la que elegiría si quieres revisar cada línea del workflow, usar un entorno enterprise o aplicar una política interna de seguridad más estricta.
- App: instala la GitHub App de Claude en el repositorio o en la organización correspondiente.
- Secret: añade ANTHROPIC_API_KEY o CLAUDE_CODE_OAUTH_TOKEN, según el método de autenticación.
- Archivo: copia el workflow en la carpeta .github/workflows/ del repositorio.
- Prueba: etiqueta a @claude en un issue o pull request para comprobar que responde.
Según Anthropic, ANTHROPIC_API_KEY es una clave API desde Claude Console y CLAUDE_CODE_OAUTH_TOKEN es un token OAuth ligado a una suscripción Claude. La documentación indica que el token OAuth está disponible en planes Pro, Max, Team y Enterprise.
| Vía | Cuándo usarla | Qué configura | Límite principal |
|---|---|---|---|
| Setup rápido | Cuando trabajas en github.com y quieres acelerar la instalación | GitHub App, secret y pull request con workflow | Según Anthropic, solo funciona con repositorios github.com |
| Setup manual | Cuando necesitas control, entorno enterprise o revisión interna | App instalada, secret y workflow copiado a mano | Requiere más criterio técnico y revisión del YAML |
| Organización | Cuando varios repositorios comparten el mismo patrón | App a nivel organización, secret de Actions compartido o workflow reutilizable | Hay que definir gobierno y permisos por repositorio |
Para organizaciones, Anthropic recomienda instalar la app a nivel de organización, guardar el secret como secret de Actions de organización y añadir el workflow a cada repositorio o usar un workflow reutilizable. Si gestionas varios equipos, esto evita copiar credenciales por todas partes y facilita auditar qué repositorios usan Claude.
Permisos, secrets y seguridad antes de automatizar
Claude necesita permisos de lectura y escritura sobre contenidos, issues y pull requests para trabajar dentro de un repositorio. Según Anthropic, la app se apoya en permisos sobre Contents, Issues y Pull requests, porque sin ellos no podría modificar archivos, responder a incidencias ni empujar cambios.
Este es el punto donde conviene frenar un poco. Una integración que puede leer código y escribir commits no debe instalarse como quien añade una extensión del navegador. En mi experiencia, la ganancia aparece cuando el equipo define límites: quién puede invocarlo, en qué ramas, con qué workflows y bajo qué revisión.
- Contents: permite a Claude leer y escribir archivos del repositorio para aplicar cambios.
- Issues: permite a Claude leer incidencias y responder dentro de la conversación técnica.
- Pull requests: permite a Claude interactuar con PR, comentar y empujar modificaciones.
- id-token: Anthropic lo requiere cuando usas federación de identidad con OpenID Connect.
- actions: según la FAQ oficial, actions: read permite a Claude leer resultados de CI en pull requests para ayudar a depurar fallos.
La documentación de seguridad del repositorio oficial añade una barrera importante: la acción solo puede ser activada por usuarios con permiso de escritura en el repositorio y rechaza actores bot por defecto salvo que se configuren en allowed_bots. Esto reduce el riesgo de que alguien externo use una mención para ejecutar instrucciones sobre tu código.
También hay que tratar los secrets con seriedad. Anthropic permite usar ANTHROPIC_API_KEY o CLAUDE_CODE_OAUTH_TOKEN, pero para evitar un secret de larga duración documenta la autenticación mediante workload identity federation, donde el workflow intercambia el token OpenID Connect de GitHub por acceso a la API de Claude.
Si tu empresa usa proveedores cloud, Anthropic documenta el uso con Amazon Bedrock, Google Cloud’s Agent Platform y Microsoft Foundry. En esos casos, la acción se selecciona con opciones como use_bedrock, use_vertex o use_foundry, y la recomendación oficial es apoyarse en OIDC para no guardar credenciales cloud de larga duración en el repositorio.
La seguridad no termina en permisos. La documentación oficial advierte de riesgos con eventos como pull_request_target y workflow_run, porque pueden ejecutarse con secrets del repositorio base. Si tu equipo está explorando automatizaciones más autónomas, te vendrá bien comparar este enfoque con el modo automático de Claude Code y definir dónde quieres supervisión humana obligatoria.
Cómo usar Claude en issues y pull requests
Usar Claude en GitHub consiste en darle una instrucción concreta dentro del contexto donde vive la tarea. La forma más sencilla es comentar en un issue o pull request mencionando @claude, con una petición clara, verificable y limitada.
Una mala petición sería: “@claude arregla esto”. Una buena petición sería: “@claude revisa por qué falla la validación del NIF en este flujo, propón un cambio mínimo y añade una prueba que cubra el caso”. La diferencia es que la segunda instrucción define alcance, criterio técnico y salida esperada.
Patrones útiles de comentario
Claude funciona mejor cuando el comentario tiene objetivo, límites y criterio de aceptación. No necesitas escribir una especificación de diez páginas, pero sí evitar instrucciones ambiguas que le obliguen a adivinar prioridades del negocio.
- Bug: “@claude reproduce el fallo descrito, localiza la causa probable y prepara un cambio pequeño con prueba asociada”.
- Refactor: “@claude simplifica esta función sin cambiar comportamiento y mantén compatibilidad con las pruebas actuales”.
- Documentación: “@claude actualiza el README para explicar este flujo de despliegue usando el workflow actual”.
- Revisión: “@claude revisa este PR buscando regresiones, problemas de seguridad y pruebas que falten”.
En una pyme española con un equipo pequeño de producto, el caso típico sería convertir incidencias funcionales en una primera rama de trabajo. Por ejemplo, el responsable de soporte abre un issue con el error reportado por clientes; una persona técnica añade contexto y menciona a Claude para que proponga una corrección inicial. El equipo revisa el diff, ejecuta CI y decide si continúa desde esa base.
Este flujo no elimina al desarrollador. Lo cambia de escribir cada línea desde cero a revisar hipótesis, validar impacto y decidir arquitectura. Si quieres aterrizarlo en un marco más amplio de adopción, encaja con lo que explico en cómo usar Claude en tu empresa.
¿Puede Claude crear pull requests automáticamente?
Claude no crea pull requests por defecto desde esta acción, según la FAQ oficial del repositorio de Anthropic. La FAQ explica que Claude empuja commits a una rama y proporciona un enlace a una página de PR pre-rellenada, para respetar reglas de protección de ramas y dejar el control final al usuario.
Esta decisión me parece sensata. En equipos con ramas protegidas, revisores obligatorios o checks de CI, crear PR automáticamente puede chocar con políticas internas. Que Claude prepare la rama y deje al humano abrir la PR mantiene una frontera clara entre propuesta y cambio formal.
Automatizar tareas con GitHub Actions con IA
GitHub Actions con IA permite ejecutar Claude sin mención manual cuando el workflow incluye un prompt asociado a un evento. Según Anthropic, Claude Code GitHub Actions puede recibir un prompt para ejecutarse automáticamente ante cualquier evento de GitHub.
El modo automático tiene mucho potencial, pero también más riesgo operativo. Yo lo reservaría para tareas de bajo impacto o muy bien acotadas al principio: generar resúmenes, proponer actualizaciones de documentación, revisar patrones repetitivos o preparar ramas que siempre pasen por revisión.
- Documentación: al cambiar una carpeta concreta, Claude puede proponer ajustes en documentación relacionada.
- Incidencias: al etiquetar un issue con una categoría determinada, Claude puede preparar una propuesta inicial.
- CI: si se permite leer resultados de Actions, Claude puede ayudar a diagnosticar fallos de pruebas.
- Mantenimiento: Claude puede automatizar tareas recurrentes que antes quedaban en una lista pendiente.
La clave es no confundir automatización con barra libre. Un buen workflow limita eventos, permisos y alcance del prompt. Por ejemplo, no es lo mismo permitir que Claude proponga cambios en una rama secundaria que dejarle actuar sobre cualquier evento con secrets disponibles.
Si ya trabajas con agentes o flujos de automatización, esta integración se entiende mejor como una pieza dentro de un sistema. Anthropic ha ido moviéndose hacia agentes más conectados al trabajo real; lo analizamos también al hablar de Dispatch y los agentes IA.
| Uso | Activación | Riesgo | Control recomendado |
|---|---|---|---|
| Comentario en issue | Mención a @claude | Bajo o medio | Permitir solo a usuarios con escritura y revisar commits |
| Revisión de PR | Mención o workflow de revisión | Medio | Exigir CI y revisión humana antes de merge |
| Prompt automático | Evento de GitHub Actions | Medio o alto | Limitar eventos, ramas, permisos y secrets |
| Organización completa | Workflow reutilizable | Alto si no hay gobierno | Plantillas, auditoría y aprobación por repositorio |
Desinstalar Claude Code GitHub Actions sin dejar restos
Desinstalar Claude Code GitHub Actions implica eliminar workflows, borrar secrets y retirar la GitHub App de Claude si ya no se usa. Anthropic indica que para quitar la acción hay que deshacer cada pieza de la configuración aplicada a la instalación.
No basta con borrar un archivo YAML si la app sigue instalada y los secrets siguen vivos. Desde un punto de vista de gobierno, la desinstalación correcta debe cerrar los tres frentes: ejecución, credenciales y permisos de aplicación.
- Workflows: elimina los archivos de .github/workflows/ que usen anthropics/claude-code-action.
- Secrets: borra ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN o secrets equivalentes si ya no se usan.
- App: desinstala la GitHub App de Claude del repositorio u organización si no queda ningún flujo dependiente.
- Ramas: revisa si quedan ramas creadas durante pruebas o propuestas pendientes.
- Auditoría: comprueba el historial de Actions y permisos para confirmar que no hay ejecuciones residuales.
Este último paso suele olvidarse. En empresas pequeñas, muchas integraciones se prueban, se dejan a medias y meses después nadie sabe qué credencial sigue activa. Con IA aplicada a código, ese descuido pesa más porque el sistema puede leer repositorios, participar en issues y empujar cambios.
Cuándo merece la pena usar Claude para revisar código
Claude para revisar código merece la pena cuando el equipo ya tiene GitHub ordenado y una cultura mínima de pull requests. Si no hay issues claros, pruebas, ramas protegidas o responsables de revisión, la IA solo acelerará el desorden existente.
Yo lo usaría primero en tres escenarios: mantenimiento de proyectos internos, resolución de bugs bien descritos y revisión de cambios medianos. Evitaría empezar con refactors grandes, migraciones críticas o cambios de seguridad sin supervisión estrecha.
- Buen candidato: repositorio con CI, pruebas y pull requests revisadas por al menos una persona técnica.
- Candidato dudoso: proyecto sin documentación, sin tests y con despliegues manuales poco controlados.
- Primer piloto: un workflow interactivo con @claude, sin automatizaciones agresivas y con permisos mínimos razonables.
- Escalado: tras validar resultados, pasar a workflows reutilizables o secrets de organización si hay varios repositorios.
La adopción buena no consiste en “meter IA” en GitHub, sino en diseñar un flujo donde cada propuesta de Claude llegue con contexto, pase por CI y quede bajo decisión humana. Ahí es donde automatizar pull requests con Claude empieza a ahorrar tiempo sin perder control.
También conviene revisar la parte legal y de gobierno interno, sobre todo si trabajas con código sensible o datos de clientes. Para pymes que están ordenando su estrategia de IA, el debate no es solo técnico; enlaza con la regulación de IA en pymes y con cómo documentas decisiones, accesos y responsabilidades.
Mi criterio práctico: empieza con un repositorio, un workflow interactivo, usuarios con permiso de escritura y revisión humana obligatoria. Si el equipo gana velocidad sin aumentar retrabajo ni incidentes, entonces tiene sentido pasar a automatizaciones más ambiciosas. Si no, el problema no será Claude; será el proceso de desarrollo que intentabas automatizar.
Preguntas frecuentes
¿Qué es Claude Code GitHub Actions?
Claude Code GitHub Actions es una GitHub Action oficial de Anthropic que ejecuta Claude Code dentro de workflows de GitHub. Permite mencionar a @claude en issues o pull requests para analizar código, implementar cambios y empujar commits, además de ejecutarse automáticamente mediante prompts en eventos de GitHub.
¿Cómo se configura Claude Code en GitHub?
Claude Code en GitHub se configura con acceso de administrador al repositorio. Puedes usar el comando /install-github-app en repositorios github.com o hacerlo manualmente instalando la GitHub App de Claude, añadiendo un secret de autenticación y copiando el workflow en .github/workflows/.
¿Qué permisos necesita Claude para trabajar en un repositorio?
Claude necesita permisos de lectura y escritura sobre contenidos, issues y pull requests. Según Anthropic, esos permisos permiten modificar archivos, responder a incidencias y trabajar con pull requests; algunos workflows también pueden usar id-token: write para OIDC o actions: read para leer resultados de CI.
¿Puede Claude crear pull requests automáticamente?
Claude no crea pull requests por defecto desde esta acción, según la FAQ oficial de Anthropic. La acción empuja commits a una rama y ofrece un enlace a una página de PR pre-rellenada, para respetar reglas de protección de ramas y mantener el control final en el usuario.
¿Cómo desinstalar Claude Code GitHub Actions?
Para desinstalar Claude Code GitHub Actions hay que retirar cada pieza de la configuración. Elimina los workflows que usan la acción, borra secrets como ANTHROPIC_API_KEY o CLAUDE_CODE_OAUTH_TOKEN y desinstala la GitHub App de Claude del repositorio u organización si ya no se necesita.
