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
Config File
Precedence
Flags

Environment Variables

All flags can be specified as environment variables.

Take the flag name, ex. --gh-user
Ignore the first -- => gh-user
Convert the -'s to _'s => gh_user
Uppercase all the letters => GH_USER
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:

Flags
Environment Variables
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.

# Server Configuration

# Environment Variables

# Config File

# Precedence

# Flags

# --allow-fork-prs

# --allow-repo-config

# --atlantis-url

# --automerge

# --bitbucket-base-url

# --bitbucket-token

# --bitbucket-user

# --bitbucket-webhook-secret

# --checkout-strategy

# --config

# --data-dir

# --default-tf-version

# --disable-apply-all

# --gh-hostname

# --gh-token

# --gh-user

# --gh-webhook-secret

# --gitlab-hostname

# --gitlab-token

# --gitlab-user

# --gitlab-webhook-secret

# --help

# --log-level

# --port

# --repo-config

# --repo-config-json

# --repo-whitelist

# --require-approval

# --require-mergeable

# --silence-whitelist-errors

# --slack-token

# --ssl-cert-file

# --ssl-key-file

# --tfe-hostname

# --tfe-token

# --write-git-creds

Server Configuration

Environment Variables

Config File

Precedence

Flags

`--allow-fork-prs`

`--allow-repo-config`

`--atlantis-url`

`--automerge`

`--bitbucket-base-url`

`--bitbucket-token`

`--bitbucket-user`

`--bitbucket-webhook-secret`

`--checkout-strategy`

`--config`

`--data-dir`

`--default-tf-version`

`--disable-apply-all`

`--gh-hostname`

`--gh-token`

`--gh-user`

`--gh-webhook-secret`

`--gitlab-hostname`

`--gitlab-token`

`--gitlab-user`

`--gitlab-webhook-secret`

`--help`

`--log-level`

`--port`

`--repo-config`

`--repo-config-json`

`--repo-whitelist`

`--require-approval`

`--require-mergeable`

`--silence-whitelist-errors`

`--slack-token`

`--ssl-cert-file`

`--ssl-key-file`

`--tfe-hostname`

`--tfe-token`

`--write-git-creds`