terramate-atlantis-config

Generate atlantis.yaml from your Terramate stacks.

Description • Install • Getting Started • Configuration • How It Works • Recipes • CI/CD • Contributing • Development

📚 Description

terramate-atlantis-config reads your Terramate stack definitions and git history, then generates an atlantis.yaml configuration file for Atlantis. It's built for teams running Terramate alongside Atlantis who want to stop hand-maintaining project lists as their stack count grows.

Instead of updating atlantis.yaml every time you add, rename, or remove a stack, you run this tool in CI and let it do the bookkeeping. It does not run Terraform or modify any stack files.

✨ Key Features

• Stack discovery via Terramate SDK: walks your repo and collects all stacks, respecting tag and path filters.
• Per-stack overrides via globals: set atlantis_workflow, atlantis_skip, and more directly in any stack's globals block.
• Change detection: pass --changed to only include stacks that differ from a base git ref.
• Dependency tracking and execution ordering: reads Terramate's dependency graph to populate depends_on and execution order groups.
• Configurable project naming with auto-disambiguation: four strategies for deriving project names from stack paths, with automatic collision resolution.
• CI modes: --check exits non-zero if the output would change; --diff prints a unified diff.
• Config file support: store defaults in .terramate-atlantis.yaml at your repo root.
• Pre-commit hook: regenerate on every commit without any extra CI step.

🔧 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

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)

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

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

Tip

Combine --check with --diff to see exactly what changed when the check fails.

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]

Note

The pre-commit hook regenerates atlantis.yaml in place. Stage the updated file as part of your commit or let your CI catch any drift with --check.

🤝 Contributing

Contributions are welcome! To suggest an enhancement, report a bug, or submit a pull request:

• Open a feature request for new functionality.
• Open a bug report if something isn't working as expected.
• Fork the repository, create a feature branch, make your changes and tests, then open a pull request. Please ensure all tests pass and follow the existing code style.

🛠️ Development

1. Fork this project.
2. Install mise.
3. Install the dependencies:

   mise trust
   mise install

4. Make changes and run the tests to make sure everything works. ✅

   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

5. Commit your changes, push them to the repository 🚀, and open a new pull request.

License

MIT