Publishing Node.js packages

You can publish Node.js packages to a registry as part of your continuous integration (CI) workflow.

Introduction

This guide shows you how to create a workflow that publishes Node.js packages to the GitHub Packages and npm registries after continuous integration (CI) tests pass. With a single workflow, you can publish packages to a single registry or multiple registries.

Prerequisites

We recommend that you have a basic understanding of workflow configuration options and how to create a workflow file. For more information, see "Learn GitHub Actions."

For more information about creating a CI workflow for your Node.js project, see "Using Node.js with GitHub Actions."

You may also find it helpful to have a basic understanding of the following:

About package configuration

The name and version fields in the package.json file create a unique identifier that registries use to link your package to a registry. You can add a summary for the package listing page by including a description field in the package.json file. For more information, see "Creating a package.json file" and "Creating Node.js modules" in the npm documentation.

When a local .npmrc file exists and has a registry value specified, the npm publish command uses the registry configured in the .npmrc file. 您可以使用 setup-node 操作在运行器上创建本地 .npmrc 文件,以配置默认注册表和范围。 setup-node 操作也接受身份验证令牌作为输入,用于访问私人注册表或发布节点包。 更多信息请参阅 setup-node

You can specify the Node.js version installed on the runner using the setup-node action.

If you add steps in your workflow to configure the publishConfig fields in your package.json file, you don't need to specify the registry-url using the setup-node action, but you will be limited to publishing the package to one registry. For more information, see "publishConfig" in the npm documentation.

Publishing packages to the npm registry

Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs when the release event triggers with type created. The workflow publishes the package to the npm registry if CI tests pass.

To perform authenticated operations against the npm registry in your workflow, you'll need to store your npm authentication token as a secret. For example, create a repository secret called NPM_TOKEN. For more information, see "Creating and using encrypted secrets."

By default, npm uses the name field of the package.json file to determine the npm registry. When publishing to a global namespace, you only need to include the package name. For example, you would publish a package named npm-hello-world-test to the https://www.npmjs.com/package/npm-hello-world-test.

If you're publishing a package that includes a scope prefix, include the scope in the name of your package.json file. For example, if your npm scope prefix is octocat and the package name is hello-world, the name in your package.json file should be @octocat/hello-world. If your npm package uses a scope prefix and the package is public, you need to use the option npm publish --access public. This is an option that npm requires to prevent someone from publishing a private package unintentionally.

This example stores the NPM_TOKEN secret in the NODE_AUTH_TOKEN environment variable. When the setup-node action creates an .npmrc file, it references the token from the NODE_AUTH_TOKEN environment variable.

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

In the example above, the setup-node action creates an .npmrc file on the runner with the following contents:

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

Publishing packages to GitHub Packages

Each time you create a new release, you can trigger a workflow to publish your package. The workflow in the example below runs anytime the release event with type created occurs. The workflow publishes the package to GitHub Packages if CI tests pass.

Configuring the destination repository

If you don't provide the repository key in your package.json file, then GitHub Packages publishes a package in the GitHub repository you specify in the name field of the package.json file. For example, a package named @my-org/test is published to the my-org/test GitHub repository.

However, if you do provide the repository key, then the repository in that key is used as the destination npm registry for GitHub Packages. For example, publishing the below package.json results in a package named my-amazing-package published to the octocat/my-other-repo GitHub repository.

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

Authenticating to the destination repository

To perform authenticated operations against the GitHub Packages registry in your workflow, you can use the GITHUB_TOKEN. 每当工作流程中的作业开始时,都会将 GITHUB_TOKEN 密钥设置为仓库的访问令牌。 您应该在工作流程文件中设置此访问令牌的权限,以授予 contents 范围的读取访问权限,并授予 packages 范围的写入访问权限。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

If you want to publish your package to a different repository, you must use a personal access token (PAT) that has permission to write to packages in the destination repository. For more information, see "Creating a personal access token" and "Encrypted secrets."

Example workflow

This example stores the GITHUB_TOKEN secret in the NODE_AUTH_TOKEN environment variable. When the setup-node action creates an .npmrc file, it references the token from the NODE_AUTH_TOKEN environment variable.

YAML
name: Node.js Package
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest 
    permissions: 
      contents: read
      packages: write 
    steps:
      - uses: actions/checkout@v2
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v2
        with:
          node-version: '12.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 }}

The setup-node action creates an .npmrc file on the runner. When you use the scope input to the setup-node action, the .npmrc file includes the scope prefix. By default, the setup-node action sets the scope in the .npmrc file to the account that contains that workflow file.

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

Publishing packages using yarn

If you use the Yarn package manager, you can install and publish packages using Yarn.

YAML
name: Node.js Package
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v2
        with:
          node-version: '12.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 }}

Publishing packages to npm and GitHub Packages

Note: If you need to publish to registries that have different scope prefixes, you'll need to modify the package.json file on the runner to change the scope prefix. For example, if you publish a package to the @mona scope for npm and @octocat scope for GitHub Packages, you can replace the @mona scope with @octocat in the package.json file on the runner after publishing to npm and before publishing to GitHub Packages.

You can publish your packages to both the npm registry and GitHub Packages by using the setup-node action for each registry.

If you publish a package to both registries, you'll need to ensure that your scope prefix on npm matches your GitHub user or organization name. To publish packages to a public registry with a scope prefix, you can use the command npm publish --access public. For more information, see npm-scope and "Creating and publishing scoped public packages" in the npm documentation.

Ensure your package.json file includes the scope of your GitHub repository and npm registry. For example, if you plan to publish a package in the octocat/npm-hello-world-test repository to GitHub and https://www.npmjs.com/package/@octocat/npm-hello-world-test, the name in your package.json file would be "name": "@octocat/npm-hello-world-test".

To perform authenticated operations against the GitHub Packages registry in your workflow, you can use the GITHUB_TOKEN. 每当工作流程中的作业开始时,都会将 GITHUB_TOKEN 密钥设置为仓库的访问令牌。 您应该在工作流程文件中设置此访问令牌的权限,以授予 contents 范围的读取访问权限,并授予 packages 范围的写入访问权限。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

When you use the scope input to the setup-node action, the action creates an .npmrc file that includes the scope prefix. By default, the setup-node action sets the scope in the .npmrc file to the user or organization that owns the workflow file.

This workflow calls the setup-node action two times. Each time the setup-node action runs, it overwrites the .npmrc file. The .npmrc file references the token that allows you to perform authenticated operations against the package registry from the NODE_AUTH_TOKEN environment variable. The workflow sets the NODE_AUTH_TOKEN environment variable each time the npm publish command is run, first with a token to publish to npm (NPM_TOKEN) and then with a token to publish to GitHub Packages (GITHUB_TOKEN).

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

此文档对您有帮助吗?

隐私政策

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或者, 了解如何参与。