Earthly — Build Automation for the Container Era

What it is

Earthly is a build automation tool that runs builds inside containers, ensuring they work the same on your laptop, your teammate's laptop, and in CI. It uses an Earthfile (similar to a Dockerfile) to define build targets with explicit inputs and outputs. Each target runs in an isolated container with caching, parallelism, and dependency management built in.

Earthly is for teams frustrated by builds that pass locally but fail in CI, or vice versa. If you maintain complex Makefiles, Bash scripts, or multi-step CI configurations, Earthly replaces them with a single, reproducible definition.

How it saves time or tokens

Earthly eliminates the 'works on my machine' problem by running builds in containers. Layer caching means only changed steps re-execute, saving minutes on each build. Parallel execution of independent targets reduces total build time. A single Earthfile replaces Makefiles, shell scripts, and CI-specific configuration files. For AI workflows, the declarative Earthfile syntax is concise and easy to generate or review.

How to use

1. Install Earthly: brew install earthly (macOS) or follow the install guide for your OS.
2. Create an Earthfile in your project root defining build targets.
3. Run targets with earthly +build, earthly +test, etc.

Example

# Earthfile
VERSION 0.8

FROM golang:1.23
WORKDIR /app

deps:
    COPY go.mod go.sum .
    RUN go mod download
    SAVE IMAGE --cache-hint

build:
    FROM +deps
    COPY . .
    RUN go build -o bin/myapp ./cmd/myapp
    SAVE ARTIFACT bin/myapp AS LOCAL bin/myapp

test:
    FROM +deps
    COPY . .
    RUN go test ./...

docker:
    FROM alpine:3.19
    COPY +build/myapp /usr/local/bin/myapp
    ENTRYPOINT ["/usr/local/bin/myapp"]
    SAVE IMAGE myapp:latest

Related on TokRepo

• DevOps AI tools -- build and deployment automation tools
• AI tools for automation -- CI/CD and workflow automation

Common pitfalls

• Not using cache hints on dependency steps. Mark dependency download steps with SAVE IMAGE --cache-hint so they persist across builds. Without caching, every build re-downloads dependencies.
• Mixing Earthly with traditional CI scripts. Earthly works best when it owns the build definition end-to-end. Your CI config should just call earthly +target rather than duplicating build logic.
• Forgetting that each target runs in a fresh container. Files from one target are not available in another unless explicitly passed with COPY +target/artifact.