Troubleshooting VCS webhooks in Terraform Enterprise

Problem

In a Terraform Enterprise (TFE) workspace configured with the UI/VCS-driven run workflow, runs are not being triggered automatically after new commits are pushed or pull requests are opened in the connected Version Control System (VCS) repository.

Cause

Terraform Enterprise uses webhook integration with VCS providers to monitor repository events. An automatic run may fail to trigger due to several reasons:

• The webhook is missing or misconfigured in the VCS provider.
• The webhook is not configured to respond to the correct events (push, pull request).
• The webhook is failing to deliver its payload to the TFE instance due to network issues or service interruptions.
• TFE does not use webhooks for all configuration version fetches. When a workspace is created or its settings are changed, TFE initiates a direct request to the VCS provider. Webhooks are only used for subsequent pushes and pull requests.

Troubleshooting Steps

Follow these steps to diagnose issues with webhook behavior for a workspace.

Step 1: Verify the Webhook is Present

On most VCS providers, you can view existing webhooks in the repository settings, although the exact path varies by provider.

1. Navigate to your repository's webhook settings in the VCS provider's UI.
2. Confirm that a webhook has been created for your TFE instance. The webhook's payload URL should match the URL of your private TFE instance. This URL is also shown in the workspace’s “Version Control” settings page in TFE.
3. These URLs contain a UUID, so check carefully for an exact match.

Step 2: Confirm Webhook Event Configuration

If the webhook is present, access its detailed settings to ensure that it is configured for both push and pull request events.

1. This is the default set of events, but if the webhook was edited, the configuration may have changed.
2. If the webhook is configured to respond to pushes but not pull requests, Terraform runs will only be initiated on a push to the workspace's tracked VCS branch, not when a pull request is opened.

Step 3: Check Webhook Delivery Logs

All supported VCS providers, except for Bitbucket Server, provide a log of recent webhook deliveries.

1. Access the webhook's detailed view and check the delivery history.
2. Look for deliveries corresponding to recent push or pull request events.
3. Verify whether the delivery was successful. A successful delivery typically receives a 200 OK response from the TFE instance.

If a webhook delivery was not sent, confirm that the event should have triggered one and check the VCS provider's status page for any ongoing incidents. If a delivery was sent but failed, the error message in the delivery log can often help identify the root cause, such as a network connectivity issue between the VCS provider and your TFE instance.

Some VCS providers retain this history for a short period. If there are no recent events, you can trigger a new delivery by pushing a commit, opening a pull request, or using a "Test" button if one is available in the webhook settings.

Additional Information

For specific instructions on how to locate and inspect webhooks, refer to the official documentation for your VCS provider (e.g., GitHub, GitLab, Azure DevOps).