Lab Solution Version Control Branching and Workspaces

In this guide, you’ll learn how to integrate Terraform Cloud with GitHub to manage infrastructure across development, staging, and production environments. You will:

Create development and staging branches in GitHub
Configure a shared Terraform Cloud variable set for AWS credentials
Point the development workspace to the development branch
Provision a staging workspace on the staging branch
Trigger and verify runs in each workspace
Create a production workspace on the main branch
Confirm all workspaces and their run statuses

Prerequisites

A Terraform Cloud organization and Terraform CLI installed.
A GitHub repository (clumsy_bird) containing your Terraform configurations.

1. Create Development and Staging Branches

Clone your GitHub repository, then create and push the feature branches:

git clone https://github.com/your-org/clumsy_bird.git
cd clumsy_bird
git checkout -b development
git push -u origin development
git checkout main
git checkout -b staging
git push -u origin staging

Alternatively, use the GitHub UI to add the development and staging branches.

The image shows a GitHub repository page with a branch selection dropdown open, displaying branches "main" and "development." The repository is named "clumsy_bird" and contains several Terraform configuration files.

2. Configure a Terraform Cloud Variable Set

In Terraform Cloud, navigate to Organization Settings → Variable Sets and create or verify a set containing:

Variable Name	Category	Description
`AWS_ACCESS_KEY_ID`	Environment Variable	Your AWS access key
`AWS_SECRET_ACCESS_KEY`	Environment Variable	Your AWS secret key

This centralizes AWS credentials for all workspaces in your organization.

Security Best Practice

Never commit AWS credentials to Git. Always use Terraform Cloud variable sets or Vault for secret management.

3. Update the Development Workspace

Open the devops-aws-myapp-dev workspace in Terraform Cloud.
Go to Settings → Version Control.
Change VCS Branch to development and Save.

Terraform Cloud will automatically queue and apply a run on the development branch:

The image shows a KodeKloud lab interface for version control branching and workspaces, with instructions to navigate a workspace on Terraform Cloud. The left side displays task steps, while the right side features a terminal window.

The image shows a Terraform Cloud workspace settings page, specifically the Version Control section, indicating a connection to a GitHub repository named "gmaentz/clumsy_bird."

The image shows a version control settings page for a Terraform Cloud workspace, with options for configuring VCS branch, pull requests, and other settings like including submodules on clone.

The image shows a Terraform Cloud interface with a workspace named "devops-aws-myapp-dev" that is currently in the "Applying" status. The interface includes options for managing workspaces, registry, and settings.

4. Create the Staging Workspace

In Terraform Cloud, select Workspaces → New Workspace.
Choose Version Control Workflow and connect to gmaentz/clumsy_bird.
Configure the workspace:

Setting	Value
Name	devops-aws-myapp-staging
VCS Branch	staging
Auto Apply	Enabled
Automatic Speculative Plans	Enabled

(Optional) Add Terraform variables for environment context:

prefix      = "clumsy"
project     = "Clumsy Bird"
environment = "staging"

The image shows a Terraform Cloud interface for creating a new workspace, with options to choose a workflow type such as version control, CLI-driven, or API-driven. The sidebar includes navigation options like Workspaces, Registry, and Settings.

The image shows a Terraform Cloud interface where a user is choosing a repository from a list, with "gmaentz/clumsy_bird" highlighted. The interface includes navigation options and a filter for repositories.

The image shows a Terraform Cloud interface for creating a workspace, with options for triggering runs, specifying a VCS branch, and configuring pull requests and other settings. A "Create workspace" button is highlighted.

The image shows a HashiCorp Cloud Platform interface where a workspace has been created, prompting the user to configure Terraform variables such as prefix, project, and environment.

Save and monitor the initial plan/apply run.

5. Trigger Manual Runs

To validate both environments:

Development: Open devops-aws-myapp-dev and click Start new run.
Staging: Open devops-aws-myapp-staging and click Start new run.

Manual vs. Auto Apply

Auto Apply simplifies continuous delivery, but manual runs offer more control for production-critical changes.

6. Create the Production Workspace

Repeat the workspace creation steps for production:

Setting	Value
Name	devops-aws-myapp-prod
VCS Branch	main
Auto Apply	Enabled (or Manual per policy)
Always Trigger Runs	Enabled

Workspaces → New Workspace → Version Control
Select gmaentz/clumsy_bird and set VCS Branch to main.
Add the same Terraform variables (prefix, project, environment = "production").

The image shows a GitHub repository page for a project named "clumsy_bird," with a dropdown menu for switching branches, displaying "main," "development," and "staging" branches. The repository contains files related to Terraform configuration.

Save the workspace to kick off the initial production run.

7. Verify All Workspaces

Head to Workspaces overview. You should see all three environments configured:

Workspace Name	Branch	Status
devops-aws-myapp-dev	development	Applied
devops-aws-myapp-staging	staging	Applied
devops-aws-myapp-prod	main	Pending / Applied

The image shows a Terraform Cloud interface displaying a list of workspaces with their names, run statuses, repositories, and the time of the latest changes. Two workspaces have the status "Applied."

Congratulations! You’ve successfully implemented version control branching strategies and workspace management in Terraform Cloud. Next, explore GitOps-native workflows with Terraform Enterprise or integrate policy as code using Sentinel.