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.3"
}
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"
}
-
repositoryOwner
: GitHub user or organization name (optional, defaults tospring-projects
) -
repositoryName
: GitHub repository name (optional, defaults toproject.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 thereferenceDocUrl
; Useful for working with Antora (optional, defaults tofalse
) -
releaseVersionPrefix
: The prefix used to tag the release version; typically used to prefix withv
, e.g.v1.0.1
(optional, defaults to an empty string)
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:
Internal tasks (only used by other tasks):
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.
|
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
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
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, usesgetNextReleaseMilestone
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
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, usesgetNextReleaseMilestone
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
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, usesgetNextReleaseMilestone
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
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, usesgetNextReleaseMilestone
if not specified) -
branch
: Specify the branch used to tag the release (optional, defaults tomain
) -
createRelease
: Flag controlling whether the release is created (true
) or a dry-run is performed (false
) (optional, defaults tofalse
) -
gitHubAccessToken
: A personal access token used to avoid hitting rate limits on the GitHub API and/or create the release (optional, required ifcreateRelease
istrue
)
Full example:
./gradlew createRelease -PnextVersion=1.0.0 -Pbranch=1.0.x -PcreateRelease=true -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN
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, usesgetNextReleaseMilestone
if not specified) -
branch
: Specify the branch used to tag the release (optional, defaults tomain
) -
createRelease
: Flag controlling whether the release is created (true
) or a dry-run is performed (false
) (optional, defaults tofalse
) -
gitHubAccessToken
: A personal access token used to avoid hitting rate limits on the GitHub API and/or create the release (optional, required ifcreateRelease
istrue
)
Full example:
./gradlew createGitHubRelease -PnextVersion=1.0.0 -Pbranch=1.0.x -PcreateRelease=true -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN
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, usesproject.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
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, usesgetPreviousReleaseMilestone
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
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, usesgetNextReleaseMilestone
if not specified) -
gitHubAccessToken
: A personal access token used to avoid hitting rate limits on the GitHub API (optional) -
gitHubUserName
: The username that owns thegitHubAccessToken
(optional, usesgetGitHubUserName
to look up the username if not specified)
Full example:
./gradlew generateChangelog -PnextVersion=1.0.0 -PgitHubAccessToken=$GITHUB_ACCESS_TOKEN -PgitHubUserName=spring-user
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)
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, usesproject.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
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, usesproject.version
if not specified)
Full example:
./gradlew getNextSnapshotVersion -PcurrentVersion=1.0.0
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, usesproject.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
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, usesgetNextReleaseMilestone
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