Skip to content

windows_path

Experimental. One folder in a Windows host’s Path, the machine’s or the login user’s. The other folders and their order stay as they are. New logons see a change; programs already running keep the Path 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_path to put one folder on a Windows host’s Path, such as a tool’s bin folder, and leave every other folder where it is. Path is one long string, so setting it whole with setx or SetEnvironmentVariable is how servers lose half their tools, and how %SystemRoot% gets expanded into a fixed C:\Windows. This step changes one folder and nothing else.

step "go_on_path" {
windows_path {
element = "C:\\Program Files\\Go\\bin"
}
}

Take an old folder out of the user’s own Path:

step "old_tool_gone" {
windows_path {
element = "C:\\OldTool"
scope = "user"
state = "absent"
}
}
Name Type Required Description
element string Yes The folder, such as C:\Program Files\Go\bin. Compared as Windows does, without case and with or without a trailing backslash. Added at the end.
on_remove string No What happens on the host when this resource is removed: “forget” (default) leaves the folder in Path, “delete” takes it out.
scope 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 Path entry.
state string No “present” (default), or “absent” to take every copy of the folder out.

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

Name Type Description
in_sync bool Whether Path had the folder, or didn’t for state “absent”, 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_path resource, one instance per host, and connects with its circuit’s ssh block.

Reading. On every plan, Conn3x reads Path from the registry, the machine’s or the user’s, without expanding it, and looks for the folder. Folders compare the way Windows compares them: C:\Tools, c:\tools and C:\Tools\ are the same folder.

Applying. To add the folder, Conn3x reads Path again and writes it back with the folder at the end. To remove it, every copy of it comes out. The other folders, their order and their %SystemRoot%-style names are written back exactly as they were, and Path keeps its type, so it still expands.

When it takes effect. New logons, and programs they start, see the change. Programs already running, services included, keep the Path they started with until they restart.

Changes. Changing state updates Path in place. Changing element or scope replaces the step.

on_remove = "forget", the default, leaves the folder on Path. on_remove = "delete" takes it out.