Gradle Dependency Locking, Verification & Caching

Locking is enabled per configuration; once enabled, a lock state must exist (or be created, see below), and the build then fails if resolution no longer produces what the file says. For a few configurations the resolution strategy has the switch:

Only resolvable configurations carry lock state; the call on a consumable or declarable one does nothing. A build that wants every project configuration locked says so once, with the dependencyLocking extension, typically for all projects:

lockAllConfigurations() locks the configurations of the project, not those of the build script (buildscript { configurations.classpath }) nor those of the settings; both have their own switch, shown in the section "The build script and the settings". The task resolveAndLockAll is the helper that the Gradle documentation describes for writing all the lock states in one run, and it is explained in the next section. In the Groovy build it uses matching and not findAll: on Gradle 9.8.1 the first version of this build file used configurations.findAll { it.canBeResolved }.each { ... }, and the build printed The DomainObjectCollection.findAll(Closure) method has been deprecated. This is scheduled to be removed in Gradle 10. with a link to the upgrade guide, because findAll on a domain object collection is going away; matching returns the live, filtered collection and has no such problem. (The Kotlin filter is the Kotlin standard library function on a collection and is not affected.)

Source: Gradle User Manual: Activate locking for all configurations

Lock state is only written when you ask for it, with --write-locks, on a build that resolves the locked configurations:

(The line about starting a daemon that could not reuse others is omitted; the machine had several daemons of other builds.) Gradle writes one gradle.lockfile per project, next to its build file, and one settings-gradle.lockfile for the dependency resolution management of the settings (the version catalog is resolved there). The lock file of the engine:

and of the command line project, which shows how the same module can be locked in some configurations and absent from others (the engine is an implementation dependency, so commons-csv is not on the compile classpath of the CLI):

The format is simple on purpose: one group:name:version per line followed by the configurations that contain it, sorted alphabetically so that version control diffs are small, and a last empty= line for locked configurations that resolved to nothing. The file belongs in version control, and Gradle does not write it when the build fails, so a failed resolution cannot leave a half-written state behind. The settings lock file had only the line empty=incomingCatalogForLibs0 (the configuration that resolves the catalog libs, which had no external dependencies).

Two details of the command are easy to miss. ./gradlew dependencies --write-locks writes the state of the configurations that the dependencies report resolves, and in a multi-project build the unqualified dependencies task runs in only one project (the one in the current directory): in the tidepool build it printed No configurations for the root project, persisted only the settings lock state, and created no gradle.lockfile at all. The two ways around it are naming the projects (./gradlew :tidepool-engine:dependencies :tidepool-cli:dependencies --write-locks) or a task that resolves everything, which is what resolveAndLockAll does. It declares itself incompatible with the configuration cache because it filters and resolves configurations at execution time; that is why this one command ran without --configuration-cache. The second detail: with --write-locks, Gradle ignores existing lock state and writes what the current resolution produced, and it writes only for the configurations that were resolved in that build. After ./gradlew compileJava --write-locks the lock file of the engine listed only compileClasspath and annotationProcessor; the runtime and test configurations had no entry (and so, in the default mode, nothing locked them) until a build resolved them.

Source: Gradle User Manual: Generating and updating dependency locks

Source: Gradle User Manual: Lock all configurations in one build execution

Gradle turns each locked entry into a strictly version constraint, which is the strongest of the rich version declarations (see Platforms, Constraints & Rich Versions). The dependency report shows them, marked (c) for constraint:

and dependencyInsight gives the reason in words:

(./gradlew :tidepool-engine:dependencyInsight --dependency commons-csv --configuration compileClasspath, first lines.) Because the lock is only a constraint, the ordinary rules of version conflict resolution apply to it, and they explain every failure below. For a transitive dependency the strict constraint pins the version, whatever the transitive path would have chosen. For a direct dependency, the declared version is a requirement and the lock a strict constraint: if the requirement is lower than or equal to the locked version (or a range or dynamic selector that the locked version satisfies), the locked version wins; if the requirement is higher than the locked version, the two conflict and resolution fails.

Source: Gradle User Manual: Understanding lock state location and format

With lock state present, resolution is validated against it in the default mode. The three ways it can go wrong are shown here, each with the real message. These runs are without --configuration-cache because, with it, Gradle reports the same failure inside a configuration cache serialization problem (error writing value of type DefaultResolvableConfiguration) that hides the message in a report.

A dependency is added and the lock was not updated. The engine gets a direct dependency on org.slf4j:slf4j-api:2.0.17 and nothing else changes:

A dependency is removed and the lock still lists it:

A direct dependency asks for more than the lock allows. The catalog was first [1.10,1.12), which locked Commons CSV at 1.11.0, and was then changed to the fixed version 1.14.1:

This last message is the one people find confusing, because nothing in the build file says strictly: the constraint comes from the lock file, and its path line says so ("Dependency version enforced by Dependency Locking"). The reverse direction does not fail: with the catalog at [1.10,1.12) and the lock at 1.11.0, changing it to the dynamic 1.+ left the report at 1.+ -> 1.11.0, because the locked version satisfies 1.+; the build kept 1.11.0 even though 1.14.1 existed, which is exactly what locking is for.

In the default mode there are therefore only two ways to change what the build resolves: change the declarations and update the lock in the same commit, or update the lock on its own. The next sections show the second.

Source: Gradle User Manual: Running a build with lock state present

--write-locks rewrites everything. To move only some modules, --update-locks takes a comma-separated list of module notations; the existing lock state is still used as input, except for the modules named, which are free to resolve again:

The starting point was the lock at 1.11.0 (written when the catalog said [1.10,1.12)) and a catalog that had been widened to 1.+. The lock files afterwards:

The module that was named moved from 1.11.0 to 1.14.1, and so did its transitive dependencies commons-io (2.16.1 to 2.20.0) and commons-codec (1.16.1 to 1.19.0), because the resolution rules choose their versions once the lock on the parent is gone. picocli stayed at 4.7.7 in the same run. Wildcards are allowed in the group and the name, but only as the whole value or at the end: org.apache.commons:*, *:guava and org.springframework.spring*:spring* are all valid notations. The option is marked [incubating] in ./gradlew --help on 9.8.1; the behaviour may still change. The same caveat as for --write-locks holds: only the configurations resolved in that build are updated.

This is also the whole renewal workflow of a team that wants fresh dependencies but reviewed ones: a scheduled job (or a bot) runs --write-locks, and the pull request that changes gradle.lockfile is the review. The next section gives the third option, loosening the rules.

Source: Gradle User Manual: Selectively updating lock state entries

The default mode, described so far, requires that existing entries are matched and that resolution adds nothing. Two other modes are selected with lockMode:

The default mode lets a configuration without a lock file through, which is the dangerous case: a new project or a new configuration is simply not locked, and nobody notices. With STRICT, deleting the lock file of tidepool-cli and building gives

Use STRICT in CI and for projects that must be reproducible; use LENIENT in a throwaway branch or a job that deliberately tests against newer versions. In LENIENT mode the same dependency added to the engine, with a dynamic version org.slf4j:slf4j-api:2.0.+ that has no lock entry, built without errors, and the report resolved it freely to 2.0.20 (the newest 2.0.x on the day) while the locked modules stayed at their locked versions:

Note that in this mode the locked entries are no longer strictly (they print as plain 1.14.1 (c)), which is how a dependency can shift.

Source: Gradle User Manual: Fine-tuning dependency locking behaviour with lock mode

Some dependencies are meant to move: an organisation’s own libraries, for example, which should always be the newest. The extension can exclude them from the lock state (they still resolve, but are neither recorded nor validated); the wildcard rules are the same as for --update-locks. The lock file location can also be changed, which is useful when one project has several variants of its dependencies (the manual’s example is the Scala binary version in the artifact coordinates, with a lock file per version):

With slf4j-api as a dependency of the engine, resolveAndLockAll --write-locks wrote tidepool-engine/gradle/locks/tidepool-engine.lockfile (and the same for the other two projects), and that file listed the three Commons modules but no slf4j-api; the build then passed without any entry for it. (The first gradle.lockfile files from the default location were still on disk from the earlier runs and were simply no longer used.) Ignoring dependencies defeats reproducibility for them by design; the manual suggests separate lock modes or separate lock files instead for anything that matters.

Source: Gradle User Manual: Ignoring specific dependencies from the lock state

Source: Gradle User Manual: Configuring the lock file name and location

The plugins that a build applies are dependencies too, and lockAllConfigurations() does not cover the configuration that holds them. For the buildscript classpath, activate locking there explicitly:

(A small separate project, so that it does not disturb the tidepool lock files; a real build would apply a plugin from the Plugin Portal in the same way, see Plugins Overview.) ./gradlew hello --write-locks wrote buildscript-gradle.lockfile, in both DSLs:

The third file is settings-gradle.lockfile, already seen above: it locks the dependencies of the settings (the plugins applied in settings.gradle(.kts), and the catalogs). Locking settings dependencies arrived in Gradle 6.8.

Source: Gradle User Manual: Activate locking for a buildscript classpath configuration

Locking has no built-in equivalent in either of the other tools. Ivy has fixed revisions and the deliver task that writes a concrete ivy file for publication (see Ivy: Conflicts & Versions); Maven’s answer is not to use ranges and to pin versions in the POM (see Maven Versions, SNAPSHOTs & Ranges), with the enforcer rules of Maven Dependency Analysis & Convergence to police it. The comparison table is in Dependency Management Fundamentals.

A checksum (SHA-256, say) fingerprints the content: it proves the file is the one whose hash you recorded, and says nothing about who produced it. A signature (a PGP .asc file published next to the artifact) proves who signed it, provided you trust the key; the manual points out that signatures alone may rest on weak hashes, so the strongest setup uses both. Gradle supports MD5, SHA-1, SHA-256 and SHA-512 checksums, of which only SHA-256 and SHA-512 are considered secure today. Signatures are verified only if they are ASCII-armoured .asc files on a remote repository.

Gradle verifies everything its dependency management engine downloads: jars and other artifacts, metadata files (POM, Ivy descriptors and Gradle Module Metadata), plugins (project and settings plugins) and artifacts resolved through advanced resolution APIs. It does not verify changing dependencies (SNAPSHOT versions) or artifacts the build itself produces, because their checksums change constantly. The file is global for the build: one file serves the root project, all subprojects and buildSrc; for a composite build, the file of the current build is used and those of the included builds are ignored.

Source: Gradle User Manual: Checksum verification

Source: Gradle User Manual: Signature verification

Source: Gradle User Manual: Scope of dependency verification

Verification is enabled the moment gradle/verification-metadata.xml exists. An empty file would make every build fail, so the file is generated:

The flag takes a comma-separated list of algorithms (and pgp), resolves every resolvable configuration of the build, downloads the artifacts and computes the checksums. Run with a Gradle user home that had never seen these dependencies, it wrote this file (the schema attribute of the root element and the middle components are shortened):

There are eight components for three declared dependencies: Commons CSV with its two transitive modules, picocli, and the parents and BOMs that appear only because their POMs are part of the metadata (org.apache:apache, commons-parent, junit-bom). Because metadata verification is on, every .pom and .module file has its own checksum; with <verify-metadata>false</verify-metadata> the file is much shorter but compromised metadata could add malicious transitive dependencies, which is why the manual advises against it. The origin="Generated by Gradle" marker means "recorded, not reviewed": bootstrapping trusts whatever the repositories serve right now, so the file must be reviewed, ideally against checksums published elsewhere than in the repository (the project’s own website), and the attribute changed to origin="Verified" or a note on where the value came from.

Bootstrap with a clean cache. The first bootstrap of this page ran against the shared Gradle user home, which already held these dependencies, and wrote seven components: the junit-bom-5.13.1.module entry above was missing. A later build with a clean Gradle user home then failed with One artifact failed verification: junit-bom-5.13.1.module, because that file had never been verified before. Gradle documents that artifacts that are only resolved at execution time or through custom resolution code can be missed; this was a different cause (the warm cache), and the practical rule is the same: generate the file with a fresh GRADLE_USER_HOME (or --refresh-dependencies), and prove it by building once more with another fresh one.

Source: Gradle User Manual: Generating and bootstrapping verification metadata

Source: Gradle User Manual: The verification metadata file

Most Maven Central artifacts are signed, so the file can say "trust this key" instead of "trust these bytes":

Gradle downloads the signature file of each artifact, fetches the public key from a key server, verifies the signature, and writes the key as trusted. The algorithm list must still contain a checksum, because not every artifact is signed: those get the fallback checksum. With a clean Gradle user home, the run wrote this:

Read it from the top. Eight components shrank to one, because everything signed by a key that is now trusted needs no entry of its own. The Apache Commons key is trusted for three groups together, grouped under one trusted-key with nested trusting elements. Picocli’s and the JUnit BOM’s keys were written as trusted only for exactly that module and version. The Apache parent POM was signed with a key that no key server had (it was recorded as an ignored key), so the artifact fell back to a checksum, with a reason saying why. Both the ignored key and the fallback checksum are things to review by hand: ideally find the key and add it to the keyring (see below). Gradle takes an optimistic view while bootstrapping, which is why the documentation recommends checksums first if integrity matters, then signatures.

The key identifiers are full 40-character fingerprints; Gradle requires full fingerprints for pgp and trusted-key entries, not short or long key IDs, to make collision attacks harder (ignored keys may use long IDs, as above). Never trust a key because of the name in its user ID: anyone can create a key with any name, and the right check is that the fingerprint is listed on the project’s own site (Apache projects publish a KEYS file).

The file the flag wrote with --export-keys is the local keyring, below. The elements of <configuration> are:

Source: Gradle User Manual: Understanding signature verification

Source: Gradle User Manual: Trusting keys globally

Fetching keys from key servers on every clean checkout is slow and makes CI depend on someone else’s availability. The answer is a keyring in the repository. --export-keys writes the public keys used for verification to two files in gradle/:

The .gpg file is binary (compact and editable with gpg), the .keys file is ASCII-armoured (readable in a pull request, mergeable by hand). Commit one: without a keyring-format element Gradle reads whichever exists, and the binary one takes precedence when both are present; with <keyring-format>armored</keyring-format> (or binary) only that format is read and written (since 8.5). Since Gradle 8.0 ./gradlew --export-keys alone exports the keys of an already trusted set, without writing the metadata; and it only stores public key packets and a single user ID per key. A binary keyring should be marked in .gitattributes (*.gpg binary). A key that Gradle cannot download but that you can find can be appended to the .keys file or imported into the .gpg one with gpg.

To make a build refuse the network completely for keys, disable the key servers:

With that in the metadata and the exported .keys file in gradle/, a build in a clean Gradle user home passed (14 s, because it downloaded the dependencies). Without the keyring file, the same build failed with 9 artifacts failed verification for the Commons modules (the list starts with commons-codec-1.19.0.jar): the keys were needed and could not be fetched. When a flag ignores enabled="false": if you ask Gradle to generate metadata and the existing file disables key servers, the setting is ignored so that missing keys can be downloaded.

Gradle caches keys it could not find for 24 hours; ./gradlew build --refresh-keys retries immediately. --refresh-keys was accepted and the build passed (nothing needed refreshing, so nothing visible changed).

Source: Gradle User Manual: Local keyring

Source: Gradle User Manual: Key servers and ignoring keys

Source: Gradle User Manual: Refreshing missing keys

Plugins are dependencies, so they are covered by the same file. The buildscript classpath project of the locking section (with commons-lang3) was bootstrapped with ./gradlew --write-verification-metadata sha256 hello and listed five components: org.apache:apache, commons-lang3, commons-parent, junit-bom and mockito-bom, the last two being BOMs imported by the parent POMs. Changing one checksum of the jar to zeros, and running the build, failed during configuration of the project, before any task:

That is the point of verifying plugins: a build file is code (see Supply-Chain Security), and a plugin artifact runs with the privileges of the build.

Gradle’s failure output has two layers: a summary on the console and an HTML report, linked in the message, with the full detail. The summary of a changed checksum on the tidepool engine (the metadata had the SHA-256 of commons-csv-1.14.1.jar replaced by zeros) is:

That is short, and in CI you cannot open a file in the workspace of a finished job. The property org.gradle.dependency.verification.console=verbose (in gradle.properties) prints the full text, including the expected and the actual value, which is what you need to decide whether this is a typo, a different binary in another repository or an attack:

The other failures that matter, all produced here:

Untrusted signature. The trusted-key of picocli was removed from the metadata:

(The name and e-mail address in the key’s user ID are replaced by (...).) Note the meaning: the signature is valid; Gradle simply does not know whether you trust the signer. Missing metadata. A new direct dependency was added to the engine without updating the file:

The advice in that message points to the anchor sec:troubleshooting-verification, which does not exist on the 9.8.1 page; the section on failures is sec:dealing-verification-failure (the same slip is noted on Supply-Chain Security). The same message shows why one new dependency means four artifacts: the jar, its POM, and the BOM and parent POM that the POM imports.

What to do depends on the failure. A missing entry is fixed by bootstrapping again (incremental, below). An untrusted key: check the fingerprint against the project’s website, then add the key. A checksum mismatch is the serious one: the options are a damaged or tampered file in the local cache (delete it and let Gradle download again), the same artifact published slightly differently to two repositories (accept both with also-trust, below), or a compromised artifact (inform the maintainers and the repository). Watch also for name squatting and repository shadowing, where look-alike coordinates, or the official ones in a repository that comes first, give the wrong file; content filtering (see Repositories & Content Filtering) and verification together close that gap. The HTML report explains each failure kind (checksum mismatch, key not trusted, signature did not match, key ignored, key not found, checksum missing, deleted artifact) and what to do about it.

Since Gradle 9.7, the console and the HTML report add a note when a signing key cannot be found on any key server: they report how many other keys are already trusted for that module or group. A non-zero count suggests that the key was rotated, a zero count that you are trusting something for the first time (not run here; described in the 9.7.0 release notes).

Source: Gradle User Manual: Troubleshooting verification failures

Source: Gradle User Manual: Configuring the console output

Verification is expensive for some workflows (frequent dependency upgrades, for example) and not for others (CI). There are three modes:

They are chosen with --dependency-verification (-F), the system property org.gradle.dependency.verification, or in gradle.properties. With the tampered checksum from above, --dependency-verification lenient printed the verification failure as plain text and the build ended in BUILD SUCCESSFUL:

and -F off printed nothing and ran the build normally. A sensible policy: strict everywhere that matters, lenient on a developer’s machine while upgrading, never off in CI. (To turn off verification for one configuration, for example one that a plugin uses to look up newer versions, call resolutionStrategy.disableDependencyVerification() on it; Gradle prints a warning when it is used.) The related <trusted-artifacts> entries below do the same job declaratively.

Source: Gradle User Manual: Verification modes

When a dependency changes, the build fails (as above) and the file needs more entries. Re-running the bootstrap adds them and keeps everything else, including hand-written entries, comments and trusted keys:

With the slf4j dependency added, the only change to the signature-based file was one line: the key of the SLF4J group was trusted.

and the build then passed. Always use the same list of algorithms as the first time. Gradle never deletes entries (it cannot know that a version is no longer used), so the file only grows; review the diff in every pull request, remove entries for old versions and change the origin="Generated by Gradle" markers.

Dry-run mode. To see what bootstrapping would write without touching the file, combine the flag with --dry-run:

(Tasks are not executed, so it is fast, but it misses dependencies that are resolved at execution time.) The proposal went to gradle/verification-metadata.dryrun.xml. With the checksum of Commons CSV still wrong in the real file, the difference between the two was a new also-trust element:

That is the second use of dry runs: Gradle’s bootstrapping accepts whatever it sees, including a changed checksum, by adding the new value as an alternative. A reviewer would stop here and ask why the artifact changed. The manual also suggests dry-run as a way to clean up the file: move the old file away, run with --dry-run and compare, remembering that both modes are incremental and copy existing keys.

Source: Gradle User Manual: Dry-run mode

Source: Gradle User Manual: Updating verification metadata automatically

Source: Gradle User Manual: Verification metadata hygiene

You can write entries yourself, and for checksums taken from the project’s website you should. The attributes origin and reason are free text that Gradle preserves but never evaluates; since 9.7 they also exist on pgp entries and trusted-key elements, and the files Gradle 9.7 and later writes use the schema dependency-verification-1.4.xsd (older files are read unchanged). The constructs not used in the generated files above:

trusted-artifacts means no verification at all for the matching artifacts: use it for artifacts produced inside your organisation, for sources and javadoc jars that an IDE downloads (otherwise importing a project fails), and nothing else. The fragment above ran: with the org.junit:junit-bom trust element in place the build passed with no component entry for the BOM, and with that line removed it failed with One artifact failed verification: junit-bom-5.13.1.pom. For one artifact, the two individual forms:

(Two excerpts shown together; the values come from the Gradle manual’s examples, they are illustrative and were not used in a build.) Several checksums for one artifact are all checked, so a second weaker one adds a little assurance when a site publishes only MD5 or SHA-1. also-trust accepts a second legitimate checksum, which happens when the same artifact is published to two repositories by two builds. An ignored-key can be given at artifact level too, when an artifact’s signature is known to be wrong but its checksum has been checked by hand (a checksum must be given too, otherwise all of the artifact’s keys are ignored and Gradle still fails).

Source: Gradle User Manual: Adding trusted artifacts

Source: Gradle User Manual: Skipping javadocs and sources

Source: Gradle User Manual: Disabling metadata verification

The configuration cache has supported dependency verification since Gradle 8.1: changes to the verification file and to the keyring files invalidate the cache entry. In the 9.8.1 runs here, the verification-enabled builds ran with --configuration-cache without problems. When a verification error occurs while Gradle is writing a configuration cache entry (because the classpath of a task is serialized), it comes wrapped in a "configuration cache state could not be cached" failure whose cause is the verification message; the same applies to lock errors. Look for the Dependency verification failed line in the stack of causes, or rerun with --no-configuration-cache.

The dependency cache lives in $GRADLE_USER_HOME/caches (by default ~/.gradle/caches). Run with an empty Gradle user home to see it:

The directory modules-2 is the module cache; 9.8.1 and jars-9 belong to the running Gradle version (generated build logic, compiled build scripts). Inside the module cache, files-2.1 is the file store: downloaded artifacts and raw metadata files, kept under the SHA-1 of their content. The listing for one cached module:

(demo-lib is the small library used in the demonstrations below.) The directory names are the SHA-1 of the files, which was checked here with shasum -a 1 for the jar and the POM. Storing by checksum means two repositories that serve different files for the same coordinates (a re-published release, or a SNAPSHOT) never overwrite each other, and the same bytes are stored once. metadata-2.107 is a set of binary files (module-metadata.bin, module-versions.bin, module-artifact.bin, resource-at-url.bin and the descriptors directory) that record the results of resolution: which concrete version a dynamic version resolved to, the parsed metadata of each module, the pointer from each artifact to its file, and the absence of a module or artifact in a repository, so that a missing resource is not asked for again and again. Each entry records the repository it came from and a timestamp, which is what the expiry rules below use.

Two consequences matter in practice. First, the metadata is stored per repository (identified by URL, type and layout), and an artifact that was resolved from one repository stays tied to it: Gradle will not silently resolve it from another, and a build that works on one machine can fail on another where the repository differs. Second, the format version in the name, metadata-2.107, changes with the Gradle version: that value is used by Gradle 8.11 and later (checked here on 9.8.1), metadata-2.106 by 8.2 to 8.10.2, metadata-2.105 by 8.1 and metadata-2.100 by 8.0 (Gradle 7.x and older used other numbers). The table matters when you seed a cache for another Gradle version, see the CI section.

Gradle also tries to reuse artifacts from the local Maven repository (~/.m2/repository), but only if the file matches the checksum published by the remote repository; mavenLocal() as a declared repository is a different thing and is discouraged, see Repositories & Content Filtering. The cache is also safe for concurrent builds: access to the binary store is guarded by file locks (modules-2.lock), released during slow operations such as downloads. That works across Gradle processes that can see each other’s locks; it does not work for containers that share the directory through different mounts.

Unused entries are cleaned up: Gradle records which files were accessed, scans the cache at most once every 24 hours and removes what has not been used for more than 30 days. The retention can be configured with an init script in the Gradle user home (see Directories & Logging and Init Scripts & the Tooling API):

Both scripts were accepted by Gradle 9.8.1 (./gradlew help --task build ran; the cleanup itself takes 24 hours of cache age and was not observed). In Groovy, the closure of beforeSettings receives the settings object, so the configuration goes through settings.caches; written like the Kotlin version, it failed with Could not find method caches() on the build.

Source: Gradle User Manual: The dependency cache

Source: Gradle User Manual: Checksum based storage

Source: Gradle User Manual: Cache cleanup

To watch caching behaviour you need a repository you control. The examples use a tiny library, io.tidepool:demo-lib, published with the maven-publish plugin to a directory, and served from localhost:

./gradlew publish -PlibVersion=1.0.0 writes io/tidepool/demo-lib/1.0.0/ (jar, POM, Gradle Module Metadata and checksums) and a maven-metadata.xml listing under repo/; publishing is the subject of Publishing. The directory was served with python3 -m http.server 8099 --bind 127.0.0.1 --directory repo, whose log lines are quoted below as plain request paths. The consumer declares the repository over HTTP (hence the explicit opt-in, since plain HTTP is refused by default) and has a task that prints the jar it resolved. Both DSLs were run:

The task reads the resolved artifacts through providers, which keeps it compatible with the configuration cache; the same task in the first Kotlin version captured a top-level val and the configuration cache refused it (cannot serialize Gradle script object references), which is why the val lives inside the task registration. In the Groovy build the configuration must be looked up with configurations.named('runtimeClasspath') to get a provider to flatMap: configurations.runtimeClasspath is the configuration itself there, and calling flatMap on it failed with No signature of method …​ flatMap() is applicable. The first run, with a Gradle user home that had never seen the library:

and the repository saw four requests:

First the version listing (to resolve 1.+), then the POM, the Gradle Module Metadata and the jar of the selected version. The 9s includes unpacking the wrapper distribution of the new Gradle user home.

These files are this page’s own setup for the examples, not an example taken from the manual.

Source: Gradle User Manual: The Maven Publish Plugin, repositories

A new version, 1.1.0, was published to the repository. The same build, twice, with and without the configuration cache:

Both still resolved 1.0.0 although 1.1.0 existed. The first is the configuration cache doing its job (the resolution is part of the cached task graph); the second shows the dependency cache: Gradle caches the resolution of a dynamic version, and the resolution of a changing module (a SNAPSHOT, or a dependency declared with isChanging = true), for 24 hours by default, and does not contact the repository during that time (the log of the server for the second run was empty). The knobs are on the resolution strategy of a configuration, and take a time and a unit:

cacheDynamicVersionsFor controls how long the answer to "what is the newest 1.x?" is trusted; cacheChangingModulesFor controls how long the metadata and artifacts of a changing module are. A short window means more requests to the repository on every build, which costs time; a value of 0 means "ask every time". With both set to zero seconds in the consumer (the block above with 0, "seconds"), and 1.2.0 published, the next run resolved the new version at once (the build file had changed, so the configuration cache entry was recalculated), with the requests

and resolved: [demo-lib-1.2.0.jar]. A SNAPSHOT or a locked build never needs this: a lock removes the question, and a release needs no refresh. Treat a short TTL as a development setting for the modules that change, not as a global default.

Source: Gradle User Manual: Controlling dynamic version caching programmatically

Source: Gradle User Manual: Changing dependencies

When the cache and the repositories disagree (a repository was misconfigured, a "release" was republished, a new dynamic version is wanted now), --refresh-dependencies (-U) tells Gradle to ignore all cached entries for modules and artifacts for this one build. Starting again from 1.0.0 cached with 1.1.0 published, the 24-hour window above holds, and:

Two things in that output are worth noting. The option makes the configuration cache entry unusable (the message says so), because the resolution has to run again. And the requests are for the new version only: the already cached 1.0.0 files were not asked for again. The manual is explicit that --refresh-dependencies is widely misunderstood as "download everything again". Gradle recalculates dynamic versions, invalidates listing caches, refreshes metadata and downloads artifacts, but it checks cached ones with HEAD requests and compares published checksums, and downloads again only what differs. So refreshing is cheap when nothing changed, and it has an effect only for dynamic or changing dependencies, or a repository that now serves different content. If a SNAPSHOT or a dynamic dependency is not moving, the lasting fix is the TTL, not a habit of typing -U.

Source: Gradle User Manual: Force-refreshing dependencies

Source: Gradle User Manual: Controlling dependency caching from the command line

--offline tells Gradle to use the cache for everything, regardless of expiry, and never touch the network. With 1.3.0 published (and the TTLs at zero, which would normally have forced a request) the build ran with the server still up:

and the server log stayed empty: it used the cached answer (1.2.0) instead of asking for 1.3.0. After stopping the server, a normal build fails with the connection error of every network failure (the part of the message that matters):

(The "SSL misconfiguration" hint is generic; this repository is plain HTTP.) The same build with --offline printed resolved: [demo-lib-1.2.0.jar] and BUILD SUCCESSFUL. And a module that was never cached cannot be found offline: with an extra dependency io.tidepool:never-cached:2.1.0,

Offline mode is the cheapest way to prove that a build’s dependencies are all in the cache, which is what a container with a pre-filled cache needs. The same switch exists as a property (org.gradle.offline, see Build Environment & Properties) and as a command-line option in Command-Line Interface. Offline mode with the dependency verification of this page works as long as the metadata and keyring are complete: verification needs no network when the keys are in the keyring.

Source: Gradle User Manual: Using offline mode

CI builds in ephemeral containers start with an empty Gradle user home, so each one downloads everything. The manual describes two remedies. They work because the module cache is stored with relative paths.

Copying a cache. Copy $GRADLE_USER_HOME/caches/modules-2 (not the *.lock and gc.properties files) into the same place of another Gradle user home. The Gradle versions that created and consume the cache must have the same format numbers, otherwise Gradle still contacts the repositories for what it lacks; the formats are:

A shared read-only cache. Instead of copying, mount one cache read-only into all containers and point the environment variable GRADLE_RO_DEP_CACHE at the directory that contains modules-2. Gradle then looks in both the writable cache in its own user home and the shared one without locking (so many builds may read it at the same time), takes what the shared cache has, and downloads and writes only what is missing. The seeding build should produce the shared cache in a job of its own, copy it away (never use a live Gradle user home, which may be locked or modified) and publish it as a volume. The feature is marked incubating in the manual. Demonstration: a copy of the cache that contained demo-lib 1.1.0 (without lock and gc.properties files, made read-only with chmod -R a-w) as /work/ro/modules-2, a consumer with a fixed version 1.1.0, a brand-new Gradle user home, and the server stopped:

The writable cache of that new home contained metadata-2.107 and modules-2.lock but no files-2.1 at all: the jar, POM and module file were served from the shared cache. The control, an equally fresh Gradle user home without the variable, failed on the first file it needed:

The consumer in this demonstration used a fixed version, because a dynamic one would still ask the (stopped) repository for the version listing. Combining the shared cache with dependency verification was not run here. In principle a seeded cache plus --offline, a committed lock file and the verification file give a CI build that is repeatable and does not need the internet.

Source: Gradle User Manual: Dealing with ephemeral builds

Source: Gradle User Manual: Sharing the dependency cache with other Gradle instances

Source: Gradle User Manual: Copying and reusing the cache