使用Git Hooks触发流水线时遭遇422请求被拒绝错误排查

• 核对curl请求参数与执行环境
  422错误本质是请求参数不符合Jenkins的要求，虽然手动执行正常，但钩子运行在GitLab容器内部的git用户环境下，需确保：

  • 钩子中的curl命令与你手动执行的完全一致，包括请求方法（POST/GET）、触发token、分支参数（如BRANCH=main）、请求头等。比如不要漏写buildWithParameters路径，或参数名大小写错误。
  • 进入GitLab容器（docker exec -it <gitlab容器名> bash），切换到git用户（su git）执行相同的curl命令，验证是否能成功触发，排除环境差异导致的问题。

• 验证GitLab容器到Jenkins的网络连通性
  手动执行curl可能在宿主机或Jenkins所在环境，而钩子在GitLab容器内运行，需确认：

  • GitLab容器能解析Jenkins的IP/域名，可在容器内执行ping <jenkins地址>测试。
  • 若两者在不同Docker网络，需将GitLab容器加入Jenkins所在的网络（docker network connect <jenkins网络名> <gitlab容器名>），或调整防火墙/安全组规则，开放容器间的访问端口。

• 检查Jenkins CSRF保护配置
  Jenkins默认开启CSRF防护，部分版本下即使使用触发token，也需要携带Crumb信息：

  • 可临时关闭CSRF保护（进入Manage Jenkins > Configure Global Security，取消勾选Prevent Cross Site Request Forgery exploits）测试，若触发成功，需在钩子的curl命令中加入Crumb头。
  • 获取Crumb的命令示例：curl -u <Jenkins用户名>:<API令牌> http://jenkins地址/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)，将返回结果作为-H参数加入触发请求。

• 修正分支判断逻辑
  post-receive钩子接收的第三个参数是完整的引用路径（如refs/heads/main），而非单纯的分支名，需确保判断逻辑正确：

  • 脚本中分支判断应写为：if [[ "$3" == "refs/heads/main" ]]; then（$3对应refname参数），避免直接判断main导致逻辑不触发。
  • 在钩子中添加日志记录，比如echo "当前推送分支: $3" >> /var/log/gitlab-hook.log，推送后查看日志确认分支是否被正确识别。

• 检查Jenkins流水线参数配置
  确认流水线的参数配置与钩子传递的参数匹配：

  • 进入Jenkins流水线的配置页面，查看此项目是参数化的中的参数名称（大小写敏感），比如钩子传递的是BRANCH=main，流水线中需存在同名的字符串参数。

• 排查git用户环境变量差异
  git用户在容器内的环境变量可能与手动执行时不同，比如代理配置、PATH等：

  • 在钩子脚本开头添加env >> /var/log/gitlab-hook-env.log，推送后查看日志，对比手动执行时的环境变量，补充缺失的必要配置（如HTTP_PROXY）。

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