Using private GitHub repos with NPM

We do Node JS Consulting.

We've delivered complex, enterprise applications for billion dollar companies and small product shops. Our specialty is data-driven architectures, analytics, machine-learning and visualization.

One architecture we use in large applications is modularity through separate NPM modules. Where we have reusable code, like data models or utility methods, we’ll componetize them as separate GitHub repos - this helps us ensure modularity as well as simplifying unit testing and continuous integration.

This is easy to do with public GitHub repos, where you can use npm install <github_url> to add the repo, but is more challenging with private repos and deploy environments (like Heroku or Docker) where providing SSH keys isn’t possible/recommended. GitHub provides a simple HTTP auth scheme that works where SSH isn’t an option.

Here’s a step-by-step guide that outlines how we do it.

1. Create a read-only GitHub account for deployments and set up permissions

Because you’ll be generating a private key with repository access, you’ll want to create a ‘deploy only’ account that has read-only permissions to the repositories you need to deploy. This is just a regular GitHub account, but be sure to add the user to the repositories you want to access via NPM.

2. Create a GitHub personal access tokens

Next, you need to create a personal access token which can be used to authenticate and access repositories under your deploy user.

It is generally a good idea to create a separate key for each application/repository you’ll be using, so that if the key becomes compromised, you can revoke it without breaking deploys on all your applications using this account.

To create a personal access token, go to your deploy users' Settings page, click on Developer Settings, then Personal Access Tokens.

Create a new access token, and give it a name such as 'App Deploy Token'. Be sure to copy the actual token.

3. Create the necessary GitHub url

GitHub offers an HTTP auth scheme for accessing private repos, where the personal access token created above is the account name and the password is . To create the NPM appropriate URL, you would do something like:

4. Add the repo to package.json

Now that you’ve created the URL, you can use it with the standard `npm install` command, and it will be added to `package.json` and `package-lock.json` like any other repo.

Security Notes

Remember, this private key is like a password, and you’ll need to secure it accordingly. For us, there is a trade off between committing this private key to source control, which is generally a bad idea, and ease of use/deployment. One way of making this less problematic is using the deploy only account created above instead of your GitHub user account with full access.