Add a manual workflow to promote the release tag

[matt-edmondson]

What

promote-release.yml — a workflow_dispatch that moves the release tag, plus the matching section in docs/shared-ci.md.

Why a workflow rather than git push -f

Every repository's ci.yml resolves ci-shared.yml@release, so moving that tag is a change to CI in fifty repositories at once. From a terminal it has no record, no checks and no summary.

What it refuses

Dispatch takes a ref (default main) and the tag does not move unless all three hold:

1. The ref resolves to a commit in this repository.
2. The commit is contained in main. Nothing reaches fifty repositories' CI without having gone through review here — this is the check that makes the tag safe to move from a dispatch box.
3. ci-shared.yml exists at that commit, and so does every pipeline it dispatches to. Cheap to check, and the failure it prevents is org-wide: a release whose dispatcher names a missing pipeline breaks every caller the instant the tag moves.

Then it force-moves an annotated tag recording who promoted it and from which run, and writes a step summary naming the commit the tag moved from and to.

concurrency queues promotions rather than cancelling them — cancelling a run that may already have pushed the tag would leave it somewhere nobody read a summary for.

Testing

The validation step is a shell script with an embedded Python heredoc, which actionlint cannot execute, so I extracted the run: block after YAML dedent and ran it against a real clone:

Input	Result
main	passes — resolves f855adc, confirms both pipelines present
no-such-ref-xyz	rejected: does not resolve
a1e16a8 (on main, predates ci-shared.yml)	rejected: no ci-shared.yml at that commit
synthetic commit off main	rejected: not contained in main

So each refusal above is demonstrated, not just asserted. actionlint 1.7.7 with shellcheck clean; markdownlint-cli clean.

Ordering

Depends on #19, already merged — an unfiltered push: fires on tags, where actions/checkout leaves a detached HEAD and the bare git push fails, so every promotion would otherwise have produced a failing Update Readme run.

Once this merges, the first dispatch creates release. Nothing references it yet, so creating it is inert until repositories get a ci.yml.

🤖 Generated with Claude Code

https://claude.ai/code/session_014RABe2NufFc9hwm94iB3Rf

---

Generated by Claude Code