Initiative: adopt tag-based release pinning for ALL reusable workflows (extend the dev-lead/pr-review standard org-wide)

[don-petry]

Note: intended as a Discussion to ideate → plan → deliver as an initiative. The Discussions API isn't available to the agent tooling, so it's captured here — please Convert to discussion (Issue → ⋯ → Convert to discussion) if you want it in Discussions.

Problem

First-party reusable workflows are pinned inconsistently. Concretely, ci-failure-analyst-reusable.yml is pinned to off-main SHAs with inaccurate # main annotations — verified on main @ a682741:

SHA	On main?	Lives on
db60a41… (old)	❌	only fix/action-sha-pinning (unmerged)
0ef7b615… (new, now on main via #640 + #520)	❌	only fix/action-sha-pinning (unmerged)

Result: the lock file, templates/ci-failure-analyst.yml, and docs/aw/ci-failure-analyst.md all pin a commit that was never merged, and consumers copying the template inherit an off-main pin. The pr-review agent flagged this on #520 (MEDIUM, needs-human).

The agreed direction

Adopt tag-based release pinning + release versions for all reusable workflows — the standard already defined in petry-projects/.github and adopted by dev-lead (@dev-lead/stable, dev-lead/vX.Y.Z) and pr-review (@pr-review/stable). Replace SHA-# main pins with channel/version tags backed by cut-release.sh-style cuts.

Scope

1. Enumerate every cross-repo / first-party reusable workflow still pinned by SHA-or-# main (e.g. ci-failure-analyst, and any others under .github/workflows/* callers + templates/* + docs/aw/*).
2. Define release channels + cut initial versions for each reusable per the .github standard.
3. Repin all callers/templates/docs to the channel tag; remove inaccurate # main SHA pins.
4. Compliance checks: extend the structure tests (cf. tests/dev-lead/integration/test_auto_rebase_stub.py, test_dependency_audit_stub.py) so a SHA/off-main pin can't merge for any reusable — make tag-pinning a CI-enforced standard, not per-workflow bespoke tests.
5. Roll out across consuming repos (this is cross-repo, so it likely touches petry-projects/.github standards + downstream callers).

Deliverables

• A pinning standard doc update in .github covering all reusables (not just dev-lead/pr-review).
• Release tags cut for each reusable; callers/templates/docs repinned.
• A generalized compliance test enforcing tag pins org-wide.

Open questions (for ideation)

• One channel convention for all (@<name>/stable + vX.Y.Z) or per-tier?
• Who/what cuts releases for the non-agent reusables (manual cut-release.sh by OrganizationAdmin, as today, vs. a release workflow)?
• Migration order and how to avoid breaking in-flight consumers.
• Immediate stopgap for the already-merged off-main ci-failure-analyst pin (repin to an on-main SHA now, or fast-track its first tag)?

---

Originally filed as a bug from PR #520's pr-review finding; reframed per maintainer as an initiative covering all reusable workflows + compliance.

[github-actions[bot]]

[don-petry]

2. Fast track
3. Yes, one convention defined in .github standard
4. Agentic friendly Release workflow
5. Enforce release tags on reusable workflows
6. yes
7. yes, align as subsequent

[github-actions[bot]]

📋 Initiative planned by the BMAD Scrum Master (Bob).

Epic #684 — Tag-based release pinning for ALL first-party reusable workflows + org-wide compliance enforcement

6 stories created (inert — labelled initiative, NOT initiative:auto):

• [Phase 1] Stopgap: repin ci-failure-analyst off the broken off-main SHA to an on-main SHA #685 (S) — [Phase 1] Stopgap: repin ci-failure-analyst off the broken off-main SHA to an on-main SHA
• [Phase 1] Generalize cut-release.sh + the release standard to cover non-agent reusables #686 (M) — [Phase 1] Generalize cut-release.sh + the release standard to cover non-agent reusables
• [Phase 2] Generalized CI compliance test: reject SHA / # main pins on any first-party reusable #687 (M) — [Phase 2] Generalized CI compliance test: reject SHA / # main pins on any first-party reusable
• [Phase 2] Cut ci-failure-analyst initial release + channel tags and extend the release-channel ruleset #688 (S) — [Phase 2] Cut ci-failure-analyst initial release + channel tags and extend the release-channel ruleset
• [Phase 2] Repin ci-failure-analyst callers/template/docs to @ci-failure-analyst/stable #689 (S) — [Phase 2] Repin ci-failure-analyst callers/template/docs to @ci-failure-analyst/stable
• [Phase 3] Cross-repo rollout: lift the all-reusables standard into petry-projects/.github and repin downstream consumers #690 (L) — [Phase 3] Cross-repo rollout: lift the all-reusables standard into petry-projects/.github and repin downstream consumers

Open questions for review:

• Stopgap vs. fast-track (discussion Q4): land the interim on-main SHA repin (story id 1) at all, or skip straight to cutting the first ci-failure-analyst tag (stories id 4/5)? Story 1 is cheap insurance because the tag cut is an admin/hands-off action that may lag, but if an admin can cut the tag immediately, story 1 can be dropped.
• Channel convention (discussion Q1): this plan assumes ONE convention for all reusables (<name>/stable + <name>/vX.Y.Z), matching docs/release/versioning.md. Confirm we do not want a per-tier scheme for non-agent/utility reusables.
• Who cuts releases for non-agent reusables (discussion Q2): this plan keeps the manual cut-release.sh + OrganizationAdmin path (story id 4). Confirm whether a dedicated release workflow should automate cuts, and whether the forthcoming health-gated promotion workflow ([Phase 2] Replace PUT-contents clobber deploy with versioned, ring-staged, health-gated promotion #501) should own channel-tag moves for ci-failure-analyst too.
• Initial version for ci-failure-analyst: v0.1.0 (pre-1.0, assumed) vs v1.0.0 (signal production-ready). Confirm before cutting.
• Relationship to the Safe Release Strategy initiative (epic Initiative: Safe Release Strategy for Agentic Workflows (versioning · rings · canary) #495, docs/initiatives/agentic-release-strategy.md), which explicitly scoped ci-failure-analyst OUT 'for now'. This initiative reverses that for the pinning/compliance dimension — confirm it should proceed independently rather than be folded into Initiative: Safe Release Strategy for Agentic Workflows (versioning · rings · canary) #495.
• Bespoke-stub disposition (story id 3): keep test_auto_rebase_stub.py / test_dependency_audit_stub.py alongside the generalized test, or fold them in? They assert exact @v2 refs for petry-projects/.github reusables, which the generalized class-based test would need to preserve.

---

Review the epic and its sub-issue DAG, adjust as needed, then add initiative:auto to epic #684 to hand it to initiative-driver for auto-implementation.

[github-actions[bot]]

Enhancement: Tag-Based Release Pinning — Canonical Inventory, Automation & Lint Gate

Sharpened problem & goal
First-party reusable workflows are pinned inconsistently — some callers use stale/off-main SHAs with inaccurate # main annotations. The goal is to extend the @dev-lead/stable / @pr-review/stable channel-tag pattern (already the approved standard for those two agents per AGENTS.md §"Release channel tags") to all first-party reusable workflows. Key ambiguity: a canonical inventory of which workflows are "in scope" doesn't yet exist. The implementation plan should start there — without it, automation and lint gates have an undefined target.

Context
Significant infrastructure already exists for this exact pattern:

• scripts/cut-release.sh — creates immutable vX.Y.Z tags and advances channel tags; already enforces "never overwrite a release tag"; extending it to new workflows is a configuration addition
• docs/release/versioning.md — documents the two-tag scheme (immutable release + moving channel)
• The release-channel-tags repository ruleset already restricts pr-review/** and dev-lead/** tags — this ruleset needs extending to cover newly tagged workflows
• The gh-aw-compile job in lint.yml (AGENTS.md documented exception) already gates agentic workflow compilation — a "all first-party callers use channel tags, not bare SHAs" lint check is a natural addition here

This is also related to the CI SHA-pin standard: AGENTS.md distinguishes third-party actions (must use SHA) from first-party channel tags (intentionally mutable, accepted exception). The lint gate must understand this distinction to avoid flagging valid channel-tag references.

Impact / Effort

• Impact: HIGH — stale SHA pins with wrong annotations create supply-chain confusion risk and make rollbacks unreliable; the ci-failure-analyst-reusable.yml example is a concrete production instance
• Effort: M — inventory + cutting initial tags is S; extending cut-release.sh and the ruleset to new workflows is M; a CI lint gate is S

Suggested acceptance criteria

• A canonical inventory (docs/release/workflow-inventory.md) lists every first-party reusable workflow, its current pin style (SHA/tag/branch), its caller(s), and its target state — this is the prerequisite for all subsequent steps
• All in-scope workflows have an initial vX.Y.Z immutable tag cut via scripts/cut-release.sh and a corresponding stable channel tag
• The release-channel-tags repository ruleset is extended to cover all newly tagged workflows (protecting them from unauthorized moves/deletes)
• lint.yml gains a check that fails if any .github/workflows/*.yml caller references a first-party reusable via bare SHA instead of a channel tag — with an explicit allowlist for the SHA-pinning standard's third-party exceptions so the two rules don't conflict
• scripts/cut-release.sh (or a wrapper) can cut releases for all inventoried first-party reusables, not just pr-review/dev-lead, with per-workflow version tracking