Add GitHub Actions usage examples.
This commit is contained in:
Chris Davis
Artur
277
docs/examples/github/gitversion/execute/usage-examples.md
Normal file
277
docs/examples/github/gitversion/execute/usage-examples.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
> The examples use version _0.9.6_ 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 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 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.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
# gitversion/setup@v0.9.6 action ommitted for brevity.
|
||||
|
||||
- name: Determine Version
|
||||
uses: gittools/actions/gitversion/execute@v0.9.6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
- 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.9.6
|
||||
with:
|
||||
useConfigFile: true
|
||||
```
|
||||
|
||||
Example contents of **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.9.6 action ommitted for brevity.
|
||||
|
||||
- name: Determine Version
|
||||
uses: gittools/actions/gitversion/execute@v0.9.6
|
||||
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.9.6 action ommitted for brevity.
|
||||
|
||||
- name: Display GitVersion config
|
||||
uses: gittools/actions/gitversion/execute@v0.9.6
|
||||
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.9.6 action ommitted for brevity.
|
||||
|
||||
- name: Determine Version
|
||||
id: gitversion
|
||||
uses: gittools/actions/gitversion/execute@v0.9.6
|
||||
|
||||
- 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.
|
||||
|
||||
```yaml
|
||||
steps:
|
||||
# gitversion/setup@v0.9.6 action ommitted for brevity.
|
||||
|
||||
- name: Determine Version
|
||||
uses: gittools/actions/gitversion/execute@v0.9.6
|
||||
|
||||
- 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.
|
||||
|
||||
````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 ommitted for brevity
|
||||
|
||||
- name: Determine Version
|
||||
id: gitversion
|
||||
uses: gittools/actions/gitversion/execute@v0.9.6
|
||||
|
||||
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 ommitted for brevity
|
||||
|
||||
- name: Determine Version
|
||||
id: gitversion
|
||||
uses: gittools/actions/gitversion/execute@v0.9.6
|
||||
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user