Jenkins对接Bitbucket多分支流水线扫描失败原因排查

故障核心表现 #

执行Scan Multibranch Pipeline Now时Git fetch操作返回状态码128，stderr输出如下：

stderr: Repository not found
The requested repository does not exist, or you do not have permission to access it.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

同仓库的单分支流水线拉取代码完全正常，故障持续一段时间后未做明确配置变更即自动恢复。

可能的故障原因 #

这类偶发、自动恢复的故障，通常和临时状态异常有关，结合Windows Jenkins节点、SSH鉴权的场景，常见诱因如下：

• 凭据加载临时异常
  Windows节点上如果使用Pageant、Windows原生OpenSSH代理做SSH密钥缓存，可能出现临时的密钥句柄泄漏、代理进程假死问题，导致Jenkins执行Git命令时没有正确加载对应Bitbucket仓库的访问密钥。由于Bitbucket对无权限的SSH请求统一返回404（和仓库不存在的返回完全一致），就会触发对应报错；后续重试时代理重新加载密钥、或者代理进程自动恢复，鉴权通过后故障就会消失。
  另外如果Jenkins凭据库中存在多个同Bitbucket域名的SSH凭据，多分支流水线未强制绑定指定凭据ID时，可能偶发匹配到无仓库权限的旧凭据，而单分支流水线因为固定绑定了正确凭据ID，全程不受影响。
• Bitbucket服务端临时状态异常
  如果故障发生前后刚好做过SSH公钥更新、仓库用户组权限调整、项目权限迁移操作，Bitbucket后端的权限缓存同步存在数秒到数分钟的延迟，期间的鉴权请求会被判定为非法，返回仓库不存在的报错，等集群缓存同步完成后请求自动恢复正常。
  另外Bitbucket服务端节点临时故障、负载均衡转发异常，也可能导致请求被路由到无对应仓库数据的节点，触发同类报错。
• 网络链路临时波动
  Jenkins节点到Bitbucket之间如果经过内网代理、防火墙、负载均衡设备，可能出现临时的路由波动、SSH会话被拦截、域名解析指向错误的问题，导致Git请求无法到达正确的仓库地址，触发仓库不存在的报错，网络链路恢复后故障自动消失。
• Jenkins侧缓存/进程异常
  多分支流水线在Jenkins节点上存储的远程分支引用缓存、仓库元数据缓存出现文件损坏、锁占用问题时，Git fetch操作会因为本地校验失败抛出错误；后续某次扫描触发全量缓存刷新（比如定时任务触发全量拉取、缓存锁超时释放），操作就会恢复正常。
  另外Windows节点上的Git、SSH相关进程出现临时的环境变量加载异常、句柄占用问题，导致GIT_SSH环境变量未正确传递、凭据配置读取失败，也会触发鉴权错误，进程重启后环境加载正常，故障自动恢复。

后续排查建议 #

如果故障复现，可直接登录Jenkins节点使用对应SSH密钥手动执行git ls-remote <仓库SSH地址>，跳过Jenkins插件逻辑直接验证网络、凭据是否正常，快速定位故障层级。

注意：不要被「Repository not found」的报错误导，Bitbucket的鉴权失败不会返回明确的无权限提示，排查时优先验证鉴权有效性，不要反复核对仓库地址是否正确。

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