Environment Variables

Environment Variables

Beez can load environment variables from files and config, expose them to build.lua, and include selected vars in cache fingerprints.

Reading values in build.lua

local buildType = beez.env("BUILD_TYPE")

Resolution order for beez.env(key):

1. Process environment (getenv), including values from env.vars and env files loaded by applyEnvironment()
2. Project root .env file (lazy file read on first beez.env() call)
3. nil if unset

Keys from env.files (for example .env.local) are available through beez.env() only after beez.config() has applied them to the process. Load project config before reading those vars in build.lua.

The env config section

env = {
    load_dotenv = true,
    dotenv_overrides_system = false,
    files = ".env",
    vars = {
        BUILD_TYPE = "Release",
    },
    hash_vars = {
        "CC",
        "CXX",
        "CFLAGS",
        "CXXFLAGS",
        "LDFLAGS",
        "BUILD_TYPE",
    },
    ignore_vars_for_hashing = {
        "TERM",
        "PWD",
    },
    mask_secrets = {
        "GITHUB_TOKEN",
    },
}

load_dotenv

When true (default if you do not set it), Beez also loads .env from the project root in addition to any env.files entries.

files

Extra env files to load. A single string or a list of paths:

files = ".env.local"
-- or
files = { ".env", ".env.local" }

Paths are relative to the project root unless absolute.

dotenv_overrides_system

Value	Behavior
false (default)	Do not overwrite vars already set in the shell
true	Values from dotenv files replace existing process env

env.vars from config always overrides the process environment when applied.

vars

Default values set for the Beez process. Useful for toolchain or output paths shared by the whole team:

vars = {
    CC = "clang",
    CXX = "clang++",
    BUILD_TYPE = "Release",
}

Cache fingerprints

Variables listed in hash_vars are included in the environment fingerprint for cache keys. If a hashed var changes, Beez treats cached step results as stale.

Default hash_vars when you omit the key:

• CC, CXX, CFLAGS, CXXFLAGS, LDFLAGS, BUILD_TYPE

Vars in ignore_vars_for_hashing are skipped even if they appear in hash_vars. Defaults include TERM, COLORTERM, PWD, SESSION_ID.

Add compiler flags or custom toolchain vars to hash_vars when they affect build output. Add noisy session vars to ignore_vars_for_hashing.

See Cache Keys and Invalidation for how fingerprints affect step cache and success cache.

Masking secrets in logs

Keys listed in mask_secrets are redacted in log output. Defaults include common token names (GITHUB_TOKEN, AWS_SECRET_ACCESS_KEY, etc.).

Add any secret your steps or workers might print.

Typical setup

.env (gitignored, local secrets and overrides):

BUILD_TYPE=Debug
API_TOKEN=...

config.lua (committed, team defaults):

env = {
    load_dotenv = true,
    vars = {
        BUILD_TYPE = "Release",
    },
    hash_vars = {
        "CC", "CXX", "BUILD_TYPE",
    },
}

build.lua:

beez.config(require("config"))

local buildType = beez.env("BUILD_TYPE") or "Release"

Shell vs Beez environment

Shell steps run with the environment Beez applied. They do not automatically re-source .env; Beez has already loaded it into the process.

If you run beez from CI, set vars in the CI environment or commit safe defaults in config.lua.

Next steps

• Project Config - where env fits in project settings
• Cache Settings - cache path and compression
• Configuration Overview - merge order