Puertas de Calidad

Bloquea las fusiones e implementaciones hasta que lint, las pruebas, la verificación de tipos y la auditoría de seguridad pasen en el código TypeScript de Node.js 24.

Receta

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

steps:
  - run: npm ci
  - run: npm run lint
  - run: npm run typecheck
  - run: npm run test
  - run: npm audit --audit-level=high
  - run: npm run build

Cuándo usarlo: Antes de cualquier implementación en staging o producción. Las puertas de calidad no son negociables para las API de producción de Node.

Ejemplo de Trabajo

{
  "scripts": {
    "lint": "eslint src --max-warnings 0",
    "typecheck": "tsc -p tsconfig.json --noEmit",
    "test": "vitest run --coverage",
    "test:unit": "vitest run --project unit",
    "test:integration": "vitest run --project integration",
    "build": "tsc -p tsconfig.json",
    "audit:ci": "npm audit --audit-level=high",
    "gates": "npm run lint && npm run typecheck && npm run test && npm run audit:ci && npm run build"
  }
}

# .github/workflows/ci.yml (extracto)
jobs:
  gates:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          cache: npm
      - run: npm ci
      - run: npm run gates
 
  docker-scan:
    needs: gates
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t api:ci .
      - uses: aquasecurity/trivy-action@master
        with:
          image-ref: api:ci
          severity: CRITICAL,HIGH
          exit-code: 1

Lo que esto demuestra:

• Un único script gates que los desarrolladores locales ejecutan antes de hacer push
• --max-warnings 0 trata las advertencias de lint como fallos
• Escaneo de Trivy en la imagen de Docker después de que pasen las puertas de la aplicación

Análisis Profundo

Orden y Costo de las Puertas

Puerta ESLint

// eslint.config.js extracto
export default [
  {
    rules: {
      "no-console": "error",
      "@typescript-eslint/no-floating-promises": "error",
    },
  },
];

Prohíbe console.log en src/; usa el registro estructurado.

Puerta de Verificación de Tipos

{
  "scripts": {
    "typecheck": "tsc -p tsconfig.json --noEmit"
  }
}

Ejecútalo en CI incluso si build emite tipos. --noEmit es más rápido para la retroalimentación de PR.

Umbral de Cobertura (Opcional)

// vitest.config.ts
export default {
  test: {
    coverage: {
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 70,
      },
    },
  },
};

Comienza con la cobertura de diferencias en los archivos cambiados si los umbrales de repositorio completo son demasiado estrictos inicialmente.

Protección de Ramas

Configura en GitHub:

• Requiere la verificación de estado gates (y docker-scan para las ramas de lanzamiento)
• Requiere revisión de PR
• Descarta aprobaciones obsoletas en nuevos commits

Errores Comunes

• Ruido de npm audit en dependencias transitivas - bloquea cada PR. Solución: audit-level=high, Renovate para actualizaciones, o un manual de npm audit fix.
• Omitir la verificación de tipos cuando build ejecuta tsc - la compilación puede omitir archivos estrictos. Solución: un trabajo typecheck explícito.
• Lint solo archivos cambiados en CI - la rama principal se desvía. Solución: lint todo src/ en cada ejecución (lo suficientemente rápido).
• Pruebas de integración sin contenedores de servicio - CI inestable. Solución: contenedores de servicio de postgres/redis en el flujo de trabajo.
• Escaneo de Docker solo en main - Dockerfile vulnerable en fusiones de PR. Solución: escanear en PR cuando Dockerfile cambie.
• Sin lockfile - npm ci falla o la auditoría no tiene sentido. Solución: forzar package-lock.json en el repositorio.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos básicos de CI/CD - estructura de la tubería
• GitHub Actions para Node - cableado del flujo de trabajo
• Verificación de tipos en CI - puertas de TypeScript
• Conceptos básicos de Linting - configuración de ESLint
• Mejores prácticas de CI/CD - lista de verificación de la sección

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