Autoplan#

Autoplan is the mechanism that automatically runs terraform plan on a pull request when it is opened or a new commit is pushed. It determines which projects to plan by matching changed files against configurable glob patterns, and provides several ways to suppress or disable the behavior.

Webhook Triggering#

All supported VCS providers converge on a single code path. The VCSEventsController.Post() method routes incoming webhooks to provider-specific handlers, each of which calls handlePullRequestEvent() 1.

Provider handlers:

• GitHub — handleGithubPost() 2
• GitLab — handleGitlabPost() 3
• Bitbucket Cloud / Server — handleBitbucketCloudPost() / handleBitbucketServerPost() 4
• Azure DevOps — handleAzureDevopsPost() 5
• Gitea — handleGiteaPost() 6

handlePullRequestEvent() fires RunAutoplanCommand() asynchronously (via goroutine) on OpenedPullEvent or UpdatedPullEvent only — closed/merged events do not trigger autoplan 7.

Bitbucket note: Bitbucket lacks a webhook that fires only on new commits. Atlantis caches the last commit SHA to avoid duplicate plans. If the cache is cleared, a spurious plan may occur. (runatlantis.io docs)

Execution Flow#

RunAutoplanCommand() in command_runner.go orchestrates the full autoplan lifecycle:

1. Drainer check (graceful shutdown guard)
2. Team permission check
3. Build command.Context with Trigger: command.AutoTrigger
4. Validate context (fork rules, branch rules)
5. Check DisableAutoplan global flag 8
6. Check DisableAutoplanLabel per-PR label 9
7. Run pre-workflow hooks
8. Invoke PlanCommandRunner.Run() → runAutoplan() (triggered when ctx.Trigger == command.AutoTrigger)
9. Run post-workflow hooks

Disable / Suppression Mechanisms#

Label-based suppression 9: when DisableAutoplanLabel is set, Atlantis fetches the PR's labels via the VCS API before running. If the label is present, autoplan is skipped with a log message. On label-fetch error, autoplan proceeds (fail-open).

File Pattern Matching (when_modified)#

Without atlantis.yaml#

Atlantis uses DefaultProjectFinder.DetermineProjects() with the server-level --autoplan-file-list flag. Changed files are filtered using filterToFileList() 10 and then each file's directory is walked upward to find a Terraform root (presence of *.tf files). Module directories are handled separately via ModuleProjects.DependentProjects() 11.

With atlantis.yaml#

DetermineProjectsViaConfig() 12 iterates over every project and tests each modified file against the project's autoplan.when_modified patterns using moby/patternmatcher. Key behaviors:

• Patterns are relative to the project directory — Atlantis prepends the project dir before matching against repo-root-relative paths 13.
• Exclusion patterns prefixed with ! are supported 14.
• A project matches if any modified file matches any pattern 15.
• If the project directory does not exist on disk, the project is skipped 16.

Default Patterns#

Defined in raw/autoplan.go and expanded to recursive **/ globs:

Always-Ignored Files#

Regardless of patterns, the following files never trigger a plan 17:

• terraform.tfstate
• terraform.tfstate.backup
• tflint.hcl

atlantis.yaml Configuration Reference#

projects:
  - dir: infra/vpc
    autoplan:
      enabled: true # default: true
      when_modified:
        - "*.tf"
        - "*.tfvars"
        - "!override.tf" # exclusion

The raw config struct is defined in server/core/config/raw/autoplan.go. Both fields are optional — enabled defaults to true and when_modified defaults to the patterns above 18.

Key Source Files#