Azure DevOps

Installation and usage

For Azure DevOps Services or Azure DevOps Server you can install the GitTools Bundle.

Important

You must disable shallow fetch, either in the pipeline settings UI or by setting fetchDepth: 0 in your checkout step; without it, Azure DevOps Pipelines will perform a shallow clone, which will cause GitVersion to display an error message. See the Azure DevOps documentation for more information.

More information can be found at gittools/actions.

Pipeline variables

When the CLI runs with --output buildserver, or GitVersion.MsBuild writes build-server output, GitVersion v7 emits GitVersion_<Property> as both an ordinary variable and a named-step output variable (isOutput=true). For example:

Access from a later step Example
Ordinary pipeline variable $(GitVersion_SemVer)
Output from a step named version $(version.GitVersion_SemVer)
Expression variables['GitVersion_SemVer']
Bash environment variable $GITVERSION_SEMVER
PowerShell environment variable $env:GITVERSION_SEMVER

Azure uppercases variable names and converts periods to underscores when projecting them into the environment. Pipeline names and environment names are separate contracts. Logging commands make values available to subsequent steps; they do not update macros or environment variables in the running producer script. See Microsoft's variable reference and output-variable guide.

The GitTools gitversion-execute task has its own output contract: it reads JSON and emits names such as semVer and GitVersion_SemVer. Refer to the task documentation for supported GitVersion versions and task outputs; task support for v7 is separate from this CLI change.

Direct CLI across jobs and stages

The following example assumes GitVersion v7 is installed on the producer agent. The producer step must have a name; downstream jobs and stages must depend on the producer. Map outputs in the consumer job's variables block using the full quoted step.variable key.

stages:
- stage: Compile
  jobs:
  - job: Build
    steps:
    - checkout: self
      fetchDepth: 0
    - pwsh: dotnet-gitversion --output buildserver
      name: version
    - pwsh: |
        Write-Host "Ordinary: $(GitVersion_SemVer)"
        Write-Host "Step output: $(version.GitVersion_SemVer)"
  - job: Package
    dependsOn: Build
    variables:
      packageVersion: $[ dependencies.Build.outputs['version.GitVersion_SemVer'] ]
    steps:
    - pwsh: |
        Write-Host "Package version: $env:PACKAGE_VERSION"
      env:
        PACKAGE_VERSION: $(packageVersion)
- stage: Publish
  dependsOn: Compile
  jobs:
  - job: Release
    variables:
      releaseVersion: $[ stageDependencies.Compile.Build.outputs['version.GitVersion_SemVer'] ]
    steps:
    - pwsh: |
        Write-Host "Release version: $env:RELEASE_VERSION"
      env:
        RELEASE_VERSION: $(releaseVersion)

This example uses ordinary build jobs. Deployment and matrix jobs have additional output-key rules; see Microsoft's output-variable guide.

Upgrading from v6

Starting in v7, dotted pipeline names such as GitVersion.SemVer are no longer emitted. Update macros, conditions, dependency output keys, reusable templates, explicit environment mappings, and log parsers to GitVersion_SemVer. There are no dotted aliases. See the v6-to-v7 migration guide for examples.

The ordinary environment key remains GITVERSION_SEMVER. Remove conflicting user-defined variables: GitVersion.SemVer and GitVersion_SemVer project to the same environment key, and GitVersion now writes the underscore pipeline name. When a pipeline deliberately keeps both names with different values, explicitly map the intended pipeline variable to a distinct environment key for scripts.

GitVersion's build-number interpolation continues to accept both $(GitVersion.SemVer) and $(GitVersion_SemVer) placeholders. This input compatibility does not restore dotted pipeline outputs. Disabling output.update-build-number does not disable output-variable emission.