VCS (Version Control System) integration in HCP Terraform enables seamless collaboration between your infrastructure code repository and Terraform Cloud workspaces. This integration supports popular platforms like GitHub, GitLab, Bitbucket, and Azure DevOps.
When you connect a VCS repository to an…VCS (Version Control System) integration in HCP Terraform enables seamless collaboration between your infrastructure code repository and Terraform Cloud workspaces. This integration supports popular platforms like GitHub, GitLab, Bitbucket, and Azure DevOps.
When you connect a VCS repository to an HCP Terraform workspace, you establish an automated workflow that triggers Terraform runs based on repository events. The primary workflow types include:
**VCS-driven Workflow**: This is the most common approach where commits or pull requests to specified branches automatically initiate Terraform plans. When a pull request is opened, HCP Terraform runs a speculative plan and posts the results as a comment, allowing team members to review infrastructure changes before merging.
**Branch-based Triggers**: You can configure workspaces to monitor specific branches. Changes pushed to the designated branch (typically main or master) trigger automatic plan and apply operations, ensuring your infrastructure stays synchronized with your code.
**Pull Request Integration**: HCP Terraform provides feedback on pull requests by running plans and displaying results in the VCS interface. This enables code review processes to include infrastructure validation before changes are merged.
**Key Benefits**:
- Automatic plan execution on code changes
- Infrastructure change visibility in pull request discussions
- Audit trail linking infrastructure changes to specific commits
- Collaboration through familiar VCS workflows
- Policy enforcement through Sentinel before applies
**Configuration Steps**:
1. Connect your VCS provider to HCP Terraform organization settings
2. Create or configure a workspace with VCS connection
3. Select the repository and branch to monitor
4. Optionally specify working directory and trigger patterns
The VCS integration ensures infrastructure changes follow the same review and approval processes as application code, promoting GitOps practices and maintaining consistency across your team's deployment workflows.
VCS Integration and Workflows in HCP Terraform
Why VCS Integration Matters
Version Control System (VCS) integration is a cornerstone of modern Infrastructure as Code practices. In HCP Terraform (formerly Terraform Cloud), VCS integration enables teams to manage infrastructure changes through familiar Git-based workflows, ensuring collaboration, auditability, and automation.
What is VCS Integration?
VCS integration connects your HCP Terraform workspaces to repositories in platforms like GitHub, GitLab, Bitbucket, or Azure DevOps. This connection allows HCP Terraform to:
• Automatically trigger runs when changes are pushed to specified branches • Display proposed changes as pull request comments • Track the source of every infrastructure change • Enable code review processes for infrastructure modifications
How VCS-Driven Workflows Function
The VCS-driven workflow follows these steps:
1. Configuration: Connect a workspace to a VCS repository and specify the working directory containing your Terraform configuration.
2. Triggering Runs: When commits are pushed to the tracked branch, HCP Terraform automatically queues a speculative plan for pull requests or a full run for merged changes.
3. Speculative Plans: For pull requests, HCP Terraform creates a plan-only run and posts the results as a comment, allowing reviewers to see infrastructure impact before merging.
4. Apply on Merge: When changes are merged to the default branch, HCP Terraform can automatically apply the changes (if auto-apply is enabled) or wait for manual approval.
Key Configuration Options
• Working Directory: Specifies which subdirectory contains the Terraform configuration • VCS Branch: The branch HCP Terraform monitors for changes (default is the repository's default branch) • Automatic Run Triggering: Can be configured to trigger only on specific file changes • Auto-Apply: Determines whether successful plans are applied automatically
Workflow Types in HCP Terraform
VCS-Driven (Default): Runs triggered by VCS events, configuration stored in VCS
CLI-Driven: Runs triggered via Terraform CLI, configuration uploaded from local machine
API-Driven: Runs triggered via API, configuration uploaded programmatically
Exam Tips: Answering Questions on VCS Integration and Workflows
• Remember the trigger mechanism: VCS-driven workspaces trigger runs on push events to the monitored branch and create speculative plans for pull requests
• Understand speculative plans: These are plan-only runs that cannot be applied, used to preview changes in pull requests
• Know the workflow differences: VCS-driven workflows store configuration in the repository, while CLI-driven workflows upload configuration from the local environment
• Working directory importance: When a repository contains multiple configurations, the working directory setting determines which one the workspace uses
• Auto-apply behavior: By default, workspaces require manual confirmation to apply changes; auto-apply must be explicitly enabled
• Branch tracking: Each workspace can only track one branch at a time; multiple workspaces can track the same repository with different branches
• Authentication: VCS connections use OAuth tokens configured at the organization level, not individual workspace credentials
• Common exam scenario: Questions may ask about the sequence of events when a pull request is opened or merged, or which workflow type is appropriate for different use cases