Setting up authentication for npm

This page describes how to configure build tools to connect with Artifact Registry repositories.

Package management is only available to alpha users. To apply for the alpha, complete the sign up form.

Before you begin

  1. If the target repository does not exist, create a new repository.
  2. If you are connecting to repositories from Windows, install PowerShell,
  3. (Optional) Configure defaults for gcloud commands. if you want to connect to an npm repository from Windows.

Using scopes

An npm scope is a label that acts as a namespace. In the context of Artifact Registry, you can associate a scope with a repository to distinguish it from other repositories or other registries, such as the public npm registry.

If you are only working with a single npm repository, you do not need to use a scope. A registry that is not associated with a scope is configured like the following example in the .npmrc configuration file:

registry=https://us-central1-npm.pkg.dev/my-project/my-npm-repo/
//us-central1-npm.pkg.dev/my-project/my-npm-repo/:_password=""
//us-central1-npm.pkg.dev/my-project/my-npm-repo/:username=oauth2accesstoken
//us-central1-npm.pkg.dev/my-project/my-npm-repo/:email=not.valid@email.com
//us-central1-npm.pkg.dev/my-project/my-npm-repo/:always-auth=true

If you use a mixture of registries with npm, you must use scoped packages. For example, you might use both the public npm registry for open source packages and npm repositories in Artifact Registry for private packages.

Scopes are also useful when you want to work with multiple npm repositories in either the same project or across different Google Cloud projects. You can associate a scope with each repository in .npmrc and use the same credentials for authentication across the repositories.

The following example shows configuration for two Artifact Registry repositories in different projects.

  • The @blue scope is for the repository in the project blue-project.
  • The @green scope is for the repository in the project green-project.
@blue:registry=https://us-central1-npm.pkg.dev/blue-project/blue-npm-repo/
//us-central1-npm.pkg.dev/blue-project/blue-npm-repo/:_password=""
//us-central1-npm.pkg.dev/blue-project/blue-npm-repo/:username=oauth2accesstoken
//us-central1-npm.pkg.dev/blue-project/blue-npm-repo/:email=not.valid@email.com
//us-central1-npm.pkg.dev/blue-project/blue-npm-repo/:always-auth=true

@green:registry=https://us-central1-npm.pkg.dev/green-project/green-npm-repo/
//us-central1-npm.pkg.dev/green-project/green-npm-repo/:_password=""
//us-central1-npm.pkg.dev/green-project/green-npm-repo/:username=oauth2accesstoken
//us-central1-npm.pkg.dev/green-project/green-npm-repo/:email=not.valid@email.com
//us-central1-npm.pkg.dev/green-project/green-npm-repo/:always-auth=true

After you have authenticated to Artifact Registry, you can upload a package to a particular repository using the appropriate scope. For example, the following command uploads a package to the blue-npm-repo in the project blue-project:

npm publish @blue/blue-npm-repo

For more information about scopes, see the npm documentation

Where to store settings

Settings used for authentication are stored in npm configuration files. These files are named .npmrc. The following settings are used for Artifact Registry.

  • Credentials for the public npm registry

    Store your credentials for the public npm registry (https://registry.npmjs.org/) in the per-user config file so that they are not available to other users. This file is located in your user home directory, or is set with the npm --userconfig parameter or $NPM_CONFIG_USERCONFIG environment variable. The Artifact Registry tools for authenticating with Artifact Registry repositories are located in the public npm registry.

  • Settings for connecting to a repository

    You can store Artifact Registry repository settings in one of these npm configuration files:

    • The per-project config file. This .npmrc file is usually in the same directory as the package.json file in your npm project. This is the simpler option.

    • The per-user config file. This file is located in your user home directory, or is set with the npm --userconfig parameter or $NPM_CONFIG_USERCONFIG environment variable.

    • The global config file, $PREFIX/etc/npmrc. To get the value of $PREFIX, run the command npm prefix -g.

If you use both the public npm registry and an npm repository in Artifact Registry, all packages that you store in Artifact Registry repositories must be scoped and the default registry in the configuration file must be the public npm registry.

To check the current default registry value run the command:

npm get registry

To set the public npm registry as your default registry, run the command:

npm set registry https://registry.npmjs.org/

For more information about npm configuration files, see the npm config file documentation.

Configuring repository settings

To configure npm to connect to a Artifact Registry repository:

  1. Run the following command to get the configuration settings for a repository. If you want to store the settings in the npm global or per-user configuration file, you must include a scope.

    gcloud beta artifacts print-settings npm [--project=PROJECT] \
    [--repository=REPOSITORY] [--location=LOCATION] [--scope=@SCOPE-NAME]

    Where

    • PROJECT is the project ID. If this flag is omitted, the current or default project is used.
    • REPOSITORY is the ID of the repository. If you configured a default Artifact Registry repository, it is used when this flag is omitted from the command.
    • LOCATION is the regional or multi-regional location for the repository.
    • SCOPE-NAME is the name of the npm scope you want to associate with the Artifact Registry repository.
      • If a scope is specified, the Artifact Registry repository is associated with the specified scope. Unscoped packages are associated with your default npm registry.
      • If a scope is not specified, the Artifact Registry repository is configured as the default repository.
  2. Add the returned configuration settings to your per-user, per-project, or global npm configuration file.

  3. If you have other npm repositories to connect to, repeat the previous steps to obtain the settings and add them to the .npmrc file. See Using scopes for more information about using scopes to configure multiple npm repositories.

  4. When you want to connect to a repository, refresh the access token for authentication within 60 minutes of making the connection. google-artifactregistry-auth is a client library that updates credentials for Artifact Registry repositories.

    To refresh credentials, use one of these options:

    • Use npx directly to refresh the access token. If you are using npm 5.2.0 or newer, it is included with npm.

      1. Ensure that credentials for connecting to the public npm registry are in your user npm configuration file, ~/.npmrc.

      2. Run the following command in the folder above your npm project.

      npx google-artifactregistry-auth PROJECT-NPMRC
      

      Where PROJECT-NPMRC is the path to the .npmrc file in your project directory.

      You must run the command outside of your project directory so that npx uses your public npm registry credentials in ~/.npmrc to download google-artifactregistry-auth.

    • Add a script to the package.json file in your project.

      "scripts": {
        "artifactregistry-login": "npx google-artifactregistry-auth"
      }
      
      npm run artifactregistry-login PROJECT-NPMRC --registry https://registry.npmjs.org/
      

      Where PROJECT-NPMRC is the path to the .npmrc file in your project directory.

    • For versions of npm older than 5.2.0, perform the following steps:

      1. Run the command:
      npm install google-artifactregistry-auth --save-dev --registry https://registry.npmjs.org/
      
      1. Add it to an authentication script:
      "scripts": {
          "artifactregistry-login": "./node_modules/.bin/artifactregistry-auth",
      }
      

      Run the script

      npm run artifactregistry-login PROJECT-NPMRC
      

      Where PROJECT-NPMRC is the path to the .npmrc file in your project directory.

If you did not specify a scope with the print-settings command, you can run the following command to associate a scope with a Artifact Registry repository.

npm config set @SCOPE_NAME:registry https://LOCATION-npm.pkg.dev/PROJECT-ID/REPOSITORY/

What's next