Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kinsondigital/versionminer
Pulls versions from XML files for use in a workflow
https://github.com/kinsondigital/versionminer
action actions github-actions hacktoberfest
Last synced: about 9 hours ago
JSON representation
Pulls versions from XML files for use in a workflow
- Host: GitHub
- URL: https://github.com/kinsondigital/versionminer
- Owner: KinsonDigital
- License: mit
- Created: 2021-07-12T09:24:21.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-08T16:59:11.000Z (about 1 month ago)
- Last Synced: 2024-10-30T05:41:38.858Z (21 days ago)
- Topics: action, actions, github-actions, hacktoberfest
- Language: C#
- Homepage: https://github.com/marketplace/actions/version-miner
- Size: 648 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
**🪨⛏️**
**VersionMiner**
[](https://app.codecov.io/gh/KinsonDigital/VersionMiner/tree/release%2Fv1.0.0)
[](https://github.com/KinsonDigital/VersionMiner/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
[](https://discord.gg/qewu6fNgv7)
## **🤷🏼♂️ What is it? 🤷🏼♂️**
This **GitHub Action** makes it easy to pull versions from XML files.
It can be used in your workflows for other uses such as version validation, version tag management, and more!!
TLDR - Additional Info
In a nutshell, _**VersionMiner**_ 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.
TLDR - Use Cases
- 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.
>**Note** VersionMiner is built using C#/NET and runs in a docker container. If the job step for running this action is contained in a job that runs on **Windows**, you will need to move the step to a job that runs on **Ubuntu**. You can split up your jobs to fulfill the `runs-on` requirements of the GitHub action. This can be accomplished by moving the step into its job. You can then route the action step outputs to the job outputs and use them throughout the rest of your workflow.
For more information on step and job outputs, refer to the GitHub documentation links below:
>- [Defining outputs for jobs](https://docs.github.com/en/actions/using-jobs/defining-outputs-for-jobs)
>- [Setting a step action output parameter](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter)
🪧 Example 🪧
```yml
name: Get Version Example
jobs:
get_version_job:
runs-on: ubuntu-latest # Cannot use windows
steps:
- uses: actions/3
- name: Get Version From C# Project File
id: get-version
uses: KinsonDigital/[email protected]
with:
repo-owner: JohnDoe
repo-name: MyRepo
repo-token: ${{ secrets.GITHUB_TOKEN }}
branch-name: main
file-format: xml # Not case sensitive
file-path: "MyProject/MyProject.csproj"
version-keys: Version
- name: Print Version From File
id: print-output
run: echo "${{ steps.get-version.outputs.version }}"
```
If the XML file had the contents below, the workflow above would print the value ***1.2.3*** to the GitHub console.
```xml
Exe
net7.0
11.0
1.2.3
0.1.0
```
---
## **➡️ Action Inputs ⬅️**
| Input Name | Description | Required | Default Value |
|:---|:---|:---:|:---:|
| `repo-owner` | The owner of the repository. This is _**NOT**_ case-sensitive. | yes | N/A |
| `repo-name` | The name of the repository. This is _**NOT**_ case-sensitive. | yes | N/A |
| `repo-token` | The repository or PAT token to use for authorized requests. | yes | empty |
| `branch-name` | The name of the branch where the file lives. This _**IS**_ case sensitive. | yes | N/A |
| `file-format` | A non-case-sensitive value representing the data format of the file that contains the version. Currently, the only supported value is `xml` for a file format. | yes | N/A |
| `file-path` | The path to the file relative to the root of the repository. | yes | N/A |
| `version-keys` | A comma-delimited list of keys that hold the version value. Spaces around commas are ignored. Values must be wrapped with single or double quotes to be processed properly if more than one key exists. The search for keys will stop once the first occurrence of a key that contains a value is found. | yes | N/A |
| `case-sensitive-keys` | If true, key searching will be case-sensitive. | no | `true` |
| `trim-start-from-branch` | Will trim the given value from the beginning of the `branch-name` input. | no | empty |
| `fail-on-key-value-mismatch` | If true, the action will fail, if all of the key values listed in the `version-keys` input do not match. Other failure inputs will not affect this input. | no | `false` |
| `fail-when-version-not-found` | If true, the action will fail, if no version exists. Other failure inputs will not affect this input. | no | `true` |
## **⬅️ Action Output ➡️**
The action output is a single `string` value with the name _**version**_. Click here to see an example of how to use the output of the action.
---
## **🪧 More Examples 🪧**
Searches for a version but does not fail the workflow if no version is found:
```yml
#Example 1 Workflow
- name: Get Version From C# Project File
uses: KinsonDigital/[email protected]
with:
repo-owner: JohnDoe
repo-name: MyRepo
repo-token: ${{ secrets.GITHUB_TOKEN }}
branch-name: main
file-format: xml # Not case sensitive
file-path: "${{ github.workspace }}/MyProject/MyProject.csproj"
version-keys: Version
fail-when-version-not-found: false
```
```xml
Exe
net7.0
11.0
```
Searches multiple keys for the version. The job fails if no version is found in the keys:
```yml
#Example 2 Workflow
- name: Get Version From C# Project File
uses: KinsonDigital/[email protected]
with:
repo-owner: JohnDoe
repo-name: MyRepo
repo-token: ${{ secrets.GITHUB_TOKEN }}
branch-name: main
file-format: xml # Not case sensitive
file-path: "MyProject/MyProject.csproj"
version-keys: "Version,FileVersion"
```
```xml
Exe
net7.0
11.0
4.5.6
```
Searches for a key without using case-sensitivity:
```yml
#Example 3 Workflow
- name: Get Version From C# Project File
uses: KinsonDigital/[email protected]
with:
repo-owner: JohnDoe
repo-name: MyRepo
repo-token: ${{ secrets.GITHUB_TOKEN }}
branch-name: main
file-format: xml # Not case sensitive
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.
```
```xml
Exe
net7.0
11.0
1.2.3
```
Trims the value `refs/heads/` from the beginning of the branch.
> **Note** Click [here](https://docs.github.com/en/actions/learn-github-actions/environment-variables#default-environment-variables) to get more information about the default variable `github.ref` used in the example below:
```yml
#Example 4 Workflow
- name: Get Version From C# Project File
uses: KinsonDigital/[email protected]
with:
repo-owner: JohnDoe
repo-name: MyRepo
repo-token: ${{ secrets.GITHUB_TOKEN }}
branch-name: ${{ github.ref }} # If the branch was 'my-branch', this value could be 'refs/heads/my-branch'
file-format: xml # Not case sensitive
file-path: "MyProject/MyProject.csproj"
version-keys: version
trim-start-from-branch: "refs/heads/"
```
---
🙏🏼 Contributing 🙏🏼
Interested in contributing? If so, click [here](https://github.com/KinsonDigital/.github/blob/main/docs/CONTRIBUTING.md) to learn how to contribute your time or [here](https://github.com/sponsors/KinsonDigital) if you are interested in contributing your funds via one-time or recurring donation.
## **🔧 Maintainers 🔧**
[Calvin Wilkinson](https://twitter.com/KDCoder) (KinsonDigital GitHub Organization - Owner)
[Kristen Wilkinson](https://twitter.com/kswilky) (KinsonDigital GitHub Organization - Project Management, Documentation, Tester)
🚔 Licensing And Governance 🚔
[](https://github.com/KinsonDigital/.github/blob/main/docs/code_of_conduct.md)
[](https://github.com/KinsonDigital/VersionMiner/blob/main/LICENSE.md)
This software is distributed under the very permissive MIT license and all dependencies are distributed under MIT-compatible licenses.
This project has adopted the code of conduct defined by the **Contributor Covenant** to clarify expected behavior in our community.