Integrar Claude Code con GitHub

Si ya usas Claude Code en tu terminal, sabes lo cómodo que es delegarle tareas mientras tú piensas en el problema de fondo. Pero buena parte del trabajo real no ocurre en tu máquina: ocurre en GitHub. Los issues se abren ahí, las revisiones se piden ahí y el código se mergea ahí. Cada vez que saltas de un comentario de un PR a tu terminal para aplicar un cambio y volver, pierdes contexto y tiempo.

La integración de Claude Code con GitHub cierra ese hueco. Puedes mencionar a @claude en un issue para que implemente la solución y abra el PR, pedirle una revisión automática en cada pull request, o seguir trabajando desde tu terminal usando el gh CLI. En este artículo vemos cómo montarlo paso a paso, los casos de uso reales y las buenas prácticas de seguridad que conviene no saltarse.

Por qué integrar Claude Code con GitHub

Hay tres motivos principales para dar el salto de "Claude Code en local" a "Claude Code dentro de GitHub":

• Creación de PRs al instante. Describes lo que necesitas en un issue y Claude crea un pull request completo con todos los cambios, listo para revisar.
• Implementación automática desde issues. Un issue bien redactado se convierte en código funcional con una sola mención.
• Revisiones de código automáticas. Claude puede comentar cada PR buscando bugs, problemas de seguridad o desviaciones de tus convenciones, sin que nadie lo dispare a mano.

Además, todo respeta tu CLAUDE.md: las guías de estilo y los patrones de tu proyecto viajan con la integración, así que las sugerencias encajan con tu código en lugar de pelearse con él.

Dos formas de trabajar con GitHub

Antes de configurar nada, conviene distinguir los dos modos, que son complementarios:

Empecemos por el que más gente quiere: la GitHub App.

Instalar la GitHub App con /install-github-app

La vía recomendada y más rápida es ejecutar el comando de instalación desde la propia terminal de Claude Code:

/install-github-app

Este comando instala la GitHub App de Claude en tu repositorio y luego te guía para añadir los workflows de GitHub Actions y el secret con la API key. Un par de detalles importantes:

• Necesitas ser administrador del repositorio para instalar la app y añadir secrets.
• La app pide permisos de lectura y escritura sobre Contents, Issues y Pull requests (lo mínimo para modificar archivos, responder issues y abrir PRs).
• Desde Claude Code v2.1.187 puedes elegir "Skip for now" para dejar solo la app instalada y volver más tarde a los pasos del workflow y el secret ejecutando de nuevo /install-github-app.

Nota: este método rápido está pensado para quienes usan la API de Claude directamente. Si trabajas sobre Amazon Bedrock o Vertex AI, la configuración cambia y necesitas identidad federada (OIDC) en lugar de una API key.

El secret que necesitas

La autenticación se hace con un secret del repositorio. Tienes dos opciones:

• ANTHROPIC_API_KEY: tu API key de console.anthropic.com.
• CLAUDE_CODE_OAUTH_TOKEN: un token OAuth, que los usuarios Pro y Max pueden generar localmente con claude setup-token.

Sea cual sea, nunca lo escribas directo en el workflow: siempre como secret del repositorio.

Configuración manual (si prefieres el control)

Si el comando falla o quieres entender qué hace por debajo, los pasos manuales son tres:

1. Instala la GitHub App desde github.com/apps/claude sobre tu repositorio.
2. Añade ANTHROPIC_API_KEY a los secrets del repositorio (Settings → Secrets and variables → Actions).
3. Copia el workflow a .github/workflows/claude.yml.

Un workflow básico que responde a menciones de @claude en comentarios de issues y PRs se ve así:

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 los comentarios

La acción v1 (GA) detecta automáticamente si debe correr en modo interactivo (responder a @claude) o en modo automatización (ejecutarse con un prompt fijo), según cómo la configures. Cuando termines, prueba etiquetando a @claude en cualquier comentario.

Casos de uso: mencionar a @claude

Aquí es donde la integración brilla. En un comentario de un issue o un PR, escribes lenguaje natural y Claude analiza el contexto y actúa:

@claude implementa esta funcionalidad según la descripción del issue
@claude ¿cómo debería estructurar la autenticación de este endpoint?
@claude corrige el TypeError del componente del dashboard

El comportamiento depende de lo que pidas:

Revisiones automáticas en cada PR

Si quieres una revisión en cada pull request sin depender de que alguien mencione a Claude, dispara la acción con el evento pull_request. Este ejemplo instala el plugin oficial de code review y lo ejecuta en cada PR nuevo o actualizado:

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 }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

El flujo: rama, PR y tú revisando el diff

Este es el punto clave que hace que la integración sea segura y no un "agente suelto" en tu repo. Claude nunca mergea por su cuenta. El flujo es siempre el mismo:

1. Mencionas a @claude con la tarea.
2. Claude crea una rama nueva y hace ahí los commits.
3. Abre un pull request con los cambios y un resumen de lo que ha hecho.
4. Tú revisas el diff, comentas si algo no encaja (Claude puede iterar sobre tus comentarios) y decides si mergeas.

Tú sigues siendo la última verja. Claude propone; tú dispones.

Usar el gh CLI desde Claude Code

En tu terminal, Claude Code puede operar sobre GitHub a través del gh CLI oficial. Esto cubre lo que la app no hace desde local: crear PRs, abrir issues, consultar estados de CI, etc. Un ejemplo típico de lo que Claude ejecuta por ti:

# Crear una rama antes de tocar nada
git checkout -b fix/login-timeout

# ...cambios y commits...

# Abrir el PR con título y cuerpo
gh pr create --title "Corrige el timeout del login" \
  --body "Ajusta el TTL de la sesión y añade un test de regresión."

# Abrir un issue
gh issue create --title "Flaky test en el CI" --body "El test de auth falla 1 de cada 5 ejecuciones."

Algunas buenas prácticas que conviene tener grabadas (y dejar escritas en tu CLAUDE.md):

• Trabaja siempre en ramas, nunca directamente sobre main.
• No commitees ni hagas push a main sin permiso explícito. Que el cambio pase por un PR.
• Usa gh para las operaciones de GitHub en lugar de improvisar con la API a mano.
• Deja que abra PRs, no que mergee. El merge es una decisión humana.

Seguridad y buenas prácticas

Dar a un agente acceso de escritura a tu repositorio exige un mínimo de disciplina. Lo esencial:

Sobre costes: cada interacción consume minutos de GitHub Actions y tokens de la API. Menciones concretas, --max-turns ajustado y controles de concurrencia mantienen la factura a raya.

Conclusión y próximos pasos

Integrar Claude Code con GitHub no cambia quién manda: tú sigues revisando y mergeando. Lo que cambia es cuánto trabajo mecánico te quitas de encima. Menciones a @claude para convertir issues en PRs, revisiones automáticas que cazan bugs antes que tú, y el gh CLI para operar sin salir de la terminal.

Para empezar hoy mismo:

1. Ejecuta /install-github-app en un repositorio del que seas admin.
2. Añade el secret ANTHROPIC_API_KEY (o el token OAuth) y el workflow básico.
3. Abre un issue de prueba y menciona a @claude con una tarea pequeña.
4. Revisa el PR que te abra, comenta y, si te convence, mergea.

A partir de ahí, ve sumando: un workflow de revisión automática en los PRs y un CLAUDE.md afinado con tus convenciones. En una tarde tienes un compañero de equipo que trabaja donde vive tu código.