Semantic Versioning - Azure DevOps Pipeline Task

Calculate semantic version numbers from git history and commit messages. A lightweight, transparent alternative to GitVersion.

What this task does

Automatically determines the next semantic version for your build by:

1. Finding the most recent version tag in git history (e.g., v1.2.3)
2. Analyzing all commit messages since that tag for version bump indicators
3. Incrementally calculating the next version based on SemVer 2.0 rules
4. Generating pre-release versions for feature branches and PRs
5. Setting pipeline output variables with the calculated version

Commit message conventions

Use markers in your commit messages to control version bumps:

Commits without markers default to a patch bump (configurable).

Usage

Basic

steps:
  - checkout: self
    fetchDepth: 0  # Required: full history for accurate versioning

  - task: GetSemanticVersion@0
    name: version
    displayName: 'Calculate Version'

Access output variables in subsequent steps:

  - script: echo "Version is $(version.SemVer)"

With build number update

steps:
  - task: GetSemanticVersion@0
    name: version
    displayName: 'Calculate Version'
    inputs:
      updateBuildNumber: true
      buildNumberPrefix: 'prd'

This updates the pipeline build number to prd-1.2.3.

Pre-release versions

Feature branches and PR builds automatically get pre-release labels:

# On branch 'feature/my-feature', produces: 1.2.3-my-feature.5
steps:
  - task: GetSemanticVersion@0
    name: version

Or set an explicit label:

# Produces: 1.2.3-beta.5
steps:
  - task: GetSemanticVersion@0
    name: version
    inputs:
      preReleaseLabel: 'beta'

All options

steps:
  - task: GetSemanticVersion@0
    name: version
    inputs:
      updateBuildNumber: false       # Update pipeline build number (default: false)
      buildNumberPrefix: ''          # Prefix for build number (default: none)
      defaultBumpType: 'patch'       # Bump for unmarked commits: 'patch' or 'none'
      tagPattern: 'v*.*.*'           # Pattern for version tags (default: v*.*.*)
      preReleaseLabel: ''            # Pre-release label: empty=auto, 'none'=disable, or explicit value

Output variables

All variables are available as task output variables (reference via taskName.VariableName):

How version calculation works

1. Find last tag: Searches for the most recent tag matching v*.*.* (or *.*.*) merged into HEAD
2. Parse base version: Extracts major.minor.patch from the tag (defaults to 0.0.0 if no tag found)
3. Replay commits: Iterates through all commits since the tag in chronological order
4. Apply bumps: Each commit's marker determines how the version is incremented:
   • [major]: major++, minor=0, patch=0
   • [minor]: minor++, patch=0
   • [patch] or unmarked: patch++
   • [skip]: no change
5. Pre-release: If on a feature branch or PR, appends pre-release label and commit count
6. Output: The final version is set as pipeline output variables

Example

Starting from tag v1.0.0 with these commits on branch feature/search:

fix: correct validation     → 1.0.1
feature: add search         → 1.1.0
[skip] update docs          → 1.1.0
fix: search edge case       → 1.1.1

Result: 1.1.1-search.4 (with pre-release label from branch)

Important notes

• Shallow clones: The task detects shallow clones and emits a warning. Use fetchDepth: 0 for accurate results.
• Detached HEAD: Handled gracefully using Azure DevOps BUILD_SOURCEBRANCHNAME variable.
• No git: If git is not available, the task fails with a clear error message.

Requirements

• Git must be available on the agent
• The repository must be checked out with sufficient history (use fetchDepth: 0)

Support

• Publisher: sadiablo
• Repository: SemanticVersioningExtension