Gradle-Plugin

DepCheck — Dependency Update Checker for Gradle

Findet neuere Versionen Ihrer Abhängigkeiten und Gradle-Plugins über deps.dev.

Dokumentation aus der README der Version 0.6.1, auf Englisch.

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)
}
OptionTypeDefaultDescription
verboseBooleanfalseShow 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
showAllBooleanfalseShow all checked dependencies, not only updates (implied by verbose)
failOnUpdatesBooleanfalseThe build fails when at least one update is available
includePreReleaseBooleanfalseCount pre-releases (snapshot, alpha, beta, RC, milestone, build) as newer versions
excludeList<String>[]Coordinates skipped entirely (group:name or plugin ID)
maxVersionMap<String, String>{}Version pattern per coordinate: numbers = cap, trailing x = level at which an update counts (table below)
checkGradleWrapperBooleantrueCheck the Gradle Wrapper version via services.gradle.org
checkSubprojectsBooleantruefalse = the root task checks only the root build.gradle + the catalog entries referenced there
mavenRepositoriesList<String>[]Maven repositories asked for coordinates deps.dev does not know (next section); inherited by subprojects
excludeModeString—Required on collision: "MERGE" = combine root + sub; "OVERRIDE" = subproject list only
maxVersionModeString—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.org and central.sonatype.com in mavenRepositories fail the task.
  • All listed repositories are asked, their versions are combined; the same filters and maxVersion patterns apply. Non-numeric entries such as main or develop (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.

ValueConsideredReported
"3"3.x.xevery newer 3.x.y
"2.55"2.55.xevery newer 2.55.y
"2.x"2.x.xa new minor line only (2.56.0), no patches
"2.56.x"2.56.xevery newer 2.56.y — same as "2.56"
"x"alla new major version only
"x.x"allnew 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 / maxVersionMode must 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 inside subprojects {}. A subprojects { depsUpdate { exclude = [...] } } configures the extension of every subproject directly — when the subproject then runs its own depsUpdate { exclude = [...] }, Gradle overwrites the value completely. The root depsUpdate {} 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 checkDependencyUpdates

Example 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.1

showAll = 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:

SituationOutput
deps.dev or services.gradle.org unreachable, HTTP error, unreadable responseWarning 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 versionWarning 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 resolvedOne 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?

SourceContent
gradle/libs.versions.toml[libraries] and [plugins] (incl. version.ref resolution, all notations)
gradle/wrapper/gradle-wrapper.propertiesGradle version, against services.gradle.org (checkGradleWrapper)
build.gradle / build.gradle.ktsimplementation, 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

TaskBehaviour
./gradlew checkDependencyUpdatesRuns the task in all projects (root + all subprojects)
./gradlew :checkDependencyUpdatesRuns 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:checkDependencyUpdatesScans 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

  1. The task reads all dependency coordinates from the build files.
  2. 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}
  3. Retracted and pre-release versions (-SNAPSHOT, -alpha, -beta, -RC, -M1 …) are filtered out.
  4. Gradle plugins are resolved via their Maven marker artifact: {pluginId}:{pluginId}.gradle.plugin
  5. 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 nothing

On 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.kts

Releasing a new version

  1. Bump version in gradle.properties and in this README
  2. Head the CHANGELOG.md entry with ## [X.Y.Z] - <date> of the coming release — never [Unreleased]
  3. Set a Git tag: git tag 0.6.1 && git push --tags — tags carry no v (the CI would strip one)
  4. The CI pipeline publishes to the GitLab Package Registry and the Gradle Plugin Portal and creates the GitHub release automatically
  5. Update the version in the consuming projects

Tech stack

LanguageKotlin 2.4.21
Gradle9.8.2
HTTPjava.net.http.HttpClient (no external framework)
JSONGson 2.15.0
TestsJUnit 6 + kotlin-test
ConcurrencyJava 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 Kotlin at compile time.


License

MIT

The MIT license applies only to files created by epicsoft LLC. Third-party files, such as the Gradle wrapper, remain under their own licenses.

Sprechen wir über Ihr Projekt

Erzählen Sie uns, was Sie vorhaben – Sie erhalten eine ehrliche Einschätzung und ein klares Angebot.

Kontakt aufnehmen