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:
A commit modifies a Terraform file (
.tf) and triggers a speculative run.A second commit modifies a non-trigger file (for example
.md) within the same open PR.GitHub emits a
pull_request → synchronizewebhook event.The webhook payload reflects the combined state of the PR branch, which still includes Terraform file changes.
Terraform Enterprise evaluates the PR branch again and triggers a new speculative run.
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:
Create a Pull Request containing Terraform changes.
Trigger a speculative plan.
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