TeamCity On-Premises 2023.05 Help

Build Cache

The "Build Cache" feature allows build configurations to keep specific files produced during a build run (for example, downloaded npm packages) and reuse them during subsequent builds. This technique optimizes and accelerates building routines.

Prerequisites

Build Cache is currently available as an experimental feature and may be changed in future releases.

To enable this build feature, navigate to the Administration | Experimental Features page and tick the corresponding checkbox.

Common Concepts

Build Cache feature can work in one- or two-way mode. In two-way mode it downloads caches published by the same feature during a previous build. When you add a new Build Cache feature, it is configured to operate in this mode.

In one-way mode one build configuration with the "Build Cache" feature publishes cache, and another build configuration downloads it. This mode allows you to set up "publisher" and "consumer" features to exchange caches between different build configurations of the same project.

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.

  1. Add the build feature to a build configuration and specify a unique Cache Name.

  2. Since we want the feature to both publish and use cache, leave both Publish and Use Cache settings enabled.

  3. Specify paths to files and folders that should be cached (currently, only paths relative to the checkout directory are supported). Each path should start from a new line. Wildcards are not supported.

    The figure below illustrates the Build Cache feature configured to publish NodeJS packages downloaded by the npm install or yarn install build step.

    Publishing NodeJS packages
  4. Save the settings and ensure that the build feature description confirms that your feature both publishes and uses its cache.

    Build Cache feature description
  5. Run the build. If you correctly set up the feature, you should be able to see required files published as a ".teamcity.build_cache" hidden artifact when the build finishes.

    Publish build cache
  6. To confirm that cache published during the previous run is used, run the build again and check the build log.

    Download build cache

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 to this configuration's checkout directory.

Reuse caches published by other configurations

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

  1. Add the build feature to a build configuration and specify a unique Cache Name.

  2. Specify paths to files and folders that should be cached (currently, only paths relative to the checkout directory are supported). Each path should start from a new line. Wildcards are not supported.

  3. Uncheck the Use Cache checkbox and save feature settings.

Set Up a Consumer

  1. Add the build feature to a build configuration and specify the same Cache Name the publisher feature uses.

  2. Uncheck the Publish checkbox and save feature settings.

  3. Repeat the steps above for every build configuration that needs this published cache.

Additional Information

Build Sequence

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

  1. Resolve artifact dependencies

  2. Download caches

  3. Checkout the sources

  4. Start the build

Transferring Caches

Caches are automatically compressed into archives when published, and unpacked into the configuration's checkout directory when downloaded. You do not need to manually specify expressions (as you do with regular artifacts).

Tell Us What You Think

The Build Cache feature is still under development, and we'd love to hear your early thoughts and suggestions. See this document for the information on how to send feedback to the TeamCity team: Feedback.

See Also

Last modified: 14 March 2023