Environment Variables
Environment variables come from three sources: the shell environment, .env files and values defined in the build file.
Shell environment
Variables from the shell environment are passed to a command when the task declares them:
tasks:
example:
envs:
VERSION: $VERSION
cmds:
- echo $VERSIONEvery environment variable a task uses should be declared in its envs. Hammerkit checks that each one is defined and otherwise fails with an error, to prevent undesired behavior.
.env file
Environment variables can be defined in a .env file. This is recommended for secret values that should neither be committed nor made public.
NPM_TOKEN=abctasks:
example:
envs:
NPM_TOKEN: $NPM_TOKEN
cmds:
- npm publishDefined values in the build file
Environment variables can be defined in the build file itself. They can be defined for the entire build file or only for specific tasks.
envs:
NODE_VERSION: '22'
tasks:
example:
cmds:
- echo $NODE_VERSION
override_example:
envs:
NODE_VERSION: '20'
cmds:
- echo $NODE_VERSIONVariables defined in a build file are scoped to that file. Neither referenced nor included tasks have access to them. Pass a value on to an include with with, as NODE_VERSION: ${NODE_VERSION}.
Cache key
Every variable a task receives, including each build-file envs value, is part of
its cache key: changing one reruns the task. A build-file
value only a few tasks need — an image tag, a test token — therefore reruns every
task in the file when it changes. Define such values on the tasks that use them.
validate warns about this: for each task with commands it
lists the build-file envs its definition never mentions as $NAME or ${NAME}.
warn at lint build-file envs E2E_TOKEN are part of this task's cache key but not referenced by it: …Hammerkit can't see what a tool reads at runtime, so a variable such as
NODE_ENV that every task's tooling picks up on its own belongs in the build-file
envs despite the warning.
Precedence
A variable can be defined in more than one place. Hammerkit resolves it like this:
- Task
envswin over build-fileenvson the same key. In the example aboveoverride_exampleprints20, whileexampleprints22. - A value of exactly
$NAMEis a reference that is filled in from, in order:- a
--set NAME=valueargument on the hammerkit command, then - the shell / process environment, then
- a
.envfile in the build file's directory.
- a
If a referenced $NAME is set nowhere, hammerkit aborts before running with
missing environment variable NAME. A variable set to an empty string counts as
set, as in a shell: export NAME= passes an empty value, which is how a CI job
provides a variable its provider leaves unset on some pipelines.
Every variable a task uses must be declared in its envs (directly or via
$NAME). Hammerkit only passes declared variables to the command, so an
undeclared shell variable is not leaked into the task.
Interpolation
There are two distinct places a variable can appear:
Inside a command (cmds), $NAME is expanded by the shell at runtime, using
the variables hammerkit passed in — exactly like a normal shell. This is the
echo $NODE_VERSION case above.
Inside other task fields, hammerkit substitutes $NAME itself when it plans
the task — before anything runs. This works for image, src, generates,
mounts, ports, shell, command working directories and a service's image,
so you can drive them from a single value:
envs:
NODE_VERSION: '24'
tasks:
build:
image: node:$NODE_VERSION-alpine # -> node:24-alpine
src:
- src
cmds:
- tsc -bInside an envs value, ${NAME} is replaced anywhere in the string, and
${NAME:-default} falls back to default when NAME is set nowhere. A name comes
from the shell / process environment, then a .env file, then a literal value of
the same envs (build file and task merged), then the default:
envs:
DB_USER: app
tasks:
e2e:
envs:
DATABASE_URL: postgres://${DB_USER}@db:5432/app # -> postgres://app@db:5432/app
SPEC: ${E2E_SPEC:-e2e/**/*.cy.ts} # E2E_SPEC=e2e/login.cy.ts narrows it
MR_IID: ${CI_MERGE_REQUEST_IID:-} # empty outside merge request pipelines
cmds:
- cypress run --spec "$SPEC"A ${NAME} without a default that is set nowhere fails like a missing $NAME,
when a task that declares it runs.
The whole value $NAME (no braces) is a reference to the shell or .env only, as
before. Field substitution matches $NAME and ${NAME} anywhere in the string and
is case-insensitive; a value defined in envs (like NODE_VERSION: '24', or one
built with ${…}) is what gets substituted into fields such as image. A name is
matched as the text it is (a . in it is a dot), and a value is put in as it is
written: a $NAME inside the value that was put in is not substituted again.