GitHub Actions

Llevamos el modo headless a GitHub: la Claude Code GitHub Action corre Claude dentro de tus workflows. Con un @claude en un PR o issue, analiza código, implementa features, arregla bugs y abre PRs — siguiendo tu CLAUDE.md. Aquí montas tu primer workflow, el artefacto del curso.

Instalación rápida

La forma más fácil, desde un Claude Code en tu terminal:

/install-github-app

Te guía para instalar la GitHub App en el repo y crear los secrets necesarios (debes ser admin del repo). La app pide permisos de lectura/escritura en Contents, Issues y Pull requests.

Si prefieres a mano: instala la app desde github.com/apps/claude, añade el secret ANTHROPIC_API_KEY a los secrets del repo, y copia el workflow de examples/claude.yml a .github/workflows/. El instalador hace exactamente esto por ti.

Tu primer disparo

Antes de personalizar nada, confirma que la Action está instalada y responde. Es un minuto:

1. En tu repo (GitHub web), abre un issue nuevo con cualquier título.
2. Una vez creado, escribe un comentario en él (el trigger más fiable, funciona con cualquier versión del workflow):

@claude resume este repo en tres líneas

3. Vete a la pestaña Actions del repo. En segundos aparece un run del workflow Claude Code con un job claude en estado amarillo (en curso) → verde (ok). Si no ves ningún run, salta a "Si falla".
4. Vuelve al issue. Claude postea un comentario de respuesta. Primero verás una casilla de progreso (un checklist tipo - [x] Leyendo el repo…) que se va actualizando, y al terminar el resumen final.

Si llegaste hasta aquí, la Action está viva y autenticada. Ese workflow que responde a @claude es el artefacto del curso; el resto de la lección es entender qué montó el instalador y cómo ampliarlo.

El workflow básico

Esto es lo que el instalador deja en .github/workflows/claude.yml (versión mínima). Responde a menciones @claude en comentarios de issues y PRs:

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 }}
          # Responde a las menciones @claude en comentarios

Con esto, en cualquier issue o PR puedes escribir:

@claude implementa esta feature según la descripción del issue
@claude arregla el TypeError del dashboard

Claude analiza el contexto y responde con un comentario. Pero para que pueda abrir un PR con los cambios (no solo comentar), el job necesita permisos de escritura — eso es lo siguiente.

Permisos: que Claude pueda abrir PRs

El workflow mínimo de arriba deja a Claude comentar, pero no escribir en el repo. Para que cree ramas y abra PRs, añade un bloque permissions: al job:

jobs:
  claude:
    runs-on: ubuntu-latest
    permissions:
      contents: write        # crear ramas y commits
      pull-requests: write   # abrir y comentar PRs
      issues: write          # comentar en issues
      id-token: write        # autenticación OIDC del runner
      actions: read          # leer resultados de CI en el PR
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Estos son los mismos permisos que pide la GitHub App al instalarse (Contents, Issues y Pull requests en lectura/escritura): el bloque permissions: se los concede también al GITHUB_TOKEN del job. El actions/checkout previo es lo que da a Claude el código del repo para trabajar. El claude.yml oficial trae este bloque ya puesto.

Pasar opciones con claude_args

Cualquier flag del CLI que viste en las lecciones anteriores se pasa por claude_args:

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Revisa este PR buscando problemas de seguridad"
    claude_args: |
      --append-system-prompt "Sigue nuestras convenciones"
      --max-turns 10
      --model claude-sonnet-4-6

Tareas recurrentes con schedule

Hasta aquí Claude reacciona a un @claude. Pero con un trigger schedule (cron) corre solo, sin que nadie lo mencione — p.ej. un informe diario. La clave: al no haber comentario que disparar, das un prompt directo y la Action entra en modo automático.

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"   # cada día a las 09:00 UTC
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Resume los commits de ayer y los issues abiertos"
          claude_args: "--model claude-sonnet-4-6"

Sin prompt, un schedule no tendría nada que ejecutar (no hay @claude que leer). Si además quieres que ese informe abra un PR o un issue, recuerda el bloque permissions: de antes.

Seguridad

Nunca metas la API key en el workflow: siempre como secret (${{ secrets.ANTHROPIC_API_KEY }}). Limita los permisos del job al mínimo y revisa lo que Claude propone antes de mergear. Tu CLAUDE.md del repo guía su comportamiento también aquí.

Vigila el coste: corre en runners de GitHub (consume tus minutos) y cada interacción gasta tokens. --max-turns y timeouts del workflow evitan jobs desbocados.

Si falla

Tu @claude no responde — ni comentario, ni run en Actions. Los tres culpables habituales, con cómo verificar cada uno:

• El secret ANTHROPIC_API_KEY no está (o está mal) → en GitHub web: Settings → Secrets and variables → Actions. Tiene que existir un secret con ese nombre exacto. Si el run aparece en Actions pero falla en el paso de Claude, abre los logs: un error de autenticación apunta aquí. Recréalo y relanza.
• La GitHub App no está instalada en ese repo → si en la pestaña Actions no aparece ningún run al mencionar @claude, es que la app no escucha ese repo. Ve a github.com/apps/claude → Configure, y confirma que tu repo está en la lista de "select repositories" (o reejecuta /install-github-app). Sin la app, el evento no dispara nada.
• El trigger_phrase no coincide → la frase por defecto es @claude. Si escribiste /claude no dispara (es un error clásico), y si en el workflow personalizaste trigger_phrase, tu comentario tiene que usar esa frase. Revisa el with: del workflow y el texto que escribiste.

Y si Claude responde pero no abre el PR que esperabas: no es el trigger, es el bloque permissions:. Sin contents: write y pull-requests: write solo puede comentar. Revísalo en el job.

Qué llevas hasta aquí

• La GitHub Action (anthropics/claude-code-action@v1) corre Claude en tus workflows.
• La instalas con /install-github-app y el secret ANTHROPIC_API_KEY; la disparas con @claude y lo confirmas con un run en la pestaña Actions.
• Para que abra PRs (no solo comente), el job necesita permissions: con contents: write y pull-requests: write.
• Pasas cualquier flag del CLI por claude_args, y con un trigger schedule + prompt lo corres sin menciones.

En la siguiente lección, el caso estrella: revisión de código automática en cada PR.

Fuente oficial: Claude Code GitHub Actions