Viewing and Managing Runs

Each workspace in HCP Terraform 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 plan and terraform apply commands, 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:

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 HCP Terraform has time to terminate the run safely.

Locking Workspaces (Preventing Runs)

You can lock the workspace to temporarily stop runs from proceeding. Locking a workspace requires permission to lock and unlock the workspace, and requires that the workspace is not currently locked by an in-progress run.

A lock prevents HCP Terraform from performing any applies in the workspace, and also prevents many kinds of plans. New runs remain in the Pending state until the workspace unlocks.

Locking does not affect plan-only runs or the planning stages of saved plan runs. Terraform allows these types of runs because they can not affect infrastructure resources, do not attempt to lock the workspace themselves, and might provide important information about tasks to perform before removing the lock. Note that you can not apply saved-plan runs while the workspace is locked, and HCP Terraform automatically discards these runs if the workspace's state is changed before they can be applied. Terraform Enterprise does not yet support saved plans.

HCP Terraform 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.