Claude Code GitHub Actions

Claude Code GitHub Actions lleva la automatización impulsada por IA a tu flujo de trabajo de GitHub.

Al mencionar simplemente en un PR o Issue@claude, Claude puede analizar código, crear Pull Requests, implementar funciones y corregir bugs, mientras sigue los estándares de tu proyecto.

¿Por qué usar Claude Code GitHub Actions?

  • Creación instantánea de PR: describe tu necesidad y Claude creará un Pull Request completo
  • Implementación automatizada de código: convierte un Issue en código funcional con un solo comando
  • Sigue los estándares del proyecto: respeta tusCLAUDE.mdguías y patrones de código existentes
  • Simple y rápido: comienza a usarlo en minutos
  • Seguro y confiable: el código se ejecuta en el runner de GitHub

Inicio rápido

Método 1: Instalación automática (recomendado)

Ejecuta en la terminal de Claude Code:

/install-github-app

Esto te guiará a través de:

  • Configurar la GitHub App
  • Agregar los Secrets necesarios

Requisitos: debes ser administrador del repositorio. La GitHub App necesita permisos de lectura y escritura para Contents, Issues y Pull requests. Solo se aplica a usuarios que usan directamente la API de Claude (no compatible con AWS Bedrock ni Google Vertex AI).

Método 2: Instalación manual

Paso 1: Instalar la GitHub App de Claude

Visita:https://github.com/apps/claude

Permisos necesarios:

  • Contents: permisos de lectura y escritura
  • Issues: permisos de lectura y escritura
  • Pull requests: permisos de lectura y escritura

Paso 2: Agregar la clave de API

Agrega en los Secrets del repositorioANTHROPIC_API_KEY

Paso 3: Crear el archivo de flujo de trabajo

Copia desde el archivo de ejemplo:examples/claude.ymlllegar.github/workflows/

Configuración del flujo de trabajo

Flujo de trabajo básico (responde a menciones @claude)

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Revisión automática de código

name: Code Review
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Review this pull request for code quality, correctness, and security."
          claude_args: "--max-turns 5"

Tareas programadas

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Generate a summary of yesterday's commits and open issues"
          claude_args: "--model opus"

Comandos comunes de @claude

Usa en comentarios de PR o Issue:

@claude implement this feature based on the issue description
@claude how should I implement user authentication for this endpoint?
@claude fix the TypeError in the user dashboard component
@claude review this PR for security issues
@claude add tests for this new function

Explicación detallada de los parámetros de Action

Parámetro Descripción ¿Obligatorio?
prompt Instrucciones para Claude (texto plano o nombre de habilidad) No*
claude_args Parámetros de CLI que se pasan a Claude Code no
anthropic_api_key Clave de API de Claude Sí**
github_token Token de GitHub (para acceso a la API) no
trigger_phrase Palabra de activación personalizada (por defecto:@claude） no
use_bedrock Usar AWS Bedrock en lugar de la API de Claude no
use_vertex Usar Google Vertex AI en lugar de la API de Claude no

*Cuando se usa en comentarios de issue/PR, omite el prompt y Claude responderá a la palabra de activación

**Obligatorio cuando se usa directamente la API de Claude; no necesario con Bedrock/Vertex

Parámetros comunes de CLI

Parámetro Descripción
--max-turns Máximo de rondas de conversación (por defecto 10)
--model Modelo a usar (por ejemploclaude-sonnet-4-6）
--mcp-config Ruta del archivo de configuración de MCP
--allowedTools Herramientas permitidas (separadas por comas)
--append-system-prompt Añadir prompt de sistema
--debug Activar salida de depuración

Ejemplos de claude_args

claude_args: |
  --max-turns 5
  --model claude-sonnet-4-6
  --mcp-config /path/to/config.json
  --append-system-prompt "Follow our coding standards"

Integración con AWS Bedrock

Requisitos previos

  • Acceso a AWS Bedrock habilitado, incluidos los permisos de los modelos Claude
  • GitHub configurado como proveedor de identidad OIDC en AWS
  • Rol de IAM con permisos de Bedrock

Secrets necesarios

Nombre del Secret Descripción
AWS_ROLE_TO_ASSUME ARN del rol de IAM para acceso a Bedrock
APP_ID GitHub App ID
APP_PRIVATE_KEY Clave privada de la GitHub App

Ejemplo de flujo de trabajo con Bedrock

name: Claude PR Action
permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude-pr:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude'))
    runs-on: ubuntu-latest
    env:
      AWS_REGION: us-west-2
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Configure AWS Credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
          aws-region: us-west-2

      - uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          use_bedrock: "true"
          claude_args: '--model us.anthropic.claude-sonnet-4-6 --max-turns 10'

Integración con Google Vertex AI

Requisitos previos

  • API de Vertex AI habilitada en el proyecto de GCP
  • Workload Identity Federation configurado para GitHub
  • Cuenta de servicio con permisos de Vertex AI

Secrets necesarios

Nombre del Secret Descripción
GCP_WORKLOAD_IDENTITY_PROVIDER Nombre del recurso del Workload Identity Provider
GCP_SERVICE_ACCOUNT Correo electrónico de la cuenta de servicio con acceso a Vertex AI
APP_ID GitHub App ID
APP_PRIVATE_KEY Clave privada de la GitHub App

Ejemplo de flujo de trabajo con Vertex AI

name: Claude PR Action
permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

on:
  issue_comment:
    types: [created]

jobs:
  claude-pr:
    if: github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Generate GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Authenticate to Google Cloud
        id: auth
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}

      - uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ steps.app-token.outputs.token }}
          trigger_phrase: "@claude"
          use_vertex: "true"
          claude_args: '--model claude-sonnet-4-5@20250929 --max-turns 10'
        env:
          ANTHROPIC_VERTEX_PROJECT_ID: ${{ steps.auth.outputs.project_id }}
          CLOUD_ML_REGION: us-east5

Actualización desde la versión Beta (cambios importantes en v1.0)

Entradas Beta Nuevas entradas de v1.0
mode (eliminado - detección automática)
direct_prompt prompt
override_prompt con variables de GitHubprompt
custom_instructions claude_args: --append-system-prompt
max_turns claude_args: --max-turns
model claude_args: --model
allowed_tools claude_args: --allowedTools
disallowed_tools claude_args: --disallowedTools

Comparación antes y después de la actualización

Versión Beta:

- uses: anthropics/claude-code-action@beta
  with:
    mode: "tag"
    direct_prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    custom_instructions: "Follow our coding standards"
    max_turns: "10"
    model: "claude-sonnet-4-6"

Versión GA (v1.0):

- uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR for security issues"
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: |
      --append-system-prompt "Follow our coding standards"
      --max-turns 10
      --model claude-sonnet-4-6

Solución de problemas

Claude no responde a los comandos @claude

  • Confirma que la GitHub App esté instalada correctamente
  • Verifica que el flujo de trabajo esté habilitado
  • Asegúrate de que la clave de API esté configurada en los Secrets del repositorio
  • Confirma que el comentario contiene@claude(no/claude）

CI no se ejecuta en los commits de Claude

  • Usa la GitHub App o una app personalizada (no uses el usuario de Actions)
  • Verifica que los activadores del flujo de trabajo incluyan los eventos necesarios
  • Confirma que los permisos de la app incluyan los activadores de CI

Errores de autenticación

  • Confirma que la clave de API sea válida y tenga permisos suficientes
  • Para Bedrock/Vertex: verifica la configuración de credenciales
  • Asegúrate de que los nombres de los Secrets sean correctos en el flujo de trabajo

Consideraciones de seguridad

  • Nunca confirmes claves de API directamenteen el repositorio
  • Usa GitHub Secrets para almacenar las claves de API:${{ secrets.ANTHROPIC_API_KEY }}
  • Limita los permisos de la action y otorga solo los permisos necesarios
  • Revisa las sugerencias de Claude antes del merge
  • Para AWS/GCP: usar proveedores de identidad OIDC en lugar de credenciales estáticas.
  • Crear cuentas de servicio dedicadas para cada repositorio.

Consideraciones de costos

Estructura de costos

  • Tarifas de GitHub Actions.: al ejecutar en runners alojados en GitHub, se consumen minutos de GitHub Actions.
  • Tarifas de API.: cada interacción con Claude consume tokens de API según la longitud de la solicitud/respuesta.

Sugerencias para optimizar costos

  • Usar comandos específicos.@claudepara reducir llamadas de API innecesarias
  • Configurar límites adecuados.--max-turnsde turnos de conversación
  • Configurar el tiempo de espera del flujo de trabajo para evitar que las tareas se salgan de control.
  • Usar el control de concurrencia de GitHub para limitar la ejecución en paralelo.

Mejores prácticas

1. Crear CLAUDE.md

En la raíz del repositorio, crearCLAUDE.mdun archivo, definiendo las guías de estilo de código y las reglas específicas del proyecto:

# 项目开发规范

## 代码风格
- 使用 TypeScript 4.x
- 遵循 ESLint 配置
- 函数必须有 JSDoc 注释

## PR 要求
- 必须通过所有 CI 检查
- 至少一个代码审查
- 更新相关文档

## 禁止事项
- 不要修改 `migrations/` 目录
- 不要提交 `.env` 文件

2. Usar comandos @claude específicos

@claude review this PR for SQL injection vulnerabilities
@claude add unit tests for the new validateEmail function

3. Configurar límites apropiados

jobs:
  claude:
    runs-on: ubuntu-latest
    timeout-minutes: 15  # 设置超时
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          claude_args: "--max-turns 5 --allowedTools Read,Grep,Glob,Bash,Write,Edit"

4. Escenarios de automatización CI/CD

  • Revisión automática de PR.: activar automáticamente la revisión cuando se abra o actualice un PR.
  • Clasificación automática de Issues.: agregar automáticamente etiquetas y asignar cuando se cree un nuevo Issue.
  • Informes programados.: generar diariamente informes de estadísticas de código o de seguridad.
  • Corrección automática.: analizar automáticamente e intentar corregir cuando la CI falle.
Otras extensiones.