Création et test de code Node.js

Introduction

Ce guide explique comment créer un workflow d’intégration continue (CI) qui génère et teste du code Node.js. Si vos tests CI réussissent, vous pouvez déployer votre code ou publier un package.

Il est recommandé d’avoir une compréhension de base du Node.js, du YAML, des options de configuration de workflows et de la création de fichiers de workflow. Pour plus d'informations, consultez les pages suivantes :

« Écriture de workflows »
« Bien démarrer avec Node.js »

Utilisation d’un modèle de workflow Node.js

Pour démarrer rapidement, ajoutez un modèle de workflow au répertoire .github/workflows de votre référentiel.

GitHub fournit un modèle de workflow pour Node.js qui devrait fonctionner pour la plupart des projets Node.js. Les sections suivantes de ce guide donnent des exemples de la manière dont vous pouvez personnaliser ce modèle de workflow.

Sur GitHub, accédez à la page principale du référentiel.
Sous le nom de votre dépôt, cliquez sur Actions.
Si vous disposez déjà d’un workflow dans votre dépôt, cliquez sur Nouveau workflow.
La page « Choisir un workflow » présente une sélection de modèles de workflow recommandés. Recherchez « Node.js ».
Filtrez la sélection des flux de travail en cliquant sur Intégration continue.
Dans le flux de travail « Node.js », cliquez sur Configurer.
Modifiez le workflow en fonction des besoins. Par exemple, changez les versions de Node que vous voulez utiliser.
Cliquez sur Valider les changements.

Le fichier de workflow node.js.yml est ajouté à l’annuaire .github/workflows de votre référentiel.

Spécification de la version de Node.js

Le moyen le plus simple de spécifier une version Node.js consiste à utiliser l’action setup-node fournie par GitHub. Pour plus d’informations, consultez setup-node.

L’action setup-node prend une version Node.js en tant qu’entrée et configure cette version sur l’exécuteur. L’action setup-node recherche une version spécifique de Node.js dans le cache d’outils de chaque exécuteur et ajoute les fichiers binaires nécessaires à PATH, qui est conservé pour la suite du travail. L’action setup-node est recommandée pour utiliser Node.js avec GitHub Actions, car cela garantit un comportement cohérent sur tous les exécuteurs et toutes les versions de Node.js. Si vous utilisez un exécuteur auto-hébergé, vous devez installer Node.js et l’ajouter à PATH.

Le modèle de workflow comprend une stratégie de matrice qui permet de générer et de tester votre code avec les versions de Node.js répertoriées dans node-version. Le « x » dans le numéro de version est un caractère générique qui correspond à la dernière version mineure et corrective disponible d’une version donnée. Chaque version de Node.js spécifiée dans le tableau node-version crée un travail qui exécute les mêmes étapes.

Chaque travail peut accéder à la valeur définie dans le tableau matriciel node-version à l’aide du contexte matrix. L’action setup-node utilise le contexte comme entrée node-version. L’action setup-node configure chaque travail avec une version de Node.js différente avant de générer et de tester le code. Pour plus d’informations sur les stratégies de matrice et les contextes, consultez « Workflow syntax for GitHub Actions » et « Accès à des informations contextuelles sur l’exécution d’un workflow ».

YAML

strategy:
  matrix:
    node-version: ['18.x', '20.x']

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

strategy:
  matrix:
    node-version: ['18.x', '20.x']

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

Vous pouvez également créer et tester du code avec des versions exactes de Node.js.

YAML

strategy:
  matrix:
    node-version: ['10.17.0', '17.9.0']

strategy:
  matrix:
    node-version: ['10.17.0', '17.9.0']

Enfin, vous pouvez générer et tester du code à l’aide d’une seule version de Node.js.

YAML

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

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

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

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

Si vous ne spécifiez pas de version Node.js, GitHub utilise la version par défaut de l’environnement Node.js. Pour plus d’informations, consultez « Utilisation des exécuteurs hébergés par GitHub ».

Installer les dépendances

Des gestionnaires de dépendances npm et Yarn sont installés sur les exécuteurs qui sont hébergés dans GitHub. Vous pouvez utiliser npm et Yarn pour installer des dépendances dans votre workflow avant de générer et de tester votre code. Les exécuteurs Windows et Linux hébergés dans GitHub disposent également de Grunt, Gulp et Bower.

Vous pouvez également mettre en cache vos dépendances pour accélérer vos exécutions de workflow. Pour plus d’informations, consultez « Mise en cache des dépendances pour accélérer les workflows ».

Exemple d’utilisation de npm

Cet exemple installe les versions dans le fichier package-lock.json ou npm-shrinkwrap.json et empêche les mises à jour du fichier verrouillé. L’utilisation de npm ci est généralement plus rapide que l’exécution de npm install. Pour plus d’informations, consultez npm ci et « Présentation de npm ci pour des builds plus rapides et plus fiables ».

YAML

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

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

Si vous utilisez npm install, les dépendances définies dans le fichier package.json sont installées. Pour plus d’informations, consultez npm install.

YAML

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

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

Exemple d’utilisation de Yarn

Cet exemple installe les dépendances définies dans le fichier yarn.lock et empêche les mises à jour du fichier yarn.lock. Pour plus d’informations, consultez yarn install.

YAML

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

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

Vous pouvez également installer les dépendances définies dans le fichier package.json.

YAML

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

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

Exemple d’utilisation d’un registre privé et de création du fichier .npmrc

Vous pouvez utiliser l’action setup-node pour créer un fichier .npmrc local sur l’exécuteur, qui configure le registre et l’étendue par défaut. L’action setup-node accepte également un jeton d’authentification en tant qu’entrée. Celui-ci est utilisé pour accéder à des registres privés ou pour publier des packages de nœuds. Pour plus d’informations, consultez setup-node.

Pour vous authentifier auprès de votre registre privé, vous devez stocker votre jeton d’authentification npm en tant que secret. Par exemple, créez un secret de dépôt appelé NPM_TOKEN. Pour plus d’informations, consultez « Utilisation de secrets dans GitHub Actions ».

Dans l’exemple ci-dessous, le secret NPM_TOKEN stocke le jeton d’authentification npm. L’action setup-node configure le fichier .npmrc pour lire le jeton d’authentification npm à partir de la variable d’environnement NODE_AUTH_TOKEN. Lorsque vous utilisez l’action setup-node pour créer un fichier .npmrc, vous devez définir la variable d’environnement avec le secret NODE_AUTH_TOKEN qui contient votre jeton d’authentification npm.

Avant d’installer des dépendances, utilisez l’action setup-node pour créer le fichier .npmrc. L’action a deux paramètres d’entrée. Le paramètre node-version définit la version Node.js, et le paramètre registry-url définit le registre par défaut. Si votre registre de package utilise des étendues, vous devez utiliser le paramètre scope. Pour plus d’informations, consultez npm-scope.

YAML

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

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

L’exemple ci-dessus crée un fichier .npmrc avec le contenu suivant :

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

Exemple de mise en cache des dépendances

Vous pouvez mettre en cache et restaurer les dépendances à l’aide de l’action setup-node.

L’exemple suivant met en cache les dépendances pour npm.

YAML

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'
- run: npm install
- run: npm test

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'
- run: npm install
- run: npm test

L’exemple suivant met en cache les dépendances pour Yarn.

YAML

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'yarn'
- run: yarn
- run: yarn test

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'yarn'
- run: yarn
- run: yarn test

L’exemple suivant met en cache les dépendances pour pnpm (v6.10+).

YAML

# Ce workflow utilise des actions qui ne sont pas certifiées par GitHub.
# Elles sont fournies par un tiers et régies par
# des conditions d’utilisation du service, une politique de confidentialité et un support distincts.
# documentation en ligne.

# NOTE: pnpm caching support requires pnpm version >= 6.10.0

steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
  with:
    version: 6.10.0
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

# Ce workflow utilise des actions qui ne sont pas certifiées par GitHub.
# Elles sont fournies par un tiers et régies par
# des conditions d’utilisation du service, une politique de confidentialité et un support distincts.
# documentation en ligne.

# NOTE: pnpm caching support requires pnpm version >= 6.10.0

steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
  with:
    version: 6.10.0
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

Si vous avez une exigence particulière ou si vous avez besoin d’un contrôle plus précis pour la mise en cache, vous pouvez utiliser l’action cache. Pour plus d’informations, consultez « Mise en cache des dépendances pour accélérer les workflows ».

Génération et test de votre code

Vous pouvez utiliser les mêmes commandes que celles que vous utilisez localement pour générer et tester votre code. Par exemple, si vous exécutez npm run build pour exécuter des étapes de génération définies dans votre fichier package.json, et npm test pour exécuter votre suite de tests, vous devez ajouter ces commandes dans votre fichier de workflow.

YAML

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

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

Empaquetage des données de workflow en tant qu’artefacts

Vous pouvez enregistrer les artefacts de vos étapes de génération et de test afin de les examiner une fois le travail terminé. Par exemple, vous devrez peut-être enregistrer des fichiers journaux, des vidages principaux, des résultats de test ou des captures d’écran. Pour plus d’informations, consultez « Stockage et partage des données d’un workflow ».

Publication dans des registres de package

Vous pouvez configurer votre workflow pour publier votre package Node.js dans un registre de package une fois vos tests CI réussis. Pour plus d’informations sur la publication dans npm et GitHub Packages, consultez « Publication de packages Node.js ».

Dans cet article

Introduction

Prérequis

Utilisation d’un modèle de workflow Node.js

Spécification de la version de Node.js

Installer les dépendances

Exemple d’utilisation de npm

Exemple d’utilisation de Yarn

Exemple d’utilisation d’un registre privé et de création du fichier .npmrc

Exemple de mise en cache des dépendances

Génération et test de votre code

Empaquetage des données de workflow en tant qu’artefacts

Publication dans des registres de package