Skip to content

Document config-shaping env vars delivered via loadEnv .env files #564

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kylebernhardy wants to merge 4 commits into
base: main
Choose a base branch
from
+10 −0
Open

Document config-shaping env vars delivered via loadEnv .env files #564

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
067593e
Document config-shaping env vars via loadEnv (harper#1580)
nizzlenitz Jul 2, 2026
938746d
Clarify override belongs to the loadEnv config block
nizzlenitz Jul 2, 2026
43f7c75
Pivot to warn-don't-honor per harper#1580 direction
nizzlenitz Jul 8, 2026
6918477
Note the warning also ships in 5.1.x patches (harper#1580 patch-labeled)
nizzlenitz Jul 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions reference/environment-variables/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,16 @@ loadEnv:

Files are loaded in the order specified.

## Config-Shaping Variables Are Not Honored

@kriszyp kriszyp Jul 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This guidance is now already present on origin/main in the loadEnv warning added by #579 (current main lines 49-57). A three-way merge keeps both insertions, so the page would explain the same rule and workaround twice. Could we rebase and fold only the uniquely useful warning-timing detail into the existing warning, or close this PR as superseded?


<VersionBadge type="changed" version="v5.2.0" />

The three configuration env vars — `HARPER_DEFAULT_CONFIG`, `HARPER_CONFIG`, and `HARPER_SET_CONFIG` (see [Configuration](../configuration/overview.md)) — shape Harper's root configuration, which is composed once at startup, **before components load**. Delivering one of them through a `loadEnv` `.env` file therefore has **no effect**: configuration is strictly top-down (the instance's configuration controls components, never the reverse), so a component cannot shape instance-wide config.

As of 5.2.0 (and 5.1.x patch releases from 5.1.18) this is no longer silent: Harper logs a prominent warning at startup for each config-shaping variable found in a component `.env` file — naming the variable and the file — and again at component load time (which also covers components deployed after startup). Earlier versions ignored these variables without any message.

@kriszyp kriszyp Jul 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The v5.1 backport first shipped in v5.1.19, not v5.1.18: merge 2fff82731 is not contained by the v5.1.18 tag, while it is contained by v5.1.19 (componentEnvPrepass.ts is likewise absent in 5.1.18 and present in 5.1.19). Please change this to from 5.1.19 so 5.1.18 operators are not told to expect warnings their version cannot emit.


To configure the instance, use the supported channels instead: set the variable in the process environment (container env, service unit, shell), or put the equivalent keys in the instance's `harper-config.yaml`.

## Related

- [Components Overview](../components/overview.md)
Expand Down