RELEASE.adoc

Release Process

The release process for Spring Security is entirely automated via the Spring Security Release Plugin and reusable workflows. The following table outlines the steps that are taken by the automation.

Warning

The 5.8.x branch does not have all of the improvements from the 6.x.x branches. See "Status (5.8.x)" for which steps are still manual.

In case of a failure, you can follow the links below to read about each step, which includes instructions for performing the step manually if applicable. See FAQ for troubleshooting tips.

Step	Status (5.8.x)	Status (6.0.x+)
Update dependencies	✅ automated	✅ automated
Check all issues are closed	✅ automated	✅ automated
Update release version	✅ automated	✅ automated
Tag release	✅ automated	✅ automated
Push release commit	✅ automated	✅ automated
Build	✅ automated	✅ automated
Update release notes on GitHub	✅ automated	✅ automated
Update version on project page	❌ manual	✅ automated
Close milestone	❌ manual	✅ automated
Announce release on Slack	✅ automated	✅ automated
Update to next development version	✅ automated	✅ automated
Create milestone	✅ automated	✅ automated
Announce release on other channels	❌ manual	❌ manual

Update dependencies

Dependency versions are managed in the file libs.versions.toml and are automatically updated by dependabot.

Check all issues are closed

The first step of a release is to check if there are any open issues remaining in a milestone.

Note	A scheduled release will not proceed if there are any open issues.

Tip	If you need to prevent a release from occurring automatically, the easiest way to block a release is to add an unresolved issue to the milestone.

The checkMilestoneHasOpenIssues command will check if there are any open issues for the release. Before running the command manually, replace the following values:

• <next-version> - Replace with the title of the milestone you are releasing now (i.e. 5.5.0-RC1)

• <github-personal-access-token> - Replace with a GitHub personal access token that has a scope of public_repo. This is optional since you are unlikely to reach the rate limit for such a simple check.

./gradlew checkMilestoneHasOpenIssues -PnextVersion=<next-version> -PgitHubAccessToken=<github-personal-access-token>

Alternatively, you can manually check using the milestones page.

Update release version

If all issues for the release are closed, the version number is automatically updated using the milestone title. When performing this step manually, update the version number in gradle.properties for the release (for example 5.5.0) and commit the change using the message "Release x.y.z".

Tag release

The release will automatically be tagged using the milestone title. It is not required to tag manually. However, you can perform this step manually by running the following command:

git tag 5.5.0

Push release commit

During a scheduled release, the release commit will automatically be pushed to trigger a build. If performing this step manually, you can push the commit and tag and GitHub actions will build and deploy the artifacts with the following command:

git push --atomic origin main 5.5.0

The build will automatically wait for artifacts to be released to Maven Central. You can get notified manually when uploading is complete by running the following:

./scripts/release/wait-for-done.sh 5.5.0

Build

All checks will automatically be performed by the build prior to uploading the artifacts to Maven Central. If something goes wrong, you can run the build locally using:

./gradlew check

Update release notes on GitHub

Once the release has been uploaded to Maven Central, release notes will automatically be generated and a GitHub release will be created. To do this manually, you can use the generateChangelog command to generate the release notes by replacing:

• <next-version> - Replace with the milestone you are releasing now (i.e. 5.5.0)

./gradlew generateChangelog -PnextVersion=<next-version>

Then copy the release notes to your clipboard (your mileage may vary with the following command):

cat build/changelog/release-notes.md | xclip -selection clipboard

Finally, create the release on GitHub, associate it with the tag, and paste the generated notes.

Alternatively, you can run the createGitHubRelease command to perform these steps automatically, replacing:

• <next-version> - Replace with the milestone you are releasing now (i.e. 5.5.0)

• <branch> - The name of the branch to be tagged (if the release commit has not already been tagged)

• <github-personal-access-token> - Replace with a GitHub personal access token that has a scope of write:org

./gradlew createGitHubRelease -PnextVersion=<next-version> -Pbranch=<branch> -PcreateRelease=true -PgitHubAccessToken=<github-personal-access-token>

Update version on project page

The build will automatically update the project versions on https://spring.io/projects/spring-security#learn. To do this manually, you can use the createSaganRelease and deleteSaganRelease commands using the following parameters:

• <next-version> - Replace with the milestone you are releasing now (i.e. 5.5.0)

• <previous-version> - Replace with the previous release which will be removed from the listed versions (i.e. 5.5.0-RC1)

• <github-personal-access-token> - Replace with a GitHub personal access token that has a scope of read:org as documented for spring.io api

./gradlew createSaganRelease deleteSaganRelease -PnextVersion=<next-version> -PpreviousVersion=<previous-version> -PgitHubAccessToken=<github-personal-access-token>

Alternatively, you can log into Contentful and update the versions manually on the Spring Security project page.

Close / Create milestone

The release milestone will be automatically closed once the release is complete. To proceed manually, perform the following steps:

1. Visit GitHub Milestones and create a new milestone for the next release version

2. Move any open issues from the existing milestone you just released to the new milestone

3. Close the milestone for the release

Note	Remember that scheduled releases will not proceed if there are still open issues in the milestone.

Announce release on Slack

The release will automatically be announced on Slack. If proceeding manually, announce the release on Slack in the channel #spring-release, including the keyword spring-security-announcing in the message. Something like:

spring-security-announcing `5.5.0` is available now

Update to next development version

After the release is complete and artifacts have been uploaded to Maven Central, the build will automatically update to the next development version, commit and push. If proceeding manually, update the version in gradle.properties to the next SNAPSHOT version with the commit message "Next development version" and then push.

Announce release on other channels

• Create a blog post on Contentful

• Tweet from @SpringSecurity

Frequently Asked Questions

When should I update dependencies manually? Dependencies should be updated at the latest the end of the week prior to the release. This is usually the Friday following the 2nd Monday of the month (counting from the first week with a Monday). When in doubt, check the milestones page for release due dates.

When do scheduled releases occur? Automated releases are scheduled to occur at 3:15 PM UTC on the 3rd Monday of the month (counting from the first week with a Monday).

Note	The scheduled release process currently runs every Monday but only releases when a release is due. See the performed checks below for more information.

The automated release process occurs on the following branches:

• main

• 6.2.x

• 6.1.x

• 6.0.x (commercial only)

• 5.8.x

For each of the above branches, the automated process performs the following checks before proceeding with the release:

1. Check if the milestone is due today. This check compares the current (SNAPSHOT) version of the branch with available milestones and chooses the first match (sorted alphabetically). If the due date on the matched milestone is not today, the process stops.

2. Check if all issues are closed. This check uses the milestone from the previous step and looks for open issues. If any open issues are found, the process stops.

Important

You should ensure all issues are closed or moved to another milestone prior to a scheduled release.

If the above checks pass, the version number is updated (in gradle.properties) and a commit is pushed to trigger the CI process.

How do I trigger a release manually? You can trigger a release manually in two ways:

1. Trigger a release for a particular branch via update-scheduled-release-version.yml on the desired branch. The above checks are performed for that branch, and the release will proceed if all checks pass. This is the recommended way to trigger a release that did not pass the above checks during a regularly scheduled release.

2. Trigger releases for all branches via release-scheduler.yml on the main branch. The above checks are performed for each branch, and only releases that pass all checks will proceed.

When should additional manual steps be performed? All other automated steps listed above occur during the normal CI process. Additional manual steps can be performed at any time once the builds pass and releases are finished.

What if something goes wrong? If the normal CI process fails, you can retry by re-running the failed jobs with the "Re-run failed jobs" option in GitHub Actions. If changes are required, you should revert the "Release x.y.z" commit, delete the tag, and proceed manually.