Skip to content
compiler.dev
Start free

What Is a Remote Build Cache?

Last updated

A remote build cache is a shared store of build and test outputs, keyed by a hash of each task's inputs. When any machine, in CI or on a developer laptop, needs the same task with the same inputs, it downloads the saved result instead of running the task again.

How it works

Build tools such as Nx, Turborepo, Gradle and Bazel split work into tasks (compile, lint, test, bundle). For each task the tool computes a hash from the source files, dependencies, environment variables and command. Before running, it asks the cache for that hash. A hit restores the output files and replays the logs. A miss runs the task and uploads the result.

This is finer-grained than a dependency cache. An actions/cache entry restores one folder for the whole job. A remote cache skips individual tasks, so a change to one package in a monorepo rebuilds that package and its dependents only.

Because the hash covers all inputs, correctness depends on declaring them well. A task that reads an undeclared file can return stale output.

Example

Turborepo with a remote cache, using environment variables for credentials:

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx turbo run build test lint

Nx works the same way with its own cache settings. See the monorepo CI guide for Nx and Turborepo. compiler.dev supports Nx and Turborepo remote caches alongside machine-local dependency, git and Docker layer caches; details on pricing.

Remote versus local cache

  • Local cache lives on one machine's disk. Free, but each fresh CI runner starts empty.
  • Remote cache is shared across runners and people, which is what makes it useful for ephemeral CI.

Common mistakes

  • Undeclared inputs. Environment variables or files that affect output but are not in the hash cause wrong cache hits.
  • Non-deterministic outputs. Timestamps or random IDs in build output make every run look different.
  • Caching tests that touch the network. A cached pass hides a failing dependency.
  • Writing from pull requests of forks. Cache poisoning is a real risk. Give read-only access to untrusted code.
  • Treating it as a replacement for dependency caching. You still need to install dependencies quickly. See GitHub Actions caching.

Related terms

FAQ

Is a remote build cache secure?

Treat it like a deploy target. Limit write access to trusted branches and keep tokens in secrets.

Does it work with Docker builds?

Docker has its own layer cache. See Docker layer caching in CI.

How much does it save?

It depends on how often tasks are unchanged between runs. Monorepos with small changes see the most benefit.

Related