Problem
When configuring a service account for a Version Control System (VCS) connection in HCP Terraform or Terraform Enterprise, you may want to grant read-only permissions to follow the principle of least privilege. However, read-only access is insufficient for the integration to function correctly.
Cause
A service account for a VCS connection requires administrative permissions on the repository because HCP Terraform and Terraform Enterprise must automatically create and manage webhooks. These webhooks are essential for communication between the VCS provider and your Terraform instance, enabling features like automatic run triggering on code changes.
It is not possible to create these webhooks manually for two main reasons:
- Dynamic URL Generation: The specific callback URL for each webhook is generated dynamically during events like workspace creation or private module publishing. This URL is not known in advance.
- Workspace-Specific Webhooks: While the organization-level OAuth connection uses a user-provided callback URL, each workspace connected to a VCS repository creates its own unique webhook on that repository.
Therefore, the service account must have sufficient permissions to manage webhooks on the connected repositories to support these automated, dynamic processes. This requirement applies to both HCP Terraform and Terraform Enterprise.
Additional Information
For more details on connecting to a VCS provider, please refer to the official HCP Terraform and Terraform Enterprise documentation.