glsemver

Semantic versioning tool based on GitLab commit history and Conventional Commits.

Features

• 🚀 Calculate semantic versions from commit history
• 🔄 Follows Conventional Commits specification
• 🌿 Supports multi-branch workflows with prerelease versions
• 🌐 Pure API-based: all data fetched from GitLab API
• 🦊 Supports self-hosted GitLab instances
• 📦 Works perfectly with shallow clones in CI/CD
• 🎯 Zero configuration required

Installation

Global Installation

npm install -g @sharedutils/glsemver

Use with npx (Recommended)

npx @sharedutils/glsemver current
npx @sharedutils/glsemver next

Usage

Get Current Version

Get the latest semantic version tag from your repository:

glsemver current
# Output: 1.0.0

Calculate Next Version

Calculate the next version based on commit history:

glsemver next
# Output: 1.1.0

With Verbose Logging

Use --log flag to see detailed information:

glsemver next --log
# Output:
# Repository: mygroup/myproject
# Host: https://gitlab.com
# Current branch: main
# Main branch: main
# Base version: 1.0.0
# HEAD SHA: abc1234
# Tag SHA: def5678
# Analyzing 3 commit(s)
# Release type: minor
# 1.1.0

Command Options

current command

Get the current version (latest semantic version tag).

glsemver current [options]

Options:

• -r, --repo <repo> - Repository path (owner/repo or group/subgroup/repo)
• -H, --host <host> - GitLab host URL (default: from git remote or gitlab.com)
• -b, --branch <branch> - Current branch name
• -m, --main-branch <mainBranch> - Main branch name (default: from API)
• --sha <sha> - Current commit SHA
• --tag-prefix <tagPrefix> - Tag prefix before the semver (default: v)
• --log - Enable verbose logging

next command

Calculate the next version based on commits.

glsemver next [options]

Options:

• -r, --repo <repo> - Repository path (owner/repo or group/subgroup/repo)
• -H, --host <host> - GitLab host URL (default: from git remote or gitlab.com)
• -b, --branch <branch> - Current branch name
• -m, --main-branch <mainBranch> - Main branch name (default: from API)
• --sha <sha> - Current commit SHA
• --tag-prefix <tagPrefix> - Tag prefix before the semver (default: v)
• -p, --path <path> - Only count commits touching this path (monorepo package directory)
• --scope <scope> - Only count commits whose Conventional Commits scope matches
• -s, --suffix <suffix> - Prerelease suffix for non-main branches
• --log - Enable verbose logging

Data Source Strategy

This tool uses a pure API approach:

| Data | Source | |------|--------| | Repository info | CLI --repo > local git remote | | GitLab host | CLI --host > local git remote > GITLAB_HOST env > gitlab.com | | Current branch | CLI --branch > CI_COMMIT_BRANCH env > local git | | Current SHA | CLI --sha > CI_COMMIT_SHA env > local git > API | | Main branch | CLI --main-branch > GitLab API | | Tags & Commits | GitLab API (always) |

This approach is:

• 📦 Shallow clone friendly: Works perfectly with git clone --depth 1
• 🎯 Consistent: Always reflects the remote repository state
• 🔧 Flexible: Can run without a git repository if all options provided

Version Calculation Rules

This tool follows Conventional Commits specification:

Major Version (X.0.0)

Incremented when commits contain breaking changes:

• BREAKING CHANGE: or BREAKING-CHANGE: in commit message body
• ! after commit type: feat!:, fix!:

feat!: redesign authentication system

BREAKING CHANGE: removed old authentication API

Result: 1.0.0 → 2.0.0

Minor Version (0.X.0)

Incremented for new features:

• Commit type: feat or feature

feat: add user export functionality

Result: 1.0.0 → 1.1.0

Patch Version (0.0.X)

Incremented for bug fixes and performance improvements:

• Commit type: fix
• Commit type: perf

fix: resolve login page styling issue
perf: optimize database queries

Result: 1.0.0 → 1.0.1

Prerelease Versions

On non-main branches, versions include a prerelease identifier:

Format: {version}-{suffix}.{number}

# On develop branch
glsemver next
# Output: 1.1.0-develop.1

# On feature/awesome branch
glsemver next
# Output: 1.1.0-feature-awesome.1

# Custom suffix
glsemver next --suffix beta
# Output: 1.1.0-beta.1

Branch names are sanitized into valid semver prerelease identifiers: characters other than letters, digits and - are replaced with - (e.g. feature/awesome → feature-awesome).

No Version Bump

When commits don't match Conventional Commits patterns or only contain non-versioning types:

• chore:, docs:, style:, refactor:, test:, build:, ci:

glsemver next
# Output: (empty string)

Monorepo Support

In a monorepo, give each package its own tag series with --tag-prefix, and restrict commit analysis to the package directory with --path:

# Package in packages/pkg-a, tagged as pkg-a/v1.2.0, pkg-a/v1.3.0, ...
glsemver next --tag-prefix "pkg-a/v" --path packages/pkg-a
# Output: 1.3.0

• --tag-prefix <prefix> - the literal prefix before the semantic version. The recommended convention is <package>/v<version> (e.g. pkg-a/v1.2.0), but any prefix works: pkg-a@ matches [email protected], pkg-a-v matches pkg-a-v1.2.0.
• -p, --path <path> - only commits that modify files under this path count towards the version bump.
• --scope <scope> - optional, additionally require the Conventional Commits scope to match (e.g. feat(pkg-a): ...). Commits without a scope are ignored when --scope is set.

The output is always the bare version without the prefix — prepend the prefix yourself when creating the tag.

Monorepo CI Example

release-pkg-a:
  stage: release
  script:
    - VERSION=$(glsemver next --tag-prefix "pkg-a/v" --path packages/pkg-a)
    - |
      if [ -z "$VERSION" ]; then
        echo "No version bump needed for pkg-a"
        exit 0
      fi
    - git tag "pkg-a/v$VERSION"
    - git push origin "pkg-a/v$VERSION"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      changes:
        - packages/pkg-a/**/*

Errors and Exit Codes

• Exit 0 with a version on stdout: success
• Exit 0 with empty output: no version bump needed
• Exit 1 with a message on stderr: configuration or GitLab API error (invalid token, repository not found, network failure, ...)

API and configuration errors are never silently treated as "no version bump".

Environment Variables

GITLAB_TOKEN

Set GITLAB_TOKEN to authenticate with GitLab API:

export GITLAB_TOKEN=your_gitlab_token_here

Get a token at: https://gitlab.com/-/profile/personal_access_tokens

In GitLab CI/CD, CI_JOB_TOKEN is automatically available and will be used if GITLAB_TOKEN is not set.

GITLAB_HOST

For self-hosted GitLab instances, set the host URL:

export GITLAB_HOST=https://gitlab.example.com

In GitLab CI/CD, CI_SERVER_URL is automatically used if GITLAB_HOST is not set.

GitLab CI/CD Environment Variables

The tool automatically uses these CI variables when available:

• CI_COMMIT_BRANCH / CI_COMMIT_REF_NAME - Current branch
• CI_COMMIT_SHA - Current commit SHA
• CI_JOB_TOKEN - API authentication
• CI_SERVER_URL - GitLab instance URL

Examples

Basic Usage

# Get current version
glsemver current
# Output: 1.0.0

# Calculate next version
glsemver next
# Output: 1.1.0

Explicit Repository (No Git Required)

# Specify repository explicitly
glsemver next --repo mygroup/myproject --branch main --sha abc1234

# With self-hosted GitLab
glsemver next --repo mygroup/myproject --host https://gitlab.example.com --branch main

In GitLab CI/CD

# .gitlab-ci.yml
stages:
  - version
  - release

calculate-version:
  stage: version
  image: node:20
  script:
    - npm install -g @sharedutils/glsemver
    - VERSION=$(glsemver next --log)
    - |
      if [ -z "$VERSION" ]; then
        echo "No version bump needed"
        exit 0
      fi
    - echo "VERSION=$VERSION" >> version.env
  artifacts:
    reports:
      dotenv: version.env
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

create-release:
  stage: release
  image: node:20
  needs:
    - job: calculate-version
      artifacts: true
  script:
    - |
      if [ -z "$VERSION" ]; then
        echo "No version to release"
        exit 0
      fi
    - git config user.email "[email protected]"
    - git config user.name "GitLab CI"
    - git tag "v$VERSION"
    - git push origin "v$VERSION"
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

In Package Scripts

{
  "scripts": {
    "version:current": "glsemver current",
    "version:next": "glsemver next",
    "version:check": "glsemver next || echo 'No version bump needed'"
  }
}

Version Bump Script

#!/bin/bash
VERSION=$(glsemver next)

if [ -z "$VERSION" ]; then
  echo "No version bump required"
  exit 0
fi

echo "Bumping version to $VERSION"
npm version $VERSION --no-git-tag-version
git add package.json
git commit -m "chore: bump version to $VERSION"
git tag "v$VERSION"
git push --follow-tags

Tag Format

By default the tool recognizes tags starting with v followed by a valid semantic version:

• ✅ Valid: v1.0.0, v2.3.4, v10.20.30, v1.0.0-beta.1
• ❌ Invalid: 1.0.0, v1.0, release-v1.0.0

Use --tag-prefix to change the prefix (e.g. pkg-a/v for monorepos). Tags whose remainder after the prefix is not a valid semantic version are ignored.

Output versions do not include the prefix.

Requirements

• Node.js >= 18.0.0
• GitLab API access (token required for private repositories)
• Git (optional, only needed if not providing --repo option)

License

ISC

Contributing

Issues and merge requests are welcome!

Credits

Inspired by semantic-release but designed to be:

• Lighter weight
• Zero configuration
• Focused on version calculation only
• Pure API-based for better CI/CD compatibility