Configure VCS status checks

Status checks are notifications sent to your version control system's VCS provider, providing details about specific commits, including the present status of the HCP Terraform run. Please refer to your VCS provider's documentation regarding status checks (e.g., GitHub Status Checks).

Permissions

To modify VCS Status Checks settings, you must have Manage VCS Settings permissions.

Managing organization VCS status check settings

Organization owners can choose between aggregated (default) and non-aggregated status checks. This setting determines whether detailed information and links are accessed directly from the VCS provider or HCP Terraform.

This setting also determines the number of status checks directly sent to the VCS Provider in response to actions such as pull or merge requests.

To view and manage an organization’s VCS Status Check settings, click Settings then Version Control.

Aggregated status checks

Aggregated status checks offer a streamlined experience if you have a single repository containing configuration for many workspaces (a.k.a., a monorepo).

When aggregated status checks are enabled, HCP Terraform sends one VCS status check for all runs triggered by a VCS event. If multiple workspaces rely on a shared repository, HCP Terraform aggregates the status checks for these workspaces into one summary. This summary is unique to the workspace's organization and VCS client connection.

You can access additional information about an aggregated status check in HCP Terraform by clicking the Details link a status check provides. This link directs you to an HCP Terraform page that offers the consolidated status check results across multiple workspaces, highlighting details such as resource changes and issues that require attention.

Non-aggregated status checks

Non-aggregated status checks send your VCS provider a status check for each triggered workspace and related run stage in response to a VCS event. For example, a VCS push triggers checks for each related workspace's run stages, including the plan operation, policy checks, cost estimation, run tasks, and more.

If you have a manageable amount of workspaces and want to visualize status checks on your VCS Provider rather than in HCP Terraform, use non-aggregated status checks.

Send passing commit statuses

Workspaces that use part of a shared repository do not typically run plans for changes that do not affect their files. This includes speculative plans on pull requests. Since pending VCS status checks can block pull requests, workspaces automatically send passing commit statuses for any PRs that do not affect their files.

You can disable this behavior if it creates too many status checks for your VCS provider. You may want to do this if you have a large number of workspaces sharing one VCS repository.