feat: adopt merge queue versioning

[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 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.

This repo is the test. It is the canary for validating reusable workflows end to end.

PR Type

• Feature

Linked tickets

• feat: add merge queue versioning workflows shared-workflows#122

High level description

Canary adoption of the merge queue versioning model from digicatapult/shared-workflows#122. Moves this repository from bumping the version on the pull request branch to applying it on main after merge.

Detailed description

Removed

• synchronise-pr-version-npm.yml and synchronise-trunk-version-npm.yml callers. These commit a version onto the branch, which dismisses approval and evicts the PR from a queue. Both reusable workflows remain in shared-workflows for repositories not adopting a queue.
• The check-version job in test.yml. It asserts package.json is ahead of the last release, which two approved PRs cannot both satisfy.

The two models compete over the same v: labels, so a repository uses one or the other.

Added

• version-label.yml, gating a PR on exactly one v: label. Its own file because it must trigger on labeled and unlabeled, which in test.yml would re-run the whole suite on every label change.
• apply-version.yml, computing and committing the version on main after merge.
• renovate.json, holding the merge queue Renovate overrides inline.
• A Merge queue section in README.md carrying the rationale, so the workflow files stay terse.

Changed

• test.yml: adds merge_group, and sets fail_on_same_version: false on both build-docker jobs. Without that second change every PR would fail, because the branch deliberately carries no version bump and build-docker's check-version defaults to failing when the version matches the latest release.
• release.yml: every job guarded so the release runs on the version commit rather than the merge commit, since build-docker, generate-sbom and release-github all read the version from the checked-out tree.

What a merge now looks like

1. The queue merges the PR. apply-version computes the bump from its label and pushes a chore(release): commit. release.yml is skipped.
2. That version commit triggers a second run. apply-version is skipped by its guard. release.yml runs and releases.

Renovate

Four overrides, inline rather than in a shared preset so an untested preset does not land across every repository at once:

Setting	Why
bumpVersion: null	The base preset has Renovate write the version onto its own branch, reintroducing the collision this change removes.
addLabels: ["v:patch"]	The base preset applies no v: labels, so every Renovate PR would fail the gate and never merge.
platformAutomerge: true	Renovate supports merge queues only when true, since GitHub does the enqueueing. Already the default; explicit because it is load bearing. Needs "Allow auto-merge" on the repo.
rebaseWhen: "automerging"	The base preset's behind-base-branch rebases every open PR whenever main moves, wasted CI under a queue and evicts anything enqueued. automerging limits that to PRs actually automerging.

Renovate's branch automerge (automergeType: branch) can never work behind a merge queue. This repo uses pr, so it is unaffected.

Describe alternatives you've considered

Keeping both the per-PR bump callers and the new ones, selected by a variable. Rejected: both react to the same v: labels, so the repo would bump twice. Coexistence belongs in shared-workflows, where both reusables remain, not in a single caller.

Putting the Renovate overrides straight into a shared preset. Rejected for now: proving them here first avoids landing an untested preset org-wide.

rebaseWhen: "conflicted". An earlier revision of this PR used it, taken from a GitHub discussion rather than the documentation. Renovate documents auto as rebasing when automerge is enabled, so conflicted risks an automerging PR sitting behind its base and never merging. automerging cannot deadlock.

Operational impact

Prerequisites that need repository admin, and this PR should not merge without them:

1. The GitHub App behind BOT_ID / BOT_KEY must be added to the bypass list of the organisation ruleset protecting main. It now pushes there rather than to feature branches. A repo-level ruleset cannot grant this, because rulesets are cumulative.
2. "Allow auto-merge" must be enabled. Currently off. Renovate needs it to route through the queue.
3. A repo-level ruleset with the merge queue rule and required checks, with "Require branches to be up to date" off. Set the required check names only after #122 merges, since the test check names change.

Before merging: the six shared workflows pinned to @merge-queue-versioning (migration-checks-npm/poetry, static-checks-npm/poetry, tests-npm/poetry, plus build-docker) must be flipped to @main once #122 lands.

To revert: restore the two synchronise-* callers and the check-version job, and drop the workflow changes. Nothing in shared-workflows needs reverting.

Additional context

Verified in a real merge queue on a throwaway branch, so main was never touched:

• Two PRs both labelled v:patch merged together, package.json unchanged at 2.0.0 throughout. PR 31's queue branch was built on PR 30's commit, confirming stacking.
• A PR failing migration-checks was refused entry to the queue.
• Full suite green on the queue branch, 38 jobs: run 30699160605.

Known gaps:

• The Renovate overrides are inline, so no other repository benefits until promoted to renovate-config. That promotion must also cover cargo and nuget, which carry the same bumpVersion: patch and are omitted here only because this repo has neither.
• generate-sbom on PRs now tags Dependency-Track with the current released version rather than the upcoming one, since the branch is not bumped. It uses fail_on_same_version: false so nothing fails, but the tag is less useful.
• This repo is a weak canary for version comparisons: its package.json is 2.0.0 against a latest release tag of v1.1.3, so it is already ahead. That masked the build-docker same-version failure, which was found by inspection rather than by CI here.