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,
#                                and push the release tag into this repository
#   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 spring-website-content: the release blog post
#                                and the documentation.json version bumps (OSS trains only)
#   8. summary                 — one report covering everything above
#
# release/<version> and the v<version> tag only ever exist 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, and it pushes the tag into the OSS repo once the merge has made the
# tagged commit reachable there. Step 6 has to follow it for that reason: POST /releases with a
# tag_name that does not exist creates the tag at the default branch head, so publishing before
# the tag arrives would stamp v<version> onto whatever main happened to be.
#
# 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 and 6:
# 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).
#
# 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, or 2025.1.2.1 for a commercial hotfix)'
        required: true
        type: string
      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
      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 }}
      entries: ${{ steps.parse.outputs.entries }}
    steps:
      - name: Parse releaser config and build matrix
        id: parse
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          RELEASE_VERSION: ${{ inputs.release_version }}
          COMMERCIAL: ${{ inputs.commercial }}
          PROJECTS_FILTER: ${{ inputs.projects }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const { execFileSync } = require('child_process');

          const releaseVersion = (process.env.RELEASE_VERSION || '').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); };

          // Pre-release qualifiers are rejected rather than half-handled: bumping the patch of
          // something like 2025.1.0-RC1 produces a version nobody wants, and post-release chores
          // are not run for milestones or release candidates anyway.
          if (!/^\d+(\.\d+){2,3}$/.test(releaseVersion)) {
            fail(`ERROR: release_version must be a plain numeric version with 3 or 4 segments ` +
              `(e.g. 2025.1.2 or 2025.1.2.1); got '${releaseVersion}'.`);
          }

          // A 4-segment version is a commercial hotfix: only the tag gate and the
          // milestone/release step apply to it.
          const hotfix = releaseVersion.split('.').length === 4;

          // ── 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.`);
            }
          }

          // Always spring-cloud-release-commercial, for OSS trains too: that repository holds
          // the releaser config for every train now, so this is deliberately NOT derived from
          // `commercial`. That input still decides everything else - which project repos are
          // acted on, whether release notes are sanitized, and the OSS tag fallback.
          const releaseRepo = 'spring-cloud/spring-cloud-release-commercial';
          const propsFile = releaseVersion.replace(/\./g, '_') + '.properties';

          // ── read the properties file ────────────────────────────────────────────────
          console.log(`Reading ${propsFile} from ${releaseRepo}@jenkins-releaser-config...`);
          let content;
          try {
            const b64 = execFileSync('gh', ['api',
              `repos/${releaseRepo}/contents/${propsFile}?ref=jenkins-releaser-config`,
              '--jq', '.content'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
            content = Buffer.from(b64.replace(/\s/g, ''), 'base64').toString('utf8');
          } catch (err) {
            fail(`ERROR: could not read ${propsFile} from ${releaseRepo}@jenkins-releaser-config.`,
              'Check that release_version matches a properties file on that branch, and that the',
              'token has read access to the repository.');
          }

          const ENTRY_RE = /^releaser\.fixed-versions\[([^\]]+)\]=(.+)$/;
          const entries = [];
          for (const line of content.split('\n')) {
            const m = line.match(ENTRY_RE);
            if (m) entries.push({ key: m[1].trim(), version: m[2].trim() });
          }
          if (!entries.length) {
            fail(`ERROR: ${propsFile} contains no releaser.fixed-versions[...] entries.`);
          }
          console.log(`Found ${entries.length} version entries.`);

          // spring-boot lives in the properties file but is not a Spring Cloud repository, so it
          // has no tag, milestone or release of ours. It is still bumped in the snapshot file.
          const NON_REPO_KEYS = new Set(['spring-boot']);

          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));

          // ── next snapshot train version ─────────────────────────────────────────────
          const bump = v => {
            const parts = v.split('.');
            const last = parts[parts.length - 1];
            if (!/^\d+$/.test(last)) return null;
            parts[parts.length - 1] = String(Number(last) + 1);
            return parts.join('.');
          };

          let nextVersion = '';
          let nextFile = '';
          if (!hotfix) {
            const unbumpable = entries.filter(e => bump(e.version) === null);
            if (unbumpable.length) {
              fail('ERROR: these versions do not end in a numeric segment and cannot be bumped:',
                ...unbumpable.map(e => `  ${e.key}=${e.version}`));
            }
            nextVersion = bump(releaseVersion);
            nextFile = nextVersion.replace(/\./g, '_') + '-snapshot.properties';
          }

          console.log('');
          console.log(`commercial:      ${commercial}`);
          console.log(`hotfix:          ${hotfix}`);
          console.log(`release repo:    ${releaseRepo}`);
          console.log(`properties file: ${propsFile}`);
          if (!hotfix) console.log(`next snapshot:   ${nextVersion} (${nextFile})`);
          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, `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 = [];

          // Tags are only ever created on a release/<version> branch, and those only ever exist
          // in the commercial repo - an OSS release is built there too, from the -internal
          // branch. So the commercial repo is where the gate really looks, for both flavours;
          // the difference is what a hit means afterwards.
          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 {
              // Checked first only because a hit here means there is nothing left to do: the
              // tag is already where this run needs it, either from a re-run of this workflow
              // or because the version was carried over from an earlier train.
              if (tagExists(e.ossRepo, e.tag)) {
                console.log(`✓ ${e.ossRepo} ${e.tag}`);
                resolved.push({ ...e, resolvedIn: 'oss' });
                continue;
              }

              // The normal path for an OSS release: the tag exists only on the release branch
              // in the commercial repo. merge-back-and-update pushes it to the OSS repo once
              // the tagged commit is reachable there, which is why that job now runs before
              // milestones-and-releases.
              if (tagExists(e.commercialRepo, e.tag)) {
                console.log(`✓ ${e.commercialRepo} ${e.tag} ` +
                  `(not in ${e.ossRepo} yet - the merge back will push it)`);
                resolved.push({ ...e, resolvedIn: 'commercial-pending' });
                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 ` +
                `${e.commercialRepo} or ${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]
    if: needs.setup.outputs.hotfix != 'true'
    runs-on: ubuntu-latest
    outputs:
      status: ${{ steps.write.outputs.status }}
      available: ${{ steps.write.outputs.available }}
      versions: ${{ steps.write.outputs.versions }}
    steps:
      - 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 { 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; }
          };

          const ENTRY_RE = /^releaser\.fixed-versions\[([^\]]+)\]=(.+)$/;
          const parse = text => {
            const map = {};
            for (const line of text.split('\n')) {
              const m = line.match(ENTRY_RE);
              if (m) map[m[1].trim()] = m[2].trim();
            }
            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]
    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.next-snapshot-config.outputs.versions }}
        run: |
          set -euo pipefail

          TITLE=$(echo "$VERSIONS" | jq -r --arg k "$PROJECT" '.[$k] // ""' | sed 's/-SNAPSHOT$//')
          if [[ -z "$TITLE" ]]; then
            echo "No snapshot 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"

          # Piped through jq rather than gh's --jq, which takes no --arg. Same shape as the
          # lookup in the create-milestone action.
          NUMBER=$(gh api "repos/${REPO}/milestones?state=all&per_page=100" 2>/dev/null \
            | jq -r --arg t "$TITLE" '.[] | 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]
    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 ─────────────────────────────────────────────
      - name: Resolve target branch
        id: branch
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          PROJECT: ${{ matrix.project }}
          REPO: ${{ matrix.repo }}
          COMMERCIAL: ${{ needs.setup.outputs.commercial }}
          VERSIONS: ${{ needs.next-snapshot-config.outputs.versions }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const { execFileSync } = require('child_process');

          const project = process.env.PROJECT;
          const repo = process.env.REPO;
          const commercial = process.env.COMMERCIAL === 'true';
          const versions = JSON.parse(process.env.VERSIONS);

          const out = process.env.GITHUB_OUTPUT;
          const emit = (k, v) => fs.appendFileSync(out, `${k}=${v}\n`);
          const stop = (status, message) => {
            console.log(message);
            emit('status', status);
            emit('branch', '');
            process.exit(0);
          };

          const snapshot = versions[project];
          if (!snapshot) stop('no-version', `No snapshot version for ${project}.`);

          // Drop the last segment and append .x. Works for both lines: OSS 5.0.3 -> 5.0.x, and
          // 3-part commercial 4.2.8 -> 4.2.x.
          const plain = snapshot.replace(/-SNAPSHOT$/, '');
          const parts = plain.split('.');
          const target = parts.slice(0, -1).join('.') + '.x';

          const branchExists = branch => {
            try {
              execFileSync('gh', ['api', `repos/${repo}/branches/${branch}`, '--jq', '.name'],
                { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
              return true;
            } catch (err) { return false; }
          };

          if (branchExists(target)) {
            console.log(`Target branch: ${target}`);
            emit('status', 'ok');
            emit('branch', target);
            process.exit(0);
          }

          // Commercial repos have no main branch at all - spring-cloud-config-commercial's
          // default is 4.3.x - so there is no sane fallback to make.
          if (commercial) {
            stop('branch-not-found',
              `ERROR: ${repo} has no ${target} branch, and commercial repos have no main to ` +
              'fall back to. Skipping this project.');
          }

          if (!branchExists('main')) {
            stop('branch-not-found', `ERROR: ${repo} has neither ${target} nor main.`);
          }

          // Falling back to main is only safe if main really is the line this version belongs
          // to - otherwise we would bump an unrelated major.minor to these versions.
          const expected = parts.slice(0, 2).join('.');
          let pom;
          try {
            const b64 = execFileSync('gh', ['api',
              `repos/${repo}/contents/pom.xml?ref=main`, '--jq', '.content'],
              { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
            pom = Buffer.from(b64.replace(/\s/g, ''), 'base64').toString('utf8');
          } catch (err) {
            stop('branch-not-found', `ERROR: no ${target} branch and could not read pom.xml on main.`);
          }

          // The root <version> is the project's own; fall back to <parent><version> when the
          // root pom inherits it.
          const withoutParent = pom.replace(/<parent>[\s\S]*?<\/parent>/, '');
          let m = withoutParent.match(/<version>([^<]+)<\/version>/);
          if (!m) {
            const parent = pom.match(/<parent>[\s\S]*?<\/parent>/);
            if (parent) m = parent[0].match(/<version>([^<]+)<\/version>/);
          }
          const pomVersion = m ? m[1].trim() : '';

          if (!pomVersion.startsWith(`${expected}.`)) {
            stop('version-mismatch',
              `ERROR: ${repo} has no ${target} branch, and main is at '${pomVersion}', which is ` +
              `not on the ${expected} line. Refusing to bump main to ${snapshot}.`);
          }

          console.log(`No ${target} branch; main is at ${pomVersion} - using main.`);
          emit('status', 'ok');
          emit('branch', 'main');
          JSEOF

      # ── 5b. merge release/<version> back into the .x branch ──────────────────────────
      - name: Merge release branch back
        id: merge
        if: steps.branch.outputs.status == 'ok'
        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
        # 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.
        if: |
          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.next-version }}-SNAPSHOT
          # 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 ──────────────────
      - name: Commit and push
        id: push
        if: steps.bump.outcome == 'success'
        env:
          REPO: ${{ matrix.repo }}
          BRANCH: ${{ steps.branch.outputs.branch }}
          NEXT_VERSION: ${{ needs.setup.outputs.next-version }}
          MERGE_STATUS: ${{ steps.merge.outputs.status }}
          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 new snapshot versions is to start CI on them.
            git commit --quiet -m "Updating project versions to ${NEXT_VERSION}-SNAPSHOT"
            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. push the release tag into this repository ────────────────────────────────
      # Only for an OSS run whose tag exists solely in the commercial repo, which is where it
      # was created - the release is built on release/<version> over there. The merge above is
      # what puts the tagged commit into this repository; this makes the tag itself exist here,
      # so milestones-and-releases can publish a release against a real tag rather than having
      # the API create one at the default branch head.
      - name: Push release tag
        id: tag
        if: |
          matrix.resolvedIn == 'commercial-pending' &&
          (steps.push.outputs.status == 'pushed' ||
           steps.push.outputs.status == 'nothing-to-push' ||
           steps.push.outputs.status == 'would-push')
        env:
          REPO: ${{ matrix.repo }}
          COMMERCIAL_REPO: ${{ matrix.commercialRepo }}
          TAG: ${{ matrix.tag }}
          BRANCH: ${{ steps.branch.outputs.branch }}
          DRY_RUN: ${{ inputs.dry_run }}
        run: |
          set -uo pipefail
          cd project

          # By exact refspec, so nothing but this tag comes across.
          if ! git fetch --quiet commercial "refs/tags/${TAG}:refs/tags/${TAG}"; then
            echo "::error::Could not fetch ${TAG} from ${COMMERCIAL_REPO}."
            echo "status=fetch-failed" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          TAGGED=$(git rev-parse "${TAG}^{commit}")

          # Pushing a tag whose commit is on no branch here would upload that commit as
          # unreachable history. The merge is what makes it reachable, so if it is not an
          # ancestor of what this leg pushed, something landed on the release branch after the
          # merge and this needs a human rather than a push.
          if ! git merge-base --is-ancestor "$TAGGED" HEAD; then
            echo "::error::${TAG} points at ${TAGGED}, which is not reachable from ${BRANCH} in ${REPO}."
            echo "status=not-reachable" >> "$GITHUB_OUTPUT"
            exit 0
          fi

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

          git push --quiet origin "refs/tags/${TAG}"
          echo "Pushed ${TAG} (${TAGGED}) to ${REPO}."
          echo "status=pushed" >> "$GITHUB_OUTPUT"

      # ── 5f. 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 }}
          BUMP_OUTCOME: ${{ steps.bump.outcome }}
          PUSH_STATUS: ${{ steps.push.outputs.status }}
          TAG_STATUS: ${{ steps.tag.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"

          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 bumpOutcome "${BUMP_OUTCOME:-skipped}" \
            --arg pushStatus "${PUSH_STATUS:-skipped}" \
            --arg tagStatus "${TAG_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,
              bumpOutcome: $bumpOutcome, pushStatus: $pushStatus,
              tagStatus: $tagStatus, 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 for an OSS release that is what puts the tag into the
    # repository this job publishes into. !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:
      - 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 }}
          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 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'] });

          // 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 = JSON.parse(gh(['api', `repos/${repo}/milestones?state=all&per_page=100`]));
              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 ───────────────────────────────────────────────────
          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. On an OSS run that would stamp v<version> onto
            // whatever main happens to be, silently. So the tag is confirmed here rather than
            // assumed: verify-tags may have resolved it in the commercial repo, and it only
            // arrives in this one when the merge back pushes it (5e), which a dry run, a merge
            // conflict, or a failed bump all prevent.
            if (!tagExists(repo, tag)) {
              // A dry run pushes nothing, so on an OSS run the tag is expected to be absent
              // here - reporting that as a failure would make every dry run look broken.
              if (dryRun) {
                console.log(`[dry run] ${tag} is not in ${repo}; the merge back would push it. ` +
                  'Nothing to publish against, so there is no release to preview.');
                return { release: 'no-tag-dry-run', releaseUrl: '' };
              }
              console.log(`${tag} does not exist in ${repo} - release skipped.`);
              console.log('It is pushed here by the merge back, which did not get that far ' +
                'for this project (see its leg above, or the summary).');
              return { release: 'no-tag', 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(' ');

              // On a commercial train some entries carry the plain OSS version because that
              // project had no commercial release, and the commercial repo has no such tag. The
              // link has to follow the tag that actually exists or the release body ships 404s.
              const linkRepo = e => {
                if (!commercial) return `spring-cloud/${e.key}`;
                const commercialRepo = `spring-cloud/${e.key}-commercial`;
                try {
                  const refs = gh(['api',
                    `repos/${commercialRepo}/git/matching-refs/tags/v${e.version}`,
                    '--jq', '.[].ref']);
                  if (refs.split('\n').map(r => r.trim()).includes(`refs/tags/v${e.version}`)) {
                    return commercialRepo;
                  }
                } catch (err) { /* fall through to the OSS repo */ }
                return `spring-cloud/${e.key}`;
              };

              const included = entries
                .filter(e => e.key !== 'spring-boot' && e.key !== 'spring-cloud-release')
                .map(e => ` - ${titleCase(e.key)} \`${e.version}\` ` +
                  `([issues](https://github.com/${linkRepo(e)}/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;

            if (dryRun) {
              console.log(`[dry run] would create release '${name}' for ${tag} in ${repo}:`);
              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({ tag_name: tag, name, body }));
            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,
          }));

          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.next-snapshot-config.result == 'success')
    runs-on: ubuntu-latest
    steps:
      - 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.next-snapshot-config.outputs.versions }}
          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 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 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 ENTRY_RE = /^releaser\.fixed-versions\[([^\]]+)\]=(.+)$/;
          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 => e.key !== 'spring-boot');

          // 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 line of text.split('\n')) {
                  const m = line.match(ENTRY_RE);
                  if (m) previousVersions[m[1].trim()] = m[2].trim();
                }
                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 || '';
          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 the General ' +
              `Availability (RELEASE) of the [Spring Cloud ${releaseVersion}]` +
              '(https://cloud.spring.io) Release Train is available today. The release can be ' +
              'found in [Maven Central](https://repo1.maven.org/maven2/org/springframework/' +
              `cloud/spring-cloud-dependencies/${releaseVersion}/). 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>');
            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('}');
            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');
            const block = lines.slice(blocks[anchor].start, blocks[anchor].end + 1)
              .map(l => l.replace(bounded, e.version));

            // 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 two entries to update.
          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: '', 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;
            };

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

            if (!ga && !snap) {
              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';
            }
            if (snap && nextSnap && snap.version !== nextSnap) {
              if (replaceVersion(snap.version, nextSnap)) {
                rec.snapshot = `${snap.version} → ${nextSnap}`;
              } else {
                rec.status = 'ambiguous';
              }
            }

            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.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('');
          }
          const added = result.docs.filter(d => d.status === 'added');
          const bumped = result.docs.filter(d => d.ga || d.snapshot);
          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('');
            P.push('| Project | General availability | Snapshot |');
            P.push('|---|---|---|');
            for (const d of bumped) {
              P.push(`| \`${d.project}\` | ${d.ga || '—'} | ${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:
      - 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 }}
          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 token = process.env.GH_TOKEN;
          const releaseVersion = process.env.RELEASE_VERSION;
          const dryRun = process.env.DRY_RUN === 'true';
          const runUrl = process.env.RUN_URL || '';

          const REPO = 'spring-io/start.spring.io';
          const BASE = 'main';
          const FILE = 'start-site/src/main/resources/application.yml';
          // The one line that identifies the Spring Cloud bom among the dozen boms in that
          // file, several of which are also called spring-cloud-something.
          const ANCHOR = /^\s*artifactId:\s*spring-cloud-dependencies\s*$/;
          const VERSION_RE = /^(\s*version:\s*)(["']?)([^"'\s]+)\2(\s*)$/;

          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);
          };

          const lineOf = v => v.split('.').slice(0, 2).join('.');
          const target = lineOf(releaseVersion);

          // ── 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 path = `start/${FILE}`;
          if (!fs.existsSync(path)) {
            finish('file-not-found', `${FILE} is not in ${REPO} - it has moved.`);
          }

          const original = fs.readFileSync(path, 'utf8');
          const lines = original.split('\n');
          const indentOf = l => l.match(/^(\s*)/)[1].length;

          const anchor = lines.findIndex(l => ANCHOR.test(l));
          if (anchor < 0) {
            finish('bom-not-found',
              `Could not find the spring-cloud bom in ${FILE} - no line matching ` +
              '"artifactId: spring-cloud-dependencies".');
          }

          // The bom's own key is the nearest earlier line indented less than its body, and
          // the block runs to the next line indented no further than that key. Read from the
          // file rather than assumed, so a reindentation upstream does not silently retarget
          // this at the neighbouring bom.
          const bodyIndent = indentOf(lines[anchor]);
          let keyLine = -1;
          for (let i = anchor - 1; i >= 0; i--) {
            if (!lines[i].trim()) continue;
            if (indentOf(lines[i]) < bodyIndent) { keyLine = i; break; }
          }
          if (keyLine < 0) finish('bom-not-found', `Could not find the key above ${FILE}:${anchor + 1}.`);
          const keyIndent = indentOf(lines[keyLine]);

          let blockEnd = lines.length;
          for (let i = anchor + 1; i < lines.length; i++) {
            if (!lines[i].trim()) continue;
            if (indentOf(lines[i]) <= keyIndent) { blockEnd = i; break; }
          }
          console.log(`spring-cloud bom: ${FILE}:${keyLine + 1}-${blockEnd}`);

          const mappings = [];
          for (let i = keyLine + 1; i < blockEnd; i++) {
            const m = lines[i].match(VERSION_RE);
            if (m) mappings.push({ index: i, version: m[3], prefix: m[1], quote: m[2], trail: m[4] });
          }
          result.mappings = mappings.map(m => m.version);
          console.log(`Versions currently mapped: ${result.mappings.join(', ') || 'none'}`);

          const hit = mappings.find(m => lineOf(m.version) === target);
          if (!hit) {
            // Deliberately not a PR. A new mapping needs a compatibilityRange saying which
            // Spring Boot versions this train supports, and that is not derivable from
            // anything this workflow reads.
            finish('no-mapping',
              `No ${target}.x mapping in ${FILE} - start.spring.io does not currently offer ` +
              `this train line. Add a mapping with the right compatibilityRange by hand; ` +
              'nothing was changed.');
          }

          result.from = hit.version;
          if (hit.version === releaseVersion) {
            finish('already-current',
              `${FILE} already maps ${target}.x to ${releaseVersion}.`);
          }

          // ── c. the one-line change ─────────────────────────────────────────────────
          lines[hit.index] = `${hit.prefix}${hit.quote}${releaseVersion}${hit.quote}${hit.trail}`;
          fs.writeFileSync(path, lines.join('\n'));
          console.log(`${FILE}:${hit.index + 1}  ${hit.version} -> ${releaseVersion}`);

          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}\` line ${hit.index + 1}: ` +
                `\`${hit.version}\` → \`${releaseVersion}\``,
              '',
              '```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 ` +
              `mapping for the ${target} line moves from \`${hit.version}\` to ` +
              `\`${releaseVersion}\`. The \`compatibilityRange\` is unchanged.`,
          ].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

  summary:
    name: Summary
    needs: [setup, verify-tags, milestones-and-releases, next-snapshot-config, new-milestones, merge-back-and-update, website-pr, start-site-pr]
    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 }}
          NEXT_VERSION: ${{ needs.setup.outputs.next-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 commercial = (process.env.COMMERCIAL || 'false') === 'true';
          const releaseVersion = process.env.RELEASE_VERSION || '';
          const nextVersion = process.env.NEXT_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 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)' : '') +
            (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': '➖',
            // start-site-pr
            'already-current': '➖', 'no-mapping': '⚠️',
            'file-not-found': '❌', 'bom-not-found': '❌',
            'not-found': '❔', 'no-tag-oss-fallback': '⏭️', 'no-version': '❔',
            skipped: '⏭️', 'skipped-by-request': '⏭️',
            'merge-conflict': '❌', 'branch-not-found': '❌',
            'clone-failed': '❌', 'branch-fetch-failed': '❌',
            'version-mismatch': '❌', error: '❌', failure: '❌',
            // tag push (5e) and the tag check that gates publishing
            'no-tag': '❌', 'not-reachable': '❌', 'fetch-failed': '❌',
            'no-tag-dry-run': '🔎',
          };
          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 | Tag | Dependabot |');
            L.push('|---|---|---|---|---|---|---|---|');
            for (const r of mb) {
              const branch = r.branch ? `\`${r.branch}\`` : `${icon(r.branchStatus)} ${r.branchStatus}`;
              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)`) : []),
              ];
              // The tag column is only meaningful for an entry whose tag was resolved in the
              // commercial repo and so has to be pushed here; anything else already had it.
              const tag = r.resolvedIn === 'commercial-pending'
                ? `${icon(r.tagStatus)} ${r.tagStatus}`
                : '—';
              L.push(`| \`${r.project}\` | ${branch} | ${icon(r.mergeStatus)} ${r.mergeStatus} | ` +
                `${kept.length ? kept.join(', ') : '—'} | ${icon(r.bumpOutcome)} ${r.bumpOutcome} | ` +
                `${icon(r.pushStatus)} ${r.pushStatus} | ${tag} | ${dep} |`);
            }
            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.
            const addedDocs = docs.filter(d => d.status === 'added');
            if (addedDocs.length || commercial) {
              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);
              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('');
            }
          }

          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');

          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('For an OSS release this also holds up the GitHub release: the tag reaches this');
            L.push('repository through the merge, so nothing can be published until it lands.');
            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 (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. The tag is pushed here');
            L.push('by the merge back, so look at that leg first: a conflict, a failed bump, or a');
            L.push('dry run all stop it before the tag moves.');
            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.
          const problems =
            blocked.length + unreachable.length + branchFailed.length + noTag.length;
          // 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 ? '⚠️' : '✅'} *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',
            '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',
            'file-not-found': 'application.yml has moved', 'bom-not-found': 'could not find the bom',
            'no-tag': 'NO TAG - not published', 'not-reachable': 'tag not reachable',
            'fetch-failed': 'tag fetch failed',
            'no-tag-dry-run': 'would publish once the tag lands (dry run)',
          };
          // 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');
          // Only the entries that actually needed a tag pushed here, so a commercial run - where
          // the tag was already in place - does not report a line of "not reached".
          const tagged = mb.filter(r => r.resolvedIn === 'commercial-pending');
          if (tagged.length) tally('Tags pushed', tagged, 'tagStatus');
          // "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 (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) {
            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');
            }
            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`);
            }
          }

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