How does remote build caching in tools like Bazel or Nx decide whether it can reuse a previous task's result instead of re-executing it, and what property does the task need to have for that reuse to be safe?

## Content addressing: how the key is built Remote caching turns a task execution — compiling a library, running a test suite, linting a package — into a lookup problem instead of a compute problem, and the mechanism that makes that safe is **content addressing**. Before running any task, the orchestrator computes a cryptographic hash (Bazel and most modern tools use something like SHA-256) over a well-defined set of inputs: - the contents of every source file the task reads; - the hashes of every upstream dependency's outputs (so a change three layers down the graph still changes the hash at the top); - the exact command line and flags being invoked; - often the toolchain/compiler version. That hash becomes the **cache key**. ## The lookup, hit and miss The orchestrator then asks a cache store — which might be a folder on local disk for a single developer, or a shared remote service reachable by every CI runner and every teammate's laptop, such as Bazel's Remote Cache protocol, Nx Cloud, or Turborepo's remote cache — "has anyone already produced output for this exact key?" 1. **If yes**, it downloads the stored artifacts (compiled binaries, test reports, coverage data) and the exit code, and reports the task as complete without ever invoking the compiler or test runner. 2. **If no**, it runs the task for real and, on success, uploads the result under that key so the next person (or the next CI job, seconds later) gets a hit. ## Why it exists The reason this exists is straightforward **economics at scale**: the same unchanged code gets rebuilt and retested over and over — - once per CI run per branch, - once per developer's local iteration, - once per merge — and in a large team, the overwhelming majority of those executions are against inputs someone else has already built moments earlier. Sharing the cache turns thousands of redundant builds across a whole engineering org into effectively one real build per unique input state, with everyone else getting near-instant downloads. This is the single biggest lever these tools pull for CI cost and wall-clock time in large monorepos. ## The trade-off: the promise the task has to keep The trade-off is that the entire safety of this system rests on a promise the underlying task itself has to keep: **hermeticity and determinism**. - **Hermetic** means the task's output depends only on its declared inputs — no reading files outside the sandbox, no hitting the network, no depending on machine-specific absolute paths. - **Deterministic** means running it twice with identical inputs produces identical (or at least behaviorally equivalent) outputs — no embedding the current timestamp or a random UUID into a build artifact, no relying on filesystem iteration order that varies by OS. | Tool | How much of that promise it polices for you | |---|---| | **Bazel** | takes this extremely seriously: by default it executes each action inside a sandbox that only exposes declared inputs, actively working to catch violations at build time rather than trusting the build script's discipline | | **Lighter tools like Nx and Turborepo** | generally trust the task author to keep it hermetic and offer configuration to declare inputs/outputs explicitly, but don't sandbox execution the same way — faster to adopt, weaker guarantees | ## Failure modes Failure modes show up as a specific, confusing class of bug: "it works on my machine but CI is broken" inverted into "CI says it passed but the code is actually broken." - A test that reads an environment variable **never declared as a cache input** can pass once under one env configuration, get cached, and then silently "pass" forever afterward even when the underlying logic breaks, because the cache key never changes. - A code generator that **embeds a build timestamp** produces a different byte-for-byte output every run, which either destroys the cache hit rate (every run looks "new") or, worse, if the timestamp isn't part of what's checked for correctness, masks a genuine non-determinism bug. - Teams also hit **"cache key too broad"** problems, where a task declares more inputs than it actually needs (e.g., depending on an entire shared `utils` package when it only calls one function from it), so any unrelated change anywhere in that shared package invalidates the cache for everything downstream — correct, but needlessly conservative, and a sign the dependency graph itself needs finer-grained splitting. ## Where it shows up A concrete, widely cited real-world example: Google's internal build system (Bazel's ancestor, Blaze) was built specifically to make remote caching and remote execution trustworthy at the scale of a single-repo codebase with tens of thousands of engineers, precisely because hermetic, content-addressed caching was the only way to keep build times tractable; Bazel is the open-sourced descendant of that same design. On the JS side, Turborepo's marketing point of "never build the same code twice" is this exact mechanism, and its adoption by companies like Vercel is largely justified by the CI-minutes savings it produces once a monorepo passes a few dozen packages.