GitLab CI流水线拉取子模块失败：远程项目无法访问排查

问题概述 #

CI流水线拉取x2_can_port、x2_logger等子模块时持续报错「项目不存在或无访问权限」，问题已存在近1个月。所有子模块使用相对URL，与父项目同属一个GitLab私有服务器，本人拥有所有仓库的完整权限；仅x2_can_port和x2_logger使用main分支，其余子模块为master分支；本地克隆项目可正常拉取所有子模块，无权限或路径问题。

已提供文件：.gitlab-ci.yml、.gitmodules、完整CI运行日志。

排查与解决方案 #

1. 校验CI_JOB_TOKEN的权限配置 #

GitLab CI默认通过CI_JOB_TOKEN访问同服务器内的子模块，需确保：

• 父项目与所有子项目的CI/CD设置中，开启「允许作业令牌访问此项目」（路径：项目设置 → CI/CD → 流水线令牌）
• 子项目的成员列表中，添加gitlab-ci-token用户并授予至少Reporter权限（拉取子模块需要仓库读取权限）

2. 确认子模块分支配置一致性 #

检查.gitmodules文件中分支配置是否准确：

• 确保x2_can_port和x2_logger的branch字段设为main，其余子模块设为master
• 执行本地命令git submodule sync --recursive同步配置后，推送父项目至远程，避免本地与远程配置偏差

3. 修正CI流水线的子模块拉取脚本 #

在.gitlab-ci.yml的before_script中添加标准的子模块拉取命令，确保递归同步与初始化：

before_script:
  - git submodule sync --recursive
  - git submodule update --init --recursive --jobs 4

若使用SSH协议拉取，需替换为HTTPS（CI_JOB_TOKEN仅支持HTTPS认证），或在CI环境中配置SSH密钥（需确保密钥拥有子模块访问权限）

4. 验证相对URL的正确性 #

确认.gitmodules中的相对URL符合GitLab服务器路径规则：

• 例如父项目路径为my-group/main-repo，子模块相对URL应为../my-group/x2_can_port.git，而非本地文件路径
• 执行本地命令git submodule status查看子模块远程URL，确认与GitLab项目页面显示的HTTPS/SSH地址匹配

5. 排查CI环境的Git版本兼容性 #

旧版本Git可能存在子模块相对URL或分支处理的bug，建议在CI脚本中指定或升级Git版本：

before_script:
  - apt-get update && apt-get install -y git>=2.28.0

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