Skip to content

Latest commit

 

History

History
283 lines (230 loc) · 8.71 KB

usage-examples.md

File metadata and controls

283 lines (230 loc) · 8.71 KB

Execute GitVersion Action (gitversion/execute) Usage Examples

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

For the GitVersion workflow to execute successfully, you must checkout your Git repository with fetch-depth: 0 to fetch all history for all tags and branches, as follows:

steps:
  - name: Checkout
    uses: actions/checkout@v2
    with:
      fetch-depth: 0

This step is omitted from the examples for brevity.

The examples use version 0.9.7 of the GitVersion Execute action. It is recommended to use the latest released version in your own workflows.

Inputs

The Execute GitVersion action 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: 'GitVersion.yml'
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 action creates the following outputs:

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

The outputs can be accessed using the syntax ${{ steps.<id>.outputs.<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 GITVERSION_<OUTPUTNAME> for use by other steps in the same job. See example 6.

The outputs can be accessed across jobs by mapping them to job outputs and referencing the job outputs using the needs context in dependent jobs. See examples 7 and 8.

Examples

Example 1

Calculate the version for the build.

steps:
  # gitversion/[email protected] action omitted for brevity.

  - name: Determine Version
    uses: gittools/actions/gitversion/[email protected]

Example 2

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

steps:
  - name: Determine Version
    uses: gittools/actions/gitversion/[email protected]
    with:
      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/[email protected] action omitted for brevity.

  - name: Determine Version
    uses: gittools/actions/gitversion/[email protected]
    with:
      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/[email protected] action omitted for brevity.

  - name: Display GitVersion config
    uses: gittools/actions/gitversion/[email protected]
    with:
      useConfigFile: true
      additionalArguments: '/showConfig'

Example 5

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

steps:
  # gitversion/[email protected] action omitted for brevity.

  - name: Determine Version
    id:   gitversion
    uses: gittools/actions/gitversion/[email protected]

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

Example 6

Calculate the version for the build and display the value of the GITVERSION_SEMVER environment variable.

steps:
  # gitversion/[email protected] action omitted for brevity.

  - name: Determine Version
    uses: gittools/actions/gitversion/[email protected]

  - name: Display SemVer
    run: |
      echo "SemVer: $GITVERSION_SEMVER"

Example 7

Calculate the version for the build and use the branchName output in a condition for starting another job.

jobs:
  calculate-version:
    name: Calculate Version
    runs-on: ubuntu-latest
    outputs:
      branchName: ${{ steps.gitversion.outputs.branchName }} # To use an output in another job, you have to map it to a job output.
    steps:
      # gitversion/execute step omitted for brevity

      - name: Determine Version
        id: gitversion
        uses: gittools/actions/gitversion/[email protected]

  create-release-notes:
    name: Create Release Notes
    runs-on: ubuntu-latest
    needs: calculate-version
    if: contains(needs.calculate-version.outputs.branchName, 'main') # Output variable accessed via `needs` context.
    steps:
      - run: |
          # Output variables can also be accessed in steps, using an expression.
          echo "Creating release notes for ${{ needs.calculate-version.outputs.branchName }} branch."

Example 8

Calculate the version for the build and map the semVer output into an environment variable in another job.

jobs:
  calculate-version:
    name: Calculate Version
    runs-on: ubuntu-latest
    outputs:
      semVer: ${{ steps.gitversion.outputs.semVer }}
    steps:
      # gitversion/execute step omitted for brevity

      - name: Determine Version
        id: gitversion
        uses: gittools/actions/gitversion/[email protected]

  display-semver:
    name: Display Semantic Version
    runs-on: ubuntu-latest
    needs: calculate-version
    env:
      SEMVER: ${{ needs.calculate-version.outputs.semVer }}
    steps:
      - name: Display version
        run: |
          echo SemVer: $SEMVER