Demo Automating Runs with VCS Driven Workflow

This guide shows how to switch an HCP Terraform workspace from a CLI-driven workflow to a VCS-driven workflow so commits in your Git repository (for example, GitHub) automatically trigger Terraform runs. You’ll learn how to connect a workspace to a repository, configure VCS triggers and working directories, interpret speculative plans, and confirm applies. Table of contents

Preparing the repository and making the initial commit
Connecting the workspace to your VCS provider
Configuring trigger options and speculative plans
Making a code change to trigger a run
Reviewing, confirming, and applying the plan
Benefits and recommended settings

Preparing the repository and initial commit

In this example we started with a repository that only contained a .gitignore. Locally we added Terraform files (main.tf, providers.tf, variables.tf). The primary resources in main.tf looked like this:

resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_support   = true
  enable_dns_hostnames = true

  tags = {
    Name        = "dev-main-vpc"
    Environment = "development"
  }
}

resource "aws_subnet" "private" {
  vpc_id           = aws_vpc.main.id
  cidr_block       = var.private_subnet_cidr
  availability_zone = var.private_subnet_az

  tags = {
    Name = "main-subnet"
  }
}

Staged and pushed the files:

# Show staged files before committing
bk~$ git status
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    new file:   main.tf
    new file:   providers.tf
    new file:   variables.tf

# Commit and push the initial upload
bk~$ git add main.tf providers.tf variables.tf
bk~$ git commit -m "initial upload"
[main ad1ae35] initial upload
 3 files changed, 120 insertions(+)
bk~$ git push
Counting objects: 6, done.
Delta compression using up to 10 threads
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 945 bytes | 945.00 KiB/s, done.
Total 5 (delta 0), reused 0 (delta 0), pack-reused 0
To https://github.com/btkrausen/hcp-demo.git
   ad1ae35..6fb376a  main -> main
bk~$

Connecting the workspace to the repository

To convert a workspace from CLI-driven to VCS-driven:

Open the workspace in HCP Terraform: https://app.terraform.io
Go to Settings → Version Control.
Switch to “Version Control Workflow” (from CLI-driven).
Choose your VCS provider (GitHub, GitLab, Bitbucket, Azure DevOps) and follow the guided sign-in and authorization flow.
Select the repository and branch the workspace should track. Optionally set a Terraform working directory (leave blank for repository root).

A screenshot of the Terraform Cloud "Version Control" settings page for a workspace, showing the multi-step flow to connect to a VCS. The UI shows a dropdown selecting GitHub with other provider options (GitLab, Bitbucket, Azure DevOps) and the workspace settings sidebar on the left.

Follow the OAuth flow to authorize HCP to access your organization/repository. After authorization, configure the workspace to track the appropriate branch and (if needed) a subdirectory.

A screenshot of a Terraform Cloud workspace settings page (hcp-demo) showing Version Control linked to the GitHub repo btkrausen/hcp-demo. The page displays workspace settings like the Terraform working directory, auto-apply options, and VCS trigger types.

Trigger options and speculative plans

When you enable VCS integration you can configure how runs are created and what events trigger them: branch pushes, tags, pull requests, and more. You can also choose whether the workspace should auto-apply plans or require manual confirmation.

Branch-based runs: run on commits to specific branches.
Pull request speculative plans: preview changes without updating state.
Tag-based runs: useful for release-related automation.
Auto-apply: toggle to automatically apply successful plans (use carefully).

A screenshot of the Terraform Cloud workspace "Version Control" settings showing VCS Triggers, with the "Branch-based" option selected and fields for VCS branch, automatic run triggering, and pull request settings. The left sidebar lists workspace settings like General, Locking, Notifications, and Version Control.

After saving VCS settings, Terraform Cloud typically queues an initial plan to evaluate the repository contents against the workspace state. In our example the initial plan completed with no changes because the previously pushed configuration already matched the workspace state.

A screenshot of the Terraform Cloud workspace page for a workspace named "hcp-demo." It shows a run labeled "initial upload" that is “Planned and finished” with a plan result of “No changes.”

Making a code change and letting VCS trigger a run

We updated main.tf to add an Environment tag to both the private and public subnets. Example updated public subnet:

resource "aws_subnet" "public" {
  vpc_id                  = aws_vpc.main.id
  cidr_block              = var.public_subnet_cidr
  availability_zone       = var.public_subnet_az
  map_public_ip_on_launch = true

  tags = {
    Name        = "public-subnet"
    Environment = "development"
  }
}

Staged, committed, and pushed the change:

bk~$ git add main.tf
bk~$ git commit -m "adding environment tags"
[main e9daeed] adding environment tags
 1 file changed, 2 insertions(+)
bk~$ git push
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 10 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 297 bytes | 297.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (2/2), done.
To https://github.com/btkrausen/hcp-demo.git
   6fb376a..e9daeed  main -> main
bk~$

Because the workspace is VCS-connected, Terraform Cloud immediately queued a plan for this commit. The GitHub commit view shows the added tag lines in the diff:

@@ -14,6 +14,7 @@ resource "aws_subnet" "private" {
   availability_zone = var.private_subnet_az
   tags = {
     Name = "main-subnet"
+    Environment = "development"
   }
 }

@@ -24,5 +25,6 @@ resource "aws_subnet" "public" {
   map_public_ip_on_launch = true
   tags = {
     Name = "public-subnet"
+    Environment = "development"
   }
 }

Abridged plan output (showing the two subnet tag additions):

~ aws_subnet.private
  id : "subnet-0a250a84c0a2c54f9"

  ~ tags : {
      + Environment : "development"
      ... 1 unchanged attributes hidden
    }

  ~ tags_all : {
      + Environment : "development"
      ... 1 unchanged attributes hidden
    }
  ... 20 unchanged attributes hidden

~ aws_subnet.public
  id : "subnet-042bc17e0105dbd91"

  ~ tags : {
      + Environment : "development"
      ... 1 unchanged attributes hidden
    }

  ~ tags_all : {
      + Environment : "development"
      ... 1 unchanged attributes hidden
    }
  ... 20 unchanged attributes hidden

Confirming and applying the run

From the workspace run page you can inspect the speculative plan, review diffs, and either Confirm & Apply or discard. After you confirm, the run performs the apply step and updates the managed state. A new state version is recorded in the workspace’s States view.

A screenshot of the Terraform Cloud "hcp-demo" workspace States page showing recent state entries/runs (e.g., "adding environment tags", "Triggered via CLI"). The left sidebar shows workspace navigation (Overview, Runs, States, Variables, Settings) and a "New run" button appears at the top right.

Quick reference — VCS-driven workspace checklist

Step	Action
Connect VCS	Settings → Version Control → Authorize provider and select repo/branch.
Working directory	Set if your Terraform code lives in a subdirectory.
Trigger types	Choose branch-based, PR speculative plans, tags, etc.
Auto-apply	Enable to auto-apply successful plans; disable to require manual approval.
Review runs	Inspect speculative plans in the Runs view before applying.

Benefits of a VCS-driven workflow

Automated speculative plans for each commit or pull request.
Clear audit trail: commits + run history explain who changed what and why.
Safer reviews: PR previews allow teams to see proposed changes without touching state.
Optional auto-apply for trusted branches or CI releases.

This lesson demonstrated switching an HCP Terraform workspace from CLI-driven to VCS-driven, connecting to GitHub, pushing a change, and following the speculative plan → confirm → apply lifecycle. Explore additional HCP Terraform features for multi-workspace orchestration and advanced VCS patterns as next steps.

When a workspace is VCS-connected, each commit can trigger a speculative plan automatically. If you prefer not to auto-apply changes, leave auto-apply disabled so you can review and confirm plans before applying.

Course Introduction

Preparing Your Environment

Terraform Foundations

The Core Terraform Workflow

Terraform CLI

Terraform File Structure and Organization

Terraform Configuration - Fundamentals

Understading and Managing Terraform State

Marking Code Reusable

Refactoring Terraform State

Terraform Modules

Managing Resource Behavior and Dependencies

Securing Terraform Configurations

Terraform Troubleshooting

HCP Terraform

Demo Automating Runs with VCS Driven Workflow

Preparing the repository and initial commit

Connecting the workspace to the repository

Trigger options and speculative plans

Making a code change and letting VCS trigger a run

Confirming and applying the run

Quick reference — VCS-driven workspace checklist

Benefits of a VCS-driven workflow

Watch Video

​Preparing the repository and initial commit

​Connecting the workspace to the repository

​Trigger options and speculative plans

​Making a code change and letting VCS trigger a run

​Confirming and applying the run

​Quick reference — VCS-driven workspace checklist

​Benefits of a VCS-driven workflow

Watch Video

Preparing the repository and initial commit

Connecting the workspace to the repository

Trigger options and speculative plans

Making a code change and letting VCS trigger a run

Confirming and applying the run

Quick reference — VCS-driven workspace checklist

Benefits of a VCS-driven workflow