terramate-atlantis-config

README

terramate-atlantis-config

Generates atlantis.yaml from your Terramate stacks.

Before you begin

You need:

• Terramate installed and a repo with at least one stack
• Atlantis set up to consume atlantis.yaml
• Go 1.25+ (if installing from source)

This tool reads your Terramate stack definitions and git history. It does not run Terraform or modify any stack files.

Install

Go install:

go install github.com/devops-roast/terramate-atlantis-config@latest

Homebrew:

brew install --cask devops-roast/tap/terramate-atlantis-config

Binary download: grab the latest from GitHub Releases and put it on your PATH.

From source:

git clone https://github.com/devops-roast/terramate-atlantis-config.git
cd terramate-atlantis-config
make install

Getting started

Run this from your repo root:

terramate-atlantis-config generate --root . --output atlantis.yaml

# Generated by terramate-atlantis-config. DO NOT EDIT.
version: 3
automerge: false
parallel_plan: true
parallel_apply: true
projects:
    - name: aws-production-vpc
      dir: stacks/aws/production/vpc
      autoplan:
        enabled: true
        when_modified:
            - '*.tf'
            - '*.tf.json'
            - .terraform.lock.hcl

Configuration reference

Config file

Place .terramate-atlantis.yaml in your repo root. CLI flags override config file values.

output: atlantis.yaml
workflow: terramate
autoplan: true
parallel: true
project_name_strategy: last-n
project_name_depth: 2
apply_requirements:
  - approved
  - mergeable
when_modified:
  - "*.tf"
  - "*.tf.json"
  - ".terraform.lock.hcl"
tag_workflows:
  production: prod-workflow
  staging: staging-workflow
workflows:
  prod-workflow:
    plan:
      steps:
        - run: terramate run -- terraform init -input=false
        - run: terramate run -- terraform plan -input=false -out=$PLANFILE
    apply:
      steps:
        - run: terramate run -- terraform apply $PLANFILE

CLI flags

Output

Flag	Default	Description
--root	.	Root directory to search for stacks
--output	stdout	Output file path
--format	yaml	Output format: yaml or json
--no-header	false	Omit the generated-by header comment
--config		Path to config file

Filtering

Flag	Default	Description
--filter		Include only stacks matching this tag filter
--filter-path		Include only stacks under this path
--exclude-tags		Exclude stacks with these tags
--exclude-path		Exclude stacks under this path

Naming

Flag	Default	Description
--create-project-name	true	Generate a project name from the stack path
--project-name-strategy	auto-strip	Naming strategy: auto-strip, stack-name, last-n, full
--project-name-prefix		Strip this prefix from stack paths when generating names
--project-name-depth	3	Number of trailing path segments for last-n strategy
--create-workspace	false	Set workspace from stack path
--sort-by	dir	Sort projects by this field

Dependencies

Flag	Default	Description
--execution-order-groups	false	Add execution order groups from stack dependencies
--depends-on	false	Add depends_on from stack dependencies

Workflows

Flag	Default	Description
--autoplan	true	Enable autoplan for all projects
--parallel	true	Enable parallel plan and apply
--automerge	false	Enable automerge in atlantis.yaml
--workflow		Default workflow name for all projects
--terraform-version		Default Terraform version for all projects
--when-modified	*.tf, *.tf.json, .terraform.lock.hcl	File patterns that trigger autoplan
--apply-requirements		Apply requirements for all projects
--tag-workflow		Map stack tags to workflows
--tag-requirements		Map stack tags to apply requirements
--preserve-workflows	false	Keep existing workflow blocks from current atlantis.yaml
--generate-workflows	false	Auto-generate workflow blocks wrapping terraform in terramate run
--workflow-terramate-wrap	true	Wrap terraform commands with terramate run in generated workflows

CI modes

Flag	Default	Description
--changed	false	Only include stacks changed vs base ref
--changed-base-ref	main	Git ref to compare against for change detection
--check	false	Exit non-zero if the output would change
--diff	false	Print a unified diff of current vs generated output

Per-stack globals

Set Terramate globals in any stack to override defaults for that project.

Global	Type	Description
atlantis_skip	bool	Skip this stack entirely
atlantis_workflow	string	Override workflow for this stack
atlantis_autoplan	bool	Override autoplan enabled/disabled
atlantis_terraform_version	string	Override Terraform version
atlantis_when_modified	list(string)	Override when_modified patterns
atlantis_extra_deps	list(string)	Additional when_modified entries merged with defaults
atlantis_apply_requirements	list(string)	Override apply requirements

globals {
  atlantis_workflow          = "production"
  atlantis_terraform_version = "1.5.0"
  atlantis_extra_deps        = ["../modules/**/*.tf"]
}

How it works

1. Stack discovery. The tool walks your repo using the Terramate SDK and collects all stacks, respecting tag filters and path filters you specify.
2. Globals extraction. For each stack, it reads Terramate globals to pick up per-stack overrides (atlantis_workflow, atlantis_skip, etc.).
3. atlantis.yaml generation. It builds the project list, applies your naming strategy, resolves dependency ordering if requested, and writes the output.

Project names are derived from stack paths. Four strategies control the format:

Strategy	Behavior	Example (stacks/aws/prod/eu-west-1/db/billing)
auto-strip	Strips the longest common prefix across all stacks	prod-eu-west-1-db-billing
stack-name	Uses the stack's name field with parent context	eu-west-1-db-billing
last-n	Uses the last N path segments	db-billing (depth=2)
full	Full path, no stripping	stacks-aws-prod-eu-west-1-db-billing

If two stacks would produce the same name, the tool adds parent segments until names are unique.

Recipes

Generate for changed stacks only:

terramate-atlantis-config generate --changed --changed-base-ref main --output atlantis.yaml

Short project names in CI (recommended for PR workflows):

# .terramate-atlantis.yaml
project_name_strategy: last-n
project_name_depth: 2
changed: true

Check atlantis.yaml is up to date in CI:

terramate-atlantis-config generate --output atlantis.yaml --check

Map tags to workflows:

terramate-atlantis-config generate --tag-workflow production=prod-wf,staging=staging-wf

Generate workflows wrapping terramate run:

terramate-atlantis-config generate --generate-workflows --output atlantis.yaml

Strip an explicit path prefix from project names:

terramate-atlantis-config generate --project-name-prefix "stacks/aws"

CI/CD integration

GitHub Actions — fail the build if atlantis.yaml is out of sync:

jobs:
  check-atlantis-config:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: devops-roast/terramate-atlantis-config@v1
        with:
          root: "."
          output: atlantis.yaml
          check: "true"

pre-commit — regenerate on every commit:

repos:
  - repo: https://github.com/devops-roast/terramate-atlantis-config
    rev: v1
    hooks:
      - id: terramate-atlantis-config
        args: [--output, atlantis.yaml]

Development

Prerequisites: Go 1.25, managed via mise.toml.

mise install          # install Go and tooling
make test             # run tests
make lint             # run linters
make build            # build binary
make check            # full CI check (vet + fmt + test)
make help             # list all targets

License

MIT