Solution skill
Terraform workflow: set up an HCP Terraform VCS-driven workspace from scratch
Complete solution
Connecting a workspace to version control gives speculative plans, run history, and policy checks. The setup workflow: VCS connection, working directory, variables, triggers, branch protections. Not the full reference manual.
TL;DR: Connecting a workspace to version control gives speculative plans, run history, and policy checks. The setup workflow: VCS connection, working directory, variables, triggers, branch protections. Create the workspace in the right project. Set the Terraform working directory to the config subdirectory if the repo is a monorepo.
When
A new service or environment needs the full HCP workflow: plans on PRs, applies on merge, variable management, and policy checks.
Steps
- Create the workspace in the right project. Set the Terraform working directory to the config subdirectory if the repo is a monorepo.
- Connect the VCS repo and set the trigger patterns: which branches and paths trigger runs.
main-only applies with PR speculative plans is the standard. - Set the execution mode: Remote for consistency, Agent if runs need private network access. This decision is load-bearing; make it deliberately.
- Add variables: non-sensitive as Terraform variables, secrets as sensitive variables or via a variable set shared across the project's workspaces.
- Wire run triggers for upstream/downstream workspace ordering (network applies before app plans).
- Enable speculative plans on PRs and cost estimation. Require the plan status check in branch protection.
- Test the loop: open a no-op PR (whitespace), confirm the speculative plan runs and posts; merge, confirm the apply run triggers.
Rules for agents
- The working directory setting is the most common misconfiguration. A workspace pointed at the repo root when the config lives in
terraform/plans nothing or plans the wrong thing. - Do not connect the workspace to a branch developers push to directly. The VCS flow assumes PR review; direct pushes bypass it.
- Variable sets over per-workspace variables for anything shared. Per-workspace copies drift; this was decided in the variable-sets skill.
- After setup, the workspace should never need local runs. If someone is running
terraform applylocally against this workspace's state, the workflow is broken; fix the workflow, not the person.
When to use this
- This covers exactly what the title says: Terraform workflow.
- You are setting this up for the first time, or auditing an existing setup.
- You want the key gotchas in one place before you start.
When not to use this
- You are doing a different workflow with Terraform; these steps are specific to the title above.
- You need the full reference docs; this is the short path, not the manual.
Evidence
HCP workspaces connect to VCS with working directory, trigger patterns, execution modes, variable sets, run triggers, and speculative plans. Verified against live docs 2026-09-26.
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_qjYaIueJcmPOJwme7UIqMQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Terraform workflow: set up an HCP Terraform VCS-driven workspace from scratch <span>— Vectle</span></a>