Private NPM repository, Github Packages and Heroku

It took a while to put together this simple, on the first look, combination.

Problem: Node project, hosted on Heroku, that needs access to a private NPM repository on Github.

Solution that worked for me is below. I will use fake repository name @foo/bar in this guide where foo - organization/user name on Github, and bar - a repository name, e.g.

1. Publish private NPM repository on Github Packages #

Generate a new personal access token (PAT) on Github #

It will be used to authenticate the private package in your consumer project. To create a PAT got to go to Settings -> Developer Settings > Personal Access Token -> Generate new token.

Select the scopes of repo, write:packages and click on the Generate token button.

Make sure to save this token in a secure place, e.g. your password manager - you will need it later.

Modyfy your private repo's package.json: #

Add name and semantic version, if it's not there yet:

  "name": "@foo/bar",
  "version": "1.0.0",

Add registry information:

  "publishConfig": {
    "registry": ""
  "repository": {
    "type": "git",
    "url": "ssh://",
    "directory": "@foo/bar"

Add .npmrc file #

The private repository needs to configure an alternate registry with access tokens - Github Packages in our case. Create .npmrc config with the following content:

; Use NPM registry by default

; GitHub Packages registry for your org's packages

Add the personal access token #

Make sure your environment has NPM_AUTH_TOKEN variable - the toke from step 1, you can use the following command to export it:

export NPM_AUTH_TOKEN=token

Publish your package #

To publish your package you will need to login to Github Packages with your Github user's credentials on your local machine:

npm login --scope=@foo --registry=

Once logged in, type npm publish, then you will be able to find your package under Packages tab in your organization homepage on Githib, or

2. Include private repository in your consuming project #

Add .npmrc file in your project #

Copy .npmrc file from your private repository (step 1.3) to you consuming project (same content).

This file tells NPM to build packages belonging to @foo from a custom registry.

Add the token #

Make sure your environment has NPM_AUTH_TOKEN (your personal access token from step 1):

export NPM_AUTH_TOKEN=token

Install your private package #

npm install @foo/bar

It should like the following in your package.json:

  "dependencies": {
    "@foo/bar": "1.0.0"

Use a package in you code #

Now you should be able to use this repository in your code:

import Module from "@foo/bar/path/to/module";

3. Enable on Heroku #

According to Heroku documentation to enable access to private NPM package on Heroku you need:

  1. .npmrc file (which we already added to your project in previous step)
  2. adding the token as a config var in your Heroku app

Go to Dashboard -> your app -> Settings -> Config Vars and add NPM_AUTH_TOKEN and its value.

4. Enable on Github Actions #

Add access token to Github actions (if actions are used):

Modify action config #

Add the environment variable into your action .yml file:


Add token to Github secrets #

Go to Organization -> Settings -> Secrets -> Actions on Github and add a new secret NPM_AUTH_TOKEN with your personal access token value.