From 4ace268ae2489e21f44f9d3be871754799f5492f Mon Sep 17 00:00:00 2001 From: Chris Davis <74455480+chris-codeflow@users.noreply.github.com> Date: Sat, 21 Nov 2020 21:03:42 +0000 Subject: [PATCH] Add GitHub Actions usage examples. --- .../gitversion/execute/usage-examples.md | 277 ++++++++++++++++++ docs/examples/github/gitversion/index.md | 57 +--- .../github/gitversion/setup/usage-examples.md | 59 ++++ 3 files changed, 345 insertions(+), 48 deletions(-) create mode 100644 docs/examples/github/gitversion/execute/usage-examples.md create mode 100644 docs/examples/github/gitversion/setup/usage-examples.md diff --git a/docs/examples/github/gitversion/execute/usage-examples.md b/docs/examples/github/gitversion/execute/usage-examples.md new file mode 100644 index 000000000..cb352a4d2 --- /dev/null +++ b/docs/examples/github/gitversion/execute/usage-examples.md @@ -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..outputs. }}`, where `` 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_` 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 + ``` diff --git a/docs/examples/github/gitversion/index.md b/docs/examples/github/gitversion/index.md index c22a606d2..92db39cc8 100644 --- a/docs/examples/github/gitversion/index.md +++ b/docs/examples/github/gitversion/index.md @@ -1,50 +1,11 @@ -# GitVersion +# GitVersion Actions Usage Examples -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. +Use the following links to see usage examples of the Setup GitVersion (**gitversion/setup**) and Execute GitVersion (**gitversion/execute**) actions. -```yaml - steps: - - name: Checkout - uses: actions/checkout@v2 - with: - fetch-depth: 0 - - name: Install GitVersion - uses: gittools/actions/gitversion/setup@v0.9.6 - with: - versionSpec: '5.x' - - name: Use GitVersion - id: gitversion # step id used as reference for output values - uses: gittools/actions/gitversion/execute@v0.9.6 - - 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 "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 "CommitDate: ${{ steps.gitversion.outputs.commitDate }}" -``` +## Setup GitVersion (gitversion/setup) + +- [Usage examples](setup/usage-examples.md) + +## Execute GitVersion (gitversion/execute) + +- [Usage examples](execute/usage-examples.md) diff --git a/docs/examples/github/gitversion/setup/usage-examples.md b/docs/examples/github/gitversion/setup/usage-examples.md new file mode 100644 index 000000000..5451893b9 --- /dev/null +++ b/docs/examples/github/gitversion/setup/usage-examples.md @@ -0,0 +1,59 @@ +# Setup GitVersion Action (gitversion/setup) Usage Examples + +Find out how to use the **gitversion/setup** action using the examples below. + +> 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 Setup GitVersion action accepts the following inputs: + +```yaml +versionSpec: + description: Required version in the form of 5.x or exact version like 5.0.0. + required: true + default: '' +includePrerelease: + description: Include pre-release versions when matching a version. + required: false + default: false +``` + +--- + +## Usage examples + +- Example 1: Install the latest GitVersion 5 version. + + ```yaml + steps: + - name: Install GitVersion + uses: gittools/actions/gitversion/setup@v0.9.6 + with: + versionSpec: '5.x' + ``` + +--- + +- Example 2: Install GitVersion 5.5.0. + + ```yaml + steps: + - name: Install GitVersion + uses: gittools/actions/gitversion/setup@v0.9.6 + with: + versionSpec: '5.5.0' + ``` + +--- + +- Example 3: Install the latest GitVersion 6 pre-release version. For example **6.0.0-beta1.1**. + + ```yaml + steps: + - name: Install GitVersion + uses: gittools/actions/gitversion/setup@v0.9.6 + with: + versionSpec: '6.x' + includePrerelease: true + ```