In GitHub Packages, how does a project point npm at npm.pkg.github.com, and why must the package scope match the owning account?
answer
- scoped packages only
- the scope names the account
- one routing line, one token line
- the token never lives in the project
basics
~10 sGitHub Packages hosts only scoped npm packages, and the scope is the owning user or organisation, so .npmrc maps @acme to https://npm.pkg.github.com and a separate auth line supplies a classic token for that host.
solid answer
~40 sGitHub Packages' npm registry hosts **only scoped packages**, named `@NAMESPACE/PACKAGE`, where the namespace is the user or organisation that owns the package, in lowercase. The project's `.npmrc` routes that scope with `@acme:registry=https://npm.pkg.github.com`, so `@acme/...` requests go to GitHub while everything else still resolves from the default registry, and it stops a developer accidentally publishing the library to the public npm registry. The credential is a separate line, `//npm.pkg.github.com/:_authToken=...`, holding a classic token with `read:packages` or `write:packages`; it belongs in the per-user `~/.npmrc` or an environment variable, never in the committed project file. In GitHub Actions, `actions/setup-node` with `registry-url` and `scope` writes both lines and reads the token from `NODE_AUTH_TOKEN`, which you set to `GITHUB_TOKEN`.
code
ini · 5 lines# project .npmrc, committed
@acme:registry=https://npm.pkg.github.com
# credential line: in ~/.npmrc, or written by setup-node in CI
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}go deeper
Remember that the npm registry on GitHub only takes scoped names, that the scope is the owning account, and that a classic token is needed even to install.
Explain the split between the committed routing line and the per-user credential line, and how setup-node writes both on a runner from NODE_AUTH_TOKEN.
Diagnose install and publish failures by which half of the configuration is missing, and keep tokens out of committed files across every repository that consumes the library.
Decide whether internal npm libraries belong on a registry tied to the code host or on a shared one, weighing scope ownership, token types and onboarding cost.
## What the npm registry in GitHub Packages expects **GitHub Packages** runs an npm-compatible registry at `https://npm.pkg.github.com`. Unlike the public npm registry, it hosts **only scoped packages**: every package name has the form `@NAMESPACE/PACKAGE-NAME`. The namespace is not a free choice. It is the **personal account or organisation** that the package belongs to, written in lowercase, because package names and scopes on this registry may only use lowercase letters. A library owned by the `acme` organisation is therefore `@acme/billing-client`; the same code published by the user `alice` would be `@alice/billing-client`, a different package under a different owner. The scope is how GitHub Packages knows **which account to file the package under and where to route requests**. That is why the scope in `package.json` and the namespace in the configuration have to agree with the real owner. ## The two lines a client needs npm reads its registry settings from `.npmrc` files. For GitHub Packages two different lines matter, and they belong in different places: | Line | What it does | Where it belongs | |---|---|---| | `@acme:registry=https://npm.pkg.github.com` | routes every `@acme/...` package to GitHub Packages | the project's `.npmrc`, committed next to `package.json` | | `//npm.pkg.github.com/:_authToken=TOKEN` | supplies the credential for that host | the per-user `~/.npmrc`, or a variable reference in CI | The routing line is safe to commit and has a useful side effect: with it in place, `npm publish` cannot silently send the library to the public npm registry. The token line must never be committed with a real value. How npm resolves scopes and `.npmrc` files in general belongs to npm's own material; what is specific here is the host and which token it accepts. If the project consumes packages from two GitHub owners, it needs **one routing line per namespace**, because by default the configuration routes only the scope you named: ```ini @acme:registry=https://npm.pkg.github.com @example-org:registry=https://npm.pkg.github.com ``` ## Which token goes in the auth line Outside a workflow, the only personal token GitHub Packages accepts is a **personal access token (classic)**: - `read:packages` to install, with read access to the package on your account; - `write:packages` to publish, with write access; - a token is required even to install a **public** npm package, unlike public container images. On npm 9 and later, `npm login` against a private registry defaults to a browser flow, so GitHub's documentation uses `npm login --scope=@acme --auth-type=legacy --registry=https://npm.pkg.github.com` and types the classic token at the password prompt. ## In a GitHub Actions workflow A workflow should not carry a personal token for this registry. The pattern GitHub documents: 1. the job declares `packages: write` (to publish) and `contents: read`; 2. `actions/setup-node` runs with `registry-url: https://npm.pkg.github.com` and, optionally, `scope: '@acme'` (by default it uses the account that owns the workflow's repository); 3. the step that runs npm sets `NODE_AUTH_TOKEN` to `GITHUB_TOKEN`. The action writes an `.npmrc` on the runner containing the routing line and `//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}`, so the token is read from the environment at run time and never written into the repository. ## Linking the package to its repository The `repository` field in `package.json` decides which GitHub repository the published package is linked to. Several packages can name the same repository, so every package built from one repository can link back to it. A package published without the field is not linked, and can be connected later. ## Laptop and pipeline, side by side The same two lines appear in both places; only the source of the token differs. | | Developer laptop | GitHub Actions job | |---|---|---| | routing line | committed project `.npmrc` | committed `.npmrc`, or written by `setup-node` | | token | classic token with `read:packages` in `~/.npmrc` | `GITHUB_TOKEN` through `NODE_AUTH_TOKEN` | | to publish | a classic token with `write:packages` | the job declares `packages: write` | A workflow in a **different** repository that installs the library cannot rely on its own `GITHUB_TOKEN` unless the package grants that repository access; that grant is a package setting, separate from anything in `.npmrc`. ## Symptoms and causes - **Install resolves `@acme/...` from the public registry and fails**: the routing line is missing or names the wrong scope. - **Install reaches GitHub and is refused**: no auth line for `npm.pkg.github.com`, or the token lacks `read:packages`. - **Publish is refused for a package named `billing-client`**: unscoped names are not accepted; rename it `@acme/billing-client`. - **Publish of a tarball over 256 MB fails**: npm versions on GitHub Packages must be smaller than that.
- In GitHub Packages, a developer's npm install of @acme/billing-client returns a 404 from the public npm registry. What do you check first?Whether the project's `.npmrc` routes the `@acme` scope to `https://npm.pkg.github.com`. Without that line npm asks its default registry, where the package does not exist. If the line is present and the request reaches GitHub but is refused, the next check is the auth line for `npm.pkg.github.com` and whether the classic token carries `read:packages`.
- Why does GitHub Packages' documentation recommend a committed scope line in .npmrc for a private library?Because it routes the library's scope to GitHub Packages for everyone who clones the project, so `npm publish` cannot send it to the public npm registry by mistake. The same line also makes installs of that scope go to GitHub without each developer configuring it by hand; only the token stays per-user.
- You can publish an unscoped npm package to GitHub Packages.
- Any scope works as long as the repository field points at GitHub.
- Commit the _authToken line with the token so CI can install.
- Public npm packages on GitHub Packages install without any token.
- One scope line in .npmrc covers packages from every GitHub organisation.