@claude en cualquier PR o issue, Claude puede analizar tu código, crear pull requests, implementar características y corregir errores - todo mientras sigue los estándares de tu proyecto.
Claude Code GitHub Actions está construido sobre el Claude Code
SDK, que permite la integración programática de
Claude Code en tus aplicaciones. Puedes usar el SDK para construir flujos de trabajo de automatización personalizados más allá de GitHub Actions.
¿Por qué usar Claude Code GitHub Actions?
- Creación instantánea de PR: Describe lo que necesitas, y Claude crea un PR completo con todos los cambios necesarios
- Implementación de código automatizada: Convierte issues en código funcional con un único comando
- Sigue tus estándares: Claude respeta tus directrices
CLAUDE.mdy patrones de código existentes - Configuración simple: Comienza en minutos con nuestro instalador y clave API
- Seguro por defecto: Tu código permanece en los runners de Github
¿Qué puede hacer Claude?
Claude Code proporciona una poderosa GitHub Action que transforma cómo trabajas con código:Claude Code Action
Esta GitHub Action te permite ejecutar Claude Code dentro de tus flujos de trabajo de GitHub Actions. Puedes usar esto para construir cualquier flujo de trabajo personalizado sobre Claude Code. Ver repositorio →Configuración
Configuración rápida
La forma más fácil de configurar esta action es a través de Claude Code en la terminal. Solo abre claude y ejecuta/install-github-app.
Este comando te guiará a través de la configuración de la aplicación GitHub y los secretos requeridos.
- Debes ser administrador del repositorio para instalar la aplicación GitHub y agregar secretos
- La aplicación GitHub solicitará permisos de lectura y escritura para Contents, Issues y Pull requests
- Este método de inicio rápido solo está disponible para usuarios directos de Claude API. Si estás usando AWS Bedrock o Google Vertex AI, consulta la sección Usar con AWS Bedrock y Google Vertex AI.
Configuración manual
Si el comando/install-github-app falla o prefieres la configuración manual, sigue estas instrucciones de configuración manual:
-
Instala la aplicación Claude GitHub en tu repositorio: https://github.com/apps/claude
La aplicación Claude GitHub requiere los siguientes permisos del repositorio:
- Contents: Lectura y escritura (para modificar archivos del repositorio)
- Issues: Lectura y escritura (para responder a issues)
- Pull requests: Lectura y escritura (para crear PRs e insertar cambios)
- Agrega ANTHROPIC_API_KEY a tus secretos del repositorio (Aprende cómo usar secretos en GitHub Actions)
-
Copia el archivo de flujo de trabajo desde examples/claude.yml en el directorio
.github/workflows/de tu repositorio
Después de completar la configuración rápida o manual, prueba la action etiquetando
@claude en un comentario de issue o PR!Actualización desde Beta
Claude Code GitHub Actions v1.0 introduce cambios que rompen la compatibilidad y requieren actualizar tus archivos de flujo de trabajo para actualizar a v1.0 desde la versión beta.
Cambios esenciales
Todos los usuarios de beta deben hacer estos cambios en sus archivos de flujo de trabajo para actualizar:- Actualiza la versión de la action: Cambia
@betaa@v1 - Elimina la configuración de modo: Borra
mode: "tag"omode: "agent"(ahora se detecta automáticamente) - Actualiza las entradas de prompt: Reemplaza
direct_promptconprompt - Mueve opciones CLI: Convierte
max_turns,model,custom_instructions, etc. aclaude_args
Referencia de cambios que rompen la compatibilidad
| Entrada Beta Antigua | Nueva Entrada v1.0 |
|---|---|
mode | (Eliminada - se detecta automáticamente) |
direct_prompt | prompt |
override_prompt | prompt con variables de GitHub |
custom_instructions | claude_args: --system-prompt |
max_turns | claude_args: --max-turns |
model | claude_args: --model |
allowed_tools | claude_args: --allowedTools |
disallowed_tools | claude_args: --disallowedTools |
claude_env | settings formato JSON |
Ejemplo antes y después
Versión beta:La action ahora detecta automáticamente si ejecutar en modo interactivo (responde a menciones
@claude) o modo de automatización (se ejecuta inmediatamente con un prompt) basado en tu configuración.Casos de uso de ejemplo
Claude Code GitHub Actions puede ayudarte con una variedad de tareas. El directorio de ejemplos contiene flujos de trabajo listos para usar para diferentes escenarios.Flujo de trabajo básico
Usando comandos de barra
Automatización personalizada con prompts
Casos de uso comunes
En comentarios de issue o PR:Mejores prácticas
Configuración de CLAUDE.md
Crea un archivoCLAUDE.md en la raíz de tu repositorio para definir directrices de estilo de código, criterios de revisión, reglas específicas del proyecto y patrones preferidos. Este archivo guía la comprensión de Claude de los estándares de tu proyecto.
Consideraciones de seguridad
¡Nunca confirmes claves API directamente en tu repositorio!
- Agrega tu clave API como un secreto del repositorio nombrado
ANTHROPIC_API_KEY - Referencialo en flujos de trabajo:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - Limita los permisos de la action solo a lo necesario
- Revisa las sugerencias de Claude antes de hacer merge
${{ secrets.ANTHROPIC_API_KEY }}) en lugar de codificar directamente las claves API en tus archivos de flujo de trabajo.
Optimización del rendimiento
Usa plantillas de issue para proporcionar contexto, mantén tuCLAUDE.md conciso y enfocado, y configura timeouts apropiados para tus flujos de trabajo.
Costos de CI
Cuando uses Claude Code GitHub Actions, ten en cuenta los costos asociados: Costos de GitHub Actions:- Claude Code se ejecuta en runners alojados por GitHub, que consumen tus minutos de GitHub Actions
- Consulta la documentación de facturación de GitHub para precios detallados y límites de minutos
- Cada interacción de Claude consume tokens de API basados en la longitud de prompts y respuestas
- El uso de tokens varía según la complejidad de la tarea y el tamaño de la base de código
- Consulta la página de precios de Claude para las tasas de tokens actuales
- Usa comandos específicos
@claudepara reducir llamadas API innecesarias - Configura
--max-turnsapropiado enclaude_argspara prevenir iteraciones excesivas - Establece timeouts a nivel de flujo de trabajo para evitar trabajos descontrolados
- Considera usar los controles de concurrencia de GitHub para limitar ejecuciones paralelas
Ejemplos de configuración
Claude Code Action v1 simplifica la configuración con parámetros unificados:- Interfaz de prompt unificada - Usa
promptpara todas las instrucciones - Comandos de barra - Prompts preconstruidos como
/reviewo/fix - Paso a través de CLI - Cualquier argumento CLI de Claude Code a través de
claude_args - Disparadores flexibles - Funciona con cualquier evento de GitHub
Cuando respondas a comentarios de issue o PR, Claude responde automáticamente a menciones @claude. Para otros eventos, usa el parámetro
prompt para proporcionar instrucciones.Usar con AWS Bedrock y Google Vertex AI
Para entornos empresariales, puedes usar Claude Code GitHub Actions con tu propia infraestructura en la nube. Este enfoque te da control sobre la residencia de datos y la facturación mientras mantienes la misma funcionalidad.Requisitos previos
Antes de configurar Claude Code GitHub Actions con proveedores en la nube, necesitas:Para Google Cloud Vertex AI:
- Un proyecto de Google Cloud con Vertex AI habilitado
- Workload Identity Federation configurado para GitHub Actions
- Una cuenta de servicio con los permisos requeridos
- Una aplicación GitHub (recomendado) o usa el GITHUB_TOKEN predeterminado
Para AWS Bedrock:
- Una cuenta de AWS con Amazon Bedrock habilitado
- Proveedor de identidad OIDC de GitHub configurado en AWS
- Un rol IAM con permisos de Bedrock
- Una aplicación GitHub (recomendado) o usa el GITHUB_TOKEN predeterminado
1
Crear una aplicación GitHub personalizada (Recomendado para proveedores de terceros)
Para el mejor control y seguridad cuando uses proveedores de terceros como Vertex AI o Bedrock, recomendamos crear tu propia aplicación GitHub:Alternativa para Claude API o si no quieres configurar tu propia aplicación Github: Usa la aplicación oficial de Anthropic:
- Ve a https://github.com/settings/apps/new
- Completa la información básica:
- Nombre de la aplicación GitHub: Elige un nombre único (por ejemplo, “YourOrg Claude Assistant”)
- URL de inicio: El sitio web de tu organización o la URL del repositorio
- Configura los ajustes de la aplicación:
- Webhooks: Desmarca “Active” (no es necesario para esta integración)
- Establece los permisos requeridos:
- Permisos del repositorio:
- Contents: Lectura y escritura
- Issues: Lectura y escritura
- Pull requests: Lectura y escritura
- Permisos del repositorio:
- Haz clic en “Create GitHub App”
- Después de la creación, haz clic en “Generate a private key” y guarda el archivo
.pemdescargado - Anota tu ID de aplicación desde la página de configuración de la aplicación
- Instala la aplicación en tu repositorio:
- Desde la página de configuración de tu aplicación, haz clic en “Install App” en la barra lateral izquierda
- Selecciona tu cuenta u organización
- Elige “Only select repositories” y selecciona el repositorio específico
- Haz clic en “Install”
- Agrega la clave privada como un secreto en tu repositorio:
- Ve a la configuración de tu repositorio → Secrets and variables → Actions
- Crea un nuevo secreto nombrado
APP_PRIVATE_KEYcon el contenido del archivo.pem
- Agrega el ID de la aplicación como un secreto:
- Crea un nuevo secreto nombrado
APP_IDcon el ID de tu aplicación GitHub
Esta aplicación se usará con la action actions/create-github-app-token para generar tokens de autenticación en tus flujos de trabajo.
- Instala desde: https://github.com/apps/claude
- No se necesita configuración adicional para autenticación
2
Configurar la autenticación del proveedor en la nube
Elige tu proveedor en la nube y configura la autenticación segura:
AWS Bedrock
AWS Bedrock
Configura AWS para permitir que GitHub Actions se autentique de forma segura sin almacenar credenciales.Consulta la documentación de AWS para instrucciones detalladas de configuración de OIDC.
Nota de seguridad: Usa configuraciones específicas del repositorio y otorga solo los permisos mínimos requeridos.Configuración requerida:
-
Habilita Amazon Bedrock:
- Solicita acceso a modelos de Claude en Amazon Bedrock
- Para modelos entre regiones, solicita acceso en todas las regiones requeridas
-
Configura el proveedor de identidad OIDC de GitHub:
- URL del proveedor:
https://token.actions.githubusercontent.com - Audiencia:
sts.amazonaws.com
- URL del proveedor:
-
Crea un rol IAM para GitHub Actions:
- Tipo de entidad de confianza: Web identity
- Proveedor de identidad:
token.actions.githubusercontent.com - Permisos: política
AmazonBedrockFullAccess - Configura la política de confianza para tu repositorio específico
- AWS_ROLE_TO_ASSUME: El ARN del rol IAM que creaste
OIDC es más seguro que usar claves de acceso estáticas de AWS porque las credenciales son temporales y se rotan automáticamente.
Google Vertex AI
Google Vertex AI
Configura Google Cloud para permitir que GitHub Actions se autentique de forma segura sin almacenar credenciales.Para instrucciones de configuración detalladas, consulta la documentación de Workload Identity Federation de Google Cloud.
Nota de seguridad: Usa configuraciones específicas del repositorio y otorga solo los permisos mínimos requeridos.Configuración requerida:
-
Habilita APIs en tu proyecto de Google Cloud:
- API de credenciales de IAM
- API de servicio de token de seguridad (STS)
- API de Vertex AI
-
Crea recursos de Workload Identity Federation:
- Crea un Workload Identity Pool
- Agrega un proveedor OIDC de GitHub con:
- Emisor:
https://token.actions.githubusercontent.com - Asignaciones de atributos para repositorio y propietario
- Recomendación de seguridad: Usa condiciones de atributos específicas del repositorio
- Emisor:
-
Crea una cuenta de servicio:
- Otorga solo el rol
Vertex AI User - Recomendación de seguridad: Crea una cuenta de servicio dedicada por repositorio
- Otorga solo el rol
-
Configura enlaces de IAM:
- Permite que el Workload Identity Pool suplante la cuenta de servicio
- Recomendación de seguridad: Usa conjuntos de principios específicos del repositorio
- GCP_WORKLOAD_IDENTITY_PROVIDER: El nombre completo del recurso del proveedor
- GCP_SERVICE_ACCOUNT: La dirección de correo electrónico de la cuenta de servicio
Workload Identity Federation elimina la necesidad de claves de cuenta de servicio descargables, mejorando la seguridad.
3
Agregar secretos requeridos
Agrega los siguientes secretos a tu repositorio (Settings → Secrets and variables → Actions):
Para Claude API (Directo):
-
Para autenticación de API:
ANTHROPIC_API_KEY: Tu clave API de Claude desde console.anthropic.com
-
Para aplicación GitHub (si usas tu propia aplicación):
APP_ID: El ID de tu aplicación GitHubAPP_PRIVATE_KEY: El contenido de la clave privada (.pem)
Para Google Cloud Vertex AI
-
Para autenticación de GCP:
GCP_WORKLOAD_IDENTITY_PROVIDERGCP_SERVICE_ACCOUNT
-
Para aplicación GitHub (si usas tu propia aplicación):
APP_ID: El ID de tu aplicación GitHubAPP_PRIVATE_KEY: El contenido de la clave privada (.pem)
Para AWS Bedrock
-
Para autenticación de AWS:
AWS_ROLE_TO_ASSUME
-
Para aplicación GitHub (si usas tu propia aplicación):
APP_ID: El ID de tu aplicación GitHubAPP_PRIVATE_KEY: El contenido de la clave privada (.pem)
4
Crear archivos de flujo de trabajo
Crea archivos de flujo de trabajo de GitHub Actions que se integren con tu proveedor en la nube. Los ejemplos a continuación muestran configuraciones completas tanto para AWS Bedrock como para Google Vertex AI:
Flujo de trabajo de AWS Bedrock
Flujo de trabajo de AWS Bedrock
Requisitos previos:
- Acceso a AWS Bedrock habilitado con permisos de modelo de Claude
- GitHub configurado como proveedor de identidad OIDC en AWS
- Rol IAM con permisos de Bedrock que confía en GitHub Actions
| Nombre del secreto | Descripción |
|---|---|
AWS_ROLE_TO_ASSUME | ARN del rol IAM para acceso a Bedrock |
APP_ID | Tu ID de aplicación GitHub (desde la configuración de la aplicación) |
APP_PRIVATE_KEY | La clave privada que generaste para tu aplicación GitHub |
El formato de ID de modelo para Bedrock incluye el prefijo de región (por ejemplo,
us.anthropic.claude...) y sufijo de versión.Flujo de trabajo de Google Vertex AI
Flujo de trabajo de Google Vertex AI
Requisitos previos:
- API de Vertex AI habilitada en tu proyecto de GCP
- Workload Identity Federation configurada para GitHub
- Cuenta de servicio con permisos de Vertex AI
| Nombre del secreto | Descripción |
|---|---|
GCP_WORKLOAD_IDENTITY_PROVIDER | Nombre del recurso del proveedor de identidad de carga de trabajo |
GCP_SERVICE_ACCOUNT | Correo electrónico de la cuenta de servicio con acceso a Vertex AI |
APP_ID | Tu ID de aplicación GitHub (desde la configuración de la aplicación) |
APP_PRIVATE_KEY | La clave privada que generaste para tu aplicación GitHub |
El ID del proyecto se recupera automáticamente del paso de autenticación de Google Cloud, por lo que no necesitas codificarlo.
Solución de problemas
Claude no responde a comandos @claude
Verifica que la aplicación GitHub esté instalada correctamente, comprueba que los flujos de trabajo estén habilitados, asegúrate de que la clave API esté configurada en los secretos del repositorio y confirma que el comentario contenga@claude (no /claude).
CI no se ejecuta en los commits de Claude
Asegúrate de estar usando la aplicación GitHub o una aplicación personalizada (no el usuario Actions), comprueba que los disparadores del flujo de trabajo incluyan los eventos necesarios y verifica que los permisos de la aplicación incluyan disparadores de CI.Errores de autenticación
Confirma que la clave API es válida y tiene permisos suficientes. Para Bedrock/Vertex, comprueba la configuración de credenciales y asegúrate de que los secretos estén nombrados correctamente en los flujos de trabajo.Configuración avanzada
Parámetros de la action
Claude Code Action v1 usa una configuración simplificada:| Parámetro | Descripción | Requerido |
|---|---|---|
prompt | Instrucciones para Claude (texto o comando de barra) | No* |
claude_args | Argumentos CLI pasados a Claude Code | No |
anthropic_api_key | Clave API de Claude | Sí** |
github_token | Token de GitHub para acceso a API | No |
trigger_phrase | Frase de disparo personalizada (predeterminado: “@claude”) | No |
use_bedrock | Usar AWS Bedrock en lugar de Claude API | No |
use_vertex | Usar Google Vertex AI en lugar de Claude API | No |
**Requerido para Claude API directo, no para Bedrock/Vertex
Usando claude_args
El parámetroclaude_args acepta cualquier argumento CLI de Claude Code:
--max-turns: Máximo de turnos de conversación (predeterminado: 10)--model: Modelo a usar (por ejemplo,claude-sonnet-4-5-20250929)--mcp-config: Ruta a la configuración de MCP--allowed-tools: Lista separada por comas de herramientas permitidas--debug: Habilitar salida de depuración
Métodos de integración alternativos
Aunque el comando/install-github-app es el enfoque recomendado, también puedes:
- Aplicación GitHub personalizada: Para organizaciones que necesitan nombres de usuario personalizados o flujos de autenticación personalizados. Crea tu propia aplicación GitHub con los permisos requeridos (contents, issues, pull requests) y usa la action actions/create-github-app-token para generar tokens en tus flujos de trabajo.
- GitHub Actions manual: Configuración directa del flujo de trabajo para máxima flexibilidad
- Configuración de MCP: Carga dinámica de servidores del Protocolo de contexto del modelo
Personalizar el comportamiento de Claude
Puedes configurar el comportamiento de Claude de dos formas:- CLAUDE.md: Define estándares de codificación, criterios de revisión y reglas específicas del proyecto en un archivo
CLAUDE.mden la raíz de tu repositorio. Claude seguirá estas directrices al crear PRs y responder a solicitudes. Consulta nuestra documentación de memoria para más detalles. - Prompts personalizados: Usa el parámetro
prompten el archivo de flujo de trabajo para proporcionar instrucciones específicas del flujo de trabajo. Esto te permite personalizar el comportamiento de Claude para diferentes flujos de trabajo o tareas.