Locking

When plan is run, the directory and Terraform workspace are Locked until the pull request merged or the plan is manually deleted.

If another user attempts to plan for the same directory and workspace in a different pull request they'll see this error:

Lock Comment

Which links them to the pull request that holds the lock.

NOTE

Only the directory in the repo and Terraform workspace are locked, not the whole repo.

Why

  1. Because atlantis apply is being done before the pull request is merged, after an apply your master branch does not represent the most up to date version of your infrastructure anymore. With locking, you can ensure that no other changes will be made until the pull request is merged.

Why not apply on merge?

Sometimes terraform apply fails. If the apply were to fail after the pull request was merged, you would need to create a new pull request to fix it. With locking + applying on the branch, you effectively mimic merging to master but with the added ability to re-plan/apply multiple times if things don't work.

  1. If there is already a plan in progress, other users won't see a plan that will be made invalid after the in-progress plan is applied.

Viewing Locks

To view locks, go to the URL that Atlantis is hosted at:

Locks View

You can click on a lock to view its details:

Lock Detail View

Unlocking

To unlock the project and workspace without completing an apply and merging, click the link at the bottom of the plan comment to discard the plan and delete the lock where it says "To discard this plan click here":

Locks View

The link will take you to the lock detail view where you can click Discard Plan and Unlock to delete the lock.

Lock Detail View

Once a plan is discarded, you'll need to run plan again prior to running apply when you go back to that pull request.

Relationship to Terraform State Locking

Atlantis does not conflict with Terraform State Locking. Under the hood, all Atlantis is doing is running terraform plan and apply and so all of the locking built in to those commands by Terraform isn't affected.

In more detail, Terraform state locking locks the state while you run terraform apply so that multiple apply's can't run concurrently. Atlantis's locking is at a higher level because it prevents multiple pull requests from working on the same state.