Publication de packages Node.js

Dans ce tutoriel, vous allez apprendre à publier des packages Node.js dans un registre dans le cadre de votre workflow d’intégration continue (CI).

Dans cet article

Présentation

Ce guide vous montre comment créer un flux de travail qui publie des packages Node.js sur les GitHub Packages registres et npm après la réussite des tests d’intégration continue (CI).

Prérequis

Il est recommandé d’avoir une compréhension de base des options de configuration de workflows et de la création de fichiers de workflow. Pour plus d’informations, consultez « Écriture de workflows ».

Pour plus d’informations sur la création d’un workflow CI pour votre projet Node.js, consultez Création et test de code Node.js.

Vous pouvez également trouver utile d’avoir une compréhension de base des éléments suivants :

À propos de la configuration d’un package

Les champs name et version du fichier package.json créent un identifiant unique que les registres utilisent pour associer votre package à un registre. Vous pouvez ajouter un résumé pour la page de présentation du package en incluant un champ description dans le fichier package.json. Pour plus d’informations, consultez Création d’un fichier package.json et Création de modules Node.js dans la documentation npm.

Lorsqu’un fichier .npmrc local existe et qu’une valeur registry y est spécifiée, la commande npm publish utilise le registre configuré dans le fichier .npmrc. Vous pouvez utiliser setup-node l’action pour créer un fichier local .npmrc sur l’exécuteur qui configure le registre et la portée 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.

Vous pouvez spécifier la version de Node.js installée sur l’exécuteur à l’aide de l’action setup-node.

Si vous ajoutez des étapes dans votre workflow pour configurer les champs publishConfig dans votre fichier package.json, vous n’avez pas besoin de spécifier l’URL du registre via l’action setup-node, mais vous serez limité à la publication du package dans un seul registre. Pour plus d’informations, consultez publishConfig dans la documentation npm.

Publication de packages sur le registre npm

Vous pouvez déclencher un workflow pour publier votre package chaque fois que vous publiez une nouvelle version. Le processus de l’exemple suivant est exécuté quand l’événement de mise en production de type published est déclenché. Si les tests CI réussissent, le processus charge le package dans le registre npm. Pour plus d’informations, consultez « Gestion des versions dans un référentiel ».

Pour effectuer des opérations authentifiées sur le registre npm dans votre workflow, vous devez stocker votre jeton d’authentification npm en tant que secret. Par exemple, créez un secret de référentiel appelé NPM_TOKEN. Pour plus d’informations, consultez « Utilisation de secrets dans GitHub Actions ».

Par défaut, npm utilise le champ name du fichier package.json pour déterminer le nom de votre package publié. Lorsque vous publiez sur un espace de noms global, vous devez uniquement inclure le nom du package. Par exemple, vous allez publier un package nommé my-package sur https://www.npmjs.com/package/my-package.

Si vous publiez un package incluant un préfixe de portée (scope), incluez cette portée dans le nom de votre fichier package.json. Par exemple, si votre préfixe de portée npm est « octocat » et que le nom du package est « hello-world », la valeur name dans votre fichier package.json doit être @octocat/hello-world. Si votre package npm utilise un préfixe d’étendue et que le package est public, vous devez utiliser l’option npm publish --access public. Il s’agit d’une option requise par npm pour empêcher une personne de publier involontairement un package privé.

Si vous souhaitez publier votre package avec provenance, incluez l’indicateur --provenance avec votre npm publish commande. Cela vous permet d’établir publiquement et de manière vérifiable où et comment votre package a été construit, ce qui renforce la sécurité de la chaîne d’approvisionnement pour les personnes qui consomment votre package. Pour plus d’informations, consultez Générer des instructions de provenance dans la documentation npm.

Cet exemple stocke le secret NPM_TOKEN dans la variable d’environnement NODE_AUTH_TOKEN. Lorsque l’action setup-node crée un fichier .npmrc, elle référence le jeton provenant de la variable d’environnement NODE_AUTH_TOKEN.

YAML
name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Dans l’exemple ci-dessus, l’action setup-node crée un fichier .npmrc sur le runner avec le contenu suivant :

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

Notez que vous devez définir l’registry-url sur https://registry.npmjs.org/ dans setup-node pour configurer correctement vos informations d’identification.

Publication de paquets vers GitHub Packages

Vous pouvez déclencher un workflow pour publier votre package chaque fois que vous publiez une nouvelle version. Le processus de l’exemple suivant est exécuté quand l’événement de mise en production de type published est déclenché. Si les tests CI réussissent, le processus charge le package vers GitHub Packages. Pour plus d’informations, consultez « Gestion des versions dans un référentiel ».

Configuration du référentiel de destination

Lier votre paquet à GitHub Packages à l’aide de la clé repository est facultatif. Si vous choisissez de ne pas fournir la repository clé dans votre package.json fichier, votre package ne sera pas lié à un référentiel lorsqu’il est publié, mais vous pouvez choisir de connecter le package à un référentiel ultérieurement.

Si vous fournissez la repository clé dans votre package.json fichier, le référentiel de cette clé est utilisé comme registre npm de destination pour GitHub Packages. Par exemple, la publication des résultats ci-dessous package.json entraîne la publication d’un package nommé my-package dans le octocat/my-other-repoGitHub référentiel.

{
  "name": "@octocat/my-package",
  "repository": {
    "type": "git",
    "url": "https://github.com/octocat/my-other-repo.git"
  },
}

Authentification auprès du référentiel de destination

Pour effectuer des opérations authentifiées sur le GitHub Packages Registre dans votre flux de travail, vous pouvez utiliser le GITHUB_TOKEN. Le secret GITHUB_TOKEN est défini sur un jeton d’accès pour le dépôt chaque fois qu’un travail dans un flux de travail commence. Vous devez définir les autorisations de ce jeton d’accès dans le fichier de workflow afin d’octroyer l’accès en lecture pour l’autorisation contents et l’accès en écriture pour l’autorisation packages. Pour plus d’informations, consultez « Utiliser GITHUB_TOKEN pour l’authentification dans les flux de travail ».

Si vous souhaitez publier votre package dans un autre référentiel, vous devez utiliser une personal access token (classic) autorisation d’écriture dans les packages dans le référentiel de destination. Pour plus d’informations, consultez « Gestion de vos jetons d’accès personnels » et « Utilisation de secrets dans GitHub Actions ».

Exemple de flux de travail

Cet exemple stocke le secret GITHUB_TOKEN dans la variable d’environnement NODE_AUTH_TOKEN. Lorsque l’action setup-node crée un fichier .npmrc, elle référence le jeton provenant de la variable d’environnement NODE_AUTH_TOKEN.

YAML
name: Publish package to GitHub Packages
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v6
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

L’action setup-node crée un fichier .npmrc sur le runner. Lorsque vous utilisez l’entrée scope de l’action setup-node, le fichier .npmrc inclut le préfixe de portée. Par défaut, l’action setup-node définit la portée dans le fichier .npmrc sur le compte qui contient le fichier de workflow.

//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://npm.pkg.github.com
always-auth=true

Publication de packages avec Yarn

Si vous utilisez le gestionnaire de package Yarn, vous pouvez installer et publier des packages à l’aide de Yarn.

YAML
name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Pour vous authentifier auprès du registre lors de la publication, assurez-vous que votre jeton d’authentification est également défini dans votre fichier yarnrc.yml. Pour plus d’informations, consultez l’article Paramètres dans la documentation Yarn.