Reducing CI Blast Radius with Terramate Git-Aware Change Detection

The Monorepo Bottleneck

As infrastructure grows, the common pattern of a single Terraform or OpenTofu monorepo often leads to a critical performance wall: the "everything plan." When every pull request triggers a plan across every module and environment, CI pipelines slow down, API rate limits are hit, and the risk of accidental changes to stable production environments increases.

The solution is to move from a monolithic execution model to a stack-based model where only the modified components—and the components that depend on them—are processed. Terramate achieves this by treating the directory structure as a set of stacks (logical groupings of infrastructure) and using git metadata to isolate changes.

How Stack-Based Change Detection Works

Terramate uses terramate.tm.hcl files to define the configuration and inheritance of your infrastructure. Unlike standard Terraform, which sees a directory as a single state, Terramate views your repository as a graph of interdependent stacks.

When integrated into a CI pipeline, Terramate can analyze the git diff between your current feature branch and the target base branch (for example, main). Instead of running terraform plan globally, the Terramate CLI identifies which .tm.hcl or .tf files changed. It then calculates the blast radius—the specific stack where the change occurred and any downstream stacks that inherit variables or outputs from that changed stack.

Practical Implementation: Targeted CI Execution

To implement this, you shift the responsibility of "what to run" from your CI YAML file to the Terramate CLI. This removes the need for complex shell scripts that manually parse directory names to decide which Terraform folders to enter.

Example Workflow Configuration

Assuming a directory structure where global variables are inherited by prod and staging environments, a change to a global variable should trigger plans for both, while a change to staging should only trigger a staging plan.

# Run this on your CI runner (e.g., GitHub Actions or GitLab Runner)
# Requires: Terramate CLI installed, git configured with fetch-depth 0

# 1. Identify changed stacks based on the git diff against the main branch
# Note: Verify exact flag names via 'terramate run --help' for your version
terramate run --git-diff origin/main terraform plan

Expected behavior:

• If you modified environments/staging/main.tf, Terramate executes the plan only within the staging stack.
• If you modified global/variables.tm.hcl, Terramate detects that prod and staging inherit from this file and executes plans for both.

Required Permissions and Risks

The CI runner must have git installed and the repository must be cloned with enough history (avoid shallow clones or fetch-depth: 1) for the CLI to accurately compare the current HEAD against the base branch. The primary risk is under-detection: if a change is made to a file not tracked by Terramate's dependency graph, that stack may be skipped during the plan phase.

Trade-offs: Granularity vs. Complexity

While git-aware detection solves the speed problem, it introduces a management trade-off. The more granular your stacks are, the faster your CI runs, but the more complex your terramate.tm.hcl inheritance chain becomes.

Strategy	CI Speed	Management Overhead	Blast Radius
Coarse Stacks (Few large folders)	Slow	Low	High
Fine Stacks (Many small folders)	Fast	High	Low

Over-segmenting your infrastructure can lead to "dependency hell," where a single variable change triggers a cascade of plans across dozens of small stacks, effectively returning you to the "everything plan" scenario.

Verifying the Change Set

Before automating this in a production pipeline, you should manually verify which stacks Terramate considers "changed." You can do this by running the list command in your terminal:

# Run locally to see which stacks would be targeted
terramate list --changed

If the output includes stacks that you know are unrelated to your current changes, review your terramate.tm.hcl files for unnecessary inherit blocks or overly broad file patterns.