Locking & the apply gate

No colliding applies; review first.

Advanced10 min · lesson 4 of 12

When multiple PRs touch the same Terraform, concurrent plans and applies would race on shared state. Atlantis prevents this with locking: when a PR plans a project, Atlantis locks that project (directory + workspace), and any other PR trying to plan or apply it is blocked with a comment pointing at the PR that holds the lock. The lock releases when the PR is applied and merged, or when you manually unlock it. One project changes through one PR at a time.

THE PROJECT LOCK LIFECYCLE
1PR plans project
Atlantis runs plan for dir + workspace
2Lock acquired
project locked to that PR
3Other PRs blocked
comment points at the holding PR
4Apply & merge
or manual unlock via UI
5Lock released
next PR may plan
One project changes through one PR at a time; unlock deliberately if a lock lingers.
PR comment
This project is currently locked by an unapplied plan from PR #142.
To continue, apply and merge PR #142, or unlock it via the Atlantis UI.
# your plan will run once the lock is released

The apply gate

Locking pairs with the apply gate to make the review meaningful. Atlantis can require that a PR be approved (and that its plan is current) before atlantis apply is allowed, and restrict who may apply. Combined, these enforce: only one change to a project in flight, only after review, only by authorized people. That is the governance the whole tool exists to provide — serialize, review, authorize — enforced automatically rather than by convention.

server config
# require approval + a mergeable PR before apply is permitted
--require-approval # (or per-repo: apply_requirements: [approved, mergeable])
# restrict who can run apply via VCS permissions + team membership
A stuck lock blocks the project — unlock deliberately
If a PR is closed without applying, or a run fails midway, a lock can linger and block everyone else on that project. Atlantis provides a UI/command to unlock, but unlock deliberately: confirm no apply is genuinely in flight first, because force-unlocking while another run holds state can lead to the concurrent applies locking was meant to prevent. Investigate the holding PR before you clear the lock.