Skip to main content
In this guide, you’ll learn how to integrate Terraform Cloud with GitHub to manage infrastructure across development, staging, and production environments. You will:
  1. Create development and staging branches in GitHub
  2. Configure a shared Terraform Cloud variable set for AWS credentials
  3. Point the development workspace to the development branch
  4. Provision a staging workspace on the staging branch
  5. Trigger and verify runs in each workspace
  6. Create a production workspace on the main branch
  7. Confirm all workspaces and their run statuses
  • 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 NameCategoryDescription
AWS_ACCESS_KEY_IDEnvironment VariableYour AWS access key
AWS_SECRET_ACCESS_KEYEnvironment VariableYour AWS secret key
This centralizes AWS credentials for all workspaces in your organization.
Never commit AWS credentials to Git. Always use Terraform Cloud variable sets or Vault for secret management.

​
3. Update the Development Workspace

  1. Open the devops-aws-myapp-dev workspace in Terraform Cloud.
  2. Go to Settings → Version Control.
  3. 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

  1. In Terraform Cloud, select Workspaces → New Workspace.
  2. Choose Version Control Workflow and connect to gmaentz/clumsy_bird.
  3. Configure the workspace:
SettingValue
Namedevops-aws-myapp-staging
VCS Branchstaging
Auto ApplyEnabled
Automatic Speculative PlansEnabled
  1. (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.
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:
SettingValue
Namedevops-aws-myapp-prod
VCS Branchmain
Auto ApplyEnabled (or Manual per policy)
Always Trigger RunsEnabled
  1. Workspaces → New Workspace → Version Control
  2. Select gmaentz/clumsy_bird and set VCS Branch to main.
  3. 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 NameBranchStatus
devops-aws-myapp-devdevelopmentApplied
devops-aws-myapp-stagingstagingApplied
devops-aws-myapp-prodmainPending / 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.

​
References

Watch Video

Practice Lab