💡 Reusable Workflow Semantic Versioning and Release Automation

[github-actions[bot]]

Summary

Implement semantic versioning (v1, v1.2.0) with automated release tagging for all reusable workflows in this repository. Add a release workflow that creates Git tags, generates changelogs, and validates that all consuming repos reference valid versions. Prevent the class of org-wide failures caused by stale or missing version tags.

Market Signal

GitHub's 2026 best practices explicitly recommend pinning reusable workflows to commit SHAs for production usage. The upcoming workflow dependency locking feature (public preview in 3-6 months) will introduce a dependencies: section in workflow YAML that locks all direct and transitive dependencies using SHAs. Organizations that already version their reusable workflows will have a smoother migration path to this new mechanism. GitHub community discussions consistently highlight friction with reusable workflow referencing and versioning as a top pain point.

User Signal

Bug #267 (filed 2026-05-13) documents an org-wide failure caused by a stale v1 tag on the pr-review-mention reusable workflow. PR #236 had to revert a workflow deletion. PR #189 fixed incorrect reusable workflow header comments about secret passing. The 30-day PR history shows 6+ PRs fixing workflow reference and configuration issues across the org, indicating systemic fragility in the current "push to main and hope consumers update" model.

Technical Opportunity

The repository already has 8 reusable workflows (*-reusable.yml):

• agent-shield-reusable.yml
• auto-rebase-reusable.yml
• claude-code-reusable.yml
• dependabot-automerge-reusable.yml
• dependabot-rebase-reusable.yml
• dependency-audit-reusable.yml
• feature-ideation-reusable.yml
• pr-review-mention-reusable.yml

A release-reusable-workflows.yml workflow can:

1. Trigger on pushes to main affecting *-reusable.yml files
2. Determine version bump type from PR labels (semver:major, semver:minor, semver:patch) or commit prefixes
3. Create a precise Git tag (e.g., v1.3.0) and update the floating major tag (e.g., v1)
4. Create a GitHub Release with auto-generated notes
5. Run a consumer validation job that scans all petry-projects org repos for references to this repo's workflows and flags any pointing to non-existent tags

Assessment

Dimension	Score	Rationale
Feasibility	high	Git tagging + GitHub Releases are well-understood; the release workflow is standard CI
Impact	high	Prevents org-wide cascading failures; provides upgrade path to GitHub's dependency locking feature
Urgency	high	Bug #267 demonstrated the failure mode today; 6+ workflow fix PRs in 30 days show ongoing fragility

Adversarial Review

Strongest objection: Tagging adds ceremony to a currently simple push-to-main flow. For a small org, the overhead of maintaining version tags, changelogs, and consumer validation isn't worth it.

Rebuttal: Bug #267 caused org-wide PR review failures from a stale v1 tag — this is not hypothetical risk but proven, recent breakage. The 30-day PR history shows 6+ workflow reference fixes, each requiring investigation, fix, review, and merge across multiple repos. The versioning workflow is a one-time setup that runs automatically on merge; ongoing cost is near-zero. GitHub's upcoming dependency locking feature will make versioned workflows the standard, positioning the org ahead of the migration.

Suggested Next Step

Create a release-reusable-workflows.yml workflow that triggers on pushes to main affecting *-reusable.yml files. It should: (1) determine the version bump type from PR labels or commit prefixes, (2) create a Git tag (e.g., v1.3.0), (3) update the floating major tag (e.g., v1), (4) create a GitHub Release with auto-generated notes. Add a consumer validation job that scans petry-projects org repos for references to this repo's workflows.