Saltar al contenido

Plantilla de flujo de trabajo de GitHub Actions para Node.js

Última actualización

Este es un .github/workflows/ci.yml completo para un proyecto Node.js que usa npm. Instala las dependencias desde una caché, ejecuta lint, build y tests con dos versiones de Node y cancela las ejecuciones de pull request que han quedado obsoletas. Cópielo, ajuste los scripts para que coincidan con su package.json y haga commit.

El flujo de trabajo

name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        node: [20, 22]
    steps:
      - uses: actions/checkout@v4

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

      - run: npm ci
      - run: npm run lint --if-present
      - run: npm run build --if-present
      - run: npm test

Qué hacen las partes menos evidentes

  • permissions: contents: read limita el GITHUB_TOKEN automático a la lectura del repositorio. Añada más permisos por job solo cuando sea necesario.
  • concurrency asigna a cada pull request su propio grupo. Un nuevo push cancela la ejecución anterior. Los push a main no se cancelan, así que cada commit en main obtiene un resultado.
  • timeout-minutes: 15 evita que un test bloqueado consuma el valor predeterminado de seis horas. Configúrelo en aproximadamente el doble de su tiempo de ejecución habitual.
  • fail-fast: false permite que ambas versiones de Node terminen, así verá todos los fallos y no solo el primero.
  • cache: npm hace que setup-node guarde en caché la carpeta de descargas de npm (no node_modules), indexada por package-lock.json. Después, npm ci instala desde tarballs locales. Más detalles en cómo guardar en caché npm en GitHub Actions.
  • npm ci instala exactamente lo que indica el lockfile y falla si no está sincronizado. Úselo en lugar de npm install en CI.
  • --if-present omite los scripts que no haya definido, así la plantilla funciona en proyectos pequeños.

Variantes

pnpm o Yarn

Cambie la opción de caché y el comando de instalación. Para pnpm, añada pnpm/action-setup@v4 antes de setup-node y configure cache: pnpm. Consulte cómo guardar pnpm en caché y cómo guardar Yarn en caché.

Monorepo

Ejecute las tareas a través de su herramienta de build y use una caché remota para omitir los paquetes sin cambios. Consulte CI para monorepos de Nx y Turborepo.

Añadir un job de despliegue

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/deploy.sh

Use OIDC para las credenciales en la nube en lugar de claves almacenadas; consulte la entrada de glosario sobre OIDC.

macOS o Windows

Añádalos a la matriz con os: [ubuntu-latest, macos-latest] y runs-on: ${{ matrix.os }}. Utilícelos solo si publica en esas plataformas, ya que cuestan más por minuto.

Ejecútelo en máquinas más rápidas

Si sus tests son la parte lenta, cambie una línea y mantenga el resto:

    runs-on: [self-hosted, Linux, compiler-ci]

compiler.dev ejecuta el job en una máquina nueva de 8 vCPU / 16 GB. Si en algún momento no puede, el job vuelve a su runner original. Consulte precios y cómo acelerar GitHub Actions.

Preguntas frecuentes

¿Debo guardar node_modules en caché?

Normalmente no. Es más seguro guardar en caché la caché de descargas de npm y ejecutar npm ci, porque node_modules puede contener binarios específicos de la plataforma y npm ci lo elimina de todos modos.

¿Qué versiones de Node debo probar?

Las líneas LTS activas que soporta. Consulte el calendario de publicaciones de Node.js y descarte las versiones que han llegado al fin de su vida útil.

¿Cómo ejecuto las pruebas en paralelo?

Use los workers del test runner en local y test sharding entre varias máquinas. Jest y Vitest admiten --shard.

¿Por qué no se restaura mi caché?

Normalmente la ruta del lockfile es incorrecta o está en un ámbito de rama distinto. Lea sobre las claves de caché.