update-versions.yml

name: Update Versions

# Names each run for what it targets, so the Actions list distinguishes runs at a glance
# instead of showing a column of identical "Update Versions" rows:
#
#   Update Versions - 2025.1.3-SNAPSHOT
#   Update Versions - 2024.0.9-SNAPSHOT (commercial)
#   Update Versions - 2025.1.3-SNAPSHOT [spring-cloud-config] - Dry Run
run-name: "Update Versions - ${{ inputs.release_train_version }}${{ inputs.projects != '' && format(' [{0}]', inputs.projects) || (inputs.commercial == true && ' (commercial)' || '') }}${{ inputs.dry_run == true && ' - Dry Run' || '' }}"

# A thin wrapper around the update-project-versions action that runs it against every OSS or
# every commercial project of a release train, in one go:
#
#   1. setup  — read <release_train_version>.properties from jenkins-releaser-config, build
#               the project matrix, and wait until raw.githubusercontent.com serves that file
#   2. update — per project: resolve the branch, clone it, apply the versions, commit and push
#   3. summary — one report covering every project
#
# The usual reason to run this is the snapshot bump after a release: move every project on the
# train from the versions it was just released at to the next -SNAPSHOT versions. post-release
# already does that as part of its merge-back step, but it does it only as part of a full
# post-release run - this workflow is the same bump on its own, for when the versions have to
# move before (or independently of) post-release.
#
# Nothing here creates the properties file. It must already exist on the jenkins-releaser-config
# branch of spring-cloud-release-commercial; post-release's next-snapshot-config step is what
# normally writes the -snapshot one, and it can also be committed by hand.
#
# See README-update-versions.md for details.

on:
  workflow_dispatch:
    inputs:
      release_train_version:
        description: 'Release train version whose versions should be applied (e.g. 2025.1.3-SNAPSHOT, 2025.1.2, or 2025.1.4-INTERNAL-SNAPSHOT for the -internal branches of the commercial repos). Must have a matching properties file on the jenkins-releaser-config branch.'
        required: true
        type: string
      commercial:
        description: 'Run against the -commercial repositories? 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: ''
      release_branches:
        description: 'Update the release/<version> branches (e.g. release/5.0.5.1 for a hotfix) instead of the <major>.<minor>.x maintenance branches. Each project''s branch is derived from its own version in the properties file; projects without that branch are skipped.'
        required: false
        type: boolean
        default: false
      dry_run:
        description: 'Dry run, if checked nothing is committed or pushed, but you can see what would change'
        required: false
        type: boolean
        default: true
      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 }}
      commercial: ${{ steps.parse.outputs.commercial }}
      release-repo: ${{ steps.parse.outputs.release-repo }}
      props-file: ${{ steps.parse.outputs.props-file }}
      internal: ${{ steps.parse.outputs.internal }}
    steps:
      # Only so the inline scripts below can require .github/scripts/.
      - uses: actions/checkout@v4

      - name: Parse releaser config and build matrix
        id: parse
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          TRAIN_VERSION: ${{ inputs.release_train_version }}
          COMMERCIAL: ${{ inputs.commercial }}
          PROJECTS_FILTER: ${{ inputs.projects }}
          RELEASE_BRANCHES: ${{ inputs.release_branches }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');
          const path = require('path');
          const { execFileSync } = require('child_process');
          // The one implementation of this rule, shared with update-project-versions - the
          // action that reads the very file this names - and with the composite actions that
          // need it from bash. This job checks the repository out, so the module is under the
          // workspace.
          const { releaserConfigFileName } = require(path.join(process.env.GITHUB_WORKSPACE,
            '.github', 'scripts', 'releaser-config-file.js'));
          const { RELEASER_CONFIG_REPO, RELEASER_CONFIG_BRANCH, fetchReleaserConfig } =
            require(path.join(process.env.GITHUB_WORKSPACE,
              '.github', 'scripts', 'releaser-config.js'));


          const trainVersion = (process.env.TRAIN_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); };

          // 3 or 4 numeric segments, optionally with a qualifier: 2025.1.3, 2025.1.3-SNAPSHOT,
          // 2025.1.0-RC1, 2025.1.2.1, 2025.1.4-INTERNAL-SNAPSHOT (the qualifier may itself
          // contain hyphens). Anything else would resolve to a properties file name that cannot
          // exist, so it is rejected here rather than as a confusing 404.
          if (!/^\d+(\.\d+){2,3}(-[A-Za-z][\w.]*)*$/.test(trainVersion)) {
            fail(`ERROR: release_train_version must be 3 or 4 numeric segments with an optional ` +
              `qualifier (e.g. 2025.1.3-SNAPSHOT, 2025.1.2 or 2025.1.4-INTERNAL-SNAPSHOT); ` +
              `got '${trainVersion}'.`);
          }

          // An -INTERNAL train addresses the <major>.<minor>.x-internal branches, which exist
          // only in the commercial repositories.
          const internal = /-INTERNAL(-|$)/i.test(trainVersion);

          // This job must read exactly the file update-project-versions will read, or it
          // would validate one file and apply another.
          const propsFile = releaserConfigFileName(trainVersion);

          // ── projects filter ─────────────────────────────────────────────────────────
          // Commerciality comes from the names when they are given, because the names are what
          // the caller actually typed. A mixed list is rejected: one train version addresses one
          // line, so a mix would apply the wrong versions to half the list.
          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.`);
            }
          }

          if (internal && process.env.RELEASE_BRANCHES === 'true') {
            fail(`ERROR: ${trainVersion} is an -INTERNAL train, which targets the -internal ` +
              'branches; it cannot be combined with release_branches.');
          }

          if (internal && !commercial) {
            fail(`ERROR: ${trainVersion} is an -INTERNAL train, and -internal branches exist only ` +
              'in the -commercial repositories. Set commercial, or use -commercial project names.');
          }

          // Where the config lives, from the shared module - it owns that choice for every
          // caller. `commercial` decides only which project repositories are updated.
          const releaseRepo = RELEASER_CONFIG_REPO;
          const BRANCH = RELEASER_CONFIG_BRANCH;

          // ── read the properties file ────────────────────────────────────────────────
          console.log(`Reading ${propsFile} from ${releaseRepo}@${BRANCH}...`);
          // content as well as entries: the CDN wait below compares what raw.githubusercontent
          // serves against the bytes the API returned, so it needs the file itself.
          let content, entries;
          try {
            ({ content, entries } = fetchReleaserConfig(trainVersion));
          } catch (err) {
            fail(`ERROR: ${err.message}.`,
              'This workflow applies an existing properties file, it does not create one.',
              'Check that release_train_version matches a file on that branch (post-release',
              'writes the -snapshot file; it can also be committed by hand), and that the token',
              'has read access to the repository.');
          }
          console.log(`Found ${entries.length} version entries.`);

          // spring-boot and spring-vault are in the properties file so that every project picks up
          // their versions, but they are not Spring Cloud repositories and nothing is pushed to them.
          const NON_REPO_KEYS = new Set(['spring-boot', 'spring-vault']);

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

          const matrix = entries
            .filter(e => !NON_REPO_KEYS.has(e.key))
            .filter(e => !wanted || wanted.has(e.key))
            .map(e => ({
              project: e.key,
              repo: commercial ? `spring-cloud/${e.key}-commercial` : `spring-cloud/${e.key}`,
              version: e.version,
            }))
            .sort((a, b) => a.project.localeCompare(b.project));

          // ── make sure raw serves this exact file ────────────────────────────────────
          // update-project-versions resolves versions over raw.githubusercontent.com, which is
          // CDN-cached. A file committed moments ago - by post-release, or by hand, which is the
          // common case for this workflow - may 404 or still serve its previous contents there.
          // Applying stale versions across every repository is far worse than waiting, so this
          // blocks until raw agrees with the API, and fails the run if it never does.
          const url = `https://raw.githubusercontent.com/${releaseRepo}/${BRANCH}/${propsFile}`;
          console.log(`Waiting for ${url} to serve these contents...`);
          let available = false;
          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 expected contents after ${attempt} attempt(s).`);
              available = true;
              break;
            }
            console.log(`Attempt ${attempt}: ` +
              (served === null ? 'not served yet' : 'still serving different contents') +
              ', waiting 10s...');
            execFileSync('sleep', ['10']);
          }
          if (!available) {
            fail('', `ERROR: ${url} never served the contents the API returned for ${propsFile}.`,
              'Nothing was changed. Re-run this workflow once the CDN catches up.');
          }

          console.log('');
          console.log(`commercial:      ${commercial}`);
          console.log(`internal:        ${internal}`);
          console.log(`release repo:    ${releaseRepo}`);
          console.log(`properties file: ${propsFile}`);
          console.log('');
          console.log(`Projects to update: ${matrix.length}`);
          for (const e of matrix) console.log(`  ${e.repo} -> ${e.version}`);

          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, `commercial=${commercial}\n`);
          fs.appendFileSync(out, `release-repo=${releaseRepo}\n`);
          fs.appendFileSync(out, `props-file=${propsFile}\n`);
          fs.appendFileSync(out, `internal=${internal}\n`);
          JSEOF

  update:
    name: "Update — ${{ matrix.project }}"
    needs: setup
    if: needs.setup.outputs.count != '0'
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      max-parallel: 8
      matrix: ${{ fromJson(needs.setup.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

      # ── resolve the branch to work on ────────────────────────────────────────────────
      # The branch is always derived from the version in the properties file - there is no
      # input to override it. Between the .x derivation and the main fallback the action
      # makes, every OSS and commercial release-line branch this workflow targets is covered.
      # An -INTERNAL train is the exception: it resolves to <major>.<minor>.x-internal, with
      # no fallback, and only in the commercial repos. With release_branches it resolves
      # release/<version> instead (hotfix and release branches), also with no fallback.
      - name: Resolve target branch
        id: branch
        uses: ./.github/actions/resolve-release-branch
        with:
          repo: ${{ matrix.repo }}
          version: ${{ matrix.version }}
          commercial: ${{ needs.setup.outputs.commercial }}
          internal: ${{ needs.setup.outputs.internal }}
          release-branch: ${{ inputs.release_branches }}
          token: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}

      - name: Clone project
        id: clone
        if: steps.branch.outputs.status == 'ok'
        env:
          GH_TOKEN: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          REPO: ${{ matrix.repo }}
          BRANCH: ${{ steps.branch.outputs.branch }}
        run: |
          set -uo pipefail

          REMOTE="https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git"

          if ! git clone --quiet "$REMOTE" --branch "$BRANCH" project; then
            echo "::error::Could not clone ${REPO}@${BRANCH}."
            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"

          echo "Cloned ${REPO}@${BRANCH} at $(git rev-parse --short HEAD)."
          echo "status=cloned" >> "$GITHUB_OUTPUT"

      # ── apply the 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 versions
        id: bump
        if: steps.clone.outputs.status == 'cloned'
        continue-on-error: true
        uses: ./.github/actions/update-project-versions
        with:
          release-train-version: ${{ inputs.release_train_version }}
          # Hardcoded true, not the run's commercial flavour. This input does one thing in the
          # action - pick which repo the releaser config is fetched from
          # (update-project-versions/src/index.js:193-194) - and the config now always lives in
          # spring-cloud-release-commercial, including for OSS trains. Passing the derived value
          # would send an OSS run to spring-cloud-release, where the file no longer is.
          commercial: 'true'
          token: ${{ inputs.token || secrets.GH_ACTIONS_REPO_TOKEN }}
          directory: project

      - name: Commit and push
        id: push
        if: steps.bump.outcome == 'success'
        env:
          REPO: ${{ matrix.repo }}
          BRANCH: ${{ steps.branch.outputs.branch }}
          TRAIN_VERSION: ${{ inputs.release_train_version }}
          DRY_RUN: ${{ inputs.dry_run }}
        run: |
          set -euo pipefail
          cd project

          git add -A
          if git diff --cached --quiet; then
            # Re-running against versions that are already applied is the normal way this
            # happens, and it is not a failure.
            echo "No version changes to commit - already at the ${TRAIN_VERSION} versions."
            echo "status=no-changes" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          echo "Changes to commit:"
          git --no-pager diff --cached --stat

          # Deliberately no [skip actions], the same as post-release's bump: the point of moving
          # a branch onto new versions is to have CI build on them.
          MESSAGE="Updating project versions to ${TRAIN_VERSION}"
          git commit --quiet -m "$MESSAGE"

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

          git push --quiet origin "HEAD:refs/heads/${BRANCH}"
          echo "Pushed \"${MESSAGE}\" to ${REPO}@${BRANCH}."
          echo "status=pushed" >> "$GITHUB_OUTPUT"

      - 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 }}
          CLONE_STATUS: ${{ steps.clone.outputs.status }}
          BUMP_OUTCOME: ${{ steps.bump.outcome }}
          PUSH_STATUS: ${{ steps.push.outputs.status }}
        run: |
          set -euo pipefail

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

          jq -n \
            --arg project "$PROJECT" \
            --arg repo "$REPO" \
            --arg version "$VERSION" \
            --arg branch "${BRANCH:-}" \
            --arg branchStatus "${BRANCH_STATUS:-skipped}" \
            --arg cloneStatus "${CLONE_STATUS:-skipped}" \
            --arg bumpOutcome "${BUMP_OUTCOME:-skipped}" \
            --arg pushStatus "${PUSH_STATUS:-skipped}" \
            '{project: $project, repo: $repo, version: $version, branch: $branch,
              branchStatus: $branchStatus, cloneStatus: $cloneStatus,
              bumpOutcome: $bumpOutcome, pushStatus: $pushStatus}' \
            > "result-update-${SAFE}.json"

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

  summary:
    name: Summary
    needs: [setup, update]
    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
        env:
          TRAIN_VERSION: ${{ inputs.release_train_version }}
          COMMERCIAL: ${{ needs.setup.outputs.commercial }}
          PROPS_FILE: ${{ needs.setup.outputs.props-file }}
          RELEASE_REPO: ${{ needs.setup.outputs.release-repo }}
          PROJECTS_FILTER: ${{ inputs.projects }}
          DRY_RUN: ${{ inputs.dry_run }}
        run: |
          node - << 'JSEOF'
          const fs = require('fs');

          const dryRun = (process.env.DRY_RUN || 'false') === 'true';
          const commercial = (process.env.COMMERCIAL || 'false') === 'true';
          const trainVersion = process.env.TRAIN_VERSION || '';
          const propsFile = process.env.PROPS_FILE || '';
          const releaseRepo = process.env.RELEASE_REPO || '';
          const filter = (process.env.PROJECTS_FILTER || '').trim();

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

          const L = [];
          L.push(dryRun ? '## Update versions summary (dry run — nothing was changed)'
                        : '## Update versions summary');
          L.push('');
          L.push(`Applying **${trainVersion}** · ${commercial ? 'commercial' : 'OSS'}` +
            (filter ? ` · filtered to \`${filter}\`` : ''));
          if (propsFile) {
            L.push('');
            L.push(`Versions read from \`${propsFile}\` on \`${releaseRepo}\`` +
              '@`jenkins-releaser-config`.');
          }
          L.push('');

          // "Pushed" and "was already at these versions" have to read differently, or a run that
          // changed nothing looks identical to one that did all the work.
          const ICON = {
            pushed: '✅', success: '✅',
            'would-push': '🔎',
            'no-changes': '➖', skipped: '⏭️', cancelled: '⚠️',
            cloned: '✅',
            'clone-failed': '❌', 'branch-not-found': '❌', 'version-mismatch': '❌',
            failure: '❌',
          };
          const icon = s => ICON[s] || '❔';

          if (results.length) {
            L.push('| Project | Version | Branch | Update | Push |');
            L.push('|---|---|---|---|---|');
            for (const r of results) {
              const branch = r.branch
                ? `\`${r.branch}\``
                : `${icon(r.branchStatus)} ${r.branchStatus}`;
              // The clone failing is what a blank bump column would otherwise hide.
              const update = r.cloneStatus === 'clone-failed'
                ? `${icon('clone-failed')} clone-failed`
                : `${icon(r.bumpOutcome)} ${r.bumpOutcome}`;
              L.push(`| \`${r.project}\` | ${r.version} | ${branch} | ${update} | ` +
                `${icon(r.pushStatus)} ${r.pushStatus} |`);
            }
            L.push('');

            const pushed = results.filter(r => r.pushStatus === 'pushed').length;
            const would = results.filter(r => r.pushStatus === 'would-push').length;
            const unchanged = results.filter(r => r.pushStatus === 'no-changes').length;
            const failed = results.filter(r =>
              r.branchStatus === 'branch-not-found' || r.branchStatus === 'version-mismatch' ||
              r.cloneStatus === 'clone-failed' || r.bumpOutcome === 'failure');

            L.push(`**${results.length}** project(s) processed — ` +
              (dryRun ? `**${would}** would be pushed` : `**${pushed}** pushed`) +
              `, **${unchanged}** already at these versions, **${failed.length}** failed.`);
            L.push('');

            if (failed.length) {
              L.push('### ❌ Not updated');
              L.push('');
              L.push('Fix these and re-run with `projects` set to just this list — projects that');
              L.push('were already updated will report no changes rather than being touched again.');
              L.push('');
              for (const r of failed) {
                const why = r.branchStatus === 'branch-not-found'
                    ? `no branch for ${r.version} to update`
                  : r.branchStatus === 'version-mismatch'
                    ? 'only `main` exists and it is on a different line'
                  : r.cloneStatus === 'clone-failed' ? 'could not be cloned'
                  : 'the version update failed — see that job\'s log';
                L.push(`- \`${r.repo}\` — ${why}`);
              }
              L.push('');
            }
          } else {
            L.push('No projects were processed.');
            L.push('');
          }

          if (dryRun) {
            L.push('This was a **dry run**. Re-run with `dry_run` unchecked to push these changes.');
          }

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