Bitbucket提交未触发Terraform Enterprise运行如何解决

你遇到的手动切分支才能触发运行的现象，本质是TFE主动拉取仓库代码的链路正常，但Bitbucket主动推送代码变更事件的Webhook链路失效：手动切换分支的操作会强制TFE主动调用Bitbucket API拉取对应分支的最新提交，所以能触发Plan任务；正常提交代码时依赖Bitbucket主动发推送事件给TFE，这条链路断了自然不会触发任何运行。

常见诱因分三类：

• Bitbucket侧Webhook配置异常：关联工作区时自动创建的Webhook未勾选Push事件、配置了错误的分支/路径过滤规则、回调地址填写错误、Webhook签名密钥和TFE侧不匹配，都会导致推送事件无法正常送达或被TFE丢弃
• 连通性拦截：Bitbucket到TFE的请求被防火墙、WAF拦截，或TFE使用的Bitbucket访问令牌权限不足（缺少Webhook写入、仓库读取权限），导致Webhook创建半成功，事件通道实际未打通
• TFE侧自动保护机制触发：如果同一个仓库的Webhook连续5次投递失败，TFE会自动暂停接收该仓库的所有推送事件，直到手动更新VCS配置（也就是你切换分支的操作）才会重置订阅状态，恢复事件接收

按以下顺序排查，每步完成后可以测试提交代码验证是否恢复：

1. 检查Bitbucket侧Webhook配置
   进入Bitbucket对应仓库的Repository settings > Webhooks页面，找到TFE自动生成的Webhook条目：
   • 查看最近投递日志，如果提交代码时没有生成对应的投递记录，检查事件勾选配置，必须勾选Repository push事件，删除所有自定义的分支、路径过滤规则
   • 如果投递日志返回403错误，核对Webhook配置里的签名密钥，和TFE组织设置中VCS提供商配置页的密钥保持一致
   • 如果投递日志返回404错误，替换回调地址为TFE VCS配置页提供的标准地址，格式为https://<你的TFE访问域名>/webhooks/vcs/<VCS集成唯一标识>
   • 如果投递日志显示连接超时、连接被拒绝，检查TFE前端的防火墙、负载均衡、WAF规则，放通Bitbucket官方出口IP段对/webhooks/vcs/*路径的POST请求
2. 校正TFE侧配置
   • 检查Bitbucket访问令牌权限：确认所用令牌属于仓库管理员账号，已勾选repository:read、webhook:write、pullrequest:read权限范围，权限不足时重新生成令牌更新到TFE的VCS提供商配置中
   • 进入对应工作区的Settings > Version control页面，确认Automatic runs选项设置为Always trigger runs，如果不需要路径过滤不要选择指定路径触发的选项
   • 若之前存在连续Webhook投递失败的记录，在VCS配置页先切换到其他分支保存设置，再切回目标分支保存，重置TFE的事件订阅失败计数，重新激活推送接收
3. 修复验证
   在目标分支提交一个测试变更（比如修改README的空行），观察TFE工作区的运行列表，正常情况下10秒内就会自动生成新的Plan排队任务，无需手动切换分支即代表修复完成。

内容的提问来源于stack exchange，提问作者Faiz Kidwai