Running Earthly?

Earthly targets failing or caches not sharing? We fix it.

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.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

earthly-build.log

still failing

What it is

Earthly at a glance

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.

Type
Container native build tool using Earthfiles
First released
2020 initial release
License
Mozilla Public License 2.0, open source core, Earthly Cloud as a paid service
Maintained by
Earthly Technologies and open source contributors
Typically used for
CI builds, multi language monorepos, reproducible releases, shared build caches

The honest version

Earthly pros and cons

No technology is all upside. This is where Earthly earns its place and where it tends to cause trouble.

Where Earthly is strong

  • One build file per repoAn Earthfile covers lint, test, build and release for a project, so engineers no longer chase a Makefile plus a Dockerfile plus a CI YAML that each tell a different story.
  • Cache mounts cut rebuild timeGo modules, Rust target directories and node_modules caches are first class, and they work on local and remote runners through the same syntax.
  • Parallel targets out of the boxIndependent targets run in parallel on the runner, which turns a slow sequential pipeline into something that completes while you are still writing the PR description.
  • Portable across CI providersA GitHub Actions job, a GitLab job and a local developer all run the same earthly +ci command, so the CI product stops being load bearing.
  • WITH DOCKER lets you run integration testsA target can start a Docker daemon inside the build, run docker compose, and tear it down, which makes end to end tests reproducible rather than CI only.
  • Honest about the gap with DockerEarthly leans on BuildKit and does not pretend to replace the whole container story. Images still get pushed to a registry; Earthly just makes the build on the way there repeatable.

Where Earthly bites

  • Yet another build language to learnEarthfile syntax is close to Dockerfile but not identical, and the differences, especially around ARG scoping and target dependencies, trip engineers who think they already know it.
  • Remote runner cache can divergeA target that caches on a local runner may rebuild from scratch on the remote one if the base image differs, which eats the main advertised benefit until you align the two.
  • WITH DOCKER is expensiveStarting a Docker daemon inside a target is powerful and slow. Teams that overuse it end up with pipelines longer than the plain CI they were trying to replace.
  • Smaller community than Bazel or NixFewer blog posts, fewer prebuilt recipes for exotic languages, and a smaller pool of engineers who have deeply tuned an Earthly setup.
  • Cache growth needs attentionOn a self hosted runner the BuildKit cache can grow to tens of gigabytes without warning, and the runner starts failing on disk before anyone notices.
  • Version churn between 0.x releasesEarthfile syntax deprecations between 0.7 and 0.8 required work in repos that pinned older style. Reading migration notes is not optional.

Sound familiar?

Common Earthly problems we fix

The Earthly problems that bring people to us, and what you have once each one is fixed.

Earthfile syntax error

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

remote runner: connection refused

The remote runner is unreachable

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

cache not shared with remote runner

Cache hits only happen locally

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

COPY: no such file in build context

A COPY references a file that is not there

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

WITH DOCKER daemon exited early

An integration test target cannot start Docker

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

cache size near runner disk limit

The runner is running out of disk for caches

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

ARG not set: required by +release

A target is missing a required build argument

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

parallel target limit reached

Builds queue instead of running in parallel

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

Earthly help, from targets to shared runners

Pass us a failing +target or hand over the whole build system for an audit, either way we get it reproducible.

Rescue
An Earthfile that will not parse, a cache that stopped sharing, or a WITH DOCKER target that is timing out. We take the build back to green.
Earthfile design
Target boundaries, ARG scoping, cache mount strategy and base images chosen so builds are both fast and legible.
Remote runner topology
Shared BuildKit runners on Kubernetes, VMs or dedicated hardware, with authentication and cache retention worked out.
CI integration
GitHub Actions, GitLab, CircleCI and Jenkins wiring that treats earthly as the real build step and the CI provider as the trigger.
Migrations
Moving from Makefiles, Bazel or pure Dockerfiles onto Earthly incrementally, so the team keeps shipping while the move happens.
Managed Tech
Cache size monitoring, runner upkeep, Earthly version bumps and an engineer on call when a build lands on a cold cache during a release.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Earthly alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Earthly questions

Something else? Call+1 737 727 7327

Why is our Earthly cache not sharing across machines?

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.

Should we use Earthly or Bazel?

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.

How do we run Earthly in CI without burning the cache?

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.

Can Earthly replace our Makefile and Dockerfile?

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.

Why does WITH DOCKER slow our pipeline down?

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.

How much does Earthly help cost?

Our estimates are free. Describe the build and where it is stalling, and a price shows up before anyone edits the Earthfile.

Free estimate

Earthly builds misbehaving?

Share the failing run or a note on the repo, and a build engineer gets back with a plan and a quote.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.