Integración con GitHub Actions

Q: ¿npm audit falla en una dependencia transitiva que no podemos arreglar?

Documenta la excepción en docs/security-audit-exceptions.md con fecha de caducidad. No deshabilites permanentemente la auditoría en CI.

Un manual para GitHub Actions + protección de ramas en equipos de Node.js: comprobaciones obligatorias, lanzamientos impulsados por etiquetas y plantillas de PR que detectan brechas de migración y reversión antes de la fusión.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# .github/workflows/pr-checks.yml
name: PR Checks
on:
  pull_request:
    branches: [main]
 
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24.18.0"
          cache: npm
      - run: npm ci
      - run: npm run typecheck
      - run: npm run lint
      - run: npm test -- --ci
      - run: npm audit --audit-level=high

# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ["v*"]
 
jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24.18.0"
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npm test -- --ci
      # docker build + push to registry

<!-- .github/pull_request_template.md -->
## Resumen
 
## Ticket
<!-- API-___ -->
 
## Lista de verificación de API / DB
- [ ] OpenAPI o lista de rutas actualizada
- [ ] Migración incluida (o N/A)
- [ ] Plan de reversión documentado
- [ ] Compatibilidad del worker verificada (si el esquema de eventos cambió)
 
## CI
- [ ] Comprobación `quality` en verde localmente: `npm ci && npm run typecheck && npm test`

Protección de ramas (UI de GitHub):

Requerir comprobación de estado: quality
Requerir revisiones de PR: 1
Requerir historial lineal o fusión por squash (elección del equipo)
No permitir la omisión para main

Cuándo usarlo:

Primer repositorio de backend que pasa de "confía en mí, ejecuté las pruebas" a puertas forzadas
Desfase de lockfile que causa fallos solo en CI
Las implementaciones de producción sin etiquetar necesitan trazabilidad semver
Monorepo necesita filtros de ruta para omitir servicios no relacionados

Ejemplo de trabajo

Paso 1 - Coincidir scripts locales y de CI

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint src test",
    "test": "node --import tsx --test test/**/*.test.ts",
    "build": "tsc -p tsconfig.build.json"
  }
}

# .husky/pre-push
npm run typecheck && npm test

Paso 2 - Filtro de ruta de monorepo

on:
  pull_request:
    paths:
      - "services/orders-api/**"
      - "package-lock.json"
 
defaults:
  run:
    working-directory: services/orders-api

Paso 3 - Puerta de migración (trabajo opcional)

  db-lint:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run db:migrate
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test

Paso 4 - Comprobaciones obligatorias en la protección de ramas

Configuración → Ramas → main → Requerir comprobaciones de estado:
  ✓ quality
  ✓ db-lint (si hay migraciones en la PR)

Etiquetas de PR (Opcional)

Etiqueta	Efecto
`skip-audit`	Solo documentación; auditoría eximida con aprobación de seguridad
`has-migration`	Activa el trabajo db-lint
`worker-change`	Requiere nota de implementación de worker en la plantilla

Preguntas Frecuentes

¿npm audit falla en una dependencia transitiva que no podemos arreglar?

Documenta la excepción en docs/security-audit-exceptions.md con fecha de caducidad. No deshabilites permanentemente la auditoría en CI.

¿Matrix Node 20 y 24 durante la actualización?

Matriz temporal en las comprobaciones de PR durante la migración LTS. Elimina la versión N-2 cuando toda la flota esté en 24.18.0.

¿Quién puede subir etiquetas?

Restringe la creación de etiquetas a los gerentes de lanzamiento o al bot de CI. Las etiquetas activan la producción; protégelas con reglas.

Relacionado

Conceptos básicos de Git para equipos de Node - carriles de ramas y etiquetas
Mejores prácticas de Git y GitHub - resumen portátil
GitHub Actions para Node - matriz y artefactos
Mejores prácticas de administradores de paquetes - política de npm ci

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# .github/workflows/pr-checks.yml
name: PR Checks
on:
  pull_request:
    branches: [main]
 
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24.18.0"
          cache: npm
      - run: npm ci
      - run: npm run typecheck
      - run: npm run lint
      - run: npm test -- --ci
      - run: npm audit --audit-level=high

# .github/workflows/release.yml
name: Release
on:
  push:
    tags: ["v*"]
 
jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24.18.0"
          cache: npm
      - run: npm ci
      - run: npm run build
      - run: npm test -- --ci
      # docker build + push to registry

<!-- .github/pull_request_template.md -->
## Resumen
 
## Ticket
<!-- API-___ -->
 
## Lista de verificación de API / DB
- [ ] OpenAPI o lista de rutas actualizada
- [ ] Migración incluida (o N/A)
- [ ] Plan de reversión documentado
- [ ] Compatibilidad del worker verificada (si el esquema de eventos cambió)
 
## CI
- [ ] Comprobación `quality` en verde localmente: `npm ci && npm run typecheck && npm test`

Protección de ramas (UI de GitHub):

Requerir comprobación de estado: quality
Requerir revisiones de PR: 1
Requerir historial lineal o fusión por squash (elección del equipo)
No permitir la omisión para main

Cuándo usarlo:

Primer repositorio de backend que pasa de "confía en mí, ejecuté las pruebas" a puertas forzadas
Desfase de lockfile que causa fallos solo en CI
Las implementaciones de producción sin etiquetar necesitan trazabilidad semver
Monorepo necesita filtros de ruta para omitir servicios no relacionados

Ejemplo de trabajo

Paso 1 - Coincidir scripts locales y de CI

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint src test",
    "test": "node --import tsx --test test/**/*.test.ts",
    "build": "tsc -p tsconfig.build.json"
  }
}

# .husky/pre-push
npm run typecheck && npm test

Paso 2 - Filtro de ruta de monorepo

on:
  pull_request:
    paths:
      - "services/orders-api/**"
      - "package-lock.json"
 
defaults:
  run:
    working-directory: services/orders-api

Paso 3 - Puerta de migración (trabajo opcional)

  db-lint:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run db:migrate
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test

Paso 4 - Comprobaciones obligatorias en la protección de ramas

Configuración → Ramas → main → Requerir comprobaciones de estado:
  ✓ quality
  ✓ db-lint (si hay migraciones en la PR)

Etiquetas de PR (Opcional)

Etiqueta	Efecto
`skip-audit`	Solo documentación; auditoría eximida con aprobación de seguridad
`has-migration`	Activa el trabajo db-lint
`worker-change`	Requiere nota de implementación de worker en la plantilla

Preguntas Frecuentes

¿npm audit falla en una dependencia transitiva que no podemos arreglar?

Documenta la excepción en docs/security-audit-exceptions.md con fecha de caducidad. No deshabilites permanentemente la auditoría en CI.

¿Matrix Node 20 y 24 durante la actualización?

Matriz temporal en las comprobaciones de PR durante la migración LTS. Elimina la versión N-2 cuando toda la flota esté en 24.18.0.

¿Quién puede subir etiquetas?

Restringe la creación de etiquetas a los gerentes de lanzamiento o al bot de CI. Las etiquetas activan la producción; protégelas con reglas.

Relacionado

Conceptos básicos de Git para equipos de Node - carriles de ramas y etiquetas
Mejores prácticas de Git y GitHub - resumen portátil
GitHub Actions para Node - matriz y artefactos
Mejores prácticas de administradores de paquetes - política de npm ci

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Integración con GitHub Actions

Buscar en la documentación

Integración con GitHub Actions