Volver a Claude Code
Claude CodeAvanzado12 min de lectura

Workflows con GitHub Actions — Usa Claude Code en Tareas Repetidas del Equipo

Dónde encaja Claude Code en GitHub Actions, review automation y mantenimiento del repo sin sobreautomatizar lo que todavía necesita juicio humano

github-actionsautomatizacionreviewequipo

Referencias Oficiales: GitHub Actions · Overview · SDK

Ruta del currículo

  1. CLAUDE.md Mastery — memoria del repo y reglas
  2. Effective Prompting — framing de tareas y restricciones
  3. MCP Power Tools — herramientas y contexto vivo
  4. Multi-Agent Workflows — delegación y ejecución en paralelo
  5. Hooks Automation — enforcement local del flujo de trabajo
  6. GitHub Actions Workflows — automatización repetida de equipo ← Estás aquí
  7. Claude Loop Seguro del Primer Día — onboarding seguro para principiantes
  8. Playbook Claude para Refactor de Tamaño Medio — disciplina intermedia por lanes
  9. Gobernanza de Cambios de Alto Riesgo con Claude — control avanzado de release
  10. Manual Operativo de Claude — ritmo operativo a escala de equipo

Documentación oficial usada en esta guía

  • Claude Code dentro de GitHub ActionsGitHub Actions
  • Superficie de automatización y SDKSDK
  • Cómo encaja en workflows más ampliosOverview

Dónde Encaja Claude Code en Automatización de Equipo

Claude Code brilla en desarrollo interactivo, pero Anthropic también soporta su uso en GitHub Actions y flujos automatizados.

Buenos usos:

  • review de PRs con checklist
  • triage de issues
  • resúmenes de checks fallidos
  • borradores de release notes
  • tareas repetidas disparadas por labels o comentarios

Buenas Tareas para Automatizar

Funciona bien cuando el trabajo es:

  • acotado
  • revisable
  • asociado a un PR o issue real
  • útil aunque la decisión final siga siendo humana

Malas Tareas para Automatizar

No fuerces Claude Code en trabajos que requieren invención amplia, acceso muy sensible o cambios de alto riesgo sin review.

Patrón Práctico

  1. trigger por PR, issue o label
  2. contexto claro del repo
  3. Claude ejecuta un trabajo estrecho
  4. salida como comentario, resumen o artifact
  5. humano sigue en el camino del merge

Configuración Básica

Registrar la clave de API

Ve a Settings → Secrets and variables → Actions en tu repositorio y añade ANTHROPIC_API_KEY. Sin esta clave, el workflow no podrá ejecutarse.

Usar la acción oficial

Anthropic ofrece anthropics/claude-code-action@v1 como la forma oficial de ejecutar Claude Code dentro de GitHub Actions. No necesitas instalar ni configurar nada extra.

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Describe aquí la tarea que quieres que realice Claude."

Si tu repositorio tiene un archivo CLAUDE.md en la raíz, la acción lo lee automáticamente para entender las convenciones de código y la arquitectura del proyecto. Es una de las formas más sencillas de mejorar la calidad de la automatización.


Workflow de Revisión Automática de PRs

Claude publica comentarios de revisión automáticamente cada vez que se abre un PR o se añaden nuevos commits.

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Revisa este PR teniendo en cuenta:
            - Vulnerabilidades de seguridad
            - Problemas de rendimiento
            - Consistencia del estilo de código
            Proporciona feedback concreto y accionable como comentarios en el PR.

pull-requests: write es obligatorio en permissions. Sin él, la acción no puede publicar comentarios.

Los prompts específicos producen mejores resultados. "Revisa este código" es demasiado vago. "Concéntrate en riesgos de migración y gestión de errores faltante" le da a Claude un objetivo claro con resultados medibles.


Workflow de Triage de Issues

Cuando se registra un nuevo issue, Claude lo lee y automáticamente le asigna etiquetas y publica una respuesta inicial.

name: Issue Triage
on:
  issues:
    types: [opened]
 
jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Analiza este issue recién registrado:
 
            Título: ${{ github.event.issue.title }}
            Contenido: ${{ github.event.issue.body }}
 
            Por favor realiza lo siguiente:
            1. Clasifícalo como reporte de bug, solicitud de funcionalidad o pregunta
            2. Si faltan pasos de reproducción o contexto, publica un comentario solicitándolos
            3. Sugiere etiquetas apropiadas (bug, enhancement, question, needs-info)
            4. Evalúa la urgencia (critical, high, medium, low)
 
            Publica un resumen del triage como comentario en el issue.

El triage de issues es especialmente útil en proyectos de código abierto donde el volumen de issues entrantes hace que la primera respuesta manual sea lenta e inconsistente.


Workflow de Análisis de Fallos

Cuando un workflow de CI falla, Claude lee los logs, analiza la causa raíz y publica un comentario resumen en el PR relacionado.

name: Analyze Failure
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
 
jobs:
  analyze:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      actions: read
    steps:
      - name: Obtener logs del workflow
        id: logs
        uses: actions/github-script@v7
        with:
          script: |
            const logs = await github.rest.actions.downloadWorkflowRunLogs({
              owner: context.repo.owner,
              repo: context.repo.repo,
              run_id: context.payload.workflow_run.id,
            });
            return Buffer.from(logs.data).toString('utf-8').slice(0, 8000);
 
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Aquí están los logs del workflow de CI que ha fallado:
 
            ${{ steps.logs.outputs.result }}
 
            Por favor analiza:
            1. Qué falló primero
            2. La causa raíz más probable
            3. Próximos pasos concretos para solucionarlo
 
            Publica el análisis como comentario en el PR relacionado.

Pasar los logs completos consume muchos tokens. Recortarlos a la parte relevante con slice(0, 8000) o similar mantiene los costes razonables sin perder la información importante.


Seguridad y Permisos

Principio de mínimos privilegios

Otorga solo los permisos que el workflow realmente necesita. Si solo publica comentarios, pull-requests: write es suficiente. contents: write solo es necesario cuando la acción modifica archivos directamente.

permissions:
  contents: read        # leer código fuente
  pull-requests: write  # publicar comentarios en PRs
  issues: write         # publicar comentarios y aplicar etiquetas en issues
  # actions: read       # leer logs de workflows (solo cuando sea necesario)

Gestión de secretos

  • Guarda siempre ANTHROPIC_API_KEY en GitHub Secrets. Nunca la pongas directamente en los archivos de workflow.
  • Usa GitHub Environments si necesitas claves separadas por entorno.
  • Rota las claves de forma regular.

Límite de peticiones y consideraciones de coste

Cada ejecución de GitHub Actions que llama a la API de Claude consume créditos de la API de Anthropic. Algunos puntos a tener en cuenta:

  • En repositorios grandes, los PRs pueden abrirse con mucha frecuencia. Asociar un workflow de revisión a cada PR puede acumular costes rápidamente.
  • Usa filtros paths para ejecutar el workflow solo cuando cambien archivos relevantes.
  • Usa concurrency para evitar ejecuciones duplicadas en el mismo PR.
on:
  pull_request:
    paths:
      - "src/**"
      - "tests/**"
 
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Buenas Prácticas

1. Empieza con acciones de solo lectura

Comienza con comentarios, resúmenes y borradores antes de intentar acciones de escritura o auto-merge. Construye confianza en la calidad del output antes de ampliar el alcance.

2. Mantén a las personas en el camino del merge

Aunque los comentarios de Claude sean de alta calidad, la decisión final de hacer merge debe quedarse con un revisor humano. El comportamiento de auto-merge es tentador pero hace que el análisis de causas raíz sea mucho más difícil cuando algo sale mal.

3. Establece límites de tiempo

Evita workflows que se ejecuten indefinidamente usando timeout-minutes.

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 10

4. Usa CLAUDE.md para dar contexto del repo a la acción

Pon tus convenciones de código, decisiones de arquitectura y checklists de revisión en CLAUDE.md en la raíz del repositorio. La acción lo recoge automáticamente y produce resultados significativamente mejores cuando entiende el contexto del proyecto.

Ejemplo de contenido de CLAUDE.md para automatización:

## Reglas de Código
- TypeScript en modo strict obligatorio
- Todos los endpoints de API deben tener gestión de errores
- Las nuevas funcionalidades requieren tests
 
## Checklist de Revisión
- Verificar vectores de inyección SQL
- Comprobar autenticación y autorización
- Validar todos los inputs externos

5. Escribe prompts específicos

Los prompts vagos producen resultados vagos. Sé explícito sobre qué debe verificar Claude y en qué formato debe presentar el output. Trata el prompt como una descripción de puesto para un revisor cuidadoso.


Complementar con Guías del Repositorio

La automatización mejora cuando el repo ya tiene instrucciones sólidas.

Fuentes de guía útiles:

  • CLAUDE.md para reglas de código y arquitectura
  • plantillas de issues para dar forma a las tareas
  • checklists de revisión para política estable
  • hooks para enforcement local durante el trabajo interactivo

Si las guías de tu repo son débiles, la automatización de GitHub solo escalará la ambigüedad más rápido.

Automatización Avanzada con el SDK

Además de la acción oficial, puedes usar el CLI de Claude Code directamente en CI para tener un control más preciso.

name: Claude Code CI Tasks
on:
  push:
    branches: [main]
 
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
 
      - name: Security Audit
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Audit the files changed in this push for security vulnerabilities. \
            Focus on: SQL injection, XSS, auth bypasses. \
            Output a markdown summary." \
            --output-format text > security-report.md
 
      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: security-report
          path: security-report.md
  • El CLI te da más control que la acción: formatos de salida personalizados, piping y encadenamiento.
  • Usa --model haiku para análisis masivos con coste reducido.
  • Combínalo con --allowedTools "Read,Glob,Grep" para restringir a operaciones de solo lectura.

Generación Automática de Release Notes

Cuando se crea un release, Claude analiza el historial de commits y genera las notas de lanzamiento automáticamente.

name: Release Notes
on:
  release:
    types: [created]
 
jobs:
  generate-notes:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for commit analysis
 
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Generate release notes for tag ${{ github.event.release.tag_name }}.
 
            Analyze all commits since the previous tag:
            1. Group changes by category (Features, Bug Fixes, Performance, Documentation)
            2. Write user-facing descriptions (not commit hashes)
            3. Highlight breaking changes with ⚠️ prefix
            4. Include migration steps if needed
 
            Format as GitHub-flavored markdown.
            Update the release body with the generated notes.
  • fetch-depth: 0 es imprescindible: Claude necesita el historial completo de git para comparar tags.
  • Funciona mejor con Conventional Commits (feat:, fix:, breaking:).
  • Combínalo con reglas en CLAUDE.md sobre el formato de tu changelog para obtener resultados más consistentes.

Estrategia Matrix para Reviews en Paralelo

Ejecuta múltiples revisiones especializadas en paralelo usando la estrategia matrix de GitHub Actions.

name: Multi-Aspect Review
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  review:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        aspect:
          - name: security
            prompt: "Review for OWASP Top 10 vulnerabilities, injection risks, and auth issues"
          - name: performance
            prompt: "Review for N+1 queries, memory leaks, unnecessary re-renders, and heavy computations"
          - name: maintainability
            prompt: "Review for code duplication, complex functions (>20 lines), missing error handling, and unclear naming"
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            You are a ${{ matrix.aspect.name }} specialist.
            ${{ matrix.aspect.prompt }}
 
            Be specific: reference file names and line numbers.
            If no issues found, say "✅ No ${{ matrix.aspect.name }} issues found."
  • Cada aspecto se ejecuta en un job separado, es decir, verdadero paralelismo, no ejecución secuencial.
  • Cada revisión se enfoca en una sola dimensión, evitando revisiones amplias pero superficiales.
  • Coste: aproximadamente 3x el de una revisión única, pero mucho más exhaustivo.
  • Agrega if: contains(github.event.pull_request.labels.*.name, 'deep-review') para activarlo solo cuando sea necesario.

Automatización de Actualización de Dependencias

Ejecuta una revisión semanal de dependencias y crea PRs automáticamente para parches de seguridad.

name: Weekly Dependency Check
on:
  schedule:
    - cron: "0 9 * * 1"  # Every Monday at 9 AM
  workflow_dispatch:  # Manual trigger
 
jobs:
  check-deps:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
 
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Check for outdated dependencies in this project:
 
            1. Run `npm outdated` (or equivalent for the package manager used)
            2. For each outdated package, check:
               - Is it a major version bump? (potential breaking changes)
               - Does the changelog mention security fixes?
               - Are there known vulnerabilities? (check `npm audit`)
            3. Create a summary categorized by:
               - 🔴 Security patches (update immediately)
               - 🟡 Minor updates (safe to update)
               - 🟠 Major updates (needs review)
            4. If there are security patches, create a PR with those updates
 
            Be conservative — only auto-update for security patches.
            Major version bumps should only be recommended, not applied.
  • Programa con cron para mantenimiento regular.
  • workflow_dispatch permite ejecuciones manuales cuando sea necesario.
  • Enfoque conservador: PR automático solo para seguridad, recomendaciones para todo lo demás.
  • Combínalo con reglas en CLAUDE.md sobre políticas de gestión de dependencias.

Claude vs Codex en CI

  • Claude: mejor para review, síntesis y explicación
  • Codex: mejor para ejecución acotada, cambios y validación

Empieza Comentando, No Mergeando

El mejor primer paso suele ser automatización que comenta, resume o redacta, no que mergea sola.

Ejemplos:

  • comentarios de revisión en PRs
  • resúmenes de fallos en trabajos de CI
  • release notes generadas

Saltar directamente a comportamiento de merge autónomo suele ser el punto de partida equivocado.

El Valor Real

El beneficio real no es la autonomía llamativa. Es hacer que los flujos de trabajo repetidos del equipo sean más rápidos, más consistentes y más fáciles de revisar.

Ahí es donde la automatización con Claude Code se vuelve genuinamente útil.

Guías Conectadas