Skip to main content

Publication de packages Node.js

Vous pouvez publier des packages Node.js sur un registre dans le cadre de votre workflow d’intégration continue (CI).

Remarque : Les exécuteurs hébergés sur GitHub ne sont pas pris en charge sur GitHub Enterprise Server. Vous pouvez voir plus d’informations sur le support futur planifié dans la GitHub public roadmap.

Introduction

Ce guide vous montre comment créer un workflow qui publie des packages Node.js sur les registres GitHub Packages 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 « Découvrir GitHub Actions ».

Pour plus d’informations sur la création d’un workflow CI pour votre projet Node.js, consultez « Utilisation de Node.js avec GitHub Actions ».

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 dans le fichier package.json créent un identificateur unique que les registres utilisent pour lier votre package à un registre. Vous pouvez ajouter un résumé pour la page de la liste des packages 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 a une valeur registry spécifiée, la commande npm publish utilise le registre configuré dans le 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.

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 de votre fichier package.json, vous n’avez pas besoin de spécifier l’URL de registre à l’aide de l’action setup-node, mais vous serez limité à la publication du package sur un registre. Pour plus d’informations, consultez « publishConfig » dans la documentation npm.

Publication de packages sur le registre npm

Chaque fois que vous créez une version, vous pouvez déclencher un workflow pour publier votre package. Le workflow de l’exemple ci-dessous s’exécute lorsque l’événement release se déclenche avec le type created. Le workflow publie le package sur le registre npm si les tests CI réussissent.

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 dépôt appelé NPM_TOKEN. Pour plus d’informations, consultez « Création et utilisation de secrets chiffrés ».

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é npm-hello-world-test sur https://www.npmjs.com/package/npm-hello-world-test.

Si vous publiez un package qui inclut un préfixe d’étendue, incluez l’étendue dans le nom de votre fichier package.json. Par exemple, si votre préfixe d’étendue npm est octocat et que le nom du package est hello-world, le 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é.

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 fait référence au jeton à partir de la variable d’environnement NODE_AUTH_TOKEN.

YAML
name: Publish Package to npmjs
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v3
        with:
          node-version: '16.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Dans l’exemple ci-dessus, l’action setup-node crée un fichier .npmrc sur l’exécuteur 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 packages sur GitHub Packages

Chaque fois que vous créez une version, vous pouvez déclencher un workflow pour publier votre package. Le workflow de l’exemple ci-dessous s’exécute chaque fois que l’événement release avec le type created se produit. Le workflow publie le package sur GitHub Packages si les tests CI réussissent.

Configuration du dépôt de destination

La liaison de votre package à GitHub Packages à l’aide de la clé repository est facultative. Si vous choisissez de ne pas fournir la clé repository dans votre fichier package.json, GitHub Packages publie un package sur le dépôt GitHub que vous spécifiez dans le champ name du fichier package.json. Par exemple, un package nommé @my-org/test est publié sur le dépôt GitHub my-org/test. Si le url spécifié dans la clé repository n’est pas valide, votre package pourra quand même être publié. Cependant, il ne sera pas lié à la source du dépôt comme prévu.

Si vous fournissez la clé repository de votre fichier package.json, le dépôt de cette clé est utilisé comme registre npm de destination pour GitHub Packages. Par exemple, la publication du fichier package.json ci-dessous entraîne la publication d’un package nommé my-amazing-package sur le dépôt GitHub octocat/my-other-repo. Une fois publié, seule la source du dépôt est mise à jour et le package n’hérite d’aucune autorisation du dépôt de destination.

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

Authentification auprès du dépôt de destination

Pour effectuer des opérations authentifiées sur le registre GitHub Packages dans votre workflow, vous pouvez utiliser GITHUB_TOKEN. Le secret GITHUB_TOKEN a la valeur d’un jeton d’accès pour le dépôt chaque fois qu’un travail d’un workflow démarre. 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’étendue contents et l’accès en écriture pour l’étendue packages. Pour plus d’informations, consultez « Authentification avec GITHUB_TOKEN ».

Si vous souhaitez publier votre package sur un autre dépôt, vous devez utiliser un personal access token qui a l’autorisation d’écrire dans des packages dans le dépôt de destination. Pour plus d’informations, consultez « Création d’un personal access token » et « Secrets chiffrés ».

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 fait référence au jeton à partir de la variable d’environnement NODE_AUTH_TOKEN.

YAML
name: Publish package to GitHub Packages
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v3
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v3
        with:
          node-version: '16.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 l’exécuteur. Lorsque vous utilisez l’entrée scope pour l’action setup-node, le fichier .npmrc inclut le préfixe d’étendue. Par défaut, l’action setup-node définit l’étendue dans le fichier .npmrc sur le compte qui contient ce fichier de workflow.

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

Publication de packages à l’aide de 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: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v3
        with:
          node-version: '16.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}