How to setup semantic release on Circle CI

How to use CircleCI to publish new versions of your NPM modules.

There are problems currently with Travis CI due to DDoS attacks, and my favorite new process while working with NodeJS is not working. I would like to be able to use CircleCI

  • a very fast and intuitive continuous integration service, to unit test and publish new versions of my modules automatically using semantic-release service.

Here is step by step guide how to do this

Semantic-release setup

You need to install the command line tool first

npm install -g semantic-release-cli

Now from your project, run it in setup mode. Answer questions, like NPM username, GitHub authentication, etc. At the last question "What CI are you using?" pick option "Other (print tokens)". You will see something like this

$ semantic-release-cli setup
? Is the GitHub repository private? No
? What is your npm registry?
? What is your npm username? bahmutov
? What is your npm email? [email protected]
? What is your GitHub username? bahmutov
? What is your GitHub two-factor authentication code? 739958
? What CI are you using? Other (prints tokens)


Note: the setup step removes the version property from your package.json. To avoid constant NPM warnings, I follow Kent C. Dodds' advice and add back a placeholder property

"version": "0.0.0-semantic-release"

CircleCI setup

  • Add your project to CircleCI (typical series of steps, just like any other CI). Then open the "Project Settings" and select tab "Environment variables". Usually the direct url for this tab is something like<username>/<project name>/edit#env-vars

  • Add 2 new environment variables - the tokens you got in the previous step.

  • Add circle.yml file to your project with post test command to run the semantic-release NPM script. See directions in the next step.

Tell semantic-release to use condition-circle plugin

By default, semantic-release uses condition-travis module to verify that it is running on Travis CI before publishing to NPM. We need to use a different verifyConditions plugin to check CircleCI environment instead. Luckily, I wrote condition-circle you can use ;)

It is very simple to setup, just follow the directions in condition-circle


Don't forget to add the semantic-release badge to your README; let everyone know there is some system to the semver madness!

Update 1: CircleCI works by default

Today CircleCI should work with semantic release straight out of the box. The only note is that semantic release skips a deploy from a pull request build. The CI is determined using package env-ci from the environment variables. Thus you need to "trick" the release job to not know it is running from a pull request job on Circle via environment variables.

Error message you usually see on CircleCI when releasing from a pull request:

This run was triggered by a pull request and therefore a new version won't be published

Fix by setting the environment variables

# allow CircleCI to release beta versions
# from pull request build jobs
- run:
name: Semantic release 🚀
command: npx semantic-release
# by tricking Circle and removing the environment variables