Webhook Comment Processing#

When a user comments on a pull request, Atlantis receives a provider-specific webhook, parses it into internal models, validates multiple guards, and then dispatches the command asynchronously. The full pipeline spans three layers:

1. HTTP routing → VCSEventsController.Post 1
2. Event parsing → provider-specific functions in server/events/event_parser.go
3. Validation + execution → handleCommentEvent → RunCommentCommand

Provider-Specific Event Parsing#

Each VCS provider uses a distinct webhook payload. The EventParser in server/events/event_parser.go provides a dedicated function per provider to extract the raw comment body, the commenter identity, and the repository context into canonical internal models (models.Repo, models.User, models.PullRequest):

Key differences: GitHub and Gitea comment events only carry baseRepo + user + pullNum (the head repo is fetched lazily later), while Bitbucket variants include the full PullRequest model directly in the webhook payload. GitLab uniquely returns both baseRepo and headRepo from the event. Commit-level comments in GitLab are explicitly ignored 2.

HTTP routing to these handlers is header-driven: X-Github-Event → GitHub, X-Gitlab-Event → GitLab, X-Event-Key + X-Request-UUID → Bitbucket Cloud, X-Gitea-Event → Gitea 1.

Comment Parsing#

After the provider-specific parse, the raw comment text flows into CommentParser.Parse in server/events/comment_parser.go. This function:

1. Trims & rejects multi-line comments (only a trailing double-newline from GitHub copy-paste is tolerated)
2. Matches the executable name (atlantis, run, or @<VCSUser>) — near-matches to terraform or the executable name produce a "Did you mean…?" reply
3. Re-parses with shlex.Split to handle quoted arguments
4. Dispatches to per-command pflag.FlagSet for plan, apply, unlock, version, approve_policies, import, state, cancel
5. Validates flags — blocked extra args (-chdir, -plugin-dir) and path traversal in -d/--dir and workspace names are rejected

The result is a CommentParseResult containing either a parsed CommentCommand, an immediate CommentResponse (e.g., for help), or an Ignore signal.

Validation Guards in handleCommentEvent#

Once parsing succeeds, handleCommentEvent applies guards in this order before dispatching:

1. Ignore check — if parseResult.Ignore is true (non-command comment), returns 200 immediately with no side effects 3.

2. Repo allowlist — RepoAllowlistChecker.IsAllowlisted validates the repo's full name and VCS hostname against include/exclude wildcard rules. Failure returns HTTP 403 and (optionally) a PR comment; the error can be silenced via SilenceAllowlistErrors.

3. Emoji reaction — if configured, Atlantis reacts to the comment before proceeding 4.

4. Immediate response — help and invalid commands are replied to directly without entering RunCommentCommand 5.

5. Async dispatch — valid commands are handed off to RunCommentCommand in a goroutine 6.

Validation Guards in RunCommentCommand#

DefaultCommandRunner.RunCommentCommand applies a second layer of guards after building the command.Context:

1. Repo metadata validation — ensureValidRepoMetadata fetches or validates pull request data from the VCS API, normalizing the lazy-fetched fields for providers that didn't include them in the webhook.

2. Fork policy — validateCtxAndComment rejects commands on fork PRs when AllowForkPRs=false (comparing head repo owner vs. base repo owner), rejects commands on closed PRs (except unlock), and rejects PRs whose base branch doesn't match the configured branch filter.

3. User permissions & var-file allowlist — validateCommentCommand checks team allowlist membership (hierarchical, up to 20 levels of descendant teams) and, for plan commands, validates that any -var-file flags point only to allowlisted paths.

Key Files#