# Repo Level atlantis.yaml Config

An atlantis.yaml file specified at the root of a Terraform repo allows you to instruct Atlantis on the structure of your repo and set custom workflows.

# Do I need an atlantis.yaml file?

atlantis.yaml files are only required if you wish to customize some aspect of Atlantis. The default Atlantis config works for many users without changes.

Read through the use-cases to determine if you need it.

# Enabling atlantis.yaml

By default, all repos are allowed to have an atlantis.yaml file, but some of the keys are restricted by default.

Restricted keys can be set in the server-side repos.yaml repo config file. You can enable atlantis.yaml to override restricted keys by setting the allowed_overrides key there. See the Server Side Repo Config for more details.

Notes

• atlantis.yaml files must be placed at the root of the repo
• The only supported name is atlantis.yaml. Not atlantis.yml or .atlantis.yaml.

# Example Using All Keys

version: 3
automerge: true
delete_source_branch_on_merge: true
parallel_plan: true
parallel_apply: true
projects:
- name: my-project-name
  branch: /main/
  dir: .
  workspace: default
  terraform_version: v0.11.0
  delete_source_branch_on_merge: true
  repo_locking: true
  autoplan:
    when_modified: ["*.tf", "../modules/**/*.tf"]
    enabled: true
  apply_requirements: [mergeable, approved]
  workflow: myworkflow
workflows:
  myworkflow:
    plan:
      steps:
      - run: my-custom-command arg1 arg2
      - init
      - plan:
          extra_args: ["-lock", "false"]
      - run: my-custom-command arg1 arg2
    apply:
      steps:
      - run: echo hi
      - apply
allowed_regexp_prefixes:
- dev/
- staging/

# Auto generate projects

This is useful if you have many projects in a repository. This assumes the default workspace (or no workspace).

Run this in the root of your repository. This will use gnu grep to search terraform files for an S3 backend (terraform dir), retrieve the directory path, retrieve the unique entries, and then use yq to return the YAML of a simple project dir setup which can then be modified to your liking.

grep -P 'backend[\s]+"s3"' **/*.tf |
  rev | cut -d'/' -f2- | rev |
  sort |
  uniq |
  while read d; do \
    echo '[ {"name": "'"$d"'","dir": "'"$d"'", "autoplan": {"when_modified": ["**/*.tf.*"] }} ]' | yq -PM; \
  done

# Use Cases

# Disabling Autoplanning

version: 3
projects:
- dir: project1
  autoplan:
    enabled: false

This will stop Atlantis automatically running plan when project1/ is updated in a pull request.

# Run plans and applies in parallel

version: 3
parallel_plan: true
parallel_apply: true

This will run plans and applies for all of your projects in parallel.

Enabling these options can significantly reduce the duration of plans and applies, especially for repositories with many projects.

Use the --parallel-pool-size to configure the max number of plans and applies that can run in parallel. The default is 15.

Parallel plans and applies work across both multiple directories and multiple workspaces.

# Configuring Planning

Given the directory structure:

.
├── modules
│   └── module1
│       ├── main.tf
│       ├── outputs.tf
│       └── submodule
│           ├── main.tf
│           └── outputs.tf
└── project1
    └── main.tf

If you want Atlantis to plan project1/ whenever any .tf files under module1/ change or any .tf or .tfvars files under project1/ change you could use the following configuration:

version: 3
projects:
- dir: project1
  autoplan:
    when_modified: ["../modules/**/*.tf", "*.tf*"]

Note:

• when_modified uses the .dockerignore syntax
• The paths are relative to the project's directory.
• when_modified will be used by both automatic and manually run plans.
• when_modified will continue to work for manually run plans even when autoplan is disabled.

# Supporting Terraform Workspaces

version: 3
projects:
- dir: project1
  workspace: staging
- dir: project1
  workspace: production

With the above config, when Atlantis determines that the configuration for the project1 dir has changed, it will run plan for both the staging and production workspaces.

If you want to plan or apply for a specific workspace you can use

atlantis plan -w staging -d project1

and

atlantis apply -w staging -d project1

# Using .tfvars files

See Custom Workflow Use Cases: Using .tfvars files

# Adding extra arguments to Terraform commands

See Custom Workflow Use Cases: Adding extra arguments to Terraform commands

# Custom init/plan/apply Commands

See Custom Workflow Use Cases: Custom init/plan/apply Commands

# Terragrunt

See Custom Workflow Use Cases: Terragrunt

# Running custom commands

See Custom Workflow Use Cases: Running custom commands

# Terraform Versions

If you'd like to use a different version of Terraform than what is in Atlantis' PATH or is set by the --default-tf-version flag, then set the terraform_version key:

version: 3
projects:
- dir: project1
  terraform_version: 0.10.0

Atlantis will automatically download and use this version.

# Requiring Approvals For Production

In this example, we only want to require apply approvals for the production directory.

version: 3
projects:
- dir: staging
- dir: production
  apply_requirements: [approved]

# Order of planning/applying

version: 3
projects:
- dir: project1
  execution_order_group: 2
- dir: project2
  execution_order_group: 1

With this config above, Atlantis runs planning/applying for project2 first, then for project1. Several projects can have same execution_order_group. Any order in one group isn't guaranteed. parallel_plan and parallel_apply respect these order groups, so parallel planning/applying works in each group one by one.

# Custom Backend Config

See Custom Workflow Use Cases: Custom Backend Config

# Reference

# Top-Level Keys

version: 3
automerge: false
delete_source_branch_on_merge: false
projects:
workflows:
allowed_regexp_prefixes:

# Project

name: myname
branch: /mybranch/
dir: mydir
workspace: myworkspace
execution_order_group: 0
delete_source_branch_on_merge: false
repo_locking: true
autoplan:
terraform_version: 0.11.0
apply_requirements: ["approved"]
workflow: myworkflow

# Autoplan

enabled: true
when_modified: ["*.tf", "terragrunt.hcl"]