Skip to main content
Now that the Terraform state has been migrated into an HCP (Terraform Cloud) workspace and the workspace is managing both state and configuration, the next step is converting that workspace from a CLI-driven workflow to a VCS-driven workflow. With a VCS-driven workspace, commits to your Git repository automatically trigger Terraform runs (plans) in the workspace, and pull requests can trigger speculative plans for previewing changes.
The image shows a dashboard for a Terraform Cloud workspace named "hcp-demo," displaying details about the latest run triggered via CLI, along with resource and execution metrics.
Overview — high-level steps
  • Push your Terraform configuration to a Git repository (e.g., GitHub).
  • Configure your Terraform Cloud workspace to use that repository and branch.
  • Commits to the configured branch will trigger runs (plans) automatically; pull requests can trigger speculative plans.
  • Review and optionally apply plans from the Terraform Cloud UI or enable Auto-Apply for automatic applies.
Preparing your repository
  1. Confirm the repository contains the Terraform files you want Terraform Cloud to run.
  2. Push the files to the branch that the workspace will monitor.
Example: verify local git status 
# local repository
git status
Sample output: 
On branch main
No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        main.tf
        providers.tf
        variables.tf
Initial Terraform configuration Below is the initial main.tf used in this demo — a simple VPC and a private subnet. 
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"
  }
}
Stage and push these files to your remote repository: 
git add main.tf providers.tf variables.tf
git commit -m "initial Terraform configuration"
git push origin main
Successful push feedback (example): 
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), 945 bytes | 945.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
To https://github.com/your-org/hcp-demo.git
   adlae35..6fb376a  main -> main
Configure the workspace to use VCS
  1. In Terraform Cloud, open the workspace.
  2. Go to Settings → Version Control.
  3. Connect or select your VCS provider (GitHub, GitLab, Bitbucket, Azure DevOps, etc.).
  4. Pick the repository and branch you pushed your code to, and save the settings.
The image shows a web interface for configuring version control settings in Terraform Cloud, where a repository is being selected for hosting Terraform source code.
VCS configuration options
  • Working directory: set a subdirectory if your Terraform root is not at the repository root (leave blank for root).
  • Auto-apply: enable to automatically apply successful plans.
  • Trigger type: branch or tag based; pull request behavior (speculative plans) depends on provider and integration settings.
Connecting a workspace to VCS enables automatic plans whenever commits are pushed; pull requests can trigger speculative plans. You can enable Auto-Apply to apply changes automatically after a successful plan, but it’s common to require manual approval for production-sensitive workspaces.
First run after connecting VCS As soon as the workspace is connected to the repository and branch, Terraform Cloud queues an initial plan. This first run maps the repository configuration to the state currently managed by the workspace. In many cases this initial plan will report no changes if the state and configuration already match.
The image shows a Terraform Cloud web interface with a workspace titled "hcp-demo." It displays details about the latest run, resources, and settings.
Demonstrating an update via VCS To demonstrate how commits trigger runs, update your local configuration (for example, add environment tags to the private subnet and create a public subnet). The updated portion of main.tf: 
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"
    Environment = "development"
  }
}

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"
  }
}
Commit and push the changes: 
git status
git add main.tf
git commit -m "add environment tags and public subnet"
git push origin main
Example push output: 
Counting objects: 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
To https://github.com/your-org/hcp-demo.git
   6fb376a..e9daeed  main -> main
Automatic runs and reviewing plans After the push completes, Terraform Cloud detects the commit and automatically triggers a run for the workspace. If this change were part of a pull request, Terraform Cloud would present a speculative plan tied to that PR. Each run is associated with the commit that triggered it so you can see exactly what Terraform will change.
The image shows a Terraform Cloud interface displaying run details of a plan that changed subnet tags to "development," with a focus on AWS subnets configuration.
From the run details you can:
  • Review the plan, then click Confirm & Apply to execute the changes, or
  • Enable Auto-Apply so successful plans are applied automatically.
I chose Confirm & Apply in this demo. Terraform Cloud executed the apply, updated the workspace state, and created a new state version. You can verify the new state under the workspace States tab. Benefits of a VCS-driven Terraform workflow
BenefitDescription
Versioned IaCKeep your infrastructure-as-code in Git with commit history and diffs.
Automated runsCommits trigger plans automatically; PRs can trigger speculative plans for pre-merge validation.
Auditing & visibilitySee who triggered runs and why; Terraform Cloud logs runs and state versions for compliance.
Flexible apply workflowsChoose manual Confirm & Apply for control or Auto-Apply for automation.
Links and references Next steps With the workspace now VCS-connected, you can extend this pattern to:
  • Create additional workspaces per environment (dev, staging, prod),
  • Use workspace variables and policies to enforce guardrails,
  • Integrate CI/CD pipelines to manage more complex workflows.
Now that the workspace is VCS-driven, subsequent changes to infrastructure will be governed by commits and PR workflows, improving collaboration, traceability, and automation.

Watch Video