runatlantis.io/guide/testing-locally.md
These instructions are for running Atlantis locally on your own computer so you can test it out against your own repositories before deciding whether to install it more permanently.
::: tip If you want to set up a production-ready Atlantis installation, read Deployment. :::
Steps:
terraform needs to be in the $PATH for Atlantis.
Download from Terraform
unzip path/to/terraform_*.zip -d /usr/local/bin
Get the latest release from GitHub and unpackage it.
Atlantis needs to be accessible somewhere that github.com/gitlab.com/bitbucket.org or your GitHub/GitLab Enterprise installation can reach. One way to accomplish this is with ngrok, a tool that forwards your local port to a random public hostname.
Download ngrok and unzip it.
Start ngrok on port 4141 and take note of the hostname it gives you:
./ngrok http 4141
In a new tab (where you'll soon start Atlantis) create an environment variable with ngrok's hostname:
URL="https://{YOUR_HOSTNAME}.ngrok.io"
GitHub and GitLab use webhook secrets so clients can verify that the webhooks came from them.
Create a random string of any length (you can use random.org) and set an environment variable:
SECRET="{YOUR_RANDOM_STRING}"
Take the URL that ngrok output and create a webhook in your GitHub, GitLab or Bitbucket repo:
We recommend using a dedicated CI user or creating a new user named @atlantis that performs all API actions, however for testing, you can use your own user. Here we'll create the access token that Atlantis uses to comment on the pull request and set commit statuses.
TOKEN="{YOUR_TOKEN}"
TOKEN="{YOUR_TOKEN}"
TOKEN="{YOUR_TOKEN}"
TOKEN="{YOUR_TOKEN}"
You're almost ready to start Atlantis, just set two more variables:
USERNAME="{the username of your GitHub, GitLab or Bitbucket user}"
REPO_ALLOWLIST="$YOUR_GIT_HOST/$YOUR_USERNAME/$YOUR_REPO"
# ex. REPO_ALLOWLIST="github.com/runatlantis/atlantis"
# If you're using Bitbucket Server, $YOUR_GIT_HOST will be the domain name of your
# server without scheme or port and $YOUR_USERNAME will be the name of the **project** the repo
# is under, **not the key** of the project.
Now you can start Atlantis. The exact command differs depending on your Git host:
atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--repo-allowlist="$REPO_ALLOWLIST"
HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io
atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--gh-hostname="$HOSTNAME" \
--repo-allowlist="$REPO_ALLOWLIST"
atlantis server \
--atlantis-url="$URL" \
--gitlab-user="$USERNAME" \
--gitlab-token="$TOKEN" \
--gitlab-webhook-secret="$SECRET" \
--repo-allowlist="$REPO_ALLOWLIST"
HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io
atlantis server \
--atlantis-url="$URL" \
--gitlab-user="$USERNAME" \
--gitlab-token="$TOKEN" \
--gitlab-webhook-secret="$SECRET" \
--gitlab-hostname="$HOSTNAME" \
--repo-allowlist="$REPO_ALLOWLIST"
atlantis server \
--atlantis-url="$URL" \
--bitbucket-user="$USERNAME" \
--bitbucket-token="$TOKEN" \
--repo-allowlist="$REPO_ALLOWLIST"
BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990
atlantis server \
--atlantis-url="$URL" \
--bitbucket-user="$USERNAME" \
--bitbucket-token="$TOKEN" \
--bitbucket-webhook-secret="$SECRET" \
--bitbucket-base-url="$BASE_URL" \
--repo-allowlist="$REPO_ALLOWLIST"
A certificate and private key are required if using Basic authentication for webhooks.
atlantis server \
--atlantis-url="$URL" \
--azuredevops-user="$USERNAME" \
--azuredevops-token="$TOKEN" \
--azuredevops-webhook-user="$ATLANTIS_AZUREDEVOPS_WEBHOOK_USER" \
--azuredevops-webhook-password="$ATLANTIS_AZUREDEVOPS_WEBHOOK_PASSWORD" \
--repo-allowlist="$REPO_ALLOWLIST"
--ssl-cert-file=file.crt
--ssl-key-file=file.key
atlantis server \
--atlantis-url="$URL" \
--gitea-user="$ATLANTIS_GITEA_USER" \
--gitea-token="$ATLANTIS_GITEA_TOKEN" \
--gitea-webhook-secret="$ATLANTIS_GITEA_WEBHOOK_SECRET" \
--gitea-base-url="$ATLANTIS_GITEA_BASE_URL" \
--gitea-page-size="$ATLANTIS_GITEA_PAGE_SIZE" \
--repo-allowlist="$REPO_ALLOWLIST"
--ssl-cert-file=file.crt
--ssl-key-file=file.key
Create a pull request so you can test Atlantis. ::: tip You could add a null resource as a test:
resource "null_resource" "example" {}
Or just modify the whitespace in a file. :::
You should see Atlantis logging about receiving the webhook and you should see the output of terraform plan on your repo.
Atlantis tries to figure out the directory to plan in based on the files modified.
If you need to customize the directories that Atlantis runs in or the commands it runs if you're using workspaces
or .tfvars files, see atlantis.yaml Reference.
To manually plan in a specific directory or workspace, comment on the pull request using the -d or -w flags:
atlantis plan -d mydir
atlantis plan -w staging
To add additional arguments to the underlying terraform plan you can use:
atlantis plan -- -target=resource -var 'foo=bar'
If you'd like to apply, type a comment: atlantis apply. You can use the -d or -w flags to point
Atlantis at a specific plan. Otherwise it tries to apply the plan for the root directory.
The real-time terraform output for your command can be found by clicking into the status check for a given project in a PR which links to the log-streaming UI. This is a terminal UI where you can view your commands executing in real-time.
Ctrl-C the atlantis server command and the ngrok command.atlantis.yaml file.
See atlantis.yaml use cases.