Configuring Workspace VCS Connections
You can connect any Terraform Cloud workspace to a version control system (VCS) repository that contains a Terraform configuration. This page explains the workspace VCS connection settings in the Terraform Cloud UI.
Refer to Terraform Configurations in Terraform Cloud Workspaces for details about how Terraform Cloud handles 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.
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.
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.
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.
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
A working directory is required when you use trigger prefixes.
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 infrstructure outside of your automated build pipeline. This reduces the risk of congfiguration 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.
Terraform Cloud 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.
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.
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
.tfextension that are nested below the
submoduledirectory. You can also use more complex patterns like
/**/networking/**/*, which specifies all files that have a
networkingfolder 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: Terraform Cloud 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
modulesdirectory to share Terraform code across multiple configurations, changes to the shared modules are relevant to every workspace that uses that repository. You can add
modulesas a trigger directory for each workspace to track changes to shared code.
Note: Terraform Cloud 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, Terraform Cloud may show several runs with completed plans that do not result in infrastructure changes.
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,
- Version contains a prefix: It matches tags which have an additional prefix before the SemVer format. For example,
- Version contains a suffix: It matches tags which have an additional suffix after the SemVer format. For example
- Custom Regular Expression: You can define your own regex for Terraform Cloud 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)|
|Version contains a prefix|
|Version contains a suffix|
This designates which branch of the repository Terraform Cloud should use in the workspace. If left blank, Terraform Cloud uses the repository's default branch.
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.
Select Include submodules on clone to recursively clone all of the repository's Git submodules when Terraform Cloud 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 to describe a set of triggers for automatic runs. Refer to trigger patterns for details.
*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
/**/networking/*matches every file that is inside any
/**/networking/**/*matches every file that has
networkingdirectory on its path
/**/*.tfmatches every file in any directory that has the
/submodule/*.???matches every file inside
submoduledirectory which has three characters long extension.