Crear y probar en Node.js

Introducción

Esta guía te muestra cómo crear un flujo de trabajo de integración continua (CI) que construye y prueba código Node.js. Si tus pruebas de CI se superan, es posible que desees implementar tu código o publicar un paquete.

Prerrequisitos

Te recomendamos que tengas una comprensión básica de Node.js, YAML, las opciones de configuración de flujo de trabajo y cómo crear un archivo de flujo de trabajo. Para más información, consulte:

• "Más información sobre GitHub Actions"
• "Introducción a Node.js"

Utilizar ejecutores auto-hospedados en GitHub Enterprise Server

Cuando use acciones de configuración, (como actions/setup-LANGUAGE) en GitHub Enterprise Server con ejecutores autohospedados, es posible que necesite configurar la caché de herramientas en los ejecutores que no tienen acceso a Internet. Para más información, vea "Configuración de la caché de herramientas en ejecutores autohospedados sin acceso a Internet".

Utilizar el flujo de trabajo inicial de Node.js

GitHub proporciona un flujo de trabajo inicial de Node.js que funcionará para la mayoría de los proyectos de Node.js. Esta guía incluye ejemplos de Yarn y de npm que puedes utilizar para personalizar el flujo de trabajo inicial. Para más información, vea el flujo de trabajo de inicio de Node.js.

Para comenzar rápidamente, agregue el flujo de trabajo de inicio al directorio .github/workflows del repositorio. En el flujo de trabajo que se muestra a continuación se asume que la rama predeterminada del repositorio es main.

name: Node.js CI

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

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [10.x, 12.x, 14.x, 15.x]

    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Ejecución en un sistema operativo diferente

El flujo de trabajo de inicio configura trabajos para que se ejecuten en Linux, mediante los ejecutores ubuntu-latest hospedados en GitHub. Puede cambiar la clave runs-on para ejecutar los trabajos en otro sistema operativo. Por ejemplo, puedes utilizar los ejecutores de Windows hospedados en GitHub.

runs-on: windows-latest

O puedes utilizar los ejecutores de macOS hospedados en GitHub.

runs-on: macos-latest

También puedes ejecutar jobs en contenedores de Docker, o puedes proporcionar un ejecutor auto-hospedado que se ejecute en tu propia infraestructura. Para más información, vea "Sintaxis de flujo de trabajo para GitHub Actions".

Especificar la versión de Node.js

La forma más fácil de especificar una versión de Node.js consiste en usar la acción setup-node proporcionada por GitHub. Para más información, vea setup-node.

La acción setup-node toma una versión de Node.js como entrada y la configura en el ejecutor. La acción setup-node busca una versión específica de Node.js en la caché de herramientas en cada ejecutor y agrega los archivos binarios necesarios a PATH, que se conserva para el resto del trabajo. El uso de la acción setup-node es la forma recomendada de utilizar Node.js con GitHub Actions, ya que garantiza el comportamiento coherente entre los distintos ejecutores y versiones de Node.js. Si va a usar un ejecutor autohospedado, debe instalar Node.js y agregarlo a PATH.

El flujo de trabajo inicial incluye una estrategia de matriz que compila y prueba tu código con cuatro versiones de Node.js: 10.x, 12.x, 14.x y 15.x. La 'x' es un carácter comodín que coincide con el último lanzamiento menor y de parche disponible para una versión. Cada versión de Node.js que se especifica en la matriz node-version crea un trabajo que ejecuta los mismos pasos.

Cada trabajo puede acceder al valor definido en la matriz node-version de matrices mediante el contexto matrix. La acción setup-node usa el contexto como entrada node-version. La acción setup-node configura cada trabajo con una versión diferente de Node.js antes de compilar y probar el código. Para más información sobre las estrategias y los contextos de matriz, vea "Sintaxis de flujo de trabajo para GitHub Actions" y "Contextos".

strategy:
  matrix:
    node-version: [10.x, 12.x, 14.x, 15.x]

steps:
- uses: actions/checkout@v2
- name: Use Node.js ${{ matrix.node-version }}
  uses: actions/setup-node@v2
  with:
    node-version: ${{ matrix.node-version }}

Como alternativa, puedes construir y probar con las versiones exactas de Node.js.

strategy:
  matrix:
    node-version: [8.16.2, 10.17.0]

O bien, puedes construir y probar mediante una versión única de Node.js.

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '12.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Si no especificas una versión de Node.js, GitHub utiliza la versión de Node.js por defecto del entorno. Para más información, vea "Especificaciones para ejecutores hospedados en GitHub".

Instalación de dependencias

Los ejecutores alojados en GitHub tienen instalados administradores de dependencias de npm y Yarn. Puedes usar npm y Yarn para instalar dependencias en tu flujo de trabajo antes de construir y probar tu código. Los ejecutores Windows y Linux alojados en GitHub también tienen instalado Grunt, Gulp y Bower.

Ejemplo con npm

En este ejemplo se instalan las dependencias definidas en el archivo package.json. Para más información, vea npm install.

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '12.x'
- name: Install dependencies
  run: npm install

El uso de npm ci instala las versiones en el archivo package-lock.json o npm-shrinkwrap.json, y evita las actualizaciones del archivo de bloqueo. El uso de npm ci suele ser más rápido que la ejecución de npm install. Para más información, vea npm ci e "Introducción de npm ci para compilaciones más rápidas y confiables".

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '12.x'
- name: Install dependencies
  run: npm ci

Ejemplo con Yarn

En este ejemplo se instalan las dependencias definidas en el archivo package.json. Para más información, vea yarn install.

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '12.x'
- name: Install dependencies
  run: yarn

Como alternativa, puede pasar --frozen-lockfile para instalar las versiones en el archivo yarn.lock y evitar actualizaciones en el archivo yarn.lock.

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '12.x'
- name: Install dependencies
  run: yarn --frozen-lockfile

Ejemplo de uso de un registro privado y la creación del archivo .npmrc

Puede usar la acción setup-node para crear un archivo .npmrc local en el ejecutor que configure el registro y el ámbito predeterminados. La acción setup-node también acepta un token de autenticación como entrada, que se usa para acceder a los registros privados o publicar paquetes de nodos. Para más información, vea setup-node.

Para autenticar tu registro privado, necesitarás almacenar tu token de autenticación de npm como un secreto. Por ejemplo, cree un secreto de repositorio denominado NPM_TOKEN. Para más información, vea "Creación y uso de secretos cifrados".

En el ejemplo siguiente, el secreto NPM_TOKEN almacena el token de autenticación de npm. La acción setup-node configura el archivo .npmrc para leer el token de autenticación de npm de la variable de entorno NODE_AUTH_TOKEN. Al usar la acción setup-node para crear un archivo .npmrc, debe establecer la variable de entorno NODE_AUTH_TOKEN con el secreto que contiene el token de autenticación de npm.

Antes de instalar las dependencias, use la acción setup-node para crear el archivo .npmrc. La acción tiene dos parámetros de entrada. El parámetro node-version establece la versión de Node.js y el parámetro registry-url establece el registro predeterminado. Si en el registro de paquetes se utilizan ámbitos, debe usar el parámetro scope. Para más información, vea npm-scope.

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    always-auth: true
    node-version: '12.x'
    registry-url: https://registry.npmjs.org
    scope: '@octocat'
- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

En el ejemplo anterior se crea un archivo .npmrc con el contenido siguiente:

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://registry.npmjs.org/
always-auth=true

Construir y probar tu código

Puedes usar los mismos comandos que usas de forma local para construir y probar tu código. Por ejemplo, si ejecuta npm run build para ejecutar los pasos de compilación definidos en el archivo package.json y npm test para ejecutar el conjunto de pruebas, tendría que agregar esos comandos en el archivo de flujo de trabajo.

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v2
  with:
    node-version: '12.x'
- run: npm install
- run: npm run build --if-present
- run: npm test

Empaquetar datos de flujo de trabajo como artefactos

Puedes guardar los artefactos de tus pasos de construcción y prueba para verlos después de que se complete un trabajo. Por ejemplo, es posible que debas guardar los archivos de registro, los vaciados de memoria, los resultados de las pruebas o las capturas de pantalla. Para más información, vea "Conservación de datos de flujo de trabajo mediante artefactos".

Publicar en registros de paquetes

Puedes configurar tu flujo de trabajo para que publique tu paquete Node.js en un registro de paquete después de que se aprueben tus pruebas de CI. Para más información sobre la publicación en npm y GitHub Packages vea "Publicación de paquetes de Node.js".