Configure workspace VCS connections

You can connect any HCP Terraform workspace to a version control system (VCS) repository that contains a Terraform configuration. This page explains the workspace VCS connection settings in the HCP Terraform UI.

Refer to Terraform Configurations in HCP Terraform Workspaces for details on handling configuration versions and connected repositories. Refer to Connecting VCS Providers for a list of supported VCS providers and details about configuring VCS access, viewing VCS events, etc.

API

You can use the Update a Workspace endpoint in the Workspaces API to change one or more VCS settings. We also recommend using this endpoint to automate changing VCS connections for many workspaces at once. For example, when you move a VCS server or remove a deprecated API version.

Version Control Settings

To change a workspace's VCS settings:

Go to the workspace and click Settings > Version Control. The Version Control page appears.
Choose the desired settings and click Update VCS settings.

You can update the following types of VCS settings for the workspace.

VCS Connection

You can take one of the following actions:

To add a new VCS connection, click Connect to version control. Select Version control workflow and follow the steps to select a VCS provider and repository.
To edit an existing VCS connection, click Change source. Choose the Version control workflow and follow the steps to select VCS provider and repository.
To remove the VCS connection, click Change source. Select either the CLI-driven workflow or the API-driven workflow, and click Update VCS settings. The workspace is no longer connected to VCS.

Terraform Working Directory

Specify the directory where Terraform will execute runs. This defaults to the root directory in your repository, but you may want to specify another directory if you have directories for multiple different Terraform configurations within the same repository. For example, if you had one staging directory and one production directory.

A working directory is required when you use trigger prefixes.

Apply Method

Choose a workflow for Terraform runs.

Auto apply: Terraform will apply changes from successful plans without prompting for approval. A push to the default branch of your repository will trigger a plan and apply cycle. You may want to do this in non-interactive environments, like continuous deployment workflows.
Warning: If you choose auto apply, make sure that no one can change your infrastructure outside of your automated build pipeline. This reduces the risk of configuration drift and unexpected changes.
Manual apply: Terraform will ask for approval before applying changes from a successful plan. A push to the default branch of your repository will trigger a plan, and then Terraform will wait for confirmation.

Automatic Run Triggering

HCP Terraform uses your VCS provider's API to retrieve the changed files in your repository. You can choose one of the following options to specify which changes trigger Terraform runs.

Always trigger runs

This option instructs Terraform to begin a run when changes are pushed to any file within the repository. This can be useful for repositories that do not have multiple configurations but require a working directory for some other reason. However, we do not recommend this approach for true monorepos, as it queues unnecessary runs and slows down your ability to provision infrastructure.

Only trigger runs when files in specified paths change

This option instructs Terraform to begin new runs only for changes that affect specified files and directories. This behavior also applies to speculative plans on pull requests.

You can use trigger patterns and trigger prefixes in the Add path field to specify groups of files and directories.

Trigger Patterns: (Recommended) Use glob patterns to specify the files that should trigger a new run. For example, /submodule/**/*.tf, specifies all files with the .tf extension that are nested below the submodule directory. You can also use more complex patterns like /**/networking/**/*, which specifies all files that have a networking folder in their file path. (e.g., /submodule/service-1/networking/private/main.tf). Refer to Glob Patterns for Automatic Run Triggering for details.
Trigger Prefixes: HCP Terraform will queue runs for changes in any of the specified trigger directories matching the provided prefixes (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 repository. You can add modules as a trigger directory for each workspace to track changes to shared code.

Note: HCP Terraform triggers runs on all attached workspaces if it does not receive a list of changed files or if that list is too large to process. When this happens, HCP Terraform may show several runs with completed plans that do not result in infrastructure changes.

Trigger runs when a git tag is published

This option instructs Terraform to begin new runs only for changes that have a specific tag format.

The tag format can be chosen between the following options:

Semantic Versioning: It matches tags in the popular SemVer format. For example, 0.4.2.
Version contains a prefix: It matches tags which have an additional prefix before the SemVer format. For example, version-0.4.2.
Version contains a suffix: It matches tags which have an additional suffix after the SemVer format. For example 0.4.2-alpha.
Custom Regular Expression: You can define your own regex for HCP Terraform to match against tags.

You must include an additional \ to escape the regex pattern when you manage your workspace with the hashicorp/tfe provider and trigger runs through matching git tags. Refer to Terraform escape sequences for more details.

Tag Format	Regex Pattern	Regex Pattern (Escaped)
Semantic Versioning	`^\d+.\d+.\d+$`	`^\\d+.\\d+.\\d+$`
Version contains a prefix	`\d+.\d+.\d+$`	`\\d+.\\d+.\\d+$`
Version contains a suffix	`^\d+.\d+.\d+`	`^\\d+.\\d+.\\d+`

HCP Terraform triggers runs for all tags matching this pattern, regardless of the value in the VCS Branch setting.

VCS Branch

This setting designates which branch of the repository HCP Terraform should use when the workspace is set to Always Trigger Runs or Only trigger runs when files in specified paths change. If you leave this setting blank, HCP Terraform uses the repository's default branch. If the workspace is set to trigger runs when a git tag is published, all tags will trigger runs, regardless of the branch specified in this setting.

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.

Include Submodules on Clone

Select Include submodules on clone to recursively clone all of the repository's Git submodules when HCP Terraform fetches 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.

Glob Patterns for Automatic Run Triggering

We support glob patterns to describe a set of triggers for automatic runs. Refer to trigger patterns for details.

Supported wildcards:

* Matches zero or more characters.
? Matches one or more characters.
** Matches directories recursively.

The following examples demonstrate how to use the supported wildcards:

/**/* matches every file in every directory
/module/**/* matches all files in any directory below the module directory
/**/networking/* matches every file that is inside any networking directory
/**/networking/**/* matches every file that has networking directory on its path
/**/*.tf matches every file in any directory that has the .tf extension
/submodule/*.??? matches every file inside submodule directory which has three characters long extension.