Project-Level Secrets & Variables

Define secrets and variables once at the project level as a single source of truth, auto-inject them across resources, and override values per environment.

The Traditional Challenge

Traditionally, managing environment variables and secrets across different environments has been a major pain point:

Multiple environment-specific files to maintain
Risk of secrets exposure in version control
Complex secret rotation processes
Difficulty in maintaining consistency across environments
No clear separation between configuration and sensitive data

Project-level interface for managing secrets and variables as a single source of truth

Variables Management

Project-Level Definition: Define variables once at the project level as your source of truth
Key-Value Storage: Each variable has a key and value defined at the blueprint level
Auto-Injection: Mark variables for automatic injection across all resources
Resource-Level Flexibility: Create aliases for specific resource usage when needed
Environment Overrides: Override any variable at environment level without changing the source

Secrets Management

Secure by Design: Only secret keys are stored at project level
Environment-Level Values: Secret values are stored securely in the environment's secret manager
Flexible Access: Choose between auto-injection or selective usage through aliases
Safe Storage: No sensitive data in version control
Easy Rotation: Update secret values at environment level without touching the blueprint

How to Use Secrets/Variables at Project Level?

Note: Select theAuto Inject checkbox to automatically add (auto-inject) the key-value pair to all the resources in the Blueprint.

Benefits

Single Source of Truth: One place to define and manage all configurations
Environment Flexibility: Override values as needed for different environments
Security First: Proper separation of configuration and sensitive data
Simplified Management: No need to maintain multiple environment-specific files
Developer Friendly: Clear visibility of available variables and secrets

This approach transforms what was once a complex, risky process into a streamlined, secure system that scales with your needs.

Variable Status and Overrides

Each variable displays a status indicator showing its current state:

Status	Defination
DEFAULT	Environment uses the project-level default value (variables only, secrets have no project-level default)
OVERRIDDEN	Environment has a custom value that differs from default
NOT_SET	Variable key exists but no value is configured for this environment
NO_ACCESS	You lack VIEW_SECRETS permission to view this secret value

The multi-environment view displays all these statuses at once, making it easy to identify which environments have custom configurations and which inherit defaults.

Secret values are masked as **** in the table by default. Reveal a secret's value for a specific environment using the eye-icon toggle in that environment's column. This toggle requires the VIEW_SECRETS permission scoped to that environment — if you lack it for a given environment, the toggle stays disabled there and the status for that environment shows as NO_ACCESS.

Seeing Where a Variable Is Used

The Used By column shows how many resources currently consume a variable or secret. Select it to open a modal listing every consuming resource, with its Resource Type, Resource Name, Blueprint, and Environment, so you can confirm whether the reference is project-level or scoped to a specific environment.

Editing a Variable or Secret

Select Edit on a row to open a drawer where you can update the description, the project-level default value (variables only, secrets have no project-level default), and per-environment values together. Secret values can be revealed for editing per environment, gated by the same VIEW_SECRETS permission described above.

Referencing a Variable or Secret in Configuration

Once a variable or secret is defined at the project level, reference it from a resource's configuration instead of duplicating the value.

Locate the variable or secret in the table.
Select Copy $ Reference on that row.
Facets copies a template expression to your clipboard — for example ${blueprint.self.variables.<name>} for a variable, or ${blueprint.self.secrets.<name>} for a secret.
Open the module or resource configuration field where the value belongs, and paste the copied expression.
For fields that support it, use the reference autocomplete field directly instead of copy-pasting — start typing and select the variable or secret by name from the suggestions, which resolves to the same reference expression.

📘

You can also perform this operation programmatically. See the API Reference for details.

Deleting a Variable or Secret

Select Delete Variable on a row to remove a definition that's no longer needed.

🚧

Facets blocks deletion while a variable or secret is still referenced by any resource. The Delete Variable action stays disabled, with a tooltip explaining how many resources still use it. Remove all references before deleting.

Permissions

Different actions on this page require different permissions, checked independently:

Action	Required Permission	Scope
Define new variables/secrets and edit project-level fields (description, default value)	STACK_WRITE	Project
Edit per-environment values (Edit Env. Values)	ENVIRONMENT_CONFIGURE	Global, or scoped to a specific environment
Reveal a secret's actual value	VIEW_SECRETS	Scoped to a specific environment

A user can hold one of these permissions without the others — for example, someone with ENVIRONMENT_CONFIGURE but not STACK_WRITE can edit environment values but can't define new variables.

Troubleshooting

Problem	Solution
Creating a variable or secret fails because the name already exists	Choose a different name, or edit the existing definition instead of creating a new one.
A bulk create or update request is rejected for duplicate names	Each variable name must be unique within a single request. Remove duplicates and resubmit.
The project or a referenced variable can't be found	Confirm the project and variable name are correct. The definition may have been deleted or renamed.
Saving fails with an access-denied error	You lack STACK_WRITE for project-level fields, or ENVIRONMENT_CONFIGURE for one or more of the environments you're writing to. Ask a project admin for access.
The page shows "Failed to load variables"	The initial data fetch failed. Reload the page; if it persists, check your connection or contact your administrator.
The page shows "Invalid Project"	Facets couldn't resolve a project from the current URL. Navigate to the project from its dashboard instead of a direct link.

Environment-Level Management - Compare values across environments and bulk-edit overrides
Resource-Level Variables - Override a variable's default for a single resource
Resource Connections - Reference other resources' fields using $ syntax
Secrets Backend Integration - How secret values are stored and encrypted
API Reference - Programmatic access to variables and secrets