Skip to content

build: make the release pipeline rehearsable and recoverable - #3443

Merged
bnasslahsen merged 1 commit into
springdoc:mainfrom
gwr0-0:build/release-pipeline
Nov 19, 2026
Merged

bnasslahsen merged 1 commit into
springdoc:mainfrom
gwr0-0:build/release-pipeline

Conversation

@gwr0-0

@gwr0-0 gwr0-0 commented Nov 18, 2026

Copy link
Copy Markdown

Problem

The release workflow was not safe to run:

  • It ran the test suite before release:prepare, then deployed a build that had never been verified. A failure after the tag was pushed had no documented way back.
  • dryRun executed release:prepare release:perform -DdryRun=...; release:perform -DdryRun=true runs no goals, so the "rehearsal" proved nothing.
  • A single release:prepare release:perform invocation with -Darguments skipped tests in both the prepare-time verify and the perform-time deploy.
  • Nothing checked, before anything was pushed, that the version was not already tagged or published (Central releases are immutable).

Changes

  • Gate the release on tests: new test job (same command as CI, permissions: contents: read) + needs: test; the release job keeps release:prepare's forked clean verify, which is what prevents a bad tag from being pushed. The suite therefore runs twice by design: once before any version transformation, once on the release POM.
  • Real rehearsal: dryRun now runs release:prepare -DdryRun=true -DpushChanges=false, then release:clean + git checkout -- . + scratch-file cleanup in the same step, and fails if the working tree is dirty.
  • Fail-closed preflight: refuses a tag or Central version that already exists before anything is pushed; a failed Central request stops the run instead of being read as "version is free". Applies to rehearsals too, so a rehearsal needs an unused version.
  • Split prepare/perform: two Maven invocations. -Darguments now applies only to release:perform, so the prepare-time verify runs the suite and only the deploy skips it.
  • Credentials at job level: MAVEN_USERNAME/MAVEN_PASSWORD/MAVEN_GPG_PASSPHRASE/GITHUB_TOKEN are set on the release job, so splitting steps cannot silently drop them.
  • Recovery step: on failure, writes to the run summary whether the tag was already pushed and what to do next.
  • Docs: new .github/workflows/RELEASING.md (procedure, rehearsal limits, recovery), linked from CONTRIBUTING.adoc and the workflow header.

Verification

  • release.yml parses (YAML); git diff --check clean; git range-diff against the previous branch state shows only the intended structural changes.
  • git merge-base --is-ancestor main HEAD → this PR is one commit on top of b46782a94 (current main, which already contains build: drop the stale distributionManagement #3430).
  • All workflow Actions in the new test job are the repository's current versions (checkout@v7, setup-java@v6, cache@v6).
  • Workflow runtime behavior cannot be exercised locally (GPG key, Central token, tag push). Dry-run rehearsal needs a version that is neither tagged nor published — e.g. the next candidate release version — and must be run in the canonical repository after merge.

Notes for reviewers

  • The two test runs are intentional; see the comments in release.yml and RELEASING.md § "What a real run does".
  • This targets main. spring-boot-3 would need a backport of release.yml/RELEASING.md if 2.10.x releases should use it.
  • The <distributionManagement> removal (build: drop the stale distributionManagement #3430) is already merged, so RELEASING.md's statement matches main.
  • No CHANGELOG.md entry: release tooling only, not the published API or behavior.

The release job ran the test suite before release:prepare and then deployed
a build that had never been verified, its dry run executed nothing at all,
and a failure after release:prepare had no way back.

- Gate the release job on tests passing so a release can no longer start
  from red code, and keep the suite running inside release:prepare as well:
  its forked "clean verify" is what stops a bad release before the tag is
  pushed. The suite therefore runs twice by design, in the Test job and in
  release:prepare; the previous comment claimed once.
- Give the release job the Central credentials at job level. They were set
  on the single release step before, and setup-java resolves them from the
  environment, so splitting that step must not be allowed to drop them.
- Run release:prepare and release:perform as two Maven invocations inside
  the publish step. The plugin's arguments parameter reaches both the
  prepare-time verify and the perform deploy through the phase they share,
  so -Darguments only applies to the invocation carrying it: the
  prepare-time verify runs the suite and only the deploy skips it. Omitting
  it on the perform invocation would run the suite again inside the deploy,
  because the perform mojo overwrites the stored exec.additionalArguments
  with its own value. The split is also what lets the recovery step run at
  all, since it is reached only if the publish step fails.
- Make dryRun a real rehearsal: run release:prepare alone with dryRun and
  pushChanges disabled, drop the release:perform that executed no goals, and
  clean up without -DdryRun (release:clean has no such parameter, so the
  flag would be silently ignored). Rehearsal and cleanup share one step so
  the cleanup always runs and no message can report a failed rehearsal as OK.
- Make the preflight fail closed. It refuses a tag or a Central version that
  already exists before anything is pushed, and a Central request that fails
  stops the run rather than being read as "the version is free" - the one
  case where the check must not pass. The version check also applies to
  rehearsals, so a rehearsal needs an unused version.
- Pass workflow inputs to the shell through env instead of interpolating
  them into the script text.
- Document the procedure, the limits of a rehearsal and the recovery steps
  in .github/workflows/RELEASING.md.

The root POM no longer declares a <distributionManagement> (springdoc#3430); the new
RELEASING.md assumes that change.
@bnasslahsen
bnasslahsen merged commit 1d0f1a0 into springdoc:main Nov 19, 2026
1 check passed
bnasslahsen added a commit that referenced this pull request Nov 19, 2026
…suite once

Set MAVEN_USERNAME, MAVEN_PASSWORD, MAVEN_GPG_PASSPHRASE and GITHUB_TOKEN on the
git configuration and the two release-plugin steps only, as before, instead of on
the whole release job. Skip the tests in release:prepare as well: the Test job
that gates the release already runs the suite on the commit being released.
See #3443

Signed-off-by: Badr NASS LAHSEN <badr.nasslahsen@gmail.com>
@bnasslahsen

Copy link
Copy Markdown
Collaborator

Thanks, merged, with a follow-up commit (ba89e8f) on top:

  • The release credentials are back on the steps that use them (git configuration and the two release-plugin invocations), so the preflight and the other actions don't get them.
  • release:prepare skips the tests too: the new test job gates the release, so the suite runs once per release, as before.

We'll rehearse it with dryRun on main before the 3.2.1 release, then backport it to spring-boot-3.

bnasslahsen added a commit that referenced this pull request Nov 19, 2026
…suite once

Set MAVEN_USERNAME, MAVEN_PASSWORD, MAVEN_GPG_PASSPHRASE and GITHUB_TOKEN on the
git configuration and the two release-plugin steps only, as before, instead of on
the whole release job. Skip the tests in release:prepare as well: the Test job
that gates the release already runs the suite on the commit being released.
See #3443

Signed-off-by: Badr NASS LAHSEN <badr.nasslahsen@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants