Building Github Actions CI for an npm package

This is now deprecated :(

Today I would like to go through the process I went through for setting up a CI build pipeline for one of my published NPM packages, React Twitch Embed Video.
If you are not already part of the Github Actions Beta you can request access here: Github Actions.

Table Of Contents

• Part 1: Creating a lint workflow
• Part 2: Creating release workflow

Part 1: Creating a lint workflow

In the first part of this guide well create a linting workflow that you can use to check against your branches or pull requests.

Getting started

After getting access to the Beta the first thing you will notice in you repository homepage is the new Actions tab at the top.

Clicking on Actions you should see the following message in nice big bold letters Create your first workflow

Let's get started creating our workflow by clicking on Create a new workflow

Step 1: Creating a workflow

Once you're ready to start building your first workflow you will be presented the custom Github workflow editor.

This is basically where we will live while we start building out the first part of our workflow for our npm package.

To get started using Github's visual editor click create a new workflow

Now, this is where the fun begins. Now the visual editor should be initialized with a Github Actions workflow trigger. This is where we name our workflow and configure the type of repository event we want to listen to. Were going to be listening to the default push event in our use case.

Triggered on a push to a repository branch. Branch pushes and repository tag pushes also trigger webhook push events. This is the default event.

Here is a link to the docs describing the other events https://developer.github.com/actions/managing-workflows/workflow-configuration-options/#actions-attributes

Step 2: npm install action

Now let's make our first action! Just like the outline on the screen says we will drag the blue bullet to it and make our first action. Once that's completed we now get to select what our first action will be.

On the right, we will be presented with Featured actions and we immediately see GitHub Action for npm, exactly what we want.

Clicking the Use button will add the npm action to our workflow.

Now we need to install our dependencies before we can lint our code. In the right modal in the args text field input out first npm command:

 install

Let's also update the label to something more descriptive other than GitHub Action for npm, something like npm install.

Click Done at the bottom of the modal and BOOM we have our first action.

Step 3: Lint action

Now that we have npm install done, let's create our lint action.

We will follow the exact same steps with did with creating the npm install action, but in args well input:

lint

As you might have already noticed the Github Action for npm will run any npm command you configured in the package.json so you can use this same workflow for running other npm commands you might run as part of your development process.

Step 4: Saving workflow and trigger CI

At this point, let's save our brand new linting workflow and watch it do its magic. In the top right you can click Start commit and commit your newly created file.

After submitting your new commit you should see your new workflow starting to do its thing by click on the Actions tab on your repository. You should then see something similar to this (well add some of the other actions you see in a bit)

The left side has the job history and the right side visualizes the progress of the workflow and links to additional information like logs. You will either see a nice green checkmark for passing tests or a red x if a failure happened.

Part 2: Creating release workflow

In this part of the guide, I will walk you through creating a release workflow so that you can publish a new tagged version of your package to npm registry.

Step 1: Filtering for Git Tags

Now let's create a new action that will filter only Git Tags events. Let's drag that blue little dot on our lint action and create a new action.

Now select Filters for GitHub Actions and click use.

In args input:

tag

This action will now filter for only Git Tag events. The nice thing is that this filter won't fail our builds if it stops at this point in the workflow (good when running against pull requests).

Visit https://github.com/actions/bin/tree/master/filter to find out all the different events you can filter for

Step 2: Building package for release

Before we can publish our package we need to build a release version. Well follow the same steps we used to create npm install and npm lint actions and use the trusty GitHub Action for NPM.

This time in args input your production build command, in my case it was:

release

Now after we filter for a Git Tag event well build the release version of our package.

Step 3: Publishing package to npm

Now, lets set up our last step, publishing our package. We again lean on GitHub Action for NPM that we have used to create our npm install, npm lint and npm release action.

But there will be one minor difference, we need to generate an authentication token from the npm registry and then add a secret called NPM_AUTH_TOKEN to the repo.

Checkout the Github Action for NPM repo for the details https://github.com/actions/npm/tree/59b64a598378f31e49cb76f27d6f3312b582f680/#secrets

In the args for this action input:

publish

Next, we need to follow these instructions to generate your auth token on npm: https://docs.npmjs.com/creating-and-viewing-authentication-tokens

After we have our token we need to add the auth token as a secret to our repository. Back in our new release action, click on Create a new secret.

Name your new secret:

NPM_AUTH_TOKEN

And insert newly generated npm registry authentication token as the value.

Click Add secret

Make sure you newly added secret is checked, so the publish task has access to it.

Click Done and it should look something like this:

Step 4: Save your updated workflow

Now save your new and improved workflow by committing your new changes. Just like last time, the CI process will kick off but since this is a standard commit the process will terminate at the Filter Tag action we created. You should see the later workflow actions marked skipped when looking in the Actions tab.

Step 5: The finish line.... Tag a new release

Now our Github Actions workflow is complete. All you have to do now is Git Tag a new release and watch your workflow do its thing. If something goes wrong to check the logs for any potential issues and debug them.

Conclusion

Thanks for sticking around till the end of this and hopefully you found this helpful. I plan to add a follow-up post on other Github Actions lessons learned.