GitLab Runner私有子模块update --init失败问题咨询

一、标准操作流程 #

方案1：用HTTPS地址（推荐，无需折腾SSH密钥） #

1. 主仓库的.gitmodules文件中，子模块URL使用GitLab的HTTPS地址，示例：

   [submodule "module1"]
       path = module1
       url = https://gitlab.example.com/你的分组/module1.git
   

2. 在CI/CD的before_script中，利用GitLab Runner内置的CI_JOB_TOKEN完成认证，通过Git URL替换规则自动为子模块请求带上令牌：

   before_script:
     - export GIT_SSL_NO_VERIFY=1 # 若你的GitLab使用自签证书，需保留此配置
     - git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/".insteadOf "https://gitlab.example.com/"
     - git submodule update --init --recursive
   

   原理：CI_JOB_TOKEN是Runner每次运行任务时自动生成的临时令牌，只要子模块与主仓库在同一GitLab实例，且主仓库的CI权限覆盖子模块（比如同分组、子仓库给主仓库分组开放权限），就能正常拉取。

方案2：用SSH地址 #

1. 在.gitmodules中配置子模块的SSH地址：

   [submodule "module1"]
       path = module1
       url = git@gitlab.example.com:你的分组/module1.git
   

2. 生成一对SSH密钥：将公钥添加到子仓库的Deploy Keys中（只读拉取无需勾选"允许写入权限"）；将私钥作为CI/CD变量（例如命名为SSH_PRIVATE_KEY）添加到主仓库的CI/CD设置里，类型可选"文件"或普通变量（普通变量需处理换行符）。
3. 在before_script中配置SSH环境：

   before_script:
     - export GIT_SSL_NO_VERIFY=1
     - eval $(ssh-agent -s)
     - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
     - mkdir -p ~/.ssh
     - echo "Host gitlab.example.com" >> ~/.ssh/config
     - echo "  StrictHostKeyChecking no" >> ~/.ssh/config # CI环境下跳过主机密钥验证简化流程
     - git submodule update --init --recursive
   

二、为什么Runner能访问主仓库却无法访问私有子模块？ #

• Runner拉取主仓库时，使用的是项目级别的CI_JOB_TOKEN或预配置的SSH密钥，但该权限默认仅覆盖主仓库本身。
• 子模块是独立的仓库，即便与主仓库在同一GitLab实例，CI_JOB_TOKEN也需要拥有子仓库的访问权限：要么子模块与主仓库同属一个分组（继承分组权限），要么为主仓库的项目机器人用户（project_{ID}_bot）分配子仓库的Reporter及以上权限。
• 你之前的尝试中，比如改用SSH地址但未配置对应的Deploy Keys/SSH密钥，或者用HTTPS但未添加CI_JOB_TOKEN的URL替换规则，都会导致认证失败。

三、关于你遇到的特殊现象解析 #

• 子模块设为公开后仍报错，修改目录后解决：这是Git缓存机制导致的，之前私有状态下的认证失败记录仍存在缓存中，修改子模块目录相当于让Git重新初始化子模块，清除了旧缓存状态，因此能正常拉取公开仓库。
• 公开改私有后仍可拉取，修改目录后再次报错：同样是Git缓存的问题，之前拉取公开仓库时的本地缓存（包括已下载的对象、认证信息）未失效，因此能继续拉取；修改目录后需要重新从远程拉取，此时子模块已设为私有，且无正确认证信息，就会触发报错。

内容的提问来源于stack exchange，提问作者Ömer GÜZEL