CI/CD con Claude Code: GitHub Actions seguro para PR, despliegue y rollback

Pedirle a Claude Code “crea mi CI/CD” produce YAML rápido. Lo difícil es que ese YAML sea seguro para producción. Un pipeline útil debe bloquear Pull Requests rotos, no exponer Secrets a forks, separar staging de production, dejar la aprobación final en manos humanas y tener un camino claro de rollback.

En esta guía usamos Claude Code como compañero de diseño de CI/CD, no como una máquina de plantillas. CI significa integración continua: lint, tipos, pruebas y build se ejecutan en cada cambio. CD significa entrega o despliegue continuo: un cambio ya validado avanza hacia un entorno. Un gate es una condición que debe pasar antes del siguiente job. Secrets son valores privados como API keys. OIDC permite credenciales temporales y evita guardar claves cloud de larga vida en GitHub.

Revisa siempre la documentación oficial: Claude Code GitHub Actions, GitHub Actions workflow syntax, GITHUB_TOKEN permissions, GitHub Secrets y GitHub Environments. Los ejemplos usan GitHub-hosted runners y, a fecha 2026-06-03, actions/checkout@v6 y actions/setup-node@v6. Si usas self-hosted runners, valida primero la versión del runner.

Define el límite de automatización

Antes de escribir workflows, decide qué puede hacer Claude Code y qué queda como decisión humana. Claude Code puede leer el repositorio, proponer YAML, analizar logs y sugerir cambios. No debería ampliar permisos por sí solo, decidir una publicación de production, imprimir Secrets ni ejecutar código no confiable con eventos privilegiados.

Área	Buen trabajo para Claude Code	Decisión humana
PR checks	Crear lint, test, typecheck y build	Checks obligatorios y reglas de merge
PR review	Señalar riesgos, permisos y tests faltantes	Aceptar o rechazar el cambio
Deploy	Borrador para staging y production	Aprobación y alcance de Secrets
Recovery	Resumir logs y proponer rollback	Ejecutar rollback en production

Usa un prompt con restricciones:

Design CI/CD for this repository.
The goals are pull request quality gates, staging deployment, Claude Code review, and production rollback.

Constraints:
- Use least-privilege GITHUB_TOKEN permissions per job.
- Do not use secrets on forked pull requests.
- If pull_request_target is suggested, explain why PR head code is not checked out.
- Put production deployment behind a GitHub Environment approval.
- Never print ANTHROPIC_API_KEY, DEPLOY_TOKEN, or other secret values.
- Produce workflow YAML that can be placed under .github/workflows/.

End with failure cases, verification commands, and rollback steps.

Ese prompt funciona como harness, es decir, un marco seguro para el agente. Para reglas persistentes, escríbelas en CLAUDE.md; la guía de CLAUDE.md best practices explica cómo hacerlo sin llenar el archivo de reglas vagas.

Caso 1: gate de calidad en Pull Request

Empieza con un workflow que impida merges sin validar. Este ejemplo ejecuta lint, typecheck, test y build, y usa una matrix con Node.js 22 y 24.

# .github/workflows/ci.yml
name: ci

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    name: test-node-${{ matrix.node-version }}
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        node-version: [22, 24]
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm

      - run: npm ci
      - run: npm run lint --if-present
      - run: npm run typecheck --if-present
      - run: npm test -- --runInBand

  build:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    needs: test
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npm run build

Es ejecutable en un proyecto Node típico con npm test y npm run build. lint y typecheck usan --if-present para facilitar la primera migración, pero no los dejes así para siempre. Pide a Claude Code que lea package.json y deje solo gates reales. Para decidir qué pruebas merecen estar en CI, combina esto con testing strategies.

Caso 2: revisión de PR con Claude Code en modo lectura

Claude Code Action puede revisar cambios de workflow, exposición de Secrets, falta de tests, permisos excesivos y archivos no relacionados. La primera versión debería comentar, no modificar.

# .github/workflows/claude-pr-review.yml
name: claude-pr-review

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: write
  issues: write

concurrency:
  group: claude-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    if: >
      github.event.pull_request.draft == false &&
      github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
        with:
          persist-credentials: false

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          prompt: |
            Review this pull request as a CI/CD safety reviewer.
            Focus on GitHub Actions permissions, secrets exposure, test coverage,
            deployment gates, rollback risk, and unrelated file changes.
            Do not edit files. Leave concise review comments with evidence.
          claude_args: |
            --max-turns 4

La condición del fork evita que un workflow con Secrets corra en PRs externos. Si necesitas revisar contribuciones externas, separa checks sin Secrets de un workflow privilegiado que se ejecute solo tras aprobación humana. Ten mucho cuidado con pull_request_target: corre con el contexto del repositorio base. Si Claude Code lo propone, exige una explicación concreta. Para el marco completo, lee security best practices y Git workflow.

Caso 3: deploy gates para staging y production

Un patrón sano es desplegar main a staging automáticamente y dejar production detrás de workflow_dispatch y GitHub Environment approval. Los Secrets de production deben vivir en el Environment de production.

# .github/workflows/deploy.yml
name: deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  deployments: write

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run build

  deploy-staging:
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment: staging
    env:
      APP_ENV: staging
      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run deploy:staging

  deploy-production:
    if: github.event_name == 'workflow_dispatch'
    needs: deploy-staging
    runs-on: ubuntu-latest
    timeout-minutes: 10
    environment: production
    env:
      APP_ENV: production
      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run deploy:production

En push llega a staging. Production solo avanza cuando alguien lanza el workflow manualmente y aprueba el Environment. Este diseño reduce mucho el riesgo de publicar un error justo al hacer merge.

Caso 4: rollback antes del incidente

El rollback no se diseña bajo presión. Este workflow permite redeployar un commit concreto, con la aprobación del Environment production.

# .github/workflows/rollback-production.yml
name: rollback-production

on:
  workflow_dispatch:
    inputs:
      target_sha:
        description: "Commit SHA to redeploy to production"
        required: true
        type: string

permissions:
  contents: read
  deployments: write

jobs:
  rollback:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    environment: production
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ inputs.target_sha }}

      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npm run build
      - run: npm run deploy:production

Pide a Claude Code que revise deploy.yml y rollback-production.yml juntos: si un commit antiguo todavía builda, si las migraciones son reversibles, si staging y production difieren en variables, y cómo identificar el SHA desplegado. Para diagnóstico de logs, usa el build error triage loop.

Errores frecuentes

El primero es permissions: write-all. Puede hacer que todo pase, pero agranda el daño posible. Empieza con contents: read y añade solo permisos explicables.

El segundo es imprimir Secrets en logs. No hagas echo $DEPLOY_TOKEN. Verifica scope y nombre, nunca el valor.

El tercero es un gate falso. --if-present ayuda al migrar, pero la versión final debe fallar si falta un script obligatorio.

El cuarto es dar a Claude Code un log enorme. Mejor entrega el primer comando que falló, la primera línea de error útil, el resultado esperado y el comando local de reproducción.

Monetización y siguiente paso

CI/CD convierte bien porque el lector tiene un problema real de riesgo operativo. Un desarrollador individual puede empezar con ClaudeCodeLab products para CLAUDE.md, prompts de review y checklists. Un equipo que necesita branch protection, GitHub Actions, Secrets, approvals, rollback y Claude Code review en un repositorio real debería usar training and consultation.

Después lee Advanced GitHub Actions with Claude Code, testing strategies y security best practices. En la práctica, el mejor primer paso no es automatizar production, sino introducir el gate de PR y la revisión de Claude Code en modo lectura. Eso mejora las conversaciones de merge con evidencia antes de tocar el despliegue real.