Skip to main content

Working with the npm registry

You can configure npm to publish packages to GitHub Packages and to use packages stored on GitHub Packages as dependencies in an npm project.

GitHub Packages 适用于 GitHub Free、GitHub Pro、面向组织的 GitHub Free、GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 3.0 或更高版本以及 GitHub AE。
GitHub Packages 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 此外,使用旧版按仓库计划的帐户无法访问 Container registry,因为这些帐户是按仓库计费的。 有关详细信息,请参阅“GitHub 的产品”。

Authenticating to GitHub Packages

GitHub Packages 仅支持使用 personal access token (classic) 进行身份验证。 有关详细信息,请参阅“创建 personal access token”。

You need an access token to publish, install, and delete private, internal, and public packages.

You can use a personal access token (classic) to authenticate to GitHub Packages or the GitHub API. When you create a personal access token (classic), you can assign the token different scopes depending on your needs. For more information about packages-related scopes for a personal access token (classic), see "About permissions for GitHub Packages."

To authenticate to a GitHub Packages registry within a GitHub Actions workflow, you can use:

  • GITHUB_TOKEN to publish packages associated with the workflow repository.
  • a personal access token (classic) with at least packages:read scope to install packages associated with other private repositories (which GITHUB_TOKEN can't access).

如果你的工作流使用 personal access token 向注册表进行身份验证,则强烈建议更新工作流以使用 GITHUB_TOKEN

有关更新使用 personal access token 对注册表进行身份验证的工作流的指南,请参阅“升级使用 personal access token 访问注册表的工作流”。

有关 GITHUB_TOKEN 的详细信息,请参阅“工作流中的身份验证”。

有关在操作中使用注册表时的最佳做法的详细信息,请参阅“GitHub Actions 的安全强化”。

You can also choose to give access permissions to packages independently for Codespaces and GitHub Actions. For more information, see "Ensuring Codespaces access to your package and Ensuring workflow access to your package."

Authenticating with a personal access token

You must use a personal access token (classic) with the appropriate scopes to publish and install packages in GitHub Packages. For more information, see "About GitHub Packages."

You can authenticate to GitHub Packages with npm by either editing your per-user ~/.npmrc file to include your personal access token (classic) or by logging in to npm on the command line using your username and personal access token.

To authenticate by adding your personal access token (classic) to your ~/.npmrc file, edit the ~/.npmrc file for your project to include the following line, replacing TOKEN with your personal access token. Create a new ~/.npmrc file if one doesn't exist.

//npm.pkg.github.com/:_authToken=TOKEN

To authenticate by logging in to npm, use the npm login command, replacing USERNAME with your GitHub username, TOKEN with your personal access token (classic), and PUBLIC-EMAIL-ADDRESS with your email address.

If GitHub Packages is not your default package registry for using npm and you want to use the npm audit command, we recommend you use the --scope flag with the owner of the package when you authenticate to GitHub Packages.

$ npm login --scope=@OWNER --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS

Publishing a package

Note: Package names and scopes must only use lowercase letters.

The GitHub Packages registry stores npm packages within your organization or personal account, and allows you to associate a package with a repository. You can choose whether to inherit permissions from a repository, or set granular permissions independently of a repository.

By default, GitHub Packages publishes a package in the GitHub repository you specify in the name field of the package.json file. For example, you would publish a package named @my-org/test to the my-org/test GitHub repository. If you're running npm v8.5.3 or later, you can add a summary for the package listing page by including a README.md file in your package directory. For more information, see "Working with package.json" and "How to create Node.js Modules" in the npm documentation.

You can publish multiple packages to the same GitHub repository by including a URL field in the package.json file. For more information, see "Publishing multiple packages to the same repository."

When a package is published, it isn't automatically linked to a repository. You can however choose to link your published package to a repository using the user interface or command line. For more information, see "Connecting a repository to a package."

You can set up the scope mapping for your project using either a local .npmrc file in the project or using the publishConfig option in the package.json. GitHub Packages only supports scoped npm packages. Scoped packages have names with the format of @owner/name. Scoped packages always begin with an @ symbol. You may need to update the name in your package.json to use the scoped name. For example, "name": "@codertocat/hello-world-npm".

When you first publish a package, the default visibility is private. When a package is linked to repository, the package visibility is dependent on the repository's visibility. To change the visibility or set access permissions, see "Configuring a package's access control and visibility."

在发布包后,您可以在 GitHub 上查看该包。 有关详细信息,请参阅“查看包”。

Publishing a package using a local .npmrc file

You can use an .npmrc file to configure the scope mapping for your project. In the .npmrc file, use the GitHub Packages URL and account owner so GitHub Packages knows where to route package requests. Using an .npmrc file prevents other developers from accidentally publishing the package to npmjs.org instead of GitHub Packages.

  1. 向 GitHub Packages 验证。 有关详细信息,请参阅“向 GitHub Packages 进行身份验证”。

  2. 在与 package.json 文件相同的目录中,创建或编辑 .npmrc 文件以包含指定 GitHub Packages URL 和帐户所有者的行。 将 OWNER 替换为拥有项目所在存储库的用户或组织帐户的名称。

    @OWNER:registry=https://npm.pkg.github.com
  3. 将 .npmrc 文件添加到 GitHub Packages 可在其中找到项目的存储库。 有关详细信息,请参阅“将文件添加到存储库”。

  4. Verify the name of your package in your project's package.json. The name field must contain the scope and the name of the package. For example, if your package is called "test", and you are publishing to the "My-org" GitHub organization, the name field in your package.json should be @my-org/test.

  5. 验证项目 package.json 中的 repository 字段。 repository 字段必须与 GitHub 存储库的 URL 匹配。 例如,如果存储库 URL 是 github.com/my-org/test,则存储库字段应为 https://github.com/my-org/test.git

  6. 发布包:

    $ npm publish

Publishing a package using publishConfig in the package.json file

You can use publishConfig element in the package.json file to specify the registry where you want the package published. For more information, see "publishConfig" in the npm documentation.

  1. Edit the package.json file for your package and include a publishConfig entry.

    "publishConfig": {
      "registry": "https://npm.pkg.github.com"
    },
  2. 验证项目 package.json 中的 repository 字段。 repository 字段必须与 GitHub 存储库的 URL 匹配。 例如,如果存储库 URL 是 github.com/my-org/test,则存储库字段应为 https://github.com/my-org/test.git

  3. 发布包:

    $ npm publish

Publishing multiple packages to the same repository

To publish multiple packages to the same repository, you can include the URL of the GitHub repository in the repository field of the package.json file for each package.

To ensure the repository's URL is correct, replace REPOSITORY with the name of the repository containing the package you want to publish, and OWNER with the name of the user or organization account on GitHub that owns the repository.

GitHub Packages will match the repository based on the URL, instead of based on the package name.

"repository":"https://github.com/OWNER/REPOSITORY",

Installing a package

You can install packages from GitHub Packages by adding the packages as dependencies in the package.json file for your project. For more information on using a package.json in your project, see "Working with package.json" in the npm documentation.

By default, you can add packages from one organization. For more information, see "Installing packages from other organizations."

You also need to add the .npmrc file to your project so that all requests to install packages will go through GitHub Packages. When you route all package requests through GitHub Packages, you can use both scoped and unscoped packages from npmjs.org. For more information, see "npm-scope" in the npm documentation.

  1. 向 GitHub Packages 验证。 有关详细信息,请参阅“向 GitHub Packages 进行身份验证”。

  2. 在与 package.json 文件相同的目录中,创建或编辑 .npmrc 文件以包含指定 GitHub Packages URL 和帐户所有者的行。 将 OWNER 替换为拥有项目所在存储库的用户或组织帐户的名称。

    @OWNER:registry=https://npm.pkg.github.com
  3. 将 .npmrc 文件添加到 GitHub Packages 可在其中找到项目的存储库。 有关详细信息,请参阅“将文件添加到存储库”。

  4. Configure package.json in your project to use the package you are installing. To add your package dependencies to the package.json file for GitHub Packages, specify the full-scoped package name, such as @my-org/server. For packages from npmjs.com, specify the full name, such as @babel/core or @lodash. Replace <organization_name>/<package_name> with your package dependency.

    {
      "name": "@my-org/server",
      "version": "1.0.0",
      "description": "Server app that uses the <organization_name>/<package_name> package",
      "main": "index.js",
      "author": "",
      "license": "MIT",
      "dependencies": {
        "<organization_name>/<package_name>": "1.0.0"
      }
    }
    
  5. Install the package.

    $ npm install

Installing packages from other organizations

By default, you can only use GitHub Packages packages from one organization. If you'd like to route package requests to multiple organizations and users, you can add additional lines to your .npmrc file, replacing OWNER with the name of the user or organization account that owns the repository containing your project.

@OWNER:registry=https://npm.pkg.github.com
@OWNER:registry=https://npm.pkg.github.com