Releases Hub Gradle Plugin
Gradle Plugin to automatically upgrade your java gradle project dependencies and send a GitHub pull request with the changes.
You can read this blog post for more detailed information.
How it works
- Apply and configure the plugin according to your needs
- Invoke the
upgradeDependenciestask on your CI tool (daily, weekly, monthly, as you wish) - If any of your dependencies is out-of-date, the plugin will create a pull request to update it.
- Verify that your PR CI checks pass, scan the included release notes, perform manual tests, and merge the PR.
Features
- Automatic Pull Request creation, including useful information whenever available:
- new version release notes link
- library documentation link
- library source code link
- library issue tracker link
- library size
- new permissions added by the library (only for android libraries)
- Support to configure which dependencies include and exclude, where to find their definitions, how many pull requests create and more.
- Support any java based project using Gradle.
Setup
Add the following configuration to your root build.gradle, replacing X.Y.Z by the latest version
Using the plugins DSL:
plugins {
id "com.dipien.releaseshub.gradle.plugin" version "X.Y.Z"
}
Using legacy plugin application:
buildscript {
repositories {
mavenCentral() // or gradlePluginPortal()
}
dependencies {
classpath("com.dipien:releases-hub-gradle-plugin:X.Y.Z")
}
}
apply plugin: "com.dipien.releaseshub.gradle.plugin"
Configure
How to configure the properties
All the plugin configuration properties can be added using any of the following ways:
- Using the
releasesHubextension on the build.gradle. For example:
releasesHub {
gitHubWriteToken = "123"
}
- As a command line parameter. For example:
./gradlew listDependencies -PgitHubWriteToken=123
- As a property on a
gradle.propertiesfile. For example:
gitHubWriteToken = "123"
- As an extra property on the build.gradlee. For example:
ext.gitHubWriteToken = "123"
- As a System Environment property
Common Properties
Dependencies base path
The base path for the class names where the dependencies are defined. The default value is buildSrc/src/main/kotlin/. This property is required
dependenciesBasePath = "buildSrc/src/main/kotlin/"
Dependencies class names
The class names where the dependencies are defined. The default value is ["Libs.kt", "BuildLibs.kt"]. This property is required
dependenciesClassNames = ["Libs.kt", "BuildLibs.kt"]
Includes
The dependencies to include. You can define a groupId to match all the artifacts for that group id, or groupId:artifactId to match a particular artifact. By default all the dependencies found on dependenciesClassNames are included.
includes = ["com.groupid1", "com.groupid2:artifact1"]
Excludes
The dependencies to exclude. You can define a groupId to match all the artifacts for that group id, or groupId:artifactId to match a particular artifact. By default there aren't excluded dependencies.
excludes = ["com.groupid1", "com.groupid2:artifact1"]
If you need to exclude the Gradle upgrade, use "gradle". For example:
excludes = ["gradle"]
Usage
We suggest to define your dependencies on /buildSrc/src/main/kotlin/Libs.kt and /buildSrc/src/main/kotlin/BuildLibs.kt classes. For example:
Libs.kt
object Libs {
const val KOTLIN = "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.40"
}
BuildLibs.kt
object BuildLibs {
const val KOTLIN_PLUGIN = "org.jetbrains.kotlin:kotlin-gradle-plugin:1.3.41"
}
Root build.gradle
apply plugin: "kotlin"
apply plugin: "com.dipien.releaseshub.gradle.plugin"
buildscript {
dependencies {
classpath(BuildLibs.KOTLIN_PLUGIN)
}
}
dependencies {
compile(Libs.KOTLIN)
}
See the sample for more details.
Tasks
Validate dependencies
Validate all the dependencies. The following validations are executed:
- All the dependencies defined on each
dependenciesClassNamesare sorted alphabetically bygroupId:artifactId - There are not duplicated dependencies defined on each
dependenciesClassNames - There are not dependencies with snapshot or dynamic versions assigned
- There are dependencies on
dependenciesClassNamesbut not used on the project - There are declared dependencies on any build.gradle but not defined on
dependenciesClassNamesclasses
./gradlew validateDependencies
Properties
Unused Excludes
The dependencies to exclude from the unused validation. You can define a groupId to match all the artifacts for that group id, or groupId:artifactId to match a particular artifact. By default there aren't excluded dependencies.
unusedExcludes = ["com.groupid1", "com.groupid2:artifact1"]
Unused extensions to search
The file extensions of the files where the artifact's packages will we search to find unused dependendencies. By default [".kt", ".java", ".xml"]
unusedExtensionsToSearch = [".kt", ".java"]
List dependencies
Print all the dependencies that will be analyzed to upgrade.
./gradlew listDependencies
List dependencies to upgrade
Print all the dependencies that are upgradeable. A file build/releasesHub/dependencies_to_upgrade_count.txt is generated with the count of dependencies that are upgradeable. This could be useful for metrics.
./gradlew listDependenciesToUpgrade
Upgrade dependencies
This task creates a Github Pull Request for each groupId that have at least one dependency to upgrade.
The following steps are executed for each groupId:
- Creates the
headBranch(headBranchPrefix+groupId) (if not exists) - Merge from the
baseBranchto theheadBranch - Upgrade all the dependencies defined on the
dependenciesClassNamesfor thegroupId - Create a commit for each dependency upgraded
- Push the previous commits to the
headBranch - Create a GitHub pull request from the
headBranchto thebaseBranch
./gradlew upgradeDependencies
Properties
Pull Request Enabled
Whether a pull request with all the upgrades should be created or not. The default value is true
pullRequestEnabled = false
Pull Requests Max
The maximum amount of pull requests to create during the task execution. This is useful to avoid creating too much pull requests when you still have many dependencies to upgrade. The default value is 5
pullRequestsMax = 10
Pull Request Labels
The list of labels to assign when creating the pull request. Optional list.
pullRequestLabels = ["dependencies"]
Pull Request Reviewers
The list of reviewers to assign when creating the pull request. Optional list.
pullRequestReviewers = ["octocat", "hubot", "other_user"]
Pull Request Team Reviewers
The list of team reviewers to assign when creating the pull request. Optional list.
pullRequestTeamReviewers = ["justice-league"]
Head Branch Prefix
The branch's prefix where the commit will be pushed. Also, the head branch's prefix of the pull request to create. Required String (only if pullRequestEnabled is true). The default value is releases_hub/.
headBranchPrefix = "branch_name_"
Base Branch
The pull request base branch. Optional String. The default value is master.
baseBranch = "master"
GitHub User Name
The GitHub user name used by the commit command. Optional String.
gitHubUserName = "user"
GitHub User Email
The GitHub user email used by the commit command. Optional String.
gitHubUserEmail = "[email protected]"
GitHub Repository Owner
The GitHub repository owner where the pull request will be created. Required String (only if pullRequestEnabled is true).
gitHubRepositoryOwner = "repo_owner"
GitHub Repository Name
The GitHub repository name where the pull request will be created. Required String (only if pullRequestEnabled is true).
gitHubRepositoryName = "repo_name"
GitHub Write Token
The GitHub write token needed to access the GitHub API to create the pull request. Follow these steps to create your token. We strongly recommend to not use the releasesHub extension for this property, to avoid exposing it on the git repository. Required String (only if pullRequestEnabled is true).
gitHubWriteToken = "123"
GitHub Api Host Name
The GitHub api host name needed to access the GitHub Enterprise. Optional String.
gitHubApiHostName = "your.githubenterprise.com"
Versioning
This project uses the Semantic Versioning guidelines for transparency into our release cycle.
Privacy Policy
The listDependenciesToUpgrade & upgradeDependencies tasks send to Releases Hub servers the groupId, artifactId and version of the project dependencies, in order to process and fetch the artifacts updates. That information is sent using SSL and it is NOT stored on the servers. The dependencies excluded through the plugin configuration are not send to the servers.
Sponsor this project
Sponsor this open source project to help us get the funding we need to continue working on it.
- Donate cryptocurrency
- Donate with PayPal
- Donate on Patreon
- Become a member of Medium [We will receive a portion of your membership fee]
34 Sep 27, 2022
27 Dec 20, 2022
110 Dec 19, 2022
195 Dec 31, 2022
21 Sep 21, 2022
0 Apr 10, 2022
2 Mar 8, 2022
56 Nov 18, 2022
228 Jan 2, 2023
4 Oct 11, 2021
307 Dec 26, 2022
502 Dec 31, 2022
8 Nov 26, 2022
1 Feb 26, 2022
58 Dec 22, 2022
235 Jan 3, 2023
1.1k Dec 28, 2022
262 Jan 5, 2023
21 Oct 14, 2022