Use the Earthly CI Image
This guide is intended to help you use the Earthly image for your containerized CI workflows.
earthly/earthlyimage requires that it is run as
--privileged, or alternatively, it is run without the embedded Buildkit daemon (
It is recommended that the
earthly/earthlyimage is used with a pinned version when used in the context of a CI, in order to avoid accidental future breakage as
earthly/earthlyimage comes with an entrypoint that first starts up BuildKit and then issues an
earthlycommand that makes use of it. You may use the image just as you would use
earthlyitself otherwise. Any arguments are passed into the
Note that using the
earthlybinary as the entrypoint will not start up BuildKit within the same container and will instead attempt to use the Docker Daemon (assuming one is available via
/var/run/docker.sock) to start up BuildKit.
An alternative option is to use the
earthly/earthlyimage in conjunction with a remote BuildKit Daemon. You may use the environment variable
BUILDKIT_HOSTto specify the hostname of the remote BuildKit Daemon. When this environment variable is set, the
earthly/earthlyimage will not attempt to start BuildKit and will instead use the remote BuildKit Daemon.
You may also use the
earthly/earthlyimage to run a build against an Earthly Satellite. To achieve this you can pass along an
EARTHLY_TOKENenvironment variable, along with the command-line flags
--org, to point the build to a specific satellite.
For more details on using remote execution, see our guide on remote Buildkit or the introduction to Satellites.
The image expects the source code of the application you are building in the current working directory (by default
/workspace). You will need to copy or mount the necessary files to that directory prior to invoking the entrypoint.
docker run --privileged --rm -v "$PWD":/workspace earthly/earthly:v0.7.7 +my-target
Or, if you would like to use an alternative directory:
docker run --privileged --rm -v "$PWD":/my-dir -w /my-dir earthly/earthly:v0.7.7 +my-target
Alternatively, you may rely on Earthly to perform a git clone, by using the remote target reference format. For example:
docker run --privileged --rm earthly/earthly:v0.7.7 github.com/foo/bar:my-branch+target
As the embedded Buildkit daemon requires
--privileged, for some operations you may be able to use the
NO_BUILDKIT=1environment variable to disable the embedded Buildkit daemon. This is especially useful when running against a remote buildkit (like a Satellite), or when not performing a build as part of the command (like when using
When running the built image in your CI of choice, if you're not using a remote daemon, Earthly will start Buildkit within the same container. In this case, it is important to ensure that the directory used by Buildkit to cache the builds is mounted as a Docker volume. Failing to do so may result in excessive disk usage, slow builds, or Earthly not functioning properly.
We strongly recommend using a Docker volume for mounting
/tmp/earthly. If you do not, Buildkit can consume excessive disk space, operate very slowly, or it might not function correctly.
In some environments, not mounting
/tmp/earthlyas a Docker volume results in the following error:
--> WITH DOCKER RUN --privileged ...
rm: can't remove '/var/earthly/dind/...': Resource busy