GitHub Actions avanzado con Claude Code: permisos, OIDC, cache y matrix CI

GitHub Actions es sencillo cuando solo quieres ejecutar tests al hacer push. Lo difícil empieza cuando necesitas permisos mínimos, cache confiable, varias versiones de Node.js, despliegue a cloud sin claves largas y revisión con Claude Code sin exponer secretos.

Esta guía usa Claude Code como compañero de diseño de workflows, no como generador automático de YAML. Los ejemplos son workflows completos que puedes copiar, ajustar y ejecutar. La disciplina está en revisar por qué cada job necesita sus permisos, qué secrets puede leer y qué pasa cuando el pull request viene de un fork.

Verifiqué la guía actual con la documentación oficial de GitHub sobre workflow syntax, GITHUB_TOKEN permissions, AWS OIDC, dependency caching, concurrency y Claude Code GitHub Actions.

Arquitectura

Un workflow avanzado no es el que automatiza más cosas, sino el que reduce el radio de daño. Debe fallar con mensajes útiles, usar permisos estrechos, cancelar ejecuciones antiguas y dejar aprobación humana donde el cambio afecte producción.

flowchart LR
  PR["Pull request"] --> Gate["matrix test and lint"]
  Gate --> Cache["lockfile cache"]
  Gate --> Claude["Claude Code review"]
  Gate --> Deploy["OIDC deploy"]
  Deploy --> Env["GitHub environment approval"]
  Env --> AWS["AWS role"]

Algunos términos conviene aclararlos. Matrix es una tabla de combinaciones, por ejemplo Node.js 22 y 24 en Ubuntu y Windows. OIDC, OpenID Connect, permite cambiar una identidad temporal de GitHub Actions por credenciales cloud de corta duración. Así no guardas access keys largas de AWS en GitHub Secrets. Concurrency controla si una ejecución vieja debe seguir corriendo cuando llega un commit nuevo. Permissions define lo que puede hacer el GITHUB_TOKEN.

Casos de uso

El primer caso es un gate de calidad para pull requests. Ejecuta lint, type-check y tests en más de un runtime antes de hacer merge. Esto detecta problemas de rutas en Windows, diferencias entre versiones de Node.js y cambios incoherentes en el lockfile.

El segundo caso es deploy a staging. Cuando main pasa, GitHub Actions asume un IAM role de AWS con OIDC y despliega sin una clave estática. Producción debería agregar aprobación con GitHub Environment.

El tercer caso es CI compartido en monorepo. Si varios paquetes repiten Node setup, install y test, un reusable workflow evita que cada archivo YAML envejezca de forma distinta.

El cuarto caso es revisión de PR con Claude Code. Empieza con análisis y comentarios, no con escritura automática. Los permisos de escritura deben llegar después de branch protection, revisión obligatoria y plan de rollback.

Prompt para Claude Code

Pide primero diseño con restricciones, no solo un archivo YAML.

Design GitHub Actions for this repository.
The goals are pull request quality gates, staging deployment, and Claude Code review.

Constraints:
- Use least-privilege GITHUB_TOKEN permissions.
- Use OIDC for AWS. Do not store long-lived AWS access keys in Secrets.
- Include package-lock.json in dependency cache keys.
- Assume secrets are not available on forked pull requests.
- If pull_request_target is suggested, explain why PR head code is not checked out.
- Produce GitHub Actions YAML that is valid as written.

End with concrete failure cases and verification steps.

Con este prompt, Claude Code tiene que explicar decisiones de seguridad en lugar de rellenar una plantilla genérica.

Gate de calidad para PR

Este workflow usa actions/checkout@v6 y actions/setup-node@v6, versiones major actuales en junio de 2026. En runners hospedados por GitHub funciona normalmente. Si usas self-hosted runners, confirma primero la versión del runner.

name: pr-quality-gate

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

permissions:
  contents: read

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

jobs:
  test:
    name: node-${{ matrix.node }}-${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [22, 24]

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node }}
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npm run typecheck

      - name: Test
        run: npm test

El job solo necesita contents: read, porque no escribe en el repositorio. concurrency cancela runs antiguos del mismo branch. La cache depende de package-lock.json; evita cachear node_modules salvo que tengas una razón fuerte, porque los módulos nativos y las diferencias de sistema operativo pueden romperla.

Deploy a AWS con OIDC

El patrón seguro es registrar GitHub como OIDC provider en AWS, crear un IAM role limitado y restringir su trust policy por repository, branch o environment. En el workflow, id-token: write es obligatorio para pedir el token OIDC.

name: deploy-staging

on:
  workflow_dispatch:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

concurrency:
  group: deploy-staging
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    environment: staging

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/claude-code-github-actions-staging
          aws-region: ap-northeast-1

      - name: Verify caller identity
        run: aws sts get-caller-identity

      - name: Deploy
        run: |
          npm ci
          npm run build
          echo "Deploy command goes here"

Cambia el role ARN, la región y el comando de deploy. Para producción, usa otro environment y reviewers obligatorios.

Reusable workflow

Un reusable workflow sirve cuando varios workflows repiten la misma comprobación. También evita que una versión antigua de un action se quede escondida en un archivo olvidado.

# .github/workflows/reusable-node-check.yml
name: reusable-node-check

on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: string
        default: "24"

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Install
        run: npm ci

      - name: Check
        run: |
          npm run lint
          npm run typecheck
          npm test

Workflow que lo llama:

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

on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  node-check:
    uses: ./.github/workflows/reusable-node-check.yml
    with:
      node-version: "24"

No escondas diferencias reales dentro de un reusable workflow enorme. Si cada package necesita comandos distintos, pide a Claude Code separar setup común y pasos específicos.

Revisión de PR con Claude Code

Claude Code Action v1 usa anthropics/claude-code-action@v1, prompt y claude_args. No copies ejemplos antiguos de @beta o direct_prompt.

name: claude-pr-review

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

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

jobs:
  review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Claude Code review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this pull request as a senior engineer.
            Focus on security, broken tests, unnecessary permissions, and missing verification.
            Do not modify files. Leave concise review comments only.
          claude_args: |
            --max-turns 5

El if evita forks, porque los secrets del repositorio no suelen estar disponibles allí. Si necesitas soporte para forks, diseña una ruta de baja confianza que no exponga secrets ni ejecute código externo con permisos altos.

Fallos comunes

El fallo más peligroso es usar pull_request_target y hacer checkout del head del PR. Ese evento puede correr con permisos cercanos al repositorio base, así que ejecutar código de un fork externo puede exponer secrets.

Otro fallo es imprimir secrets para depurar. GitHub enmascara muchos valores exactos, pero cadenas derivadas, JSON, base64 y logs de herramientas externas pueden escaparse. Da a Claude Code nombres y usos de secrets, no valores.

La cache también falla cuando la key es demasiado amplia. key: node-cache puede restaurar dependencias viejas después de cambiar el lockfile. Usa cache-dependency-path o hashFiles('**/package-lock.json').

La matrix puede crecer demasiado. Dos sistemas operativos por dos versiones de Node.js está bien; tres sistemas, cuatro runtimes y ocho packages son 96 jobs. Usa una matrix pequeña en PR y cobertura amplia en nightly.

Por último, revisa las versiones de actions. En 2026 muchas actions oficiales usan runtimes de Node más nuevos. Con self-hosted runners, actualiza el runner antes de subir todos los workflows a major recientes.

Ruta de monetización

Un CI seguro mejora cambios que afectan ingresos: landing pages, templates de pago, checkout, formularios de lead y contenido de cursos. Para empezar solo, usa la chuleta gratuita de Claude Code. Para equipos que necesitan permissions, OIDC, revisión con Claude Code, branch protection y CI de monorepo sobre un repositorio real, revisa formación y consultoría Claude Code.

Lecturas relacionadas: setup de CI/CD, flujo Git, estrategia de testing y seguridad.

Resultado probado

Para este artículo extraje los bloques YAML del MDX y los validé con un parser YAML. Los ejemplos se parsean correctamente e incluyen on, permissions, concurrency, matrix, reusable workflow, deploy con OIDC y Claude Code Action v1. Antes de ejecutarlos, cambia el AWS role ARN, scripts npm, environment y secret ANTHROPIC_API_KEY.