Automated semantic version releases powered by Github Issues.
Last updated 5 years ago by ericclemmons .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install github-semantic-version 
SYNC missed versions from official npm registry.


Automated semantic version releases powered by Github Issues.

travis build version downloads MIT License

Getting Started

1. Install

$ npm install --save-dev github-semantic-version


For example, in Travis CI's "Settings" tab for your project, you'll see:


For your GH_TOKEN create one in Github with repo credentials.

You can find NPM_TOKEN in your ~/.npmrc file:


Once these are in place, your new versions can be pushed back to Github & NPM without permissions & security issues.

3. Create labels

From your repo's Issues > Labels section, add three labels representing the major, minor, and patch level changes in your repo. Ex:

  • "Version: Major"
  • "Version: Minor"
  • "Version: Patch"

Add your label definitions to a gsv section of package.json, to a gsv.json file, or a .gsvrc file in the base directory of your project.

package.json example
  "gsv": {
    "majorLabel": "Version: Major",
    "minorLabel": "Version: Minor",
    "patchLabel": "Version: Patch"
gsv.json or .gsvrc example
  "majorLabel": "Version: Major",
  "minorLabel": "Version: Minor",
  "patchLabel": "Version: Patch"

Non-version Labels

Sometimes a PR should not increment and publish a new version, for example, when updating dependencies, tests, or docs. To support this, a 4th label named internalLabel can be used. When this label is found on a PR, it will be skipped.

  "gsv": {
    "majorLabel": "Version: Major",
    "minorLabel": "Version: Minor",
    "patchLabel": "Version: Patch",
    "internalLabel": "No version: Internal"

4. Add labels to issues

Add one of your custom defined labels to your open PRs:

As these get merged, github-semantic-version will use this to determine how to bump the current version. PRs merged without a label will be treated as patch releases.

If any un-tagged commits are pushed to master outside of a PR, they're automatically treated as patch releases.

5. Update .travis.yml

sudo: false
language: node_js
    - node_modules
  email: false
    - /^v[0-9]/
  provider: script
  script: npm run release
  skip_cleanup: true
    branch: master

6. Usage

As automation related to your code and publishing to the world can sometimes be scary, github-semantic-version operates with an additive functionality philosophy.



Displays the usage information.

github-semantic-version --bump

Update the package version, no CHANGELOG, don't push to Github, don't publish to NPM.

Meant to be used in a CI environment.

github-semantic-version --init

Generates a fresh CHANGELOG based on labeled PRs and any commits to master outside of any PR. Also calculates the package version based on those PRs and commits. Won't push to Github or publish to NPM.

Meant to be used outside of a CI environment to generate the initial CHANGELOG.

The expected workflow here is to ensure parity between the calculated version/changelog and your current repo version. Once that happens, you'll want to manually commit those changes (adding github-semantic-version as a dependency, the new npm scripts to run on CI success, the CHANGELOG, updated package.json, etc.) to master (or merge a labeled PR). Once CI builds successfully, these additions will be noted in the CHANGELOG (assuming that you specified the --changelog flag in your npm scripts).

github-semantic-version --changelog

Append the latest change to an existing CHANGELOG (must have already been generated by the --init flag above).

You'll want to run github-semantic-version --init outside of CI to generate the initial CHANGELOG before enabling the --changelog flag.

github-semantic-version --bump --changelog

Bump the version and append the latest change to the CHANGELOG.

github-semantic-version --bump --changelog --push

Bump the version, append the latest change to the CHANGELOG, and push the changes to Github.

github-semantic-version --bump --changelog --push --publish

Bump the version, append the latest change to the CHANGELOG, push to Github, and publish to NPM.

Other flags


The flags --bump and --changelog are meant to be used in a CI environment. Override this if you know what you're doing.


Append this to see output of what would happen without any writing to files, pushing to Github, or publishing to NPM.


Prepend DEBUG=github-semantic-version:* to the github-semantic-version command to show all debug output when running.

7. Update package.json

  "scripts": {
    "prerelease": "npm run build",
    "release": "github-semantic-version --bump --changelog --push --publish"


You can add a startVersion to the gsv section of package.json (or to gsv.json) that will be used as the starting point to calculate the package version of a repo. Ex:

  "gsv": {
    "startVersion": "2.5.0",
    "majorLabel": "Version: Major"

If you're working on a private project, you can leave out --publish, which means you have no need for your NPM_TOKEN either.


You can add a github object to the gsv section of package.json (or to gsv.json), which are options that will be passed to the Github API.

  "gsv": {
    "github": {
      "host": ""


By default, all PRs without a label will default to "patch". If you'd prefer to skip the PR instead of releasing, use the abortOnMissingLabel option.

  "gsv": {
    "abortOnMissingLabel": true


Define the addReleasedLabelOnSuccess and releasedLabel options to add a label to a PR once it has been successfully published.

  "gsv": {
    "releasedLabel": "Released",
    "addReleasedLabelOnSuccess": true

The releasedLabel defaults to "Released".


MIT License 2016 © Eric Clemmons

Current Tags

  • 7.6.0                                ...           latest (3 years ago)

33 Versions

  • 7.6.0                                ...           3 years ago
  • 7.5.0                                ...           3 years ago
  • 7.4.0                                ...           3 years ago
  • 7.3.0                                ...           3 years ago
  • 7.2.0                                ...           3 years ago
  • 7.1.0                                ...           3 years ago
  • 7.0.0                                ...           3 years ago
  • 6.1.1                                ...           3 years ago
  • 6.1.0                                ...           3 years ago
  • 6.0.0                                ...           4 years ago
  • 5.0.2                                ...           4 years ago
  • 5.0.1                                ...           4 years ago
  • 4.0.14                                ...           5 years ago
  • 4.0.13                                ...           5 years ago
  • 4.0.12                                ...           5 years ago
  • 4.0.11                                ...           5 years ago
  • 4.0.10                                ...           5 years ago
  • 4.0.9                                ...           5 years ago
  • 4.0.8                                ...           5 years ago
  • 4.0.7                                ...           5 years ago
  • 4.0.6                                ...           5 years ago
  • 4.0.5                                ...           5 years ago
  • 4.0.4                                ...           5 years ago
  • 4.0.3                                ...           5 years ago
  • 4.0.2                                ...           5 years ago
  • 4.0.1                                ...           5 years ago
  • 3.0.1                                ...           5 years ago
  • 4.0.0                                ...           5 years ago
  • 3.0.0                                ...           5 years ago
  • 2.0.0                                ...           5 years ago
  • 1.0.2                                ...           5 years ago
  • 1.0.1                                ...           5 years ago
  • 1.0.0                                ...           5 years ago
Today 0
This Week 0
This Month 35
Last Day 0
Last Week 34
Last Month 0
Dependencies (4)
Dev Dependencies (8)
Dependents (0)

Copyright 2014 - 2017 © |