Manual semantic release setup

I use semantic-release for most of my projects. It has completely freed me from thinking about the NPM publish step, which now happens automatically. But sometimes I do not go through the semantic-release-cli setup command, instead I prefer to set things up manually. This avoids the NPM and GitHub logins, or installing semantic-release-cli global tool.

This guide assumes you are using the public NPM registry (even with private scoped modules) and GitHub. This guide also assumes Travis CI, although other CIs are supported too.

Grab the NPM auth token

Login into NPM registry from the command line. This adds an auth token to your .npmrc file in the home directory. Grab the token

$ cat ~/.npmrc | grep _authToken
//registry.npmjs.org/:_authToken=<XXXX-YYYY....>

Add GitHub access token

Open the browser at https://github.com/settings/tokens and add a new personal token. Give it a name, like semantic-release-timer-bar. You should allow the following permissions to make sure the CI can push new tags and release notes to GitHub. Only check the sub permissions, not the top level groups.

repo
  repo:status
  repo_deployment
  public_repo
admin:org
  read:org
admin:repo_hook
  write:repo_hook
user
  user:email

Make sure to copy the generated token, since it will not be displayed again.

Setup the CI project

Enable the CI build for the given project. Go to the CI project settings and add two environment variables GITHUB_TOKEN and NPM_TOKEN. Copy the values you saved previously.

Add the CI-specific configuration file to the repository. The CI should run the script "semantic-release" after successful build of the master branch. For example, here is a typical Travis configuration file.

sudo: false
language: node_js
cache:
  directories:
    - node_modules
notifications:
  email: false
node_js:
  - '6'
before_script:
  - npm prune
script:
  - npm run lint
after_success:
  - npm run semantic-release
branches:
  except:
    - "/^v\\d+\\.\\d+\\.\\d+$/"

Or if you use CircleCI using condition-circle you can use the following settings file

machine:
  node:
    version: 6
test:
  post:
    - npm run semantic-release || true

You should also add the CI badge to the project's README file. For example, here is the Markdown for a sample project (replace the user and project names). I also add "semantic release" badge.

[![Build Status][build]][link]
[![semantic-release][semantic-image] ][semantic-url]
[build]: https://travis-ci.org/<username>/<repo>.svg?branch=master
[link]: https://travis-ci.org/<username>/<repo>
[semantic-image]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
[semantic-url]: https://github.com/semantic-release/semantic-release

Add the release module

The semantic release module will actually inspect the GitHub commit log since the previous NPM publish, determine the new (if any) package version and will actually push the new version.

$ npm i -D semantic-release

Then add a new script command to package.json

{
  "scripts": {
    "semantic-release": "semantic-release pre && npm publish && semantic-release post"
  }
}

I also recommend replacing whatever the current version listed in the package file with a text clearly informing that the actual version is determined automatically.

{
  "version": "0.0.0-semantic-release"
}

Push a new commit to the GitHub and watch the CI publish it.