Generate a CI build version


0.1.14 years ago5 years agoMinified + gzip package size for @janslow/ci-build-version in KB


CI Build Version

Generates an opinionated semantic version from a base version and the current CI context. Currently supports GitLab CI.

Version Logic

The generated versions have the following precendence (from highest to lowest) based on git ref:

  1. Tag which is a semantic version (release version).
  • It must match the base version (with no prerelease identifiers).
  1. release/hotfix branches (prerelease starts with rc).
  2. master/develop branches (prerelease starts with dev).
  3. Other branches and tags (prerelease starts with ci).

If used outside a CI environment, the prerelease is always local.



import { SemVer } from 'semver';
import generateBuildVersion, { load, loadSync, parse } from '@janslow/ci-build-version';

// Manually specify base version.
const buildVersion1: SemVer = generateBuildVersion(new SemVer('1.2.3-local'));

// Load base version from a file
const buildVersion2: Promise<SemVer> = load('package.json', 'UTF8');
const buildVersion3: SemVer = loadSync('package.json', 'UTF8');
const buildVersion4: SemVer = parse(require('package.json'));

Command Line

ci-build-version -b 1.2.3-local # Generate a version using the base version 1.2.3-local
ci-build-version -f package.json # Generate a version using the base version in `package.json`

Supported File Formats

Plain text

Must only contain the base version. E.g.,



Must either contain a JSON/YAML string which is the base version or an object with the key version (which is the base version). For example a package.json file. YAML files must only contain a single document. E.g.,

"0.1.2-local" # Base version
  "version": "0.1.2-local"
version: 0.1.2-local



export DEBUG='ci-build-version*'

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.