Viewing and Managing Runs
Each workspace in Terraform Cloud includes a list of its current, pending, and historical runs. You can view and interact with these runs in the UI. You can also lock workspaces to temporarily prevent new runs.
API
Refer to the Runs API and lock a Workspace endpoint.
Navigating Runs
Go to the workspace and click the Runs tab to review a list of all current and past Terraform runs.
Click a run to go to its details page. The details page contains the following information:
- The current status of the run.
- The code commit associated with the run.
- How the run initiated, when, and which user initiated it (if applicable).
- A timeline of events related to the run.
- The output from both the
terraform planandterraform applycommands, if applicable. This output defaults to visible if the command is currently running and hidden if the command has finished.
Interacting with Runs
In workspaces where you have permission to apply runs, you can interact with a run at the bottom of its details page.
The following options are available, depending on the state of the run:
| Button | Available when: |
|---|---|
| Add Comment | Always. |
| Confirm & Apply | A plan needs confirmation. |
| Override & Continue | A soft-mandatory policy failed. Requires permission to manage policy overrides for the organization. |
| Discard Run | A plan needs confirmation or a soft-mandatory policy failed. |
| Cancel Run | A plan or apply is currently running. |
| Force Cancel Run | A plan or apply canceled, but Terraform Cloud was unable to end the run. Requires admin access to the workspace. |
| Retry Run | A plan-only run has finished. You can also change which Terraform version to use when retrying a plan-only run. |
If a plan needs confirmation (with manual apply enabled) or a soft-mandatory policy failed, the run remains paused until a user with appropriate permissions uses these buttons to continue or discard the run. Refer to Run States and Stages for more details.
Canceling Runs
If a run is currently planning or applying, users with permission to apply runs for the workspace can click Cancel Run to stop the run before it finishes.
Canceling a run is roughly equivalent to typing ctrl+c during a Terraform plan or apply on the CLI. The running Terraform process is sent an INT signal, which instructs Terraform to end its work, update state for any resources that have already been changed, and wrap up in the safest way possible.
In rare cases, a canceled run can fail to end, continuing to lock the workspace. You can forcefully cancel these runs, which immediately terminates the running Terraform process and unlocks the workspace.
Force-canceling requires admin access to the workspace because it can have dangerous side-effects, including loss of state and orphaned resources. Additionally, the Force Cancel Run button only appears after you click Cancel Run and Terraform Cloud has time to terminate the run safely.
Locking Workspaces (Preventing Runs)
You can lock the workspace to temporarily stop runs from being queued. Locking a workspace requires permission to lock and unlock the workspace.
A lock prevents Terraform Cloud from performing any plans or applies in the workspace. This lock includes automatic runs due to new commits in the VCS repository, manual runs queued via the UI, runs started on the command line with terraform plan and terraform apply, and runs created with the API. New runs remain in the Pending state until the workspace unlocks.
Terraform Cloud shows the lock status in the workspace's header, next to the Actions menu.
To lock or unlock a workspace, do one of the following:
- Open the Actions menu and select Lock workspace or Unlock workspace.
- Go to Settings > Locking.