Using Github Actions to Publish the HTML5 Boilerplate npm Package

We just released HTML5 Boilerplate 7.3.0. As part of that release we integrated Github Actions in order to publish our npm package when we cut a Github release. Doing so was pretty easy. This is how I ended up doing it.

To start, I enabled Github Actions for the repo. To do so check “Enable local and third party Actions for this repository” on the “settings/actions” tab of the repository.

Next, I created a workflows directory inside our .github folder and added a new file called npmpublish.yml

Here’s what that file looks like. It’s based on one of the default Actions that Github provides, conveniently.


name: publish npm

on:
  release:
    types: [published]

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

  publish-npm:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: 12
          registry-url: https://registry.npmjs.org/
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

Let’s go through what it does. The first line gives the action its name.


name: publish npm

This is the name that will show up in the Actions tab within Github.

The next section indicates that this action should run on a release event, specifically when a release is published. Github releases are basically enhanced git tags and we use them to neatly package up our dist folder for easy consumption as a zip folder. The type property actually accepts a list, but since we’re publishing to npm, we only want to do this when the code is actually released.


on:
  release:
    types: [published]

The next section contains the jobs that we will run, build and publish.

First up is build. I just used the default runs-on option- ubuntu-latest, since I’m not doing anything particularly fancy. This just means my work will run on a machine running Ubuntu.

Following that are some default Actions:

actions/checkout@v1, which checks out your repository, so that your workflow can access the contents of your repository.
actions/setup-node@v1, which installs a specific version of node for your project to use. In our case we’re using node version 12.

Finally, with the environment set up, we run two commands. npm ci, which is a continuous integration version of the more familiar npm install command. npm ci uses package-lock.json and some other optimizations to build out node_modules dependencies more quickly than npm install. Then we run npm run build which is our standard build command. That is an alias for gulp build and it generates the contents our our dist folder.


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

At this point we’re ready to publish to npm. That happens in our next job, npm-publish. Here we have a new wrinkle, the needs property. This just means that it requires the previous build job to be there before it can run. After that, the setup is similar. It runs on ubuntu-latest, it checks out the code and sets up our node environment. The one change in the environment set-up is that it sets the registry-url to https://registry.npmjs.org/. This is the default, but your organization might have a different private registry. You would set that here.

Finally, we run npm publish which does the actual job of publishing the project out to npm. This is just the standard npm command. This command uses the environment variable NODE_AUTH_TOKEN for authentication. The following section shows how to set up authentication for npm.


 publish-npm:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: 12
          registry-url: https://registry.npmjs.org/
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

To set up a token to use for authentication with npm, first go to npmjs.com/ and open up the tokens page.