Gradle plugin that reports newer versions of your dependencies, Gradle plugins and the Gradle wrapper. It asks the Google deps.dev Open Source Insights API and, for your own artifacts, the Maven repositories you list.
Supports both gradle/libs.versions.toml (Version Catalog) and build.gradle / build.gradle.kts.
Requires a Gradle daemon running on Java 25 or later; your own code can still target Java 17+.
- Plugin id:
one.epicsoft.depcheck - License: MIT
- Source: developed on GitLab, mirrored to GitHub — issues are welcome on both; code changes only as merge requests on GitLab, the mirror cannot take pull requests
Usage
1. Apply the plugin
The plugin is on the Gradle Plugin Portal, which Gradle asks by default — add it to build.gradle, there is no repository to declare:
plugins {
id "one.epicsoft.depcheck" version "0.6.1"
}2. Configuration (optional)
depsUpdate {
verbose = true // default: false — like showAll, plus where each entry was found and the entries not checked
showAll = true // default: false — show all checked dependencies, not only updates
failOnUpdates = true // default: false — fail the build when updates are available
includePreRelease = true // default: false — count RC, Alpha, Beta, Milestone as valid updates
// Exclude coordinates from the check (group:name for libraries, plugin ID for plugins)
exclude = ["com.example:some-lib", "org.some.plugin"]
// Version pattern per coordinate: numbers cap the candidates, a trailing "x" sets the level at which an update counts
maxVersion = [
"org.springframework.boot:spring-boot-starter": "3", // 3.x.x only, every newer 3.x.y is reported
"org.springframework.boot" : "3.2", // 3.2.x only
"software.amazon.awssdk:s3" : "2.x" // 2.x.x, new minor lines only — no patches
]
checkGradleWrapper = true // default: true — check the Gradle Wrapper version
checkSubprojects = false // default: true — check the root build only, ignore subprojects
// Asked for what deps.dev does not know, e.g. your own artifacts in a package registry
mavenRepositories = ["https://repo.example.com/maven"]
// Required when the root project AND a subproject set the same parameter:
excludeMode = "MERGE" // "MERGE" = combine, "OVERRIDE" = subproject only
maxVersionMode = "OVERRIDE" // "MERGE" = combine (subproject wins on conflicts)
}| Option | Type | Default | Description |
|---|---|---|---|
verbose | Boolean | false | Show all dependencies (incl. current ones) + where every entry was found (deps.dev, the Maven repository, Gradle releases for the wrapper) + the entries not checked and why |
showAll | Boolean | false | Show all checked dependencies, not only updates (implied by verbose) |
failOnUpdates | Boolean | false | The build fails when at least one update is available |
includePreRelease | Boolean | false | Count pre-releases (snapshot, alpha, beta, RC, milestone, build) as newer versions |
exclude | List<String> | [] | Coordinates skipped entirely (group:name or plugin ID) |
maxVersion | Map<String, String> | {} | Version pattern per coordinate: numbers = cap, trailing x = level at which an update counts (table below) |
checkGradleWrapper | Boolean | true | Check the Gradle Wrapper version via services.gradle.org |
checkSubprojects | Boolean | true | false = the root task checks only the root build.gradle + the catalog entries referenced there |
mavenRepositories | List<String> | [] | Maven repositories asked for coordinates deps.dev does not know (next section); inherited by subprojects |
excludeMode | String | — | Required on collision: "MERGE" = combine root + sub; "OVERRIDE" = subproject list only |
maxVersionMode | String | — | Required on collision: "MERGE" = combine, subproject wins on the same key; "OVERRIDE" = subproject map only |
Artifacts outside deps.dev
deps.dev only knows public repositories such as Maven Central. Artifacts published elsewhere — your own libraries and Gradle plugins in a GitLab or other package registry — answer with HTTP 404 there. List those repositories in mavenRepositories, and every coordinate deps.dev does not know is looked up in them via maven-metadata.xml:
depsUpdate {
mavenRepositories = [
"https://gitlab.example.com/api/v4/projects/123/packages/maven",
"https://repo.example.com/releases",
]
}- deps.dev is asked first; a repository only for what deps.dev does not know.
- Never Maven Central. deps.dev covers it;
repo.maven.apache.org,repo1.maven.organdcentral.sonatype.cominmavenRepositoriesfail the task. - All listed repositories are asked, their versions are combined; the same filters and
maxVersionpatterns apply. Non-numeric entries such asmainordevelop(branch builds) are ignored. - Gradle plugins are looked up by their marker artifact, as with deps.dev.
- Anonymous access only. A URL with credentials (
https://user:secret@…) fails the task, so a secret can never end up in the build log; a repository that needs a login is reported as a failed lookup. - The XML parser refuses a
DOCTYPE, so a manipulated response cannot pull in external entities.
Version patterns in maxVersion
Leading numbers cap which versions are considered. A trailing x (also X or *) sets the level at which a newer version counts as an update — anything after it is ignored. x may only come last; "2.x.5" fails the task with an error message.
| Value | Considered | Reported |
|---|---|---|
"3" | 3.x.x | every newer 3.x.y |
"2.55" | 2.55.x | every newer 2.55.y |
"2.x" | 2.x.x | a new minor line only (2.56.0), no patches |
"2.56.x" | 2.56.x | every newer 2.56.y — same as "2.56" |
"x" | all | a new major version only |
"x.x" | all | new major and minor versions, no patches |
Central configuration (root → subprojects)
All scalar options (verbose, showAll, failOnUpdates, includePreRelease, checkGradleWrapper, checkSubprojects) and mavenRepositories are inherited automatically from the root project by the subprojects and can be overridden there.
For exclude and maxVersion:
- Only the root defines it → the subproject inherits it automatically
- Only the subproject defines it → the subproject value is used
- Both define it →
excludeMode/maxVersionModemust be set in the subproject, otherwise the build fails
// build.gradle (root) — OUTSIDE of subprojects {}
depsUpdate {
failOnUpdates = true
exclude = ["com.example:legacy-lib"]
maxVersion = ["org.springframework.boot:spring-boot-starter": "3"]
}
// core/build.gradle
depsUpdate {
// failOnUpdates, maxVersion are inherited
exclude = ["com.example:core-internal"]
excludeMode = "MERGE" // → both lists combined
}Caution:
depsUpdate {}in the root must not be placed insidesubprojects {}. Asubprojects { depsUpdate { exclude = [...] } }configures the extension of every subproject directly — when the subproject then runs its owndepsUpdate { exclude = [...] }, Gradle overwrites the value completely. The rootdepsUpdate {}stays empty and inheritance does not apply.Correct:
// Root build.gradle depsUpdate { exclude = ["com.example:shared-exclude"] } // ← at root level subprojects { apply plugin: "one.epicsoft.depcheck" // optional: the root plugin already applies it to every subproject // no depsUpdate {} here }
3. Run the task
./gradlew checkDependencyUpdatesExample output
Default (verbose = false, showAll = false) — updates only:
Scanning: gradle/libs.versions.toml
Scanning: build.gradle
Scanning: core/build.gradle
Available updates (2):
[library] org.springframework.boot:spring-boot-starter 3.2.0 → 3.4.1
[plugin ] org.springframework.boot 3.2.0 → 3.4.1showAll = true — all dependencies:
Checked 3 dependencies:
[library] com.fasterxml.jackson.core:jackson-databind 2.18.3
[library] org.springframework.boot:spring-boot-starter 3.2.0 → 3.4.1
[plugin ] org.springframework.boot 3.2.0 → 3.4.1
2 update(s) available.verbose = true — all dependencies with link (showAll is implied):
Checked 3 dependencies:
[library] com.fasterxml.jackson.core:jackson-databind 2.18.3
https://deps.dev/maven/com.fasterxml.jackson.core:jackson-databind
[library] org.springframework.boot:spring-boot-starter 3.2.0 → 3.4.1
https://deps.dev/maven/org.springframework.boot:spring-boot-starter
[plugin ] org.springframework.boot 3.2.0 → 3.4.1
https://deps.dev/maven/org.springframework.boot:org.springframework.boot.gradle.plugin
2 update(s) available.Lookup problems
A dependency that could not be looked up is never dropped silently:
| Situation | Output |
|---|---|
| deps.dev or services.gradle.org unreachable, HTTP error, unreadable response | Warning Lookup failed for N dependencies — not checked, the result is incomplete; if no update was found, the summary reads All checked dependencies are up-to-date. instead of All dependencies … |
A maxVersion pattern matches no version | Warning No version matches the maxVersion pattern — check the configuration |
| Neither deps.dev nor a configured repository knows the package, it has no stable version, or its version expression cannot be resolved | One line N not checked — verbose = true lists them and why.; with verbose = true listed under Not checked |
Failed lookups do not fail the build on their own; failOnUpdates only reacts to updates found.
What is scanned?
| Source | Content |
|---|---|
gradle/libs.versions.toml | [libraries] and [plugins] (incl. version.ref resolution, all notations) |
gradle/wrapper/gradle-wrapper.properties | Gradle version, against services.gradle.org (checkGradleWrapper) |
build.gradle / build.gradle.kts | implementation, api, compileOnly, runtimeOnly, testImplementation, testRuntimeOnly, testCompileOnly, testAnnotationProcessor, annotationProcessor, developmentOnly, classpath — also wrapped in platform(…) / enforcedPlatform(…) —, mavenBom (Spring dependency management) + plugins {} block |
Versions may come from a variable in the same file (def, val, ext.), from the root gradle.properties or from the catalog (${libs.versions.spring.cloud.get()}).
Both syntaxes (Groovy + Kotlin DSL) are recognized.
Behaviour with subprojects
| Task | Behaviour |
|---|---|
./gradlew checkDependencyUpdates | Runs the task in all projects (root + all subprojects) |
./gradlew :checkDependencyUpdates | Runs only the root task — scans libs.versions.toml (all entries) + the build.gradle of all subprojects |
./gradlew :checkDependencyUpdates (checkSubprojects = false) | Runs only the root task and scans only the root build.gradle + the catalog entries referenced there |
./gradlew :core:checkDependencyUpdates | Scans only core/build.gradle — from the version catalog only the libs.* aliases actually referenced are checked |
Note:
./gradlew checkDependencyUpdates(without:) is standard Gradle behaviour — Gradle runs the task in every project that registered it. For root only, always use./gradlew :checkDependencyUpdates.
Catalog alias syntax (implementation libs.someLib) is resolved and checked automatically in subprojects.
How it works
- The task reads all dependency coordinates from the build files.
- For every coordinate the deps.dev REST API is queried in parallel (Java Virtual Threads):
GET https://api.deps.dev/v3/systems/MAVEN/packages/{groupId%3AartifactId} - Retracted and pre-release versions (
-SNAPSHOT,-alpha,-beta,-RC,-M1…) are filtered out. - Gradle plugins are resolved via their Maven marker artifact:
{pluginId}:{pluginId}.gradle.plugin - What deps.dev does not know is looked up in
mavenRepositories, if configured:GET {repository}/{groupId with / instead of .}/{artifactId}/maven-metadata.xml
Developing the plugin
Requirements
- Java 25+ (Gradle daemon)
- Gradle Wrapper (in the repo)
The plugin runs in the Gradle daemon (Java 25). Your own application can still be compiled for Java 17+.
Build
./gradlew build # compiles, validates the plugin and runs the tests (src/test)The tests need no network: the deps.dev and repository clients run against local HTTP servers, and a TestKit build checks the task with the configuration cache and --warning-mode=fail.
Publishing
Runs automatically in the CI pipeline when a Git tag is pushed: PUB:plugin to the GitLab Package Registry (CI_JOB_TOKEN is set automatically) and PUB:portal to the Gradle Plugin Portal (CI variables GRADLE_PUBLISH_KEY and GRADLE_PUBLISH_SECRET, masked and protected). A version on the Portal cannot be replaced, and a new plugin id waits for a manual review there. The repository reaches GitHub through a GitLab push mirror; the pipeline then creates the GitHub release with the CHANGELOG.md entry of the tag and the JARs attached.
./gradlew publishPlugins --validate-only # checks the Portal metadata, uploads nothingOn main the pipeline also checks the runtime dependencies — Gson and the Kotlin standard library, the JARs the plugin brings into your build: their licenses (./gradlew checkLicense, permissive licenses only), known vulnerabilities (OWASP dependency-check) and newer versions, with the plugin checking its own build. It also builds with deprecated Gradle features treated as errors, so they show up before the next Gradle major removes them. It runs on every push and weekly.
Project structure
src/main/kotlin/one/epicsoft/gradle/
├── DepsUpdatePlugin.kt # Registers extension + task
├── DepsUpdateExtension.kt # Configuration (verbose, exclude, maxVersion, …)
├── task/CheckUpdatesTask.kt # Task implementation
├── api/DepsDevClient.kt # deps.dev HTTP client
├── api/MavenRepositoryClient.kt # maven-metadata.xml lookup in configured repositories
├── api/VersionSources.kt # deps.dev first, then the repositories
├── api/Versions.kt # picks the newest usable version (shared filters)
├── api/Lookup.kt # lookup outcome: latest / no match / unknown / failed
├── api/VersionPattern.kt # maxVersion pattern (cap + update level)
└── parser/
├── VersionCatalogParser.kt # libs.versions.toml
└── BuildGradleParser.kt # build.gradle / build.gradle.ktsReleasing a new version
- Bump
versioningradle.propertiesand in this README - Head the
CHANGELOG.mdentry with## [X.Y.Z] - <date>of the coming release — never[Unreleased] - Set a Git tag:
git tag 0.6.1 && git push --tags— tags carry nov(the CI would strip one) - The CI pipeline publishes to the GitLab Package Registry and the Gradle Plugin Portal and creates the GitHub release automatically
- Update the version in the consuming projects
Tech stack
| Language | Kotlin 2.4.21 |
| Gradle | 9.8.2 |
| HTTP | java.net.http.HttpClient (no external framework) |
| JSON | Gson 2.15.0 |
| Tests | JUnit 6 + kotlin-test |
| Concurrency | Java Virtual Threads (Executors.newVirtualThreadPerTaskExecutor()) |
Note: Gradle 9.8.2 embeds Kotlin 2.4.10. The two need not be identical, because this project compiles plain Kotlin sources rather than precompiled script plugins; a genuine incompatibility shows up as
incompatible version of Kotlinat compile time.
License
The MIT license applies only to files created by epicsoft LLC. Third-party files, such as the Gradle wrapper, remain under their own licenses.