Skip to main content
Secrets are encrypted environment variables associated with your BuildBuddy organization. Secrets can be used in actions executed with remote execution as well as BuildBuddy remote runners. BuildBuddy encrypts secrets with a libsodium sealed box. Secrets are encrypted before they are sent to BuildBuddy’s servers, and stay encrypted until they are used.

​
Why use secrets?

Builds that are executed remotely on BuildBuddy’s servers may occasionally need access to an API key or other credentials. For example, you may want to pass credentials for a Docker image.
Storing these sensitive parameters as plain environment variables is undesirable because those keys would be stored unencrypted in BuildBuddy’s Action Cache. While BuildBuddy’s cache requires authorization and is secured using TLS, storing so many copies of the secret in cache increases attack surface and increases the chance of accidentally exposing your own credentials.
Secrets solve this problem by allowing sensitive keys to be stored in encrypted format separately from the actions themselves.

​
Defining secrets

Secrets can be added to your organization using the Secrets page in settings.
1

Navigate to Secrets page

Open your organization settings and go to the Secrets tab.
2

Add a new secret

Click “Add Secret” and provide:
  • Secret name (used to reference it in your builds)
  • Secret value (will be encrypted before storage)
3

Save the secret

Click save to encrypt and store the secret.
Secrets can be edited or deleted using the Secrets page. Once a secret is saved, its currently stored value cannot be viewed using the Secrets page.

​
Getting secret values

To opt a specific action into secrets, you can define the remote exec property include-secrets=true. We recommend doing this per-action to avoid exposing secrets to actions that do not need them.Example:
BUILD
foo_library(
    # ...
    exec_properties = {
        "include-secrets": "true",
    }
)
Only enable include-secrets for actions that actually need access to secrets to minimize the attack surface.

​
Short-lived secrets

For secrets that have a short Time To Live (TTL), BuildBuddy supports setting environment variables via special headers passed at the Bazel command line. Headers are more secure than setting environment variables with Bazel, as they are not stored in the remote cache.
Use env-overrides for simple key-value pairs:
--remote_exec_header=x-buildbuddy-platform.env-overrides=VAR_A=value_a,VAR_B=val_b
At execution time:
> echo $VAR_A
value_a
> echo $VAR_B
val_b
If multiple values are given with the same variable name, the last value will be used. If a variable is specified in both env-overrides and env-overrides-base64, env-overrides-base64 will take priority.
These secrets will be set as environment variables at action execution time, overriding the default environment variables on your container image as well as the environment variables set by Bazel as part of the action configuration.
Secrets may be cached as part of action results if not properly handled. Avoid printing secret values to the console or storing them in action outputs.
Secrets that are passed through env-overrides or env-overrides-base64 headers are not subjected to include-secrets control documented above.

​
Security notes

Secrets are encrypted on the client-side using libsodium, which is based on NaCl.

Organization-specific keys

The public key used to encrypt secrets is unique to each organization. The private key used to decrypt secrets is stored encrypted and only decrypted when used to unseal secrets.

Encrypted at rest

Secrets are only stored in their encrypted form and are decrypted on-demand for actions that opt in to receiving secrets.

Encrypted in transit

All communication with BuildBuddy servers uses TLS encryption to protect secrets during transmission.

Minimal exposure

Secrets are only decrypted for actions that explicitly opt in, reducing the attack surface.
Avoid printing secret values to your build logs or action outputs. This is the most common way secrets accidentally leak.

​
Best practices

Prefer generating short-lived tokens (e.g., using gcloud auth print-access-token) over storing long-lived credentials. Pass these via remote headers for maximum security.
Only enable include-secrets=true for specific actions that need secrets, not globally for all actions.
Update secrets periodically and when team members with access leave the organization.
Review which actions have access to secrets and remove unnecessary access.
Name secrets clearly to indicate their purpose and scope (e.g., PROD_DB_PASSWORD vs db_pass).

Build docs developers (and LLMs) love

Get started for freeTalk to us