虚拟机及GitLab Runner克隆Git子模块时的两类异常问题咨询

问题1：git submodule update --remote要求输入用户名密码（本地无此情况） #

可能原因 #

• 虚拟机/Runner的Git凭证管理配置与本地不一致：本地已配置SSH密钥或系统凭证管理器自动缓存密码，而虚拟机/Runner未配置。
• 子模块远程URL为HTTPS协议：本地已手动切换为SSH地址，但虚拟机/Runner仍使用HTTPS，导致每次拉取都需要身份验证。
• GitLab Runner执行用户无有效权限：Runner运行时的用户没有访问子模块仓库的SSH密钥，或未配置CI/CD凭证变量。

解决方法 #

1. 检查并修改子模块远程URL
   在虚拟机/Runner上执行以下命令查看子模块的远程地址：

   git submodule foreach git remote -v
   

   如果显示为HTTPS地址，切换为GitLab兼容的SSH地址：

   git submodule set-url [子模块路径] git@gitlab.com:用户名/子模块仓库名.git
   

   提交.gitmodules文件的变更到主仓库，确保所有环境统一使用SSH地址。

2. 配置Git凭证缓存
   在虚拟机上设置全局凭证存储，避免重复输入密码：

   git config --global credential.helper store
   

   对于GitLab Runner，可在CI脚本中注入GitLab提供的凭证变量：

   git config credential.username "$CI_REGISTRY_USER"
   git config credential.password "$CI_REGISTRY_PASSWORD"
   

3. 为Runner配置SSH密钥
   生成SSH密钥对，将公钥添加到子模块仓库的部署密钥中（GitLab项目设置→部署密钥），然后在Runner的CI脚本中加载私钥：

   eval $(ssh-agent -s)
   echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
   mkdir -p ~/.ssh
   echo "Host gitlab.com" >> ~/.ssh/config
   echo "  StrictHostKeyChecking no" >> ~/.ssh/config
   

   其中SSH_PRIVATE_KEY是在GitLab项目CI/CD变量中配置的私钥值。

问题2：fatal: Needed a single revision Unable to find current origin/master revision（本地无需添加branch = main） #

可能原因 #

• Git版本差异：本地Git版本较新（2.22+），可自动识别子模块的默认分支；而虚拟机/Runner的Git版本低于2.22，无法自动识别，必须明确指定分支。
• 子模块默认分支变更：子模块仓库的默认分支已从master改为main，旧版本Git仍默认查找master分支，导致找不到对应版本。
• Git全局配置的默认分支不一致：虚拟机/Runner的init.defaultBranch配置为master，与子模块的默认分支main不匹配。

解决方法 #

1. 升级Git版本
   检查虚拟机/Runner的Git版本：

   git --version
   

   如果版本低于2.22，升级到最新稳定版（如Ubuntu用apt install git，CentOS用yum update git）。升级后Git会自动识别子模块的默认分支，无需在.gitmodules中指定branch参数。

2. 在.gitmodules中指定分支
   如果无法升级Git，直接在.gitmodules中为对应子模块添加分支配置：

   [submodule "子模块路径"]
       path = 子模块路径
       url = git@gitlab.com:用户名/子模块仓库名.git
       branch = main
   

   提交该变更到主仓库，确保所有环境都能正确拉取分支。

3. 统一Git全局默认分支配置
   在虚拟机/Runner上设置全局默认分支为main：

   git config --global init.defaultBranch main
   

额外排查步骤 #

• 对比本地与虚拟机/Runner的Git配置：执行git config --list，重点检查credential.helper、init.defaultBranch等参数的差异。
• 验证子模块仓库的默认分支：登录GitLab查看子模块项目的设置，确认默认分支是否为main。
• 测试完整克隆流程：在虚拟机/Runner上执行git clone --recurse-submodules [主仓库地址]，观察是否能自动拉取子模块且无需输入密码。

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