• Overview
    • Enforce Policy as Code
    • Infrastructure as Code
    • Inject Secrets into Terraform
    • Integrate with Existing Workflows
    • Manage Kubernetes
    • Manage Virtual Machine Images
    • Multi-Cloud Deployment
    • Network Infrastructure Automation
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
  • Registry
  • Tutorials
    • About the Docs
    • Intro to Terraform
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
    • Terraform Tools
    • CDK for Terraform
    • Glossary
  • Community
GitHubTerraform Cloud
Download

    Terraform Cloud and Enterprise

  • Overview
  • Plans and Features
  • Getting Started
    • API Docs template
    • Overview
    • Account
    • Agent Pools
    • Agent Tokens
    • Applies
    • Audit Trails
    • Comments
    • Configuration Versions
    • Cost Estimates
    • Feature Sets
    • Invoices
    • IP Ranges
    • Notification Configurations
    • OAuth Clients
    • OAuth Tokens
    • Organizations
    • Organization Memberships
    • Organization Tags
    • Organization Tokens
    • Plan Exports
    • Plans
    • Policies
    • Policy Checks
    • Policy Sets
    • Policy Set Parameters
      • Modules
      • Providers
      • Private Provider Versions and Platforms
      • GPG Keys
    • Runs
      • Run Tasks
      • Stages and Results
      • Custom Integration
    • Run Triggers
    • SSH Keys
    • State Versions
    • State Version Outputs
    • Subscriptions
    • Team Access
    • Team Membership
    • Team Tokens
    • Teams
    • User Tokens
    • Users
    • Variables
    • VCS Events
    • Workspaces
    • Workspace-Specific Variables
    • Workspace Resources
    • Variable Sets
      • Overview
      • Module Sharing
      • Organizations
      • Runs
      • Settings
      • Terraform Versions
      • Users
      • Workspaces
    • Changelog
    • Stability Policy
    • Overview
    • Creating Workspaces
    • Naming
    • Terraform Configurations
      • Overview
      • Managing Variables
      • Overview
      • VCS Connections
      • Access
      • Drift Detection
      • Notifications
      • SSH Keys for Modules
      • Run Triggers
      • Run Tasks
    • Terraform State
    • JSON Filtering
    • Remote Operations
    • Viewing and Managing Runs
    • Run States and Stages
    • Run Modes and Options
    • UI/VCS-driven Runs
    • API-driven Runs
    • CLI-driven Runs
    • The Run Environment
    • Installing Software
    • Users
    • Teams
    • Organizations
    • Permissions
    • Two-factor Authentication
    • API Tokens
      • Overview
      • Microsoft Azure AD
      • Okta
      • SAML
      • Linking a User Account
      • Testing
    • Overview
    • GitHub.com
    • GitHub.com (OAuth)
    • GitHub Enterprise
    • GitLab.com
    • GitLab EE and CE
    • Bitbucket Cloud
    • Bitbucket Server and Data Center
    • Azure DevOps Services
    • Azure DevOps Server
    • Troubleshooting
    • Overview
    • Adding Public Providers and Modules
    • Publishing Private Providers
    • Publishing Private Modules
    • Using Providers and Modules
    • Configuration Designer
  • Migrating to Terraform Cloud
    • Overview
    • Using Sentinel with Terraform 0.12
    • Manage Policies
    • Enforce and Override Policies
    • Mocking Terraform Sentinel Data
    • Working With JSON Result Data
      • Overview
      • tfconfig
      • tfconfig/v2
      • tfplan
      • tfplan/v2
      • tfstate
      • tfstate/v2
      • tfrun
    • Example Policies
    • Overview
    • AWS
    • GCP
    • Azure
      • Overview
      • Service Catalog
      • Admin Guide
      • Developer Reference
      • Example Customizations
      • V1 Setup Instructions
    • Splunk Integration
    • Kubernetes Integration
    • Run Tasks Integration
    • Overview
    • IP Ranges
    • Data Security
    • Security Model
    • Overview
    • Part 1: Overview of Our Recommended Workflow
    • Part 2: Evaluating Your Current Provisioning Practices
    • Part 3: How to Evolve Your Provisioning Practices
    • Part 3.1: From Manual Changes to Semi-Automation
    • Part 3.2: From Semi-Automation to Infrastructure as Code
    • Part 3.3: From Infrastructure as Code to Collaborative Infrastructure as Code
    • Part 3.4: Advanced Workflow Improvements

  • Terraform Cloud Agents

  • Terraform Enterprise Admin

  • Other Docs

  • Intro to Terraform
  • Configuration Language
  • Terraform CLI
  • Terraform Cloud
  • Terraform Enterprise
  • Provider Use
  • Plugin Development
  • Registry Publishing
  • Integration Program
  • Terraform Tools
  • CDK for Terraform
  • Glossary
Type '/' to Search

»Configuring Workspace VCS Connections

Any Terraform Cloud workspace can be connected to a version control system (VCS) repository that contains its Terraform configuration. You can assign a connection when creating a workspace, and can modify that connection in the "Version Control" page of the workspace's settings.

For more information about how configuration versions and connected repositories work, see Terraform Configurations in Terraform Cloud Workspaces.

To change the VCS settings for an existing workspace, choose "Version Control" from the workspace's "Settings" menu. The version control page includes the following settings:

  • Which VCS repository to use.
  • Which directories in the repository should trigger Terraform runs when they change.
  • Which branch of the repository to use.
  • Whether to download the repository's submodules.

For most of the settings on this page, you must save any changes with the "Update VCS settings" button at the bottom of the page.

API: See the Update a Workspace endpoint (PATCH /organizations/:organization_name/workspaces/:name).

»VCS Connection and Repository

The first item in the version control settings lets you select a new VCS repository or disconnect from the current repository. Depending on the current status, this control can appear as a "Connect to version control" button or a "Change VCS connection" link.

Clicking this control will navigate to a separate page, which will walk you through the process of connecting or disconnecting a repository. This page is split into three screens.

  1. On the first screen, choose your VCS provider (or choose "No VCS connection" to disconnect the workspace from version control).

    If you haven't added a VCS provider for your organization yet, choosing one here will prompt you to configure it. See Connecting VCS Providers for more information. Configuring a VCS provider requires permission to manage VCS settings. (More about permissions.)

  2. On the second screen, choose a repository from the filterable list. This screen is skipped if you chose "No VCS connection".

    Some VCS providers limit the list's size. If a repository isn't listed, you can still choose it by name; scroll to the bottom of the list and enter its ID in the text field.

    For some VCS providers, this list includes a drop-down menu for changing which account's repositories are shown. Other providers combine all available accounts into a single list.

  3. On the third screen, confirm or cancel your choice. Confirmed changes will be saved immediately, and you will be returned to the "Version Control" settings page.

See also:

  • Creating Workspaces
  • Connecting VCS Providers to Terraform Cloud

API: If you need to change VCS connections for many workspaces at once, consider automating the changes with the Update a Workspace endpoint. This is most common when moving a VCS server, or when a vendor deprecates an older API version.

»Automatic Run Triggering

Note: This setting only affects workspaces that specify a Terraform working directory. Without a working directory, the entire repository is considered relevant and any change will trigger a run. The working directory setting can be found on the "General" settings page.

For workspaces that specify a Terraform working directory, Terraform Cloud assumes that only some content in the repository is relevant to the workspace. Only changes that affect the relevant content will trigger a run. This behavior also applies to speculative plans on pull requests — Terraform Cloud won't queue plans for changes that aren't considered relevant.

By default, only the designated working directory is considered relevant.

You can adjust this behavior in two ways:

  • Add more trigger directories. Terraform Cloud will queue runs for changes in any of the specified trigger directories (including the working directory).

    For example, if you use a top-level modules directory to share Terraform code across multiple configurations, changes to the shared modules are relevant to every workspace that uses that repo. You can add modules as a trigger directory for each workspace to make sure they notice any changes to shared code.

  • Mark the entire repository as relevant. If you set the "Automatic Run Triggering" setting to "Always Trigger Runs," Terraform Cloud will assume that anything in the repository might affect the workspace's configuration, and will queue runs for any change.

    This can be useful for repos that don't have multiple configurations but require a working directory for some other reason. It's usually not what you want for true monorepos, since it queues unnecessary runs and slows down your ability to provision infrastructure.

»Error Handling for Run Triggers

Terraform Cloud retrieves the changed files for each push or pull request using your VCS provider's API. If for some reason the list of changed files cannot be retrieved, or if it is too large to process, the default behavior is to trigger runs on all attached workspaces. Should this happen, you may see several runs with state "Planned", due to the push resulting in no changes to infrastructure.

»Automatic Speculative Plans

Whether to perform speculative plans on pull requests to the connected repository, to assist in reviewing proposed changes.

Automatic speculative plans are enabled by default, but you can disable them for any workspace.

»VCS Branch

Which branch of the repository to use. If left blank, Terraform Cloud will use the repository's default branch.

»Include submodules on clone

Whether to recursively clone all of the repository's Git submodules when fetching a configuration.

Note: The SSH key for cloning Git submodules is set in the VCS provider settings for the organization, and is not related to the workspace's SSH key for Terraform modules.

github logoEdit this page
  • Overview
  • Docs
  • Extend
  • Privacy
  • Security
  • Press Kit
  • Consent Manager