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.

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

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-fork-prs

    atlantis server --allow-fork-prs
    

    Respond to pull requests from forks. Defaults to false.

    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

    Deprecated
    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 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}]}'
    

    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"
    

    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.

  • --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.

    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-all

    atlantis server --disable-apply-all
    

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

  • --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/).

    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.

  • --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 --gh-webhook-secret="secret"
    # or (recommended)
    ATLANTIS_GITLAB_WEBHOOK_SECRET='secret' atlantis server
    

    Secret used to validate GitLab webhooks.

    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.

  • --log-level

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

    Log level. Defaults to info.

  • --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

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

    Atlantis requires you to specify a whitelist 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

    Examples:

    • Whitelist myorg/repo1 and myorg/repo2 on github.com
      • --repo-whitelist=github.com/myorg/repo1,github.com/myorg/repo2
    • Whitelist all repos under myorg on github.com
      • --repo-whitelist='github.com/myorg/*'
    • Whitelist all repos in my GitHub Enterprise installation
      • --repo-whitelist='github.yourcompany.com/*'
    • Whitelist all repositories
      • --repo-whitelist='*'
  • --require-approval

    Deprecated
    atlantis server --require-approval
    

    This flag is deprecated. It requires all pull requests to be approved before atlantis apply is allowed. See Apply Requirements 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

    Deprecated
    atlantis server --require-mergeable
    

    This flag is deprecated. It causes all pull requests to be mergeable before atlantis apply is allowed. See Apply Requirements 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-whitelist-errors

    atlantis server --silence-whitelist-errors
    

    Some users use the --repo-whitelist flag to control which repos Atlantis responds to. Normally, if Atlantis receives a pull request webhook from a repo not listed in the whitelist, 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.

  • --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.

  • --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' atlantis server
    

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

  • --write-git-creds

    atlantis server --write-git-creds
    

    Write out a .git-credentials file and configure git-credentials-store. To allow authentication with your git remotes over https. See here for more information.

    SECURITY WARNING

    Potentially dangerous to enable as this writes your credentials to disk.