Configuration reference
Global configuration values for earthly can be stored on disk in the configuration file.
By default, earthly reads the configuration file ~/.earthly/config.yml; however, it can also be overridden with the --config command flag option.

Format

The earthly config file is a YAML formatted file that looks like:
1
global:
2
cache_size_mb: <cache_size_mb>
3
git:
4
global:
5
url_instead_of: <url_instead_of>
6
<site>:
7
auth: https|ssh
8
user: <username>
9
password: <password>
10
<site2>:
11
...
Copied!
Example:
1
global:
2
cache_size_mb: 20000
3
git:
4
global:
5
url_instead_of: "[email protected]:=https://localmirror.example.com/"
6
github.com:
7
auth: https
8
user: alice
9
password: itsasecret
Copied!
Tip
To quickly change a configuration item via the earthly command, you can use earthly config.
1
earthly config <key> <value>
Copied!
For example
1
earthly config global.cache_size_mb 20000
Copied!

Global configuration reference

cache_size_mb

Specifies the total size of the BuildKit cache, in MB. The BuildKit daemon uses this setting to configure automatic garbage collection of old cache. A value of 0 causes the size to be adaptive depending on how much space is available on your system. The default is 0.

disable_analytics

When set to true, disables collecting command line analytics; otherwise, earthly will report anonymized analytics for invocation of the earthly command. For more information see the data collection page.

conversion_parallelism

The number of concurrent converters for speeding up build targets that use blocking commands like IF, WITH DOCKER --load, FROM DOCKERFILE and others.

buildkit_max_parallelism

The maximum parallelism configured for the buildkit daemon workers. The default is 20.
Note
Set this configuration to a lower value if your machine is resource constrained and performs poorly when running too many builds in parallel.

buildkit_additional_args

This option allows you to pass additional options to Docker when starting up the Earthly BuildKit daemon. For example, this can be used to bypass user namespacing like so:
1
global:
2
buildkit_additional_args: ["--userns", "host"]
Copied!

buildkit_additional_config

This option allows you to pass additional options to BuildKit. For example, this can be used to specify additional CA certificates:
1
global:
2
buildkit_additional_args: ["-v", "<absolute-path-to-ca-file>:/etc/config/add.ca"]
3
buildkit_additional_config: |
4
[registry."<registry-hostname>"]
5
ca=["/etc/config/add.ca"]
Copied!

cni_mtu

Allows overriding Earthly's automatic MTU detection. This is used when configuring the BuildKit internal CNI network. MTU must be between 64 and 65,536.

ip_tables

Allows overriding Earthly's automatic ip_tables module detection. Valid choices are iptables-legacy or iptables-nft.

no_loop_device (obsolete)

This option is obsolete and it is ignored. Earthly no longer uses a loop device for its cache.

cache_path (obsolete)

This option is obsolete and it is ignored. Earthly cache has moved to a Docker volume. For more information see the page on managing cache.

Git configuration reference

All git configuration is contained under site-specific options.

site-specific options

site

The git repository hostname. For example github.com, or gitlab.com

auth

Either ssh, https, or auto (default). If https is specified, user and password fields are used to authenticate over HTTPS when pulling from git for the corresponding site. If auto is specified earthly will use ssh when the ssh-agent is running and has at least one key loaded, and will fallback to using https when no ssh-keys are present.
See the Authentication guide for a guide on setting up authentication.

user

The HTTPS username to use when auth is set to https. This setting is ignored when auth is ssh.

password

The HTTPS password to use when auth is set to https. This setting is ignored when auth is ssh.

pattern

A regular expression defined to match git URLs, defaults to the <site>/([^/]+)/([^/]+). For example if the site is github.com, then the default pattern will match github.com/<user>/<repo>.
See the Authentication guide for a guide on setting up authentication with self-hosted git repositories.
See the RE2 docs for a complete definition of the supported regular expression syntax.

substitute

If specified, a regular expression substitution will be performed to determine which URL is cloned by git. Values like $1, $2, ... will be replaced with matched subgroup data. If no substitute is given, a URL will be created based on the requested SSH authentication mode.
See the Authentication guide for a guide on setting up authentication with self-hosted git repositories.
Last modified 2d ago