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).

2. release/hotfix branches (prerelease starts with rc).
3. master/develop branches (prerelease starts with dev).
4. Other branches and tags (prerelease starts with ci).

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

Usage

TypeScript

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.,

1.2.3-local

JSON/YAML

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

Development

Debugging

export DEBUG='ci-build-version*'