Running the server & webhooks

Wiring Atlantis to your VCS.

Advanced12 min · lesson 2 of 12

Atlantis is a single Go binary (or container) that runs as a long-lived server, reachable by your version-control system. Setup has three connections: Atlantis needs a VCS token to read PRs and post comments, the VCS needs a webhook pointing at Atlantis so events reach it, and Atlantis needs cloud credentials to run Terraform. Once those are wired, opening a Terraform PR triggers the flow automatically.

terminal

$ atlantis server \
    --gh-user=atlantis-bot \
    --gh-token=$GH_TOKEN \
    --gh-webhook-secret=$WEBHOOK_SECRET \
    --repo-allowlist=github.com/acme/* \
    --atlantis-url=https://atlantis.acme.internal

Webhooks and the allowlist

The webhook is how PR events reach Atlantis, and it must be authenticated with a shared secret (--gh-webhook-secret) so Atlantis rejects forged events — without it, anyone who can reach the server could trigger runs. The repo allowlist restricts which repositories Atlantis will act on, so a webhook from an unexpected repo is ignored. These two settings are the front door’s lock; they are security controls, not optional config.

webhook config

# VCS webhook -> https://atlantis.acme.internal/events
# events: Pull request, Push, Issue comment
# secret: <WEBHOOK_SECRET>   (must match --gh-webhook-secret)
# Atlantis verifies the secret on every event and ignores repos outside the allowlist

Set the webhook secret and a tight allowlist

Running Atlantis without a webhook secret lets anyone who can reach /events forge PR events and drive Terraform runs; a wildcard repo allowlist lets it act on repos you never intended. Always configure --gh-webhook-secret and scope --repo-allowlist to exactly your org’s repos. These are the difference between a controlled automation server and an open door to your cloud.

What Atlantis is: PR-driven…The plan/apply PR workflow