Integrating a private registry with GitHub Actions

If you are using GitHub Actions as the CI/CD service for your build chain, you may be looking for a way to include private packages in your builds.

The solution: install your package dependencies from a private npm registry by configuring a user-defined package source!

And integrating a Bytesafe private registry with GitHub Actions couldn’t be easier. So let’s look into how we can setup GitHub Actions to install package dependencies in this way.

But first: the basics behind using a private registry

The default registry when using npm, is the public npm registry. It contains public packages that are available for any developer to pull required packages from.

But teams often require a separate and private home for their internal packages. Packages that are their own proprietary code, that is never intended to be published to any public registry. But still need to be shared internally and used in builds.

In such cases, organizations use a private registry to hold their packages. A private registry can either be something that is self-hosted or a service provided by a specialized provider.

GitHub Actions

GitHub Actions is a workflow automation tool provided by GitHub. With the widespread use of its repository tool, it is no surprise that the popularity of its related (and to an extent included) automation tool only continue to rise.

Users can build, test, and deploy code according to workflows they define and trigger the workflows based on certain events, like the push of code to a GitHub repo.

To get the CI/CD to install dependencies using the private registry, we need to:

1. Provide GitHub Actions with custom configuration for the registry to use, as well as related access token
2. Define our Actions workflow for what steps are to be run as part of our build

Configuring use of private registry

Like many similar services, GitHub Actions relies on the .npmrc (npm runtime configuration) file to provide custom instructions to be used by its built-in npm cli.

If no custom configuration is provided, npm will default to fetch required package dependencies from the public registry.

But as our example uses private packages not available in any public npm registry, we will use .npmrc to set a custom parameters for:

• registry (provide an URL for our private registry)
• authToken (provide the authentication details required to communicate with the private registry)
• always-auth=true (force authentication details to be sent alongside requests to private registry)

The authToken will be defined as an environment variable, but more on this later.

For our example we want to pull all packages from the private registry, as such we will override the default, by simply setting a new registry URL to be used for all packages.

If we want to pull only a subset of packages from a registry, we can make use of @scope and only packages matching the scope will be fetched from that registry.

Putting together the .npmrc file

First step is to provide on the registry URL that should be used. Bytesafe private registries use the following pattern:

Next we need to create an authToken to be used with requests to the private registry. Let’s create a fresh token to be used solely for this CI/CD chain:

We add the generated token from the output to GitHub’s built-in secret store (to make sure we do not leak credentials).

Create a new repository secret called NPM_TOKEN and save the created token. For more information on storing of repository secrets, refer to GitHub’s official documentation on the subject.

We will configure our workflow to use the environment variable NODE_AUTH_TOKEN, which in turn links to the NPM_TOKEN secret.

At this point your .npmrc file should look something like this:

If you are happy with the state of your file, go ahead and push it to the related repository.

Alternative: Have GitHub Actions create the .npmrc file for you

GitHub Actions can create the .npmrc config for you, with the actions/setup-node@v1 action.

If you use this approach, enter the same registry URL that you would use in .npmrc and always-auth: true when configuring the GitHub Actions workflow yaml file.

Define the GitHub Actions workflow

Now we are ready to define the workflow and what actions should be run on our behalf.

This is done by creating a yaml file that we store in the projects .github/workflows directory. The yaml file contains the steps we want to run through.

We use it to tell GitHub Actions: what trigger to use (push), to checkout the code, what parameters to use with node and to install the dependencies as part of our example:

Voila! With that we have now configured a GitHub Actions workflow using packages from a private registry.

With a setup like this, each time code is pushed to the registry, GitHub Actions will safely install the dependencies using npm ci with --ignore-scripts flag set. And obviously this is only an example. Users can design the workflow to perform the actions required for their needs.

After a workflow has been triggered, users can check the status and progress of the job in the Actions tab in GitHub.

Want to integrate with other cloud platforms or CI/CD services?

The basic principle of using the .npmrc file to provide custom configuration is applicable for many other similar services as well.

Users that want to integrate Bytesafe with other services can refer to our general guide on integrating services with Bytesafe on our docs site for more information.

If you need more GitHub Actions specific details to get your build chain up and running, refer to the official GitHub Actions documentation for setting up node.js.

And lastly, the principles of using a private source with GitHub Actions also applies for other package ecosystems. If you need a private repository for your Java or .NET artifacts, use Bytesafe for Maven and NuGet.

Thanks for reading!