Variable sets

A library variable set is a named bag of variables that lives in the library and can be linked to one or more projects. Every project the set is linked to receives the set’s variables as if they were defined locally — without copy-pasting and without risk of values drifting between projects.

Use library variable sets when the same variable should resolve to the same value (or environment-scoped value) in multiple projects: shared connection strings, common API endpoints, organization-wide feature flags, third-party credentials reused across services.

For variables that are project-specific, keep using project variables. The two coexist; you can link any number of library sets to a project and still define project-local variables on top.

How linking works

A project can link any number of library variable sets. Each link has a sort order that determines precedence when two linked sets define a variable with the same name.

Linking is bidirectional from a permissions standpoint: the user must be able to edit the project and be able to view library variable sets (see Permissions below).

Variable resolution order

When fDeploy builds the effective variable set for a project — both for the Insert Variable picker in the step editor and for the variable snapshot captured at release creation — values are layered in this order:

1. Linked library variable sets, in ascending sort order. Among linked sets, later sets win on a name collision.
2. Project variables, applied last. Project variables always win over any library set on a name collision.

This means a project can override a value from a shared library set just by defining a variable with the same name locally — no plumbing required. There is no per-environment override at the library level; environment scoping inside a library set works exactly as it does for project variables (see variable scope resolution).

Tip

Sort order is the only knob you have to resolve collisions between two library sets. If a project links both a generic Shared set and a more specific Payments set, place Payments below Shared so its values take precedence.

Sensitive values

Sensitive values inside a library variable set are encrypted and handled exactly like sensitive project variables — the same AES-256 storage, the same step-field decryption path, the same redaction in deployment logs, and the same $env:FDEPLOY_SENSITIVE_X injection for PowerShell script bodies. From the agent’s perspective, a library-set sensitive value is indistinguishable from a project sensitive value.

The same caveats apply: redaction is substring-based, and a script that derives output from a sensitive value can defeat masking.

Snapshots and the frozen-release contract

Library variable set values are captured into a release’s variable snapshot at release creation time. Editing the set afterwards does not change snapshots that were taken before the edit, and does not retroactively change deployments of older releases.

To pull updated library values into an existing release, use Update variable snapshot on the release — see variable snapshots for the full mechanics.

Usage view

Each variable set has a usage view listing every project linked to it, in sort order. Use this before editing or deleting a set to assess blast radius — a single value change can ripple into every project that links it.

The usage list filters out projects the viewer has no access to, so a non-administrator may see fewer entries than the actual link count shown on the set summary.

Deleting a set

A set linked to one or more projects cannot be deleted. Unlink it from every project first, then delete. This is intentional — silently removing variables that running deployment processes reference would surface as #{Variable.X} placeholders failing to resolve at deploy time, with no way to recover the original values.

Set names are globally unique across the library.

Permissions

Two permission gates apply:

• Viewing library variable sets — granted to system administrators, system managers, anyone holding the LibraryVariableSetEditor role, and implicitly to anyone who can view at least one project (they need to see what’s available to link).
• Creating, editing, or deleting sets — granted to system administrators, system managers, and holders of the LibraryVariableSetEditor role.

The LibraryVariableSetEditor role is globally scoped only — it cannot be narrowed to a specific project or environment. See Library roles for where the role sits relative to other roles.

Linking or unlinking a set on a project additionally requires the CanEditProject permission on the project itself, on top of view access to library sets.