Speed Up Terraform Runs with Terramate’s Change Detection

Problem: Wasting Time on Unchanged Terraform Stacks

When a repository holds many Terraform stacks, a typical CI pipeline runs terraform apply on every stack, even if only one folder changed. This wastes compute time and increases the chance of unintended side‑effects.

How Terramate’s Change Detection Works

Terramate scans the git history between the current HEAD and the previous commit. For each stack defined in a terramate.hcl file, it checks whether any file inside the stack’s directory (or a referenced module) differs. If a difference exists, the stack is marked as “changed”. The command terramate list --changed outputs exactly those stack names.

Because the detection relies solely on committed changes, it works with any git provider and needs no extra state store.

Running Only Changed Stacks in a CI Pipeline

In a CI job you can gate Terraform execution on the list returned by Terramate:

# Fetch the list of changed stacks (requires read access to the repo)
CHANGED_STACKS=$(terramate list --changed --format json | jq -r '.[]')

# Iterate and run Terraform only on those stacks
for stack in $CHANGED_STACKS; do
  echo "Processing $stack"
  terramate run --dir $stack -- terraform init
  terramate run --dir $stack -- terraform apply -auto-approve
 done

If CHANGED_STACKS is empty, the loop skips entirely, saving the pipeline from unnecessary work.

Worked Example: Updating a Variable File

1. Start with a clean repo where two stacks exist: stacks/network and stacks/app. Each has its own terramate.hcl.
2. Edit stacks/network/variables.tf to add a new variable.
3. Commit the change: git add stacks/network/variables.tf && git commit -m "add variable".
4. Run detection: terramate list --changed outputs something like:

   stacks/network
   

5. Apply only that stack: terramate run --changed -- terraform apply -auto-approve triggers Terraform only for stacks/network; stacks/app is untouched.
6. Revert the commit (git reset --hard HEAD~1) and run the same command again; the list is empty, confirming no false positives.

Trade‑off and Limitations

The detection is blind to uncommitted work. If you stage a change with git add but do not commit, Terramate will ignore it, potentially causing a drift between what you expect to apply and what actually runs. To avoid this, commit changes before invoking Terramate, or use a pre‑commit hook that runs terramate run --changed on the staged snapshot.

Additionally, the algorithm assumes that each stack’s files live inside the directory declared in its terramate.hcl. Moving a file outside that directory without updating the Terramate configuration leads to a false negative—the change will not be detected.

Actionable Checklist

• Add terramate list --changed to your CI script to obtain the set of stacks to process.
• Wrap Terraform commands in terramate run --changed so they execute only on the returned list.
• Verify locally: make a committed change, run the detection command, and confirm the output matches the edited stack.
• After reverting the change, run the detection again and ensure the list is empty.
• If you work with uncommitted changes, commit them first or adjust your workflow to snapshot the index before detection.