Table of Contents
Use of dynamic dependency versions (e.g. 1.+
or [1.0,2.0)
) makes builds non-deterministic.
This causes builds to break without any obvious change, and worse, can be caused by a transitive dependency that the build author has no control over.
To achieve reproducible builds, it is necessary to lock versions of dependencies and transitive dependencies such that a build with the same inputs will always resolve the same module versions. This is called dependency locking.
It enables, amongst others, the following scenarios:
Companies dealing with multi repositories no longer need to rely on
-SNAPSHOT
or changing dependencies, which sometimes result in cascading failures when a dependency introduces a bug or incompatibility. Now dependencies can be declared against major or minor version range, enabling to test with the latest versions on CI while leveraging locking for stable developer builds.Teams that want to always use the latest of their dependencies can use dynamic versions, locking their dependencies only for releases. The release tag will contain the lock states, allowing that build to be fully reproducible when bug fixes need to be developed.
Locking is enabled per dependency configuration. Once enabled, you must create an initial lock state. It will cause Gradle to verify that resolution results do not change, resulting in the same selected dependencies even if newer versions are produced. Modifications to your build that would impact the resolved set of dependencies will cause it to fail. This makes sure that changes, either in published dependencies or build definitions, do not alter resolution without adapting the lock state.
Dependency locking makes sense only with dynamic versions.
It will have no impact on changing versions (like -SNAPSHOT
) whose coordinates remain the same, though the content may change.
Gradle will even emit a warning when persisting lock state and changing dependencies are present in the resolution result.
Locking of a configuration happens through the ResolutionStrategy
:
Example: Locking a specific configuration
build.gradle
configurations { compileClasspath { resolutionStrategy.activateDependencyLocking() } }
Or the following, as a way to lock all configurations:
Only configurations that can be resolved will have lock state attached to them. Applying locking on non resolvable-configurations is simply a no-op.
In order to generate or update lock state, you specify the --write-locks
command line argument in addition to the normal tasks that would trigger configurations to be resolved.
This will cause the creation of lock state for each resolved configuration in that build execution.
Note that if lock state existed previously, it is overwritten.
When locking multiple configurations, you may want to lock them all at once, during a single build execution.
For this, you have two options:
Run
gradle dependencies --write-locks
. This will effectively lock all resolvable configurations that have locking enabled. Note that in a multi project setup,dependencies
only is executed on one project, the root one in this case.Declare a custom task that will resolve all configurations
Example: Resolving all configurations
build.gradle
task resolveAndLockAll { doFirst { assert gradle.startParameter.writeDependencyLocks } doLast { configurations.findAll { // Add any custom filtering on the configurations to be resolved it.canBeResolved }.each { it.resolve() } } }
That second option, with proper choosing of configurations, can be the only option in the native world, where not all configurations can be resolved on a single platform.
Lock state will be preserved in a file located in the folder gradle/dependency-locks
inside the project or subproject directory.
Each file is named by the configuration it locks and has the lockfile
extension.
The content of the file is a module notation per line, with a header giving some context. Module notations are ordered alphabetically, to ease diffs.
Example: Lockfile content
gradle/dependency-locks/compileClasspath.lockfile
# This is a Gradle generated file for dependency locking. # Manual edits can break the build and are not advised. # This file is expected to be part of source control. org.springframework:spring-beans:5.0.5.RELEASE org.springframework:spring-core:5.0.5.RELEASE org.springframework:spring-jcl:5.0.5.RELEASE
which matches the following dependency declaration:
Example: Dynamic dependency declaration
build.gradle
dependencies {
implementation 'org.springframework:spring-beans:[5.0,6.0)'
}
The moment a build needs to resolve a configuration that has locking enabled and it finds a matching lock state, it will use it to verify that the given configuration still resolves the same versions.
A successful build indicates that the same dependencies are used as stored in the lock state, regardless if new versions matching the dynamic selector have been produced.
The complete validation is as follows:
Existing entries in the lock state must be matched in the build
A version mismatch or missing resolved module causes a build failure
Resolution result must not contain extra dependencies compared to the lock state
In order to update only specific modules of a configuration, you can use the --update-locks
command line flag.
It takes a comma (,
) separated list of module notations.
In this mode, the existing lock state is still used as input to resolution, filtering out the modules targeted by the update.
❯ gradle classes --update-locks org.apache.commons:commons-lang3,org.slf4j:slf4j-api
Wildcards, indicated with *
, can be used in the group or module name. They can be the only character or appear at the end of the group or module respectively.
The following wildcard notation examples are valid:
org.apache.commons:*
: will let all modules belonging to grouporg.apache.commons
update*:guava
: will let all modules namedguava
, whatever their group, updateorg.springframework.spring*:spring*
: will let all modules having their group starting withorg.springframework.spring
and name starting withspring
update
The resolution may cause other module versions to update, as dictated by the Gradle resolution rules.
Make sure that the configuration for which you no longer want locking is not configured with locking.
Remove the file matching the configurations where you no longer want locking.
If you only perform the second step above, then locking will effectively no longer be applied. However, if that configuration happens to be resolved in the future at a time where lock state is persisted, it will once again be locked.
It is currently not possible to lock the
classpath
configuration used for script plugins.Locking can not yet be applied to source dependencies.
This feature is inspired by the Nebula Gradle dependency lock plugin.
If you were using that plugin and want to migrate, see the Nebula documentation.