AI
Choosing Between Three Terraform Workflow Types
HCP Terraform offers three workspace types when you create a new workspace: VCS-driven, CLI-driven, and API-driven. That choice determines how runs are triggered and where they execute. Ting Li frames the decision around four factors: setup effort, day-two maintenance effort, security considerations, and the technical skill the team must bring. No single type fits every organization. The right answer depends on project requirements and what the application teams can actually operate.
VCS-Driven Workflow: Branch Strategy Is the Real Work
VCS-driven workspaces map each workspace to a repository branch. HCP Terraform sets a webhook, so any commit triggers a run automatically. Pull requests get speculative plans. Setup looks simple on paper — connect your VCS provider, configure branches — but branch strategy decisions compound fast: dev, staging, and production environments, how merges flow between them, who clicks approve. Teams using mono-repos need extra thought here. The security side is also concrete: when the person who configured the VCS provider connection leaves the company, the integration needs to keep working.
“very easy to adopt and skill does not ask you” — Ting Li
The pattern fits teams that want straightforward provisioning without heavy Terraform expertise.
CLI-Driven Workflow: Running Remotely from a Local Terminal
CLI-driven workspaces run terraform plan and terraform apply from a local machine, but execute in HCP Terraform. State files stay remote. Progress appears in both the terminal and the HCP Terraform UI. The main use cases are custom CI/CD pipelines (Jenkins, GitHub Actions) where teams want HCP Terraform for state and policy enforcement but not run orchestration, and migrations from community Terraform. Teams moving from the open-source version can keep their existing command lines intact. Nothing changes except where the run executes. The credential management burden is higher: API tokens must be secured wherever the local CLI runs.
API-Driven Workflow: Full Control, Full Responsibility
API-driven workspaces connect to nothing by default — no VCS provider, no webhook. Third-party tools like ServiceNow or HCP Waypoint call the Terraform API directly to create workspaces, upload configuration, and trigger runs. Teams that want fine-grained control over when runs happen, enforce their own audit logging, or lock down HCP Terraform access to a central platform choose this path.
“needed to pay your debt, right? You need” — Ting Li
The cost is real: every piece of error handling, retry logic, and credential rotation belongs to the team writing the scripts. Workspaces and environments are managed programmatically, so less human touch also means fewer guardrails are built in.
TFCI and GitHub Actions Demo
TFCI is a Go-based wrapper HashiCorp wrote around the Terraform API, built to integrate with GitHub Actions and GitLab. Ting Li walked through the TFCI GitHub Actions demo (22:55) using a recorded six-minute session. The flow: create an API-driven workspace in HCP Terraform, store the HCP Terraform API token as a GitHub Actions secret, then define two workflow files. On a pull request, GitHub Actions uploads Terraform config to HCP Terraform, creates a speculative run (plan only), and posts results back to GitHub. On merge, the same jobs run but execute a full apply. Users never leave GitHub to see plan output or approve changes.
Notable Quotes
There’s no best workflow. There’s no Ting Li · ▶ 29:02
just make an order. You are the chef Ting Li · ▶ 19:38
needed to pay your debt, right? You need Ting Li · ▶ 17:47
very easy to adopt and skill does not ask you Ting Li · ▶ 9:56
Key Takeaways
- No single Terraform workflow fits every team — match setup complexity to actual project requirements.
- VCS-driven is the default starting point; CLI-driven is the lowest-disruption migration path from community Terraform.
- API-driven workflows give full programmatic control but require custom error handling, credential management, and audit logging.