There is a category of tooling proposal I have learned to decline on sight: the one whose first slide is an architecture diagram with a service in the middle of it.
A build cache service. A remote execution farm. A resolution proxy. These solve real problems, and every one of them adds a component that can be slow, that can be down, and that introduces a new place for versions to drift.
The question worth asking is not 'can I build this service'. It is 'what is the smallest set of facts that makes the build reproducible, and where do those facts have to live?'
The facts
For a build to be reproducible, you need to know exactly:
- Which runtime version executes it.
- Which dependency resolution it uses.
- Which artefacts — images, binaries, action SHAs — it consumes.
- Whether all of the above are identical on the laptop and on the runner.
That is the entire requirement. Four facts. One of them — dependency resolution — is already in a lockfile in most ecosystems. The other three need a small, committed document that says: this runtime, this resolution, these digests.
The lockfile is the whole product
Once you have a lockfile, the interesting design question becomes: what reads it?
The answer is a resolver — a program that takes the lock and produces a concrete local environment. The resolver has to run in two places, and it has to behave identically in both. That is the entire constraint.
If the resolver is a local script, then:
- The laptop and the runner invoke the same implementation, so they cannot disagree about anything except hardware.
- There is no service to be slow or unavailable.
- The lockfile is a plain, reviewable, diffable text file.
- Adding a teammate is a
git cloneand a cache warm, not an onboarding request.
The remote-execution approach optimises for a different problem — the one where the build is genuinely expensive to run, where a fleet of beefy machines genuinely helps. That is a real case. It is also not the case for the fast checks that run on every commit, and those are the ones setting your feedback latency.
The version I actually shipped
When I built this for real, the answer turned out to be simpler than a resolver. The repository holds the setup in scripts/ci/, and both the Makefile and the GitHub Actions workflow call those same scripts. There is one copy of the setup. It cannot disagree with itself.
developer repository runner
| | |
| make ci | |
|----------------------->| |
| | scripts/ci/*.sh |
| | the setup and the gates |
| | | |
| | +---------------->|
| | the same script|
| | |
| the same script, so the local run and the runner
| cannot disagree about what the code needs |
No resolver. No service. No lockfile format to design. Just: do not write the setup twice.
The hard part is failure, not success
The subtle requirement is what happens when the environment cannot be honoured. The runner is an image you do not control. The base image has been updated. The action tag moved. The cache restored something unexpected.
A build system that fails with a confusing test error has lost. It has converted a five-second diagnosis into a twenty-minute one, and it will do this several times a week. The failure must be classified:
error: toolchain mismatch
lock: runtime go1.23.4, digest sha256:9f2c...
runner: runtime go1.22.9, digest sha256:41ab...
this job cannot reproduce the tested environment.
run `make ci` locally to reproduce, or update the lock deliberately.
That error is the product. Everything else is plumbing. A fast build that fails for the wrong reason is still a distraction; a slow build that fails for the right reason is a roadmap.
The part that surprised me
The version of this I did not expect was the inverse of a speed tool. I had assumed the local gate would be faster than the runner, and measured it at 99 seconds against 43–48 seconds on identical work. It was slower, roughly twice the wall clock.
What the local gate actually bought was a guarantee. The remote runner had been refusing to start jobs for a week — 28 of the last 30 runs failing, none of them on code — and the local gate had answered the same question every time, on a laptop, for free.
So the honest pitch is not 'faster'. It is 'always available, and it says why'. That is a less impressive sentence than the one I had written, and it is the one that survived contact with a measurement.
The cache is not the point
Every proposal in this space eventually adds a cache, because a cold build is slow and a cache makes it faster. But a cache is a second copy of the truth, which means it is a second place for the truth to be wrong.
The cache should be keyed by the content of the lockfile, not by the commit SHA. If the lock changes, the key changes, and a stale entry is unreachable by construction rather than by a policy that someone has to remember. Content addressing is not an optimisation here; it is how you make staleness structurally impossible.
What this looks like in practice
The end state is boring in the best way:
$ make ci
running the gates
✓ lint
✓ type check
✓ tests (412 passed)
✓ secret scan
all gates passed in 99s
Ninety-nine seconds, on a laptop, offline, with a build that the runner will reproduce exactly because both read the same scripts.
There is no service. There is no cluster. There is one copy of the setup and a rule that if the environment does not match, the build stops and says so.
That is most of the value of the expensive architectures, at essentially none of the cost. Which is, I think, the general shape of infrastructure work: the winning move is usually to make the state explicit and small, not to add a component that holds the state for you.