An Earthfile will not parse after an upgrade
Syntax that was valid in an earlier Earthly version and deprecated in a later one, usually around FROM DOCKERFILE or ARG scope.
Earthfile reads on current and next
Running Earthly?
Earthly promises repeatable builds and usually delivers, until a +target that worked on a developer laptop refuses to run on a remote runner because the cache key diverged, or a Dockerfile style COPY pulled a file that no longer exists. We work the Earthfile, the runner topology and the cache strategy so what builds locally also builds in CI on the first try.
What it is
Earthly is a build system that sits between Dockerfiles and Make. Vlad Ionescu and the Earthly team shipped the first release in 2020, with the explicit goal of making container native builds reproducible and portable across CI providers.
An Earthfile looks like a Dockerfile with target labels, dependencies between targets, and support for cache mounts, secrets and parallel execution. Builds run against a local BuildKit backed runner or a shared remote runner for team caching. Earthly earns its place where teams have a mix of languages and want one build file per repo rather than a Makefile plus a Dockerfile plus a CI YAML all drifting apart.
The honest version
No technology is all upside. This is where Earthly earns its place and where it tends to cause trouble.
Sound familiar?
The Earthly problems that bring people to us, and what you have once each one is fixed.
Syntax that was valid in an earlier Earthly version and deprecated in a later one, usually around FROM DOCKERFILE or ARG scope.
Earthfile reads on current and next
A buildkit daemon that is not running, a firewall between the CLI and the runner, or a stale cert on an mTLS enabled runner.
Runner connects, caches shared
A base image or build arg that differs between local and remote runners, invalidating the cache key before any step runs.
Cache hits land the same everywhere
A path that works from one target but not another because Earthfile build context is per target, not global like a Dockerfile.
COPY paths resolve from every target
A WITH DOCKER target running on a runner that does not allow nested containers, or a Docker image size that exceeds the inner daemon's disk.
WITH DOCKER runs reliably
A self hosted runner where BuildKit cache has grown to fill the volume, so new builds start failing with unhelpful disk errors.
Cache sized and pruned on schedule
A release target that expects VERSION from the CLI or CI, and a pipeline that forgot to pass it, so the build fails before touching source.
Build args flow through reliably
Parallelism capped at a conservative default or constrained by runner CPU, so targets wait in a queue rather than running at once.
Parallelism tuned to the runner
What we do
Pass us a failing +target or hand over the whole build system for an audit, either way we get it reproducible.
How it works
Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.
We fix the cause, not the symptom. If something is down, getting it back up comes first.
Backups, monitoring, updates and access, so the same problem can't quietly come back.
You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.
Often found together
We work on the whole stack, so the problem can be wherever it actually is.
The cache key for a target is derived from its inputs, the base image digest and the build args. If a developer laptop pulls a slightly different base image than the remote runner, the keys diverge and nothing shares. The fix is to pin base image digests, standardize the Earthly version across runners, and confirm build args are identical. Once those line up the shared runner starts earning its keep.
Earthly is friendlier to pick up, closer to Dockerfile syntax and better suited to a team that wants one build file per repo. Bazel is more rigorous, has better remote execution semantics and fits very large monorepos where hermetic builds matter above all else. Many teams find Earthly covers 80 percent of the value with 20 percent of the learning curve, which is the honest trade.
Use a remote BuildKit runner that outlives individual CI jobs. Ephemeral GitHub Actions runners throw their disk away between jobs, so a self hosted runner, Earthly Cloud or a long lived BuildKit pod is what actually keeps the cache warm. Without that the main benefit of Earthly disappears and builds feel slow for no obvious reason.
In most repos yes. An Earthfile can define a build target that produces the same image your Dockerfile produced, plus lint, test, release and integration test targets that previously sat in a Makefile. Teams usually keep the Dockerfile for a short transition period, then retire it when the Earthfile is the source of truth for every environment.
WITH DOCKER starts a Docker daemon inside the Earthly target, and that is genuinely expensive. Use it where you need it, such as docker compose based integration tests, and avoid it where a plain container run would do. If a WITH DOCKER target dominates your pipeline time, moving it to a separate out of pipeline job is often the right call.
Our estimates are free. Describe the build and where it is stalling, and a price shows up before anyone edits the Earthfile.
Free estimate
Share the failing run or a note on the repo, and a build engineer gets back with a plan and a quote.
Your message is with a real person, and we'll get back to you soon.
Rather talk now? Call us: