Builtin variables

Varlock provides a set of builtin VARLOCK_* variables that are automatically populated with information about the current CI/deploy platform, git branch, commit, and inferred deployment environment. They are entirely opt-in — they only exist in your schema when you reference them.

Usage

Builtin variables are activated when you reference them via $VARLOCK_* in a value expression:

# @currentEnv=$VARLOCK_ENV
# ---
BUILD_TAG="build-$VARLOCK_COMMIT_SHA_SHORT"
DB_URL=if(
  eq($VARLOCK_ENV, development),
  postgres://localhost/myapp,
  postgres://${VARLOCK_ENV}-db.example.com/myapp
)

If you want to include a builtin variable in your resolved env without referencing it from another item, just define it with an empty value — varlock will populate it automatically:

VARLOCK_BRANCH=
VARLOCK_COMMIT_SHA_SHORT=

You can also use VARLOCK_ENV as your environment flag with @currentEnv, which means you don’t need to create your own APP_ENV variable — Varlock will auto-detect the environment for you.

Builtin Vars

`VARLOCK_ENV`

Type: string — one of development, preview, staging, production, test

The inferred deployment environment. Detection follows this priority:

Test environment — detected from NODE_ENV=test, VITEST, JEST_WORKER_ID, or VITEST_POOL_ID
Platform-provided — uses the platform’s own environment concept (e.g., Vercel’s VERCEL_ENV, Netlify’s CONTEXT)
Branch inference — in CI, infers from branch name: main/master/production/prod → production, staging/stage/develop/dev → staging, qa/test → test, anything else → preview
CI fallback — if in CI but no branch info is available, defaults to preview
Local fallback — if not in CI, defaults to development

Using with `@currentEnv`

# @currentEnv=$VARLOCK_ENV
# ---
DB_HOST=if(forEnv(production), "prod-db.example.com", "localhost")
DB_NAME=myapp
DB_URL="postgres://$DB_HOST/$DB_NAME"

Test environment caveat

Test runners and VARLOCK_ENV

Many test runners (Vitest, Jest, etc.) set NODE_ENV=test after the process has started — often after varlock has already loaded and resolved your env vars. This means VARLOCK_ENV may not detect test automatically in all setups.

If you depend on VARLOCK_ENV=test to load .env.test or toggle behavior via forEnv(test), explicitly pass it when running tests:

VARLOCK_ENV=test bun run test
# or
VARLOCK_ENV=test varlock run -- vitest

This is the same pattern recommended for any environment flag — see the environments guide for more details.