Working with Job Cache

Job caches preserve reusable files between builds, such as downloaded dependencies. A cache can be missing, so the job must always be able to populate its files from scratch.

Set Up a Cache

Add a Set Up Cache step after checkout and before the commands that use the cached files. Configure:

• Cache Key: a stable name identifying the cache, such as tutorial-cache.
• Checksum Files: files representing the cache's inputs, such as a dependency lock file. OneDev computes their checksum automatically. Leave this empty to use an empty checksum.
• Cache Entries: directories or files to cache. Each entry has a Path and optional Excludes patterns.
• Upload Strategy: Upload if not exact match uploads after a successful build when no cache matched both the key and checksum. Upload if changed uploads when cached files change.

OneDev searches the current project and its ancestors for caches. An exact match has the same key and checksum. A partial match has the same key but a different checksum, allowing old dependency data to be reused while the job updates it. You do not need the separate checksum-generation step or load keys shown in older versions of this tutorial.

Relative cache paths are resolved under the job working directory. Container executors also accept absolute paths inside the container. Shell executors only accept relative paths, avoiding concurrent jobs sharing an absolute host path.

Leave Upload to Project empty to upload to the current project. Uploading to the current or a child project does not require an upload token when the build commit is reachable from the default branch. Other cases require a job secret containing an access token with the necessary cache upload permission.

Try a Complete Example

1. Commit a file named cache-version.txt containing version-one.

2. Add a job with these steps in order: Checkout Code, Set Up Cache, and Execute Commands.

3. Configure the cache step as shown above: key tutorial-cache, checksum file cache-version.txt, cache entry path cached-data, and upload strategy Upload if not exact match.

4. In Execute Commands, use the container image alpine:3.20, the default POSIX shell, and these commands:

   if [ -f cached-data/value ]; then
     echo "Restored cache: $(cat cached-data/value)"
   else
     echo 'Cache miss: populating data'
   fi
   mkdir -p cached-data
   cp cache-version.txt cached-data/value

5. Commit the build specification to the default branch and run the job. The log should show Cache miss: populating data and then an uploaded cache.

6. Make another commit without changing cache-version.txt and run the job. The log should report an exact match and Restored cache: version-one. No upload is needed.

7. Change cache-version.txt to version-two, commit, and run again. The log should report a partial match, restore version-one, then upload the updated data under the new checksum.

For a dependency cache, use the same sequence with your lock file as Checksum Files and the dependency directory as a cache entry. Always run the dependency installation/update command after restoring the cache so a partial match is brought up to date.

Cache Maintenance

Open the project's Settings > Cache Management page. The table shows each cache's key, checksum, number of paths, and last access date. Click the path count to inspect its paths. The row's delete action removes that cache.

Set Preserve Days and click Update to control how long an unaccessed cache is retained. Jobs must tolerate cache removal and regenerate the data when needed.