Github Webhooks突然停止自动拉取排查求助（cPanel Git环境）

开发者阿泽

2026-7-26

GitHub Webhooks自动拉取失效排查方向

一、GitHub端配置检查

查看Webhook请求状态：进入仓库Settings→Webhooks，查看最近的请求记录，重点关注状态码（如404/500/403）和响应详情，确认GitHub是否成功发送请求、是否收到错误反馈。
验证触发事件配置：确认Webhook仅勾选了需要的触发事件（如Push事件），未被误修改为其他事件或取消勾选。
核对Secret密钥：确保GitHub后台配置的Secret与脚本中$secret变量值完全一致，无空格、大小写错误，或近期更换密钥后未同步更新脚本。
检查Payload格式：脚本注释明确说明仅支持x-www-form-urlencoded格式，需确认GitHub Webhook的Content type未被改为application/json，否则$_POST['payload']无法获取到数据。

确认服务器可接收GitHub请求：Bluehost服务器可能存在防火墙或安全规则拦截GitHub IP段，需核对GitHub官方IP列表，确保服务器未屏蔽这些IP；也可在服务器上用curl模拟GitHub请求，测试/webhooks/git-post-receive.php是否可正常访问。
检查脚本与目录权限：确保git-post-receive.php文件权限为644或755，PHP进程拥有读写执行权限；同时确认/webhooks目录未被.htaccess规则拦截，注释中提到的“排除该目录于htaccess”已生效。
验证Git命令执行权限：手动更新cPanel仓库成功不代表PHP进程有权限执行Git命令，需确认运行PHP的用户（cPanel账户用户）拥有对应站点目录的读写权限，且Git可正常拉取远程代码。可修改脚本记录Git命令输出：
```
$output = shell_exec('git reset --hard HEAD && git pull 2>&1');
file_put_contents('./git-log.txt', $output . "\n", FILE_APPEND);
```
通过日志排查是否存在权限不足、SSH密钥未配置或远程仓库地址错误等问题。

开启日志追踪：取消脚本中file_put_contents的注释，在关键节点添加日志记录，比如：
- 收到请求时记录时间与请求方式
- 签名验证前后记录$signature和$hash值
- Git命令执行后记录输出结果
  以此定位脚本执行到哪一步出现异常。
检查PHP环境与函数支持：确认服务器PHP版本未发生不兼容更新，且未禁用file_get_contents("php://input")、shell_exec、mail等关键函数，可通过phpinfo()查看配置或联系Bluehost客服确认。
分支匹配逻辑验证：若近期新增或修改分支名，需确认脚本switch语句中存在对应分支的case；同时检查$payload->ref的返回格式是否变化，避免substr提取分支名出错。
邮件通知辅助排查：若未收到脚本发送的通知邮件，说明脚本可能未执行到邮件逻辑，可暂时注释邮件代码，优先排查核心拉取逻辑是否正常。

核对Git仓库配置：确认cPanel的Git Version Control中，对应仓库的远程地址、分支设置与脚本中切换目录的仓库一致，未被误修改。
检查cPanel安全规则：排查cPanel的ModSecurity是否拦截了GitHub请求，或是否开启了限制PHP执行shell命令的规则，可临时关闭ModSecurity测试，或查看其日志确认拦截记录。

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