Forgecroft Docs
Quickstart Guides Essentials Power Agent API Reference
Core ConceptsCLI ReferenceGo SDKAuthenticationAPI KeysRoles & PermissionsCreating WorkspacesVCS ConnectionsCredentialsState BackendsExecution ModesWorkspace AttributesDependencies & PromotionStacks OverviewCreating StacksEnvironments & VarfilesPromotion GraphManaging StacksRun LifecyclePlan vs ApplyChangesetsApprovalsLogsForce UnlockDrift DetectionTroubleshootingGovernance OverviewPolicy SetsWriting RegoRego PlaygroundApproval RulesExternal ChecksGovernance PreviewGovernance TimelineManaging TeamsNotification ChannelsNotification TargetsUser PreferencesAccess GrantsAudit EventsGitHub AppSlackCredential TypesState Backends
Guides / Stacks

Environments and Varfiles

Each environment in a stack gets its own workspace with isolated configuration and .tfvars files.

One Environment = One Workspace

When you create a stack, each environment becomes its own workspace. Each workspace is fully isolated:

Var Files

Each environment can have its own .tfvars file paths:

{
  "environments": [
    {
      "name": "dev",
      "var_files": ["env/dev.tfvars"]
    },
    {
      "name": "staging",
      "var_files": ["env/staging.tfvars"]
    },
    {
      "name": "prod",
      "var_files": ["env/prod.tfvars", "env/prod-secrets.tfvars"]
    }
  ]
}

The var_files are passed to the IaC tool during execution, so each environment gets its own variable values.

Multiple var files per environment are supported — they are applied in order, with later files overriding earlier values.

Environment Order

Environments are assigned an environment_order based on their declaration order in the environments array:

"environments": [
  { "name": "dev" },      // order: 0
  { "name": "staging" },  // order: 1
  { "name": "prod" }      // order: 2
]

This order is used for sorting and display purposes. It does not affect promotion — that’s controlled by promote_to.

Per-Environment Workspace Properties

Each created workspace inherits the stack’s shared configuration but has its own:

PropertyValue
name{stack}-{env}
state_key{stack}/{env}
var_filesFrom the environment definition
environment_nameThe environment name (e.g., dev)
environment_orderDeclaration order (0, 1, 2…)
stack_idReference back to the parent stack

Example: Different Instance Sizes

{
  "name": "webapp",
  "environments": [
    {
      "name": "dev",
      "var_files": ["env/dev.tfvars"]
    },
    {
      "name": "prod",
      "var_files": ["env/prod.tfvars", "env/prod-scale.tfvars"]
    }
  ]
}

With dev.tfvars:

instance_type = "t3.micro"
min_count     = 1
max_count     = 2

And prod.tfvars:

instance_type = "m5.xlarge"
min_count     = 3
max_count     = 10