Force Cancel Multiple Runs together using HCP Terraform API

Problem

In some situations, multiple HCP Terraform runs may become stuck in a pending state. This can block the workspace's execution queue, preventing new runs from starting. You need a method to cancel all stuck runs in bulk to clear the queue.

Prerequisites

Before you begin, ensure you have the following:

• An HCP Terraform user token or team token. You cannot use organization tokens for this operation.
• The Workspace ID for the workspace containing the stuck runs.
• The curl and jq command-line utilities installed on your local machine.

Procedure

Follow these steps to identify and cancel all pending runs in a specific workspace.

Step 1: Retrieve Pending Run IDs

First, execute a command to fetch all pending run IDs from your workspace and save them to a file. This command filters the runs API response to isolate the IDs of runs with a pending status.

Replace <WS-ID> with your actual Workspace ID.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/workspaces/<WS-ID>/runs | \
  jq | grep -e '"status": "pending"' -e '"id":' | \
  grep pending -B1 | grep id | awk -F '"' '{print $4}' > list_of_pending_runs.txt

After running the command, a file named list_of_pending_runs.txt will be created in your current directory. Verify that the run IDs in this file correspond to the correct runs in the HCP Terraform UI before proceeding.

Step 2: Create the Payload File

Create a file named payload.json with a comment to include with the cancellation request. This comment will be visible in the run's timeline.

{
  "comment": "This run was discarded via API to clear the queue."
}

Step 3: Cancel the Runs

Finally, execute a for loop that reads each run ID from list_of_pending_runs.txt and sends a request to the discard runs API endpoint for each one.

$ for i in $(cat list_of_pending_runs.txt); do \
  curl \
    --header "Authorization: Bearer $TOKEN" \
    --header "Content-Type: application/vnd.api+json" \
    --request POST \
    --data @payload.json \
    https://app.terraform.io/api/v2/runs/$i/actions/discard | jq; \
  done

This script iterates through the list and effectively cancels each pending run in the workspace.

Additional Information

• Note: The shell commands provided are for UNIX-based systems (like Linux or macOS). You may need to modify them for other operating systems, such as Windows.
• For more details on interacting with runs, refer to the Runs API documentation.