Terraform Enterprise - Unexpected Runs Caused by GitHub PR Synchronize Events in VCS-Driven Workspaces

Avatar
Konica Sethi
  • Updated

 

Introduction

This article explains why Terraform Enterprise (TFE) may trigger additional speculative runs when a non-Terraform file (such as a Markdown documentation file) is committed to an existing Pull Request (PR), even when Automatic Run Trigger patterns are configured to only include Terraform files.

Problem

In a Terraform Enterprise VCS-driven workspace with Automatic Run Trigger patterns configured (for example, only .tf, .tfvars, .hcl files), users may observe that:

  • A Terraform file change correctly triggers a speculative plan.

  • A subsequent commit to a non-trigger file (e.g., README.md) within the same Pull Request unexpectedly triggers another run.

  • The previously running speculative plan may be canceled and replaced with a new run.

This creates confusion because the non-trigger file change appears to initiate the run.

Prerequisites

This behavior applies to environments with the following configuration:

  • Terraform Enterprise

  • VCS-driven workspaces

  • GitHub repository integration

  • Speculative plans enabled

  • Pull Request-based workflows

  • Automatic Run Trigger patterns configured such as:

**/*.tf
**/*.tfvars
**/*.hcl
**/*.tfvars.json

Cause

This behavior occurs due to how GitHub Pull Request lifecycle events interact with Terraform Enterprise speculative plan evaluation.

When a commit is pushed to an open Pull Request branch, GitHub emits a webhook event:

pull_request → synchronize

This event represents the latest state of the entire PR branch, not just the changes in the most recent commit.

This behavior is usually encountered in the following scenario:

  1. A commit modifies a Terraform file (.tf) and triggers a speculative run.

  2. A second commit modifies a non-trigger file (for example .md) within the same open PR.

  3. GitHub emits a pull_request → synchronize webhook event.

  4. The webhook payload reflects the combined state of the PR branch, which still includes Terraform file changes.

  5. Terraform Enterprise evaluates the PR branch again and triggers a new speculative run.

  6. The previous run is automatically canceled and replaced.

Even though the second commit only modifies documentation, Terraform Enterprise evaluates the PR's current state, which still contains Terraform changes.

Overview of possible solutions

This behavior is expected when speculative plans are enabled in Pull Request workflows. The following approaches can help reduce unnecessary run triggers.

Solutions

Solution 1 – Combine commits before pushing

Combine Terraform configuration changes and documentation updates into a single commit before pushing to the Pull Request branch.

This prevents multiple PR synchronize events from being generated.

Solution 2 – Modify documentation automation

If documentation is generated automatically (for example, Terraform documentation automation updating README.md), consider modifying the automation to:

  • Run after the Pull Request is merged, or

  • Push documentation changes to a separate branch.

Solution 3 – Avoid auto-commits to open PR branches

Automation that commits additional changes to an open Pull Request can trigger new PR synchronize events, which will cause Terraform Enterprise to reevaluate the PR.

Avoid committing new changes to active PR branches when possible.

Solution 4 – Review GitHub workflow configuration

Review any GitHub Actions, bots, or automation tools that may:

  • Update documentation

  • Modify files in open Pull Requests

  • Automatically push commits to PR branches

These automated commits can trigger PR synchronize events.

Outcome

Once the Pull Request workflow or automation is adjusted, Terraform Enterprise will no longer trigger additional speculative runs due to documentation updates.

To confirm the issue is resolved:

  1. Create a Pull Request containing Terraform changes.

  2. Trigger a speculative plan.

  3. Ensure that subsequent non-trigger file changes do not cause additional runs unless the PR branch state includes Terraform modifications.

If unexpected runs continue to occur, review webhook payloads and PR event logs to confirm the events being emitted by GitHub.

Additional Information

Terraform Enterprise Documentation – VCS-driven workflows
https://developer.hashicorp.com/terraform/cloud-docs/run/run-triggers

Terraform Enterprise Documentation – Speculative Plans
https://developer.hashicorp.com/terraform/cloud-docs/run/speculative-plans

GitHub Documentation – Pull Request Events
https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request

GitHub Actions – Workflow path filters
https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#paths-ignore

Articles in this section

See more