GitLab流水线中嵌套Git子模块递归失败求助

问题背景 #

项目结构如下：

project A
   |_project B
   |_project C
        |_project D

• A为超项目，B、C是A的子模块，D是C的子模块
• 本地手动递归克隆/更新时可正常拉取所有子模块（包括D），但GitLab Runner执行流水线时，仅D无法实例化，报错：

fatal: could not read Username for 'the-gitlab-server': No such device or address
Failed to recurse into submodule path 'Project C'

• B和C可正常实例化，已尝试以下配置但均无效：
  1. 设置CI变量：

     variables:
       GIT_SUBMODULE_STRATEGY: recursive
       GIT_STRATEGY: clone
     

  2. 在任务的before_script中手动执行同步更新：

     <the-job-that-causes-the-failure>:
       stage: smoke
       script:
         - <job>
       before_script:
         - git submodule sync --recursive
         - git submodule update --init --recursive
     

• 所有子模块的.gitmodules均使用相对路径，本地和Runner的Git版本均为2.25。

可能原因 #

1. 深层子模块认证缺失：GitLab Runner拉取顶层子模块（B、C）时会自动使用CI_JOB_TOKEN认证，但递归拉取嵌套子模块（D）时，该认证信息无法自动传递到深层操作中，导致无权限拉取D。
2. 相对路径解析问题：C的.gitmodules中D的相对路径基准错误（虽然本地正常，但Runner的工作目录上下文可能存在差异）。

解决方案 #

方案1：全局配置Git URL替换，注入CI_JOB_TOKEN #

在before_script中添加Git配置，让所有指向GitLab服务器的请求自动带上CI_JOB_TOKEN作为认证凭证，覆盖所有层级的子模块拉取：

<the-job-that-causes-the-failure>:
  stage: smoke
  script:
    - <job>
  before_script:
    - git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@the-gitlab-server/".insteadOf "https://the-gitlab-server/"
    - git submodule sync --recursive
    - git submodule update --init --recursive

原理：该配置会将所有https://the-gitlab-server/开头的仓库URL替换为带CI_JOB_TOKEN的认证URL，不管是顶层还是嵌套子模块，拉取时都会自动携带权限凭证。

方案2：验证嵌套子模块的相对路径 #

检查C的.gitmodules中D的URL是否为相对于C仓库根目录的正确相对路径。例如，若C和D在GitLab同组下，D的URL应为类似../project-D.git的格式，确保Runner拉取时能正确解析为GitLab仓库地址。

方案3：使用SSH认证（若Runner已配置SSH密钥） #

如果Runner使用SSH方式拉取代码，确保所有子模块的URL为SSH格式（如git@the-gitlab-server:group/project-D.git），并在CI/CD变量中配置SSH_PRIVATE_KEY，同时在before_script中启动SSH代理：

<the-job-that-causes-the-failure>:
  stage: smoke
  script:
    - <job>
  before_script:
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - git submodule sync --recursive
    - git submodule update --init --recursive

注意：需确保该SSH密钥拥有所有子模块（包括D）的拉取权限。

验证建议 #

优先尝试方案1，这是嵌套子模块在GitLab Runner中认证失败的最常见解决方案，本地正常是因为本地环境已存在有效的Git认证缓存或SSH密钥，而Runner的执行环境是临时且无缓存的，需要显式注入认证信息。

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