386 lines
16 KiB
Markdown
386 lines
16 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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 (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 `${{ steps.<id>.outputs.<outputName> }}` or `${{ steps.<id>.outputs.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](#example-5).
|
|
|
|
The action also creates environment variables of the form `${{ env.<outputName> }}` or `${{ env.GitVersion_<OutputName> }}` for use by other steps in the same job. See example [6](#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](#example-7) and [8](#example-8).
|
|
|
|
---
|
|
|
|
## Examples
|
|
|
|
### Example 1
|
|
|
|
Calculate the version for the build.
|
|
|
|
```yaml
|
|
steps:
|
|
# gitversion/setup@v0 action omitted for brevity.
|
|
|
|
- name: Determine Version
|
|
uses: gittools/actions/gitversion/execute@v0
|
|
```
|
|
|
|
### Example 2
|
|
|
|
Calculate the version for the build using a config file with the default name **GitVersion.yml**.
|
|
|
|
```yaml
|
|
steps:
|
|
- name: Determine Version
|
|
uses: gittools/actions/gitversion/execute@v0
|
|
with:
|
|
useConfigFile: true
|
|
```
|
|
|
|
Example contents of **GitVersion.yml**:
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
steps:
|
|
# gitversion/setup@v0 action omitted for brevity.
|
|
|
|
- name: Determine Version
|
|
uses: gittools/actions/gitversion/execute@v0
|
|
with:
|
|
useConfigFile: true
|
|
configFilePath: VersionConfig.yml
|
|
```
|
|
|
|
### Example 4
|
|
|
|
Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument).
|
|
|
|
```yaml
|
|
steps:
|
|
# gitversion/setup@v0 action omitted for brevity.
|
|
|
|
- name: Display GitVersion config
|
|
uses: gittools/actions/gitversion/execute@v0
|
|
with:
|
|
useConfigFile: true
|
|
additionalArguments: '/showConfig'
|
|
```
|
|
|
|
### Example 5
|
|
|
|
Calculate the version for the build and display all the calculated variables in the next step.
|
|
|
|
```yaml
|
|
steps:
|
|
# gitversion/setup@v0 action omitted for brevity.
|
|
|
|
- name: Determine Version
|
|
id: gitversion # id to later be referenced
|
|
uses: gittools/actions/gitversion/execute@v0
|
|
|
|
- name: Display GitVersion outputs (step output)
|
|
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 }}"
|
|
|
|
- name: Display GitVersion outputs (step output with prefix)
|
|
run: |
|
|
echo "Major: ${{ steps.gitversion.outputs.GitVersion_Major }}"
|
|
echo "Minor: ${{ steps.gitversion.outputs.GitVersion_Minor }}"
|
|
echo "Patch: ${{ steps.gitversion.outputs.GitVersion_Patch }}"
|
|
echo "PreReleaseTag: ${{ steps.gitversion.outputs.GitVersion_PreReleaseTag }}"
|
|
echo "PreReleaseTagWithDash: ${{ steps.gitversion.outputs.GitVersion_PreReleaseTagWithDash }}"
|
|
echo "PreReleaseLabel: ${{ steps.gitversion.outputs.GitVersion_PreReleaseLabel }}"
|
|
echo "PreReleaseNumber: ${{ steps.gitversion.outputs.GitVersion_PreReleaseNumber }}"
|
|
echo "WeightedPreReleaseNumber: ${{ steps.gitversion.outputs.GitVersion_WeightedPreReleaseNumber }}"
|
|
echo "BuildMetaData: ${{ steps.gitversion.outputs.GitVersion_BuildMetaData }}"
|
|
echo "BuildMetaDataPadded: ${{ steps.gitversion.outputs.GitVersion_BuildMetaDataPadded }}"
|
|
echo "FullBuildMetaData: ${{ steps.gitversion.outputs.GitVersion_FullBuildMetaData }}"
|
|
echo "MajorMinorPatch: ${{ steps.gitversion.outputs.GitVersion_MajorMinorPatch }}"
|
|
echo "SemVer: ${{ steps.gitversion.outputs.GitVersion_SemVer }}"
|
|
echo "LegacySemVer: ${{ steps.gitversion.outputs.GitVersion_LegacySemVer }}"
|
|
echo "LegacySemVerPadded: ${{ steps.gitversion.outputs.GitVersion_LegacySemVerPadded }}"
|
|
echo "AssemblySemVer: ${{ steps.gitversion.outputs.GitVersion_AssemblySemVer }}"
|
|
echo "AssemblySemFileVer: ${{ steps.gitversion.outputs.GitVersion_AssemblySemFileVer }}"
|
|
echo "FullSemVer: ${{ steps.gitversion.outputs.GitVersion_FullSemVer }}"
|
|
echo "InformationalVersion: ${{ steps.gitversion.outputs.GitVersion_InformationalVersion }}"
|
|
echo "BranchName: ${{ steps.gitversion.outputs.GitVersion_BranchName }}"
|
|
echo "EscapedBranchName: ${{ steps.gitversion.outputs.GitVersion_EscapedBranchName }}"
|
|
echo "Sha: ${{ steps.gitversion.outputs.GitVersion_Sha }}"
|
|
echo "ShortSha: ${{ steps.gitversion.outputs.GitVersion_ShortSha }}"
|
|
echo "NuGetVersionV2: ${{ steps.gitversion.outputs.GitVersion_NuGetVersionV2 }}"
|
|
echo "NuGetVersion: ${{ steps.gitversion.outputs.GitVersion_NuGetVersion }}"
|
|
echo "NuGetPreReleaseTagV2: ${{ steps.gitversion.outputs.GitVersion_NuGetPreReleaseTagV2 }}"
|
|
echo "NuGetPreReleaseTag: ${{ steps.gitversion.outputs.GitVersion_NuGetPreReleaseTag }}"
|
|
echo "VersionSourceSha: ${{ steps.gitversion.outputs.GitVersion_VersionSourceSha }}"
|
|
echo "CommitsSinceVersionSource: ${{ steps.gitversion.outputs.GitVersion_CommitsSinceVersionSource }}"
|
|
echo "CommitsSinceVersionSourcePadded: ${{ steps.gitversion.outputs.GitVersion_CommitsSinceVersionSourcePadded }}"
|
|
echo "UncommittedChanges: ${{ steps.gitversion.outputs.GitVersion_UncommittedChanges }}"
|
|
echo "CommitDate: ${{ steps.gitversion.outputs.GitVersion_CommitDate }}"
|
|
```
|
|
|
|
### Example 6
|
|
|
|
Calculate the version for the build and display the value of the `env.GitVersion_SemVer` environment variable.
|
|
|
|
```yaml
|
|
steps:
|
|
# gitversion/setup@v0 action omitted for brevity.
|
|
|
|
- name: Determine Version
|
|
uses: gittools/actions/gitversion/execute@v0
|
|
|
|
|
|
- name: Display GitVersion variables (without prefix)
|
|
run: |
|
|
echo "Major: ${{ env.major }}"
|
|
echo "Minor: ${{ env.minor }}"
|
|
echo "Patch: ${{ env.patch }}"
|
|
echo "PreReleaseTag: ${{ env.preReleaseTag }}"
|
|
echo "PreReleaseTagWithDash: ${{ env.preReleaseTagWithDash }}"
|
|
echo "PreReleaseLabel: ${{ env.preReleaseLabel }}"
|
|
echo "PreReleaseNumber: ${{ env.preReleaseNumber }}"
|
|
echo "WeightedPreReleaseNumber: ${{ env.weightedPreReleaseNumber }}"
|
|
echo "BuildMetaData: ${{ env.buildMetaData }}"
|
|
echo "BuildMetaDataPadded: ${{ env.buildMetaDataPadded }}"
|
|
echo "FullBuildMetaData: ${{ env.fullBuildMetaData }}"
|
|
echo "MajorMinorPatch: ${{ env.majorMinorPatch }}"
|
|
echo "SemVer: ${{ env.semVer }}"
|
|
echo "LegacySemVer: ${{ env.legacySemVer }}"
|
|
echo "LegacySemVerPadded: ${{ env.legacySemVerPadded }}"
|
|
echo "AssemblySemVer: ${{ env.assemblySemVer }}"
|
|
echo "AssemblySemFileVer: ${{ env.assemblySemFileVer }}"
|
|
echo "FullSemVer: ${{ env.fullSemVer }}"
|
|
echo "InformationalVersion: ${{ env.informationalVersion }}"
|
|
echo "BranchName: ${{ env.branchName }}"
|
|
echo "EscapedBranchName: ${{ env.escapedBranchName }}"
|
|
echo "Sha: ${{ env.sha }}"
|
|
echo "ShortSha: ${{ env.shortSha }}"
|
|
echo "NuGetVersionV2: ${{ env.nuGetVersionV2 }}"
|
|
echo "NuGetVersion: ${{ env.nuGetVersion }}"
|
|
echo "NuGetPreReleaseTagV2: ${{ env.nuGetPreReleaseTagV2 }}"
|
|
echo "NuGetPreReleaseTag: ${{ env.nuGetPreReleaseTag }}"
|
|
echo "VersionSourceSha: ${{ env.versionSourceSha }}"
|
|
echo "CommitsSinceVersionSource: ${{ env.commitsSinceVersionSource }}"
|
|
echo "CommitsSinceVersionSourcePadded: ${{ env.commitsSinceVersionSourcePadded }}"
|
|
echo "UncommittedChanges: ${{ env.uncommittedChanges }}"
|
|
echo "CommitDate: ${{ env.commitDate }}"
|
|
|
|
- name: Display GitVersion variables (with prefix)
|
|
run: |
|
|
echo "Major: ${{ env.GitVersion_Major }}"
|
|
echo "Minor: ${{ env.GitVersion_Minor }}"
|
|
echo "Patch: ${{ env.GitVersion_Patch }}"
|
|
echo "PreReleaseTag: ${{ env.GitVersion_PreReleaseTag }}"
|
|
echo "PreReleaseTagWithDash: ${{ env.GitVersion_PreReleaseTagWithDash }}"
|
|
echo "PreReleaseLabel: ${{ env.GitVersion_PreReleaseLabel }}"
|
|
echo "PreReleaseNumber: ${{ env.GitVersion_PreReleaseNumber }}"
|
|
echo "WeightedPreReleaseNumber: ${{ env.GitVersion_WeightedPreReleaseNumber }}"
|
|
echo "BuildMetaData: ${{ env.GitVersion_BuildMetaData }}"
|
|
echo "BuildMetaDataPadded: ${{ env.GitVersion_BuildMetaDataPadded }}"
|
|
echo "FullBuildMetaData: ${{ env.GitVersion_FullBuildMetaData }}"
|
|
echo "MajorMinorPatch: ${{ env.GitVersion_MajorMinorPatch }}"
|
|
echo "SemVer: ${{ env.GitVersion_SemVer }}"
|
|
echo "LegacySemVer: ${{ env.GitVersion_LegacySemVer }}"
|
|
echo "LegacySemVerPadded: ${{ env.GitVersion_LegacySemVerPadded }}"
|
|
echo "AssemblySemVer: ${{ env.GitVersion_AssemblySemVer }}"
|
|
echo "AssemblySemFileVer: ${{ env.GitVersion_AssemblySemFileVer }}"
|
|
echo "FullSemVer: ${{ env.GitVersion_FullSemVer }}"
|
|
echo "InformationalVersion: ${{ env.GitVersion_InformationalVersion }}"
|
|
echo "BranchName: ${{ env.GitVersion_BranchName }}"
|
|
echo "EscapedBranchName: ${{ env.GitVersion_EscapedBranchName }}"
|
|
echo "Sha: ${{ env.GitVersion_Sha }}"
|
|
echo "ShortSha: ${{ env.GitVersion_ShortSha }}"
|
|
echo "NuGetVersionV2: ${{ env.GitVersion_NuGetVersionV2 }}"
|
|
echo "NuGetVersion: ${{ env.GitVersion_NuGetVersion }}"
|
|
echo "NuGetPreReleaseTagV2: ${{ env.GitVersion_NuGetPreReleaseTagV2 }}"
|
|
echo "NuGetPreReleaseTag: ${{ env.GitVersion_NuGetPreReleaseTag }}"
|
|
echo "VersionSourceSha: ${{ env.GitVersion_VersionSourceSha }}"
|
|
echo "CommitsSinceVersionSource: ${{ env.GitVersion_CommitsSinceVersionSource }}"
|
|
echo "CommitsSinceVersionSourcePadded: ${{ env.GitVersion_CommitsSinceVersionSourcePadded }}"
|
|
echo "UncommittedChanges: ${{ env.GitVersion_UncommittedChanges }}"
|
|
echo "CommitDate: ${{ env.GitVersion_CommitDate }}"
|
|
```
|
|
|
|
### Example 7
|
|
|
|
Calculate the version for the build and use the `branchName` output in a condition for starting another job.
|
|
|
|
```yaml
|
|
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/execute@v0
|
|
|
|
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.
|
|
|
|
```yaml
|
|
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/execute@v0
|
|
|
|
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
|
|
```
|