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.
The earthly config file is a YAML formatted file that looks like:
global:
cache_size_mb: <cache_size_mb>
git:
global:
url_instead_of: <url_instead_of>
<site>:
auth: https|ssh
user: <username>
password: <password>
<site2>:
...
Example:
global:
cache_size_mb: 20000
git:
global:
url_instead_of: "git@example.com:=https://localmirror.example.com/"
github.com:
auth: https
user: alice
password: itsasecret
{% hint style='info' %}
To quickly change a configuration item via the earthly
command, you can use earthly config
.
earthly config <key> <value>
For example
earthly config global.cache_size_mb 20000
{% endhint %}
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.
Specifies the total size of the BuildKit cache, as a percentage (0-100) of the total filesystem size.
When used in combination with cache_size_mb
, the lesser of the two values will be used. This limit is ignored when set to 0.
A custom user-supplied program to call which returns a secret for use by earthly. The secret identifier is passed as the first argument to the program.
If no secret is found, the program can instruct earthly to continue searching for secrets under .env
, by exiting with a status code of 2
, all other non-zero
status codes will cause earthly to exit.
For example, if you have:
config:
secret_provider: my-secret-provider
and my-secret-provider
(which is accessible on your PATH
):
#!/bin/sh
set -e
if [ "$1" = "mysecret" ]; then
echo -n "open sesame"
exit 0
fi
exit 2
Then when earthly encounters a command that requires a secret, such as
RUN --secret mysecret echo "the passphrase is $mysecret."
earthly will request the secret for mysecret
by calling my-secret_provider mysecret
.
{% hint style='info' %}
All stdout data will be used as the secret value, including whitespace (and newlines).
You may want to use echo -n
to prevent returning a newline.
Any data sent to stderr will be displayed on the earthly console, this makes it possible
to insert commands such as echo >&2 "here is some debug text"
without affecting the contents
of the secret.
{% endhint %}
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.
When set to true, disables sharing build logs after each build. This setting applies to logged-in users only.
The number of concurrent converters for speeding up build targets that use blocking commands like IF
, WITH DOCKER --load
, FROM DOCKERFILE
and others.
The maximum parallelism configured for the buildkit daemon workers. The default is 20.
{% hint style='info' %}
Set this configuration to a lower value if your machine is resource constrained and performs poorly when running too many builds in parallel.
{% endhint %}
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:
global:
buildkit_additional_args: ["--userns", "host"]
This option allows you to pass additional options to BuildKit. For example, this can be used to specify additional CA certificates:
global:
buildkit_additional_args: ["-v", "<absolute-path-to-ca-file>:/etc/config/add.ca"]
buildkit_additional_config: |
[registry."<registry-hostname>"]
ca=["/etc/config/add.ca"]
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.
Allows overriding Earthly's automatic ip_tables
module detection. Valid choices are iptables-legacy
or iptables-nft
.
This option is obsolete and it is ignored. Earthly no longer uses a loop device for its cache.
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.
All git configuration is contained under site-specific options.
The git repository hostname. For example github.com
, or gitlab.com
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.
The HTTPS username to use when auth is set to https
. This setting is ignored when auth is ssh
.
The HTTPS password to use when auth is set to https
. This setting is ignored when auth is ssh
.
The strict_host_key_checking
option can be used to control access to ssh-based repos whose key is not known or has changed.
Strict host key checking is enabled by default, setting it to false
disables host key checking.
This setting is only used when auth is ssh
.
{% hint style='info' %}
Disabling strict host key checking is a bad security practice (as it makes a man-in-the-middle attack possible).
Instead, it's recommended to record the host's ssh key to ~/.ssh/known_hosts
; this can be done by running
ssh-keyscan <hostname> >> ~/.ssh/known_hosts
{% endhint %}
Connect using a non-standard git port, e.g. 2222
.
The prefix
option is used to indicate where git repositories are stored on the server, e.g. /var/git/
.
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.
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.