Build Cache

The "Build Cache" feature allows build configurations to publish specific files produced during a build run (for example, downloaded npm packages or Maven local repository artifacts). Published caches can be reused during subsequent builds by the same configuration that published them, or other configurations. This technique optimizes and accelerates building routines.

Common Information

Cache Publishers and Consumers

You can set up a Build Cache feature to operate in either of two modes.

Initial Build Cache settings allow the feature to download caches published by the same feature during a previous build.
Alternatively, you can set one Build Cache feature to publish a cache, and another Build Cache (from a different build configuration) to download it. This mode allows you to set up "publisher" and "consumer" features to exchange caches between different build configurations. The number of cache consumer features is unlimited, however, they should belong to the same project as the cache publisher.

Size Limits

Caches are published as hidden artifacts under the .teamcity.build_cache folder. To view a published cache, click the Show hidden artifacts link on the Artifacts Tab.

Since caches are published as artifacts, they are affected by the Maximum build artifact file size setting that you can set on the Administration | Global Settings page.

Order of Operations

If a build configuration is configured to upload caches, it arranges its build stages in the following order:

Resolve artifact dependencies
Download caches
Checkout the sources
Start the build

Publish and Use Cache Within the Same Build Configuration

This section illustrates how to set up the Build Cache feature that allows a build configuration to reuse caches from its own previous builds.

Add the build feature to a build configuration and specify a unique Cache Name.
Since we want the feature to both publish and use cache, leave both Publish and Use Cache settings enabled.
Specify paths to files and folders that should be cached. Each path should start from a new line. Wildcards are not supported. Relative paths are resolved against checkout directories.
For example, to cache NodeJS packages downloaded by the npm install or yarn install commands, type node_modules/ in this field.
To cache local Maven artifacts, set the Artifact repository setting of your Maven runner to Maven default. If you choose the Per agent mode, use the default .m2 location in the feature's publishing rules. Alternatively, add the -Dmaven.repo.local parameter to additional runner commands and point the Build Cache feature to the same directory.
By default, new builds do not publish caches if they are identical to those published by previous builds. If you wish each build to upload a cache, uncheck the Publish only if changed setting.
Save the settings. The feature's description on the Build Features page should state that it publishes and uses the same cache.
Run the build and ensure all cached files are available on the build results page as the ".teamcity.build_cache" hidden artifact.
To confirm that cache published during the previous run is used, run the build again and check the build log for corresponding messages.

Exchange Caches Between Separate Build Configurations

In this setup, the "publisher" Build Cache feature added to one build configuration publishes its cache, while the "consumer" Build Cache feature added to another configuration downloads this cache. The dowloaded cache is placed to the same location that matches the publisher's Publishing rules path.

You can set up as many publisher and consumer features as required as long as you add features for configurations that belong to the same project.

Set Up a Publisher

Add the build feature to a build configuration and specify a unique Cache Name.
Specify paths to files and folders that should be cached. Each path should start from a new line. Wildcards are not supported. Relative paths are resolved against checkout directories.
For example, to cache NodeJS packages downloaded by the npm install or yarn install commands, type node_modules/ in this field.
To cache local Maven artifacts, set the Artifact repository setting of your Maven runner to Maven default. If you choose the Per agent mode, use the default .m2 location in the feature's publishing rules. Alternatively, add the -Dmaven.repo.local parameter to additional runner commands and point the Build Cache feature to the same directory.
By default, new builds do not publish caches if they are identical to those published by previous builds. If you wish each build to upload a cache, uncheck the Publish only if changed setting.
Uncheck the Use Cache checkbox.
Save the settings. The feature's description on the Build Features page should state that it only publishes the cache.
Run the build and ensure all cached files are available on the build results page as the ".teamcity.build_cache" hidden artifact.

Set Up a Consumer

Add the build feature to a build configuration and specify the same Cache Name the publisher feature uses.
Uncheck the Publish checkbox.
Save the settings. The feature's description on the Build Features page should state that it only uses the cache.
Run a new build and check the build log to ensure the required cache file is downloaded.
Repeat the steps above for every build configuration that needs this published cache.

TeamCity Cloud 2024.12 Help