Home Original page

GitHub - AbsaOSS/version-tag-check: GitHub Action for validating version tag order and enforcing consistent versioning rules.

Version Tag Checker

A GH action for validating version tag sequences and ensuring compliance with versioning standards in repositories.

Motivation

This action is designed to help maintainers and contributors ensure that version tags are sequenced correctly and comply with versioning standards. It can be used to prevent common issues such as:

  • Duplicate version tags on input
  • Missing version tags
  • Incorrect version sequences
  • Non-standard version formats

The action provides two possible regimes, controlled by the should-exist flag:

  • If should-exist=false (default): the action checks that the version tag is a valid increment of the latest existing version.
  • If should-exist=true: the action checks that the specified tag already exists in the repository (and skips increment checks).

Requirements

  • GitHub Token: A GitHub token with permission to fetch repository data such as Issues and Pull Requests.
  • Python 3.11+: Ensure you have Python 3.11 installed on your system.

Inputs

github-repository

  • Description: The GitHub repository to check for version tags. Example: AbsaOSS/version-tag-check.
  • Required: Yes

version-tag

  • Description: The version tag to check for in the repository. Example: v0.1.0.
  • Required: Yes

should-exist

  • Description: Flag to indicate if the version tag should exist in the repository. Set to true to check if the version tag should exist. Note: Setting this to true disables the increment validity check.

  • Default: false

  • Required: No

GITHUB_TOKEN

  • Description: Your GitHub token for authentication. Store it as a secret and reference it in the workflow file as secrets.GITHUB_TOKEN.
  • Required: Yes

Behavior Summary

The action performs three sequential checks:

  • Tag format check – ensures the tag follows semantic versioning and starts with v, e.g., v1.2.3.
  • Presence check – determines whether the version tag is present in the target GitHub repository.
  • Increment check – verifies that the provided version tag is a valid increment over the latest existing version.
    • ⚠️ This step is only performed when should-exist=false.
Tag present in repository (2nd check) Expected presence of tag in repository Increment Validity Check (3rd check) Action final state
Yes true Skipped ✅ Success: The version tag exists as expected.
No true Skipped ❌ Failure: The version tag does not exist in the repository.
Yes false Skipped ❌ Failure: The version tag should not exist but does.
No false ✅ Valid ✅ Success: The version tag does not exist and is a valid increment.
No false ❌ Invalid ❌ Failure: The version tag does not exist and is an invalid increment.

Usage

Adding the Action to Your Workflow

See the default action step definition:

- uses: actions/setup-python@v5.1.1
  with:
    python-version: '3.11'

- name: Version Tag Check
  id: version_tag_check
  uses: AbsaOSS/version-tag-check@v0.1.0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
  with:
    github-repository: "{ org }/{ repo }"   # e.g. ${{ github.repository }}
    version-tag: "v0.1.0"
    should-exist: "false"

To troubleshoot a failing run, re-run the GitHub Actions workflow with "debug logging" enabled or run it locally using the script described in Developer Guide.

Supported Version Tags Formats

Standard Versions

  • v1.0.0 - Standard semantic version

Pre-release Qualifiers

  • v1.0.0-SNAPSHOT - Snapshot pre-release
  • v1.0.0-ALPHA - Alpha pre-release
  • v1.0.0-BETA - Beta pre-release
  • v1.0.0-RC1 to v1.0.0-RC99 - Release candidates (e.g., RC1, RC2, ..., RC99)
  • v1.0.0-RELEASE - Release qualifier

Hotfix Qualifiers

  • v1.0.0-HF1 to v1.0.0-HF99 - Hotfixes (e.g., HF1, HF2, ..., HF99)

Version Weight Comparison

Numeric Precedence

Numeric versions always take precedence over qualifiers:

  • v2.0.0-SNAPSHOT > v1.9.9-RELEASE
  • v1.0.0 < v1.0.1 < v1.1.0 < v2.0.0

Qualifier Precedence (for the same numeric version)

For the same numeric version (e.g. v1.0.0), qualifiers are ordered as follows:

  1. Pre-release progression:

    • v1.0.0-SNAPSHOT < v1.0.0-ALPHA < v1.0.0-BETA
    • v1.0.0-BETA < v1.0.0-RC1 < v1.0.0-RC2 < ... < v1.0.0-RC99
    • v1.0.0-RC99 < v1.0.0-RELEASE < v1.0.0

  2. Hotfix progression:

    • v1.0.0 < v1.0.0-HF1 < v1.0.0-HF2 < ... < v1.0.0-HF99

Example progression:

v1.0.0-SNAPSHOT → v1.0.0-ALPHA → v1.0.0-BETA → v1.0.0-RC1 → v1.0.0-RC2 → 
v1.0.0-RELEASE → v1.0.0 → v1.0.0-HF1 → v1.0.0-HF2

For more details, see the Version qualifier validation specification.

Developer Guide

See this Developer Guide for more technical, development-related information.

Documentation

Contribution Guidelines

We welcome contributions to the Version Tag Check Action! Whether you're fixing bugs, improving documentation, or proposing new features, your help is appreciated.

How to Contribute

  • Submit Pull Requests: Feel free to fork the repository, make changes, and submit a pull request. Please ensure your code adheres to the existing style and all tests pass.
  • Report Issues: If you encounter any bugs or issues, please report them via the repository's Issues page.
  • Suggest Enhancements: Have ideas on how to make this action better? Open an issue to suggest enhancements.

Before contributing, please review our contribution guidelines for more detailed information.

License Information

This project is licensed under the Apache License 2.0. It is a liberal license that allows you great freedom in using, modifying, and distributing this software, while also providing an express grant of patent rights from contributors to users.

For more details, see the LICENSE file in the repository.

Contact or Support Information

If you need help with using or contributing to Generate Release Notes Action, or if you have any questions or feedback, don't hesitate to reach out: