@claude en cualquier PR o problema, Claude puede analizar tu código, crear solicitudes de extracción, 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 problemas 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 de API
- Seguro por defecto: Tu código permanece en los ejecutores 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 usarla 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 acción 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 de GitHub y los secretos requeridos.
- Debes ser administrador del repositorio para instalar la aplicación de GitHub y agregar secretos
- La aplicación de GitHub solicitará permisos de lectura y escritura para Contenidos, Problemas y Solicitudes de extracción
- 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:
- Contenidos: Lectura y escritura (para modificar archivos del repositorio)
- Problemas: Lectura y escritura (para responder a problemas)
- Solicitudes de extracción: Lectura y escritura (para crear PR 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 de examples/claude.yml en el directorio
.github/workflows/de tu repositorio
Después de completar la configuración rápida o manual, prueba la acción etiquetando
@claude en un comentario de problema o PR.Actualización desde Beta
Claude Code GitHub Actions v1.0 introduce cambios importantes que 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 acción: Cambia
@betaa@v1 - Elimina la configuración de modo: Elimina
mode: "tag"omode: "agent"(ahora se detecta automáticamente) - Actualiza las entradas de solicitud: Reemplaza
direct_promptconprompt - Mueve opciones de CLI: Convierte
max_turns,model,custom_instructions, etc. aclaude_args
Referencia de cambios importantes
| Entrada Beta antigua | Nueva entrada v1.0 |
|---|---|
mode | (Eliminado - 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 acción ahora detecta automáticamente si ejecutar en modo interactivo (responde a menciones
@claude) o modo de automatización (se ejecuta inmediatamente con un solicitud) 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 diagonal
Automatización personalizada con solicitudes
Casos de uso comunes
En comentarios de problema 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 de API directamente en tu repositorio!
- Agrega tu clave de API como un secreto del repositorio llamado
ANTHROPIC_API_KEY - Haz referencia a ella en flujos de trabajo:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - Limita los permisos de acción solo a lo necesario
- Revisa las sugerencias de Claude antes de fusionar
${{ secrets.ANTHROPIC_API_KEY }}) en lugar de codificar claves de API directamente en tus archivos de flujo de trabajo.
Optimización del rendimiento
Usa plantillas de problemas para proporcionar contexto, mantén tuCLAUDE.md conciso y enfocado, y configura tiempos de espera apropiados para tus flujos de trabajo.
Costos de CI
Al usar Claude Code GitHub Actions, ten en cuenta los costos asociados: Costos de GitHub Actions:- Claude Code se ejecuta en ejecutores alojados en GitHub, que consumen tus minutos de GitHub Actions
- Consulta la documentación de facturación de GitHub para obtener detalles de precios y límites de minutos
- Cada interacción de Claude consume tokens de API basados en la longitud de solicitudes 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 obtener las tasas de tokens actuales
- Usa comandos específicos
@claudepara reducir llamadas de API innecesarias - Configura
--max-turnsapropiado enclaude_argspara evitar iteraciones excesivas - Establece tiempos de espera a nivel de flujo de trabajo para evitar trabajos descontrolados
- Considera usar 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 solicitud unificada - Usa
promptpara todas las instrucciones - Comandos de barra diagonal - Solicitudes precompiladas como
/reviewo/fix - Paso a través de CLI - Cualquier argumento de CLI de Claude Code a través de
claude_args - Disparadores flexibles - Funciona con cualquier evento de GitHub
Al responder a comentarios de problema 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
- Federación de identidad de carga de trabajo configurada para GitHub Actions
- Una cuenta de servicio con los permisos requeridos
- Una aplicación de 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 de IAM con permisos de Bedrock
- Una aplicación de GitHub (recomendado) o usa el GITHUB_TOKEN predeterminado
1
Crear una aplicación de GitHub personalizada (Recomendado para proveedores de terceros)
Para el mejor control y seguridad al usar proveedores de terceros como Vertex AI o Bedrock, recomendamos crear tu propia aplicación de GitHub:Alternativa para Claude API o si no quieres configurar tu propia aplicación de 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 de 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: Desactiva “Activo” (no es necesario para esta integración)
- Establece los permisos requeridos:
- Permisos del repositorio:
- Contenidos: Lectura y escritura
- Problemas: Lectura y escritura
- Solicitudes de extracción: Lectura y escritura
- Permisos del repositorio:
- Haz clic en “Crear aplicación de GitHub”
- Después de la creación, haz clic en “Generar una clave privada” 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 “Instalar aplicación” en la barra lateral izquierda
- Selecciona tu cuenta u organización
- Elige “Solo repositorios seleccionados” y selecciona el repositorio específico
- Haz clic en “Instalar”
- Agrega la clave privada como un secreto a tu repositorio:
- Ve a la configuración de tu repositorio → Secretos y variables → Acciones
- Crea un nuevo secreto llamado
APP_PRIVATE_KEYcon el contenido del archivo.pem
- Agrega el ID de la aplicación como un secreto:
- Crea un nuevo secreto llamado
APP_IDcon el ID de tu aplicación de GitHub
Esta aplicación se usará con la acción 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 requiere configuración adicional para autenticación
2
Configurar autenticación del proveedor en la nube
Elige tu proveedor en la nube y configura 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 obtener 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 de IAM para GitHub Actions:
- Tipo de entidad de confianza: Identidad web
- 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 de 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 obtener instrucciones de configuración detalladas, consulta la documentación de Federación de identidad de carga de trabajo 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 Federación de identidad de carga de trabajo:
- Crea un grupo de identidad de carga de trabajo
- 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 atributo 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 grupo de identidad de carga de trabajo 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
La Federación de identidad de carga de trabajo elimina la necesidad de claves de cuenta de servicio descargables, mejorando la seguridad.
3
Agregar secretos requeridos
Agrega los siguientes secretos a tu repositorio (Configuración → Secretos y variables → Acciones):
Para Claude API (Directo):
-
Para autenticación de API:
ANTHROPIC_API_KEY: Tu clave de API de Claude desde console.anthropic.com
-
Para aplicación de GitHub (si usas tu propia aplicación):
APP_ID: El ID de tu aplicación de 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 de GitHub (si usas tu propia aplicación):
APP_ID: El ID de tu aplicación de 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 de GitHub (si usas tu propia aplicación):
APP_ID: El ID de tu aplicación de 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 de IAM con permisos de Bedrock que confía en GitHub Actions
| Nombre del secreto | Descripción |
|---|---|
AWS_ROLE_TO_ASSUME | ARN del rol de IAM para acceso a Bedrock |
APP_ID | Tu ID de aplicación de GitHub (desde la configuración de la aplicación) |
APP_PRIVATE_KEY | La clave privada que generaste para tu aplicación de 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
- Federación de identidad de carga de trabajo 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 de GitHub (desde la configuración de la aplicación) |
APP_PRIVATE_KEY | La clave privada que generaste para tu aplicación de 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 de GitHub esté instalada correctamente, comprueba que los flujos de trabajo estén habilitados, asegúrate de que la clave de API esté configurada en los secretos del repositorio y confirma que el comentario contiene@claude (no /claude).
CI no se ejecuta en los commits de Claude
Asegúrate de estar usando la aplicación de GitHub o una aplicación personalizada (no el usuario de Acciones), 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 de API sea válida y tenga permisos suficientes. Para Bedrock/Vertex, comprueba la configuración de credenciales y asegúrate de que los secretos tengan los nombres correctos en los flujos de trabajo.Configuración avanzada
Parámetros de acción
Claude Code Action v1 usa una configuración simplificada:| Parámetro | Descripción | Requerido |
|---|---|---|
prompt | Instrucciones para Claude (texto o comando de barra diagonal) | No* |
claude_args | Argumentos de CLI pasados a Claude Code | No |
anthropic_api_key | Clave de 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 de 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 de GitHub personalizada: Para organizaciones que necesitan nombres de usuario personalizados o flujos de autenticación personalizados. Crea tu propia aplicación de GitHub con los permisos requeridos (contenidos, problemas, solicitudes de extracción) y usa la acción 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 PR y responder a solicitudes. Consulta nuestra documentación de memoria para más detalles. - Solicitudes personalizadas: 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.