atlantis.yaml & projects

Multi-directory, multi-workspace repos.

Advanced14 min · lesson 5 of 12

Real repos are not a single Terraform directory — they have many projects (a vpc dir, a database dir, per-environment folders), possibly with workspaces. An atlantis.yaml in the repo root tells Atlantis how to handle them: it defines projects (each a directory + workspace + optional terraform version) and how to autoplan them. Without it, Atlantis uses defaults; with it, you get precise control over what runs where.

atlantis.yaml

version: 3
projects:
  - name: prod-vpc
    dir: live/prod/vpc
    workspace: default
    terraform_version: v1.9.2
    autoplan:
      when_modified: ["*.tf", "../../../modules/vpc/**/*.tf"]
      enabled: true
    apply_requirements: [approved, mergeable]
  - name: prod-db
    dir: live/prod/database
    apply_requirements: [approved]

Per-project control

Defining projects lets each one carry its own settings: which files trigger its plan (when_modified — including shared modules, so a module change re-plans dependents), its apply requirements, its Terraform version, and its workflow. This is how a monorepo of infrastructure stays sane — a change to the prod database plans only the prod database, and a change to a shared module plans everything that uses it. The atlantis.yaml is the map of your infrastructure repo.

Repo-side config is powerful — decide what it may override

Because atlantis.yaml lives in the repo, whoever can edit it can change how Atlantis runs — and if custom workflows are allowed from the repo, potentially what commands run with the server’s credentials. Atlantis lets the server operator control which settings a repo’s atlantis.yaml is allowed to set (the server-side config lesson covers this). Lock down repo-side overrides so a PR cannot redefine the apply requirements it must satisfy.

Locking & the apply gateCustom workflows & steps