governance(tags): add tag rulesets + tag gate workflow#51
governance(tags): add tag rulesets + tag gate workflow#51tomtastisch wants to merge 2 commits intomainfrom
Conversation
Document GitHub tag rulesets for stable and RC tags, including patterns, enforcement, and expected behavior. Signed-off-by: Tomtastisch <82227609+tomtastisch@users.noreply.github.com>
…tag validation Signed-off-by: Tomtastisch <82227609+tomtastisch@users.noreply.github.com>
github-actions
bot
added
version:patch
There was a problem hiding this comment.
Pull request overview
This PR adds governance documentation and a GitHub Actions workflow to enforce tag naming policies for stable and release candidate tags. The changes establish tags as the single source of truth (SSOT) for releases by documenting GitHub tag rulesets and implementing a validation workflow that runs on tag creation.
Changes:
- Documents GitHub tag ruleset configuration for stable (
v*) and RC (v*-rc.*) tags, including enforcement policies and rollout steps - Adds a tag-gate workflow that validates tag format and derives version outputs, with evidence artifact generation
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/governance/002_POLICY_TAGGING_RULESETS.md | Defines policy for GitHub tag rulesets including patterns, enforcement rules, and rollout order |
| .github/workflows/tag-gate.yml | Implements automated tag validation workflow that checks tag format and calls derive_tag_outputs.sh script |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 2. Add `.github/workflows/tag-gate.yml`. | ||
| 3. Wire publish pipelines to `needs: tag-gate` or via `workflow_run` on success. |
There was a problem hiding this comment.
According to the rollout plan in the documentation (line 43-44), publish pipelines should be wired to depend on the tag gate using 'needs: tag-gate' or via 'workflow_run' on success. However, the release.yml workflow still only references 'needs: version-policy' (release.yml:99) and doesn't reference this new tag-gate job. The tag-gate workflow will run independently but won't block the release workflow if it fails.
| - (optional) Require signed commits / signed tags | ||
| - Require status checks once the rc tag workflow is stable (RC is fail-closed) | ||
|
|
||
| ## Expected behaviour |
There was a problem hiding this comment.
British English spelling 'behaviour' is used here, but should be 'behavior' to match American English spelling used consistently throughout the codebase (e.g., 'behavior' in docs/governance/002_POLICY_LABELING.MD line 4).
| ## Expected behaviour | |
| ## Expected behavior |
| @@ -0,0 +1,45 @@ | |||
| # POLICY: GitHub Tag Rulesets `tags-stable` + `tags-rc` | |||
There was a problem hiding this comment.
The file extension should be uppercase .MD to be consistent with other governance policy files in this directory. All other policy files use .MD (e.g., 001_POLICY_CI.MD, 002_POLICY_LABELING.MD, 002_POLICY_NAMING_UNIFIED.MD). According to docs/governance/006_INDEX_CI_RULES.MD line 2, governance tooling globs for *.MD uppercase extensions.
| 1. Create rulesets (in evaluate mode only if needed, otherwise active). | ||
| 2. Add `.github/workflows/tag-gate.yml`. | ||
| 3. Wire publish pipelines to `needs: tag-gate` or via `workflow_run` on success. | ||
| 4. Enable status checks for tags only once the checks exist and are stable. |
There was a problem hiding this comment.
This policy document is missing the standard "RoC-Bezug" (Rules of Compliance reference) section that appears in other governance policy documents. See examples in docs/governance/001_POLICY_CI.MD lines 52-57 and docs/governance/002_POLICY_LABELING.MD lines 24-28. This section should reference relevant rule files like artifact_contract.yaml, docs_drift.yaml, and shell_safety.yaml if applicable.
| 4. Enable status checks for tags only once the checks exist and are stable. | |
| 4. Enable status checks for tags only once the checks exist and are stable. | |
| ## RoC-Bezug | |
| - `rules/artifact_contract.yaml` | |
| - `rules/docs_drift.yaml` | |
| - `rules/shell_safety.yaml` |
| - name: Gate - validate tag format (stable/rc) | ||
| shell: bash | ||
| run: | | ||
| set -euo pipefail | ||
| TAG="${GITHUB_REF_NAME}" | ||
|
|
||
| STABLE_RE='^v[0-9]+\.[0-9]+\.[0-9]+$' | ||
| RC_RE='^v[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$' | ||
|
|
||
| if [[ "$TAG" =~ $STABLE_RE ]]; then | ||
| echo "OK: stable tag $TAG" | ||
| elif [[ "$TAG" =~ $RC_RE ]]; then | ||
| echo "OK: rc tag $TAG" | ||
| else | ||
| echo "FAIL: invalid tag format: $TAG" >&2 | ||
| exit 1 | ||
| fi |
There was a problem hiding this comment.
The tag validation regex patterns here are more restrictive than the regex in tools/ci/release/derive_tag_outputs.sh (line 6). The derive_tag_outputs.sh script uses ^v([0-9]+)\.([0-9]+)\.([0-9]+)(-([0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*))?$ which allows any alphanumeric prerelease identifiers, while this workflow only accepts v*-rc.* format for RC tags. This means tags like v1.0.0-beta.1 or v1.0.0-alpha would pass the gate step calling derive_tag_outputs.sh but fail the tag format validation step. Consider either aligning the patterns or documenting why they differ.
| - name: Gate - derive tag outputs (SSOT) | ||
| shell: bash | ||
| env: | ||
| RELEASE_TAG: ${{ github.ref_name }} | ||
| run: bash tools/ci/release/derive_tag_outputs.sh |
There was a problem hiding this comment.
The derive_tag_outputs.sh script writes outputs to GITHUB_OUTPUT (version, tag, assembly_version, file_version), but this step doesn't have an id set, so the outputs cannot be referenced by other steps or jobs. If these outputs are needed elsewhere, add an id to this step. If they're not needed, consider using a simpler validation script that doesn't attempt to write outputs.
|
Closed per governance step 1 (GitHub-only config) |
1 participant
Document GitHub tag rulesets for stable and RC tags, including patterns, enforcement, and expected behavior.
Ziel & Scope
Umgesetzte Aufgaben (abhaken)
Nachbesserungen aus Review (iterativ)
resolved(inkl. outdated)Security- und Merge-Gates
security/code-scanning/tools: 0 offene AlertsEvidence (auditierbar)
DoD (mindestens 2 pro Punkt)
Risiken / Open Items
Details (nur falls vorhanden)