actions/docs/examples/azure/gitversion/execute/usage-examples.md

Execute GitVersion Task (gitversion/execute) Usage Examples

Find out how to use the gitversion/execute task using the examples below.

The examples use the latest 0.x version of the GitVersion Execute task. It is recommended to use the latest released version in your own pipelines.

Note that if the pipeline is setup to use a shallow git fetch mode the GitVersion Execute task will fail. It is required to use fetchDepth of 0 like so:

- checkout: self
  fetchDepth: 0

Inputs

The Execute GitVersion task accepts the following inputs:

targetPath:
  description: Optionally supply the path to the working directory.
  required: false
  default: ''
useConfigFile:
  description: Whether to use a custom configuration file.
  required: false
  default: false
configFilePath:
  description: Optional path to config file (defaults to GitVersion.yml).
  required: false
  default: ''
updateAssemblyInfo:
  description: Whether to update versions in the AssemblyInfo files.
  required: false
  default: false
updateAssemblyInfoFilename:
  description: Update versions in specified file.
  required: false
  default: ''
additionalArguments:
  description: Additional arguments to send to GitVersion.
  required: false
  default: ''

Outputs

The Execute GitVersion task creates the following job-scoped variables and multi-job output variables:

• major
• minor
• patch
• preReleaseTag
• preReleaseTagWithDash
• preReleaseLabel
• preReleaseNumber
• weightedPreReleaseNumber
• buildMetaData
• buildMetaDataPadded (removed in 6.0.0)
• fullBuildMetaData
• majorMinorPatch
• semVer
• legacySemVer (removed in 6.0.0)
• legacySemVerPadded (removed in 6.0.0)
• assemblySemVer
• assemblySemFileVer
• fullSemVer
• informationalVersion
• branchName
• escapedBranchName (since 5.2.0)
• sha
• shortSha
• nuGetVersionV2 (removed in 6.0.0)
• nuGetVersion (removed in 6.0.0)
• nuGetPreReleaseTagV2 (removed in 6.0.0)
• nuGetPreReleaseTag (removed in 6.0.0)
• versionSourceSha
• commitsSinceVersionSource
• commitsSinceVersionSourcePadded (since 5.2.0, removed in 6.0.0)
• uncommittedChanges (since 5.5.0)
• commitDate

The outputs can be accessed using the syntax $(<id>.<outputName>) or $(<id>.GitVersion_<OutputName>), where <id> is the ID assigned to the step that calls the action, by subsequent steps later in the same job. See example 5.

The action also creates environment variables of the form $(<outputName>) or $(GitVersion_<OutputName>) for use by other steps in the same job. See example 6.

The multi-job output variables can be accessed across jobs and stages, in both conditions and variables. See examples 7 to 10.

GitVersion also automatically updates the pre-defined Build variable Build.BuildNumber.

---

Examples

Example 1

Calculate the version for the build.

steps:
  # gitversion/setup@0 task omitted for brevity.

  - task: gitversion/execute@0
    displayName: Determine Version

Example 2

Calculate the version for the build using a config file with the default name GitVersion.yml.

steps:
  # gitversion/setup@0 task omitted for brevity.

  - task: gitversion/execute@0
    displayName: Determine Version
    inputs:
      useConfigFile: true

Example contents of GitVersion.yml:

mode: Mainline
branches:
  master:
    regex: ^latest$
  pull-request:
    tag: pr

Example 3

Calculate the version for the build using a config file named VersionConfig.yml in the root of the working folder.

steps:
  # gitversion/setup@0 task omitted for brevity.

  - task: gitversion/execute@0
    displayName: Determine Version
    inputs:
      useConfigFile: true
      configFilePath: 'VersionConfig.yml'

Example 4

Show the effective configuration for GitVersion by running the /showConfig command (passed as an additional argument).

steps:
  # gitversion/setup@0 task omitted for brevity.

  - task: gitversion/execute@0
    displayName: Display GitVersion config
    inputs:
      additionalArguments: '/showConfig'

Example 5

Calculate the version for the build and display all the calculated variables in the next step.

steps:
  # gitversion/setup@0 task omitted for brevity.

  - task: gitversion/execute@0
    name: version # id to later be referenced
    displayName: Determine Version

  - displayName: Display GitVersion outputs (step output)
    script: |
      echo "Major: $(version.major)"
      echo "Minor: $(version.minor)"
      echo "Patch: $(version.patch)"
      echo "PreReleaseTag: $(version.preReleaseTag)"
      echo "PreReleaseTagWithDash: $(version.preReleaseTagWithDash)"
      echo "PreReleaseLabel: $(version.preReleaseLabel)"
      echo "PreReleaseNumber: $(version.preReleaseNumber)"
      echo "WeightedPreReleaseNumber: $(version.weightedPreReleaseNumber)"
      echo "BuildMetaData: $(version.buildMetaData)"
      echo "BuildMetaDataPadded: $(version.buildMetaDataPadded)"
      echo "FullBuildMetaData: $(version.fullBuildMetaData)"
      echo "MajorMinorPatch: $(version.majorMinorPatch)"
      echo "SemVer: $(version.semVer)"
      echo "LegacySemVer: $(version.legacySemVer)"
      echo "LegacySemVerPadded: $(version.legacySemVerPadded)"
      echo "AssemblySemVer: $(version.assemblySemVer)"
      echo "AssemblySemFileVer: $(version.assemblySemFileVer)"
      echo "FullSemVer: $(version.fullSemVer)"
      echo "InformationalVersion: $(version.informationalVersion)"
      echo "BranchName: $(version.branchName)"
      echo "EscapedBranchName: $(version.escapedBranchName)"
      echo "Sha: $(version.sha)"
      echo "ShortSha: $(version.shortSha)"
      echo "NuGetVersionV2: $(version.nuGetVersionV2)"
      echo "NuGetVersion: $(version.nuGetVersion)"
      echo "NuGetPreReleaseTagV2: $(version.nuGetPreReleaseTagV2)"
      echo "NuGetPreReleaseTag: $(version.nuGetPreReleaseTag)"
      echo "VersionSourceSha: $(version.versionSourceSha)"
      echo "CommitsSinceVersionSource: $(version.commitsSinceVersionSource)"
      echo "CommitsSinceVersionSourcePadded: $(version.commitsSinceVersionSourcePadded)"
      echo "UncommittedChanges: $(version.uncommittedChanges)"
      echo "CommitDate: $(version.commitDate)"

  - displayName: Display GitVersion outputs (step output with prefix)
    script: |
      echo "Major: $(version.GitVersion_Major)"
      echo "Minor: $(version.GitVersion_Minor)"
      echo "Patch: $(version.GitVersion_Patch)"
      echo "PreReleaseTag: $(version.GitVersion_PreReleaseTag)"
      echo "PreReleaseTagWithDash: $(version.GitVersion_PreReleaseTagWithDash)"
      echo "PreReleaseLabel: $(version.GitVersion_PreReleaseLabel)"
      echo "PreReleaseNumber: $(version.GitVersion_PreReleaseNumber)"
      echo "WeightedPreReleaseNumber: $(version.GitVersion_WeightedPreReleaseNumber)"
      echo "BuildMetaData: $(version.GitVersion_BuildMetaData)"
      echo "BuildMetaDataPadded: $(version.GitVersion_BuildMetaDataPadded)"
      echo "FullBuildMetaData: $(version.GitVersion_FullBuildMetaData)"
      echo "MajorMinorPatch: $(version.GitVersion_MajorMinorPatch)"
      echo "SemVer: $(version.GitVersion_SemVer)"
      echo "LegacySemVer: $(version.GitVersion_LegacySemVer)"
      echo "LegacySemVerPadded: $(version.GitVersion_LegacySemVerPadded)"
      echo "AssemblySemVer: $(version.GitVersion_AssemblySemVer)"
      echo "AssemblySemFileVer: $(version.GitVersion_AssemblySemFileVer)"
      echo "FullSemVer: $(version.GitVersion_FullSemVer)"
      echo "InformationalVersion: $(version.GitVersion_InformationalVersion)"
      echo "BranchName: $(version.GitVersion_BranchName)"
      echo "EscapedBranchName: $(version.GitVersion_EscapedBranchName)"
      echo "Sha: $(version.GitVersion_Sha)"
      echo "ShortSha: $(version.GitVersion_ShortSha)"
      echo "NuGetVersionV2: $(version.GitVersion_NuGetVersionV2)"
      echo "NuGetVersion: $(version.GitVersion_NuGetVersion)"
      echo "NuGetPreReleaseTagV2: $(version.GitVersion_NuGetPreReleaseTagV2)"
      echo "NuGetPreReleaseTag: $(version.GitVersion_NuGetPreReleaseTag)"
      echo "VersionSourceSha: $(version.GitVersion_VersionSourceSha)"
      echo "CommitsSinceVersionSource: $(version.GitVersion_CommitsSinceVersionSource)"
      echo "CommitsSinceVersionSourcePadded: $(version.GitVersion_CommitsSinceVersionSourcePadded)"
      echo "UncommittedChanges: $(version.GitVersion_UncommittedChanges)"
      echo "CommitDate: $(version.GitVersion_CommitDate)"

Example 6

Calculate the version for the build and use the GitVersion.NuGetVersion variable to set the NuGet package version.

steps:
  # gitversion/setup@0 task omitted for brevity.

  - task: gitversion/execute@0
    displayName: Determine Version

  - displayName: Display GitVersion variables (without prefix)
    script: |
      echo "Major: $(major)"
      echo "Minor: $(minor)"
      echo "Patch: $(patch)"
      echo "PreReleaseTag: $(preReleaseTag)"
      echo "PreReleaseTagWithDash: $(preReleaseTagWithDash)"
      echo "PreReleaseLabel: $(preReleaseLabel)"
      echo "PreReleaseNumber: $(preReleaseNumber)"
      echo "WeightedPreReleaseNumber: $(weightedPreReleaseNumber)"
      echo "BuildMetaData: $(buildMetaData)"
      echo "BuildMetaDataPadded: $(buildMetaDataPadded)"
      echo "FullBuildMetaData: $(fullBuildMetaData)"
      echo "MajorMinorPatch: $(majorMinorPatch)"
      echo "SemVer: $(semVer)"
      echo "LegacySemVer: $(legacySemVer)"
      echo "LegacySemVerPadded: $(legacySemVerPadded)"
      echo "AssemblySemVer: $(assemblySemVer)"
      echo "AssemblySemFileVer: $(assemblySemFileVer)"
      echo "FullSemVer: $(fullSemVer)"
      echo "InformationalVersion: $(informationalVersion)"
      echo "BranchName: $(branchName)"
      echo "EscapedBranchName: $(escapedBranchName)"
      echo "Sha: $(sha)"
      echo "ShortSha: $(shortSha)"
      echo "NuGetVersionV2: $(nuGetVersionV2)"
      echo "NuGetVersion: $(nuGetVersion)"
      echo "NuGetPreReleaseTagV2: $(nuGetPreReleaseTagV2)"
      echo "NuGetPreReleaseTag: $(nuGetPreReleaseTag)"
      echo "VersionSourceSha: $(versionSourceSha)"
      echo "CommitsSinceVersionSource: $(commitsSinceVersionSource)"
      echo "CommitsSinceVersionSourcePadded: $(commitsSinceVersionSourcePadded)"
      echo "UncommittedChanges: $(uncommittedChanges)"
      echo "CommitDate: $(commitDate)"

  - displayName: Display GitVersion variables (with prefix)
    script: |
      echo "Major: $(GitVersion_Major)"
      echo "Minor: $(GitVersion_Minor)"
      echo "Patch: $(GitVersion_Patch)"
      echo "PreReleaseTag: $(GitVersion_PreReleaseTag)"
      echo "PreReleaseTagWithDash: $(GitVersion_PreReleaseTagWithDash)"
      echo "PreReleaseLabel: $(GitVersion_PreReleaseLabel)"
      echo "PreReleaseNumber: $(GitVersion_PreReleaseNumber)"
      echo "WeightedPreReleaseNumber: $(GitVersion_WeightedPreReleaseNumber)"
      echo "BuildMetaData: $(GitVersion_BuildMetaData)"
      echo "BuildMetaDataPadded: $(GitVersion_BuildMetaDataPadded)"
      echo "FullBuildMetaData: $(GitVersion_FullBuildMetaData)"
      echo "MajorMinorPatch: $(GitVersion_MajorMinorPatch)"
      echo "SemVer: $(GitVersion_SemVer)"
      echo "LegacySemVer: $(GitVersion_LegacySemVer)"
      echo "LegacySemVerPadded: $(GitVersion_LegacySemVerPadded)"
      echo "AssemblySemVer: $(GitVersion_AssemblySemVer)"
      echo "AssemblySemFileVer: $(GitVersion_AssemblySemFileVer)"
      echo "FullSemVer: $(GitVersion_FullSemVer)"
      echo "InformationalVersion: $(GitVersion_InformationalVersion)"
      echo "BranchName: $(GitVersion_BranchName)"
      echo "EscapedBranchName: $(GitVersion_EscapedBranchName)"
      echo "Sha: $(GitVersion_Sha)"
      echo "ShortSha: $(GitVersion_ShortSha)"
      echo "NuGetVersionV2: $(GitVersion_NuGetVersionV2)"
      echo "NuGetVersion: $(GitVersion_NuGetVersion)"
      echo "NuGetPreReleaseTagV2: $(GitVersion_NuGetPreReleaseTagV2)"
      echo "NuGetPreReleaseTag: $(GitVersion_NuGetPreReleaseTag)"
      echo "VersionSourceSha: $(GitVersion_VersionSourceSha)"
      echo "CommitsSinceVersionSource: $(GitVersion_CommitsSinceVersionSource)"
      echo "CommitsSinceVersionSourcePadded: $(GitVersion_CommitsSinceVersionSourcePadded)"
      echo "UncommittedChanges: $(GitVersion_UncommittedChanges)"
      echo "CommitDate: $(GitVersion_CommitDate)"

  - task: DotNetCoreCLI@2
    displayName: Pack Example
    inputs:
      command: pack
      packagesToPack: src/Example/LibExample.csproj
      versioningScheme: byEnvVar
      versionEnvVar: GitVersion_SemVer # alternative syntax GITVERSION_SEMVER (the former gets converted into the latter internally)

Example 7

Calculate the version for the build and use the GitVersion_BranchName variable in a condition for starting another job.

jobs:
  - job: CalculateVersion
    displayName: Calculate version using GitVersion
    steps:
      # gitversion/setup@0 task omitted for brevity.

      - task: gitversion/execute@0
        displayName: Use GitVersion
        name: Version # the step MUST be named to access its output variables in another job.

  - job: CreateReleaseNotes
    condition: and(succeeded(), eq(dependencies.CalculateVersion.outputs['Version.GitVersion_BranchName'], 'main'))
    dependsOn: CalculateVersion

Example 8

Calculate the version for the build and map the GitVersion_SemVer variable into a variable in another job.

jobs:
  - job: CalculateVersion
    displayName: Calculate version using GitVersion
    steps:
      # gitversion/setup@0 task omitted for brevity.

      - task: gitversion/execute@0
        displayName: Use GitVersion
        name: Version # the step MUST be named to access its output variables in another job.

  - job: BuildAndPack
    variables:
      Ver.MajorMinorPatch: $[ dependencies.CalculateVersion.outputs['Version.GitVersion_MajorMinorPatch'] ]

Example 9

Calculate the version for the build and use the GitVersion.Major output variable in a condition for starting another stage.

stages:
  - stage: S1
    jobs:
      - job: CalculateVersion
        displayName: Calculate version number using GitVersion
        steps:
          # gitversion/setup@0 task omitted for brevity.

          - task: gitversion/execute@0
            displayName: Use GitVersion
            name: Version # the step MUST be named to access its output variables in another stage.

  - stage: S2
    condition: and(succeeded(), gt(dependencies.S1.outputs['CalculateVersion.Version.GitVersion_Major'], 0))
    dependsOn: S1

Example 10

Calculate the version for the build and map the GitVersion.AssemblySemVer variable into a variable in another job for a different stage.

stages:
  - stage: S1
    jobs:
      - job: CalculateVersion
        displayName: Calculate version number using GitVersion
        steps:
          # gitversion/setup@0 task omitted for brevity.

          - task: gitversion/execute@0
            displayName: Use GitVersion
            name: Version # the step MUST be named to access its output variables in another stage.
  - stage: S2
    dependsOn: S1
    jobs:
      - job: UpdateAssemblyVersions
        variables:
          Ver.AssemblyVer: $[ stageDependencies.S1.CalculateVersion.outputs['Version.GitVersion_AssemblySemVer'] ] # Note the 'stageDependencies.<jobName>' syntax.