Earthly
Super simple build framework with fast, repeatable builds and an instantly familiar syntax – like Dockerfile and Makefile had a baby.
Install / Use
/learn @earthly/EarthlyREADME
Please note that Earthly is no longer actively maintained. Read more.
<div align="center"> <a href="https://earthly.dev"><img src="img/logo-banner-white-bg.png" alt="Earthly" width="700px" /></a> <br/> <em>It’s like Docker for builds</em> </div> <br/>
🔁 Repeatable Builds - Write builds once, and run them anywhere – on your laptop, remote, and in any CI.
❤️ Super Simple - Instantly recognizable syntax – like Dockerfile and Makefile had a baby.
🛠 Compatible with Every Language, Framework, and Build Tool - If it runs on Linux, it runs on Earthly.
🏘 Great for Monorepos and Polyrepos - Organize your build logic however makes the most sense for your project.
💨 Fast Builds - Build caching and parallel execution makes builds fast automatically.
♻️ Reuse, Don't Repeat - Never write the same code in multiple builds again.
🌎 Earthly is a versatile, approachable CI/CD framework that runs every pipeline inside containers, giving you repeatable builds that you write once and run anywhere. It has a super simple, instantly recognizable syntax that is easy to write and understand – like Dockerfile and Makefile had a baby. And it leverages and augments popular build tools instead of replacing them, so you don’t have to rewrite all your builds no matter what languages you use.
<br/> <div align="center"><a href="https://earthly.dev/get-earthly"><img src="docs/img/get-earthly-button.png" alt="Get Earthly" title="Get Earthly" /></a></div><h2 align="center">Table of Contents</h2>
- Why use Earthly?
- Where Does Earthly Fit?
- How Does It Work?
- Installation
- Quick Start
- Features
- FAQ
- Contributing
- Licensing
🔁 Repeatable Builds
Earthly runs all builds in containers, making them self-contained, isolated, repeatable, and portable. This allows for faster iteration on build scripts and easier debugging when something goes wrong – no more git commit -m "try again". When you write a build, you know it will execute correctly no matter where it runs – your laptop, a colleague’s laptop, or any CI. You don’t have to configure language-specific tooling, install additional dependencies, or complicate your build scripts to ensure they are compatible with different OSs. Earthly gives you consistent, repeatable builds regardless of where they run.
❤️ Super Simple
Earthly’s syntax is easy to write and understand. Most engineers can read an Earthfile instantly, without prior knowledge of Earthly. We combined some of the best ideas from Dockerfiles and Makefiles into one specification – like Dockerfile and Makefile had a baby.
🛠 Compatible with Every Language, Framework, and Build Tool
Earthly works with the compilers and build tools you use. If it runs on Linux, it runs on Earthly. And you don’t have to rewrite your existing builds or replace your package.json, go.mod, build.gradle, or Cargo.toml files. You can use Earthly as a wrapper around your existing tooling and still get Earthly’s repeatable builds, parallel execution, and build caching.
🏘 Great for Monorepos and Polyrepos
Earthly is great for both monorepos and polyrepos. You can split your build logic across multiple Earthfiles, placing some deeper inside the directory structure or even in other repositories. Referencing targets from other Earthfiles is easy regardless of where they are stored. So you can organize your build logic however makes the most sense for your project.
💨 Fast Builds
Earthly automatically executes build targets in parallel and makes maximum use of cache. This makes builds fast. Earthly also has powerful shared caching capabilities that speed up builds frequently run across a team or in sandboxed environments, such as Earthly Satellites, GitHub Actions, or your CI.
If your build has multiple steps, Earthly will:
- Build a directed acyclic graph (DAG).
- Isolate execution of each step.
- Run independent steps in parallel.
- Cache results for future use.
♻️ Reuse, Don't Repeat
Never have to write the same code in multiple builds again. With Earthly, you can reuse targets, artifacts, and images across multiple Earthfiles, even ones in other repositories, in a single line. Earthly is cache-aware, based on the individual hashes of each file, and has shared caching capabilities. So you can create a vast and efficient build hierarchy that only executes the minimum required steps.
<h2 align="center">Where Does Earthly Fit?</h2> <div align="center"><img src="docs/img/integration-diagram-v2.png" alt="Earthly fits between language-specific tooling and the CI" width="700px" /></div>Earthly is meant to be used both on your development machine and in CI. It runs on top of your CI/CD platform (such as Jenkins, Circle CI, GitHub Actions, and GitLab CI/CD). Earthly provides the benefits of a modern build automation system wherever it runs – such as caching and parallelism. It is a glue layer between language-specific build tooling (like maven, gradle, npm, pip, go build) and CI, working like a wrapper around your build tooling and build logic that isolates build execution from the environments they run in.
<h2 align="center">How Does It Work?</h2>In short: containers, layer caching, and complex build graphs!
Earthly executes builds in containers, where execution is isolated. The dependencies of the build are explicitly specified in the build definition, thus making the build self-sufficient.
We use a target-based system to help users break up complex builds into reusable parts. Nothing is shared between targets other than clearly declared dependencies. Nothing shared means no unexpected race conditions. In fact, the build is executed in parallel whenever possible, without any need for the user to take care of any locking or unexpected environment interactions.
<h2 align="center">Installation</h2>ℹ️ Note Earthfiles might seem very similar to Dockerfile multi-stage builds. In fact, the same technology is used underneath. However, a key difference is that Earthly is designed to be a general-purpose build system, not just a Docker image specification. Read more about how Earthly is different from Dockerfiles.
See installation instructions.
To build from source, check the contributing page.
<h2 align="center">Quick Start</h2>Here are some resources to get you started with Earthly
- 🏁 Getting started guide
- 👀 Examples
- 🔍 Explore Earthly's own build
- ✔️ Best practices
See also the full documentation.
Reference pages
A simple example (for Go)
# Earthfile
VERSION 0.8
FROM golang:1.15-alpine3.13
RUN apk --update --no-cache add git
WORKDIR /go-example
all:
BUILD +lint
BUILD +docker
build:
COPY main.go .
RUN go build -o build/go-example main.go
SAVE ARTIFACT build/go-example AS LOCAL build/go-example
lint:
RUN go get golang.org/x/lint/golint
COPY main.go .
RUN golint -set_exit_status ./...
docker:
COPY +build/go-example .
ENTRYPOINT ["/go-example/go-example"]
SAVE IMAGE go-example:latest
// main.go
package main
import "fmt"
func main() {
fmt.Println("hello world")
}
Invoke the build using earthly +all.
