Automate JavaScript deployment of npm packages with Github actions

What does Factorio and CI/CD pipelines have in common?

Using Github actions to build and publish npm packages

Manual and, let’s face it, often quite tedious tasks can easily be automated with modern tools such as Github Actions. When combined with a private registry we can facilitate collaboration and increase quality by keeping better track of our code supply pipeline.

Full disclosure: I’m one of the founders behind the product Bytesafe (https://bytesafe.dev/) that offers free, secure and highly available private NPM registries.

Below I’ll describe, step by step, an easy workflow to setup, used for building and publishing Javascript npm packages. We will use a private registry which can be used as sandbox before releasing code into the wild. This way you may be able to find potential bugs before your end users do. We will be using Github actions to automate the build

What to ship, well… A package of course!

So you’ll probably have something way more interesting to build for your workflow, but for this post we’ll create a new empty package named “@niclas-test/test” with the below package.json that describes the package.

Step 1. Define the package

We’ll setup an package.json with some basic information, package name, git location etc.

{
  "name": "@niclas-test/test",
  "version": "1.0.0",
  "description": "My test package",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/niclas-g/test.git"
  },
  "keywords": [
    "private",
    "repo",
    "github",
    "actions"
  ],
  "author": "Niclas G",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/niclas-g/test/issues"
  },
  "homepage": "https://github.com/niclas-g/test#readme"
}

Let’s add something interesting to this package:

index.js

const myPackage = require('./package.json');
const getSecret  = () => {
  return 'thisisthesecret from version ' + myPackage.version;
};
exports.getSecret = getSecret;

Nice, our package is done, let’s head over to Github and define our Github Actions workflow, well, we’ll stay in our local environment as we define the workflow using code.

Step 2. Define the build process for Github Actions Workflow

Github actions reside in the dedicated directory github/workflows

name: Deploy from master 

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 12
      - run: npm ci

  publish-npm:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 12
          registry-url: https://<YOURREGISTRY>.bytesafe.dev/r/default
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

A couple of things to point out in the snippet above

1. The trigger, i.e. what will initiate the build and deployment of the package, the “on: push: branches: master” tells Github to build on all commits to master, but maybe you are building feature branches as well, just change accordingly to your needs.
2. The endpoint of the registry, i.e. where do we send out artifacts
3. The credentials needed to authenticate towards the registry,

Step 3. Set up a private registry

For this post, we’ll publish our package to a Bytesafe private registry. It’s free to sign-up and use, head over and set up your own private registry now, it’ll take less than a minute. I’ll wait here.

(There are of course other options out there and the workflow should be similar)

Done? Great!

In the Github workflow script we refer to a secret used by npm to authenticate towards the private registry:

NODE_AUTH_TOKEN: ${{secrets.npm_token}}

You configure this secret in the Github repository. It is this access token that will enable you to upload/publish your packages to the registry.

To setup additionally Bytesafe registries in the same account is trivial, but we’ll settle for the “default” one that is supplied upon account creation.

The credentials to this registry are shown on https://bytesafe.dev under the registry details page:

To acquire the token needed, we run the standard NPM command with the following options to login:

$ npm --registry https://<account>.bytesafe.dev/r/<registry> login
Username: bytesafe
Password: ****** 
Email: (this IS public) [email protected]
Logged in as bytesafe on https://<account>.bytesafe.dev/r/<registry>

Step 4. Get the API token for use in the automated build pipeline

After you have successfully logged in, you get the token with the following command:

$ npm --registry https://<account>.bytesafe.dev/r/<registry> token create
npm password: 
┌────────────────┬────────────────────────────┐
│ token          │ 01E54TK8T🤐🤐🤐🤐🤐🤐 B0TQ│
├────────────────┼────────────────────────────┤
│ readonly       │ false                      │
├────────────────┼────────────────────────────┤
│ cidr_whitelist │ null                       │
├────────────────┼────────────────────────────┤
│ created        │ 2020-04-05T09:26:26Z       │
└────────────────┴────────────────────────────┘

Step 5. Add token to Github Actions

Next, add the token to the Github repository, click Settings -> Secrets -> “Add a new secret” and name it “npm_token”, enter the data from the token row above.

Step 6 …And you’re done.

Go ahead and do:

$ git push

Head over to GitHub and to the actions tab in your repository and see the build progressing, chances are that you are to late, the build is usually quite fast:

And for validation: go back to Bytesafe web console and verify that the package was shipped:

And there you have it: A (very) basic pipeline that will build your code upon commits to master and deploy the packages to your private npm registry, ready to be consumed by your and your team’s applications.

^ Basic pipeline?