Earthly has the ability to use secure cloud-based storage for build secrets. This page goes through the basic setup and usage examples.
Cloud secrets can be used to share secrets between team members or across multiple computers and a CI systems.
Each user has a non-sharable private user space which can be referenced by
/user/...; this can be thought of as your home directory. To view this workspace, try running:
earthly secrets ls
earthly secrets ls /user
Secrets are referenced by a path, and can contain up to 512 bytes.
To set a secret value, use the
earthly secrets set /user/my_key 'hello world'
To view a secret value, use the
earthly secrets ls /user
earthly secrets get /user/my_key
Consider the Earthfile:
RUN --secret MY_KEY=+secrets/user/my_key echo $MY_KEY
SAVE IMAGE myimage:latest
The env variable
MY_KEYwill be set with the value stored under your private
You can build it via:
To share secrets between teams, an organization must first be created:
earthly org create <org-name>
Then additional users can be invited into the organization:
earthly org invite /<org-name>/ <email>
By default this will grant the invited user read privileges to all keys under the organization. It's also possible to use the
--writeflag to grant write permission too. Additionally, the permissions can be set to lower paths.
Alice then creates an organization called hush-co:
earthly org create hush-co
Alice then creates a secret under the
earthly secrets set /hush-co/project-zulu/transponder-code peanut
Alice then grants Bob read permission on all of
Bob now has permission to everything under the
/hush-co/project-zulu/directory. If he runs
earthly secrets ls /hush-co/
he will see:
However if Alice were to create any secrets outside of
project-zulu, Bob would not be able to list or retrieve them.
To reference secrets from a CI environment, you can make use of the password or ssh-key authentication referenced under the login/logout section, or you can generate an authentication token by running:
earthly account create-token [--write] <token-name>
This token can then be exported as
Which will then force Earthly to use that token when accessing secrets. This is useful for cases where running an ssh-agent is impractical.
The Earthly command uses HTTPS to communicate with the cloud secrets server. The server encrypts all secrets using OpenPGP's implementation of AES256 before storing it in a database. We use industry-standard security practices for managing our encryption keys in the cloud. For more information see our Security page.
Secrets are presented to BuildKit in a similar fashion as locally-supplied secrets: When BuildKit encounters a
RUNcommand that requires a secret, the BuildKit daemon will request the secret from the earthly command-line process --
earthlywill then make a request to earthly's cloud storage server (along with the auth token); once the server returns the secret, that secret will be passed to BuildKit.