{"id":17665,"library":"google-artifactregistry-auth","title":"Google Artifact Registry Auth for npm/Yarn","description":"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.","status":"active","version":"3.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/GoogleCloudPlatform/artifact-registry-npm-tools","tags":["javascript","google","google cloud platform","google cloud","cloud","artifact registry","artifact-registry"],"install":[{"cmd":"npm install google-artifactregistry-auth","lang":"bash","label":"npm"},{"cmd":"yarn add google-artifactregistry-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add google-artifactregistry-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the underlying Google authentication mechanisms to obtain access tokens for Artifact Registry.","package":"google-auth-library","optional":false}],"imports":[{"note":"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.","symbol":"google-artifactregistry-auth (CLI)","correct":"npx google-artifactregistry-auth"},{"note":"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.","wrong":"require('google-artifactregistry-auth').getAuthToken()","symbol":"Auth Tokens (npmrc)","correct":"npx google-artifactregistry-auth --repo-config=[./.npmrc] --credential-config=[~/.npmrc]"},{"note":"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.","wrong":"yarn add google-artifactregistry-auth && yarn run google-artifactregistry-auth","symbol":"Auth Tokens (yarnrc.yml)","correct":"npx google-artifactregistry-auth --repo-config-yarn=[./.yarnrc.yml] --credential-config-yarn=[~/.yarnrc.yml]"}],"quickstart":{"code":"# 1. Authenticate your gcloud CLI or set Application Default Credentials\n# Option 1: Log in as a service account using a JSON key file\nexport GOOGLE_APPLICATION_CREDENTIALS=\"/path/to/key.json\"\n# Option 2: Log in as a service account via gcloud\ngcloud auth application-default login\n# Option 3: Log in as an end user via gcloud\ngcloud auth login\n\n# 2. Add repository settings to your project's .npmrc file\n# Replace LOCATION, PROJECT_ID, REPOSITORY_ID with your actual values\n# Example: gcloud artifacts print-settings npm --project=my-project --repository=my-repo --location=us-central1\necho \"registry=https://LOCATION-npm.pkg.dev/PROJECT_ID/REPOSITORY_ID/\" > .npmrc\necho \"//LOCATION-npm.pkg.dev/PROJECT_ID/REPOSITORY_ID/:always-auth=true\" >> .npmrc\n\n# 3. Run the auth module to write the access token to your user .npmrc file\nnpx google-artifactregistry-auth --repo-config=./.npmrc --credential-config=~/.npmrc\n\n# Now you can install packages from your Artifact Registry private repository\nnpm install","lang":"bash","description":"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`."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=3.0.1"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"The module could not find valid Google Cloud credentials in the execution environment.","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."},{"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.","cause":"The module did not have sufficient write permissions to the specified `.npmrc` or `.yarnrc.yml` file, or the path was incorrect.","error":"Failed to update _authToken in .npmrc / .yarnrc.yml. Please check file permissions or path."},{"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.","cause":"The access token used by npm is expired, invalid, or missing, leading to an unauthorized access attempt to Artifact Registry.","error":"npm ERR! 401 Unauthorized - GET https://LOCATION-npm.pkg.dev/PROJECT_ID/REPOSITORY_ID/package-name"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}