Automerge#

Atlantis can automatically merge a pull request after every plan in that PR has been successfully applied. The feature is implemented in server/events/automerger.go, which exposes the AutoMerger struct wired to a VCS client.

Enabling Automerge#

Automerge is opt-in and can be enabled at two scopes 1:

Per-repo config takes precedence over the server-wide flag 1. Automerge can be disabled for a single apply command via atlantis apply --auto-merge-disabled 1.

Requirements before merging:

• All plans in the PR must succeed before any can be applied 1.
• All plans must be applied before automerge fires 2.
• The Atlantis VCS user must have merge permissions on the repo 1.

Merge Method Configuration#

Three merge methods are supported for GitHub: merge, rebase, and squash 1. A fourth, fast-forward, was introduced for Gitea/Forgejo, Bitbucket Cloud, and Bitbucket Server by PR #6681 3.

Configuration follows a three-tier precedence (highest → lowest) 3:

1. --auto-merge-method comment flag — per-apply override: atlantis apply --auto-merge-method squash
2. automerge_method in atlantis.yaml — per-repo default (added in PR #6681)
3. --automerge-method server flag / ATLANTIS_AUTOMERGE_METHOD env var — global default (added in PR #6573)

In automerger.go, if the comment command carries no method, the GlobalAutomergeMethod from the server config is used as fallback.

VCS Provider Support Matrix 3:

GitHub MergePull Behavior#

The GitHub VCS MergePull function:

1. Fetches the repo to determine which merge methods it allows (AllowMergeCommit, AllowRebaseMerge, AllowSquashMerge) 4.
2. If a MergeMethod is specified in PullRequestOptions, validates it against the repo's allowed methods and returns a clear error if unsupported 5.
3. If no method is specified, auto-selects: merge → rebase → squash in priority order, skipping any the repo disallows 6.
4. Calls PUT /repos/{owner}/{repo}/pulls/{num}/merge with an empty commit message (GitHub auto-generates it) 7.

Error Handling#

When MergePull fails, automerger.go posts a failure comment on the PR with the error message, so the team is notified without requiring log access. Commenting about the automerge attempt itself is non-fatal — failures there are logged and the merge still proceeds 8.

GitHub Merge Queue Support#

GitHub's merge queue requires merge_group webhook events instead of the standard pull_request webhooks. PR #6435 adds end-to-end support 9.

How it works:

• Pre-flight detection: A GraphQL query checks branchProtectionRule.requiresMergeQueue (classic branch protection) and inspects rulesets for an active MERGE_QUEUE rule. If detected, Atlantis uses enablePullRequestAutoMerge GraphQL mutation instead of direct REST merge 9.
• Post-flight fallback: If the REST merge returns 405 Method Not Allowed with a merge-queue error, Atlantis automatically retries via GraphQL auto-merge. This handles cases where the pre-flight query is incomplete (e.g., >100 ruleset rules) 9.
• Merge group events: When GitHub emits a merge_group event with checks_requested, Atlantis posts success statuses for plan, apply, and policy_check on the merge group's head SHA — unblocking the queue without re-running Terraform (since the PR was already validated before entering the queue) 9.

Configuration required:

1. Enable the flag: --gh-merge-queue-enabled / ATLANTIS_GH_MERGE_QUEUE_ENABLED=true 9.
2. Subscribe the GitHub webhook (or GitHub App) to the merge_group event 9.
3. Grant the Atlantis VCS user/App permission to enable auto-merge on the repository 9.

Note: Before PR #6435 landed, the incompatibility between Atlantis and GitHub merge queues was a known blocker — Atlantis would ignore merge_group webhooks entirely, leaving PRs stuck 10.

Key Source Files#