atlantis/runatlantis.io/docs/atlantis-yaml-reference.md

atlantis.yaml Reference

toc

::: tip Do I need an atlantis.yaml file? atlantis.yaml files are only required if you wish to customize some aspect of Atlantis. :::

::: tip Where are the example use cases? See www.runatlantis.io/guide/atlantis-yaml-use-cases.html :::

Enabling atlantis.yaml

The atlantis server must be running with --allow-repo-config to allow Atlantis to use atlantis.yaml files.

Example Using All Keys

version: 2
automerge: true
projects:
- name: my-project-name
  dir: .
  workspace: default
  terraform_version: v0.11.0
  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

Usage 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.
• Once an atlantis.yaml file exists in a repo, Atlantis won't try to determine where to run plan automatically. Instead it will just follow the configuration. This means that you'll need to define each project in your repo.
• Atlantis uses the atlantis.yaml version from the pull request.

Security

atlantis.yaml files allow users to run arbitrary code on the Atlantis server. This is obviously extremely powerful and dangerous since the Atlantis server will likely hold your highest privilege credentials.

The risk is increased because Atlantis uses the atlantis.yaml file from the pull request so anyone that can submit a pull request can submit a malicious file.

As such, atlantis.yaml files should only be enabled in a trusted environment.

::: danger It should be noted that atlantis apply itself could be exploited if run on a malicious terraform file. See Security. :::

Reference

Top-Level Keys

version:
automerge:
projects:
workflows:

Key	Type	Default	Required	Description
version	int	none	yes	This key is required and must be set to 2
automerge	bool	false	no	Automatically merge pull request when all plans are applied
projects	array[Project]	[]	no	Lists the projects in this repo
workflows	map[string -> Workflow]	{}	no	Custom workflows

Project

name: myname
dir: mydir
workspace: myworkspace
autoplan:
terraform_version: 0.11.0
apply_requirements: ["approved"]
workflow: myworkflow

Key	Type	Default	Required	Description
name	string	none	maybe	Required if there is more than one project with the same dir and workspace. This project name can be used with the -p flag.
dir	string	none	yes	The directory of this project relative to the repo root. Use . for the root. For example if the project was under ./project1 then use project1
workspace	string	default	no	The Terraform workspace for this project. Atlantis will switch to this workplace when planning/applying and will create it if it doesn't exist.
autoplan	Autoplan	none	no	A custom autoplan configuration. If not specified, will use the default algorithm. See Autoplanning.
terraform_version	string	none	no	A specific Terraform version to use when running commands for this project. Requires there to be a binary in the Atlantis PATH with the name terraform{VERSION}, ex. terraform0.11.0
apply_requirements	array[string]	[]	no	Requirements that must be satisfied before atlantis apply can be run. Currently the only supported requirements are approved and mergeable. See Apply Requirements for more details.
workflow	string	none	no	A custom workflow. If not specified, Atlantis will use its default workflow.

::: tip A project represents a Terraform state. Typically, there is one state per directory and workspace however it's possible to have multiple states in the same directory using terraform init -backend-config=custom-config.tfvars. Atlantis supports this but requires the name key to be specified. See atlantis.yaml Use Cases for more details. :::

Autoplan

enabled: true
when_modified: ["*.tf"]

Key	Type	Default	Required	Description
enabled	boolean	true	no	Whether autoplanning is enabled for this project.
when_modified	array[string]	no	no	Uses .dockerignore syntax. If any modified file in the pull request matches, this project will be planned. If not specified, Atlantis will use its own algorithm. See Autoplanning. Paths are relative to the project's dir.

Workflow

plan:
apply:

Key	Type	Default	Required	Description
plan	Stage	steps: [init, plan]	no	How to plan for this project.
apply	Stage	steps: [apply]	no	How to apply for this project.

Stage

steps:
- run: custom-command
- init
- plan:
    extra_args: [-lock=false]

Key	Type	Default	Required	Description
steps	array[Step]	[]	no	List of steps for this stage. If the steps key is empty, no steps will be run for this stage.

Step

Built-In Commands: init, plan, apply

Steps can be a single string for a built-in command.

- init
- plan
- apply

Key	Type	Default	Required	Description
init/plan/apply	string	none	no	Use a built-in command without additional configuration. Only init, plan and apply are supported

Built-In Command With Extra Args

A map from string to extra_args for a built-in command with extra arguments.

- init:
    extra_args: [arg1, arg2]
- plan:
    extra_args: [arg1, arg2]
- apply:
    extra_args: [arg1, arg2]

Key	Type	Default	Required	Description
init/plan/apply	map[extra_args -> array[string]]	none	no	Use a built-in command and append extra_args. Only init, plan and apply are supported as keys and only extra_args is supported as a value

Custom run Command

Or a custom command

- run: custom-command

Key	Type	Default	Required	Description
run	string	none	no	Run a custom command

::: tip run steps are executed with the following environment variables:

• WORKSPACE - The Terraform workspace used for this project, ex. default.
  • NOTE: if the step is executed before init then Atlantis won't have switched to this workspace yet.
• ATLANTIS_TERRAFORM_VERSION - The version of Terraform used for this project, ex. 0.11.0.
• DIR - Absolute path to the current directory.
• PLANFILE - Absolute path to the location where Atlantis expects the plan to either be generated (by plan) or already exist (if running apply). Can be used to override the built-in plan/apply commands, ex. run: terraform plan -out $PLANFILE.
• BASE_REPO_NAME - Name of the repository that the pull request will be merged into, ex. atlantis.
• BASE_REPO_OWNER - Owner of the repository that the pull request will be merged into, ex. runatlantis.
• HEAD_REPO_NAME - Name of the repository that is getting merged into the base repository, ex. atlantis.
• HEAD_REPO_OWNER - Owner of the repository that is getting merged into the base repository, ex. acme-corp.
• HEAD_BRANCH_NAME - Name of the head branch of the pull request (the branch that is getting merged into the base)
• BASE_BRANCH_NAME - Name of the base branch of the pull request (the branch that the pull request is getting merged into)
• PULL_NUM - Pull request number or ID, ex. 2.
• PULL_AUTHOR - Username of the pull request author, ex. acme-user.
• USER_NAME - Username of the VCS user running command, ex. acme-user. During an autoplan, the user will be the Atlantis API user, ex. atlantis. :::

::: tip Note that a custom command will only terminate if all output file descriptors are closed. Therefore a custom command can only be sent to the background (e.g. for an SSH tunnel during the terraform run) when its output is redirected to a different location. For example, atlantis will execute a custom script containing the following code to create a SSH tunnel correctly: ssh -f -M -S /tmp/ssh_tunnel -L 3306:database:3306 -N bastion 1>/dev/null 2>&1. Without the pipe, the script would block the atlantis workflow. :::

Next Steps

Check out the atlantis.yaml Use Cases for some real world examples.