In April 2024, the Core Atlantis Team launched an anonymous survey to better understand our community's needs and help prioritize our roadmap.
If you're an Atlantis user, please take 5 minutes to fill it out: Survey Link
In April 2024, the Core Atlantis Team launched an anonymous survey to better understand our community's needs and help prioritize our roadmap.
If you're an Atlantis user, please take 5 minutes to fill it out: Survey Link
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.
WARNING
Bitbucket Cloud (bitbucket.org) doesn't use webhook secrets so if you're using Bitbucket Cloud you can skip this step. When you're ready to do a production deploy of Atlantis you should allowlist Bitbucket IPs to ensure the webhooks are coming 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:
/events
at the end. Ex. https://c5004d84.ngrok.io/events
/events
to the end of your URL.application/json
/events
at the end. Ex. https://c5004d84.ngrok.io/events
/events
to the end of your URL./events
at the end. Ex. https://c5004d84.ngrok.io/events
/events
to the end of your URL./events
at the end. Ex. https://c5004d84.ngrok.io/events
/events
to the end of your URL.http://$URL/events
(or https://$URL/events
if you're using SSL) where $URL
is where Atlantis is hosted. Be sure to add /events
/events
to the end of your URL.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.