Server Side Config

A Server-Side Config file is used for more groups of server config that can't reasonably be expressed through flags.

One such usecase is to control per-repo behaviour and what users can do in repo-level atlantis.yaml files.

Do I Need A Server-Side Config File?

You do not need a server-side repo config file unless you want to customize some aspect of Atlantis on a per-repo basis.

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

Enabling Server Side Config

To use server side repo config create a config file, ex. repos.yaml, and pass it to the atlantis server command via the --repo-config flag, ex. --repo-config=path/to/repos.yaml.

If you don't wish to write a config file to disk, you can use the --repo-config-json flag or ATLANTIS_REPO_CONFIG_JSON environment variable to specify your config as JSON. See --repo-config-json for an example.

Example Server Side Repo

# repos lists the config for specific repos.
repos:
  # id can either be an exact repo ID or a regex.
  # If using a regex, it must start and end with a slash.
  # Repo ID's are of the form {VCS hostname}/{org}/{repo name}, ex.
  # github.com/runatlantis/atlantis.
- id: /.*/
  # branch is an regex matching pull requests by base branch
  # (the branch the pull request is getting merged into).
  # By default, all branches are matched
  branch: /.*/

  # repo_config_file specifies which repo config file to use for this repo.
  # By default, atlantis.yaml is used.
  repo_config_file: path/to/atlantis.yaml

  # plan_requirements sets the Plan Requirements for all repos that match.
  plan_requirements: [approved, mergeable, undiverged]

  # apply_requirements sets the Apply Requirements for all repos that match.
  apply_requirements: [approved, mergeable, undiverged]

  # import_requirements sets the Import Requirements for all repos that match.
  import_requirements: [approved, mergeable, undiverged]

  # workflow sets the workflow for all repos that match.
  # This workflow must be defined in the workflows section.
  workflow: custom

  # allowed_overrides specifies which keys can be overridden by this repo in
  # its atlantis.yaml file.
  allowed_overrides: [apply_requirements, workflow, delete_source_branch_on_merge, repo_locking]

  # allowed_workflows specifies which workflows the repos that match 
  # are allowed to select.
  allowed_workflows: [custom]

  # allow_custom_workflows defines whether this repo can define its own
  # workflows. If false (default), the repo can only use server-side defined
  # workflows.
  allow_custom_workflows: true

  # delete_source_branch_on_merge defines whether the source branch would be deleted on merge
  # If false (default), the source branch won't be deleted on merge
  delete_source_branch_on_merge: true

  # repo_locking defines whether lock repository when planning.
  # If true (default), atlantis try to get a lock.
  repo_locking: true

  # pre_workflow_hooks defines arbitrary list of scripts to execute before workflow execution.
  pre_workflow_hooks: 
    - run: my-pre-workflow-hook-command arg1
  
  # post_workflow_hooks defines arbitrary list of scripts to execute after workflow execution.
  post_workflow_hooks: 
    - run: my-post-workflow-hook-command arg1

  # id can also be an exact match.
- id: github.com/myorg/specific-repo

# workflows lists server-side custom workflows
workflows:
  custom:
    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

Use Cases

Here are some of the reasons you might want to use a repo config.

Requiring PR Is Approved Before an applicable subcommand

If you want to require that all (or specific) repos must have pull requests approved before Atlantis will allow running apply or import, use the plan_requirements, apply_requirements or import_requirements keys.

For all repos:

# repos.yaml
repos:
- id: /.*/
  plan_requirements: [approved]
  apply_requirements: [approved]
  import_requirements: [approved]

For a specific repo:

# repos.yaml
repos:
- id: github.com/myorg/myrepo
  plan_requirements: [approved]
  apply_requirements: [approved]
  import_requirements: [approved]

See Command Requirements for more details.

Requiring PR Is "Mergeable" Before Apply or Import

If you want to require that all (or specific) repos must have pull requests in a mergeable state before Atlantis will allow running apply or import, use the plan_requirements, apply_requirements or import_requirements keys.

For all repos:

# repos.yaml
repos:
- id: /.*/
  plan_requirements: [mergeable]
  apply_requirements: [mergeable]
  import_requirements: [mergeable]

For a specific repo:

# repos.yaml
repos:
- id: github.com/myorg/myrepo
  plan_requirements: [mergeable]
  apply_requirements: [mergeable]
  import_requirements: [mergeable]

See Command Requirements for more details.

Repos Can Set Their Own Apply an applicable subcommand

If you want all (or specific) repos to be able to override the default apply requirements, use the allowed_overrides key.

To allow all repos to override the default:

# repos.yaml
repos:
- id: /.*/
  # The default will be approved.
  plan_requirements: [approved]
  apply_requirements: [approved]
  import_requirements: [approved]

  # But all repos can set their own using atlantis.yaml
  allowed_overrides: [plan_requirements, apply_requirements, import_requirements]

To allow only a specific repo to override the default:

# repos.yaml
repos:
# Set a default for all repos.
- id: /.*/
  plan_requirements: [approved]
  apply_requirements: [approved]
  import_requirements: [approved]

# Allow a specific repo to override.
- id: github.com/myorg/myrepo
  allowed_overrides: [plan_requirements, apply_requirements, import_requirements]

Then each allowed repo can have an atlantis.yaml file that sets plan_requirements, apply_requirements or import_requirements to an empty array (disabling the requirement).

# atlantis.yaml in the repo root or set repo_config_file in repos.yaml
version: 3
projects:
- dir: .
  plan_requirements: []
  apply_requirements: []
  import_requirements: []

Running Scripts Before Atlantis Workflows

If you want to run scripts that would execute before Atlantis can run default or custom workflows, you can create a pre-workflow-hooks:

repos:
  - id: /.*/
    pre_workflow_hooks:
      - run: my custom command
      - run: |
          my bash script inline

See Pre Workflow Hooks for more details on writing pre workflow hooks.

Running Scripts After Atlantis Workflows

If you want to run scripts that would execute after Atlantis runs default or custom workflows, you can create a post-workflow-hooks:

repos:
  - id: /.*/
    post_workflow_hooks:
      - run: my custom command
      - run: |
          my bash script inline

See Post Workflow Hooks for more details on writing post workflow hooks.

Change The Default Atlantis Workflow

If you want to change the default commands that Atlantis runs during plan and apply phases, you can create a new workflow.

If you want to use that workflow by default for all repos, use the workflow key default:

# repos.yaml
# NOTE: the repos key is not required.
workflows:
  # It's important that this is "default".
  default:
    plan:
      steps:
      - init
      - run: my custom plan command
    apply:
      steps:
      - run: my custom apply command

See Custom Workflows for more details on writing custom workflows.

Allow Repos To Choose A Server-Side Workflow

If you want repos to be able to choose their own workflows that are defined in the server-side repo config, you need to create the workflows server-side and then allow each repo to override the workflow key:

# repos.yaml
# Allow repos to override the workflow key.
repos:
- id: /.*/
  allowed_overrides: [workflow]

# Define your custom workflows.
workflows:
  custom1:
    plan:
      steps:
      - init
      - run: my custom plan command
    apply:
      steps:
      - run: my custom apply command

  custom2:
    plan:
      steps:
      - run: another custom command
    apply:
      steps:
      - run: another custom command

Or, if you want to restrict what workflows each repo has access to, use the allowed_workflows key:

# repos.yaml
# Restrict which workflows repos can select.
repos:
- id: /.*/
  allowed_overrides: [workflow]

- id: /my_repo/
  allowed_overrides: [workflow]
  allowed_workflows: [custom1]

# Define your custom workflows.
workflows:
  custom1:
    plan:
      steps:
      - init
      - run: my custom plan command
    apply:
      steps:
      - run: my custom apply command

  custom2:
    plan:
      steps:
      - run: another custom command
    apply:
      steps:
      - run: another custom command

Then each allowed repo can choose one of the workflows in their atlantis.yaml files:

# atlantis.yaml
version: 3
projects:
- dir: .
  workflow: custom1 # could also be custom2 OR default

NOTE

There is always a workflow named default that corresponds to Atlantis' default workflow unless you've created your own server-side workflow with that key (overriding it).

See Custom Workflows for more details on writing custom workflows.

Allow Repos To Define Their Own Workflows

If you want repos to be able to define their own workflows you need to allow them to override the workflow key and set allow_custom_workflows to true.

DANGER

If repos can define their own workflows, then anyone that can create a pull request to that repo can essentially run arbitrary code on your Atlantis server.

# repos.yaml
repos:
- id: /.*/

  # With just allowed_overrides: [workflow], repos can only
  # choose workflows defined server-side.
  allowed_overrides: [workflow]

  # By setting allow_custom_workflows to true, we allow repos to also
  # define their own workflows.
  allow_custom_workflows: true

Then each allowed repo can define and use a custom workflow in their atlantis.yaml files:

# atlantis.yaml
version: 3
projects:
- dir: .
  workflow: custom1
workflows:
  custom1:
    plan:
      steps:
      - init
      - run: my custom plan command
    apply:
      steps:
      - run: my custom apply command

See Custom Workflows for more details on writing custom workflows.

Multiple Atlantis Servers Handle The Same Repository

Running multiple Atlantis servers to handle the same repository can be done to separate permissions for each Atlantis server. In this case, a different atlantis.yaml repository config file can be used by using different repos.yaml files.

For example, consider a situation where a separate production-server atlantis uses repo config atlantis-production.yaml and staging-server atlantis uses repo config atlantis-staging.yaml.

Firstly, deploy 2 Atlantis servers, production-server and staging-server. Each server has different permissions and a different repos.yaml file. The repos.yaml contains repo_config_file key to specify the repository atlantis config file path.

# repos.yaml
repos:
- id: /.*/
  # for production-server
  repo_config_file: atlantis-production.yaml
  # for staging-server
  # repo_config_file: atlantis-staging.yaml

Then, create atlantis-production.yaml and atlantis-staging.yaml files in the repository. See the configuration examples in atlantis.yaml.

# atlantis-production.yaml
version: 3
projects:
- name: project
  branch: /production/
  dir: infrastructure/production
---
# atlantis-staging.yaml
version: 3
projects:
  - name: project
    branch: /staging/
    dir: infrastructure/staging

Now, 2 webhook URLs can be setup for the repository, which send events to production-server and staging-server respectively. Each servers handle different repository config files.

Notes

  • If no projects comments are annoying, set --silence-no-projects.
  • The command trigger executable name can be reconfigured from atlantis to something else by setting Executable Name.
  • When using different atlantis server vcs users such as @atlantis-staging, the comment @atlantis-staging plan can be used instead atlantis plan to call staging-server only.

Reference

Top-Level Keys

KeyTypeDefaultRequiredDescription
reposarray[Repo]see belownoList of repos to apply settings to.
workflowsmap[string: Workflow]see belownoMap from workflow name to workflow. Workflows override the default Atlantis commands.
policiesPolicies.nonenoList of policy sets to run and associated metadata

A Note On Defaults

repos

repos always contains a first element with the Atlantis default config:

repos:
- id: /.*/
  branch: /.*/
  plan_requirements: []
  apply_requirements: []
  import_requirements: []
  workflow: default
  allowed_overrides: []
  allow_custom_workflows: false

workflows

workflows always contains the Atlantis default workflow under the key default:

workflows:
  default:
    plan:
      steps: [init, plan]
    apply:
      steps: [apply]

This gets merged with whatever config you write. If you set a workflow with the key default, it will override this.

Repo

KeyTypeDefaultRequiredDescription
idstringnoneyesValue can be a regular expression when specified as /<regex>/ or an exact string match. Repo IDs are of the form {vcs hostname}/{org}/{name}, ex. github.com/owner/repo. Hostname is specified without scheme or port. For Bitbucket Server, {org} is the name of the project, not the key.
branchstringnonenoAn regex matching pull requests by base branch (the branch the pull request is getting merged into). By default, all branches are matched
repo_config_filestringnonenoRepo config file path in this repo. By default, use atlantis.yaml which is located on repository root. When multiple atlantis servers work with the same repo, please set different file names.
workflowstringnonenoA custom workflow.
plan_requirements[]stringnonenoRequirements that must be satisfied before atlantis plan can be run. Currently the only supported requirements are approved, mergeable, and undiverged. See Command Requirements for more details.
apply_requirements[]stringnonenoRequirements that must be satisfied before atlantis apply can be run. Currently the only supported requirements are approved, mergeable, and undiverged. See Command Requirements for more details.
import_requirements[]stringnonenoRequirements that must be satisfied before atlantis import can be run. Currently the only supported requirements are approved, mergeable, and undiverged. See Command Requirements for more details.
allowed_overrides[]stringnonenoA list of restricted keys that atlantis.yaml files can override. The only supported keys are apply_requirements, workflow, delete_source_branch_on_merge and repo_locking
allowed_workflows[]stringnonenoA list of workflows that atlantis.yaml files can select from.
allow_custom_workflowsboolfalsenoWhether or not to allow Custom Workflows.
delete_source_branch_on_mergeboolfalsenoWhether or not to delete the source branch on merge.
repo_lockingboolfalsenoWhether or not to get a lock

Notes

  • If multiple repos match, the last match will apply.

  • If a key isn't defined, it won't override a key that matched from above. For example, given a repo ID github.com/owner/repo and a config:

    repos:
    - id: /.*/
      allow_custom_workflows: true
      apply_requirements: [approved]
    - id: github.com/owner/repo
      apply_requirements: []
    

    The final config will look like:

    apply_requirements: []
    workflow: default
    allowed_overrides: []
    allow_custom_workflows: true
    

    Where

    • apply_requirements is set from the id: github.com/owner/repo config because it overrides the previous matching config from id: /.*/.
    • workflow is set from the default config that always exists.
    • allowed_overrides is set from the default config that always exists.
    • allow_custom_workflows is set from the id: /.*/ config and isn't unset by the id: github.com/owner/repo config because it didn't define that key.

Policies

KeyTypeDefaultRequiredDescription
conftest_versionstringnonenoconftest version to run all policy sets
ownersOwners(#Owners)noneyesowners that can approve failing policies
policy_sets[]PolicySetnoneyesset of policies to run on a plan output

Owners

KeyTypeDefaultRequiredDescription
users[]stringnonenolist of github users that can approve failing policies
teams[]stringnonenolist of github teams that can approve failing policies

PolicySet

KeyTypeDefaultRequiredDescription
namestringnoneyesunique name for the policy set
pathstringnoneyespath to the rego policies directory
sourcestringnoneyesonly local is supported at this time

Metrics

KeyTypeDefaultRequiredDescription
statsdStatsdnonenoStatsd metrics provider
prometheusPrometheusnonenoStatsd metrics provider

Statsd

KeyTypeDefaultRequiredDescription
hoststringnoneyesstatsd host ip address
portstringnoneyesstatsd port

Prometheus

KeyTypeDefaultRequiredDescription
endpointstringnoneyespath to metrics endpoint
Last Updated:
Contributors: Ken Kaizu, Luke Kysow, Nish Krishnan, Sarvar Muminov, Alexander Dupuy, Dalton Hubble, Darren Worrall, Istvan Tapaszto, Josh Soref, Li Lin, Logan Stuart, Luke Young, Marc Goujon, Marcus Ramberg, Martin Mosegaard Amdisen, Masayuki Morita, PePe Amengual, Tim McFadden, markleary