feat: add merge queue versioning workflows

[dblane-digicatapult]

Pull Request

Checklist

• Have you read Digital Catapult's Code of Conduct?
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.

Validated in the hello-world canary rather than by unit tests, which is how reusable workflows are verified here. Evidence below.

PR Type

• Feature
• Bug Fix

Linked tickets

• Canary: feat: adopt merge queue versioning hello-world#29

High level description

Adds an opt-in versioning model for repositories on a GitHub merge queue, where a pull request carries only the intent to bump (a v: label) and the version number is computed on trunk after merge. Also fixes five existing workflows that break, or silently misbehave, under merge_group.

Additive throughout. The synchronise-*-version workflows are untouched, so repositories not adopting a queue are unaffected.

Detailed description

Why the current gate cannot survive a queue. Requiring package.json to be ahead of the last release puts an absolute number on the branch, so two approved pull requests compute the same one. The queue merges the first and publishes that tag; the second now equals the latest tag, fails check-version, and is evicted. Recovering it needs another bump, which dismisses its approval. That is the loop the queue was adopted to remove.

New workflows

Workflow	Purpose
require-version-label.yml	Gates a PR on exactly one v: label. Order independent, so every queued PR satisfies it at once. No token, no permissions.
apply-version-npm.yml / apply-version-poetry.yml	Compute and commit the version on trunk after merge. Same arithmetic as synchronise-pr-version-*, different location. Resolves the bump across every commit in the push, so batched queue merges work.

Why the App token, and why a merge produces two runs. build-docker, generate-sbom and release-github all read the version from the checked-out tree, so the released commit must be the one carrying the new version. GITHUB_TOKEN pushes do not trigger workflows, so a version commit pushed with it would never be built and nothing would be published. Using the App token means the version commit triggers a second run, and that run releases. A shared chore(release): prefix guards both sides against triggering each other.

This is the same App the synchronise-* workflows already use, so adopters need no new app and no new secrets. It does need adding to the trunk ruleset bypass.

Bug fixes

Fix	Impact
migration-checks-npm/poetry resolve merge_group	A merge_group payload has neither pull_request nor before, so the base sha resolved empty and the immutability lint, ordering lint and seeded-upgrade silently no-opped for every queued PR. Lost coverage, not just a compatibility nicety.
tests-npm coverage comment guarded to pull_request	No PR to comment on under merge_group; would fail the job and stall the queue for any repo with coverage: true.
tests-npm / tests-poetry job names	The name interpolated the branch, so the check name carried the ephemeral gh-readonly-queue/... ref, unique per PR and per merge attempt. Such a name can never be a required status check, so the queue would wait forever.
static-checks-npm/poetry SARIF upload skipped on merge_group	The queue deletes its ref before code scanning can attach the analysis, failing with "ref not found". Observed on a real queue run. Would block every merge once lint and test are required.
release-github release notes	Built from gh pr list --limit 1, which orders by created date, not merged date, so a long-lived PR merged today loses to a newer one merged last week. Also credits only one PR, misattributing any batched merge. Now resolved from the commits since the previous release tag.
build-docker gains fail_on_same_version (default true)	Its check-version call defaulted to failing when the version matches the latest release. For repos with no separate check-version job that is the PR version gate, so it cannot simply be disabled. Queue repos set false; default is unchanged for everyone else.

Documentation

README gains a "Choosing a versioning model" section presenting the two models as alternatives, and a "Merge queue compatibility" table recording the merge_group behaviour once rather than in each file. Three new examples docs.

Describe alternatives you've considered

Pushing the version commit with GITHUB_TOKEN. Preferred initially because it cannot loop. Rejected: such pushes never trigger a run, so the release keeps running on the pre-bump commit and silently publishes nothing. Making it work needs a ref or version input plumbed through build-docker, generate-sbom and release-github, a much larger and non-additive change.

Deriving the version from git tags and dropping it from package.json. Cleanest conceptually, but changes anything reading package.json at build or deploy time.

Replacing the per-PR bump outright. Rejected. Both models are kept and documented so repositories can adopt a queue at their own pace.

Disabling build-docker's same-version failure rather than adding an input. Rejected: it is the de facto PR version gate for repos without a separate check-version job.

Operational impact

Additive for every existing consumer. Behaviour changes only on code paths that are currently broken or unreachable on pull_request and push.

A repository adopting the new model must:

1. Add merge_group to whichever workflow provides its required checks, or the queue waits indefinitely.
2. Set fail_on_same_version: false on build-docker in its PR workflow.
3. Add the GitHub App to the trunk ruleset bypass.
4. Use one model or the other, never both, since they compete over the same v: labels.

Additional context

Design writeup: Merge Queue for testbed-portal.

Verified in a real merge queue on hello-world (against a throwaway branch, main untouched):

• Two PRs both labelled v:patch merged together with no version on either branch. PR 31's queue branch was built on PR 30's commit, confirming stacking.
• A PR failing migration-checks was refused entry: "Pull request has failing required statuses".
• Full suite green on the queue's own branch, 38 jobs: run 30699160605.

Embedded shell logic (label matching, version arithmetic, precedence, prefix guard, release-note tag detection and range) was executed against a case table including multi-label, no-label, null payload, two-digit components, a force-moved latest tag and near-miss labels such as v:majorish.

Known gap: apply-version-poetry.yml is not exercised by the canary, which syncs only package.json. A Poetry repo needs its own canary before adopting.