Fix 401/404 Installing Private npm Packages in GitHub Actions
Fix 401 and 404 errors when installing private npm packages in GitHub Actions: set registry-url, pass NODE_AUTH_TOKEN to the install step.
At a glance
- Last reviewed
- Versions referenced
actions/checkout@v7actions/setup-node@v7- Reading time
- 3 min read
Code samples are not run in a live repository. See our editorial standards.
On this page
A 401 or 404 on a private npm package almost always means npm sent no valid token to the registry that hosts the package. Set registry-url in actions/setup-node, and pass NODE_AUTH_TOKEN to the step that runs npm ci. Private registries return 404 instead of 403 for packages you cannot see, so a 404 is often an auth problem too.
Install from GitHub Packages in the same repository or organization
Use the built-in GITHUB_TOKEN with packages: read when the package is published from the same repository, or when the package grants access to this repository.
name: Install private package
on:
push:
branches: [main]
jobs:
install:
runs-on: ubuntu-latest
permissions:
contents: read
packages: read
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: '20.x'
registry-url: 'https://npm.pkg.github.com'
- run: npm ci
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
setup-node writes an .npmrc that points npm at https://npm.pkg.github.com and reads the token from NODE_AUTH_TOKEN. The token must be set on the step that runs npm. Setting permissions replaces the defaults, so list both contents: read (for checkout) and packages: read.
This does not work for packages owned by another repository that has not granted access. In that case, use a PAT (next section) or give this repository access in the package’s settings under Manage Actions access.
Install from another repository or organization with a PAT
Use a personal access token (classic) with the read:packages scope. GITHUB_TOKEN is scoped to the current repository and cannot read packages that repository has no access to. For a related walkthrough, see Fix ‘Resource not accessible by integration’ (403) in GitHub Actions.
- In GitHub, go to Settings > Developer settings > Personal access tokens > Tokens (classic) and generate a token with
read:packages. - In the repository that runs the workflow, go to Settings > Secrets and variables > Actions and add a secret named
NPM_PAT. - Reference the secret in the install step.
name: Install private package from another repository
on:
push:
branches: [main]
jobs:
install:
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: '20.x'
registry-url: 'https://npm.pkg.github.com'
scope: '@example'
- run: npm ci
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_PAT }}
The scope input routes @example packages to the registry in registry-url. Replace @example with the owner’s scope. The token owner must have read access to the package, or the registry still answers 401 or 404.
Never print the token or write it into a committed file. Keep it in a secret and reference it through ${{ secrets.NAME }} or an environment variable. For a related walkthrough, see GitHub Actions Secret Not Passed to Script: Causes and Fixes.
Install private packages from npmjs.org
For private packages on the public npm registry, create a read-only npm access token, store it as a secret named NPM_TOKEN, and map it to NODE_AUTH_TOKEN.
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: '20.x'
registry-url: 'https://registry.npmjs.org'
scope: '@your-org'
- run: npm ci
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
An expired or revoked npm token produces a 401. A token without access to the organization’s packages usually produces a 404.
Keep a committed .npmrc consistent
If your repository already has an .npmrc, it must not point the scope at a different registry than the one you authenticate against. Write the token as a variable reference, never as a literal value.
@example:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
npm expands ${NODE_AUTH_TOKEN} from the environment at run time. If the variable is unset when npm reads this file, npm fails on the missing variable or sends no token.
Also check that .npmrc is not listed in .gitignore. If it is ignored, the runner never receives it and npm falls back to the public registry, which returns 404 for scoped private packages.
Common causes
| Symptom | Cause | Fix |
|---|---|---|
| 401 | NODE_AUTH_TOKEN not set on the npm step, or the secret name is misspelled |
Add env: NODE_AUTH_TOKEN: ${{ secrets.NAME }} to the npm ci step and confirm the secret exists |
| 401 | Token expired, revoked, or PAT lacks read:packages |
Regenerate the token with the right scope |
| 404 | Scope is not mapped to the private registry | Set scope in setup-node or add @scope:registry= to .npmrc |
| 404 | Token owner or repository has no access to the package | Grant access in the package settings, or use a PAT from a user who can read it |
| 401 or 404 | permissions block omits packages: read when using GITHUB_TOKEN |
Add packages: read alongside contents: read |
| 401 or 404 on pull requests from forks | Secrets are not passed to workflows triggered by forks | Run installs from a trusted trigger; do not expose secrets to untrusted code |
Verify the fix
Add a temporary step after setup-node to confirm which registry npm resolves for your scope. It prints a URL, never the token.
- run: npm config get @example:registry
- run: npm view @example/private-package version
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_PAT }}
The first command should print the registry URL you configured. The second should print the package version. If it fails, the npm error output includes the code E401 or E404, which tells you whether the problem is authentication (401) or routing and access (404). Once npm view succeeds, npm ci completes without those codes and reports the installed package count.
Spotted an error? Report it on our Contact page and see our editorial standards for how we correct articles.