install-scoped-internal-or-private-npm-packages-from-gpr.md

Installing Scoped, Internal or Private NPM Packages from GitHub's Package Registry

If you're trying to install a scoped, internal or private library and you run into authentication or not found errors, please continue reading:

Package not found error while installing

Follow the GitHub docs on installing packages from GPR. To install private or internal packages in a GitHub workflow, you'll need to add a GitHub Action Secret to the repository. Organizations that publish packages from multiple repos should provide an organization-level access token and share that token among repos that need to install other internal or private packages within the organization. Organization secrets can be shared with specific repos by an organization admin.

Installing from a single private or internal source

To configure NPM to install private or internal packages from GitHub Package Registry (GPR), two things are required:

1. Add an .npmrc file that specifies the registry you want to use. Scoping the registry to just the scope of the private package allows npm to also install public packages from the NPM registry.

@OWNER:registry=https://npm.pkg.github.com/

2. Configure NPM within GitHub Actions:

steps:
  // ...other steps

  - name: Set up Node.js
    uses: actions/setup-node@v3
    
  - name: Install Dependencies
    run: npm ci
    env:
      NODE_AUTH_TOKEN: ${{ secrets['<your-token-name>'] }}

  // ...other steps

NPM will be able to install public packages and packages from your internal or private package repository in GPR using the auth token you provide.

Installing from multiple internal or private sources

For more complex situations, it may be necessary to install packages from multiple internal or private destinations. To do so, create an .npmrc file that adds the auth token to the registry url for each destination.

⚠️ Do not commit this file ⚠️

Instead, place this in your user folder (e.g. ~/.npmrc).

@OWNER_1:registry=https:/npm.pkg.github.com/_authToken=<first-token>
@OWNER_2:registry=https:/npm.pkg.github.com/_authToken=<second-token>

And to accomplish this in a GitHub Action workflow:

  steps:
  // ...other steps

  - name: Set up Node.js
    uses: actions/setup-node@v3

  - name: Set up NPM Registries
    env:
      FIRST_TOKEN: secrets['<first-token>']
      SECOND_TOKEN: secrets['<second-token>']
    run: |
      echo "@OWNER_1:registry=https:/npm.pkg.github.com/_authToken=$FIRST_TOKEN" >> .npmrc
      echo "@OWNER_2:registry=https:/npm.pkg.github.com/_authToken=$SECOND_TOKEN" >> .npmrc

  - name: Install Dependencies
    run: npm ci

  // ...other steps

Unauthorized error while installing

For Personal Access Tokens (PAT) on your work computers, you'll need to add access to the package's organization on the PAT. If you are not part of the organization where the package is published and should be, please talk with the organization's admin to get access. Then follow GitHub's documentation for Authorizing a personal access token for use with SAML single sign-on.