Skip to main content

Check SemVer

The check job validates that release or hotfix branches follow semantic versioning (SemVer) conventions.

Overview​

This job:

  • Extracts version number from branch name
  • Validates the version against SemVer 2.0.0 specification
  • Fails the pipeline if the version format is invalid
  • Ensures consistent versioning for release and hotfix branches

Variables​

This job does not require any custom variables. It uses GitLab CI/CD predefined variables:

VariableDescription
CI_COMMIT_BRANCHThe branch name for which the pipeline is running

Usage​

Basic Usage​

check:
  script:
    - VERSION=$(echo ${CI_COMMIT_BRANCH} | awk -F "/" '{print $2}') 
    - echo "checking release version $VERSION"
    - SEMVER_REGEX="^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(\\-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$" && if [[ "$VERSION" =~ $SEMVER_REGEX ]]; then echo "ok release version"; else exit 1; fi

Job Details​

Script​

The job performs the following steps:

  1. Extract version from branch name:

    VERSION=$(echo ${CI_COMMIT_BRANCH} | awk -F "/" '{print $2}')
    • Extracts the version from branch name by splitting on / and taking the second part
    • Example: release/1.0.0 → 1.0.0
    • Example: hotfix/2.1.3 → 2.1.3

  2. Display version being checked:

    echo "checking release version $VERSION"

  3. Validate SemVer format:

    SEMVER_REGEX="^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(\\-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$"
    if [[ "$VERSION" =~ $SEMVER_REGEX ]]; then 
      echo "ok release version"
    else 
      exit 1
    fi
    • Uses a regex pattern to validate SemVer 2.0.0 format
    • Exits with code 1 if validation fails

SemVer Format​

The job validates against Semantic Versioning 2.0.0 specification:

Format: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Components​

  • MAJOR: Non-negative integer, no leading zeros (except 0)
  • MINOR: Non-negative integer, no leading zeros (except 0)
  • PATCH: Non-negative integer, no leading zeros (except 0)
  • PRERELEASE (optional): Hyphen followed by alphanumeric identifiers separated by dots
  • BUILD (optional): Plus sign followed by alphanumeric identifiers separated by dots

Valid Examples​

  • 1.0.0 - Standard release
  • 2.1.3 - Patch release
  • 0.0.1 - Initial development version
  • 1.0.0-alpha - Pre-release with alpha tag
  • 1.0.0-beta.1 - Pre-release with beta and build number
  • 1.0.0+20130313144700 - Build metadata
  • 1.0.0-alpha+001 - Pre-release with build metadata

Invalid Examples​

  • 1.0 - Missing patch version
  • 01.0.0 - Leading zero in major version
  • 1.0.0.1 - Too many components
  • v1.0.0 - Version prefix not allowed
  • 1.0.0_alpha - Invalid separator (should use hyphen)

Branch Naming Convention​

The job expects branches following this pattern:

{prefix}/{version}

Examples:

  • release/1.0.0 ✅
  • release/0.0.1 ✅
  • hotfix/2.1.3 ✅
  • release/1.0.0-alpha ✅
  • release/1.0 ❌ (missing patch version)
  • release/v1.0.0 ❌ (version prefix not allowed)

Configuration Examples​

Basic Check Job​

stages:
  - validate

check-semver:
  stage: validate
  script:
    - VERSION=$(echo ${CI_COMMIT_BRANCH} | awk -F "/" '{print $2}') 
    - echo "checking release version $VERSION"
    - SEMVER_REGEX="^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(\\-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$" && if [[ "$VERSION" =~ $SEMVER_REGEX ]]; then echo "ok release version"; else exit 1; fi
  only:
    - /^release\/.*$/
    - /^hotfix\/.*$/

With Custom Error Message​

check-semver:
  stage: validate
  script:
    - VERSION=$(echo ${CI_COMMIT_BRANCH} | awk -F "/" '{print $2}') 
    - echo "checking release version $VERSION"
    - |
      SEMVER_REGEX="^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(\\-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$"
      if [[ "$VERSION" =~ $SEMVER_REGEX ]]; then
        echo "✅ Valid SemVer version: $VERSION"
      else
        echo "❌ Invalid SemVer version: $VERSION"
        echo "Expected format: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]"
        echo "Example: 1.0.0, 2.1.3, 1.0.0-alpha"
        exit 1
      fi
  only:
    - /^release\/.*$/
    - /^hotfix\/.*$/

Early Validation in Pipeline​

stages:
  - validate
  - build
  - deploy

check-semver:
  stage: validate
  script:
    - VERSION=$(echo ${CI_COMMIT_BRANCH} | awk -F "/" '{print $2}') 
    - echo "checking release version $VERSION"
    - SEMVER_REGEX="^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(\\-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$" && if [[ "$VERSION" =~ $SEMVER_REGEX ]]; then echo "ok release version"; else exit 1; fi
  only:
    - /^release\/.*$/
    - /^hotfix\/.*$/

build:
  stage: build
  needs:
    - check-semver
  script:
    - echo "Building version $VERSION"
    # ... build commands

Regex Pattern Breakdown​

The SemVer regex pattern validates:

^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)
(\\-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?
(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$
  • ^(0|[1-9][0-9]*)\\. - Major version (0 or non-zero leading)
  • (0|[1-9][0-9]*)\\. - Minor version (0 or non-zero leading)
  • (0|[1-9][0-9]*) - Patch version (0 or non-zero leading)
  • (\\-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)? - Optional pre-release identifier
  • (\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)? - Optional build metadata
  • $ - End of string

Prerequisites​

  • Branch Format: Branch must follow {prefix}/{version} format
  • Bash Support: Requires bash shell (default in GitLab CI)
  • GitLab CI/CD: Must run in a GitLab CI/CD pipeline context

Use Cases​

Release Branch Validation​

Ensure all release branches follow SemVer:

check-semver:
  only:
    - /^release\/.*$/

Hotfix Branch Validation​

Ensure all hotfix branches follow SemVer:

check-semver:
  only:
    - /^hotfix\/.*$/

Combined Validation​

Validate both release and hotfix branches:

check-semver:
  only:
    - /^release\/.*$/
    - /^hotfix\/.*$/

Integration with Other Jobs​

This job is typically used early in the pipeline to validate branch naming before other jobs run:

stages:
  - validate
  - build
  - release

check-semver:
  stage: validate
  script:
    - VERSION=$(echo ${CI_COMMIT_BRANCH} | awk -F "/" '{print $2}') 
    - echo "checking release version $VERSION"
    - SEMVER_REGEX="^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(\\-[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$" && if [[ "$VERSION" =~ $SEMVER_REGEX ]]; then echo "ok release version"; else exit 1; fi

build:
  stage: build
  needs:
    - check-semver
  script:
    - echo "Building version $VERSION"
    # ... build commands

release:
  stage: release
  needs:
    - check-semver
    - build
  script:
    - echo "Releasing version $VERSION"
    # ... release commands

Notes​

  • The job fails fast if the version format is invalid, preventing downstream jobs from running with incorrect versions
  • The regex pattern strictly follows SemVer 2.0.0 specification
  • Leading zeros are not allowed (except for 0 itself) to prevent ambiguity
  • The job extracts version by splitting on /, so branch names must follow the {prefix}/{version} format
  • This validation is particularly useful for automated release processes that depend on consistent versioning
  • The job can be extended to export the validated version as a variable for use in subsequent jobs