Dependency Caches

Maven Cache, Gradle Cache, and NuGet Cache are configuration-free build features that speed up builds by allowing related steps to reuse dependencies downloaded during previous builds of the same build configuration. In addition, caches are shared between steps of the same build, given that these steps utilize the same dependency directory.

Maven Cache — caches dependencies used by Maven build steps
Gradle Cache — caches dependencies used by Gradle build steps
NuGet Cache — caches NuGet packages used by .NET build steps

Common Principles

All "... Cache" build features operate in a similar manner. Caches undergo identical creation/publishing/validation/reuse phases regardless of the build feature type.

Caching

The initial cache is formed during the first build run. To do this, a build feature caches the contents of the following tracked directories:

Maven: local Maven repositories. The default path depends on step local artifact repository settings.
NuGet: global package folder. The default path is ${user.home}/.nuget/packages.
Gradle: Gradle cache directory. The default path is ${user.home}/.gradle/caches/modules-<version>.

Publishing

After a cache was created, the build feature publishes it to the artifact storage, making it easily accessible to agents that process subsequent builds.

Validation

A cache is routinely checked to determine if it is still valid or needs replacement. A build feature can mark a cache as invalid at the start or end of a build (before or after executing build steps) in the following cases:

At the start:
- If the periodic cleanup is scheduled. Caches are forcibly pruned and republished every 30 days starting from their first publish date. This mechanism ensures caches stay up-to-date.
- If the teamcity.depcache.invalidate parameter equals true
At the end:
- If the list of build steps using this cache has changed
- If the project dependency list has changed

When a build feature encounters an invalid cache, it flushes this cache and republishes a newer version after the build ends.

Usage

A build feature unzips cached files from a validated cache to tracked repositories, merging existing file structure with the cached one. If a cache was marked as invalid before the actual build steps started, this build runs without using a cache and re-downloads all required dependencies anew. These fresh dependencies will be used for an updated cache published at the end of this build.

Special Notes and Limitations

Common

Dependency and Package caching is most effective on short-lived agents that terminate after a single build, as they avoid accumulating dependencies from other builds. For long-lived or permanent agents, periodically review .teamcity.build_cache/depcache_***_cacheRoot_***.tar hidden artifacts to monitor cache size and contents. Each dependency directory is archived in its own cache, so your builds can publish multiple archives. If caches grow excessively due to redundant dependencies, consider disabling this feature.
The cache is only published if the build was successful. See this ticket for more information: TW-89838.
To enable dependency caching for builds running in container, set the -v <dependency_directory>:<dependency_directory> volume.
Certain build configuration setups rely on spawning "virtual" builds. For example, when using Parallel Tests or Matrix Build, each test batch or parameter combination runs in a separate build. Each of these dynamically generated builds publish an identical cache. See the following ticket for more information: TW-89837.

Maven Cache

The build feature supports all three local Maven repo types: per-agent, per-build, and Maven default.
If builds that produce and consume caches run inside Linux Docker containers, set the Artifact repository Maven setting to either "Per agent" (default value) or "Per build configuration". Otherwise, a TeamCity server running as a regular user may lack sufficient permissions to access caches published by steps executed in Docker containers under the "root" user.

NuGet Cache

The build feature calls the dotnet list package --format=json --output-version=1 --include-transitive command to analyze project dependencies and detect invalid caches. The --format parameter is available in .NET SDK 7.0.200 and higher, meaning the build feature cannot operate on agents with older SDK versions.
The caching is not supported for environments with package locations set via MSBuild-specific ways:
- via MSBuild command line
- in a project file
- in a Directory.Build.Props file

DSL Configuration

The sample below illustrates how to add dependency cache features in Kotlin DSL.

object Build : BuildType({
    name = "Build"
    
    features {
        // ...
        gradleCache {}
        mavenCache {}
        nugetCache {}
    }
    // ...
})

Last modified: 19 November 2024