GitHub Actions para Node
Configura GitHub Actions para servicios Node.js 24 TypeScript: compilaciones en matriz, caché de npm, artefactos y despliegue OIDC.
Receta
Tarjeta de receta de referencia rápida: lista para copiar y pegar.
name: CI
on: [pull_request, push]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [22, 24]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: npm
- run: npm ci
- run: npm run lint && npm run typecheck && npm run testCuándo usarlo: Cada repositorio de Node en GitHub. Este es el esqueleto de CI predeterminado antes de los trabajos de Docker y despliegue.
Ejemplo de trabajo
# .github/workflows/ci.yml
name: CI
on:
pull_request:
push:
branches: [main]
concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
quality:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
node-version: [22, 24]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: npm
cache-dependency-path: package-lock.json
- name: Install
run: npm ci
- name: Lint
run: npm run lint
- name: Typecheck
run: npm run typecheck
- name: Test with coverage
run: npm run test -- --coverage
- name: Upload coverage
if: matrix.node-version == 24
uses: actions/upload-artifact@v4
with:
name: coverage
path: coverage/
retention-days: 7
docker:
needs: quality
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v6
with:
context: .
push: true
tags: |
ghcr.io/acme/api:${{ github.sha }}
ghcr.io/acme/api:main
cache-from: type=gha
cache-to: type=gha,mode=maxLo que esto demuestra:
- Matriz Node 22 y 24 para compatibilidad LTS
cache: npmcon clave en el archivo de bloqueo a través desetup-nodeconcurrencycancela las ejecuciones de PR superadas- Compilación de Docker solo en
maindespués de que el trabajo de calidad pase - Caché GHA de BuildKit para capas de imagen más rápidas
Análisis profundo
Comportamiento de la caché de npm
actions/setup-node@v4 con cache: npm hashea package-lock.json. Para monorepos:
cache-dependency-path: |
package-lock.json
services/api/package-lock.jsonArtefactos vs. Caché
| Característica | Usar para |
|---|---|
actions/cache | node_modules, capas de Docker |
actions/upload-artifact | Informes de cobertura, dist/ compilado, zips de Lambda |
- uses: actions/upload-artifact@v4
with:
name: lambda-zip
path: function.zipEl trabajo de despliegue posterior descarga el mismo zip probado en CI.
OIDC a AWS (sin claves estáticas)
permissions:
id-token: write
contents: read
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
aws-region: us-east-1La política de confianza en el rol de IAM se limita a repo:acme/api:ref:refs/heads/main.
Contenedores de servicio para pruebas de integración
services:
postgres:
image: postgres:16
env:
POSTGRES_PASSWORD: postgres
ports:
- 5432:5432
options: >-
--health-cmd pg_isready
--health-interval 5s
--health-timeout 3s
--health-retries 5
steps:
- run: npm run test:integration
env:
DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgresErrores comunes
npm installen lugar denpm ci- CI no reproducible. Solución: confirma el archivo de bloqueo; siemprenpm ci.- Matriz sin
fail-fast: false- un fallo en Node 22 oculta el resultado de Node 24. Solución: establecefail-fast: falseal comparar versiones. - Almacenar en caché
node_modulesmanualmente - a menudo más lento que la caché desetup-node. Solución: usa la caché de npm incorporada a menos que las herramientas de monorepo requieran rutas personalizadas. - Solo etiquetas de despliegue
:latest- no se puede revertir. Solución: siempre envía la etiqueta${{ github.sha }}. - Falta
concurrency- las pushes de PR en cola desperdician minutos. Solución: cancela las ejecuciones en curso en la misma rama. - Docker en cada PR sin filtro de ruta - lento y costoso. Solución:
paths: ['Dockerfile', 'src/**']o compila solo en main.
Alternativas
| Alternativa | Usar cuándo | No usar cuándo |
|---|---|---|
| GitHub Actions | Repositorio en GitHub | Organización solo de GitLab (usar GitLab CI) |
| CircleCI / Buildkite | Runners personalizados, monorepos grandes | Repositorios simples de un solo servicio |
| Nx Cloud / Turborepo | Grafo de tareas afectado | Aplicaciones pequeñas de un solo paquete |
| Runners autoalojados | Pruebas de GPU o internas de VPC | Repositorios públicos OSS predeterminados |
Preguntas frecuentes
¿Deberíamos usar una matriz con Node 20, 22 y 24?
Usa una matriz con 22 y 24 si soportas ambas líneas LTS activas. Elimina 20 cuando sea oficialmente obsoleto para tu producto.
¿Caché de pnpm o yarn?
- uses: pnpm/action-setup@v4
with:
version: 9
- uses: actions/setup-node@v4
with:
cache: pnpm¿Cuánto tiempo debe tardar la CI?
Menos de 10 minutos para las etapas unitarias. Divide las pruebas de integración lentas en un flujo de trabajo nocturno si es necesario.
¿Puede un flujo de trabajo hacer CI y CD?
Es posible, pero flujos de trabajo separados mejoran la claridad: ci.yml en PR, release.yml en etiqueta. Consulta Conceptos básicos de CI/CD.
¿Cómo ejecutamos Playwright?
Usa el paso npx playwright install --with-deps y divide las pruebas entre los trabajos de la matriz para suites grandes.
¿Escaneo de secretos?
Habilita el escaneo de secretos de GitHub y la acción gitleaks en los PR. Bloquea los commits con contenido .env.
Relacionado
- Conceptos básicos de CI/CD - Pipelines de PR vs. lanzamiento
- Puertas de calidad - Comprobaciones requeridas
- Entornos de vista previa - Flujos de trabajo de despliegue de PR
- Mejores prácticas de Docker - Compilación de imágenes en CI
- 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 activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.