# Run your Terraform workspace audit from one live board

> See every HCP Terraform workspace grouped by project, spot the stale, outdated and locked ones, and clean them up without leaving the page.

- Workflow type: app
- Services: HCP Terraform (Terraform Cloud), Google Sheets
- Categories: Engineering, Operations
- Published: 2026-08-24

## What it does

- Puts every workspace in your Terraform organization on one screen, grouped by project, showing its Terraform version, last run result, how long ago it ran, lock state, and source repo.
- Saved views pull out the workspaces worth acting on: nothing successful in 90 days, stuck on an old Terraform version, or still locked by someone who has moved on.
- Fix things in place with row buttons: lock or unlock a workspace, force a stuck lock open, queue a fresh plan, or change the Terraform version and auto apply setting.
- Hit Audit on any row and a background assistant reviews that workspace's recent runs, variables and outputs, then writes a short keep, upgrade or retire recommendation back onto the row. Export snapshot files the whole table into a dated Google Sheets tab so every review is on the record.

## What you'll need

- An HCP Terraform login with access to the organization you want to review
- Permission to lock, unlock and start runs if you want to use the row buttons (read-only access still gives you the full board)
- A Google account and a spreadsheet where the dated snapshots should be saved

## Prompt

Build me a workspace fleet board for our HCP Terraform organization. It replaces the spreadsheet our platform team rebuilds by hand every quarter to audit workspace sprawl. The people who open it are the infra lead running the review and anyone on the team who needs to know the state of a workspace before touching it.

Main view: one dense table of every workspace, grouped by project. Use List Workspaces to pull the full organization list (page through it, 100 per page) and List Projects to resolve project names, then render rows under sticky project headers with a workspace count on each header. Columns: workspace name, Terraform version, auto apply on or off, source VCS repo with branch (blank for CLI driven workspaces), lock state including who or what currently holds the lock, last run status, and how long ago that run finished shown as relative time like 3 days ago. Add a text search across workspace name and repo, plus sortable columns. Clicking a row opens a detail drawer backed by Show Workspace with the full settings and current run summary.

Run recency needs List Workspace Runs per workspace, so fetch it in batches with a sensible concurrency limit rather than blocking the page: render the table as soon as workspaces and projects load, then fill the last run status and age columns progressively with a subtle loading state. For each workspace keep both the most recent run of any status and the most recent successful run, since the staleness filter depends on the successful one. Cache the run lookups in the handler so re-filtering does not refetch everything.

Saved filters as chips above the table, each showing a live count. Stale: no successful run in the last 90 days, and include workspaces that have never had a successful run at all. Outdated Terraform: pinned to a version below the baseline version set in settings. Abandoned locks: locked for more than 7 days, surfacing the lock holder so the reviewer can tell whether that person is still around. The 90 day window, the version baseline and the lock age threshold all live in a small settings panel and persist between sessions.

Inline row actions, each with a confirmation step and an optimistic row refresh afterwards: Lock Workspace with an optional reason, Unlock Workspace, Force Unlock Workspace behind an extra confirmation that names the current lock holder and warns that it clears someone else's lock, Create Run to queue a fresh plan only run (never auto apply from the board, and set the run message so it is obvious it came from the fleet board), and Update Workspace to bump the Terraform version or toggle auto apply. Allow selecting several rows to queue plans in bulk. If the token lacks permission for an action, keep the button visible but disabled with a short explanation rather than hiding it.

Every row has an Audit this workspace button that kicks off a background agent for that one workspace. The agent pulls the workspace details with Show Workspace, its recent history with List Workspace Runs, its inputs with List Workspace Variables, and its current state with Get Current Workspace Outputs. It then writes back a verdict of keep, upgrade or retire, two to four bullet reasons grounded in what it actually saw (date of the last successful run, size of the Terraform version gap, repeated run failures, outputs that look like nothing consumes them, variables that look like placeholders or leftovers from a spike), and a suggested next action. Persist the result against the workspace id with a timestamp so it renders on the row as a verdict badge with an expandable panel, and survives a page reload. Show a queued or running state on the row while the agent works, and let several audits run at once.

An Export snapshot button appends whatever is currently visible, respecting the active filter and sort, to a Google Sheets tab using Append Values. One row per workspace with a leading snapshot date column, then the same columns as the board plus the latest audit verdict if one exists. Remember the spreadsheet and tab between exports, write a header row if the tab is empty, and confirm how many rows were appended. The point is a dated record of each quarterly review sitting next to the previous ones.

Degrade gracefully on permissions. HCP Terraform returns the same not found response for a resource that does not exist and one the token is not allowed to read, so a single unreadable workspace must never break the board: mark that row as no access, keep the rest rendering, and count them somewhere visible. The audit agent should do the same, saying plainly which parts it could not read and still giving a recommendation with lower confidence rather than failing.

Two constraints to respect. Do not show or promise drift detection or health assessment data anywhere in the app, there is no health assessment data available here. Staleness must be derived only from run recency via List Workspace Runs. And keep the table readable at a hundred plus rows: compact spacing, sticky headers, no truncation of workspace names that makes them ambiguous.

## How to customize

- Change the staleness window from 90 days to whatever your team treats as abandoned
- Set the Terraform version you consider current so the outdated view flags the right workspaces
- Point the export at a different spreadsheet or tab, and add the columns your review actually cares about

## FAQ

### Does this show infrastructure drift or health checks?

No. The board reports what your Terraform organization already records: runs, versions, locks, variables, outputs and repos. Staleness is worked out from when a workspace last finished a successful run, not from any drift or health assessment.

### Why do some workspaces show up as no access?

Terraform does not tell you whether a workspace is missing or simply outside your permissions, it answers the same way for both. When that happens the board marks the row instead of failing, so the rest of your fleet still loads.

### Can it delete workspaces I decide to retire?

No. Nothing on the board deletes anything. Retire is a written recommendation with reasons attached to the row, and removing the workspace stays a deliberate step you take yourself.

### Will it work with hundreds of workspaces?

That is the case it is built for. A flat list of hundreds of workspaces is unusable, so the board groups rows by project the same way Terraform does, with counts and filters on top.

### Is force unlock safe to use?

It clears a lock no matter who holds it, so it is meant for locks left behind by a departed teammate or a run that died. The button asks for confirmation and tells you who currently holds the lock before it goes through.

### Why bother cleaning up unused workspaces?

Beyond the clutter, Terraform pricing is now tied to things like how many workspaces and managed resources you keep, so retiring the ones nobody has run in months takes real money off the bill.

Use this prompt in General Input: https://www.generalinput.com/prompts/run-your-terraform-workspace-audit-from-one-live-board