Google Artifact Registry Auth for npm/Yarn

3.5.0 verified Thu Apr 23 auth: no javascript

The `google-artifactregistry-auth` module (currently at v3.5.0) provides command-line tools to configure npm and Yarn to authenticate with private npm repositories hosted in Google Cloud's Artifact Registry. It streamlines the process of obtaining and managing access tokens by automatically leveraging Google Application Default Credentials or the active `gcloud` login. The package sees a fairly active release cadence, with minor versions introducing features like Yarn support, flexible domain configurations, and token passing, indicating ongoing development and refinement. Its primary differentiator is the deep integration with Google Cloud's authentication mechanisms, making it the go-to solution for JavaScript package management within the Google Cloud ecosystem, especially for CI/CD pipelines and developer workstations. It's designed to simplify the typically complex setup of token-based authentication for private registries.

Common errors

error Error: Unable to find credentials to authenticate to Google Cloud. Please ensure you have authenticated with `gcloud auth login` or `gcloud auth application-default login` or set the GOOGLE_APPLICATION_CREDENTIALS environment variable. ↓

cause The module could not find valid Google Cloud credentials in the execution environment.

fix

Run gcloud auth login or gcloud auth application-default login to authenticate, or set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of a service account key JSON file.

error Failed to update _authToken in .npmrc / .yarnrc.yml. Please check file permissions or path. ↓

cause The module did not have sufficient write permissions to the specified `.npmrc` or `.yarnrc.yml` file, or the path was incorrect.

fix

Verify that the path provided to --credential-config (or --credential-config-yarn) is correct and that the user running the command has write permissions to that file.

error npm ERR! 401 Unauthorized - GET https://LOCATION-npm.pkg.dev/PROJECT_ID/REPOSITORY_ID/package-name ↓

cause The access token used by npm is expired, invalid, or missing, leading to an unauthorized access attempt to Artifact Registry.

fix

Re-run the npx google-artifactregistry-auth command to refresh the authentication token in your .npmrc or .yarnrc.yml file. Ensure your Google Cloud credentials are still valid.

Warnings

breaking Version 3.0.0 introduced significant changes to how configuration files are handled, requiring new `--repo-config` and `--credential-config` flags. The tool now defaults to writing auth credentials to the user's npmrc file. ↓

fix Update your scripts to use the `--repo-config` and `--credential-config` flags to explicitly define the paths for your repository settings and credential storage. For Yarn, use `--repo-config-yarn` and `--credential-config-yarn`.

gotcha This module updates credentials for *all* Artifact Registry repositories. It is not suitable if you use multiple account credentials for different Artifact Registry repositories within the same `.npmrc` or `.yarnrc.yml` file, as it will overwrite existing tokens. ↓

fix If you require multiple distinct credentials for different Artifact Registry repositories, consider manual credential management or using separate npm/yarn configurations per project/context, or explore custom solutions for token management that do not rely on this module for multi-account scenarios.

gotcha Authentication relies on Google Application Default Credentials or an active `gcloud auth login` session. If these are not configured correctly in the environment where the module runs, authentication will fail. ↓

fix Ensure `gcloud auth application-default login` or `gcloud auth login` has been executed, or that the `GOOGLE_APPLICATION_CREDENTIALS` environment variable points to a valid service account key file before running the module.

gotcha The module's behavior for locating and updating `.npmrc` or `.yarnrc.yml` files changed in v3.1.0, defaulting to the user-level npmrc if no project-level exists, and in v3.0.1, which addressed issues with `_authToken` not being available locally when moved to the user `.npmrc`. ↓

fix Always explicitly specify `--repo-config` (or `--repo-config-yarn`) for the file containing your repository URL and `--credential-config` (or `--credential-config-yarn`) for where the token should be written to ensure predictable behavior, especially in CI/CD environments.

Install

npm install google-artifactregistry-auth

yarn add google-artifactregistry-auth

pnpm add google-artifactregistry-auth

Imports

google-artifactregistry-auth (CLI)
```
npx google-artifactregistry-auth
```
This package is primarily a CLI tool executed via `npx`. It does not expose JavaScript modules for direct `import` or `require` in application code. Its functionality is invoked by running the command to update `.npmrc` or `.yarnrc.yml` files with authentication tokens.
Auth Tokens (npmrc)
wrong
```
require('google-artifactregistry-auth').getAuthToken()
```
correct
```
npx google-artifactregistry-auth --repo-config=[./.npmrc] --credential-config=[~/.npmrc]
```
The module configures `.npmrc` files; it doesn't provide an API to programmatically retrieve tokens directly from JavaScript code within an application. The interaction is through the CLI to manage registry settings.
Auth Tokens (yarnrc.yml)
wrong
```
yarn add google-artifactregistry-auth && yarn run google-artifactregistry-auth
```
correct
```
npx google-artifactregistry-auth --repo-config-yarn=[./.yarnrc.yml] --credential-config-yarn=[~/.yarnrc.yml]
```
While `yarn add` will install it, the correct way to *run* the tool is via `npx` or by defining a script in `package.json`. Yarn support was added in v3.5.0.

Quickstart

Demonstrates the full flow for authenticating npm with a Google Artifact Registry private repository, from initial Google Cloud authentication to running the `google-artifactregistry-auth` CLI to configure `.npmrc`.

# 1. Authenticate your gcloud CLI or set Application Default Credentials
# Option 1: Log in as a service account using a JSON key file
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
# Option 2: Log in as a service account via gcloud
gcloud auth application-default login
# Option 3: Log in as an end user via gcloud
gcloud auth login

# 2. Add repository settings to your project's .npmrc file
# Replace LOCATION, PROJECT_ID, REPOSITORY_ID with your actual values
# Example: gcloud artifacts print-settings npm --project=my-project --repository=my-repo --location=us-central1
echo "registry=https://LOCATION-npm.pkg.dev/PROJECT_ID/REPOSITORY_ID/" > .npmrc
echo "//LOCATION-npm.pkg.dev/PROJECT_ID/REPOSITORY_ID/:always-auth=true" >> .npmrc

# 3. Run the auth module to write the access token to your user .npmrc file
npx google-artifactregistry-auth --repo-config=./.npmrc --credential-config=~/.npmrc

# Now you can install packages from your Artifact Registry private repository
npm install