This is a GitHub Action to make it easy to pull versions from XML files. This can be used in your workflows for other uses such as version validation, version tag management, and more!!

This GitHub action is built using C#/NET and runs in a docker container. This means that the action can only be run on Linux. Running in Windows is not supported. If you need to use steps on Windows AND Ubuntu, then you can split up your workflow so that this action is in an isolated job that runs on Ubuntu, while the rest of the workflow can be executed in Windows.

• Create tags automatically with the version, during the release process.
• Validate the version syntax to help enforce version syntax.
  • Example: Semantic version vs. a date-based version.
• Manage release note file names by having the version embedded in the file name.
• Use the version in the title of a GitHub release.
• Release announcements.
  • Example: Use the version in a release announcement on Twitter.
• Use status check workflows to verify versions before a pull request can be completed.
• Whatever your imagination comes up with!!

In a nutshell, this pulls versions out of XML data files for use in workflows. Just tell the action which repo, branch, and file contains the version, and it will search through the file for the version-keys and pull out the value of that key. This value is used as the value of the action's output, which has the name version, so you can use it in the rest of your workflow.

The version-keys input is just a comma delimited list of XML keys to search for in the XML file.
Example:
If the value of the version-keys input was "Version,FileVersion", then it would search the XML for any XML elements that match the name "Version" or "FileVersion". The first element that has a value will be the value returned. So if the XML element "Version" had a value of 1.2.3, then it would simply return the value of the "Version" element and stop looking for values in any other XML elements.

name: Get Version Example

jobs:
  Get_Version_Job:
    runs-on: ubuntu-latest # Cannot use windows
    steps:
    - uses: actions/checkout@v2

    - name: Get Version From C# Project File
      id: get-version
      uses: KinsonDigital/[email protected]
      with:
      repo-owner: JohnDoe
      repo-name: MyRepo
      branch-name: master
      file-type: xml
      file-path: MyProject/MyProject.csproj
      version-keys: Version

    - name: Print Version From File
      id: print-output
      run: echo "${{ steps.get-version.outputs.version }}"

So if the C# project file had the contents below, the workflow above would print the value 1.2.3 to the GitHub console.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <LangVersion>10.0</LangVersion>
    <Version>1.2.3</Version>
    <FileVersion>0.1.0</FileVersion>
</Project>

Requirements:

• Search for a version but do not fail the workflow if no version is found

⚠️The action input fail-when-version-not-found is not required and has a default value of true. If you do not want the action to fail when the version is not found, you must explicitly use the input.

#Example 1 Workflow
- name: Get Version From C# Project File
    uses: KinsonDigital/[email protected]
    with:
        repo-owner: JohnDoe
        repo-name: MyRepo
        branch-name: master
        file-type: xml
        file-path: MyProject/MyProject.csproj
        version-keys: Version
        fail-when-version-not-found: false

<!--Example 1 C# Project File-->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <LangVersion>10.0</LangVersion>
    <Version></Version>👈🏼No value.  Does not fail workflow.
</Project>

Requirements:

• Searches multiple keys for the version.
• The job fails if no version is found in the keys.

Result:

• The example below will use the value of 4.5.6 as the action output.

⚠️Since the fail-when-version-not-found input is not explicitly used in the YAML, the default value of true will be used and the job will fail if the version was not found.

#Example 2 Workflow
- name: Get Version From C# Project File
    uses: KinsonDigital/[email protected]
    with:
        repo-owner: JohnDoe
        repo-name: MyRepo
        branch-name: master
        file-type: xml
        file-path: MyProject/MyProject.csproj
        version-keys: Version,FileVersion

<!--Example 2 C# Project File-->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <LangVersion>10.0</LangVersion>
    <Version></Version>👈🏼No value.  Search continues using the FileVersion key
    <FileVersion>4.5.6</FileVersion>👈🏼Key exists so this value is returned
</Project>

Requirements:

• Search for a key without using case-sensitivity

Result:

• The example below will use the value of 1.2.3 as the action output.

#Example 3 Workflow
- name: Get Version From C# Project File
    uses: KinsonDigital/[email protected]
    with:
        repo-owner: JohnDoe
        repo-name: MyRepo
        branch-name: master
        file-type: xml
        file-path: MyProject/MyProject.csproj
        version-keys: VeRSion 👈🏼 # Different casing as the XML key below.
        case-sensitive-keys: false 👈🏼 # Not required and has a default value of true.

<!--Example 3 C# Project File-->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <LangVersion>10.0</LangVersion>
    <version>1.2.3</version> 👈🏼 <!--Spelling matches "VeRSion" but is still found as a version key.-->
</Project>

• Calvin Wilkinson (Owner and main contributor of the GitHub organization KinsonDigital)
  • Version Miner is used in various projects for this organization with great success.
• Click here to report any issues for this GitHub action!!