Terraform Cloud VCS Workflow: GitHub and GitLab Integration (2026)

Terraform Cloud’s VCS workflow doesn’t actually check out your code from Git; it polls your repository for changes.

Let’s see what that looks like in practice. Imagine you have a Terraform file, main.tf, in your GitHub repository:

resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0" # Example AMI ID
  instance_type = "t2.micro"

  tags = {
    Name = "HelloWorld"
  }
}

You’ve configured Terraform Cloud to connect to this GitHub repository. When you push a change to main.tf, say, changing instance_type to "t3.small", Terraform Cloud detects this push. It doesn’t git clone your repo. Instead, it uses the GitHub API to get a snapshot of your repository’s HEAD at that commit. It then runs terraform plan using that snapshot. If the plan is successful, it prompts you to apply it.

The core problem Terraform Cloud’s VCS workflow solves is bridging the gap between your declarative infrastructure-as-code and the actual execution environment. It provides a centralized, auditable, and collaborative way to manage Terraform runs. Internally, when you connect a VCS repository, Terraform Cloud establishes a webhook with your Git provider. This webhook triggers an event in Terraform Cloud whenever a specified branch is pushed to. Terraform Cloud then fetches the specific commit referenced by the push. It uses this commit’s content to perform the terraform plan operation within its own execution environment. If you approve the plan, it then performs the terraform apply on the same code snapshot.

The key levers you control are:

• VCS Branch: You define which branch Terraform Cloud monitors. Pushes to this branch trigger new runs.
• Working Directory: If your Terraform code isn’t at the root of your repository, you specify the subdirectory where main.tf resides.
• Triggering Commits: You can configure whether runs are triggered by any commit to the branch or only by commits that have a specific tag pattern.
• Automatic Speculative Plans: You can enable this to have Terraform Cloud automatically run terraform plan on pull requests targeting your monitored branch, providing immediate feedback without requiring a manual trigger.

The most surprising thing about the VCS workflow is how it handles secrets and sensitive data. It doesn’t store your secrets directly. Instead, when Terraform Cloud needs to access cloud provider credentials (like AWS access keys), it retrieves them from its own secure credential store. These credentials are then injected into the Terraform execution environment as environment variables for the duration of the run. This means your sensitive data never sits in your Git repository, even if you’re using a backend.tf file that might otherwise expose your state bucket name. Terraform Cloud’s agent fetches the necessary credentials from its vault before executing plan or apply.

The next step in understanding this workflow is exploring how to integrate custom variables and environment settings for your Terraform runs.