How to Use a Private Github Repo as a Dependency with Yarn & NPM

One of the really cool, less known and typically forgotten features of NPM and Yarn is the ability to install git repositories directly as part of the package install command.

Whether you are working on a serverside javascript project using NodeJS or a client-side application using any of the build tools such as Webpack, Gulp or even, good old Grunt, you might come to the point where you need to use a private or public GitHub repository as a dependency in your package.json.

Here, we will be going over how to reference a Github repo as one of the modules in your package.json. We will start with a public repo and then go over how you can set it up using a private repo.

1. Using a Public Repository as a Dependency

The general syntax for installing a package directly from GitHub follows the structure below. You will note that this is the process for installing the package via the command-line.

npm install git+ssh://[email protected]:/]
npm install git+ssh://[email protected]:/[#semver:^x.x]
npm install git+https://[email protected]//
npm install git://github.com//
npm install github:/[#]

To use the GitHub repo as a dependency in your package.json, you can use the following syntax below:

"dependencies": {
  "bar": "git://github.com/foo/bar.git"
}

For public repositories, the syntax listed above works for all git based version control system such as GitLab, BitBucket, among others.

2. Using a Private Repository as a Dependency

When it comes to using a private repository as a module in your package.json. The syntax and the idea are very similar to the public version, the main change is that a form of authentication is added to the git syntax. There are 2 approaches to achieve this form of authentication, namely using HTTPS and SSH.

2.a. Using a HTTPS

The first approach here is to use a special GitHub system user with access to the repository and generate an access token for this user that can be used directly as basic authentication in the HTTPS call.

To do that go to Settings > Developer settings on GitHub. There, you can select the Personal access tokens and click Generate new token. Once you define the scopes for the token you can use this token in package.json as follows:

Be sure to select the types of access the system user needs. Typically, you would want to give only read access to the system user to limit risk. We will talk more about the downsides to using this approach later.

"dependencies": {
  "bar": "git+https://[INSERT PERSONAL TOKEN HERE]:[email protected]/foo/bar.git"
}

Once you have successfully added the token to your package.json, You can now delete your node_modules and then run npm install command. This should install the package from the GitHub repo.

The main disadvantage and obvious downside of this approach is that you are required to commit the token, however, as long as it’s for a private repository and you created a special read-only system account for this, you should be ok. There are actually various situations where using the SSH approach we are going to discuss next is not possible to do, an example is when you run NPM install within Docker containers or in environments where you cannot use SSH keys.

2.b. Using SSH

The second approach is very similar to the public option discussed in point #1 above, it just uses SSH for authentication. In this case, the URL to reference does not need any token like in the code sample below.

"dependencies": {
  "bar": "git+https://github.com/foo/bar.git"
}

For this SSH approach to work, you need to be sure you have access to this particular repository and you have generated SSH keys for yourself or the user account that’s going to run this install in Settings > SSH and GPG keys. Follow the guide on GitHub on how to set up SSH keys.

Even though the SSH option is clearly more secure and should be the preferred approach whenever you need to do this. There might be a case where the token works better or is the only option available.

If you enjoyed reading this article, feel free to follow us on Facebook and Twitter, or even better, sign up for our newsletter for regular updates.