post-release.yml

name: Post Release

# Names each run for what it targets, so the Actions list distinguishes runs at a glance
# instead of showing a column of identical "Post Release" rows:
#
#   Post Release - 2025.1.2
#   Post Release - 2024.0.8 (commercial)
#   Post Release - 2025.1.2 [spring-cloud-config,spring-cloud-build] - Dry Run
#
# (commercial) is shown only when `projects` is empty. With a filter the input is ignored -
# the type is derived from the names - so printing it could contradict the run, and the
# -commercial suffix in the listed names already says which line it is.
run-name: "Post Release - ${{ inputs.release_version }}${{ inputs.projects != '' && format(' [{0}]', inputs.projects) || (inputs.commercial == true && ' (commercial)' || '') }}${{ inputs.dry_run == true && ' - Dry Run' || '' }}"

# Performs the chores that follow a Spring Cloud release train, in order:
#
#   1. setup                   — read the jenkins-releaser-config properties file, validate, filter
#   2. verify-tags             — every project version must have a v<version> tag (hard gate)
#   3. next-snapshot-config    — write the next <train>-snapshot.properties file
#   4. new-milestones          — open a milestone for each new snapshot version
#   5. merge-back-and-update   — merge release/<version> back into .x, bump to snapshots, push
#   6. milestones-and-releases — close the release milestone, publish the GitHub release
#                                (skip_close_milestones leaves the milestones open and still
#                                 publishes the releases)
#   7. website-pr              — open a PR against the website content repo: the release blog
#                                post and the documentation.json versions on the OSS site, new
#                                documentation.json entries on the commercial one
#   8. start-site-pr           — open a PR against start.spring.io bumping the Spring Cloud
#                                version the Initializr offers (OSS trains only)
#   9. summary                 — one report covering everything above
#
# release/<version> only ever exists in the commercial repository - an OSS release is built
# there too, on a branch cut from <major>.<minor>.x-internal - so step 5 merges across
# repositories. The v<version> tag is a different matter: a commercial release tags the
# commercial repo, and an OSS release tags the OSS repo directly. Step 2 therefore looks in a
# different place for each flavour, and nothing here copies a tag between repositories.
#
# For an OSS release the tag lands in the OSS repo pointing at a commit built on the release
# branch in the commercial repo, so until step 5 merges that branch back the tagged commit is
# unreachable history. That is why step 6 still follows step 5: the release notes are generated
# from the tag, and generating them against a commit on no branch is not worth finding out
# about after the fact.
#
# Every mutating step is gated on existence rather than on any attempt to work out whether a
# project was really part of this train. A version carried over from an earlier release already
# has its release and a closed milestone, so those steps become no-ops on their own.
#
# Hotfix releases (a 4-segment release_version, e.g. 2025.1.2.1) run only steps 1, 2, 6 and 7:
# there is no next snapshot train, no new milestone, and no branch to merge a hotfix back into
# (release/<version> is itself the hotfix line). A hotfix is always commercial, so step 7
# documents it on the commercial site and step 8 is skipped.
#
# See README-post-release.md for details.

on:
  workflow_dispatch:
    inputs:
      dry_run:
        description: 'Dry run, if checked nothing is created, committed or pushed, but you can see what would happen'
        required: false
        type: boolean
        default: true
      release_version:
        description: 'Spring Cloud release train version that was just released (e.g. 2025.1.2, 2026.0.0-M1 or 2026.0.0-RC1, or 2025.1.2.1 for a commercial hotfix)'
        required: true
        type: string
      promote_to:
        description: 'Where the train goes next. Leave as none to stay in the current phase (M1 -> M2, RC1 -> RC2). RC moves a milestone train to RC1; GA moves a release candidate train to its final version. Ignored for GA and hotfix releases, which always bump the last segment.'
        required: false
        type: choice
        default: 'none'
        options:
          - none
          - RC
          - GA
      commercial:
        description: 'Was this a commercial release? Ignored when projects is supplied - the -commercial suffix on the project names decides.'
        required: false
        type: boolean
        default: false
      projects:
        description: 'Comma-separated list of projects to run against, including the -commercial suffix where applicable (e.g. spring-cloud-config,spring-cloud-build). Must be all OSS or all commercial. When empty, every project in the properties file is processed.'
        required: false
        type: string
        default: ''
      skip_close_milestones:
        description: 'Skip closing the release milestones. Everything else - including publishing the releases - still runs.'
        required: false
        type: boolean
        default: false
      skip_website_pr:
        description: 'Skip creating a website (for OSS or commercial) PR.'
        required: false
        type: boolean
        default: false
      skip_start_site_pr:
        description: 'Skip the start.spring.io PR that bumps the Spring Cloud version. OSS releases only.'
        required: false
        type: boolean
        default: false
      skip_release_board:
        description: 'Skip rolling the release train GitHub Project board over to the next version. OSS releases only.'
        required: false
        type: boolean
        default: false
      token:
        description: 'GitHub token with write access to all target repos. Falls back to GH_ACTIONS_REPO_TOKEN.'
        required: false
        type: string
        default: ''

permissions:
  contents: read

jobs:
  setup:
    name: Setup
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.parse.outputs.matrix }}
      count: ${{ steps.parse.outputs.count }}
      hotfix: ${{ steps.parse.outputs.hotfix }}
      commercial: ${{ steps.parse.outputs.commercial }}
      release-repo: ${{ steps.parse.outputs.release-repo }}
      props-file: ${{ steps.parse.outputs.props-file }}
      next-version: ${{ steps.parse.outputs.next-version }}
      next-file: ${{ steps.parse.outputs.next-file }}
      next-versions: ${{ steps.parse.outputs.next-versions }}
      snapshot-version: ${{ steps.parse.outputs.snapshot-version }}
      prerelease: ${{ steps.parse.outputs.prerelease }}
      entries: ${{ steps.parse.outputs.entries }}
    steps:
      # Only for .github/scripts/prerelease-rank.js, which owns the M/RC grammar shared
      # with dependabot-scan and dependabot-triage.yml. Every other job here reaches
      # GitHub over the API rather than the working tree, which is why this job had no
      # checkout before.
      - uses: actions/checkout@v4

      - name: Parse releaser config and build matrix
        id: parse
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          RELEASE_VERSION: ${{ inputs.release_version }}
          PROMOTE_TO: ${{ inputs.promote_to }}
          COMMERCIAL: ${{ inputs.commercial }}
          PROJECTS_FILTER: ${{ inputs.projects }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const path = require('path');
          const { execFileSync } = require('child_process');

          // The M/RC grammar and the rules for advancing a train, shared with
          // dependabot-scan and dependabot-triage.yml. This job checks the repository
          // out, so the module sits under the workspace.
          const prerelease = require(path.join(process.env.GITHUB_WORKSPACE,
            '.github', 'scripts', 'prerelease-rank.js'));
          const { releaserConfigFileName } = require(path.join(process.env.GITHUB_WORKSPACE,
            '.github', 'scripts', 'releaser-config-file.js'));
          const { RELEASER_CONFIG_REPO, RELEASER_CONFIG_BRANCH, fetchReleaserConfig } =
            require(path.join(process.env.GITHUB_WORKSPACE,
              '.github', 'scripts', 'releaser-config.js'));

          const releaseVersion = (process.env.RELEASE_VERSION || '').trim();
          const promoteTo = (process.env.PROMOTE_TO || 'none').trim();
          const projectsRaw = (process.env.PROJECTS_FILTER || '').trim();
          const commercialInput = (process.env.COMMERCIAL || 'false') === 'true';

          const fail = (...msg) => { for (const m of msg) console.error(m); process.exit(1); };

          // 3 or 4 numeric segments, optionally carrying an -M<n> or -RC<n> qualifier.
          // split() returns null for anything else - a -SNAPSHOT, a -INTERNAL-SNAPSHOT, a
          // qualifier outside the grammar - which would resolve to a properties file that
          // cannot exist, so it is rejected here rather than as a confusing 404 later.
          const parsed = prerelease.split(releaseVersion);
          if (!parsed) {
            fail(`ERROR: release_version must be 3 or 4 numeric segments with an optional ` +
              `-M<n> or -RC<n> qualifier (e.g. 2025.1.2, 2026.0.0-M1, 2026.0.0-RC1 or ` +
              `2025.1.2.1); got '${releaseVersion}'.`);
          }

          // A milestone or release candidate. The train does not advance during a pre-release
          // cycle - the maintenance branch stays on <train>-SNAPSHOT from M1 all the way to
          // GA - so there is no next snapshot train to write and nothing to advance. The merge
          // back does bring the release's -M<n>/-RC<n> versions onto the branch, though, so
          // after it the branch is put back on <train>-SNAPSHOT from the file that already
          // exists for it. What also happens is the milestones, the releases, the website
          // entry and the board rollover, each named after the next pre-release rather than
          // the next patch.
          const isPrerelease = parsed.kind !== null;

          // A 4-segment version is a commercial hotfix: only the tag gate and the
          // milestone/release step apply to it. Counted on the base so that a qualifier
          // cannot be mistaken for a fourth segment.
          const hotfix = parsed.base.split('.').length === 4;

          if (isPrerelease && hotfix) {
            fail(`ERROR: '${releaseVersion}' is both a 4-segment hotfix version and a ` +
              'pre-release. Commercial hotfixes do not have milestones or release candidates.');
          }

          // ── projects filter ─────────────────────────────────────────────────────────
          // Commerciality comes from the names, not from the commercial input, because the
          // names are what the caller actually typed. That derived value also selects which
          // properties file is read, which is why a mixed list cannot be allowed: one
          // release_version cannot address both the OSS train (2025.1.2) and the commercial
          // one (2025.1.2.1), so a mix would silently resolve every project to a wrong version.
          // Empty entries are dropped, not rejected: a trailing comma has only one sensible
          // reading, and this is how ci-status-report.yml:74 and rollout-deploy-docs.yml:84
          // parse the same input.
          const names = projectsRaw
            ? projectsRaw.split(',').map(s => s.trim()).filter(Boolean)
            : [];

          let commercial = commercialInput;
          if (names.length) {
            const suffixed = names.filter(n => n.endsWith('-commercial'));
            const unsuffixed = names.filter(n => !n.endsWith('-commercial'));
            if (suffixed.length && unsuffixed.length) {
              fail(
                'ERROR: projects mixes commercial and OSS projects.',
                `  commercial: ${suffixed.join(', ')}`,
                `  oss:        ${unsuffixed.join(', ')}`,
                'A run targets one release train, so every project must be the same type.');
            }
            commercial = suffixed.length > 0;
            if (commercial !== commercialInput) {
              console.log(`Note: the commercial input (${commercialInput}) is ignored when ` +
                `projects is supplied; derived commercial=${commercial} from the project names.`);
            }
          }

          // Where the config lives, and the name of the file, both from the shared module -
          // it owns that choice for every caller. `commercial` still decides everything else
          // here: which project repos are acted on, whether release notes are sanitized, and
          // the OSS tag fallback.
          const releaseRepo = RELEASER_CONFIG_REPO;
          const propsFile = releaserConfigFileName(releaseVersion);

          // ── read the properties file ────────────────────────────────────────────────
          console.log(`Reading ${propsFile} from ${releaseRepo}@${RELEASER_CONFIG_BRANCH}...`);
          let entries;
          try {
            entries = fetchReleaserConfig(releaseVersion).entries;
          } catch (err) {
            fail(`ERROR: ${err.message}.`,
              'Check that release_version matches a properties file on that branch, and that the',
              'token has read access to the repository.');
          }
          console.log(`Found ${entries.length} version entries.`);

          // spring-boot and spring-vault live in the properties file but are not Spring Cloud
          // repositories, so they have no tag, milestone or release of ours. They are still bumped
          // in the snapshot file.
          const NON_REPO_KEYS = new Set(['spring-boot', 'spring-vault']);

          let wanted = null;
          if (names.length) {
            wanted = new Set(names.map(n => n.replace(/-commercial$/, '')));
            const known = new Set(entries.map(e => e.key));
            const unknown = [...wanted].filter(k => !known.has(k));
            if (unknown.length) {
              fail(`ERROR: not found in ${propsFile}: ${unknown.join(', ')}`,
                `Known projects: ${[...known].sort().join(', ')}`);
            }
            const nonRepo = [...wanted].filter(k => NON_REPO_KEYS.has(k));
            if (nonRepo.length) {
              fail(`ERROR: ${nonRepo.join(', ')} is not a Spring Cloud project repository ` +
                'and cannot be targeted directly.');
            }
          }

          const matrix = entries
            .filter(e => !NON_REPO_KEYS.has(e.key))
            .filter(e => !wanted || wanted.has(e.key))
            .map(e => ({
              project: e.key,
              repo: commercial ? `spring-cloud/${e.key}-commercial` : `spring-cloud/${e.key}`,
              ossRepo: `spring-cloud/${e.key}`,
              // Carried on every entry, including OSS runs, because that is where the release
              // branch and the tag always live - see verify-tags and merge-back-and-update.
              // On a commercial run this is the same value as repo.
              commercialRepo: `spring-cloud/${e.key}-commercial`,
              version: e.version,
              tag: `v${e.version}`,
            }))
            .sort((a, b) => a.project.localeCompare(b.project));

          // ── where the train goes next ───────────────────────────────────────────────
          // Two different things, and only the first exists on a pre-release run:
          //
          //   nextVersion  - the next release's train version. Names the new milestones and
          //                  the new project board. Always computed (except for a hotfix).
          //   nextFile     - the next <train>-snapshot.properties file. GA only: a
          //                  pre-release cycle does not move the train off its snapshot, so
          //                  there is no new file to write.
          //
          // And one that exists only on a pre-release run:
          //
          //   snapshotVersion - the train's current <base>-SNAPSHOT. The merge back brings
          //                  the release's -M<n>/-RC<n> versions onto the maintenance branch,
          //                  and this is the file that puts it back on its snapshot.
          //
          // prerelease.next() throws on a transition that cannot be meant - a milestone
          // promoted straight to GA, a release candidate promoted to a release candidate -
          // rather than returning a version that would go on to name milestones and boards.
          let nextVersion = '';
          let nextFile = '';
          let snapshotVersion = '';
          const nextVersions = {};
          if (!hotfix) {
            try {
              nextVersion = prerelease.next(releaseVersion, promoteTo);
            } catch (err) {
              fail(`ERROR: ${err.message}`);
            }

            if (isPrerelease) {
              // Each project advances the same way the train does, from its own version:
              // spring-cloud-config 5.1.0-M1 -> 5.1.0-M2. Derived per entry rather than read
              // from a snapshot file, because on this path there is no snapshot file to
              // read - next-snapshot-config does not run.
              //
              // Only entries that are themselves pre-releases are advanced. An entry sitting
              // at a GA version during a pre-release train is either spring-boot or a module
              // pinned to a released version, and in neither case does the next milestone of
              // this train imply a next version of it - advancing spring-boot 4.0.0 to 4.0.1
              // would invent a Spring Boot release. Those keys are simply absent from the
              // map, and the jobs that read it skip a project with no entry.
              const unadvanceable = [];
              const notAdvanced = [];
              for (const e of entries) {
                if (NON_REPO_KEYS.has(e.key) || !prerelease.isPrerelease(e.version)) {
                  notAdvanced.push(`${e.key}=${e.version}`);
                  continue;
                }
                try {
                  nextVersions[e.key] = prerelease.next(e.version, promoteTo);
                } catch (err) {
                  unadvanceable.push(`  ${e.key}=${e.version}: ${err.message}`);
                }
              }
              if (unadvanceable.length) {
                fail(`ERROR: ${propsFile} holds versions that cannot be advanced to the ` +
                  'next pre-release:', ...unadvanceable);
              }
              if (!Object.keys(nextVersions).length) {
                fail(`ERROR: no entry in ${propsFile} is a pre-release version, but ` +
                  `release_version '${releaseVersion}' is one. Check that release_version ` +
                  'matches the properties file that was actually released.');
              }
              if (notAdvanced.length) {
                console.log(`Not advanced (not a pre-release): ${notAdvanced.join(', ')}`);
              }

              // Checked here rather than left to the bump step to discover: without this file
              // every merge back would land and then have nothing to restore from, leaving the
              // branches on the pre-release versions - which is the state this step exists to
              // prevent. Failing before anything has run is cheaper than sixteen half-done legs.
              snapshotVersion = `${parsed.base}-SNAPSHOT`;
              try {
                fetchReleaserConfig(snapshotVersion);
              } catch (err) {
                fail(`ERROR: ${releaserConfigFileName(snapshotVersion)} could not be read: ` +
                  `${err.message}.`,
                  'A pre-release run puts each maintenance branch back on the train\'s snapshot ' +
                  'versions after the merge back, and that file is where they come from.');
              }
            } else {
              // GA: next-snapshot-config writes the new file and publishes the per-project
              // versions, so nothing is derived here. Named through the shared rule with the
              // qualifier spelled out rather than by pasting '-snapshot.properties' on the
              // end, so the snapshot file and the release file are built the same way.
              nextFile = releaserConfigFileName(`${nextVersion}-SNAPSHOT`);
            }
          }

          console.log('');
          console.log(`commercial:      ${commercial}`);
          console.log(`hotfix:          ${hotfix}`);
          console.log(`pre-release:     ${isPrerelease}${isPrerelease ? ` (${parsed.kind}${parsed.num})` : ''}`);
          console.log(`promote_to:      ${promoteTo}`);
          console.log(`release repo:    ${releaseRepo}`);
          console.log(`properties file: ${propsFile}`);
          if (!hotfix) console.log(`next release:    ${nextVersion}`);
          if (!hotfix && !isPrerelease) console.log(`next snapshot:   ${nextFile}`);
          if (isPrerelease) console.log(`snapshot version: ${snapshotVersion}`);
          if (isPrerelease) {
            console.log('');
            console.log('This is a pre-release, so the train stays on its current snapshot:');
            console.log('  - no new <train>-snapshot.properties is written');
            console.log(`  - the release branch is merged back, then the branch is put back on ` +
              `${snapshotVersion}`);
            console.log('  - milestones and the board roll over to ' + nextVersion);
          }
          console.log('');
          console.log(`Projects to process: ${matrix.length}`);
          for (const e of matrix) console.log(`  ${e.repo} @ ${e.tag}`);

          const out = process.env.GITHUB_OUTPUT;
          fs.appendFileSync(out, `matrix=${JSON.stringify({ include: matrix })}\n`);
          fs.appendFileSync(out, `count=${matrix.length}\n`);
          fs.appendFileSync(out, `hotfix=${hotfix}\n`);
          fs.appendFileSync(out, `commercial=${commercial}\n`);
          fs.appendFileSync(out, `release-repo=${releaseRepo}\n`);
          fs.appendFileSync(out, `props-file=${propsFile}\n`);
          fs.appendFileSync(out, `next-version=${nextVersion}\n`);
          fs.appendFileSync(out, `next-file=${nextFile}\n`);
          fs.appendFileSync(out, `next-versions=${JSON.stringify(nextVersions)}\n`);
          fs.appendFileSync(out, `snapshot-version=${snapshotVersion}\n`);
          fs.appendFileSync(out, `prerelease=${isPrerelease}\n`);
          fs.appendFileSync(out, `entries=${JSON.stringify(entries)}\n`);
          JSEOF

  # ── Hard gate ────────────────────────────────────────────────────────────────────────
  # One job rather than a matrix so an incomplete release produces a single consolidated
  # failure naming every missing tag, instead of N separately-red matrix legs.
  verify-tags:
    name: Verify Tags
    needs: setup
    if: needs.setup.outputs.count != '0'
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.verify.outputs.matrix }}
    steps:
      - name: Verify a tag exists for every project version
        id: verify
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          MATRIX: ${{ needs.setup.outputs.matrix }}
          COMMERCIAL: ${{ needs.setup.outputs.commercial }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const { execFileSync } = require('child_process');

          const entries = JSON.parse(process.env.MATRIX).include;
          const commercial = process.env.COMMERCIAL === 'true';

          // matching-refs returns an array, so an exact comparison is required: a plain
          // git/refs/tags/v5.0.2 lookup also prefix-matches v5.0.20.
          const tagExists = (repo, tag) => {
            try {
              const refs = execFileSync('gh', ['api',
                `repos/${repo}/git/matching-refs/tags/${tag}`, '--jq', '.[].ref'],
                { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
              return refs.split('\n').map(r => r.trim()).includes(`refs/tags/${tag}`);
            } catch (err) {
              return false;
            }
          };

          const resolved = [];
          const missing = [];

          // Where a tag lives depends on the flavour, so the two are checked separately:
          // a commercial release tags the commercial repo, and an OSS release tags the OSS
          // repo directly, even though it was built on a branch in the commercial one.
          for (const e of entries) {
            if (commercial) {
              if (tagExists(e.commercialRepo, e.tag)) {
                console.log(`✓ ${e.commercialRepo} ${e.tag}`);
                resolved.push({ ...e, resolvedIn: 'commercial' });
                continue;
              }

              // A commercial project with no tag of its own has had no commercial release since
              // the last OSS one - its properties entry carries the plain OSS version (e.g.
              // spring-cloud-bus=5.0.2 in 2025_1_2_1.properties). The OSS tag satisfies the
              // gate, but there is nothing in the commercial repo to attach a release to.
              if (tagExists(e.ossRepo, e.tag)) {
                console.log(`✓ ${e.ossRepo} ${e.tag} (no commercial tag - OSS fallback)`);
                resolved.push({ ...e, resolvedIn: 'oss-fallback' });
                continue;
              }
            } else {
              // The OSS repo, and only the OSS repo. The release pushes the OSS tag straight
              // there - it is never created in the commercial repo - so a tag missing here is
              // a release that did not happen, not one that has yet to be copied over.
              //
              // The commit it points at is another matter: the release is built on
              // release/<version> in the commercial repo, so the tagged commit arrives in the
              // OSS repo as unreachable history and stays that way until the merge back puts
              // it on the maintenance branch. The tag existing says nothing about that, which
              // is why merge-back-and-update still runs before anything is published.
              if (tagExists(e.ossRepo, e.tag)) {
                console.log(`✓ ${e.ossRepo} ${e.tag}`);
                resolved.push({ ...e, resolvedIn: 'oss' });
                continue;
              }
            }

            console.log(`✗ ${e.tag} - MISSING`);
            missing.push(e);
          }

          fs.appendFileSync(process.env.GITHUB_OUTPUT,
            `matrix=${JSON.stringify({ include: resolved })}\n`);

          if (missing.length) {
            console.error('');
            console.error(`ERROR: ${missing.length} tag(s) do not exist:`);
            for (const e of missing) {
              console.error(`  ${e.tag} (${e.project}) - not found in ` +
                (commercial ? `${e.commercialRepo} or ${e.ossRepo}` : e.ossRepo));
            }
            console.error('');
            console.error('The release is not complete. Nothing else has been touched.');
            process.exit(1);
          }

          console.log('');
          console.log(`All ${resolved.length} tags verified.`);
          JSEOF

  next-snapshot-config:
    name: Next Snapshot Config
    needs: [setup, verify-tags]
    # A pre-release does not advance the train: 5.1.x stays on 5.1.0-SNAPSHOT from M1 all
    # the way to GA, so there is no next snapshot file to write. Every job that consumes
    # this one's versions reads setup.outputs.next-versions instead on that path.
    if: needs.setup.outputs.hotfix != 'true' && needs.setup.outputs.prerelease != 'true'
    runs-on: ubuntu-latest
    outputs:
      status: ${{ steps.write.outputs.status }}
      available: ${{ steps.write.outputs.available }}
      versions: ${{ steps.write.outputs.versions }}
    steps:
      # Only so the script below can require .github/scripts/.
      - uses: actions/checkout@v4

      - name: Write the next snapshot properties file
        id: write
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          RELEASE_REPO: ${{ needs.setup.outputs.release-repo }}
          PROPS_FILE: ${{ needs.setup.outputs.props-file }}
          NEXT_FILE: ${{ needs.setup.outputs.next-file }}
          NEXT_VERSION: ${{ needs.setup.outputs.next-version }}
          DRY_RUN: ${{ inputs.dry_run }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const path = require('path');
          const { parseReleaserConfig, ENTRY_RE } = require(path.join(
            process.env.GITHUB_WORKSPACE, '.github', 'scripts', 'releaser-config.js'));
          const { execFileSync } = require('child_process');

          const releaseRepo = process.env.RELEASE_REPO;
          const propsFile = process.env.PROPS_FILE;
          const nextFile = process.env.NEXT_FILE;
          const nextVersion = process.env.NEXT_VERSION;
          const dryRun = process.env.DRY_RUN === 'true';
          const BRANCH = 'jenkins-releaser-config';

          const gh = args => execFileSync('gh', args,
            { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
          // Returns {content, sha} - the sha is needed to update an existing file via the
          // Contents API, which rejects a PUT over an existing path without it.
          const readFile = file => {
            try {
              const raw = JSON.parse(gh(['api',
                `repos/${releaseRepo}/contents/${file}?ref=${BRANCH}`]));
              return {
                content: Buffer.from((raw.content || '').replace(/\s/g, ''), 'base64').toString('utf8'),
                sha: raw.sha,
              };
            } catch (err) { return null; }
          };

          // The shared parse, folded into the {key: version} map this job works in.
          const parse = text => {
            const map = {};
            for (const e of parseReleaserConfig(text)) map[e.key] = e.version;
            return map;
          };

          // The correct contents are always computed from the release file and written, whether
          // or not the target already exists. An existing snapshot file may have been seeded by
          // hand or by an earlier run against a different release, so trusting it would leave
          // every downstream project bumped to the wrong versions.
          const source = readFile(propsFile);
          if (source === null) {
            console.error(`ERROR: could not re-read ${propsFile}.`);
            process.exit(1);
          }

          const bump = v => {
            const parts = v.split('.');
            parts[parts.length - 1] = String(Number(parts[parts.length - 1]) + 1);
            return parts.join('.');
          };

          // Rewritten line by line so ordering and any non-fixed-versions lines survive. Every
          // entry is bumped, including spring-boot, and including projects this run is not
          // otherwise touching - the file is train-wide and update-project-versions needs the
          // complete map to update each project's dependency versions.
          const content = source.content.split('\n').map(line => {
            const m = line.match(ENTRY_RE);
            if (!m) return line;
            return `releaser.fixed-versions[${m[1]}]=${bump(m[2].trim())}-SNAPSHOT`;
          }).join('\n');

          const existing = readFile(nextFile);

          console.log(`Target ${nextFile}:`);
          console.log('---');
          console.log(content);
          console.log('---');

          let status;
          if (existing && existing.content === content) {
            // Byte-identical, so there is nothing to commit. Skipping the PUT avoids an empty
            // commit on the branch, the same way sync-deploy-docs-workflow does.
            console.log(`${nextFile} already has exactly these versions - nothing to change.`);
            status = 'unchanged';
          } else if (dryRun) {
            if (existing) {
              console.log('[dry run] would UPDATE the existing file. Current contents:');
              console.log('---');
              console.log(existing.content);
              console.log('---');
            }
            console.log('[dry run] not committing.');
            status = existing ? 'would-update' : 'would-create';
          } else {
            const payload = {
              message: existing
                ? `Updating ${nextVersion} snapshot versions`
                : `Adding ${nextVersion} snapshot versions`,
              content: Buffer.from(content, 'utf8').toString('base64'),
              branch: BRANCH,
            };
            // The blob sha is what tells the Contents API to replace rather than create, and it
            // also makes the write fail rather than clobber if someone else changed the file
            // between the read above and this PUT.
            if (existing) payload.sha = existing.sha;
            fs.writeFileSync('payload.json', JSON.stringify(payload));
            gh(['api', `repos/${releaseRepo}/contents/${nextFile}`,
              '--method', 'PUT', '--input', 'payload.json']);
            console.log(`${existing ? 'Updated' : 'Committed'} ${nextFile} on ` +
              `${releaseRepo}@${BRANCH}.`);
            status = existing ? 'updated' : 'created';
          }

          // update-project-versions resolves versions over raw.githubusercontent.com, which is
          // CDN-cached, so a file committed seconds ago may not be served yet. Wait for it - but
          // only when this job actually wrote something.
          let available = status === 'unchanged';
          if (status === 'created' || status === 'updated') {
            const url = `https://raw.githubusercontent.com/${releaseRepo}/${BRANCH}/${nextFile}`;
            console.log(`Waiting for ${url} to serve these contents...`);
            for (let attempt = 1; attempt <= 30; attempt++) {
              let served = null;
              try {
                // The commercial release repo is private, so raw needs the same bearer token
                // update-project-versions sends.
                served = execFileSync('curl', ['-s', '-f',
                  '-H', 'Cache-Control: no-cache',
                  '-H', `Authorization: Bearer ${process.env.GH_TOKEN}`, url],
                  { encoding: 'utf8' });
              } catch (err) { /* not served yet */ }

              // Compares contents rather than just the status code. An updated file returns 200
              // immediately while the CDN is still serving the previous version, so a status
              // check would wave through exactly the stale read this wait exists to prevent.
              if (served !== null && served.trim() === content.trim()) {
                console.log(`Serving the new contents after ${attempt} attempt(s).`);
                available = true;
                break;
              }
              console.log(`Attempt ${attempt}: ` +
                (served === null ? 'not served yet' : 'still serving older contents') +
                ', waiting 10s...');
              execFileSync('sleep', ['10']);
            }
            if (!available) {
              console.log('WARNING: the raw URL never served the new contents. Version updates ' +
                'will be skipped rather than applied from a stale file - re-run this workflow ' +
                'with the same inputs once the CDN catches up.');
            }
          }

          const out = process.env.GITHUB_OUTPUT;
          fs.appendFileSync(out, `status=${status}\n`);
          fs.appendFileSync(out, `available=${available}\n`);
          fs.appendFileSync(out, `versions=${JSON.stringify(parse(content))}\n`);
          fs.writeFileSync('result-snapshot-config.json', JSON.stringify({
            phase: 'next-snapshot-config',
            releaseRepo, nextFile, nextVersion, status, available,
          }));
          JSEOF

      - name: Upload result
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: result-snapshot-config
          path: result-snapshot-config.json
          if-no-files-found: ignore

  new-milestones:
    name: "New Milestone — ${{ matrix.project }}"
    needs: [setup, verify-tags, next-snapshot-config]
    # next-snapshot-config is skipped on a pre-release run, which would otherwise skip
    # this job with it. verify-tags is still a hard gate either way.
    if: |
      !cancelled() &&
      needs.verify-tags.result == 'success' &&
      (needs.next-snapshot-config.result == 'success' ||
       needs.setup.outputs.prerelease == 'true')
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      max-parallel: 8
      matrix: ${{ fromJson(needs.verify-tags.outputs.matrix) }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # Done as a separate read-only step so a dry run can report what would happen. The
      # create-milestone action performs the same check itself, so this is also what keeps the
      # non-dry-run path idempotent for versions carried over from an earlier train.
      - name: Resolve the new milestone title
        id: resolve
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          PROJECT: ${{ matrix.project }}
          REPO: ${{ matrix.repo }}
          VERSIONS: ${{ needs.setup.outputs.prerelease == 'true'
            && needs.setup.outputs.next-versions
            || needs.next-snapshot-config.outputs.versions }}
        run: |
          set -euo pipefail

          # The map holds the next snapshot version on a GA run (5.1.1-SNAPSHOT) and the
          # next pre-release on a milestone or RC run (5.1.0-M2), so the -SNAPSHOT strip is
          # a no-op on the latter. Either way the result is the milestone title.
          #
          # A project missing from the map gets no milestone. On a pre-release run that is
          # how a module pinned to a GA version is skipped: there is no next pre-release of
          # it to open a milestone for.
          TITLE=$(echo "$VERSIONS" | jq -r --arg k "$PROJECT" '.[$k] // ""' | sed 's/-SNAPSHOT$//')
          if [[ -z "$TITLE" ]]; then
            echo "No next version for ${PROJECT} - nothing to create."
            echo "title=" >> "$GITHUB_OUTPUT"
            echo "exists=unknown" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          echo "New milestone title: ${TITLE}"
          echo "title=${TITLE}" >> "$GITHUB_OUTPUT"

          # --paginate, and not optional: several of these repos are past a hundred
          # milestones - spring-cloud-release has 167 - and the list comes back sorted by
          # due date ascending, so it is precisely the newest ones that fall off page one.
          # `jq -s add` folds the pages gh emits back into one array; piped through jq
          # rather than gh's --jq because that takes no --arg (and no --slurp either).
          NUMBER=$(gh api --paginate "repos/${REPO}/milestones?state=all&per_page=100" 2>/dev/null \
            | jq -r -s --arg t "$TITLE" 'add | .[] | select(.title == $t) | .number' || echo "")
          if [[ -n "$NUMBER" ]]; then
            echo "Milestone '${TITLE}' already exists (#${NUMBER})."
            echo "exists=true" >> "$GITHUB_OUTPUT"
          else
            echo "exists=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Create milestone
        if: steps.resolve.outputs.exists == 'false' && inputs.dry_run != true
        uses: ./.github/actions/create-milestone
        with:
          repo: ${{ matrix.repo }}
          version: ${{ steps.resolve.outputs.title }}
          token: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}

      - name: Record result
        if: always()
        id: record
        env:
          PROJECT: ${{ matrix.project }}
          REPO: ${{ matrix.repo }}
          TITLE: ${{ steps.resolve.outputs.title }}
          EXISTS: ${{ steps.resolve.outputs.exists }}
          OUTCOME: ${{ steps.resolve.outcome }}
          DRY_RUN: ${{ inputs.dry_run }}
        run: |
          set -euo pipefail

          SAFE="${REPO//\//-}"
          echo "safe-name=${SAFE}" >> "$GITHUB_OUTPUT"

          if [[ "$OUTCOME" != "success" ]]; then
            STATUS="error"
          elif [[ -z "${TITLE:-}" ]]; then
            STATUS="no-version"
          elif [[ "$EXISTS" == "true" ]]; then
            STATUS="already-exists"
          elif [[ "$DRY_RUN" == "true" ]]; then
            STATUS="would-create"
          else
            STATUS="created"
          fi

          jq -n \
            --arg phase "new-milestones" \
            --arg project "$PROJECT" \
            --arg repo "$REPO" \
            --arg title "${TITLE:-}" \
            --arg status "$STATUS" \
            '{phase: $phase, project: $project, repo: $repo, title: $title, status: $status}' \
            > "result-newmilestone-${SAFE}.json"

      - name: Upload result
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: result-newmilestone-${{ steps.record.outputs.safe-name || matrix.project }}
          path: result-newmilestone-*.json
          if-no-files-found: ignore

  # ── Merge back, bump versions, nudge Dependabot ──────────────────────────────────────
  # All of these share one matrix leg per project, and one clone. That is required rather
  # than tidy: a project whose release branch will not merge cleanly has to skip everything
  # that follows, and per-step conditionals are the only way to express that.
  merge-back-and-update:
    name: "Merge Back + Bump — ${{ matrix.project }}"
    needs: [setup, verify-tags, next-snapshot-config]
    # next-snapshot-config is skipped on a pre-release run, which would otherwise skip
    # this job with it. verify-tags is still a hard gate either way.
    if: |
      !cancelled() &&
      needs.verify-tags.result == 'success' &&
      (needs.next-snapshot-config.result == 'success' ||
       needs.setup.outputs.prerelease == 'true')
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      max-parallel: 8
      matrix: ${{ fromJson(needs.verify-tags.outputs.matrix) }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          # Do not persist this repository's GITHUB_TOKEN as a git extraheader; it would
          # override the credentials baked into the target repo's remote URL below.
          persist-credentials: false

      # ── 5a. resolve the branch to work on ─────────────────────────────────────────────
      # Two steps and a normalizer rather than one script: the .x-then-main resolution is
      # shared with update-versions.yml and create-oss-release-branch.yml and lives in the
      # resolve-release-branch action. What stays here is only what is specific to this
      # workflow - reading this project's version out of the versions map, and reporting a
      # project that is not in the map at all as no-version rather than as a bad version.
      - name: Read this project's next version
        id: version
        env:
          PROJECT: ${{ matrix.project }}
          VERSIONS: ${{ needs.setup.outputs.prerelease == 'true'
            && needs.setup.outputs.next-versions
            || needs.next-snapshot-config.outputs.versions }}
        run: |
          set -euo pipefail
          VERSION=$(echo "$VERSIONS" | jq -r --arg k "$PROJECT" '.[$k] // ""')
          if [[ -z "$VERSION" ]]; then
            echo "No version for ${PROJECT}."
          else
            echo "Version for ${PROJECT}: ${VERSION}"
          fi
          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"

      - name: Resolve target branch
        id: resolve
        if: steps.version.outputs.version != ''
        uses: ./.github/actions/resolve-release-branch
        with:
          repo: ${{ matrix.repo }}
          version: ${{ steps.version.outputs.version }}
          commercial: ${{ needs.setup.outputs.commercial }}
          token: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}

      # Keeps the id every later step already reads, so the resolution moving into an action
      # is invisible to the rest of the job.
      - name: Branch resolution result
        id: branch
        env:
          VERSION: ${{ steps.version.outputs.version }}
          RESOLVED: ${{ steps.resolve.outputs.branch }}
          STATUS: ${{ steps.resolve.outputs.status }}
        run: |
          set -euo pipefail
          if [[ -z "$VERSION" ]]; then
            echo "status=no-version" >> "$GITHUB_OUTPUT"
            echo "branch=" >> "$GITHUB_OUTPUT"
          else
            echo "status=${STATUS}" >> "$GITHUB_OUTPUT"
            echo "branch=${RESOLVED}" >> "$GITHUB_OUTPUT"
          fi

      # ── 5a'. is the branch frozen? ───────────────────────────────────────────────────
      # lock-unlock-branches.yml's Release Freeze ruleset has no bypass actors, so it rejects
      # this workflow's push as well - and forgetting the unlock used to surface only as every
      # leg failing on push, partway through a real run. The rules endpoint returns every
      # ruleset rule that applies to the branch (repo-level and org-level alike); an `update`
      # rule is the one that rejects a push. Classic branch protection is not covered, which
      # matches what lock-unlock-branches manages.
      #
      # A dry run only warns, and still merges in the runner's clone so a conflict shows up
      # alongside the lock. A real run skips the merge (and so everything after it) and
      # reports the branch as frozen.
      #
      # Never a blocker on its own failure: an API error reports `unknown` and the merge goes
      # ahead, since the push would still report a real lock.
      - name: Check the branch is not frozen
        id: lock
        if: steps.branch.outputs.status == 'ok'
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          REPO: ${{ matrix.repo }}
          BRANCH: ${{ steps.branch.outputs.branch }}
          DRY_RUN: ${{ inputs.dry_run }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const { execFileSync } = require('child_process');

          const repo = process.env.REPO;
          const branch = process.env.BRANCH;
          const dryRun = (process.env.DRY_RUN || 'false') === 'true';

          const out = process.env.GITHUB_OUTPUT;
          const finish = (status, lockedBy) => {
            fs.appendFileSync(out, `status=${status}\n`);
            fs.appendFileSync(out, `locked-by=${lockedBy || ''}\n`);
            process.exit(0);
          };

          const gh = args => {
            try {
              return JSON.parse(execFileSync('gh', args,
                { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }));
            } catch (err) {
              console.log(`  gh failed: ${(err.stderr || err.message || '').split('\n')[0]}`);
              return null;
            }
          };

          // --slurp so a paginated response comes back as one array of pages.
          const pages = gh(['api', `repos/${repo}/rules/branches/${branch}`, '--paginate', '--slurp']);
          if (!pages) {
            console.log(`::notice::Could not read the rules on ${repo}@${branch} - carrying on; ` +
              'a frozen branch would still show up as a rejected push.');
            finish('unknown');
          }

          const updates = pages.flat().filter(r => r.type === 'update');
          if (!updates.length) {
            console.log(`${repo}@${branch} is not frozen.`);
            finish('unlocked');
          }

          // Named where possible, so the summary can say whether this is the Release Freeze
          // (lifted by lock-unlock-branches) or something else entirely.
          const names = [...new Set(updates.map(r => {
            if (r.ruleset_source_type === 'Repository') {
              const rs = gh(['api', `repos/${repo}/rulesets/${r.ruleset_id}`]);
              if (rs && rs.name) return rs.name;
            }
            return `ruleset #${r.ruleset_id} (${r.ruleset_source || r.ruleset_source_type})`;
          }))];

          const msg = `${repo}@${branch} is frozen by ${names.join(', ')} - ` +
            (dryRun ? 'a real run could not push to it. Unlock it before running for real.'
                    : 'skipping the merge back. Unlock it, then re-run for this project.');
          console.log(`::${dryRun ? 'warning' : 'error'}::${msg}`);
          finish('locked', names.join(', '));
          JSEOF

      # ── 5b. merge release/<version> back into the .x branch ──────────────────────────
      - name: Merge release branch back
        id: merge
        if: |
          steps.branch.outputs.status == 'ok' &&
          (inputs.dry_run == true || steps.lock.outputs.status != 'locked')
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          REPO: ${{ matrix.repo }}
          COMMERCIAL_REPO: ${{ matrix.commercialRepo }}
          VERSION: ${{ matrix.version }}
          BRANCH: ${{ steps.branch.outputs.branch }}
        run: |
          set -uo pipefail

          RELEASE_BRANCH="release/${VERSION}"
          REMOTE="https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git"
          # The release branch always lives in the commercial repo, for OSS releases too: they
          # are built on release/<version>, cut from the -internal branch in <project>-commercial
          # (create-oss-release-branch.yml), and merged back here afterwards. On a commercial run
          # this is the same repository as REMOTE, so one code path covers both.
          COMMERCIAL_REMOTE="https://x-access-token:${GH_TOKEN}@github.com/${COMMERCIAL_REPO}.git"

          # Sixteen legs clone a private repo apiece, at once, every run. github.com fails
          # often enough at that rate to be worth retrying rather than reporting: an HTTP 401
          # or a 5xx during ref advertisement is a blip, not an answer. Retried here, and every
          # remote read below is routed through this.
          #
          # Note that the step runs under `bash -e` whatever this script sets, so an unguarded
          # git failure aborts it - and a step that aborts records no status at all, which the
          # summary can only report as "skipped". Anything that can fail on the network has to
          # end in an explicit status, or it is invisible in the report.
          ATTEMPTS=3
          retry() {
            local what="$1"; shift
            local attempt
            for attempt in $(seq 1 $ATTEMPTS); do
              if "$@"; then
                return 0
              fi
              if [[ $attempt -lt $ATTEMPTS ]]; then
                echo "${what}: failed, attempt ${attempt}/${ATTEMPTS} - waiting $((attempt * 10))s..."
                sleep $((attempt * 10))
              fi
            done
            echo "::error::${what}: failed ${ATTEMPTS} times."
            return 1
          }

          # A half-written clone would make the next attempt fail on the directory rather than
          # on the network, so each attempt starts from nothing.
          clone_repo() {
            rm -rf project
            git clone --quiet "$REMOTE" --branch "$BRANCH" project
          }

          if ! retry "Cloning ${REPO}@${BRANCH}" clone_repo; then
            echo "status=clone-failed" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          cd project
          git config user.name "Spring Builds"
          git config user.email "svc.spring-builds@broadcom.com"
          git remote add commercial "$COMMERCIAL_REMOTE"

          # --exit-code exits 2 when the remote answered and has no such branch. That is a real
          # answer and the common one; any other non-zero is a transport failure, and reading
          # that as "no release branch" would skip the merge and call the run a success.
          LS_RC=0
          list_release_branch() {
            git ls-remote --exit-code --heads commercial "refs/heads/${RELEASE_BRANCH}" >/dev/null 2>&1
            LS_RC=$?
            [[ $LS_RC -eq 0 || $LS_RC -eq 2 ]]
          }

          if ! retry "Looking for ${RELEASE_BRANCH} in ${COMMERCIAL_REPO}" list_release_branch; then
            echo "status=branch-fetch-failed" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          if [[ $LS_RC -eq 2 ]]; then
            # Expected for a version carried over from an earlier train, for an OSS-fallback
            # entry, and for a release branch that was already merged and deleted.
            echo "No ${RELEASE_BRANCH} branch in ${COMMERCIAL_REPO} - nothing to merge."
            echo "status=no-release-branch" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          fetch_release_branch() {
            git fetch --quiet commercial "refs/heads/${RELEASE_BRANCH}:refs/remotes/commercial/${RELEASE_BRANCH}"
          }

          if ! retry "Fetching ${RELEASE_BRANCH} from ${COMMERCIAL_REPO}" fetch_release_branch; then
            echo "status=branch-fetch-failed" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          if git merge-base --is-ancestor "commercial/${RELEASE_BRANCH}" HEAD; then
            echo "${RELEASE_BRANCH} is already merged into ${BRANCH}."
            echo "status=already-merged" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          # The release branch has its CI and PR workflows deleted on purpose when it is created
          # (see spring-release-train-project-ready), so merging it back would carry that
          # deletion onto the maintenance branch and leave it with no CI. Keep a copy of
          # whatever this branch has, outside the clone so the merge cannot touch it.
          BACKUP=$(mktemp -d)
          SAVED=()
          for f in ci.yml ci.yaml pr.yml pr.yaml; do
            if [[ -f ".github/workflows/${f}" ]]; then
              cp ".github/workflows/${f}" "${BACKUP}/${f}"
              SAVED+=("$f")
              echo "Saved .github/workflows/${f}"
            else
              echo ".github/workflows/${f} not on ${BRANCH} - skipping."
            fi
          done

          AUTO_RESOLVED=()
          if ! git merge --no-edit -m "Merge ${RELEASE_BRANCH} into ${BRANCH}" "commercial/${RELEASE_BRANCH}"; then
            # ls-files --unmerged reads the index stages directly, so it lists modify/delete
            # conflicts as reliably as content conflicts. Read with a loop rather than mapfile,
            # which does not exist in bash 3.2 and so cannot be exercised outside a runner.
            CONFLICTED=()
            while IFS= read -r p; do
              [[ -n "$p" ]] && CONFLICTED+=("$p")
            done < <(git ls-files --unmerged | awk '{print $4}' | sort -u)
            echo "Conflicting paths: ${CONFLICTED[*]:-none}"

            # A conflict on a ci/pr workflow file is the predictable one: the release branch
            # deleted the file and this branch has changed it since, so git cannot decide. The
            # maintenance branch's version is always the one to keep, so resolve it here rather
            # than blocking the project on a merge a human would resolve the same way.
            REMAINING=()
            for p in ${CONFLICTED[@]+"${CONFLICTED[@]}"}; do
              case "$p" in
                .github/workflows/ci.yml|.github/workflows/ci.yaml|.github/workflows/pr.yml|.github/workflows/pr.yaml)
                  # HEAD is still the .x tip mid-merge, so HEAD:<path> is this branch's version.
                  # Absent from HEAD means this branch had deleted it - keep it deleted.
                  if git cat-file -e "HEAD:${p}" 2>/dev/null; then
                    git show "HEAD:${p}" > "$p"
                    git add "$p"
                    echo "Auto-resolved ${p} - kept the ${BRANCH} version."
                  else
                    git rm -f --quiet --ignore-unmatch "$p"
                    echo "Auto-resolved ${p} - not on ${BRANCH}, left deleted."
                  fi
                  AUTO_RESOLVED+=("$p")
                  ;;
                *)
                  REMAINING+=("$p")
                  ;;
              esac
            done

            if [[ ${#REMAINING[@]} -gt 0 ]]; then
              # Anything else needs a human. Abort so the clone is left clean, and stop this
              # project here - the version bump must not be layered on an unresolved merge.
              echo "::error::Cannot merge ${RELEASE_BRANCH} into ${BRANCH} in ${REPO} without conflicts."
              git merge --abort || true
              echo "status=merge-conflict" >> "$GITHUB_OUTPUT"
              echo "conflicts=${REMAINING[*]}" >> "$GITHUB_OUTPUT"
              exit 0
            fi

            git commit --quiet --no-edit
            echo "auto-resolved=${AUTO_RESOLVED[*]:-}" >> "$GITHUB_OUTPUT"
          fi

          echo "Merged ${RELEASE_BRANCH} into ${BRANCH}."

          # Restore only what the merge actually removed. A workflow file the release branch
          # modified rather than deleted is a real change and is left alone.
          RESTORED=()
          if [[ ${#SAVED[@]} -gt 0 ]]; then
            for f in "${SAVED[@]}"; do
              if [[ ! -f ".github/workflows/${f}" ]]; then
                mkdir -p .github/workflows
                cp "${BACKUP}/${f}" ".github/workflows/${f}"
                git add ".github/workflows/${f}"
                RESTORED+=("$f")
                echo "Restored .github/workflows/${f} - the merge removed it."
              fi
            done
          fi

          if [[ ${#RESTORED[@]} -gt 0 ]]; then
            # A separate commit rather than amending the merge, so the log shows plainly that
            # these files came back and why.
            git commit --quiet -m "Restoring ${RESTORED[*]} removed by the ${RELEASE_BRANCH} merge"
            echo "restored=${RESTORED[*]}" >> "$GITHUB_OUTPUT"
          else
            echo "The merge removed no ci/pr workflow files - nothing to restore."
          fi

          echo "status=merged" >> "$GITHUB_OUTPUT"

      # ── 5c. apply the new snapshot versions ──────────────────────────────────────────
      # release-train-version rather than the explicit versions input: only that path applies
      # project-version-substitutions, which is what maps spring-cloud-dependencies-parent to
      # spring-cloud-build, verifierVersion to spring-cloud-contract, and so on.
      - name: Apply new snapshot versions
        id: bump
        # GA: the next train's snapshot, from the file next-snapshot-config just wrote. The
        # available check keeps a dry run honest: nothing was committed, so there is no
        # snapshot file to resolve versions from and this is reported as skipped, not failed.
        #
        # Pre-release: the train's current snapshot, not the next one. The train does not
        # advance between M1 and GA, but the merge above brings the release branch's
        # -M<n>/-RC<n> versions onto the maintenance branch, so it has to be put back on
        # <train>-SNAPSHOT. That file already exists (setup checks it), so unlike GA a dry run
        # can apply it for real and show the diff.
        if: |
          (needs.setup.outputs.prerelease == 'true' ||
           needs.next-snapshot-config.outputs.available == 'true') &&
          (steps.merge.outputs.status == 'merged' ||
           steps.merge.outputs.status == 'already-merged' ||
           steps.merge.outputs.status == 'no-release-branch')
        continue-on-error: true
        uses: ./.github/actions/update-project-versions
        with:
          release-train-version: ${{ needs.setup.outputs.prerelease == 'true'
            && needs.setup.outputs.snapshot-version
            || format('{0}-SNAPSHOT', needs.setup.outputs.next-version) }}
          # Hardcoded true, not the run's commercial flavour. This input does one thing in the
          # action - pick which repo the releaser config is fetched from
          # (update-project-versions/src/index.js:193-194) - and the config now always lives in
          # spring-cloud-release-commercial, including for OSS trains. Passing the derived value
          # would send an OSS run to spring-cloud-release, where the file no longer is.
          commercial: 'true'
          token: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          directory: project

      # ── 5d. one push carrying the merge commit and the version bump ──────────────────
      # Every kind of release that reaches this step now bumps: GA to the next snapshot, a
      # pre-release back to the current one. So the gate is the bump alone - a merge pushed
      # without it would leave the branch on the release's versions, and on a pre-release that
      # is exactly the -M1-left-on-main state this used to produce.
      - name: Commit and push
        id: push
        if: steps.bump.outcome == 'success'
        env:
          REPO: ${{ matrix.repo }}
          BRANCH: ${{ steps.branch.outputs.branch }}
          BUMP_VERSION: ${{ needs.setup.outputs.prerelease == 'true'
            && needs.setup.outputs.snapshot-version
            || format('{0}-SNAPSHOT', needs.setup.outputs.next-version) }}
          DRY_RUN: ${{ inputs.dry_run }}
        run: |
          set -euo pipefail
          cd project

          git add -A
          if git diff --cached --quiet; then
            echo "No version changes to commit."
          else
            # Deliberately no [skip actions] here, unlike most workflows in this repo: the
            # whole point of pushing the snapshot versions is to start CI on them.
            git commit --quiet -m "Updating project versions to ${BUMP_VERSION}"
            echo "Committed the version bump."
          fi

          # Counting commits rather than diffing trees: a merge commit is worth pushing even
          # when it happens to leave the tree identical.
          AHEAD=$(git rev-list --count "origin/${BRANCH}..HEAD")
          if [[ "$AHEAD" == "0" ]]; then
            echo "Nothing to push - ${BRANCH} is already up to date."
            echo "status=nothing-to-push" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          echo "Commits to push:"
          git --no-pager log --oneline "origin/${BRANCH}..HEAD"

          if [[ "$DRY_RUN" == "true" ]]; then
            echo "[dry run] not pushing to ${REPO}@${BRANCH}."
            echo "status=would-push" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          # Merge commit and version bump go up together: one CI run, and a failure anywhere
          # above leaves the branch untouched so the whole leg can simply be re-run.
          git push --quiet origin "HEAD:refs/heads/${BRANCH}"
          echo "Pushed to ${REPO}@${BRANCH}."
          echo "status=pushed" >> "$GITHUB_OUTPUT"

      # ── 5e. ask Dependabot to re-evaluate its open PRs ───────────────────────────────
      # There is no public API to trigger a Dependabot run, so the supported route is the
      # comment command. Dependabot re-runs and closes any PR whose bump the push above
      # already satisfied.
      - name: Recreate Dependabot PRs
        id: dependabot
        if: steps.push.outputs.status == 'pushed'
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          REPO: ${{ matrix.repo }}
          BRANCH: ${{ steps.branch.outputs.branch }}
          ENTRIES: ${{ needs.setup.outputs.entries }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const { execFileSync } = require('child_process');

          const repo = process.env.REPO;
          const branch = process.env.BRANCH;
          const entries = JSON.parse(process.env.ENTRIES);

          let prs = [];
          try {
            prs = JSON.parse(execFileSync('gh', ['pr', 'list',
              '--repo', repo, '--author', 'app/dependabot', '--base', branch,
              '--state', 'open', '--limit', '100', '--json', 'number,title'],
              { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }));
          } catch (err) {
            console.log(`Could not list Dependabot PRs for ${repo}@${branch}: ${err.message}`);
          }

          console.log(`${prs.length} open Dependabot PR(s) against ${repo}@${branch}.`);

          // Only nudge PRs that actually concern something this release moved - matched on both
          // the project name and one of the released versions, so an unrelated bump is left be.
          const matched = prs.filter(pr =>
            entries.some(e => pr.title.includes(e.key) && pr.title.includes(e.version)));

          let commented = 0;
          for (const pr of matched) {
            console.log(`#${pr.number}: ${pr.title}`);
            try {
              execFileSync('gh', ['pr', 'comment', String(pr.number),
                '--repo', repo, '--body', '@dependabot recreate'],
                { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
              commented++;
            } catch (err) {
              console.log(`  could not comment: ${err.message}`);
            }
          }

          console.log(`Commented on ${commented} of ${matched.length} matching PR(s).`);
          const out = process.env.GITHUB_OUTPUT;
          fs.appendFileSync(out, `open=${prs.length}\n`);
          fs.appendFileSync(out, `matched=${matched.length}\n`);
          fs.appendFileSync(out, `commented=${commented}\n`);
          JSEOF

      - name: Record result
        if: always()
        id: record
        env:
          PROJECT: ${{ matrix.project }}
          REPO: ${{ matrix.repo }}
          VERSION: ${{ matrix.version }}
          BRANCH: ${{ steps.branch.outputs.branch }}
          BRANCH_STATUS: ${{ steps.branch.outputs.status }}
          MERGE_STATUS: ${{ steps.merge.outputs.status }}
          MERGE_RESTORED: ${{ steps.merge.outputs.restored }}
          MERGE_AUTO_RESOLVED: ${{ steps.merge.outputs.auto-resolved }}
          MERGE_CONFLICTS: ${{ steps.merge.outputs.conflicts }}
          LOCK_STATUS: ${{ steps.lock.outputs.status }}
          LOCKED_BY: ${{ steps.lock.outputs.locked-by }}
          BUMP_OUTCOME: ${{ steps.bump.outcome }}
          PUSH_STATUS: ${{ steps.push.outputs.status }}
          RESOLVED_IN: ${{ matrix.resolvedIn }}
          DEPENDABOT_OPEN: ${{ steps.dependabot.outputs.open }}
          DEPENDABOT_MATCHED: ${{ steps.dependabot.outputs.matched }}
          DEPENDABOT_COMMENTED: ${{ steps.dependabot.outputs.commented }}
        run: |
          set -euo pipefail

          SAFE="${REPO//\//-}"
          echo "safe-name=${SAFE}" >> "$GITHUB_OUTPUT"

          # A merge skipped because the branch is frozen is reported as such rather than as
          # "skipped", which reads like nothing was needed. The release gate keys off this too:
          # branch-locked is not a landed merge, so the release is held back with the reason.
          if [[ -z "${MERGE_STATUS:-}" && "${LOCK_STATUS:-}" == "locked" ]]; then
            MERGE_STATUS="branch-locked"
          fi

          jq -n \
            --arg phase "merge-back-and-update" \
            --arg project "$PROJECT" \
            --arg repo "$REPO" \
            --arg version "$VERSION" \
            --arg branch "${BRANCH:-}" \
            --arg branchStatus "${BRANCH_STATUS:-skipped}" \
            --arg mergeStatus "${MERGE_STATUS:-skipped}" \
            --arg restored "${MERGE_RESTORED:-}" \
            --arg autoResolved "${MERGE_AUTO_RESOLVED:-}" \
            --arg conflicts "${MERGE_CONFLICTS:-}" \
            --arg lockStatus "${LOCK_STATUS:-}" \
            --arg lockedBy "${LOCKED_BY:-}" \
            --arg bumpOutcome "${BUMP_OUTCOME:-skipped}" \
            --arg pushStatus "${PUSH_STATUS:-skipped}" \
            --arg resolvedIn "${RESOLVED_IN:-}" \
            --arg dependabotOpen "${DEPENDABOT_OPEN:-}" \
            --arg dependabotMatched "${DEPENDABOT_MATCHED:-}" \
            --arg dependabotCommented "${DEPENDABOT_COMMENTED:-}" \
            '{phase: $phase, project: $project, repo: $repo, version: $version,
              branch: $branch, branchStatus: $branchStatus, mergeStatus: $mergeStatus,
              restored: $restored, autoResolved: $autoResolved, conflicts: $conflicts,
              lockStatus: $lockStatus, lockedBy: $lockedBy,
              bumpOutcome: $bumpOutcome, pushStatus: $pushStatus,
              resolvedIn: $resolvedIn,
              dependabotOpen: $dependabotOpen, dependabotMatched: $dependabotMatched,
              dependabotCommented: $dependabotCommented}' \
            > "result-mergeback-${SAFE}.json"

      - name: Upload result
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: result-mergeback-${{ steps.record.outputs.safe-name || matrix.project }}
          path: result-mergeback-*.json
          if-no-files-found: ignore

  milestones-and-releases:
    name: "Milestone + Release — ${{ matrix.project }}"
    # Runs after the merge back, because that is what makes the tagged commit reachable in the
    # repository this job publishes into - and, for the same reason, a project whose merge back
    # did not land gets no release at all. !cancelled() rather than a plain needs: a hotfix run
    # skips next-snapshot-config and merge-back-and-update entirely, and a skipped dependency
    # would otherwise skip this job too - leaving a hotfix run doing nothing at all, when
    # closing the milestone and publishing the release is the whole of a hotfix run.
    needs: [setup, verify-tags, merge-back-and-update]
    if: ${{ !cancelled() && needs.verify-tags.result == 'success' }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      max-parallel: 8
      matrix: ${{ fromJson(needs.verify-tags.outputs.matrix) }}
    steps:
      # A matrix leg cannot read another matrix leg's outputs, so the merge back's verdict for
      # this project comes back through the artifact it already uploads. continue-on-error and
      # if-no-files-found both matter: a hotfix run skips the merge back entirely, and that is
      # a run which must still publish.
      - name: Download the merge back results
        continue-on-error: true
        uses: actions/download-artifact@v4
        with:
          pattern: result-mergeback-*
          merge-multiple: true
          path: mergeback

      - name: Close milestone and create release
        id: run
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          PROJECT: ${{ matrix.project }}
          REPO: ${{ matrix.repo }}
          VERSION: ${{ matrix.version }}
          TAG: ${{ matrix.tag }}
          RESOLVED_IN: ${{ matrix.resolvedIn }}
          COMMERCIAL: ${{ needs.setup.outputs.commercial }}
          PRERELEASE: ${{ needs.setup.outputs.prerelease }}
          ENTRIES: ${{ needs.setup.outputs.entries }}
          SKIP_CLOSE_MILESTONES: ${{ inputs.skip_close_milestones }}
          DRY_RUN: ${{ inputs.dry_run }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const { execFileSync } = require('child_process');

          const project = process.env.PROJECT;
          const repo = process.env.REPO;
          const version = process.env.VERSION;
          const tag = process.env.TAG;
          const resolvedIn = process.env.RESOLVED_IN;
          const commercial = process.env.COMMERCIAL === 'true';
          const isPrerelease = process.env.PRERELEASE === 'true';
          const skipCloseMilestones = process.env.SKIP_CLOSE_MILESTONES === 'true';
          const dryRun = process.env.DRY_RUN === 'true';
          const entries = JSON.parse(process.env.ENTRIES);

          const gh = (args, input) => execFileSync('gh', args,
            { encoding: 'utf8', input, stdio: ['pipe', 'pipe', 'pipe'] });

          // Every milestone in the repository, across pages. --paginate is load-bearing:
          // several of these repos are past a hundred milestones, and the API returns them
          // sorted by due date ascending, so an unpaginated read silently loses exactly the
          // newest ones - the release just made and the one after it.
          const milestones = r => JSON.parse(gh(['api', '--paginate', '--slurp',
            `repos/${r}/milestones?state=all&per_page=100`])).flat();

          // matching-refs returns an array, so an exact comparison is required: a plain
          // git/refs/tags/v5.0.2 lookup also prefix-matches v5.0.20. Same check verify-tags
          // makes, repeated here because the tag can arrive between the two jobs.
          const tagExists = (r, t) => {
            try {
              return gh(['api', `repos/${r}/git/matching-refs/tags/${t}`, '--jq', '.[].ref'])
                .split('\n').map(x => x.trim()).includes(`refs/tags/${t}`);
            } catch (err) {
              return false;
            }
          };

          // ── a. close the milestone ──────────────────────────────────────────────────
          // Milestone titles are bare version numbers, no v prefix - the same lookup the
          // create-milestone action does. Never fails the job: a version carried over from an
          // earlier train already has a closed milestone, and some projects have none at all.
          // Skipping is a per-run choice rather than a per-project one, so it is decided before
          // the lookup: with nothing to do either way, there is no reason to spend an API call
          // reading a milestone that will not be touched.
          let milestone = 'skipped-by-request';
          if (skipCloseMilestones) {
            console.log(`skip_close_milestones is set - leaving milestone '${version}' alone.`);
          } else {
            milestone = 'not-found';
            try {
              const list = milestones(repo);
              const found = list.find(m => m.title === version);
              if (!found) {
                console.log(`Milestone '${version}' not found in ${repo}.`);
              } else if (found.state === 'closed') {
                console.log(`Milestone '${version}' (#${found.number}) is already closed.`);
                milestone = 'already-closed';
              } else if (dryRun) {
                console.log(`[dry run] would close milestone '${version}' (#${found.number}).`);
                milestone = 'would-close';
              } else {
                gh(['api', `repos/${repo}/milestones/${found.number}`,
                  '--method', 'PATCH', '--field', 'state=closed']);
                console.log(`Closed milestone '${version}' (#${found.number}).`);
                milestone = 'closed';
              }
            } catch (err) {
              console.log(`Could not read milestones for ${repo}: ${err.message}`);
              milestone = 'error';
            }
          }

          // ── b. create the release ───────────────────────────────────────────────────
          // ── the merge back's verdict for this project ───────────────────────────────
          // Read from the artifact rather than passed in: matrix legs cannot see each other's
          // outputs. Absent altogether means the merge back never ran - a hotfix - and that is
          // a run whose whole point is the release, so it goes ahead.
          let heldBackReason = '';
          const mergeBackLanded = () => {
            let record = null;
            try {
              for (const f of fs.readdirSync('mergeback')) {
                if (!f.endsWith('.json')) continue;
                const r = JSON.parse(fs.readFileSync(`mergeback/${f}`, 'utf8'));
                if (r.project === project) { record = r; break; }
              }
            } catch (err) {
              console.log('No merge back results to read - it did not run for this train.');
              return { ok: true };
            }
            if (!record) {
              console.log(`No merge back result for ${project} - it did not run for it.`);
              return { ok: true };
            }

            const MERGED = ['merged', 'already-merged', 'no-release-branch'];
            const PUSHED = ['pushed', 'nothing-to-push', 'would-push'];

            if (!MERGED.includes(record.mergeStatus)) {
              return { ok: false, why: `the merge back reported ${record.mergeStatus || 'nothing'}` };
            }

            // A dry run merges in the runner's clone and pushes nothing, so the merge status is
            // a real answer there and the push status is not: on a GA run the bump is skipped
            // too, because no snapshot file was committed for it to resolve versions from. Testing the push
            // on a dry run would hold back every project on every dry run, which says nothing
            // about what a real one would do.
            if (dryRun) return { ok: true };

            // On a real run the merge only reaches the remote as part of the single push that
            // also carries the version bump, so both halves have to have happened. A failed
            // bump stops the push, leaving the merge in the runner's clone and nowhere else.
            if (PUSHED.includes(record.pushStatus)) return { ok: true };
            return {
              ok: false,
              why: `the merge back merged but the push reported ` +
                `${record.pushStatus || 'nothing'}`,
            };
          };

          const createRelease = () => {
            if (resolvedIn === 'oss-fallback') {
              // The tag only exists in the OSS repo, so there is nothing here to release. The
              // OSS run of this workflow owns that release.
              console.log(`No ${tag} in ${repo} - release skipped (satisfied by the OSS tag).`);
              return { release: 'no-tag-oss-fallback', releaseUrl: '' };
            }

            // POST /releases with a tag_name that does not exist does not fail - it creates
            // the tag, at the default branch head, silently stamping v<version> onto whatever
            // main happens to be. verify-tags already proved the tag is here, so this should
            // never fire; it is kept because the cost of being wrong is a bogus tag on a
            // public repo and the cost of the check is one API call.
            if (!tagExists(repo, tag)) {
              console.log(`${tag} does not exist in ${repo} - release skipped.`);
              console.log('It was there when verify-tags ran, so something removed it during ' +
                'this run. Nothing was published rather than have the API create it.');
              return { release: 'no-tag', releaseUrl: '' };
            }

            // Nothing is published for a project whose merge back did not land. The tag is in
            // this repository either way, but the commit it names was built on the release
            // branch in the commercial repo and only becomes reachable when the merge is
            // pushed - so releasing now would attach notes generated against history that is
            // on no branch, and announce a release the maintenance branch has not received.
            // Resolve whatever stopped the merge and re-run with `projects` set to this one.
            const landed = mergeBackLanded();
            if (!landed.ok) {
              console.log(`Release skipped for ${project}: ${landed.why}.`);
              heldBackReason = landed.why;
              return { release: 'merge-incomplete', releaseUrl: '' };
            }

            let existing = null;
            try {
              existing = JSON.parse(gh(['api', `repos/${repo}/releases/tags/${tag}`]));
            } catch (err) { /* no release yet */ }

            if (existing) {
              console.log(`Release ${tag} already exists: ${existing.html_url}`);
              return { release: 'already-exists', releaseUrl: existing.html_url };
            }

            const generated = JSON.parse(gh(['api', `repos/${repo}/releases/generate-notes`,
              '--method', 'POST', '--field', `tag_name=${tag}`]));
            let body = generated.body || '';

            // Commercial release notes are read by people without access to the private repo,
            // so the PR links and contributor handles are noise. Strip them, matching what the
            // existing commercial releases look like.
            if (commercial) {
              body = body.replace(/ by @\S+ in https?:\/\/\S+/g, '');
              const kept = [];
              let skipping = false;
              for (const line of body.split('\n')) {
                if (/^##\s/.test(line)) skipping = /contributors/i.test(line);
                if (skipping) continue;
                if (/^\*\*Full Changelog\*\*:/.test(line)) continue;
                kept.push(line);
              }
              body = kept.join('\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
            }

            // The release train's own release lists what shipped in the BOM, taken from the
            // same properties file the rest of this workflow runs on. spring-cloud-release is
            // left out of its own list: the hand-written bodies name a "Spring Cloud Starter
            // Build" repository that does not exist, so including it would emit a dead link.
            if (project === 'spring-cloud-release') {
              const titleCase = k =>
                k.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');

              // No issue links on a commercial train. They would point into the private
              // <project>-commercial repositories, and the people who read these notes are the
              // ones without access - a row of links that 404 for the audience is worse than
              // no links at all. The module and its version are the useful part either way.
              const included = entries
                .filter(e => !['spring-boot', 'spring-vault', 'spring-cloud-release'].includes(e.key))
                .map(e => commercial
                  ? ` - ${titleCase(e.key)} \`${e.version}\``
                  : ` - ${titleCase(e.key)} \`${e.version}\` ` +
                    `([issues](https://github.com/spring-cloud/${e.key}/releases/tag/v${e.version}))`);
              // Trailing trim matters here: when the generated notes are empty (see below) this
              // would otherwise leave the list followed by blank lines.
              body = `## What's Included\n${included.join('\n')}\n\n${body}`.trim() + '\n';
            }

            // generate-notes is PR-based, so it returns nothing but a Full Changelog link when
            // there are no merged PRs to list - which the sanitize step above then strips,
            // leaving an empty body. That happens when the work landed as direct commits rather
            // than through PRs, and also when there is no predecessor tag at all (commercial
            // lines are orphan branches, so the first tag on a line has nothing to diff
            // against). Publish a placeholder; the changes get written up by hand.
            // Checked after What's Included is prepended, so the release train's own list is
            // never displaced by the placeholder.
            if (!body.trim()) {
              body = `Released from tag ${tag}.\n`;
              console.log('Generated notes were empty (no predecessor tag on this line) - ' +
                'using a placeholder body.');
            }

            // Release titles are inconsistent across the org and this reproduces rather than
            // normalizes them: OSS projects use the bare version, while spring-cloud-release
            // and every commercial repo use a v prefix.
            const name = (commercial || project === 'spring-cloud-release') ? tag : version;

            // A milestone or release candidate is flagged as a pre-release, and explicitly
            // kept from becoming the repository's "Latest" release. Without make_latest
            // GitHub promotes the newest release by date, so publishing 5.1.0-M1 would put
            // it above the current 5.0.x GA on every project page and in the API that
            // downstream tooling reads to find the current version.
            const payload = { tag_name: tag, name, body };
            if (isPrerelease) {
              payload.prerelease = true;
              // A string, not a boolean: the REST API defines make_latest as an enum of
              // "true" | "false" | "legacy", and a JSON boolean is rejected.
              payload.make_latest = 'false';
            }

            if (dryRun) {
              console.log(`[dry run] would create release '${name}' for ${tag} in ${repo}` +
                `${isPrerelease ? ' (pre-release, not marked latest)' : ''}:`);
              console.log('---');
              console.log(body);
              console.log('---');
              return { release: 'would-create', releaseUrl: '' };
            }

            // Via --input rather than repeated --field, so a body containing newlines,
            // backticks or quotes cannot be mangled on the way through.
            fs.writeFileSync('payload.json', JSON.stringify(payload));
            const created = JSON.parse(gh(['api', `repos/${repo}/releases`,
              '--method', 'POST', '--input', 'payload.json']));
            console.log(`Created release ${created.html_url}`);
            return { release: 'created', releaseUrl: created.html_url };
          };

          let release = 'skipped';
          let releaseUrl = '';
          let failure = null;
          try {
            const result = createRelease();
            release = result.release;
            releaseUrl = result.releaseUrl;
          } catch (err) {
            console.error(`ERROR: ${err.message}`);
            release = 'error';
            failure = err;
          }

          // Written before exiting on failure, so a project that blew up still gets a row in
          // the summary rather than silently vanishing from the table.
          const safe = `${repo}`.replace(/\//g, '-');
          fs.appendFileSync(process.env.GITHUB_OUTPUT, `safe-name=${safe}\n`);
          fs.writeFileSync(`result-milestones-${safe}.json`, JSON.stringify({
            phase: 'milestones-and-releases',
            project, repo, version, tag, resolvedIn, milestone, release, releaseUrl,
            heldBackReason,
          }));

          if (failure) process.exit(1);
          JSEOF

      - name: Upload result
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: result-milestones-${{ steps.run.outputs.safe-name || matrix.project }}
          path: result-milestones-*.json
          if-no-files-found: ignore

  # ── The spring.io website ────────────────────────────────────────────────────────────
  # One PR against the website content repository for whichever flavour this run is:
  #
  #   OSS         spring-website-content             blog post + documentation.json bumps
  #   commercial  spring-website-commercial-content  documentation.json entries, no blog post
  #
  # The two sites keep their versions in completely different ways, so the documentation
  # halves have nothing in common beyond the file name. The OSS site lists the versions
  # currently being documented and is edited in place; the commercial site is an archive
  # where every release ever made keeps its own entry, so a release appends rather than
  # edits. See README-post-release.md.
  #
  # Never runs for a filtered run: this is a train-wide statement about a release, so a
  # partial one would be wrong rather than merely incomplete. It runs after the releases
  # are published because the blog post's module table links to release pages this
  # workflow creates.
  website-pr:
    name: Website PR
    needs: [setup, verify-tags, next-snapshot-config, milestones-and-releases]
    # next-snapshot-config only for OSS, and only because the snapshot entries on that site
    # follow it. A commercial run needs nothing from it - the commercial site has no
    # snapshot entries at all - and must not be gated on a job a hotfix skips outright.
    if: |
      !cancelled() &&
      needs.verify-tags.result == 'success' &&
      inputs.skip_website_pr != true &&
      inputs.projects == '' &&
      (needs.setup.outputs.commercial == 'true' ||
       needs.setup.outputs.prerelease == 'true' ||
       needs.next-snapshot-config.result == 'success')
    runs-on: ubuntu-latest
    steps:
      # Only so the script below can require .github/scripts/.
      - uses: actions/checkout@v4

      - name: Build the website changes and open the PR
        id: run
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          RELEASE_VERSION: ${{ inputs.release_version }}
          RELEASE_REPO: ${{ needs.setup.outputs.release-repo }}
          COMMERCIAL: ${{ needs.setup.outputs.commercial }}
          ENTRIES: ${{ needs.setup.outputs.entries }}
          RESOLVED: ${{ needs.verify-tags.outputs.matrix }}
          NEXT_VERSIONS: ${{ needs.setup.outputs.prerelease == 'true'
            && needs.setup.outputs.next-versions
            || needs.next-snapshot-config.outputs.versions }}
          PRERELEASE: ${{ needs.setup.outputs.prerelease }}
          DRY_RUN: ${{ inputs.dry_run }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const path = require('path');
          const { parseReleaserConfig, ENTRY_RE } = require(path.join(
            process.env.GITHUB_WORKSPACE, '.github', 'scripts', 'releaser-config.js'));
          const { execFileSync } = require('child_process');

          const token = process.env.GH_TOKEN;
          const releaseVersion = process.env.RELEASE_VERSION;
          const releaseRepo = process.env.RELEASE_REPO;
          const commercial = process.env.COMMERCIAL === 'true';
          const dryRun = process.env.DRY_RUN === 'true';
          const runUrl = process.env.RUN_URL || '';
          const entries = JSON.parse(process.env.ENTRIES);
          const resolved = JSON.parse(process.env.RESOLVED).include;
          const nextVersions = JSON.parse(process.env.NEXT_VERSIONS || '{}');
          const isPrereleaseRun = process.env.PRERELEASE === 'true';

          const WEBSITE = commercial
            ? 'spring-io/spring-website-commercial-content'
            : 'spring-io/spring-website-content';
          const BASE = 'main';
          const CONFIG_BRANCH = 'jenkins-releaser-config';
          // Release train codenames (Northfields, Oakwood) live nowhere this workflow reads,
          // so the title carries a placeholder rather than a guess. Same for the author: it is
          // whoever writes the post up, not whoever happened to run the release.
          const CODENAME = 'CODENAME';
          const AUTHOR = 'TODO';

          const gh = args => execFileSync('gh', args,
            { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
          const git = (args, cwd) => execFileSync('git', args,
            { encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'] });

          const branch = `spring-cloud-${releaseVersion}`;
          const result = {
            phase: 'website-pr', repo: WEBSITE, branch, status: 'skipped',
            blogFile: '', blogStatus: '', prUrl: '', previousFile: '',
            listed: [], docs: [],
          };
          const out = process.env.GITHUB_OUTPUT;
          const finish = (status, message) => {
            if (message) console.log(message);
            result.status = status;
            fs.writeFileSync('result-website.json', JSON.stringify(result));
            fs.appendFileSync(out, `status=${status}\n`);
            fs.appendFileSync(out, `pr-url=${result.prUrl}\n`);
            process.exit(0);
          };

          // ── a. which projects this run has anything to say about ────────────────────
          const cmp = (a, b) => {
            const pa = a.split('.').map(Number), pb = b.split('.').map(Number);
            for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
              const d = (pa[i] || 0) - (pb[i] || 0);
              if (d) return d;
            }
            return 0;
          };

          const [major, minor] = releaseVersion.split('.');
          const trainLine = `${major}.${minor}`;

          const titleCase = k =>
            k.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
          // spring-cloud-release is the train itself. The module table has always called it
          // Spring Cloud Starter Build, and its release is the one this workflow published.
          const label = e =>
            e.key === 'spring-cloud-release' ? 'Spring Cloud Starter Build' : titleCase(e.key);

          // Every project in the train, for the OSS site: it documents the versions currently
          // being documented, and even a project that did not move needs its snapshot entry
          // following the new snapshot train.
          const projects = entries.filter(e => !['spring-boot', 'spring-vault'].includes(e.key));

          // For the commercial site, only the projects with a tag of their own in the
          // commercial repo. An oss-fallback entry carries the plain OSS version because that
          // project has had no commercial release since the last OSS one, so there is no
          // commercial documentation of it to add.
          const releasedCommercially = resolved
            .filter(e => e.resolvedIn === 'commercial')
            .map(e => ({ key: e.project, version: e.version }))
            .sort((a, b) => a.key.localeCompare(b.key));

          // The blog post's module table and its per-project headings cover what actually
          // shipped, matching the hand-written posts, which never list a project that was
          // carried over untouched. Compared against the most recent earlier file on this
          // train line, whatever it happens to be, rather than the direct predecessor: those
          // are routinely missing (there is no 2025_0_3.properties), and a hotfix file like
          // 2025_0_2_1.properties describes the state of the train just as well.
          let listed = [];
          if (!commercial) {
            let previousVersions = null;
            try {
              const names = JSON.parse(gh(['api',
                `repos/${releaseRepo}/contents?ref=${CONFIG_BRANCH}`, '--jq', '[.[].name]']));
              const re = new RegExp(`^${major}_${minor}(?:_\\d+)+\\.properties$`);
              const earlier = names.filter(n => re.test(n))
                .map(n => ({ name: n, version: n.replace(/\.properties$/, '').replace(/_/g, '.') }))
                .filter(c => cmp(c.version, releaseVersion) < 0)
                .sort((a, b) => cmp(a.version, b.version));
              if (earlier.length) {
                result.previousFile = earlier[earlier.length - 1].name;
                const b64 = gh(['api',
                  `repos/${releaseRepo}/contents/${result.previousFile}?ref=${CONFIG_BRANCH}`,
                  '--jq', '.content']);
                const text = Buffer.from(b64.replace(/\s/g, ''), 'base64').toString('utf8');
                previousVersions = {};
                for (const e of parseReleaserConfig(text)) previousVersions[e.key] = e.version;
                console.log(`Comparing against ${result.previousFile} to find what was released.`);
              }
            } catch (err) {
              console.log(`Could not read an earlier properties file: ${err.message}`);
            }

            // Everything, when there is nothing to compare against: an over-long list is edited
            // down in the PR, whereas silently dropping a project that did ship is not noticed.
            const changed = previousVersions
              ? projects.filter(e => previousVersions[e.key] !== e.version)
              : projects.slice();
            if (!previousVersions) {
              console.log('No earlier properties file on this line - listing every project.');
            }
            listed = changed.slice().sort((a, b) => label(a).localeCompare(label(b)));
            result.listed = listed.map(e => `${e.key}=${e.version}`);

            console.log(`Modules to list (${listed.length}):`);
            for (const e of listed) console.log(`  ${label(e)} ${e.version}`);
          } else {
            result.listed = releasedCommercially.map(e => `${e.key}=${e.version}`);
            console.log(`Released commercially (${releasedCommercially.length}):`);
            for (const e of releasedCommercially) console.log(`  ${e.key} ${e.version}`);
            const fallback = resolved.filter(e => e.resolvedIn !== 'commercial');
            for (const e of fallback) {
              console.log(`  ${e.project} ${e.version} - no commercial tag, nothing to document`);
            }
          }

          // ── b. is there already a branch for this release? ──────────────────────────
          let branchExists = false;
          try {
            gh(['api', `repos/${WEBSITE}/branches/${branch}`, '--jq', '.name']);
            branchExists = true;
          } catch (err) { /* no branch yet */ }

          if (branchExists) {
            // Almost certainly an earlier run of this workflow, and the PR it opened may have
            // been edited since - on an OSS run that is where the notable-changes sections get
            // written. Force-pushing over it would throw away the one part of this PR nobody
            // can regenerate.
            try {
              const prs = JSON.parse(gh(['api',
                `repos/${WEBSITE}/pulls?head=spring-io:${branch}&state=all&per_page=1`]));
              if (prs.length) result.prUrl = prs[0].html_url;
            } catch (err) { /* leave the url empty */ }
            finish('branch-exists',
              `${branch} already exists in ${WEBSITE} - leaving it alone. ${result.prUrl}`);
          }

          // ── c. clone and write ──────────────────────────────────────────────────────
          console.log(`Cloning ${WEBSITE}@${BASE}...`);
          git(['clone', '--quiet', '--depth', '1', '--branch', BASE,
            `https://x-access-token:${token}@github.com/${WEBSITE}.git`, 'website']);

          const boot = (entries.find(e => e.key === 'spring-boot') || {}).version || '';

          // How this release describes itself. A milestone and a release candidate are
          // announced like a GA release but published somewhere else - the Spring milestone
          // repository rather than Maven Central - so the wording and the link both change,
          // and the dependency snippets below need a <repositories> block a GA post does not.
          const phase = (() => {
            const m = releaseVersion.match(/-(M|RC)(\d+)$/);
            if (!m) {
              return {
                prerelease: false,
                blurb: 'the General Availability (RELEASE) of',
                repoName: 'Maven Central',
                repoUrl: 'https://repo1.maven.org/maven2/org/springframework/cloud/' +
                  `spring-cloud-dependencies/${releaseVersion}/`,
              };
            }
            const label = m[1] === 'M' ? `Milestone ${m[2]} (M${m[2]})`
              : `Release Candidate ${m[2]} (RC${m[2]})`;
            return {
              prerelease: true,
              blurb: `the ${label} of`,
              repoName: 'the Spring milestone repository',
              repoUrl: 'https://repo.spring.io/milestone/org/springframework/cloud/' +
                `spring-cloud-dependencies/${releaseVersion}/`,
              milestoneRepoUrl: 'https://repo.spring.io/milestone',
            };
          })();
          const today = new Date().toISOString().slice(0, 10);
          const dashed = releaseVersion.replace(/\./g, '-');

          // ── c1. the blog post ───────────────────────────────────────────────────────
          // A post for this version may already be on the site - this is a re-run after the
          // first PR was merged, or the release was announced by hand. Never overwrite it.
          const existingPosts = [];
          const walk = dir => {
            for (const d of fs.readdirSync(dir, { withFileTypes: true })) {
              const p = `${dir}/${d.name}`;
              if (d.isDirectory()) walk(p);
              else if (new RegExp(`^spring-cloud-${dashed}(-|\\.)`).test(d.name)) {
                existingPosts.push(p.replace(/^website\//, ''));
              }
            }
          };
          // Nothing to look for on the commercial site: it has no blog directory at all.
          if (!commercial) {
            try { walk('website/blog'); } catch (err) { /* no blog directory */ }
          }

          // No codename in the file name: it is a placeholder in the title, and a published
          // URL reading spring-cloud-2025-0-4-aka-codename-... is worse than one that simply
          // leaves it out. Renaming the file is on the checklist in the PR body.
          const blogFile =
            `blog/${today.slice(0, 4)}/${today.slice(5, 7)}/spring-cloud-${dashed}-has-been-released.md`;

          if (commercial) {
            // Commercial releases are not announced on the commercial site - it has no blog -
            // so this PR is the documentation entries and nothing else.
            result.blogStatus = 'none';
          } else if (existingPosts.length) {
            result.blogFile = existingPosts[0];
            result.blogStatus = 'already-exists';
            console.log(`A post for ${releaseVersion} already exists (${existingPosts[0]}) - ` +
              'not writing another one.');
          } else {
            result.blogFile = blogFile;
            result.blogStatus = 'created';

            const B = [];
            B.push('---');
            B.push(`title: "Spring Cloud ${releaseVersion} (aka ${CODENAME}) Has Been Released"`);
            B.push('category: Releases');
            B.push(`publishedAt: ${today}`);
            B.push(`author: ${AUTHOR}`);
            B.push('---');
            B.push('');
            B.push('On behalf of the community, I am pleased to announce that ' +
              `${phase.blurb} the [Spring Cloud ${releaseVersion}]` +
              '(https://cloud.spring.io) Release Train is available today. The release can be ' +
              `found in [${phase.repoName}](${phase.repoUrl}). You can check out the ` +
              `${releaseVersion} [release notes for more information](https://github.com/` +
              `spring-cloud/spring-cloud-release/wiki/Spring-Cloud-${trainLine}-Release-Notes).`);
            B.push('');
            B.push(`## Notable Changes in the ${releaseVersion} Release Train`);
            B.push('');
            if (boot) {
              B.push('This release is based on Spring Boot `' + boot + '`.');
              B.push('');
            }
            // One heading per project that shipped, each left as TODO: what was notable about
            // a release is in nobody's properties file. The train itself gets no heading - it
            // is the BOM, and the hand-written posts have never given it one.
            for (const e of listed) {
              if (e.key === 'spring-cloud-release') continue;
              B.push(`### ${titleCase(e.key)}`);
              B.push('');
              B.push('TODO');
              B.push('');
            }
            B.push(`The following modules were updated as part of ${releaseVersion}:`);
            B.push('');
            B.push('| Module | Version | Issues |');
            B.push('| ------ | ------- |------- |');
            for (const e of listed) {
              B.push(`| ${label(e)}    | ${e.version}    | ([issues](https://github.com/` +
                `spring-cloud/${e.key}/releases/tag/v${e.version})) |`);
            }
            B.push('');
            B.push('');
            B.push('As always, we welcome feedback on [GitHub](https://github.com/spring-cloud/), ' +
              'on [Gitter](https://gitter.im/spring-cloud/spring-cloud), on [Stack Overflow]' +
              '(https://stackoverflow.com/questions/tagged/spring-cloud), or on [Twitter]' +
              '(https://twitter.com/SpringCloud).');
            B.push('');
            B.push('To get started with Maven with a BOM (dependency management only):');
            B.push('');
            B.push('```');
            B.push('');
            B.push('<dependencyManagement>');
            B.push('    <dependencies>');
            B.push('        <dependency>');
            B.push('            <groupId>org.springframework.cloud</groupId>');
            B.push('            <artifactId>spring-cloud-dependencies</artifactId>');
            B.push(`            <version>${releaseVersion}</version>`);
            B.push('            <type>pom</type>');
            B.push('            <scope>import</scope>');
            B.push('        </dependency>');
            B.push('    </dependencies>');
            B.push('</dependencyManagement>');
            B.push('<dependencies>');
            B.push('    <dependency>');
            B.push('        <groupId>org.springframework.cloud</groupId>');
            B.push('        <artifactId>spring-cloud-starter-config</artifactId>');
            B.push('    </dependency>');
            B.push('    <dependency>');
            B.push('        <groupId>org.springframework.cloud</groupId>');
            B.push('        <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>');
            B.push('    </dependency>');
            B.push('    ...');
            B.push('</dependencies>');
            if (phase.prerelease) {
              // Without this the snippet does not build: a milestone BOM is not on Central,
              // and the reader's first move after copying it is an unresolvable dependency.
              B.push('');
              B.push('<repositories>');
              B.push('    <repository>');
              B.push('        <id>spring-milestones</id>');
              B.push('        <name>Spring Milestones</name>');
              B.push(`        <url>${phase.milestoneRepoUrl}</url>`);
              B.push('        <snapshots>');
              B.push('            <enabled>false</enabled>');
              B.push('        </snapshots>');
              B.push('    </repository>');
              B.push('</repositories>');
            }
            B.push('```');
            B.push('');
            B.push('or with Gradle:');
            B.push('');
            B.push('```');
            B.push('buildscript {');
            B.push('dependencies {');
            B.push('classpath "io.spring.gradle:dependency-management-plugin:1.0.2.RELEASE"');
            B.push('}');
            B.push('}');
            B.push('');
            B.push('');
            B.push('');
            B.push('apply plugin: "io.spring.dependency-management"');
            B.push('');
            B.push('dependencyManagement {');
            B.push('imports {');
            B.push(`mavenBom 'org.springframework.cloud:spring-cloud-dependencies:${releaseVersion}'`);
            B.push('}');
            B.push('}');
            B.push('');
            B.push('dependencies {');
            B.push("compile 'org.springframework.cloud:spring-cloud-starter-config'");
            B.push("compile 'org.springframework.cloud:spring-cloud-starter-netflix-eureka-client'");
            B.push('...');
            B.push('}');
            if (phase.prerelease) {
              B.push('');
              B.push('repositories {');
              B.push('mavenCentral()');
              B.push(`maven { url '${phase.milestoneRepoUrl}' }`);
              B.push('}');
            }
            B.push('```');

            fs.mkdirSync(path.dirname(`website/${blogFile}`), { recursive: true });
            fs.writeFileSync(`website/${blogFile}`, B.join('\n') + '\n');
            console.log(`Wrote ${blogFile}.`);
          }

          // ── d. documentation.json ───────────────────────────────────────────────────
          // The two sites record their versions in ways that have nothing in common beyond
          // the file name, so this is two separate passes - each iterating an empty list on
          // the other flavour's run.
          const docFor = key => key === 'spring-cloud-release' ? 'spring-cloud' : key;
          const lineOf = v => v.split('.').slice(0, 2).join('.');

          // ── d1. the commercial site: one appended entry per released version ────────
          // These files are an archive. Every commercial release keeps its own
          // GENERAL_AVAILABILITY entry, nothing is ever edited, and there are no SNAPSHOT
          // entries - so a release appends.
          //
          // The new entry is cloned from the newest existing entry on the same major.minor
          // line, as raw text with the version substituted, rather than assembled from
          // fields: there is no single shape to assemble. Field order differs between files
          // (spring-cloud-gateway writes version first, spring-cloud-task writes api first),
          // ref is a versioned URL on the older lines and a static one on the newer, and
          // githubTag carries a v prefix in most files but not all. The newest entry on the
          // line is the only reliable statement of what this project's entries look like now.
          //
          // Splicing at line level is safe because every file in that repository is laid out
          // identically: one entry per '  {' ... '  }' block, one field per line. A file that
          // is not is reported rather than guessed at.
          const NUMERIC = /^\d+(\.\d+)*$/;
          const entryBlocks = fileLines => {
            const blocks = [];
            let start = -1;
            for (let i = 0; i < fileLines.length; i++) {
              if (fileLines[i] === '  {') start = i;
              else if (start >= 0 && (fileLines[i] === '  }' || fileLines[i] === '  },')) {
                blocks.push({ start, end: i });
                start = -1;
              }
            }
            return blocks;
          };

          for (const e of (commercial ? releasedCommercially : [])) {
            const rel = `project/${docFor(e.key)}/documentation.json`;
            const file = `website/${rel}`;
            const rec = {
              project: e.key, file: rel, added: '', from: '', fallback: false,
              legacyTemplate: false, status: 'unchanged',
            };
            result.docs.push(rec);

            // spring-cloud-build has no page on the site, so it has no file here.
            if (!fs.existsSync(file)) {
              rec.status = 'no-file';
              console.log(`${rel}: not on the site - skipped.`);
              continue;
            }

            const original = fs.readFileSync(file, 'utf8');
            let list;
            try {
              list = JSON.parse(original);
            } catch (err) {
              rec.status = 'unparseable';
              console.log(`${rel}: could not be parsed - skipped.`);
              continue;
            }

            const lines = original.split('\n');
            const blocks = entryBlocks(lines);
            if (blocks.length !== list.length) {
              rec.status = 'unrecognised-format';
              console.log(`${rel}: ${list.length} entries but ${blocks.length} recognised ` +
                'blocks - skipped.');
              continue;
            }

            // Idempotent on its own: a version carried over from an earlier train was
            // documented when it was released, and is left exactly as it is.
            if (list.some(x => x.version === e.version)) {
              rec.status = 'already-listed';
              console.log(`${rel}: ${e.version} is already listed.`);
              continue;
            }

            const target = lineOf(e.version);
            const usable = list
              .map((x, i) => i)
              .filter(i => NUMERIC.test(list[i].version || ''));
            const newest = candidates => candidates.reduce(
              (best, i) => (best < 0 || cmp(list[i].version, list[best].version) > 0 ? i : best),
              -1);

            // A version in a ref means the pre-Antora docs layout, where every version was
            // published under its own path. Antora URLs carry no version at all.
            const versionInRef = x => {
              const ref = x.ref || '';
              return ref.includes('{version}') || (!!x.version && ref.includes(x.version));
            };

            let anchor = newest(usable.filter(i => lineOf(list[i].version) === target));
            if (anchor < 0) {
              // No entry on this line yet, so this is the first commercial release of a new
              // line - which means Antora, which means the ref must not carry a version. So
              // the template has to be an entry whose ref already has none, even if a legacy
              // entry is newer: cloning a .../docs/<version>/reference/html/ ref would
              // substitute this version into a path that only exists for the old layout.
              rec.fallback = true;
              anchor = newest(usable.filter(i => !versionInRef(list[i])));
              if (anchor < 0) {
                // Nothing but legacy entries in the whole file. Every project in a current
                // train has an Antora entry by now, so this is either a project long retired
                // or one being documented with Antora for the first time - and the ref needs
                // writing by hand either way, so the PR says so.
                anchor = newest(usable);
                rec.legacyTemplate = true;
              }
            }
            if (anchor < 0) {
              rec.status = 'no-template';
              console.log(`${rel}: no entry to clone one from - skipped.`);
              continue;
            }

            const template = list[anchor];
            // Bounded so a template version of 4.1.1 cannot rewrite the 4.1.10 next to it,
            // and unbounded enough that the v of githubTag and the slashes around a versioned
            // ref path do not stop it matching.
            const bounded = new RegExp(
              `(?<![\\d.])${template.version.replace(/\./g, '\\.')}(?![\\d.])`, 'g');
            let block = lines.slice(blocks[anchor].start, blocks[anchor].end + 1)
              .map(l => l.replace(bounded, e.version));

            // githubTag is derived, never inherited. Substitution only rewrites fields that
            // contain the template's own version, so a template whose tag disagrees with its
            // version hands that straight to the new entry - spring-cloud-gateway carries
            // version 4.3.4.1 with githubTag v5.0.1.1, which is how a 4.3.6 entry ended up
            // tagged v5.0.1.1. Whether the prefix is a v is a per-file convention, so it is
            // read from the entries in this file that are self-consistent.
            let withV = 0, without = 0;
            for (const x of list) {
              if (!x.version || !x.githubTag) continue;
              if (x.githubTag === `v${x.version}`) withV++;
              else if (x.githubTag === x.version) without++;
            }
            const prefix = (withV || without)
              ? (withV >= without ? 'v' : '')
              : ((template.githubTag || '').startsWith('v') ? 'v' : '');
            block = block.map(l =>
              l.replace(/^(\s*"githubTag"\s*:\s*")[^"]*(")/, `$1${prefix}${e.version}$2`));

            // Any full version left in the block that is not the new one came from a template
            // that was already inconsistent - gateway's 4.0.9 entry has a ref pointing at
            // 4.0.10 - and substitution cannot have fixed it, because it never contained the
            // template's version to begin with. The entry is still added, since the version
            // and tag are right and a missing entry is worse, but it is reported so the PR
            // says which field to look at.
            // The qualifier is part of the version: without it, cloning for 5.1.0-M1 would
            // match the bare 5.1.0 inside it and report the entry's own version as a stray.
            const strays = [...new Set(
              (block.join('\n').match(/\d+\.\d+\.\d+(?:\.\d+)?(?:-(?:M|RC)\d+)?/g) || [])
              .filter(v => v !== e.version))];
            if (strays.length) {
              rec.strays = strays;
              problem(`${rel}: the ${template.version} entry it was cloned from carries ` +
                `${strays.map(v => `'${v}'`).join(', ')} - check the new entry's ref`);
            }

            // Where it goes: alongside the newest entry on its line, on whichever side keeps
            // that group's own ordering. The groups are contiguous but not consistently
            // sorted - the 4.1 group in spring-cloud-config runs 4.1.10, 4.1.9, 4.1.8 - and
            // following the local direction is what keeps this to one added block sitting
            // with its siblings rather than a reordering of the file.
            let first = list.length - 1, last = list.length - 1;
            if (!rec.fallback) {
              first = last = anchor;
              while (first > 0 && lineOf(list[first - 1].version) === target) first--;
              while (last < list.length - 1 && lineOf(list[last + 1].version) === target) last++;
            }

            if (cmp(list[first].version, list[last].version) > 0) {
              block[block.length - 1] = '  },';
              lines.splice(blocks[first].start, 0, ...block);
            } else if (lines[blocks[last].end] === '  }') {
              // Going in after the array's last entry, which moves the trailing comma onto it.
              lines[blocks[last].end] = '  },';
              block[block.length - 1] = '  }';
              lines.splice(blocks[last].end + 1, 0, ...block);
            } else {
              block[block.length - 1] = '  },';
              lines.splice(blocks[last].end + 1, 0, ...block);
            }

            // The splice is a text edit, so prove the result is still the same JSON plus one
            // entry before writing it. Cheap, and the alternative is a broken site.
            const updated = lines.join('\n');
            let check = null;
            try { check = JSON.parse(updated); } catch (err) { /* check stays null */ }
            if (!check || check.length !== list.length + 1 ||
                !check.some(x => x.version === e.version)) {
              rec.status = 'error';
              console.log(`${rel}: the edit did not produce the expected JSON - left alone.`);
              continue;
            }

            fs.writeFileSync(file, updated);
            rec.status = 'added';
            rec.added = e.version;
            rec.from = template.version;
            console.log(`${rel}: added ${e.version}, cloned from ${template.version}` +
              (rec.fallback ? ` - first ${target} entry` : '') +
              (rec.legacyTemplate ? ', and only pre-Antora refs to clone - CHECK THE REF' : ''));
          }

          // ── d2. the OSS site: the versions bumped in place ─────────────────────────
          // Applied to every project in the train, not just the ones that moved: a project
          // whose version is unchanged simply produces no diff, and its snapshot entry still
          // has to follow the new snapshot train. Each file holds one GENERAL_AVAILABILITY
          // and one SNAPSHOT entry per major.minor line, so the released version's line
          // picks out exactly the entries to update.
          //
          // A train that ships milestones adds a third status to that line, and the site
          // carries exactly one of them at a time - the entry is promoted rather than
          // accumulated:
          //
          //   5.1.0-M1   no entry on the line yet, so one is created  PRERELEASE  5.1.0-M1
          //   5.1.0-M2   the same entry, rewritten                    PRERELEASE  5.1.0-M2
          //   5.1.0-RC1  the same entry, rewritten                    PRERELEASE  5.1.0-RC1
          //   5.1.0      the same entry, rewritten and promoted       GA          5.1.0
          //
          // So a reader never sees a milestone listed next to the GA that supersedes it, and
          // the line only ever grows by one entry however many pre-releases it takes.
          for (const e of (commercial ? [] : projects)) {
            const rel = `project/${docFor(e.key)}/documentation.json`;
            const file = `website/${rel}`;
            const rec = { project: e.key, file: rel, ga: '', snapshot: '', prerelease: '', status: 'unchanged' };
            result.docs.push(rec);

            // spring-cloud-build has no page on the website, so it has no file here.
            if (!fs.existsSync(file)) {
              rec.status = 'no-file';
              console.log(`${rel}: not on the website - skipped.`);
              continue;
            }

            const original = fs.readFileSync(file, 'utf8');
            let text = original;
            let list;
            try {
              list = JSON.parse(text);
            } catch (err) {
              rec.status = 'unparseable';
              console.log(`${rel}: could not be parsed - skipped.`);
              continue;
            }

            // Edited as text rather than parsed and reserialized: these files are not
            // formatted alike across projects (some write "version" : x, others "version": x)
            // so reserializing would bury two version bumps under a whole-file reindentation.
            const replaceVersion = (oldV, newV) => {
              const quoted = oldV.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
              const re = new RegExp(`("version"\\s*:\\s*")${quoted}(")`, 'g');
              // Exactly one match or nothing: two entries carrying the same version would make
              // the edit a guess, and this file is better left to a human than half-edited.
              if ((text.match(re) || []).length !== 1) return false;
              text = text.replace(re, `$1${newV}$2`);
              return true;
            };

            // Rewrites the status of the entry that currently carries `version`. Same
            // one-match-or-nothing rule as replaceVersion, and matched on the pair so that
            // two entries sharing a status cannot be confused for each other.
            const replaceStatus = (version, newStatus) => {
              const quoted = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
              // Anchored on the version so the status of a neighbouring entry cannot be
              // rewritten instead. The version is re-emitted rather than left to a capture
              // group spanning it, because dropping it here would blank the field.
              const re = new RegExp(
                `("version"\\s*:\\s*")${quoted}("[\\s\\S]{0,400}?"status"\\s*:\\s*")[A-Z_]+(")`);
              const before = text;
              text = text.replace(re, `$1${version}$2${newStatus}$3`);
              return text !== before;
            };

            // No githubTag handling here, unlike the commercial pass above: entries on the
            // OSS site do not carry that field at all. An entry is identified by its version
            // and its ref, and both are handled explicitly.

            const target = lineOf(e.version);
            const onLine = x => x.version && lineOf(x.version) === target;
            const ga = list.find(x => x.status === 'GENERAL_AVAILABILITY' && onLine(x));
            const snap = list.find(x => x.status === 'SNAPSHOT' && onLine(x));
            const pre = list.find(x => x.status === 'PRERELEASE' && onLine(x));
            const nextSnap = nextVersions[e.key] || '';

            if (isPrereleaseRun) {
              // The snapshot entry is deliberately untouched: main has not moved off its
              // snapshot, so there is nothing to follow. nextVersions is empty on this path
              // anyway, but the intent is worth stating.
              if (pre) {
                if (pre.version !== e.version) {
                  if (replaceVersion(pre.version, e.version)) {
                    rec.prerelease = `${pre.version} → ${e.version}`;
                  } else {
                    rec.status = 'ambiguous';
                  }
                }
              } else {
                // First pre-release of this line, so there is no entry to rewrite. Creating
                // one is handled below, after the in-place cases, because it splices lines
                // rather than editing them.
                rec.status = 'needs-entry';
              }
            } else {
              if (!ga && !snap && !pre) {
                rec.status = 'no-entry';
                console.log(`${rel}: no ${target} entry - skipped.`);
                continue;
              }
              if (ga && ga.version !== e.version) {
                if (replaceVersion(ga.version, e.version)) rec.ga = `${ga.version} → ${e.version}`;
                else rec.status = 'ambiguous';
              }
              // The GA that concludes a pre-release cycle. With no GA entry on the line the
              // pre-release entry becomes it, which is the whole point of promoting in place;
              // with one already there the pre-release entry is stale and its version is
              // folded into the GA entry above, so it is dropped rather than left behind
              // advertising an RC that GA has superseded.
              if (pre) {
                if (!ga) {
                  const versionOk = pre.version === e.version ||
                    replaceVersion(pre.version, e.version);
                  if (versionOk && replaceStatus(e.version, 'GENERAL_AVAILABILITY')) {
                    rec.ga = `${pre.version} → ${e.version} (promoted from PRERELEASE)`;
                    // `current` marks the one release the site points people at. The entry
                    // being promoted has carried current: false since it was a milestone, so
                    // without this the GA of a whole new line would ship marked not-current
                    // while the previous line kept the flag. An ordinary GA release never hits
                    // this: it edits an entry that already holds the flag.
                    //
                    // Done over the entry blocks rather than by regex around the version,
                    // because field order is not consistent across these files - most write
                    // version first, spring-cli writes it last - so "the current after this
                    // version" is not a safe thing to match on.
                    const curLines = text.split('\n');
                    const curBlocks = entryBlocks(curLines);
                    if (curBlocks.length === list.length) {
                      const promoted = list.indexOf(pre);
                      let flagged = false;
                      for (let bi = 0; bi < list.length; bi++) {
                        const want = bi === promoted;
                        for (let ln = curBlocks[bi].start; ln <= curBlocks[bi].end; ln++) {
                          const next = curLines[ln].replace(
                            /^(\s*"current"\s*:\s*)(?:true|false)/, `$1${want}`);
                          if (next !== curLines[ln]) { curLines[ln] = next; flagged = true; }
                        }
                      }
                      // A file with no current field anywhere is left exactly as it was.
                      if (flagged) text = curLines.join('\n');
                    } else {
                      problem(`${rel}: could not line up entries to move the 'current' flag ` +
                        `onto ${e.version} - set it by hand.`);
                    }
                  } else {
                    rec.status = 'ambiguous';
                  }
                } else {
                  rec.prerelease = `${pre.version} superseded by ${e.version}`;
                  problem(`${rel}: the ${target} line has both a GENERAL_AVAILABILITY entry ` +
                    `and a PRERELEASE entry for ${pre.version}. The GA entry was updated; ` +
                    'remove the stale pre-release entry by hand.');
                }
              }
              if (snap && nextSnap && snap.version !== nextSnap) {
                if (replaceVersion(snap.version, nextSnap)) {
                  rec.snapshot = `${snap.version} → ${nextSnap}`;
                } else {
                  rec.status = 'ambiguous';
                }
              }
            }

            if (rec.status === 'needs-entry') {
              // ── first pre-release of a new line: clone an entry for it ──────────────
              // Same shape as the commercial path above and for the same reason: these
              // files have no single entry shape to assemble from fields, so the newest
              // entry that already looks right is copied as text.
              const lines = text.split('\n');
              const blocks = entryBlocks(lines);
              if (blocks.length !== list.length) {
                rec.status = 'unrecognised-format';
                console.log(`${rel}: not one block per entry - left alone.`);
                continue;
              }

              // Which entry to copy, and it matters which. On this site a pre-release entry's
              // ref is keyed to the *line*, not the version - spring-data-jpa carries
              //
              //   PRERELEASE  4.2.0-M1        ref .../reference/4.2/
              //   SNAPSHOT    4.2.0-SNAPSHOT  ref .../reference/4.2-SNAPSHOT/
              //
              // so the same line's SNAPSHOT entry is the right template: it is the only entry
              // already pointing at this line, and turning it into the pre-release entry is
              // one substitution, `<line>-SNAPSHOT` -> `<line>`. Cloning a previous line's GA
              // entry instead would leave the ref on that line - substituting 5.0.5 -> 5.1.0-M1
              // never touches a ref that reads .../reference/5.0/ - and quietly point the new
              // milestone at the old line's documentation.
              const snapAnchor = list.findIndex(x => x.status === 'SNAPSHOT' && onLine(x));

              // Fallback for a line with no snapshot entry yet. The line token is substituted
              // as well as the version, so the ref still lands on the right line.
              const versionInRef = x => {
                const ref = x.ref || '';
                return ref.includes('{version}') || (!!x.version && ref.includes(x.version));
              };
              const gaCandidates = list
                .map((x, i) => i)
                .filter(i => list[i].status === 'GENERAL_AVAILABILITY' &&
                  NUMERIC.test(list[i].version || '') && !versionInRef(list[i]));
              const gaAnchor = gaCandidates.reduce(
                (best, i) => (best < 0 || cmp(list[i].version, list[best].version) > 0 ? i : best),
                -1);

              const anchor = snapAnchor >= 0 ? snapAnchor : gaAnchor;
              if (anchor < 0) {
                rec.status = 'no-template';
                console.log(`${rel}: no ${target} snapshot entry and no released Antora entry ` +
                  'to clone one from - skipped.');
                continue;
              }

              const template = list[anchor];
              const fromLine = lineOf(template.version);
              let block = lines.slice(blocks[anchor].start, blocks[anchor].end + 1);
              if (snapAnchor >= 0) {
                // 5.1-SNAPSHOT -> 5.1 in ref and api. Bounded on the left so 15.1 cannot match.
                const snapToken = new RegExp(
                  `(?<![\\d.])${fromLine.replace(/\./g, '\\.')}-SNAPSHOT`, 'g');
                block = block.map(l => l.replace(snapToken, fromLine));
              } else {
                const lineToken = new RegExp(
                  `(?<![\\d.])${fromLine.replace(/\./g, '\\.')}(?![\\d.])`, 'g');
                const bounded = new RegExp(
                  `(?<![\\d.])${template.version.replace(/\./g, '\\.')}(?![\\d.])`, 'g');
                block = block.map(l => l.replace(bounded, e.version).replace(lineToken, target));
              }

              // version, status and current are set rather than substituted: the version field
              // must end up exactly this release whatever the template held, the template's
              // status is SNAPSHOT or GENERAL_AVAILABILITY and either would misdescribe this
              // entry, and `current` marks the one release a project points people at - which
              // a milestone never is. Every PRERELEASE entry on the site reads current: false.
              block = block.map(l => l
                .replace(/^(\s*"version"\s*:\s*")[^"]*(")/, `$1${e.version}$2`)
                .replace(/^(\s*"status"\s*:\s*")[A-Z_]+(")/, '$1PRERELEASE$2')
                .replace(/^(\s*"current"\s*:\s*)(?:true|false)/, '$1false'));

              const rendered = block.join('\n');
              if (!/"status"\s*:\s*"PRERELEASE"/.test(rendered) ||
                  !new RegExp(`"version"\\s*:\\s*"${e.version.replace(/\./g, '\\.')}"`).test(rendered)) {
                rec.status = 'no-template';
                console.log(`${rel}: the ${template.version} entry has no version or status ` +
                  'field to set - left alone.');
                continue;
              }

              // Newest first or oldest first differs by file, so the new entry goes on
              // whichever end already holds the newest version. Anything else reorders the
              // file around it.
              const newestFirst = list.length > 1 &&
                cmp(list[0].version || '0', list[list.length - 1].version || '0') > 0;
              if (newestFirst) {
                block[block.length - 1] = '  },';
                lines.splice(blocks[0].start, 0, ...block);
              } else if (lines[blocks[list.length - 1].end] === '  }') {
                lines[blocks[list.length - 1].end] = '  },';
                block[block.length - 1] = '  }';
                lines.splice(blocks[list.length - 1].end + 1, 0, ...block);
              } else {
                block[block.length - 1] = '  },';
                lines.splice(blocks[list.length - 1].end + 1, 0, ...block);
              }

              // The splice is a text edit, so prove the result is still the same JSON plus
              // one entry before writing it.
              const updated = lines.join('\n');
              let check = null;
              try { check = JSON.parse(updated); } catch (err) { /* check stays null */ }
              if (!check || check.length !== list.length + 1 ||
                  !check.some(x => x.version === e.version && x.status === 'PRERELEASE')) {
                rec.status = 'error';
                console.log(`${rel}: the edit did not produce the expected JSON - left alone.`);
                continue;
              }

              fs.writeFileSync(file, updated);
              rec.status = 'added';
              rec.prerelease = `added ${e.version}, cloned from ${template.version}`;
              rec.from = template.version;
              console.log(`${rel}: added ${e.version} as PRERELEASE, cloned from ` +
                `${template.version} - first ${target} entry`);
              continue;
            }

            if (text !== original) {
              fs.writeFileSync(file, text);
              if (rec.status === 'unchanged') rec.status = 'updated';
            }
            console.log(`${rel}: ${rec.status}` +
              `${rec.ga ? ` · GA ${rec.ga}` : ''}` +
              `${rec.prerelease ? ` · pre-release ${rec.prerelease}` : ''}` +
              `${rec.snapshot ? ` · ${rec.snapshot}` : ''}`);
          }

          // ── e. commit, push, open the PR ────────────────────────────────────────────
          git(['config', 'user.name', 'Spring Builds'], 'website');
          git(['config', 'user.email', 'svc.spring-builds@broadcom.com'], 'website');
          git(['checkout', '--quiet', '-b', branch], 'website');
          git(['add', '-A'], 'website');

          const staged = git(['diff', '--cached', '--name-only'], 'website').trim();
          if (!staged) {
            finish('no-changes',
              'The site already documents these versions - nothing to do.');
          }

          console.log('');
          console.log('Files to change:');
          console.log(staged);
          fs.writeFileSync('website-changes.diff', git(['diff', '--cached'], 'website'));

          // ── e1. the diff, in this job's summary ─────────────────────────────────────
          // The whole point of a dry run is seeing what would change, and the artifact makes
          // that a download-and-unzip. One collapsed block per file, so a sixteen-project run
          // is still a list you can scan.
          const summaryFile = process.env.GITHUB_STEP_SUMMARY;
          if (summaryFile) {
            // Anything fenced has to be fenced with more backticks than it contains - the blog
            // post is full of ``` blocks of its own.
            const fenceFor = text => {
              let longest = 0;
              for (const m of text.match(/`+/g) || []) longest = Math.max(longest, m.length);
              return '`'.repeat(Math.max(3, longest + 1));
            };

            // added/deleted counts per file, so each block says how big it is before you open
            // it. A binary file reports '-', which is why these are not parsed as numbers.
            const stats = {};
            for (const line of git(['diff', '--cached', '--numstat'], 'website').split('\n')) {
              const m = line.match(/^(\S+)\t(\S+)\t(.+)$/);
              if (m) stats[m[3]] = { added: m[1], deleted: m[2] };
            }

            const S = [];
            S.push(`## Website changes${dryRun ? ' — dry run, nothing was pushed' : ''}`);
            S.push('');
            S.push(`\`${WEBSITE}\` · \`${branch}\` · ${Object.keys(stats).length} file(s)`);
            S.push('');

            // GitHub rejects a step summary over 1 MiB outright, which would lose the whole
            // report rather than the tail of it, so this stops short and says what it dropped.
            const BUDGET = 900000;
            let used = S.join('\n').length;
            let omitted = 0;

            for (const file of staged.split('\n').filter(Boolean)) {
              const body = git(['diff', '--cached', '--', file], 'website');
              const st = stats[file] || { added: '?', deleted: '?' };
              const f = fenceFor(body);
              const block = [
                `<details><summary><code>${file}</code> — +${st.added} −${st.deleted}</summary>`,
                '',
                `${f}diff`,
                body.replace(/\n+$/, ''),
                f,
                '',
                '</details>',
                '',
              ].join('\n');
              if (used + block.length > BUDGET) {
                omitted++;
                continue;
              }
              used += block.length;
              S.push(block);
            }

            if (omitted) {
              S.push(`_${omitted} file(s) left out to stay inside GitHub's summary size ` +
                'limit — the complete diff is in the `website-changes` artifact._');
              S.push('');
            }

            fs.appendFileSync(summaryFile, S.join('\n') + '\n');
            console.log(`Wrote the diff to this job's summary${omitted ? ` (${omitted} file(s) omitted)` : ''}.`);
          }

          const title = commercial
            ? `Update documentation for Spring Cloud ${releaseVersion} commercial release`
            : `Spring Cloud ${releaseVersion} release updates`;

          const P = [];
          P.push(`Generated by the [post release workflow](${runUrl}) for Spring Cloud ` +
            `${releaseVersion}${commercial ? ' (commercial)' : ''}.`);
          P.push('');
          // Only when this run wrote the post. When one already existed the PR is nothing but
          // documentation.json bumps, and a checklist about a file it does not touch would
          // send whoever reviews it looking for placeholders that are not there.
          if (result.blogStatus === 'created') {
            P.push('### Before merging');
            P.push('');
            P.push('Everything the workflow could not derive is left as a placeholder in ' +
              `\`${blogFile}\`, in the order it appears:`);
            P.push('');
            P.push('- [ ] `author: TODO` in the front matter — whoever is writing the post up');
            P.push(`- [ ] \`publishedAt: ${today}\` — the date this ran, so change it if the ` +
              'post goes out on another day');
            P.push(`- [ ] \`${CODENAME}\` in the title — the release train codename, and rename ` +
              `the file to \`spring-cloud-${dashed}-aka-<codename>-has-been-released.md\``);
            P.push('- [ ] The Spring Boot line — generated from the `spring-boot` entry in the ' +
              'properties file, so it only says which version the train is based on');
            P.push('- [ ] A `TODO` under every project heading in **Notable Changes** — there is ' +
              'one heading per project whose version changed in this release, and any with ' +
              'nothing worth calling out should just be deleted');
            P.push('');
          } else if (result.blogStatus === 'already-exists') {
            P.push(`A post for ${releaseVersion} already exists (\`${result.blogFile}\`), so ` +
              'this PR only carries the documentation versions.');
            P.push('');
          }
          // `added` is the commercial site's shape: a new GA entry appended per release. The
          // OSS site is edited in place, and the new PRERELEASE entry an M1 creates there is
          // reported through `prerelease` alongside the other in-place changes.
          const added = commercial ? result.docs.filter(d => d.status === 'added') : [];
          const bumped = result.docs.filter(d => d.ga || d.snapshot || d.prerelease);
          const anyPrerelease = bumped.some(d => d.prerelease);
          if (added.length) {
            P.push('### documentation.json');
            P.push('');
            P.push('One new `GENERAL_AVAILABILITY` entry per project released in this train, ' +
              'each cloned from an existing entry so it keeps that project\'s `ref` and ' +
              '`githubTag` conventions — the newest on the same line, or the newest with an ' +
              'Antora `ref` when the line is new.');
            P.push('');
            P.push('| Project | Added | Cloned from |');
            P.push('|---|---|---|');
            for (const d of added) {
              // Cloning across lines is normal for the first release of a line and needs no
              // comment - the ref it copied carries no version, so it is right as it stands.
              // Having had nothing but pre-Antora entries to clone from does need one.
              P.push(`| \`${d.project}\` | ${d.added} | ${d.from}` +
                `${d.legacyTemplate ? ' — **only pre-Antora `ref`s in this file, check it**' : ''} |`);
            }
            P.push('');
          }
          if (bumped.length) {
            P.push('### documentation.json');
            P.push('');
            // The Pre-release column only appears when there is something to put in it, so a
            // plain GA run keeps the two-column table.
            P.push(`| Project | General availability |${anyPrerelease ? ' Pre-release |' : ''} Snapshot |`);
            P.push(`|---|---|${anyPrerelease ? '---|' : ''}---|`);
            for (const d of bumped) {
              P.push(`| \`${d.project}\` | ${d.ga || '—'} |` +
                `${anyPrerelease ? ` ${d.prerelease || '—'} |` : ''} ${d.snapshot || '—'} |`);
            }
            P.push('');
          }
          const problemDocs = result.docs.filter(d =>
            d.status === 'ambiguous' || d.status === 'unparseable' || d.status === 'no-entry' ||
            d.status === 'unrecognised-format' || d.status === 'no-template' ||
            d.status === 'error');
          if (problemDocs.length) {
            P.push('### Needs a look');
            P.push('');
            for (const d of problemDocs) P.push(`- \`${d.file}\` — ${d.status}`);
            P.push('');
          }
          const body = P.join('\n');

          if (dryRun) {
            console.log('');
            console.log('[dry run] would open this PR:');
            console.log('---');
            console.log(body);
            console.log('---');
            console.log('[dry run] not pushing. The diff is in this job\'s summary, and in ' +
              'the website-changes artifact.');
            finish('would-create');
          }

          git(['commit', '--quiet', '-m', title], 'website');
          git(['push', '--quiet', 'origin', `HEAD:refs/heads/${branch}`], 'website');
          console.log(`Pushed ${branch} to ${WEBSITE}.`);

          fs.writeFileSync('pr-body.md', body);
          result.prUrl = gh(['pr', 'create', '--repo', WEBSITE, '--base', BASE, '--head', branch,
            '--title', title, '--body-file', 'pr-body.md']).trim().split('\n').pop();
          console.log(`Opened ${result.prUrl}`);
          finish('created');
          JSEOF

      # The script writes its own result on every path it exits through deliberately; this
      # covers the one it does not - an exception - so the summary still gets a row rather
      # than quietly omitting the website from a red run.
      - name: Record failure
        if: failure()
        run: |
          set -euo pipefail
          if [[ ! -f result-website.json ]]; then
            printf '%s' '{"phase":"website-pr","status":"error"}' > result-website.json
          fi

      - name: Upload result
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: result-website
          path: result-website.json
          if-no-files-found: ignore

      # Separate from the result artifact, which the summary job downloads and parses - this
      # one is only ever read by a person, and on a dry run it is the whole point of the run.
      - name: Upload the diff
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: website-changes
          path: website-changes.diff
          if-no-files-found: ignore

  # ── start.spring.io ──────────────────────────────────────────────────────────────────
  # A one-line PR against start.spring.io bumping the Spring Cloud version the Initializr
  # offers, on a branch named <version>-release.
  #
  # OSS only: start.spring.io serves the public Initializr, and a commercial version has
  # no place in it.
  #
  # The version lives in one mapping under the spring-cloud bom, each mapping pinning a
  # Spring Cloud version to a range of Spring Boot versions:
  #
  #   spring-cloud:
  #     artifactId: spring-cloud-dependencies
  #     mappings:
  #       - compatibilityRange: "[4.0.0,4.2.0-M1)"
  #         version: 2025.1.2
  #
  # This bumps the mapping already on the released train's line and nothing else. When that
  # line has no mapping at all - a new train line, or one whose Boot range has aged off the
  # site, as 2025.0 has - the compatibilityRange a new mapping needs is a judgement nobody
  # here can make, so the run reports it and opens no PR.
  start-site-pr:
    name: start.spring.io PR
    needs: [setup, verify-tags, milestones-and-releases]
    if: |
      !cancelled() &&
      needs.verify-tags.result == 'success' &&
      needs.setup.outputs.commercial != 'true' &&
      needs.setup.outputs.hotfix != 'true' &&
      inputs.skip_start_site_pr != true &&
      inputs.projects == ''
    runs-on: ubuntu-latest
    steps:
      # Only so the script below can require .github/scripts/.
      - uses: actions/checkout@v4

      - name: Bump the Spring Cloud version and open the PR
        id: run
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          RELEASE_VERSION: ${{ inputs.release_version }}
          ENTRIES: ${{ needs.setup.outputs.entries }}
          DRY_RUN: ${{ inputs.dry_run }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const path = require('path');
          const { execFileSync } = require('child_process');

          const { updateMappings } = require(path.join(process.env.GITHUB_WORKSPACE,
            '.github', 'scripts', 'start-site-mappings.js'));

          const token = process.env.GH_TOKEN;
          const releaseVersion = process.env.RELEASE_VERSION;
          const dryRun = process.env.DRY_RUN === 'true';
          const runUrl = process.env.RUN_URL || '';

          // The compatibility range is anchored on the Spring Boot version this train is
          // built against, which is in the same properties file as everything else.
          const entries = JSON.parse(process.env.ENTRIES || '[]');
          const bootVersion = (entries.find(e => e.key === 'spring-boot') || {}).version || '';

          // Filled in by whichever branch of the edit runs, so the summary and the PR body
          // do not have to re-derive what changed.
          let changeDetail = '';

          const REPO = 'spring-io/start.spring.io';
          const BASE = 'main';
          const FILE = 'start-site/src/main/resources/application.yml';

          const gh = args => execFileSync('gh', args,
            { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
          const git = (args, cwd) => execFileSync('git', args,
            { encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'] });

          const branch = `${releaseVersion}-release`;
          const result = {
            phase: 'start-site-pr', repo: REPO, branch, file: FILE, status: 'skipped',
            from: '', to: releaseVersion, prUrl: '', mappings: [],
          };
          const out = process.env.GITHUB_OUTPUT;
          const finish = (status, message) => {
            if (message) console.log(message);
            result.status = status;
            fs.writeFileSync('result-startsite.json', JSON.stringify(result));
            fs.appendFileSync(out, `status=${status}\n`);
            process.exit(0);
          };

          // ── a. is there already a branch for this release? ──────────────────────────
          let branchExists = false;
          try {
            gh(['api', `repos/${REPO}/branches/${branch}`, '--jq', '.name']);
            branchExists = true;
          } catch (err) { /* no branch yet */ }

          if (branchExists) {
            try {
              const prs = JSON.parse(gh(['api',
                `repos/${REPO}/pulls?head=spring-io:${branch}&state=all&per_page=1`]));
              if (prs.length) result.prUrl = prs[0].html_url;
            } catch (err) { /* leave the url empty */ }
            finish('branch-exists',
              `${branch} already exists in ${REPO} - leaving it alone. ${result.prUrl}`);
          }

          // ── b. find the mapping for this train line ─────────────────────────────────
          console.log(`Cloning ${REPO}@${BASE}...`);
          git(['clone', '--quiet', '--depth', '1', '--branch', BASE,
            `https://x-access-token:${token}@github.com/${REPO}.git`, 'start']);

          const filePath = `start/${FILE}`;
          if (!fs.existsSync(filePath)) {
            finish('file-not-found', `${FILE} is not in ${REPO} - it has moved.`);
          }

          const original = fs.readFileSync(filePath, 'utf8');
          const edit = updateMappings(original, { releaseVersion, bootVersion });
          result.mappings = edit.mappings || [];
          console.log(`Versions currently mapped: ${result.mappings.join(', ') || 'none'}`);
          if (edit.status !== 'edited') {
            if (edit.from) result.from = edit.from;
            finish(edit.status, edit.message);
          }

          result.from = edit.from;
          result.action = edit.action;
          if (edit.action === 'added') result.added = [releaseVersion, edit.snapshotTo];
          if (edit.snapshotTo) { result.snapshotFrom = edit.snapshotFrom; result.snapshotTo = edit.snapshotTo; }
          changeDetail = edit.changeDetail;
          console.log(`Spring Boot ${bootVersion}: ${changeDetail}`);

          fs.writeFileSync(filePath, edit.text);

          git(['config', 'user.name', 'Spring Builds'], 'start');
          git(['config', 'user.email', 'svc.spring-builds@broadcom.com'], 'start');
          git(['checkout', '--quiet', '-b', branch], 'start');
          git(['add', '-A'], 'start');

          const diff = git(['diff', '--cached'], 'start');
          console.log('');
          console.log(diff);

          const summaryFile = process.env.GITHUB_STEP_SUMMARY;
          if (summaryFile) {
            fs.appendFileSync(summaryFile, [
              `## start.spring.io${dryRun ? ' — dry run, nothing was pushed' : ''}`,
              '',
              `\`${REPO}\` · \`${branch}\` · \`${FILE}\`: ${changeDetail}`,
              '',
              '```diff',
              diff.replace(/\n+$/, ''),
              '```',
              '',
            ].join('\n'));
          }

          const title = `Upgrade to Spring Cloud ${releaseVersion}`;
          const body = [
            `Generated by the [post release workflow](${runUrl}).`,
            '',
            `Spring Cloud ${releaseVersion} has been released, so the \`spring-cloud\` bom ` +
              `${changeDetail}.`,
            '',
            result.action === 'added'
              ? 'Two mappings, because this train is offered on two Spring Boot lines: the ' +
                'released version for Boot ' + bootVersion.replace(/-.*$/, '') + ', and the ' +
                'train snapshot for that line\'s snapshots. Only the snapshot mapping names a ' +
                'repository - Spring Boot 4.0 and up publishes milestones to Maven Central, so ' +
                'the released mapping resolves without one, matching the other pre-release ' +
                'entries in this file.'
              : 'The `compatibilityRange` only moves at GA, when it widens to the next Spring ' +
                'Boot minor; the milestone floor stays at `-M1` through the release candidates. ' +
                'Between two GA releases only the version changes. At GA ' +
                'the line\'s `-SNAPSHOT` mapping, where there is one, moves on to the next patch.',
            '',
            'Mappings for earlier trains are deliberately untouched; they use the previous ' +
            'single-entry convention.',
          ].join('\n');

          if (dryRun) {
            console.log(`[dry run] would open '${title}' from ${branch}.`);
            finish('would-create');
          }

          git(['commit', '--quiet', '-m', title], 'start');
          git(['push', '--quiet', 'origin', `HEAD:refs/heads/${branch}`], 'start');
          console.log(`Pushed ${branch} to ${REPO}.`);

          fs.writeFileSync('pr-body.md', body);
          result.prUrl = gh(['pr', 'create', '--repo', REPO, '--base', BASE, '--head', branch,
            '--title', title, '--body-file', 'pr-body.md']).trim().split('\n').pop();
          console.log(`Opened ${result.prUrl}`);
          finish('created');
          JSEOF

      # As in the website job: the script records a result on every path it exits through
      # deliberately, and this covers the one it does not.
      - name: Record failure
        if: failure()
        run: |
          set -euo pipefail
          if [[ ! -f result-startsite.json ]]; then
            printf '%s' '{"phase":"start-site-pr","status":"error"}' > result-startsite.json
          fi

      - name: Upload result
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: result-startsite
          path: result-startsite.json
          if-no-files-found: ignore

  # ── The release train's project board ────────────────────────────────────────────────
  # Rolls the org-level GitHub Project from the train just released to the next one:
  # copies the board, carries the unfinished work over, and closes the old one.
  #
  # OSS only - the boards are OSS by design, the same assumption dependabot-scan makes -
  # and never on a filtered run, since the board covers the whole train.
  #
  # Runs after new-milestones because carrying an item over re-milestones it, and the
  # milestone it moves to is the one that job opens.
  release-board:
    name: Release Board
    needs: [setup, verify-tags, next-snapshot-config, new-milestones]
    if: |
      !cancelled() &&
      (needs.next-snapshot-config.result == 'success' ||
       needs.setup.outputs.prerelease == 'true') &&
      needs.setup.outputs.commercial != 'true' &&
      needs.setup.outputs.hotfix != 'true' &&
      inputs.skip_release_board != true &&
      inputs.projects == ''
    runs-on: ubuntu-latest
    steps:
      - name: Roll the board over to the next release
        id: run
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          RELEASE_VERSION: ${{ inputs.release_version }}
          NEXT_VERSION: ${{ needs.setup.outputs.next-version }}
          ENTRIES: ${{ needs.setup.outputs.entries }}
          NEXT_VERSIONS: ${{ needs.setup.outputs.prerelease == 'true'
            && needs.setup.outputs.next-versions
            || needs.next-snapshot-config.outputs.versions }}
          # The columns whose contents follow the train. Anything else - Done, and whatever
          # else a board has grown - stays on the board being closed.
          CARRY_OVER_COLUMNS: 'Todo,In Progress'
          DRY_RUN: ${{ inputs.dry_run }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const { execFileSync } = require('child_process');

          const ORG = 'spring-cloud';
          const releaseVersion = process.env.RELEASE_VERSION;
          const nextVersion = process.env.NEXT_VERSION;
          const dryRun = process.env.DRY_RUN === 'true';
          const runUrl = process.env.RUN_URL || '';
          const entries = JSON.parse(process.env.ENTRIES || '[]');
          const nextVersions = JSON.parse(process.env.NEXT_VERSIONS || '{}');
          const carryOver = (process.env.CARRY_OVER_COLUMNS || 'Todo,In Progress')
            .split(',').map(s => s.trim()).filter(Boolean);

          // Whatever the old board had, a release board is always these. Read teams are given the
          // middle role, because the API can say which teams a board is linked to but not what any
          // of them is allowed to do - see README-post-release.md.
          const REQUIRED_TEAMS = [
            { slug: 'spring-cloud-core-developers', role: 'ADMIN' },
            { slug: 'spring-cloud-core', role: 'WRITER' },
          ];
          const INHERITED_TEAM_ROLE = 'WRITER';

          const result = {
            phase: 'release-board', org: ORG, from: releaseVersion, to: nextVersion,
            status: 'skipped', columns: carryOver, boardUrl: '', boardCreated: false,
            teams: [], moved: [], milestones: [], problems: [], closedOld: false, drafts: 0,
          };
          const out = process.env.GITHUB_OUTPUT;
          const finish = (status, message) => {
            if (message) console.log(message);
            result.status = status;
            fs.writeFileSync('result-board.json', JSON.stringify(result));
            if (out) {
              fs.appendFileSync(out, `status=${status}\n`);
              fs.appendFileSync(out, `board-url=${result.boardUrl}\n`);
            }
            process.exit(0);
          };

          // ── plumbing ─────────────────────────────────────────────────────────────────
          // Variables go through a file rather than gh's -f/-F flags, which only carry scalars -
          // updateProjectV2Collaborators takes an array of objects.
          let seq = 0;
          const graphql = (query, variables) => {
            const file = `gql-${++seq}.json`;
            fs.writeFileSync(file, JSON.stringify({ query, variables: variables || {} }));
            let raw;
            try {
              raw = execFileSync('gh', ['api', 'graphql', '--input', file],
                { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
            } catch (err) {
              // gh exits non-zero on a GraphQL error but still prints the response body, which is
              // where the useful message is.
              raw = err.stdout || '';
              if (!raw) throw new Error((err.stderr || err.message || '').split('\n')[0]);
            } finally {
              try { fs.unlinkSync(file); } catch (e) { /* nothing to clean up */ }
            }
            const body = JSON.parse(raw);
            if (body.errors) throw new Error(body.errors.map(e => e.message).join('; '));
            return body.data;
          };

          const gh = args => execFileSync('gh', args,
            { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });

          const problem = msg => { console.log(`  ! ${msg}`); result.problems.push(msg); };

          // ── a. find the two boards ───────────────────────────────────────────────────
          // By title, which is how every other workflow here resolves a release board (see
          // dependabot-scan). Paged rather than first:100 - the org is past its hundredth project.
          //
          // The page cap is a guard against looping forever, not a limit anybody expects to
          // reach, so hitting it is reported rather than swallowed: a partial listing cannot
          // tell "no board with this title" from "did not get that far", and this function is
          // what stands between a re-run and a second board for the same release.
          const boardsByTitle = () => {
            const map = new Map();
            let after = null;
            let complete = false;
            for (let page = 0; page < 20; page++) {
              const c = graphql(`query($login:String!,$after:String){
                organization(login:$login){
                  projectsV2(first:100, after:$after){
                    pageInfo{ hasNextPage endCursor }
                    nodes{ id number title url closed public }
                  }
                }
              }`, { login: ORG, after }).organization.projectsV2;
              for (const n of c.nodes) if (!map.has(n.title)) map.set(n.title, n);
              if (!c.pageInfo.hasNextPage) { complete = true; break; }
              after = c.pageInfo.endCursor;
            }
            map.complete = complete;
            return map;
          };

          console.log(`Looking for boards '${releaseVersion}' and '${nextVersion}' in ${ORG}...`);
          const boards = boardsByTitle();
          if (!boards.complete) {
            finish('board-listing-incomplete',
              `Only ${boards.size} project(s) could be listed for ${ORG} before the page cap was ` +
              'reached, so whether a board titled ' + `'${nextVersion}' already exists cannot be ` +
              'established. Nothing was created or changed - raise the cap and re-run.');
          }
          const oldBoard = boards.get(releaseVersion);
          if (!oldBoard) {
            finish('no-old-board',
              `No board titled '${releaseVersion}' in ${ORG} - nothing to carry over or close.`);
          }
          console.log(`Old board: #${oldBoard.number} ${oldBoard.url}${oldBoard.closed ? ' (closed)' : ''}`);

          // ── b. the new board ─────────────────────────────────────────────────────────
          const orgId = graphql('query($login:String!){ organization(login:$login){ id } }',
            { login: ORG }).organization.id;

          let newBoard = boards.get(nextVersion);
          if (newBoard) {
            // A re-run, or someone made it by hand. Either way it is the board to fill.
            console.log(`New board already exists: #${newBoard.number} ${newBoard.url}`);
          } else if (dryRun) {
            console.log(`[dry run] would copy #${oldBoard.number} to a new board titled '${nextVersion}'.`);
          } else {
            // Listed again immediately before the mutation. The listing above happens before the
            // teams, fields and items work, which takes minutes on a full train - long enough for
            // a concurrent run, or someone reading the same release notes, to have made the board
            // in between. copyProjectV2 will happily create a second one with the same title.
            const fresh = boardsByTitle();
            if (!fresh.complete) {
              finish('board-listing-incomplete',
                'The project listing could not be completed on the re-check before creating ' +
                `'${nextVersion}'. Nothing was created.`);
            }
            const raced = fresh.get(nextVersion);
            if (raced) {
              finish('board-created-elsewhere',
                `A board titled '${nextVersion}' appeared while this job was running ` +
                `(#${raced.number} ${raced.url}). Nothing was created - re-run to fill it.`);
            }

            // A copy rather than a fresh project: GitHub carries the views, custom fields,
            // configured workflows and insights across, which is the whole of "modelled after the
            // old one". It does not carry items, collaborators or team links - hence the rest.
            const copied = graphql(`mutation($src:ID!,$owner:ID!,$title:String!){
              copyProjectV2(input:{projectId:$src,ownerId:$owner,title:$title,includeDraftIssues:false}){
                projectV2{ id number title url public }
              }
            }`, { src: oldBoard.id, owner: orgId, title: nextVersion }).copyProjectV2.projectV2;
            newBoard = copied;
            result.boardCreated = true;
            console.log(`Created #${copied.number} ${copied.url}`);
          }
          if (newBoard) result.boardUrl = newBoard.url;

          // ── c. public, and who can use it ────────────────────────────────────────────
          if (newBoard && !newBoard.public && !dryRun) {
            graphql('mutation($id:ID!){ updateProjectV2(input:{projectId:$id,public:true}){ projectV2{ id } } }',
              { id: newBoard.id });
            console.log('Made the board public.');
          }

          const oldTeams = graphql(`query($id:ID!){ node(id:$id){ ... on ProjectV2 {
            teams(first:50){ nodes{ id slug name } } } } }`, { id: oldBoard.id }).node.teams.nodes;
          console.log(`Teams linked to the old board: ${oldTeams.map(t => t.slug).join(', ') || 'none'}`);

          const collaborators = new Map();
          for (const t of oldTeams) {
            collaborators.set(t.slug, { teamId: t.id, role: INHERITED_TEAM_ROLE, why: 'from the old board' });
          }
          for (const req of REQUIRED_TEAMS) {
            let id = null;
            try {
              id = graphql('query($login:String!,$slug:String!){ organization(login:$login){ team(slug:$slug){ id } } }',
                { login: ORG, slug: req.slug }).organization.team?.id || null;
            } catch (err) {
              problem(`could not look up team ${req.slug}: ${err.message}`);
            }
            if (!id) { problem(`team ${req.slug} not found in ${ORG} - not granted`); continue; }
            collaborators.set(req.slug, { teamId: id, role: req.role, why: 'always on a release board' });
          }

          result.teams = [...collaborators.entries()].map(([slug, c]) => ({ slug, role: c.role, why: c.why }));
          for (const t of result.teams) console.log(`  ${t.slug}: ${t.role} (${t.why})`);

          if (newBoard && !dryRun && collaborators.size) {
            graphql(`mutation($id:ID!,$c:[ProjectV2Collaborator!]!){
              updateProjectV2Collaborators(input:{projectId:$id,collaborators:$c}){ collaborators{ totalCount } }
            }`, {
              id: newBoard.id,
              c: [...collaborators.values()].map(c => ({ teamId: c.teamId, role: c.role })),
            });
            console.log(`Granted ${collaborators.size} team(s) access.`);
          }

          // ── d. the Status field on each board ────────────────────────────────────────
          // Found by shape rather than by name: the single-select field carrying the columns being
          // carried over. A board whose field is called something other than Status still works,
          // and one whose options have been renamed is reported instead of half-moved.
          const statusField = board => {
            const fields = graphql(`query($id:ID!){ node(id:$id){ ... on ProjectV2 {
              fields(first:50){ nodes{
                ... on ProjectV2SingleSelectField{ id name options{ id name } } } } } } }`,
              { id: board.id }).node.fields.nodes.filter(f => f && f.options);
            const named = fields.find(f => f.name === 'Status');
            const byOptions = fields.find(f =>
              carryOver.every(c => f.options.some(o => o.name === c)));
            return byOptions || named || null;
          };

          const oldStatus = statusField(oldBoard);
          if (!oldStatus) finish('no-status-field', `Could not find a single-select column field on '${releaseVersion}'.`);
          const missing = carryOver.filter(c => !oldStatus.options.some(o => o.name === c));
          if (missing.length) {
            finish('unknown-columns',
              `'${releaseVersion}' has no ${missing.map(m => `'${m}'`).join(' or ')} column ` +
              `(it has: ${oldStatus.options.map(o => o.name).join(', ')}).`);
          }

          const newStatus = newBoard ? statusField(newBoard) : null;
          if (newBoard && !newStatus) {
            finish('no-status-field', `Could not find a single-select column field on '${nextVersion}'.`);
          }

          // ── e. what is on the old board ──────────────────────────────────────────────
          const items = [];
          let after = null;
          for (let page = 0; page < 50; page++) {
            const c = graphql(`query($id:ID!,$after:String){ node(id:$id){ ... on ProjectV2 {
              items(first:100, after:$after){
                pageInfo{ hasNextPage endCursor }
                nodes{
                  id type
                  fieldValueByName(name:"Status"){ ... on ProjectV2ItemFieldSingleSelectValue{ name } }
                  content{
                    __typename
                    ... on Issue{ id number title state milestone{ title number state } repository{ name owner{ login } } }
                    ... on PullRequest{ id number title state milestone{ title number state } repository{ name owner{ login } } }
                  }
                }
              } } } }`, { id: oldBoard.id, after }).node.items;
            items.push(...c.nodes);
            if (!c.pageInfo.hasNextPage) break;
            after = c.pageInfo.endCursor;
          }
          console.log(`\n${items.length} item(s) on '${releaseVersion}'.`);

          const wanted = items.filter(i => carryOver.includes(i.fieldValueByName?.name));
          const drafts = wanted.filter(i => i.type === 'DRAFT_ISSUE' || !i.content?.id);
          result.drafts = drafts.length;
          if (drafts.length) {
            problem(`${drafts.length} draft issue(s) in ${carryOver.join('/')} cannot be moved - ` +
              'drafts belong to a board, not to a repository. Recreate them by hand.');
          }
          const movable = wanted.filter(i => i.content && i.content.id);
          console.log(`${movable.length} to carry over (${carryOver.join(', ')}).`);

          // ── f. milestones ────────────────────────────────────────────────────────────
          // The new milestone for a repo is the version step 3 wrote to the snapshot file, which is
          // what step 4 opened a milestone for. Only set when the item has none, or still carries
          // the train that just shipped - a milestone somebody chose deliberately is left alone.
          const milestoneCache = new Map();
          const milestoneNumber = (owner, repo, title) => {
            const key = `${owner}/${repo}#${title}`;
            if (milestoneCache.has(key)) return milestoneCache.get(key);
            let number = null;
            try {
              // --paginate, and not optional: repositories past a hundred milestones return
              // them oldest-first, so an unpaginated read cannot see the new one.
              const list = JSON.parse(gh(['api', '--paginate', '--slurp',
                `repos/${owner}/${repo}/milestones?state=all&per_page=100`])).flat();
              number = (list.find(m => m.title === title) || {}).number || null;
            } catch (err) { /* reported by the caller */ }
            milestoneCache.set(key, number);
            return number;
          };

          const releasedVersionOf = repo => (entries.find(e => e.key === repo) || {}).version || null;
          const nextMilestoneOf = repo => {
            const v = nextVersions[repo];
            return v ? v.replace(/-SNAPSHOT$/, '') : null;
          };

          // ── g. move ──────────────────────────────────────────────────────────────────
          let moved = 0, failed = 0;
          for (const item of movable) {
            const c = item.content;
            const repo = c.repository.name;
            const owner = c.repository.owner.login;
            const ref = `${owner}/${repo}#${c.number}`;
            const column = item.fieldValueByName.name;
            const record = { ref, title: c.title, column, milestone: '' };

            if (dryRun || !newBoard) {
              console.log(`[dry run] would move ${ref} (${column})`);
            } else {
              try {
                const newItem = graphql(`mutation($p:ID!,$c:ID!){
                  addProjectV2ItemById(input:{projectId:$p,contentId:$c}){ item{ id } } }`,
                  { p: newBoard.id, c: c.id }).addProjectV2ItemById.item;

                const option = newStatus.options.find(o => o.name === column);
                if (!option) throw new Error(`'${nextVersion}' has no '${column}' column`);
                graphql(`mutation($p:ID!,$i:ID!,$f:ID!,$o:String!){
                  updateProjectV2ItemFieldValue(input:{projectId:$p,itemId:$i,fieldId:$f,
                    value:{singleSelectOptionId:$o}}){ projectV2Item{ id } } }`,
                  { p: newBoard.id, i: newItem.id, f: newStatus.id, o: option.id });

                // Added to the new board first and removed from the old second, deliberately: if the
                // second call fails the item is on both boards, which is visible and fixable. The
                // other order can lose it from both.
                graphql('mutation($p:ID!,$i:ID!){ deleteProjectV2Item(input:{projectId:$p,itemId:$i}){ deletedItemId } }',
                  { p: oldBoard.id, i: item.id });
                console.log(`  moved ${ref} (${column})`);
              } catch (err) {
                failed++;
                problem(`${ref}: ${err.message}`);
                result.moved.push(Object.assign(record, { failed: true }));
                continue;
              }
            }

            // ── the milestone ──
            const target = nextMilestoneOf(repo);
            const current = c.milestone?.title || null;
            // A milestone this run declines to touch is not a failure, but it is the one
            // thing here nobody finds out about on their own - the item just sits on the new
            // board wearing an old milestone. So the reason is recorded, along with whether
            // that milestone is closed: an open item pinned to a closed milestone is drift,
            // whereas one pointing at a future release is somebody's decision.
            const leave = why => {
              record.milestone = why;
              record.leftAlone = { current, closed: c.milestone?.state === 'CLOSED', target, why };
            };
            if (!target) {
              if (current) leave(`kept ${current} - ${repo} is not in this train`);
            } else if (current === target) {
              record.milestone = 'already set';
            } else if (current && current !== releasedVersionOf(repo)) {
              leave(`kept ${current} - not the train just released, so left as a choice`);
            } else if (dryRun) {
              record.milestone = `would set to ${target}`;
            } else {
              const number = milestoneNumber(owner, repo, target);
              if (!number) {
                record.milestone = `no ${target} milestone in ${repo}`;
                problem(`${ref}: ${repo} has no '${target}' milestone, so it was left on ${current || 'none'}`);
              } else {
                try {
                  gh(['api', `repos/${owner}/${repo}/issues/${c.number}`, '--method', 'PATCH',
                    '-F', `milestone=${number}`]);
                  record.milestone = `${current || 'none'} → ${target}`;
                } catch (err) {
                  record.milestone = 'failed';
                  problem(`${ref}: could not set the milestone: ${(err.message || '').split('\n')[0]}`);
                }
              }
            }
            if (record.milestone) result.milestones.push({ ref, detail: record.milestone });
            result.moved.push(record);
            moved++;
          }

          // ── h. close the old board ───────────────────────────────────────────────────
          // Only when everything got across. Closing a board that still holds unfinished work hides
          // it, and hiding it is worse than leaving a red run to look at.
          if (failed || drafts.length) {
            console.log(`\nNot closing '${releaseVersion}': ${failed} item(s) failed to move` +
              `${drafts.length ? `, ${drafts.length} draft(s) left behind` : ''}.`);
          } else if (oldBoard.closed) {
            console.log(`\n'${releaseVersion}' is already closed.`);
            result.closedOld = true;
          } else if (dryRun) {
            console.log(`\n[dry run] would close '${releaseVersion}'.`);
          } else {
            graphql('mutation($id:ID!){ updateProjectV2(input:{projectId:$id,closed:true}){ projectV2{ id } } }',
              { id: oldBoard.id });
            console.log(`\nClosed '${releaseVersion}'.`);
            result.closedOld = true;
          }

          console.log(`\n${moved} item(s) ${dryRun ? 'would move' : 'moved'}, ${failed} failed.`);
          finish(dryRun ? 'would-run' : (failed ? 'partial' : 'done'));
          JSEOF

      - name: Record failure
        if: failure()
        run: |
          set -euo pipefail
          if [[ ! -f result-board.json ]]; then
            printf '%s' '{"phase":"release-board","status":"error"}' > result-board.json
          fi

      - name: Upload result
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: result-board
          path: result-board.json
          if-no-files-found: ignore

  summary:
    name: Summary
    needs: [setup, verify-tags, milestones-and-releases, next-snapshot-config, new-milestones, merge-back-and-update, website-pr, start-site-pr, release-board]
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Download results
        continue-on-error: true
        uses: actions/download-artifact@v4
        with:
          pattern: result-*
          merge-multiple: true
          path: results

      - name: Write summary
        id: write-summary
        env:
          RELEASE_VERSION: ${{ inputs.release_version }}
          COMMERCIAL: ${{ needs.setup.outputs.commercial }}
          HOTFIX: ${{ needs.setup.outputs.hotfix }}
          PRERELEASE: ${{ needs.setup.outputs.prerelease }}
          NEXT_VERSION: ${{ needs.setup.outputs.next-version }}
          SNAPSHOT_VERSION: ${{ needs.setup.outputs.snapshot-version }}
          PROJECTS_FILTER: ${{ inputs.projects }}
          SKIP_CLOSE_MILESTONES: ${{ inputs.skip_close_milestones }}
          DRY_RUN: ${{ inputs.dry_run }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');

          const dryRun = (process.env.DRY_RUN || 'false') === 'true';
          const skipCloseMilestones = (process.env.SKIP_CLOSE_MILESTONES || 'false') === 'true';
          const hotfix = (process.env.HOTFIX || 'false') === 'true';
          const isPrerelease = (process.env.PRERELEASE || 'false') === 'true';
          const commercial = (process.env.COMMERCIAL || 'false') === 'true';
          const releaseVersion = process.env.RELEASE_VERSION || '';
          const nextVersion = process.env.NEXT_VERSION || '';
          const snapshotVersion = process.env.SNAPSHOT_VERSION || '';
          const filter = (process.env.PROJECTS_FILTER || '').trim();

          let all = [];
          try {
            all = fs.readdirSync('results')
              .filter(f => f.endsWith('.json'))
              .map(f => JSON.parse(fs.readFileSync(`results/${f}`, 'utf8')));
          } catch (err) {
            console.log('No results to summarize.');
          }

          const byPhase = p => all.filter(r => r.phase === p)
            .sort((a, b) => (a.project || '').localeCompare(b.project || ''));

          const mr = byPhase('milestones-and-releases');
          const nm = byPhase('new-milestones');
          const mb = byPhase('merge-back-and-update');
          const sc = all.find(r => r.phase === 'next-snapshot-config');
          const web = all.find(r => r.phase === 'website-pr');
          const board = all.find(r => r.phase === 'release-board');
          const start = all.find(r => r.phase === 'start-site-pr');

          const L = [];
          L.push(dryRun ? '## Post-release summary (dry run — nothing was changed)'
                        : '## Post-release summary');
          L.push('');
          L.push(`Release **${releaseVersion}** · ${commercial ? 'commercial' : 'OSS'}` +
            (hotfix ? ' · **hotfix** (no snapshot train, new milestone or merge back)' : '') +
            // Said plainly, because a Bump column that restores the current snapshot rather than
            // advancing to the next one is the most surprising thing about one of these runs to
            // anyone reading the summary who has only ever seen a GA release.
            (isPrerelease ? ' · **pre-release** (the train stays on its current snapshot: ' +
              'no new snapshot properties file; after the merge back each branch is put back on ' +
              `\`${snapshotVersion || '<train>-SNAPSHOT'}\`)` : '') +
            (filter ? ` · filtered to \`${filter}\`` : '') +
            (skipCloseMilestones ? ' · **milestones left open** (`skip_close_milestones`)' : ''));
          L.push('');

          // Anything that already existed is deliberately a no-op, so "done" and "was already
          // done" have to read differently - otherwise a run that changed nothing looks
          // identical to one that did all the work.
          const ICON = {
            closed: '✅', created: '✅', pushed: '✅', merged: '✅',
            // bumpOutcome carries a GitHub step outcome, not one of our own statuses.
            success: '✅', cancelled: '⚠️',
            'would-close': '🔎', 'would-create': '🔎', 'would-push': '🔎',
            updated: '✅', unchanged: '➖', 'would-update': '🔎',
            'already-closed': '➖', 'already-exists': '➖', 'already-merged': '➖',
            'nothing-to-push': '➖', 'no-release-branch': '➖',
            // website-pr
            'branch-exists': '➖', 'no-changes': '➖', added: '✅', 'needs-entry': '⚠️',
            // start-site-pr
            'already-current': '➖', 'no-mapping': '⚠️',
            'unexpected-mappings': '⚠️', 'no-boot-version': '⚠️',
            'file-not-found': '❌', 'bom-not-found': '❌',
            // release-board
            done: '✅', 'would-run': '🔎', partial: '⚠️',
            'no-old-board': '❔', 'no-status-field': '❌', 'unknown-columns': '❌',
            'board-listing-incomplete': '❌', 'board-created-elsewhere': '⚠️',
            'not-found': '❔', 'no-tag-oss-fallback': '⏭️', 'no-version': '❔',
            skipped: '⏭️', 'skipped-by-request': '⏭️',
            'merge-conflict': '❌', 'branch-not-found': '❌', 'branch-locked': '🔒',
            'clone-failed': '❌', 'branch-fetch-failed': '❌',
            'version-mismatch': '❌', error: '❌', failure: '❌',
            // the checks that gate publishing
            'no-tag': '❌', 'merge-incomplete': '❌',
          };
          const icon = s => ICON[s] || '❔';

          if (mr.length) {
            L.push(skipCloseMilestones
              ? '### Releases published (milestones left open)'
              : '### Milestones closed and releases published');
            L.push('');
            L.push('| Project | Version | Milestone | Release |');
            L.push('|---|---|---|---|');
            for (const r of mr) {
              const rel = r.releaseUrl ? `[${r.release}](${r.releaseUrl})` : r.release;
              L.push(`| \`${r.project}\` | ${r.version} | ${icon(r.milestone)} ${r.milestone} | ` +
                `${icon(r.release)} ${rel} |`);
            }
            L.push('');
          }

          if (sc) {
            L.push('### Next snapshot config');
            L.push('');
            L.push(`${icon(sc.status)} \`${sc.nextFile}\` on \`${sc.releaseRepo}\`` +
              `@\`jenkins-releaser-config\` — **${sc.status}**`);
            if (sc.status === 'updated' || sc.status === 'would-update') {
              L.push('');
              L.push('The file already existed and its versions did not match, so it was ' +
                'overwritten with the versions computed from the release.');
            } else if (sc.status === 'unchanged') {
              L.push('');
              L.push('The file already had exactly these versions, so nothing was committed.');
            }
            L.push('');
          }

          if (nm.length) {
            L.push(`### New milestones${nextVersion ? ` for ${nextVersion}` : ''}`);
            L.push('');
            L.push('| Project | Milestone | Status |');
            L.push('|---|---|---|');
            for (const r of nm) {
              L.push(`| \`${r.project}\` | ${r.title || '—'} | ${icon(r.status)} ${r.status} |`);
            }
            L.push('');
          }

          if (mb.length) {
            L.push('### Merge back and version bump');
            L.push('');
            L.push('| Project | Branch | Merge | CI files restored | Bump | Push | Dependabot |');
            L.push('|---|---|---|---|---|---|---|');
            for (const r of mb) {
              const branch = (r.branch ? `\`${r.branch}\`` : `${icon(r.branchStatus)} ${r.branchStatus}`) +
                // On a dry run the merge still runs, so the lock would otherwise be invisible
                // next to a green merge.
                (r.lockStatus === 'locked' ? ' 🔒 frozen' : '');
              const dep = r.dependabotMatched
                ? `${r.dependabotCommented}/${r.dependabotMatched} of ${r.dependabotOpen}`
                : '—';
              // Restored (the merge deleted it cleanly) and auto-resolved (the merge conflicted
              // on it) are both "this branch's version was kept", so they share one column.
              const names = s => s.trim().split(/\s+/)
                .map(f => `\`${f.replace(/^\.github\/workflows\//, '')}\``);
              const kept = [
                ...(r.restored ? names(r.restored) : []),
                ...(r.autoResolved ? names(r.autoResolved).map(n => `${n} (conflict)`) : []),
              ];
              L.push(`| \`${r.project}\` | ${branch} | ${icon(r.mergeStatus)} ${r.mergeStatus} | ` +
                `${kept.length ? kept.join(', ') : '—'} | ${icon(r.bumpOutcome)} ${r.bumpOutcome} | ` +
                `${icon(r.pushStatus)} ${r.pushStatus} | ${dep} |`);
            }
            L.push('');
            // The Merge and Push columns look like they disagree when a no-op merge sits next
            // to a push - which is most runs, since the merge is usually already done and the
            // bump usually is not. Saying what the push carries is cheaper than everyone
            // working it out from the job log each time.
            L.push('**Merge and Push answer different questions.** The merge commit and ' +
              'the version bump go up together in a single push, so the Push column covers the ' +
              'whole leg: `already-merged` next to `would-push` means the merge was a no-op and ' +
              'the snapshot bump is what would be pushed, while `nothing-to-push` means the ' +
              'branch already had both.');
            L.push('');

            const restoredAny = mb.filter(r => r.restored);
            const autoAny = mb.filter(r => r.autoResolved);
            if (restoredAny.length || autoAny.length) {
              L.push(`\`ci\`/\`pr\` workflow files kept from the maintenance branch — ` +
                `**${restoredAny.length}** project(s) had them restored after the merge deleted ` +
                `them, **${autoAny.length}** had a conflict on them auto-resolved in favour of ` +
                'the maintenance branch.');
              L.push('');
            }
          }

          if (web) {
            L.push('### Website PR');
            L.push('');
            const link = web.prUrl ? `[${web.status}](${web.prUrl})` : `**${web.status}**`;
            L.push(`${icon(web.status)} \`${web.repo}\` — ${link} on \`${web.branch}\``);
            L.push('');
            if (web.blogFile) {
              L.push(`- blog post \`${web.blogFile}\` — ${web.blogStatus}`);
            }
            const docs = web.docs || [];
            // The commercial site is appended to, the OSS site is edited in place, so the two
            // have nothing to report in common.
            if (commercial) {
              const addedDocs = docs.filter(d => d.status === 'added');
              L.push(`- \`documentation.json\` — ${addedDocs.length} new ` +
                `${addedDocs.length === 1 ? 'entry' : 'entries'}`);
              for (const d of addedDocs.filter(d => d.legacyTemplate)) {
                L.push(`  - ⚠️ \`${d.project}\` ${d.added} — this file has nothing but ` +
                  'pre-Antora entries, so its `ref` was cloned from ' +
                  `\`${d.from}\` and carries a version in the path. Check it.`);
              }
            } else {
              const touched = docs.filter(d => d.ga || d.snapshot || d.prerelease);
              L.push(`- \`documentation.json\` — ${touched.length} project(s) updated`);
              L.push(web.previousFile
                ? `- modules listed: everything that changed since \`${web.previousFile}\``
                : '- modules listed: every project in the train — there was no earlier ' +
                  'properties file on this line to compare against');
            }
            // Anything the edit could not be applied to cleanly. Reported rather than failed:
            // the PR is still worth having with one file left for a human.
            const odd = docs.filter(d =>
              d.status === 'ambiguous' || d.status === 'unparseable' || d.status === 'no-entry' ||
              d.status === 'unrecognised-format' || d.status === 'no-template' ||
              d.status === 'error');
            for (const d of odd) L.push(`- ⚠️ \`${d.file}\` — ${d.status}`);
            if (web.status === 'would-create' || web.status === 'created') {
              L.push('- the full diff is under the **Website PR** job above, one collapsed ' +
                'block per file, and in the `website-changes` artifact');
            }
            L.push('');
            if (web.blogStatus === 'created') {
              L.push('The post is a template: the author and every project section still say ' +
                '`TODO`, and the title still says `CODENAME`. The PR body has the checklist.');
              L.push('');
            }
          }

          if (start) {
            L.push('### start.spring.io PR');
            L.push('');
            const link = start.prUrl ? `[${start.status}](${start.prUrl})` : `**${start.status}**`;
            L.push(`${icon(start.status)} \`${start.repo}\` — ${link} on \`${start.branch}\``);
            L.push('');
            if (start.status === 'no-mapping') {
              // The one outcome that needs a person. Spelled out rather than left as a status
              // word, because doing nothing was the right call and the reason matters.
              L.push(`**No mapping for the ${releaseVersion.split('.').slice(0, 2).join('.')} ` +
                'line, so no PR was opened.** `start.spring.io` pins a Spring Cloud version ' +
                'per Spring Boot `compatibilityRange`, and this train line has no mapping to ' +
                'bump — either it is new to the site, or its Boot range has aged off it.');
              L.push('');
              L.push('Adding one means choosing that `compatibilityRange`, which is a ' +
                'judgement this workflow cannot make. Edit `' + start.file + '` by hand if ' +
                'this release should be on the site.');
              L.push('');
              if (start.mappings && start.mappings.length) {
                L.push(`Currently mapped: ${start.mappings.map(v => `\`${v}\``).join(', ')}.`);
                L.push('');
              }
            } else if (start.from) {
              L.push(`\`${start.file}\` — \`${start.from}\` → \`${start.to}\``);
              L.push('');
            }
          }

          if (board) {
            L.push('### Release board');
            L.push('');
            const link = board.boardUrl ? `[${board.status}](${board.boardUrl})` : `**${board.status}**`;
            L.push(`${icon(board.status)} \`${board.from}\` → \`${board.to}\` — ${link}` +
              (board.boardCreated ? ' (created)' : ''));
            L.push('');
            const carried = (board.moved || []).filter(m => !m.failed);
            L.push(`- ${carried.length} item(s) in ${(board.columns || []).join(' / ')} ` +
              `${board.status === 'would-run' ? 'would be carried over' : 'carried over'}`);
            const remilestoned = (board.milestones || []).filter(m => /→|would set/.test(m.detail));
            if (remilestoned.length) L.push(`- ${remilestoned.length} milestone(s) updated`);
            const stale = (board.moved || []).filter(m => m.leftAlone);
            if (stale.length) L.push(`- ${stale.length} milestone(s) left alone — listed below`);
            if (board.teams && board.teams.length) {
              L.push(`- access: ${board.teams.map(t => `\`${t.slug}\` ${t.role}`).join(', ')}`);
            }
            // Left open is a warning on a real run and simply what a dry run does, so the
            // two must not read alike - an unclosed board is the thing to notice here.
            L.push(board.closedOld ? `- \`${board.from}\` closed`
              : board.status === 'would-run' ? `- \`${board.from}\` would be closed`
              : `- ⚠️ \`${board.from}\` left open — carry the rest over by hand, then close it`);
            for (const p of (board.problems || []).slice(0, 10)) L.push(`- ⚠️ ${p}`);
            if ((board.problems || []).length > 10) {
              L.push(`- ⚠️ …and ${board.problems.length - 10} more, see the job log`);
            }
            L.push('');

            // Listed rather than counted. Leaving these alone is deliberate, and it is also
            // exactly the sort of thing nobody notices unless it is written down: the item
            // moves to the new board and quietly keeps a milestone from an old train.
            if (stale.length) {
              L.push('#### Milestones left alone — worth a look');
              L.push('');
              L.push('These carried over but kept the milestone they had, because it is neither');
              L.push('empty nor the train just released, and a milestone somebody chose is never');
              L.push('overwritten. Update them by hand where it is drift rather than a decision —');
              L.push('**a closed milestone usually is**.');
              L.push('');
              for (const m of stale) {
                const a = m.leftAlone;
                L.push(`- ${a.closed ? '⚠️ ' : ''}\`${m.ref}\` — on \`${a.current}\`` +
                  `${a.closed ? ' **(closed)**' : ''}` +
                  `${a.target ? `, this train wants \`${a.target}\`` : ''}` +
                  `${m.title ? ` — ${m.title}` : ''}`);
              }
              L.push('');
            }
          }

          const blocked = mb.filter(r => r.mergeStatus === 'merge-conflict');
          // Git could not reach the repository at all, after retrying. Counted as a problem
          // like any other half-done project: the alternative is a row of "skipped" that reads
          // like nothing was needed.
          const unreachable = mb.filter(r =>
            r.mergeStatus === 'clone-failed' || r.mergeStatus === 'branch-fetch-failed');
          const branchFailed = mb.filter(r =>
            r.branchStatus === 'branch-not-found' || r.branchStatus === 'version-mismatch');
          const noMilestone = mr.filter(r => r.milestone === 'not-found');
          const ossFallback = mr.filter(r => r.resolvedIn === 'oss-fallback');
          const noReleaseBranch = mb.filter(r => r.mergeStatus === 'no-release-branch');
          const noTag = mr.filter(r => r.release === 'no-tag');
          const heldBack = mr.filter(r => r.release === 'merge-incomplete');
          // A branch with a push-blocking ruleset on it. On a real run nothing was merged for
          // these; on a dry run the merge ran in the clone, but a real run could not push it.
          const frozen = mb.filter(r => r.lockStatus === 'locked');

          if (frozen.length) {
            L.push(dryRun
              ? '### ⚠️ Branches frozen — a real run could not push to these'
              : '### ❌ Branches frozen — nothing was merged');
            L.push('');
            L.push(dryRun
              ? 'These branches have a ruleset that rejects pushes, this workflow\'s included, ' +
                'so a real run would merge each one and then fail to push it — and hold back ' +
                'its release with it. Unlock them before the real run.'
              : 'These branches have a ruleset that rejects pushes, this workflow\'s included, ' +
                'so the merge back was skipped rather than attempted, and their releases are ' +
                'held back until it lands.');
            L.push('');
            for (const r of frozen) {
              L.push(`- \`${r.repo}\` @ \`${r.branch}\` — ${r.lockedBy || 'a ruleset'}`);
            }
            L.push('');
            // Only the Release Freeze is lifted by lock-unlock-branches. Anything else - a
            // retired branch's Locked Branches ruleset, an org-level ruleset - is not a
            // release-time freeze, and unlocking is not a decision to make from here.
            const freeze = frozen.filter(r => (r.lockedBy || '').split(', ').includes('Release Freeze'));
            const other = frozen.filter(r => !freeze.includes(r));
            if (freeze.length) {
              L.push('To lift the `Release Freeze`, run **Lock/Unlock Branches** with `unlock` ' +
                `checked, \`repo_type\` \`${commercial ? 'commercial' : 'oss'}\`, and:`);
              L.push('');
              L.push('```');
              L.push(`projects: ${[...new Set(freeze.map(r => r.project))].join(',')}`);
              L.push('```');
              L.push('');
              L.push(dryRun
                ? 'then run this workflow for real.'
                : 'then re-run this workflow with `projects` set to the same list.');
              L.push('');
            }
            if (other.length) {
              L.push(`${other.length === 1 ? 'One is' : `${other.length} are`} locked by ` +
                'something other than the `Release Freeze`, which Lock/Unlock Branches does ' +
                'not manage — check the ruleset named above before unlocking anything.');
              L.push('');
            }
          }

          if (blocked.length) {
            L.push('### ❌ Blocked on a manual merge');
            L.push('');
            L.push('These release branches could not be merged back without conflicts. The merge was');
            L.push('aborted and nothing else was done for them — resolve each one by hand, then');
            L.push('re-run this workflow with `projects` set to just those projects.');
            L.push('');
            L.push('This also holds up the GitHub release: the merge is what makes the tagged');
            L.push('commit reachable, so those projects appear under **Releases held back** too.');
            L.push('');
            for (const r of blocked) {
              L.push(`- \`${r.repo}\` — merge \`release/${r.version}\` into \`${r.branch}\``);
              // ci/pr workflow conflicts are resolved automatically, so anything listed here is
              // genuinely something only a human can decide.
              if (r.conflicts && r.conflicts.trim()) {
                const paths = r.conflicts.trim().split(/\s+/);
                L.push(`  - conflicting: ${paths.map(p => `\`${p}\``).join(', ')}`);
              }
            }
            L.push('');
          }

          if (unreachable.length) {
            L.push('### ❌ Could not reach the repository');
            L.push('');
            L.push('Git could not clone the repository, or could not read the release branch');
            L.push('from it, after three attempts — nothing else was done for these projects.');
            L.push('An HTTP 401 or a 5xx here is usually github.com having a moment rather than');
            L.push('anything about the repository or the token, so re-running this workflow with');
            L.push('`projects` set to just these is the first thing to try.');
            L.push('');
            for (const r of unreachable) {
              L.push(`- \`${r.repo}\` — ${r.mergeStatus} on \`${r.branch}\``);
            }
            L.push('');
          }

          if (heldBack.length) {
            L.push('### ❌ Releases held back');
            L.push('');
            L.push('The merge back did not land for these projects, so nothing was published for');
            L.push('them. The tag is in the repository, but the commit it names was built on the');
            L.push('release branch in the commercial repo and only becomes reachable once the');
            L.push('merge is pushed — so a release now would carry notes generated against');
            L.push('history that is on no branch, and announce a version the maintenance branch');
            L.push('has not received.');
            L.push('');
            L.push('Fix whatever stopped the merge (see the table above), then re-run this');
            L.push('workflow with `projects` set to just these. Everything else is a no-op the');
            L.push('second time.');
            L.push('');
            // The reason, not just the name: the merge back table can read as healthy while a
            // release is held back - a clean merge whose push never happened, say - and two
            // sections of the same report disagreeing is worse than either one being terse.
            for (const r of heldBack) {
              L.push(`- \`${r.repo}\` — \`${r.tag}\`` +
                (r.heldBackReason ? `, ${r.heldBackReason}` : ''));
            }
            L.push('');
          }

          if (noTag.length) {
            L.push('### ❌ No tag to release from');
            L.push('');
            L.push('The tag was not in the repository when the release step ran, so nothing was');
            L.push('published — deliberately, since creating a release against a missing tag would');
            L.push('have GitHub create that tag at the default branch head. It **was** there when');
            L.push('the tags were verified at the start of this run, so something removed it in');
            L.push('between; that is what to go and look at.');
            L.push('');
            for (const r of noTag) L.push(`- \`${r.repo}\` — \`${r.tag}\``);
            L.push('');
          }

          if (branchFailed.length) {
            L.push('### ❌ No branch to update');
            L.push('');
            for (const r of branchFailed) {
              L.push(`- \`${r.repo}\` — ${r.branchStatus}`);
            }
            L.push('');
          }

          if (noMilestone.length) {
            L.push('### ❔ No milestone found to close');
            L.push('');
            for (const r of noMilestone) L.push(`- \`${r.repo}\` — no milestone \`${r.version}\``);
            L.push('');
          }

          if (ossFallback.length) {
            L.push('### ⏭️ Satisfied by the OSS tag');
            L.push('');
            L.push('No commercial release since the last OSS one, so there is no commercial tag to');
            L.push('attach a release to. The OSS run owns these.');
            L.push('');
            for (const r of ossFallback) L.push(`- \`${r.project}\` \`${r.version}\``);
            L.push('');
          }

          if (noReleaseBranch.length) {
            L.push('### ➖ No release branch to merge');
            L.push('');
            for (const r of noReleaseBranch) {
              L.push(`- \`${r.repo}\` — no \`release/${r.version}\` branch`);
            }
            L.push('');
          }

          fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, L.join('\n') + '\n');
          console.log(L.join('\n'));

          // ── Google Chat message ─────────────────────────────────────────────────────
          // Chat has its own lightweight formatting (*bold*, <url|text>, no tables), so this
          // is built separately rather than reusing the markdown above. Assembled here, where
          // the data already is, and handed to the posting step as one value.
          // Counted as distinct repositories rather than summed across the lists, because one
          // project lands in several of them at once by design: a merge conflict blocks the
          // merge, which holds back the release, which is two entries for one thing to fix.
          // A frozen branch is a problem on a real run - the project was left half-done - but
          // only a warning on a dry run, where finding it is the point of running one.
          const problemRepos = new Set([
            ...blocked, ...unreachable, ...branchFailed, ...noTag, ...heldBack,
            ...(dryRun ? [] : frozen),
          ].map(r => r.repo));
          const problems = problemRepos.size;
          const frozenWarning = dryRun && frozen.length > 0;
          // Called out in the message but deliberately not counted as a problem: nothing is
          // half-done, the run made the right decision, and a train line that has aged off
          // start.spring.io would otherwise turn every one of its releases red.
          const startNeedsAttention = !!start && start.status === 'no-mapping';
          const C = [];
          C.push(`${problems || startNeedsAttention || frozenWarning ? '⚠️' : '✅'} *Post Release — ${releaseVersion}* ` +
            `(${commercial ? 'commercial' : 'OSS'}${hotfix ? ', hotfix' : ''})` +
            (filter ? ` · only ${filter}` : '') +
            (skipCloseMilestones ? ' · milestones left open' : ''));
          C.push('');

          const n = (rows, pred) => rows.filter(pred).length;

          // Counted by grouping on whatever status values are present, rather than by listing
          // the ones expected. A status nobody thought to enumerate then shows up under its raw
          // name instead of being silently dropped, so the totals always add up to the project
          // count and the message cannot quietly under-report.
          const PHRASE = {
            closed: 'closed', 'already-closed': 'already closed', 'not-found': 'none found',
            'would-close': 'would close (dry run)', 'skipped-by-request': 'left open on request',
            created: 'created', 'already-exists': 'already existed',
            'no-tag-oss-fallback': 'skipped (OSS tag)', 'would-create': 'would publish (dry run)',
            merged: 'merged', 'already-merged': 'already merged',
            'no-release-branch': 'no release branch', 'merge-conflict': 'BLOCKED by a conflict',
            'branch-locked': 'BRANCH FROZEN - unlock it first',
            'clone-failed': 'COULD NOT CLONE', 'branch-fetch-failed': 'COULD NOT READ the release branch',
            pushed: 'pushed', 'nothing-to-push': 'already up to date',
            'would-push': 'would push (dry run)', 'branch-not-found': 'no branch found',
            'version-mismatch': 'version mismatch', 'no-version': 'no version',
            error: 'errored', skipped: 'not reached', unknown: 'unknown',
            'branch-exists': 'branch already existed, left alone', 'no-changes': 'nothing to change',
            'already-current': 'already up to date', 'no-mapping': 'NO MAPPING - nothing opened',
            done: 'rolled over', 'would-run': 'would roll over (dry run)',
            partial: 'PARTLY rolled over', 'no-old-board': 'no board found',
            'no-status-field': 'no column field found', 'unknown-columns': 'columns not found',
            'board-listing-incomplete': 'COULD NOT LIST the org projects - nothing created',
            'board-created-elsewhere': 'board appeared while running - nothing created',
            'file-not-found': 'application.yml has moved', 'bom-not-found': 'could not find the bom',
            'no-tag': 'NO TAG - not published',
            'merge-incomplete': 'HELD BACK - the merge back did not land',
          };
          // overrides let one status read differently per phase - a created release is
          // "published", a created milestone is just "created".
          const phrase = (k, overrides) => (overrides && overrides[k]) || PHRASE[k] || k;
          const tally = (label, rows, key, overrides) => {
            const counts = {};
            for (const r of rows) {
              const v = r[key] || 'unknown';
              counts[v] = (counts[v] || 0) + 1;
            }
            const keys = Object.keys(counts).sort();
            if (keys.length) {
              C.push(`${label}: ` +
                keys.map(k => `${counts[k]} ${phrase(k, overrides)}`).join(', '));
            }
          };

          // "Milestones closed: 12 left open on request" would contradict itself, so the label
          // follows what the run was actually asked to do.
          tally(skipCloseMilestones ? 'Milestones' : 'Milestones closed', mr, 'milestone');
          tally('Releases', mr, 'release', { created: 'published' });
          if (sc) C.push(`Next snapshot: ${sc.nextVersion} (${sc.nextFile} ${sc.status})`);
          tally('New milestones', nm, 'status');
          tally('Merge back', mb, 'mergeStatus');
          tally('Version bumps', mb, 'pushStatus');
          // "would publish" is right for a release and wrong for a pull request, so both of
          // these say what they actually do.
          const PR_PHRASE = { created: 'PR opened', 'would-create': 'would open a PR (dry run)' };
          if (web) {
            C.push(`Website PR: ${phrase(web.status, PR_PHRASE)}` +
              (web.prUrl ? ` — <${web.prUrl}|${web.repo}>` : ''));
          }
          if (board) {
            const carried = (board.moved || []).filter(m => !m.failed).length;
            // The left-alone count earns its place here: the full list is in the summary,
            // but nobody goes looking at the summary for something they do not know about.
            const kept = (board.moved || []).filter(m => m.leftAlone).length;
            C.push(`Release board: ${phrase(board.status)} ${board.from} → ${board.to}` +
              ` (${carried} item(s)` +
              `${kept ? `, ${kept} kept an old milestone - see the summary` : ''})`);
          }
          if (start) {
            C.push(`start.spring.io: ${phrase(start.status, PR_PHRASE)}` +
              (start.from ? ` (${start.from} → ${start.to})` : '') +
              (start.prUrl ? ` — <${start.prUrl}|PR>` : ''));
          }
          const kept = n(mb, r => r.restored || r.autoResolved);
          if (kept) C.push(`CI/PR workflow files kept from the maintenance branch: ${kept} project(s)`);
          const nudged = mb.reduce((sum, r) => sum + (Number(r.dependabotCommented) || 0), 0);
          if (nudged) C.push(`Dependabot: ${nudged} PR(s) asked to recreate`);

          if (problems || startNeedsAttention || frozenWarning) {
            C.push('');
            C.push(problems
              ? `*${problems} project(s) need attention:*`
              : '*Needs attention:*');
            if (startNeedsAttention) {
              C.push(`• start.spring.io has no mapping for the ` +
                `${releaseVersion.split('.').slice(0, 2).join('.')} line, so no PR was ` +
                'opened - adding one means choosing a compatibilityRange by hand');
            }
            if (frozenWarning) {
              C.push(`• ${frozen.length} branch(es) frozen - unlock before the real run: ` +
                frozen.map(r => `${r.repo}@${r.branch}`).join(', '));
            } else {
              for (const r of frozen) {
                C.push(`• ${r.repo} — ${r.branch} is frozen by ${r.lockedBy || 'a ruleset'}, ` +
                  'so nothing was merged');
              }
            }
            for (const r of blocked) {
              C.push(`• ${r.repo} — blocked on a manual merge of release/${r.version} into ${r.branch}`);
            }
            for (const r of unreachable) {
              C.push(`• ${r.repo} — ${phrase(r.mergeStatus)}, nothing was done for it`);
            }
            for (const r of branchFailed) C.push(`• ${r.repo} — ${phrase(r.branchStatus)}`);
            for (const r of noTag) {
              C.push(`• ${r.repo} — ${r.tag} never reached the repo, so no release was published`);
            }
            // Only the ones not already named above, so a merge conflict is one bullet about
            // the conflict rather than two about the same project.
            const named = new Set([...blocked, ...unreachable, ...branchFailed, ...noTag,
              ...(dryRun ? [] : frozen)].map(r => r.repo));
            for (const r of heldBack.filter(r => !named.has(r.repo))) {
              C.push(`• ${r.repo} — the merge back did not land, so ${r.tag} was not published`);
            }
          }

          C.push('');
          C.push("*Please update your project's release notes* with anything that needs calling " +
            'out — CVEs, breaking changes, deprecations, or other notable fixes. The generated ' +
            'notes only list merged pull requests, so anything that landed as a direct commit is ' +
            'missing, and any release with no PRs in range says only "Released from tag ...".');

          // Written before the exit below so the notification still goes out on a red run -
          // that is exactly when people need to see it.
          const out = process.env.GITHUB_OUTPUT;
          fs.appendFileSync(out, `total=${all.length}\n`);
          const delim = 'ghadelim_post_release_chat';
          fs.appendFileSync(out, `chat-text<<${delim}\n${C.join('\n')}\n${delim}\n`);

          // A blocked merge, an unusable branch, or a release that could not be published for
          // want of its tag all mean a project was left half-done, which has to be a red run
          // rather than a green one with a note buried in the table.
          if (problems) {
            console.error(`\n${problems} project(s) need attention.`);
            process.exit(1);
          }
          JSEOF

      # Never posted for a dry run - there is nothing to announce, and the ask to write up
      # release notes would be misleading when no release was published.
      - name: Send Google Chat notification
        if: always() && inputs.dry_run != true && steps.write-summary.outputs.total != '0'
        env:
          WEBHOOK_URL: ${{ secrets.SPRING_CLOUD_CORE_POST_RELEASE_GCHAT_WEBHOOK }}
          CHAT_TEXT: ${{ steps.write-summary.outputs.chat-text }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          set -euo pipefail

          if [[ -z "${WEBHOOK_URL}" ]]; then
            echo "SPRING_CLOUD_CORE_POST_RELEASE_GCHAT_WEBHOOK is not set - skipping the Google Chat notification."
            exit 0
          fi

          if [[ -z "${CHAT_TEXT:-}" ]]; then
            echo "No summary text was produced - skipping the Google Chat notification."
            exit 0
          fi

          TEXT=$(printf '%s\n\n<%s|View the full report>' "$CHAT_TEXT" "$RUN_URL")

          jq -n --arg text "$TEXT" '{text: $text}' > chat-message.json

          curl --fail --silent --show-error \
            -X POST \
            -H 'Content-Type: application/json; charset=UTF-8' \
            -d @chat-message.json \
            "${WEBHOOK_URL}"

          echo "Posted the post-release notification to Google Chat."