Implementing Terraform Cloud Workspaces with VCS Integration

Terraform Cloud workspaces provide a managed execution environment for infrastructure as code, while version control system (VCS) integration connects Terraform runs to a Git repository. Together, they create a repeatable workflow in which a pull request can trigger a plan, authorised changes can be applied consistently, and state remains outside individual administrators’ laptops.

This model suits teams managing AWS accounts, VMware clusters, networking, identity services, and hybrid infrastructure. It also gives system administrators a clear audit trail for who changed a configuration, which commit produced a run, and whether policy checks passed before deployment.

For Australian organisations, design decisions often include AWS regions such as Sydney and Melbourne, data residency expectations, APRA controls, and operational teams working across AEST and AWST. A sensible workspace layout can support those requirements without turning every environment into a separate, difficult-to-maintain codebase.

Preparing the repository and Terraform Cloud organisation

Start with a repository structure that separates reusable modules from live environment configuration. A common pattern is to keep modules in one repository and create directories such as live/dev, live/test, and live/prod in another. Each workspace can then point to a specific working directory while sharing the same module source and review process.

Terraform Cloud needs access to the selected GitHub, GitLab, Bitbucket, or Azure DevOps repository. An organisation administrator establishes the VCS connection, usually through an OAuth application or an equivalent integration. Use a dedicated repository rather than a personal project so staff changes do not silently break the connection when someone moves teams.

Before connecting a workspace, verify that the repository contains a valid Terraform configuration, a .terraform-version file if version pinning is required, and documented input variables. Pin provider versions and module versions wherever possible. This is particularly useful when a Brisbane or Perth operations team runs changes outside Sydney business hours and needs predictable behaviour without an emergency provider upgrade.

Creating workspaces and choosing the execution model

Create a workspace for a meaningful deployment boundary, such as network-prod-au-syd or shared-services-test-au-mel. A workspace should generally represent one state file and one lifecycle. Avoid placing unrelated VPCs, databases, and Kubernetes clusters in the same state unless they must always be changed together.

During workspace creation, choose “Version control workflow” and select the repository, branch, and working directory. The branch normally maps to the environment’s protected branch, while feature branches are used for pull requests and speculative plans. Terraform Cloud can then report the plan against the proposed commit before a merge reaches the deployment branch.

The execution mode determines where Terraform commands run. Terraform Cloud-hosted agents are convenient for public cloud APIs, while self-hosted agents are valuable when Terraform must reach private vSphere networks, internal DNS, or restricted management endpoints. An agent pool can also help keep sensitive execution inside an Australian network boundary, subject to the organisation’s compliance and architecture requirements.

Authentication should use short-lived credentials where available. For AWS, configure workload identity or another federated approach instead of committing access keys to variables. Store credentials and sensitive values as workspace or variable-set secrets, mark them sensitive, and limit access through teams and project permissions.

Connecting VCS events to safe change management

A VCS-driven workflow works best when Terraform Cloud is integrated with pull requests. A developer changes a security group rule or an AWS route, pushes the branch, and receives a speculative plan. Reviewers can inspect resource additions, deletions, and replacements before approving the merge.

Configure automatic runs for the main branch and require confirmation for production applies. In lower environments, automatic apply may be acceptable after a successful plan and policy check. In production, a human approval step provides a useful control for regulated workloads and reduces the chance of an incorrect variable or broad resource replacement reaching an important account.

Use branch protection and mandatory status checks in the source repository. Require at least one infrastructure reviewer for material changes, and use CODEOWNERS to route networking, identity, or platform changes to the right specialists. A clean Git history makes incident analysis easier than a collection of local commands run from an administrator’s workstation.

For hybrid estates, workspace outputs can feed other configurations, but dependencies should remain explicit. If an on-premises server needs management through AWS Systems Manager, the activation and connectivity design should be treated as part of the platform architecture; the hybrid activation guide provides useful context for that pattern.

Managing variables, state, and policy controls

Variable sets are useful for values shared across several workspaces, such as AWS account metadata, standard tags, proxy settings, or approved regions. Keep environment-specific values in the individual workspace. This prevents a development change from accidentally altering production and makes the source of each setting easier to trace.

Use remote state locking and state version history supplied by Terraform Cloud. Do not manually edit state unless recovery procedures require it, and document any state migration or resource import. Imports should be reviewed like normal code because they can change future plans and create an unexpected dependency between a resource and its Terraform address.

Policy as code adds another safeguard. Sentinel or OPA-based controls can reject public storage, unapproved instance types, missing tags, or resources deployed outside approved Australian regions. For organisations following the Essential Eight or APRA-aligned controls, policy checks should complement identity and logging controls rather than being treated as a complete compliance solution.

Workspace notifications can send run results to email, Slack, Microsoft Teams, or an incident platform. Configure alerts for failed applies, drift detection, and policy violations. A useful alert should identify the workspace, commit, resource category, and failure stage so the on-call engineer can act quickly during an early-morning maintenance window.

Recommendations for reliable workspace operations

A small operating standard keeps Terraform Cloud workspaces consistent as the estate grows. Names should identify the platform, environment, and region without depending on an individual’s initials. For example, payments-prod-au-mel is more useful than terraform-prod-3.

Schedule drift detection for important workspaces and investigate changes made through the AWS console, Azure portal, or vCenter. Manual changes may be necessary during an outage, but they should be reconciled into code afterwards. This habit prevents the familiar “it worked last arvo” problem where the state file and actual infrastructure gradually diverge.

Use the following practices when rolling out VCS-connected workspaces:

• Pin Terraform, provider, and module versions, then upgrade them through reviewed pull requests.
• Separate development, testing, and production state into distinct workspaces and cloud accounts where practical.
• Use workspace variable sets for shared non-secret configuration and secure variables for credentials or tokens.
• Require plan review and explicit approval before production applies.
• Test agent connectivity, private DNS, proxy access, and outbound firewall rules before migrating hybrid workloads.

Treat the first few workspace migrations as a controlled pilot. Select a low-risk service, document the existing state, connect its repository, and compare Terraform Cloud plans with the current infrastructure. Once the workflow is proven, expand it to shared services, application platforms, and VMware or on-premises resources.

Clear ownership matters as much as configuration. Assign platform owners for workspace permissions, repository owners for code review, and service owners for application-specific variables. With those responsibilities defined, VCS integration becomes a practical control for infrastructure delivery rather than another console feature that only one administrator understands.