neekey's blog


Set up automatic CI & NPM release with semantic-release


Setup semantic-release in your project is pretty easy:

npx semantic-release-cli setup

then you will be asked about your npm and github credentials

In terms of travis CI, it will setup the integration with github and the environment variables.

Release a new version

release a new version is easy, but still you need to notice:

  • it only happens on master by default (you can customize the configuration)
  • new release will only be made when you have commits followed special format, for examples: feat(pencil): add 'graphiteWidth' option

A built with a new release can be seen here:

[Semantic release]: Analyzing commit: fix(test): update fix test
[Semantic release]: The release type for the commit is patch
[Semantic release]: Analyzing commit: init
[Semantic release]: The commit should not trigger a release
[Semantic release]: Analyzing commit: Initial commit
[Semantic release]: The commit should not trigger a release
[Semantic release]: Analysis of 3 commits complete: patch release
[Semantic release]: There is no previous release, the next release version is 1.0.0
[Semantic release]: Call plugin verify-release
[Semantic release]: Call plugin generateNotes
[Semantic release]: Call plugin prepare
[Semantic release]: Wrote version 1.0.0 to package.json
[Semantic release]: Wrote version 1.0.0 to package-lock.json
[Semantic release]: Found 2 file(s) to commit
[Semantic release]: Creating tag v1.0.0
[Semantic release]: Prepared Git release: v1.0.0
[Semantic release]: Call plugin generateNotes
[Semantic release]: Create tag v1.0.0
[Semantic release]: Call plugin publish
[Semantic release]: Publishing version 1.0.0 to npm registry
+ semantic-release-test-repo@1.0.0[Semantic release]: Published GitHub release:
[Semantic release]: Published release: 1.0.0

semantic-release will create a tag back to your repo, and a new version of npm package is ready, but by default, semantic-release will not update the version of package.json back to your repo

Update package.json version

To enable this feature, we need a semantic-release plugin:

To use the plugin, we need to:

npm i @semantic-release/git

and then update the config in /path_to_your_project/.releaserc (create one):

  "prepare": [
      "path": "@semantic-release/git",
      "assets": [
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"

if you trigger a new release again, you should be able to see an automatic commit back to your repo to do the update.

Am I Satisfied?

The little tutorial above seems quite simple, but for a realy project maintainer, I am not 100% satisfied about semantic-release for several reasons:

  • Its documentation is not well enough, I still find myself spending a lot time digging around
  • The commits format based strategy is too strict, it will be quite tedious if you have to ask your contributors to commit their commit with special format
  • It does not support multiple CI buids, for example I have both Travis and Appveyor, semantic-release is not able to tell if both of the CIs have passed.

The workflow I want

To be honest, I total understand the intention of semantic-release’s strict rules, which follows the best practice. but for me and a lot small project, we just need some tool that is easy to use and understand.

A tool with following features sounds more than enough to me:

  • can do NPM release on master and use whatever in package.json as the new version number. it’s more predictable and flexible.
  • can create a tag using the version number as name and collect tag commits (no format required, just list them)

with a tool like this, i can simplely setup a workflow like bellow:



master always reflects the lastest package on NPM, and is the only branch that will trigger a new release


once a new release is ready, I will create a new release branch and bump a new version for it. if everything for the new release ready, I can just merge it to master.


a daily used development branch. can be used to accept PR from contributors. Once I have accumulated enough updates, I can create a release branch from develop.


a independent feature branch, once ready can be merged to develop.

The whole idea is from

Tools & Services I Use

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.