release-plugin

Spring Security Release Plugin

Spring Security Release Plugin is a Gradle plugin that provides common tasks for automating releases.

To use the plugin, apply the plugin in your project’s root build.gradle:

plugins {
	id "io.spring.security.release" version "1.0.4"
}

Finally, define your project’s configuration via the springRelease DSL. Here is an example configuration that releases on Thursdays following the 2nd Monday of the month (i.e. Spring Framework’s release day):

springRelease {
    repositoryOwner = "spring-projects"
    repositoryName = "spring-framework"
    weekOfMonth = 2
    dayOfWeek = 4
    referenceDocUrl = "https://docs.spring.io/spring-framework/reference/{version}/index.html"
    apiDocUrl = "https://docs.spring.io/spring-framework/docs/{version}/api/"
    replaceVersionInReferenceDocUrl = true
    releaseVersionPrefix = "v"
}

springRelease Property Reference

• repositoryOwner: GitHub user or organization name (optional, defaults to spring-projects)

• repositoryName: GitHub repository name (optional, defaults to project.name)

• weekOfMonth: The week of the month when releases for this project are scheduled; valid values are 1 - 3 where 1 is the first week with a Monday (required)

• dayOfWeek: The day of the week when releases for this project are scheduled; valid values are 1 - 5 where 1 is Monday and 5 is Friday (required)

• referenceDocUrl: The template URL for a version of the reference documentation; can contain the variable {version} which is automatically substituted based on the current version (required)

• apiDocUrl: The template URL for a version of the API documentation; can contain the variable {version} which is automatically substituted based on the current version (required)

• replaceVersionInReferenceDocUrl: Flag controlling whether {version} should be replaced (true) or left as-is (false) in the referenceDocUrl; Useful for working with Antora (optional, defaults to false)

• releaseVersionPrefix: The prefix used to tag the release version; typically used to prefix with v, e.g. v1.0.1 (optional, defaults to an empty string)

Tasks

There are two types of tasks provided by this plugin:

• Top-level tasks which you would normally run during CI as part of an automated release

• Internal tasks which are used by other tasks

Note	Some top-level tasks are also used by other tasks.

Top-level tasks:

• checkBranchHasCommercialSupport

• checkBranchHasOssSupport

• checkMilestoneIsDueToday

• checkMilestoneHasOpenIssues

• closeMilestone

• createRelease

• createGitHubRelease

• createSaganRelease

• deleteSaganRelease

• getNextReleaseMilestone

• getNextSnapshotVersion

• scheduleNextRelease

Internal tasks (only used by other tasks):

• generateChangelog

• getGitHubUserName

• getPreviousReleaseMilestone

Tip	By adding gitHubAccessToken=…​ to ~/.gradle/gradle.properties, many of these tasks can be performed with no additional inputs and therefore can be run directly from your IDE while avoiding GitHub rate limits.

Task Reference

checkBranchHasCommercialSupport

Checks if the given branch has commercial support and outputs true or false.

The following command will determine if the given branch has commercial support:

./gradlew checkBranchHasCommercialSupport -Pbranch=1.0.x

Task properties:

• branch: Specify the branch used check support (required)

• gitHubAccessToken: A personal access token used to avoid hitting rate limits on the GitHub API (optional)

Full example:

./gradlew checkBranchHasCommercialSupport -Pbranch=1.0.x -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

checkBranchHasOssSupport

Checks if the given branch has OSS support and outputs true or false.

The following command will determine if the given branch has OSS support:

./gradlew checkBranchHasOssSupport -Pbranch=1.0.x

Task properties:

• branch: Specify the branch used to check support (required)

• gitHubAccessToken: A personal access token used to avoid hitting rate limits on the GitHub API (optional)

Full example:

./gradlew checkBranchHasOssSupport -Pbranch=1.0.x -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

checkMilestoneIsDueToday

Checks if the given version is due today or past due and outputs true or false.

The following command will determine if there are no open issues (based on the current version):

./gradlew checkMilestoneIsDueToday

Task properties:

• nextVersion: Specify the version used to check the due date (optional, uses getNextReleaseMilestone if not specified)

• gitHubAccessToken: A personal access token used to avoid hitting rate limits on the GitHub API (optional)

Full example:

./gradlew checkMilestoneIsDueToday -PnextVersion=1.0.0 -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

checkMilestoneHasOpenIssues

Checks if there are open issues for the next release milestone and outputs true or false.

The following command will determine if there are open issues (based on the current version):

./gradlew checkMilestoneHasOpenIssues

Task properties:

• nextVersion: Specify the version used to check for open issues (optional, uses getNextReleaseMilestone if not specified)

• gitHubAccessToken: A personal access token used to avoid hitting rate limits on the GitHub API (optional)

Full example:

./gradlew checkMilestoneHasOpenIssues -PnextVersion=1.0.0 -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

closeMilestone

Closes a release milestone for the specified version.

The following command will close a release milestone (based on the current version):

./gradlew closeMilestone

Task properties:

• nextVersion: Specify the version of the release milestone to close (optional, uses getNextReleaseMilestone if not specified)

• gitHubAccessToken: A personal access token used access the GitHub API (required)

Full example:

./gradlew closeMilestone -PnextVersion=1.0.0 -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

createRelease

Create a GitHub release with release notes using the GitHub API and a new release version for the current project on spring.io using the Sagan API. This task uses generateChangelog to generate the release notes and the configured referenceDocUrl, apiDocUrl and replaceVersionInReferenceDocUrl values from the DSL.

Note	This task is a combination of createGitHubRelease and createSaganRelease, with the added benefit that the createRelease parameter (see Task properties below) determines whether both APIs are actually called.

The following command will perform a dry-run and provide output of what creating the next release would look like:

./gradlew createRelease

Task properties:

• nextVersion: Specify the version used to create the release (optional, uses getNextReleaseMilestone if not specified)

• branch: Specify the branch used to tag the release (optional, defaults to main)

• createRelease: Flag controlling whether the release is created (true) or a dry-run is performed (false) (optional, defaults to false)

• gitHubAccessToken: A personal access token used to avoid hitting rate limits on the GitHub API and/or create the release (optional, required if createRelease is true)

Full example:

./gradlew createRelease -PnextVersion=1.0.0 -Pbranch=1.0.x -PcreateRelease=true -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

createGitHubRelease

Create a GitHub release with release notes using the GitHub API. This task uses generateChangelog to generate the release notes.

The following command will perform a dry-run and provide output of what creating the next release would look like:

./gradlew createGitHubRelease

Task properties:

• nextVersion: Specify the version used to create the release (optional, uses getNextReleaseMilestone if not specified)

• branch: Specify the branch used to tag the release (optional, defaults to main)

• createRelease: Flag controlling whether the release is created (true) or a dry-run is performed (false) (optional, defaults to false)

• gitHubAccessToken: A personal access token used to avoid hitting rate limits on the GitHub API and/or create the release (optional, required if createRelease is true)

Full example:

./gradlew createGitHubRelease -PnextVersion=1.0.0 -Pbranch=1.0.x -PcreateRelease=true -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

createSaganRelease

Create a new release version for the current project on spring.io using the Sagan API. This task uses the configured referenceDocUrl, apiDocUrl and replaceVersionInReferenceDocUrl values from the DSL.

The following command will create a new release version:

./gradlew createSaganRelease -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

Task properties:

• nextVersion: Specify the version used to create the release (optional, uses project.version if not specified)

• gitHubAccessToken: A personal access token used to access the Sagan API (required)

Full example:

./gradlew createSaganRelease -PnextVersion=1.0.0 -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

deleteSaganRelease

Delete a release version for the current project on spring.io using the Sagan API.

The following command will delete the previous release version:

./gradlew deleteSaganRelease -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

Task properties:

• previousVersion: Specify the version used to delete the release (optional, uses getPreviousReleaseMilestone if not specified)

• gitHubAccessToken: A personal access token used to access the Sagan API (required)

Full example:

./gradlew deleteSaganRelease -PpreviousVersion=1.0.0 -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

generateChangelog

Generate the release notes (changelog) for a milestone using github-changelog-generator.

The following command will determine the next available GitHub release milestone (based on the current version), and generate a changelog which is written to build/changelog/release-notes.md:

./gradlew generateChangelog

Task properties:

• nextVersion: Specify the version used to generate the changelog (optional, uses getNextReleaseMilestone if not specified)

• gitHubAccessToken: A personal access token used to avoid hitting rate limits on the GitHub API (optional)

• gitHubUserName: The username that owns the gitHubAccessToken (optional, uses getGitHubUserName to look up the username if not specified)

Full example:

./gradlew generateChangelog -PnextVersion=1.0.0 -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN -PgitHubUserName=spring-user

getGitHubUserName

Use the gitHubAccessToken to look up the user using the GitHub API and output the username.

The following command will look up the GitHub username:

./gradlew getGitHubUserName -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

Task properties:

• gitHubAccessToken: A personal access token used to look up the user using the GitHub API (required)

getNextReleaseMilestone

Finds or calculates the next release version based on the current version and outputs the version number.

If the current version is a SNAPSHOT with a patch version of 0, the GitHub API is used to find the next milestone (sorted by due date) that matches the base version number. If no milestone exists, the base version is used instead. In all other cases, the base version is chosen automatically.

For example, if the current version is 1.0.0-SNAPSHOT and milestones 1.0.0-M2, 1.0.0-RC1 and 1.0.0 are available, then 1.0.0-M2 will be chosen based on due date. If the current version is 1.0.1-SNAPSHOT, then 1.0.1 (the base version) is chosen automatically without consulting the GitHub API.

Note	This task is used internally by several other tasks to automatically determine the next release milestone when the nextVersion property is not specified.

The following command determines the next available GitHub release milestone (based on the current version):

./gradlew getNextReleaseMilestone

Task properties:

• currentVersion: Specify the version used to calculate the next release milestone (optional, uses project.version if not specified)

• gitHubAccessToken: A personal access token used to avoid hitting rate limits on the GitHub API (optional)

Full example:

./gradlew getNextReleaseMilestone -PcurrentVersion=1.0.0 -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

getNextSnapshotVersion

Calculates the next snapshot version based on the current version and outputs the version number.

For example, if the current version is a milestone such as 1.0.0-M2, then this task outputs 1.0.0-SNAPSHOT. If the current version is a GA version such as 1.0.0, then this task increments the patch version and outputs 1.0.1-SNAPSHOT.

The following command determines the next snapshot version (based on the current release version):

./gradlew getNextSnapshotVersion

Task properties:

• currentVersion: Specify the version used to calculate the next snapshot version (optional, uses project.version if not specified)

Full example:

./gradlew getNextSnapshotVersion -PcurrentVersion=1.0.0

getPreviousReleaseMilestone

Finds the previous release version based on the current version using the Sagan API (now backed by Contentful) and outputs the version number.

If the current version is a SNAPSHOT, this task finds an existing SNAPSHOT version with the same major/minor version. If the current version is a GA version, this task finds an existing GA version with the same major/minor version. If multiple (ambiguous) options or no options exist (not found), this task outputs a message indicating the problem but does not fail.

The following command will determine the previous release milestone (based on the current version):

./gradlew getPreviousReleaseMilestone -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

Task properties:

• currentVersion: Specify the version used to calculate the previous release milestone (optional, uses project.version if not specified)

• gitHubAccessToken: A personal access token used to access the GitHub and Sagan APIs (required)

Full example:

./gradlew getPreviousReleaseMilestone -PcurrentVersion=1.0.0 -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

scheduleNextRelease

Schedule the next release (even months only) or release train (series of milestones starting in January or July) based on the current version. This task works with the concept of a Spring release train to automate scheduling one or more milestones using the configured weekOfMonth and dayOfWeek values from the DSL. All dates are calculated based on the first Monday of the month.

For example, if the current date is June 1, 2023, the current version is 1.0.0-SNAPSHOT, weekOfMonth is 2 and dayOfWeek is 4 (i.e. Spring Framework’s release day), then this task can schedule a release train for July 13, 2023 (1.0.0-M1), August 17, 2023 (1.0.0-M2), September 14, 2023 (1.0.0-M3), October 12, 2023 (1.0.0-RC1) and November 16, 2023 (1.0.0).

However with all other values being the same, if the current version is 1.0.1-SNAPSHOT, this task will simply schedule a patch release on the next even month (which is the current month in this example) of June 15, 2023 (1.0.1). The logic to determine whether to schedule a release train or a single patch release is based on the value of the patch version, where x.x.0 attempts to schedule a release train, and x.x.1 or higher schedules a patch release.

This task does nothing if the next release milestone already exists.

The following command schedules the next release milestone (or release train):

./gradlew scheduleNextRelease -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN

Task properties:

• nextVersion: Specify the version used to schedule the next release milestone (optional, uses getNextReleaseMilestone if not specified)

• gitHubAccessToken: A personal access token used to access the GitHub API (required)

Full example:

./gradlew scheduleNextRelease -PnextVersion=1.0.0 -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN