Managing Multiple Directories in Atlantis Plans

Choosing Monorepos vs multiple repos is still a debate among software professionals. Many large infrastructure teams still choose Monorepos – a single Git repository that houses multiple directories for different parts of the codebase. Configuring Atlantis to plan multiple directories helps isolate each Terraform project, reduce plan noise, and accelerate peer review. However, without proper directory-level configuration, atlantis may still plan the entire repo even when only one directory changes – a workflow issue solved through project-level configuration.

Configuring Multiple Projects for Atlantis Plan Multiple Directories

You configure Atlantis with a projects array in a root-level .atlantis.yamlfile, dividing the repo into discrete projects each tied to a directory or glob:

version: 3
projects:
  - name: dev
    dir: env/dev
    workspace: dev
    terraform_version: v1.8.0
  - name: stage
    dir: env/stage
    workspace: stage
    terraform_version: v1.8.0
  - name: prod
    dir: env/prod
    workspace: prod
    terraform_version: v1.8.0

When a pull request changes files under env/prod, Atlantis matches the path (the directory path) to the prod project and runs atlantis plan effectively a run terraform plan command just for that folder. If nothing changes inside env/dev, no plan is triggered there. Behind the scenes, the Atlantis server computes changed files → matches a dir pattern → executes the plan/apply workflow linked to that project.

How the Atlantis Plan Multiple Directories Workflow Operates in Pull Requests

1. Developer commits a change to env/prod/variables.tf (tf files in the same dir).
2. GitHub PR opens – Atlantis webhook fires. The robust VCS integration shows a pending Atlantis plan check within seconds, confirming the webhook fired and the project scan started.
3. Atlantis inspects the diff, finds only env/prod/** touched. It compares each changed file path against every dir: entry in .atlantis.yaml.

• Matches env/prod – selects the prod project and its specific workspace tied to that terraform dir.
• Ignores env/dev and env/stage projects because no files under those paths have changed.

4. It posts a single status check:

atlantis plan - project: prod
Terraform will perform the following actions...

The check name includes the project to make multi-project PRs readable; the detailed plan output is posted as a comment so reviewers can jump straight to the resource diff.

5. The dev and stage projects stay green and untouched, which keeps the conversation on track. GitHub marks the dev and stage checks as Skipped (no changes), which saves reviewers from having to look at output that isn’t relevant and saves CI time for both the staging and production workflows.

6. Once approved, the reviewer comments atlantis apply -p prod, and Atlantis applies only to the production workspace.

Atlantis:

• First, Atlantis uses reliable Atlantis locks to lock the backend key for prod.
• After that, it runs terraform apply with the plan file it made and then unlocks the lock.

Want to automate and govern your Terraform workflows? Explore ControlMonkey’s Total Automation for full CI/CD visibility.

Scale Your Terraform Automation

Best Practices for Managing Multiple Directories in Atlantis

1. Design a Predictable Directory Layout for Atlantis Plan Multiple Directories

A clean tree is the first guardrail against chaos. Start with a root-level env/ folder and mirror your environments (dev, stage, prod). Beneath each, break out by region or system (us-east-1/network, europe/rds, and so on). Keep reusable code in a top-level modules/ directory and follow Terraform’s standard module structure main.tf, variables.tf, outputs.tf, plus examples/ and a README per module. Group related resources in files like network.tf or instances.tf; don’t scatter one resource per file unless there’s a compelling reason to keep everything in the same dir.

2. Establish Consistent Naming Conventions

Poor names ripple into every plan. A few field-tested rules from the community guide:

• Use underscores, not dashes, for Terraform identifiers.
• Keep names lowercase and avoid repeating the resource type (aws_subnet.public, not aws_subnet.public_subnet).
• Stick to singular nouns and add an environment/region suffix only when it clarifies intent (alb_public_eu, vpc_core_us). These conventions make diffs self-explanatory and reduce refactors when you modularize later.

3. Isolate & Lock State Per Project

Every Atlantis project should map to a unique backend key (for example, prod/network/terraform.tfstate) so that no two directories can overwrite each other. Store remote terraform state in an S3 bucket or equivalent, enable DynamoDB locking, and never share the same workspace across projects.

 The AWS prescriptive guide shows why atlantis locks and separate state files protect multiple states during parallel applies.

4. Harden Your Atlantis Plan Multiple Directories Workflows

• Autoplan scopes – Define explicit when_modified glob patterns so only the touched directory triggers a plan.
• Apply safeguards – Add apply_requirements: [approved, mergeable] to ensure peer review.
• Concurrency limits – Use workflows:<name>:plan:steps with run: atlantis plan -p $PROJECT -- -lock-timeout=300s if you expect long-running operations.
• Full-repo catch-up – For occasional drift sweeps, teams enable the plan-all flag to run terraform plan across every directory without extra commits. These settings rely on core atlantis commands and familiar terraform commands like init, plan, and apply, letting teams run plan jobs confidently. Atlantis works best when its workflows are explicit and repeatable.

5. Branch & Review Hygiene

Make a new branch for each environment change. Don’t make omnibus PRs that affect both dev and prod at the same time. Before merging, you need green Atlantis checks, and you can’t push directly to main. This strict VCS integration makes it easy to check and roll back your CI/CD timeline.

6. Automate Validation & Testing

Set up pre-commit hooks for terraform fmt, tflint, and terraform validate. Add unit tests with Terratest or OpenTofu for important modules. Quick local feedback helps developers find syntax and policy mistakes long before Atlantis starts a costly cloud plan. This keeps automation running smoothly and protects dependencies that come after.

Conclusion: Streamline Atlantis Plan Multiple Directories with ControlMonkey

Setting up multiple directories in Atlantis is less about YAML syntax and more about guardrails, such as having a clear repo layout, strict state isolation, and planning only what has changed. 

Ready to streamline Atlantis plan multiple directories with ControlMonkey’s automation

How Do We Compare