Automate your NPM publish with GitHub Actions

De Ville Weppenaar
Dec 18, 2018 · 6 min read
Photo by Christin Hume on Unsplash

It’s no secret that I am a huge fan of automation. I always get excited when something is released that can potentially simplify my workflow or take a couple of tedious tasks off my plate. GitHub actions is one of the new kids on the block, and it promises to do just that!

github actions

GitHub recently started granting some of their users access to GitHub Actions. At the time of writing this feature is in beta, but anyone can request to be added to the beta program.

Each GitHub action performs a specific step in a process. You can think of them as things you’d often configure as NPM scripts in a package.json file, but they can pretty much take on whatever form you need them to.

A basic action consists of:

  • a unique name
  • a needs section that describes what actions it depends on
  • a uses section that lists what this action is based on (similar to from in a Dockerfile)
  • a runs section that represents the command to execute

For example:

With actions being your building blocks, you arrange them in an order that achieves a specific goal. This arrangement of actions is your workflow and our purpouse today is to publish a dependency to NPM.

For more information on workflows and actions, including creating your own, take a look at the official documentation.

what you’ll need

In order to get publishing to NPM with GitHub actions, you will need:

  • a project to publish
  • an npm auth token
  • access to github actions

the project

We need something to publish to NPM, so for the purpose of this artcle we’ll use a simple folder structure:

Where:

  • ./.github/main.workflow contains the GitHub actions and workflow
  • ./lib/index.js holds our module code
  • ./test/index.test.js has our all our module tests
  • ./package.json contains our dependency details

the token

In order for us to be able to publish to NPM, we’ll need to authenticate with the service using a token. Let’s go ahead and create a new token.

Access the tokens section from the user dropdown menu in the top right:

Select Tokens from the menu

Then click Create New Token:

Click Create New Token

Next, select Read and Publish before clicking Create Token:

Select Read and Publish and click Create Token

Be sure to save this token since you will not be able to see it again. I personally use LastPass for details like this, but any secure storage will suffice.

the workflow

With the NPM token in the bag we’re ready to set up our workflow.

Our workflow consists of two distinct parts:

  • build and test executes whenever we push code to our GitHub repo and ensures we run some basic tests
  • publish on release executes when we create a GitHub release and takes care of publishing our code to NPM

For both workflows we use the base npm action, which means the actions have runtime access to the npm cli. It’s important to note that both workflows are contained in the main.workflow file.

You can access the visual editor by clicking on the Actions tab of the repository.

build and test

Visual view of the build and test workflow

And the code looks a little something like this:

This workflow is considered successful when the test, coverage and lint actions complete without an error.

publish on release

Visual view of the publish on release workflow

With the code being:

Notice the difference from the build and test workflow. Aside from the fact that we have less steps to perform, we also have the addition of the secrets section that contains a reference to the NPM_AUTH_TOKEN.

This workflow is considered successful when the publish action completes without an error.

configuring the token

You associate the token with the action by configuring it as a secret. Secrets are the way you set values that are exposed as environment variables when the action is run.

Go ahead and click the edit button on the action. This should display the action edit menu:

Action edit menu

If this is done successfully you should see the NPM_AUTH_TOKEN on the publish action:

NPM_AUTH_TOKEN visible under the secrets

You can also access and update the token value from the settings tab of the repository:

Access the secrets from the repository settings

the tag

With the workflow in place, every push to GitHub will trigger the build and test workflow. That’s all fine and dandy, but we eventually want to have our dependency published. Our process involves creating a tag, pushing it to origin and then creating a release from the tag.

creating a tag

A tag can be creating via the terminal command: git tag v2.4.0

This will use the latest commit from the current branch to create a tag named v2.4.0. The next step is for us to get this shiny new tag onto GitHub (our origin in this case).

pushing a tag

You can push the tag to remote by issuing the following command: git push origin v2.4.0

creating a release

If the push command completed successfully, you should see the new tag on the Tags tabs under the Code. You can then create a new release from the ellipsis (…) menu on the tag:

Select Create release from the ellipsis menu on the tag

Enter any details that you’d like to include in the release and then click Publish release. Our GitHub publish on release workflow will then take care of publising our dependency on NPM.

wrapping things up

In this article we’ve seen how we can put GitHub actions to use to automatically publish our dependencies to NPM. This is only a small fraction of what’s possible, and the limitation is really just your imagination. Although you may encounter some minor issues here and there, GitHub actions is still a pretty polished feature for a something that is currently in beta.

Although there are tools that fulfil a similar roll in order to automate your CI / CD workflow, I really like the fact that it is baked into our favourite source control system. The benefit of a tight integration shouldn’t be underestimated.

I hope you’ve found this information valuable and that you are just as excited as I am for the potential that GitHub actions represents.

If you enjoyed this article, please do me a favour and like as well as share it.

Until next time! Keep on codin’!

further reading

If you enjoyed this article or would like to delve deeper into NPM publishing, be sure to check out these excellent posts:

Join our community Slack and read our weekly Faun topics ⬇

If this post was helpful, please click the clap 👏 button below a few times to show your support for the author! ⬇

Faun

The Must-Read Publication for Aspiring Developers & DevOps Enthusiasts. Medium’s largest DevOps publication.

De Ville Weppenaar

Written by

Software developer, automation addict, casual blogger, James Bond fan, amateur cat herder, eternal newbie — you guess the order.

Faun

Faun

The Must-Read Publication for Aspiring Developers & DevOps Enthusiasts. Medium’s largest DevOps publication.

More From Medium

More from Faun

More from Faun

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade