---
name: stack-dependencies
status: active
since: "1.0.1"
---

import Since from '@components/Since.astro';
import Before from '@components/Before.astro';
import { Aside } from '@astrojs/starlight/components';

Support for the `autoinclude` block in `terragrunt.stack.hcl` files, enabling dependency relationships and configuration overrides during stack generation.

### `stack-dependencies` - What it does
When enabled, this experiment adds support for the `autoinclude` block nested inside `unit` and `stack` blocks in `terragrunt.stack.hcl` files. The `autoinclude` block allows users to define `dependency` blocks and arbitrary configuration that gets generated into an autoinclude file during stack generation. This file is automatically merged into the unit/stack configuration when parsed.

The generated filename depends on the component kind:

- **Unit autoincludes** are written as `terragrunt.autoinclude.hcl` next to the unit's `terragrunt.hcl`.
- **Stack autoincludes** are written as `terragrunt.autoinclude.stack.hcl` next to the nested stack's `terragrunt.stack.hcl`. The `.stack.hcl` suffix mirrors `terragrunt.stack.hcl` so tooling (LSP, `read_terragrunt_config()`, indexers) can identify the file's purpose from its name alone.

This experiment enables:

- **`unit.<name>.path`** and **`stack.<name>.path`** variables in `terragrunt.stack.hcl` for referencing sibling component paths
- **`stack.<name>.<unit_name>.path`** for referencing individual units within a nested stack (fine-grained dependency)
- **`dependency` blocks targeting stack directories** — aggregated outputs from all units in the stack (`dependency.stack_name.outputs.unit_name.output_key`)
- **Automatic deep merge** of `terragrunt.autoinclude.hcl` into unit configurations (autoinclude wins)
- **Stack dependency expansion** in the run queue — depending on a stack blocks until all its units complete

#### Unit-to-unit dependencies within a stack

```hcl
# terragrunt.stack.hcl
unit "vpc" {
  source = "../catalog/units/vpc"
  path   = "vpc"
}

unit "app" {
  source = "../catalog/units/app"
  path   = "app"

  autoinclude {
    dependency "vpc" {
      config_path = unit.vpc.path
    }

    inputs = {
      vpc_id = dependency.vpc.outputs.vpc_id
    }
  }
}
```

#### Dependencies on units within a nested stack

```hcl
# terragrunt.stack.hcl
stack "stack_w_outputs" {
  source = "../catalog/stacks/stack-w-outputs"
  path   = "stack-w-outputs"
}

unit "unit_w_inputs" {
  source = "../catalog/units/unit-w-inputs"
  path   = "unit-w-inputs"

  autoinclude {
    dependency "unit_w_outputs" {
      config_path = stack.stack_w_outputs.unit_w_outputs.path

      mock_outputs_allowed_terraform_commands = ["plan"]
      mock_outputs = {
        val = "fake-val"
      }
    }

    inputs = {
      val = dependency.unit_w_outputs.outputs.val
    }
  }
}
```

#### Dependencies on entire stacks

```hcl
# terragrunt.stack.hcl
stack "infra" {
  source = "../catalog/stacks/infra"
  path   = "infra"
}

unit "app" {
  source = "../catalog/units/app"
  path   = "app"

  autoinclude {
    dependency "infra" {
      config_path = stack.infra.path
    }

    inputs = {
      vpc_id = dependency.infra.outputs.vpc.vpc_id
    }
  }
}
```

```bash
terragrunt run --all --experiment stack-dependencies -- plan
```

### `stack-dependencies` - How to provide feedback
Provide your feedback on the [Stack Dependencies RFC](https://github.com/gruntwork-io/terragrunt/issues/5663) GitHub Issue.

### `stack-dependencies` - Implementation roadmap

<Before version="1.0.2">

- [ ] Create `internal/hclparse` package with two-phase stack file parser and autoinclude data structures
- [ ] Implement `terragrunt.autoinclude.hcl` file generator with relative path resolution
- [ ] Implement AST-walking partial evaluator for mixed `local.*` + `dependency.*` expressions
- [ ] Integrate autoinclude parsing and generation into `pkg/config/stack.go` stack generation pipeline
- [ ] Auto-merge `terragrunt.autoinclude.hcl` into unit config during `ParseConfig()` with deep merge
- [ ] Add `tryGetStackOutput()` for dependency blocks targeting stack directories
- [ ] Add `ExtractAutoIncludeDependencyPaths()` so DAG sees dependencies from autoinclude files
- [ ] Add integration tests and test fixtures for end-to-end validation
- [ ] E2E validation with `stack run apply` and `stack run destroy`
- [ ] Community feedback on `autoinclude` syntax and merge behavior
- [ ] Integration with CAS for generated files
- [ ] Performance validation at scale

</Before>

<Since version="1.0.2">

- [x] Create `internal/hclparse` package with two-phase stack file parser and autoinclude data structures
- [x] Implement `terragrunt.autoinclude.hcl` file generator with relative path resolution
- [x] Implement AST-walking partial evaluator for mixed `local.*` + `dependency.*` expressions
- [x] Integrate autoinclude parsing and generation into `pkg/config/stack.go` stack generation pipeline
- [x] Auto-merge `terragrunt.autoinclude.hcl` into unit config during `ParseConfig()` with deep merge
- [x] Add `tryGetStackOutput()` for dependency blocks targeting stack directories
- [x] Add `ExtractAutoIncludeDependencyPaths()` so DAG sees dependencies from autoinclude files
- [ ] Add integration tests and test fixtures for end-to-end validation
- [ ] E2E validation with `stack run apply` and `stack run destroy`
- [ ] Community feedback on `autoinclude` syntax and merge behavior
- [ ] Integration with CAS for generated files
- [ ] Performance validation at scale

</Since>

<Since version="1.0.4">

- [x] Create `internal/hclparse` package with two-phase stack file parser and autoinclude data structures
- [x] Implement `terragrunt.autoinclude.hcl` file generator with relative path resolution
- [x] Implement AST-walking partial evaluator for mixed `local.*` + `dependency.*` expressions
- [x] Integrate autoinclude parsing and generation into `pkg/config/stack.go` stack generation pipeline
- [x] Auto-merge `terragrunt.autoinclude.hcl` into unit config during `ParseConfig()` with deep merge
- [x] Add `tryGetStackOutput()` for dependency blocks targeting stack directories
- [x] Add `ExtractAutoIncludeDependencyPaths()` so DAG sees dependencies from autoinclude files
- [x] Add integration tests and test fixtures for end-to-end validation
- [x] E2E validation with `stack run apply` and `stack run destroy`
- [x] Resolve `stack.<name>.<nested_stack>.path` at arbitrary nesting depth
- [x] Surface autoinclude dependencies in `terragrunt find` and `terragrunt list` (JSON, tree, and long formats)
- [x] Use distinct filenames for unit (`terragrunt.autoinclude.hcl`) and stack (`terragrunt.autoinclude.stack.hcl`) autoincludes
- [ ] Community feedback on `autoinclude` syntax and merge behavior
- [ ] Integration with CAS for generated files
- [ ] Performance validation at scale

</Since>
