Versioning & Tagging

🏷️ Versioning & Tagging Guide

This page explains how the CI/CD pipelines handle versioning and Git tagging for preview, release candidate, and release builds.

---

Build Version Resolver

The Version Resolver workflow automatically determines the correct version string based on:

• ✅ Build type (preview, release_candidate, or release)
• ✅ Git context (tag push, branch, pull request, or manual input)
• ✅ Optional manual version input

---

Versioning Rules

Build Type	Resolved Version Example
release	v1.2.3 (from Git tag or manual input)
release_candidate	v1.2.3-rc.1 (auto-generated or based on input)
preview	manual-main, main, or PR-0001 (branch or PR-based)

• ✅ Manual override → If version input is provided, it’s used directly (except in release, where Git tag takes priority).
• ✅ RC auto-generation → Automatically increments -rc.N suffix based on the latest matching base tag.
• ✅ Pull request builds → Use PR-XXXX format.
• ✅ Branch-based builds → Use branch name (main, feature-branch), replacing / with -.
• ✅ Fallback → Short commit SHA (commit-abc123).

---

Error Checks

• For release builds, you must push a valid Git tag (e.g., v1.2.3) or provide a valid manual version.
• If a resolved version already exists as a tag (outside a tag-push), the workflow fails early to prevent accidental overwrites.

---

Version Tagger

The Version Tagger workflow ensures Git tags are correctly created or verified:

• ✅ For release and release_candidate builds only (skipped for preview)
• ✅ Checks if the requested tag already exists
• ✅ If missing, creates the tag using the GitHub API

---

Tagging Flow

1. Inputs

   • version: required (e.g., v1.2.3 or v1.2.3-rc.1)
   • buildType: required

2. Tag Check

   • Uses .github/scripts/tagging/check-tag-exists.sh to verify if the tag exists.

3. Tag Creation (if needed)

   • Uses .github/scripts/tagging/create-tag.sh to create the new tag.

4. Summary Reporting

   • Outputs whether the tag already existed or was newly created.

---

Summary Table

Build Type	Tag Created?
preview	No tagging performed
release_candidate	Tag like v1.2.3-rc.1 created if missing
release	Tag like v1.2.3 created if missing

---

📋 Summary Outputs

At the end of each workflow, you get:

• ✅ Build type and trigger
• ✅ Resolved version
• ✅ Whether the tag already existed or was newly created
• ⚠️ Any warnings (e.g., version collisions)

You can view these summaries directly in the GitHub Actions run summary.

---

💡 Notes

• Manual builds → Trigger builds manually using workflow_dispatch and provide a version input.
• Automated builds → For release workflows, pushing a properly named Git tag (e.g., v1.2.3) triggers the correct flow.
• RC versioning script → Located at .github/scripts/build/version-generator-for-rc.sh, this handles incrementing -rc.N suffixes.

---