GitLab CI拉取同账号私有子模块认证失败求助

我来帮你搞定这个CI拉取子模块的认证坑——咱们同账号下的私有主项目和子模块，理论上应该能顺畅访问，但Runner默认的权限配置确实容易踩这个认证失败的坑，下面是几个经过验证的解决方案：

方案1：给CI_JOB_TOKEN授予子模块访问权限 #

GitLab的CI_JOB_TOKEN默认只能访问当前运行CI的主项目，要让它能拉取同账号下的私有子模块，需要在子模块项目里配置权限：

• 打开子模块的GitLab项目页面，进入Settings → Repository
• 往下找到CI/CD job token access区域
• 点击"Add project"，选择你的主项目（就是运行CI的那个项目），保存配置
• 之后主项目的CI_JOB_TOKEN就有权限拉取这个子模块了，不需要修改任何URL或CI配置

方案2：修改.gitmodules URL为CI_JOB_TOKEN认证格式 #

如果不想调整子模块的权限设置，可以直接修改子模块的远程URL，让它在CI环境中自动用CI_JOB_TOKEN认证：

1. 先修改本地的.gitmodules文件，把子模块的SSH URL替换成HTTPS格式并带上token占位符：

   [submodule "path/to/submodule"]
       path = path/to/submodule
       url = https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/your-username/your-submodule.git
   

2. 在.gitlab-ci.yml的before_script里添加git配置，确保变量能被正确解析：

   before_script:
     - git config --global url."https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/your-username/".insteadOf "git@gitlab.com:your-username/"
     - git submodule update --init --recursive
   

   这个配置会把所有指向你账号的SSH URL自动替换成带CI_JOB_TOKEN的HTTPS URL，拉取子模块时自动完成认证。

方案3：使用Deploy Token（适用于多子模块或复杂权限场景） #

如果你的项目有多个子模块，或者需要更灵活的权限控制，可以创建一个Deploy Token：

• 在GitLab账号的User Settings → Access Tokens（或者项目级的Deploy Token）创建一个具备read_repository权限的token
• 修改.gitmodules中的子模块URL为：

  [submodule "path/to/submodule"]
       path = path/to/submodule
       url = https://<deploy-token-username>:<deploy-token>@gitlab.com/your-username/your-submodule.git
  

• 或者把token存在CI的环境变量里（在项目Settings → CI/CD → Variables中添加），然后在before_script里动态替换URL：

  before_script:
    - git config --global url."https://${DEPLOY_TOKEN_USER}:${DEPLOY_TOKEN}@gitlab.com/".insteadOf "git@gitlab.com:"
    - git submodule update --init --recursive
  

注意事项 #

• 确保你的.gitlab-ci.yml里已经开启了子模块拉取，比如在before_script或script阶段执行git submodule update --init --recursive
• 如果用SSH方式拉取，Runner需要配置对应的SSH密钥，但这种方式不如HTTPS+token灵活，不推荐在同账号场景下使用

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