Manage dependency caches
Check that builds reuse pub, Gradle, CocoaPods and Xcode caches, change where they live and how large they grow, and purge them.
Every build starts from a fresh clone, but the runner keeps package manager caches between builds. A second build with the same lockfiles skips the dependency downloads. Use this guide to confirm that caching works, to give the caches more room or another disk, and to clear them when a cache goes bad.
The cache directories, variables, and limits are listed in Runner settings.
What you need
- A runner that has finished at least one successful build.
- Owner or Admin access to purge caches. Developers can view Settings > Runners.
- Administrator access on the Runner Mac to change the runner’s environment.
Check that builds hit the cache
- Run the same pipeline twice without changing
pubspec.lock,Podfile.lock, or the Gradle wrapper and settings files. - Open the second build’s log and find the cache lines after checkout.
Each cache shows hit or miss with the hash of its lockfiles. A miss on the first build is expected. The runner records the hash only when a build succeeds, so a failed first build leaves the next one on a miss too.
Change the size limit or location
The runner keeps its caches under 50 GiB by default and deletes the least recently used entries above that. It reads two variables from its own process environment:
OORE_RUNNER_CACHE_MAX_GBchanges the limit, for example to120.OORE_RUNNER_CACHE_DIRmoves the caches, for example to a larger volume.
Set them with oore runner config,
which works for the runner service that the Complete or Runner profile
manages, then restart the runner:
oore runner config set OORE_RUNNER_CACHE_MAX_GB 120
oore runner config set OORE_RUNNER_CACHE_DIR /Volumes/Builds/oore-caches
sudo launchctl kickstart -k system/build.oore.oore-runnerA runner you start yourself can also take them as environment variables, which win over the settings file:
OORE_RUNNER_CACHE_MAX_GB=120 oore runner startTo free space without changing the limit, purge the caches.
A pipeline variable with the same name as a cache variable, such as
PUB_CACHE, overrides the runner’s directory for that pipeline only.
Keep Gradle proxy settings
Builds use the runner’s own Gradle home. Before each build, the runner copies
~/.gradle/gradle.properties into it. Edit proxy settings such as
systemProp.https.proxyHost, and JVM settings, in ~/.gradle/gradle.properties
on the Runner Mac, not in the copy.
Purge the caches
Purge the caches when a build fails on a corrupt download or a stale DerivedData folder.
- Open Settings > Runners.
- Open the runner’s actions menu and select Purge cache.
- Confirm Purge cache.
The runner shows Purge pending until its next build. It deletes its pub, Gradle, and CocoaPods caches and its Xcode DerivedData folders before that build starts.
Verify the result
- Settings > Runners shows the runner’s cache size in the Cache column after each build.
- After a purge, the next build of each app shows miss for every cache and downloads its dependencies again. The build after that shows hit.
Troubleshooting
Every build shows a miss
The lockfiles change on every build, or the builds fail. Commit
pubspec.lock and Podfile.lock, and check that a build succeeds once. The
runner records a hash only after a successful build.
The cache size keeps growing
The runner trims the caches only above the limit. Lower
OORE_RUNNER_CACHE_MAX_GB, or purge the caches. VM builds also keep Xcode
DerivedData and Android SDK packages in the cache directory. Each app that
builds in a VM also keeps a warm image. It holds the same caches on the VM disk
and starts again from the plain image every
OORE_TART_WARM_IMAGE_MAX_AGE_DAYS.
Disk space is low on the runner
Settings > Runners shows Runner disk space is low when a runner has
less than 20 GiB free. Purge the caches, delete old Tart images if the runner
builds in VMs, or move the caches with OORE_RUNNER_CACHE_DIR.
Next step
Route builds with runner labels so each pipeline lands on a runner with the right tools and disk space.