atlantis/runatlantis.io/docs/server-configuration.md

Server Configuration

This page explains how to configure the atlantis server command.

Configuration to atlantis server can be specified via command line flags, environment variables, a config file or a mix of the three.

toc

Environment Variables

All flags can be specified as environment variables.

1. Take the flag name, ex. --gh-user
2. Ignore the first -- => gh-user
3. Convert the -'s to _'s => gh_user
4. Uppercase all the letters => GH_USER
5. Prefix with ATLANTIS_ => ATLANTIS_GH_USER

::: warning NOTE To set a boolean flag use true or false as the value. :::

::: warning NOTE The flag --atlantis-url is set by the environment variable ATLANTIS_ATLANTIS_URL NOT ATLANTIS_URL. :::

Config File

All flags can also be specified via a YAML config file.

To use a YAML config file, run atlantis server --config /path/to/config.yaml.

The keys of your config file should be the same as the flag names, ex.

gh-token: ...
log-level: ...

::: warning The config file you pass to --config is different from the --repo-config file. The --config config file is only used as an alternate way of setting atlantis server flags. :::

Precedence

Values are chosen in this order:

1. Flags
2. Environment Variables
3. Config File

Flags

• --allow-draft-prs

  atlantis server --allow-draft-prs
  

  Respond to pull requests from draft prs. Defaults to false.

• --allow-fork-prs

  atlantis server --allow-fork-prs
  

  Respond to pull requests from forks. Defaults to false.

  :::warning SECURITY WARNING Potentially dangerous to enable because if attackers can create a pull request to your repo then they can cause Atlantis to run arbitrary code. This can happen because Atlantis will automatically run terraform plan which can run arbitrary code if given a malicious Terraform configuration. :::

• --allow-repo-config

  ```bash atlantis server --allow-repo-config ``` This flag is deprecated. It allows all repos to use all restricted `atlantis.yaml` keys. See [Repo Level Atlantis.yaml](repo-level-atlantis-yaml.html) for more details.

  Instead of using this flag, create a server-side --repo-config file:

  # repos.yaml
  repos:
  - id: /.*/
    allowed_overrides: [apply_requirements, workflow]
    allow_custom_workflows: true
  

  Or use

  --repo-config-json='{"repos":[{"id":"/.*/", "allowed_overrides":["apply_requirements","workflow"], "allow_custom_workflows":true}]}'
  

  ::: warning SECURITY WARNING This setting enables pull requests to run arbitrary code on the Atlantis server. Only enable in trusted settings. :::

• --atlantis-url

  atlantis server --atlantis-url="https://my-domain.com:9090/basepath"
  # or
  ATLANTIS_ATLANTIS_URL=https://my-domain.com:9090/basepath
  

  Specify the URL that Atlantis is accessible from. Used in the Atlantis UI and in links from pull request comments. Defaults to http://$(hostname):$port where $port is from the --port flag. Supports a basepath if you're hosting Atlantis under a path.

• --automerge

  atlantis server --automerge
  

  Automatically merge pull requests after all plans have been successfully applied. Defaults to false. See Automerging for more details.

• --autoplan-file-list

  # NOTE: Use single quotes to avoid shell expansion of *.
  atlantis server --autoplan-file-list='**/*.tf,project1/*.pkr.hcl'
  

  List of file patterns that Atlantis will use to check if a directory contains modified files that should trigger project planning.

  Notes:

  • Accepts a comma separated list, ex. pattern1,pattern2.
  • Patterns use the .dockerignore syntax
  • List of file patterns will be used by both automatic and manually run plans.
  • When not set, defaults to all .tf, .tfvars, .tfvars.json, terragrunt.hcl and .terraform.lock.hcl files (--autoplan-file-list='**/*.tf,**/*.tfvars,**/*.tfvars.json,**/terragrunt.hcl,**/.terraform.lock.hcl').
  • Setting --autoplan-file-list will override the defaults. You must add **/*.tf and other defaults if you want to include them.
  • A custom Workflow that uses autoplan when_modified will ignore this value.

  Examples:

  • Autoplan when any *.tf or *.tfvars file is modified.
    • --autoplan-file-list='**/*.tf,**/*.tfvars'
  • Autoplan when any *.tf file is modified except in project2/ directory
    • --autoplan-file-list='**/*.tf,!project2'
  • Autoplan when any *.tf files or .yml files in subfolder of project1 is modified.
    • --autoplan-file-list='**/*.tf,project2/**/*.yml'

• --azuredevops-webhook-password

  atlantis server --azuredevops-webhook-password="password123"
  

  Azure DevOps basic authentication password for inbound webhooks (see https://docs.microsoft.com/en-us/azure/devops/service-hooks/authorize?view=azure-devops).

  ::: warning SECURITY WARNING If not specified, Atlantis won't be able to validate that the incoming webhook call came from your Azure DevOps org. This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. Should be specified via the ATLANTIS_AZUREDEVOPS_BASIC_AUTH environment variable. :::

• --azuredevops-webhook-user

  atlantis server --azuredevops-webhook-user="username@example.com"
  

  Azure DevOps basic authentication username for inbound webhooks. Can also be specified via the ATLANTIS_AZUREDEVOPS_WEBHOOK_USER environment variable.

• --azuredevops-token

  atlantis server --azuredevops-token="RandomStringProducedByAzureDevOps"
  

  Azure DevOps token of API user. Can also be specified via the ATLANTIS_AZUREDEVOPS_TOKEN environment variable.

• --azuredevops-user

  atlantis server --azuredevops-user="username@example.com"
  

  Azure DevOps username of API user.

• --bitbucket-base-url

  atlantis server --bitbucket-base-url="http://bitbucket.corp:7990/basepath"
  

  Base URL of Bitbucket Server (aka Stash) installation. Must include http:// or https://. If using Bitbucket Cloud (bitbucket.org), do not set. Defaults to https://api.bitbucket.org.

• --bitbucket-token

  atlantis server --bitbucket-token="token"
  # or (recommended)
  ATLANTIS_BITBUCKET_TOKEN='token' atlantis server
  

  Bitbucket app password of API user.

• --bitbucket-user

  atlantis server --bitbucket-user="myuser"
  

  Bitbucket username of API user.

• --bitbucket-webhook-secret

  atlantis server --bitbucket-webhook-secret="secret"
  # or (recommended)
  ATLANTIS_BITBUCKET_WEBHOOK_SECRET='secret' atlantis server
  

  Secret used to validate Bitbucket webhooks. Only Bitbucket Server supports webhook secrets. For Bitbucket.org, see Security for mitigations.

  ::: warning SECURITY WARNING If not specified, Atlantis won't be able to validate that the incoming webhook call came from Bitbucket. This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. :::

• --checkout-strategy

  atlantis server --checkout-strategy="<branch|merge>"
  

  How to check out pull requests. Defaults to branch. See Checkout Strategy for more details.

• --config

  atlantis server --config="my/config/file.yaml"
  

  YAML config file where flags can also be set. See Config File for more details.

• --data-dir

  atlantis server --data-dir="path/to/data/dir"
  

  Directory where Atlantis will store its data. Will be created if it doesn't exist. Defaults to ~/.atlantis. Atlantis will store its database, checked out repos, Terraform plans and downloaded Terraform binaries here. If Atlantis loses this directory, locks will be lost and unapplied plans will be lost.

• --default-tf-version

  atlantis server --default-tf-version="v0.12.0"
  

  Terraform version to default to. Will download to <data-dir>/bin/terraform<version> if not in PATH. See Terraform Versions for more details.

• --disable-apply

  atlantis server --disable-apply
  

  Disable all "atlantis apply" commands, regardless of which flags are passed with it.

• --disable-apply-all

  atlantis server --disable-apply-all
  

  Disable "atlantis apply" command so a specific project/workspace/directory has to be specified for applies.

• --disable-autoplan

  atlantis server --disable-autoplan
  

  Disable atlantis auto planning

• --disable-repo-locking

  atlantis server --disable-repo-locking
  

  Stops atlantis locking projects and or workspaces when running terraform

• --enable-policy-checks

  ```bash atlantis server --enable-policy-checks ``` Enables atlantis to run server side policies on the result of a terraform plan. Policies are defined in [server side repo config](https://www.runatlantis.io/docs/server-side-repo-config.html#reference).

• --enable-regexp-cmd

  atlantis server --enable-regexp-cmd
  

  Enable Atlantis to use regular expressions on plan/apply commands when "-p" flag is passed with it.

  ::: warning SECURITY WARNING It's not supposed to be used with --disable-apply-all. The command atlantis apply -p .* will bypass the restriction and run apply on every projects :::

• --enable-diff-markdown-format

  atlantis server --enable-diff-markdown-format
  

  Enable Atlantis to format Terraform plan output into a markdown-diff friendly format for color-coding purposes.

  Useful to enable for use with Github.

• --gh-hostname

  atlantis server --gh-hostname="my.github.enterprise.com"
  

  Hostname of your GitHub Enterprise installation. If using Github.com, don't set. Defaults to github.com.

• --gh-token

  atlantis server --gh-token="token"
  # or (recommended)
  ATLANTIS_GH_TOKEN='token' atlantis server
  

  GitHub token of API user.

• --gh-user

  atlantis server --gh-user="myuser"
  

  GitHub username of API user.

• --gh-webhook-secret

  atlantis server --gh-webhook-secret="secret"
  # or (recommended)
  ATLANTIS_GH_WEBHOOK_SECRET='secret' atlantis server
  

  Secret used to validate GitHub webhooks (see https://developer.github.com/webhooks/securing/).

  ::: warning SECURITY WARNING If not specified, Atlantis won't be able to validate that the incoming webhook call came from GitHub. This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. :::

• --gh-org

  atlantis server --gh-org="myorgname"
  

  GitHub organization name. Set to enable creating a private Github app for this organization.

• --gh-app-id

  atlantis server --gh-app-id="00000"
  

  GitHub app ID. If set, GitHub authentication will be performed as an installation.

  ::: tip A GitHub app can be created by starting Atlantis first, then pointing your browser at

  $(hostname)/github-app/setup
  

  You'll be redirected to GitHub to create a new app, and will then be redirected to

  $(hostname)/github-app/exchange-code?code=some-code
  

  After which Atlantis will display your new app's credentials: your app's ID, its generated --gh-webhook-secret and the contents of the file for --gh-app-key-file. Update your Atlantis config accordingly, and restart the server. :::

• --gh-app-key-file

  atlantis server --gh-app-key-file="path/to/app-key.pem"
  

  Path to a GitHub App PEM encoded private key file. If set, GitHub authentication will be performed as an installation.

• --gh-app-key

  atlantis server --gh-app-key="-----BEGIN RSA PRIVATE KEY-----(...)"
  

  The PEM encoded private key for the GitHub App.

  ::: warning SECURITY WARNING The contents of the private key will be visible by anyone that can run ps or look at the shell history of the machine where Atlantis is running. Use --gh-app-key-file to mitigate that risk. :::

• --gh-team-allowlist

  atlantis server --gh-team-allowlist="myteam:plan, secteam:apply"
  

  Comma-separated list of GitHub team name (not a slug) and permission pairs. By default, any team can plan and apply.

• --gitlab-hostname

  atlantis server --gitlab-hostname="my.gitlab.enterprise.com"
  

  Hostname of your GitLab Enterprise installation. If using Gitlab.com, don't set. Defaults to gitlab.com.

• --gitlab-token

  atlantis server --gitlab-token="token"
  # or (recommended)
  ATLANTIS_GITLAB_TOKEN='token' atlantis server
  

  GitLab token of API user.

• --gitlab-user

  atlantis server --gitlab-user="myuser"
  

  GitLab username of API user.

• --gitlab-webhook-secret

  atlantis server --gitlab-webhook-secret="secret"
  # or (recommended)
  ATLANTIS_GITLAB_WEBHOOK_SECRET='secret' atlantis server
  

  Secret used to validate GitLab webhooks.

  ::: warning SECURITY WARNING If not specified, Atlantis won't be able to validate that the incoming webhook call came from GitLab. This means that an attacker could spoof calls to Atlantis and cause it to perform malicious actions. :::

• --help

  atlantis server --help
  

  View help.

• --hide-prev-plan-comments

  atlantis server --hide-prev-plan-comments
  

  Hide previous plan comments to declutter PRs. This is only supported in GitHub currently.

• --log-level

  atlantis server --log-level="<debug|info|warn|error>"
  

  Log level. Defaults to info.

• --parallel-pool-size

  atlantis server --parallel-pool-size=100
  

  Max size of the wait group that runs parallel plans and applies (if enabled). Defaults to 15

• --port

  atlantis server --port=8080
  

  Port to bind to. Defaults to 4141.

• --repo-config

  atlantis server --repo-config="path/to/repos.yaml"
  

  Path to a YAML server-side repo config file. See Server Side Repo Config.

• --repo-config-json

  atlantis server --repo-config-json='{"repos":[{"id":"/.*/", "apply_requirements":["mergeable"]}]}'
  

  Specify server-side repo config as a JSON string. Useful if you don't want to write a config file to disk. See Server Side Repo Config for more details.

  ::: tip If specifying a Workflow, step's can be specified as follows:

  {
    "repos": [],
    "workflows": {
      "custom": {
        "plan": {
          "steps": [
            "init",
            {
              "plan": {
                "extra_args": ["extra", "args"]
              }
            },
            {
              "run": "my custom command"
            }
          ]
        }
      }
    }
  }
  

  :::

• --repo-whitelist

  Deprecated for `--repo-allowlist`.

• --repo-allowlist

  # NOTE: Use single quotes to avoid shell expansion of *.
  atlantis server --repo-allowlist='github.com/myorg/*'
  

  Atlantis requires you to specify an allowlist of repositories it will accept webhooks from.

  Notes:

  • Accepts a comma separated list, ex. definition1,definition2
  • Format is {hostname}/{owner}/{repo}, ex. github.com/runatlantis/atlantis
  • * matches any characters, ex. github.com/runatlantis/* will match all repos in the runatlantis organization
  • For Bitbucket Server: {hostname} is the domain without scheme and port, {owner} is the name of the project (not the key), and {repo} is the repo name
    • User (not project) repositories take on the format: {hostname}/{full name}/{repo} (e.g., bitbucket.example.com/Jane Doe/myatlantis for username jdoe and full name Jane Doe, which is not very intuitive)
  • For Azure DevOps the allowlist takes one of two forms: {owner}.visualstudio.com/{project}/{repo} or dev.azure.com/{owner}/{project}/{repo}
  • Microsoft is in the process of changing Azure DevOps to the latter form, so it may be safest to always specify both formats in your repo allowlist for each repository until the change is complete.

  Examples:

  • Allowlist myorg/repo1 and myorg/repo2 on github.com
    • --repo-allowlist=github.com/myorg/repo1,github.com/myorg/repo2
  • Allowlist all repos under myorg on github.com
    • --repo-allowlist='github.com/myorg/*'
  • Allowlist all repos in my GitHub Enterprise installation
    • --repo-allowlist='github.yourcompany.com/*'
  • Allowlist all repos under myorg project myproject on Azure DevOps
    • --repo-allowlist='myorg.visualstudio.com/myproject/*,dev.azure.com/myorg/myproject/*'
  • Allowlist all repositories
    • --repo-allowlist='*'

• --require-approval

  ```bash atlantis server --require-approval ``` This flag is deprecated. It requires all pull requests to be approved before `atlantis apply` is allowed. See [Apply Requirements](apply-requirements.html) for more details.

  Instead of using this flag, create a server-side --repo-config file:

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

  Or use --repo-config-json='{"repos":[{"id":"/.*/", "apply_requirements":["approved"]}]}' instead.

• --require-mergeable

  ```bash atlantis server --require-mergeable ``` This flag is deprecated. It causes all pull requests to be mergeable before `atlantis apply` is allowed. See [Apply Requirements](apply-requirements.html) for more details.

  Instead of using this flag, create a server-side --repo-config file:

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

  Or use --repo-config-json='{"repos":[{"id":"/.*/", "apply_requirements":["mergeable"]}]}' instead.

• --silence-fork-pr-errors

  atlantis server --silence-fork-pr-errors
  

  Normally, if Atlantis receives a pull request webhook from a fork and --allow-fork-prs is not set, it will comment back with an error. This flag disables that commenting.

• --silence-whitelist-errors

  Deprecated for `--silence-allowlist-errors`.

• --silence-allowlist-errors

  atlantis server --silence-allowlist-errors
  

  Some users use the --repo-allowlist flag to control which repos Atlantis responds to. Normally, if Atlantis receives a pull request webhook from a repo not listed in the allowlist, it will comment back with an error. This flag disables that commenting.

  Some users find this useful because they prefer to add the Atlantis webhook at an organization level rather than on each repo.

• --silence-no-projects

  atlantis server --silence-no-projects
  

  --silence-no-projects will tell Atlantis to ignore PRs if none of the modified files are part of a project defined in the atlantis.yaml file.

  This is useful when running multiple Atlantis servers against a single repository so you can delegate work to each Atlantis server. Also useful when used with pre_workflow_hooks to dynamically generate an atlantis.yaml file.

• --silence-vcs-status-no-plans

  atlantis server --silence-vcs-status-no-plans
  

  --silence-vcs-status-no-plans will tell Atlantis to ignore setting VCS status if none of the modified files are part of a project defined in the atlantis.yaml file.

• --skip-clone-no-changes

  atlantis server --skip-clone-no-changes
  

  --skip-clone-no-changes will skip cloning the repo during autoplan if there are no changes to Terraform projects. This will only apply for GitHub and GitLab and only for repos that have atlantis.yaml file. Defaults to false.

• --slack-token

  atlantis server --slack-token=token
  # or (recommended)
  ATLANTIS_SLACK_TOKEN='token' atlantis server
  

  API token for Slack notifications. Slack is not fully supported. TODO: Slack docs.

• --ssl-cert-file

  atlantis server --ssl-cert-file="/etc/ssl/certs/my-cert.crt"
  

  File containing x509 Certificate used for serving HTTPS. If the cert is signed by a CA, the file should be the concatenation of the server's certificate, any intermediates, and the CA's certificate.

• --ssl-key-file

  atlantis server --ssl-cert-file="/etc/ssl/private/my-cert.key"
  

  File containing x509 private key matching --ssl-cert-file.

• --stats-namespace

  atlantis server --stats-namespace="myatlantis"
  

  Namespace for emitting stats/metrics. See (stats.html#Metrics/Stats)

• --tf-download-url

  atlantis server --tf-download-url="https://releases.company.com"
  

  An alternative URL to download Terraform versions if they are missing. Useful in an airgapped environment where releases.hashicorp.com is not available. Directory structure of the custom endpoint should match that of releases.hashicorp.com.

• --tfe-hostname

  atlantis server --tfe-hostname="my-terraform-enterprise.company.com"
  

  Hostname of your Terraform Enterprise installation to be used in conjunction with --tfe-token. See Terraform Cloud for more details. If using Terraform Cloud (i.e. you don't have your own Terraform Enterprise installation) no need to set since it defaults to app.terraform.io.

• --tfe-token

  atlantis server --tfe-token="xxx.atlasv1.yyy"
  # or (recommended)
  ATLANTIS_TFE_TOKEN='xxx.atlasv1.yyy'
  

  A token for Terraform Cloud/Terraform Enterprise integration. See Terraform Cloud for more details.

• --vcs-status-name

  atlantis server --vcs-status-name="atlantis-dev"
  

  Name used to identify Atlantis when updating a pull request status. Defaults to atlantis.

  This is useful when running multiple Atlantis servers against a single repository so you can give each Atlantis server its own unique name to prevent the statuses clashing.

• --write-git-creds

  atlantis server --write-git-creds
  # or
  ATLANTIS_WRITE_GIT_CREDS=true
  

  Write out a .git-credentials file with the provider user and token to allow cloning private modules over HTTPS or SSH. See here for more information. ::: warning SECURITY WARNING This does write secrets to disk and should only be enabled in a secure environment. :::