Skip to content

windows_environment

Experimental. One environment variable on a Windows host, the machine’s or the login user’s, as the registry holds it, unexpanded. New logons see a change; programs already running keep the environment they started with.

Experimental. New, and tested on GitHub’s Windows Server 2022 and 2025 runners, not yet on an Azure server. See Windows readiness.

Use windows_environment to set an environment variable for the whole machine, such as JAVA_HOME or a proxy, or for the account Conn3x logs in as. It’s the [Environment]::SetEnvironmentVariable you’d otherwise run by hand on every server, kept in a plan so drift shows.

step "java_home" {
windows_environment {
name = "JAVA_HOME"
value = "C:\\Program Files\\Eclipse Adoptium\\jdk-21"
}
}

A value with % in it is stored to expand, as Windows’ own variables are:

step "app_logs" {
windows_environment {
name = "APP_LOGS"
value = "%ProgramData%\\App\\logs"
}
}
Name Type Required Description
level string No “machine” (default), in HKLM for every account, or “user”, in HKCU for the account Conn3x logs in as. Changing it is a different variable.
name string Yes The variable, such as JAVA_HOME. Not Path: give each folder in it a windows_path step.
on_remove string No What happens on the host when this resource is removed: “forget” (default) leaves the variable, “delete” removes it.
state string No “present” (default), or “absent” to remove the variable.
value string No Its value, compared as written: %SystemRoot% stays %SystemRoot%. A new variable with % in it is stored to expand; an existing one keeps its type. Required unless state is “absent”.

Conn3x sets these; reference them as conn3x_windows_environment.<circuit>__<step>["<host>"].<name>.

Name Type Description
in_sync bool Whether the variable matched at the last refresh.
revision string Changes each time Conn3x changes this on the host. Handlers watch it.

A step lowers to the conn3x_windows_environment resource, one instance per host, and connects with its circuit’s ssh block.

Reading. On every plan, Conn3x reads the variable from the registry, under HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment for the machine or HKCU\Environment for the user, without expanding it. in_sync is true when the value is exactly value, so %ProgramData% compares as %ProgramData%, not as the folder it names.

Applying. Conn3x writes the value to the registry. A variable that’s already there keeps its type; a new one with % in it is stored to expand, and one without is plain text.

When it takes effect. Windows hands each program its environment when the program starts. New logons, and programs they start, see the change. Programs already running, services included, keep what they had until they restart.

Path. Path is one string of folders, and setting it whole would drop whatever else is in it, so windows_environment refuses it. Give each folder its own windows_path step.

Changes. Changing value or state updates the variable in place. Changing name or level replaces the step.

on_remove = "forget", the default, leaves the variable. on_remove = "delete" removes it.