LogoLogo
HomeBlogGitHubGet Started FreeLogin
Earthly 0.6
Earthly 0.6
  • 👋Introduction
  • 💻Installation
  • 🎓Learn the basics
    • Part 1: A simple Earthfile
    • Part 2: Outputs
    • Part 3: Adding dependencies With Caching
    • Part 4: Args
    • Part 5: Importing
    • Part 6: Using Docker In Earthly
    • Final words
  • ✅Best practices
  • 📖Docs
    • Guides
      • Authenticating Git and image registries
      • Target, artifact and command referencing
      • Build arguments and secrets
      • User-defined commands (UDCs)
      • Managing cache
      • Advanced local caching
      • Using Docker in Earthly
      • Integration Testing
      • Debugging techniques
      • Multi-platform builds
      • Podman
      • Configuring registries
        • AWS ECR
        • GCP Artifact Registry
        • Azure ACR
        • Self-signed certificates
      • Using the Earthly Docker Images
        • earthly/earthly
        • earthly/buildkitd
    • Remote runners
    • Remote caching
    • Earthfile reference
      • Builtin args
      • Excluding patterns
      • Version-specific features
    • The earthly command
    • Configuration reference
    • Examples
    • Misc
      • Alternative installation
      • Data collection
      • Definitions
      • Public key authentication
  • 🔧CI Integration
    • Overview
    • Use the Earthly CI Image
    • Build your own Earthly CI Image
    • Pull-Through Cache
    • Remote BuildKit
    • Vendor-Specific Guides
      • Jenkins
      • Circle CI
      • GitHub Actions
      • AWS CodeBuild
      • Kubernetes
      • Google Cloud Build
      • GitLab CI/CD
      • Woodpecker CI
  • ☁️ Earthly Cloud
    • Overview
    • Cloud secrets
    • Satellites
      • Managing Satellites
      • Using Satellites
Powered by GitBook
On this page
  • Format
  • Global configuration reference
  • cache_size_mb
  • cache_size_pct
  • secret_provider (experimental)
  • disable_analytics
  • disable_log_sharing
  • conversion_parallelism
  • buildkit_max_parallelism
  • buildkit_additional_args
  • buildkit_additional_config
  • cni_mtu
  • ip_tables
  • no_loop_device (obsolete)
  • cache_path (obsolete)
  • Frontend configuration
  • Git configuration reference
  • site-specific options

Was this helpful?

Edit on GitHub
  1. Docs

Configuration reference

PreviousThe earthly commandNextExamples

Last updated 1 year ago

Was this helpful?

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 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

Tip

earthly config <key> <value>

For example

earthly config global.cache_size_mb 20000

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. Setting this to 0, either explicitly or by omission, will cause buildkit to use its internal default of 10% of the root filesystem.

cache_size_pct

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.

secret_provider (experimental)

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.

Note

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.

disable_analytics

disable_log_sharing

When set to true, disables sharing build logs after each build. This setting applies to logged-in users only.

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:

global:
  buildkit_additional_args: ["--userns", "host"]

buildkit_additional_config

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"]

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)

Frontend configuration

This option allows you to specify what supported frontend you are using (Docker / Podman). By default, Earthly will attempt to discover the frontend in this order: Docker -> Podman -> None

For Docker:

global:
  container_frontend: docker-shell

For Podman:

global:
  container_frontend: podman-shell

You can use the following command to set the configuration option using the earthly CLI:

# Docker
earthly config 'global.container_frontend' 'docker-shell'

# Podman
earthly config 'global.container_frontend' 'podman-shell'

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.

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.

strict_host_key_checking

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.

Tip

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

port

Connect using a non-standard git port, e.g. 2222.

prefix

The prefix option is used to indicate where git repositories are stored on the server, e.g. /var/git/.

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>.

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.

To quickly change a configuration item via the earthly command, you can use .

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 .

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

See the for a guide on setting up authentication.

See the for a guide on setting up authentication with self-hosted git repositories.

See the for a complete definition of the supported regular expression syntax.

See the for a guide on setting up authentication with self-hosted git repositories.

📖
YAML
data collection page
page on managing cache
Authentication guide
Authentication guide
RE2 docs
Authentication guide
earthly config