OpenShift构建报错：无法找到远程引用master的排查与解决

我在OpenShift中配置的BuildConfig，其bc.spec.source指向Git仓库的配置如下：

git:
  uri: ssh://openshift@my-server/my-repo
  ref: master

在OpenShift外部使用git clone ssh://openshift@my-server/my-repo克隆仓库时，默认分支为master，但在OpenShift内启动构建时出现错误，oc logs显示详情：

Adding cluster TLS certificate authority to trust store
Cloning "openshift@my-server/my-repo" ...
error: fatal: couldn't find remote ref master
fatal: the remote end hung up unexpectedly

可能的原因 #

• 权限差异：OpenShift构建默认使用builder服务账号，该账号的Git仓库访问权限和你本地克隆时用的SSH密钥权限不一致，可能无法读取master分支。
• 分支名称大小写敏感：部分Git环境严格区分分支名称大小写，若仓库实际分支是Master而非master，本地系统（如Windows）大小写不敏感能正常识别，但OpenShift构建环境的Git客户端会严格校验。
• SSH密钥配置错误：关联到BuildConfig的Secret中存储的SSH私钥无效，或公钥未正确添加到Git仓库的openshift用户授权列表，导致无法完整拉取分支列表。
• 仓库端分支权限限制：Git仓库服务器对openshift用户设置了分支访问限制，隐藏了master分支。

诊断步骤 #

• 验证服务账号分支访问权限：启动一个临时Git测试Pod，挂载构建用的SSH密钥，执行分支列表查询：

  oc run -it --rm git-test --image=alpine/git -- /bin/sh
  # 在Pod内挂载对应Secret后执行
  git ls-remote ssh://openshift@my-server/my-repo
  

  查看输出是否包含master分支的引用。
• 核对仓库实际分支名称：直接在Git仓库服务器上执行git branch -a，确认分支名称是否为master，排除拼写或大小写错误。
• 检查SSH密钥配置：通过oc describe secret <your-build-secret>查看Secret中的私钥内容是否正确，同时确认该密钥对应的公钥已添加到Git仓库openshift用户的授权列表中。
• 测试仓库端用户权限：在Git服务器上用openshift用户登录，执行git branch -a，确认master分支可见。

解决方法 #

• 修复仓库权限：在Git仓库服务器上为openshift用户授予master分支的读取权限，确保该用户能正常拉取分支内容。
• 修正分支名称：若仓库实际分支名称存在大小写差异，修改BuildConfig的ref字段为正确的分支名，例如Master。
• 重新配置SSH密钥：删除旧的构建Secret，重新生成SSH密钥对，将公钥添加到Git仓库用户授权列表后，创建新的Secret并关联到BuildConfig。
• 使用默认分支：若仓库默认分支已变更或不确定分支名称，可删除BuildConfig中的ref字段，让OpenShift自动拉取仓库的默认分支。

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