Oore CI
Operate OoreRunners

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

  1. Run the same pipeline twice without changing pubspec.lock, Podfile.lock, or the Gradle wrapper and settings files.
  2. 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_GB changes the limit, for example to 120.
  • OORE_RUNNER_CACHE_DIR moves 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-runner

A 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 start

To 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.

  1. Open Settings > Runners.
  2. Open the runner’s actions menu and select Purge cache.
  3. 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.