GitLab CI/CD中Submodule私有仓库认证失败排查求助

问题根源 #

你的流水线在获取源代码阶段就触发了子模块初始化（因为配置了GIT_SUBMODULE_STRATEGY: recursive），这个阶段早于before_script执行，此时Git使用.gitmodules中的原始无认证URL拉取私有子模块，导致认证失败。你在before_script中手动添加子模块的操作完全多余，反而会引发冲突。

修复方案 #

使用GitLab内置的CI_JOB_TOKEN完成认证（你已配置子模块项目的作业令牌权限，无需自定义CI_USER和CI_TOKEN），并取消自动子模块策略，手动控制初始化流程：

修改后的.gitlab-ci.yml #

stages:
  - check_sync

image: "python:3.12.0b4-alpine3.18"
 
before_script:
  - apk add --no-cache git
  # 配置Git自动使用CI_JOB_TOKEN完成认证
  - git config --global credential.helper '!f() { echo "username=gitlab-ci-token"; echo "password=$CI_JOB_TOKEN"; }; f'
  # 同步子模块URL配置
  - git submodule sync --recursive
  # 初始化并更新子模块，--force确保覆盖旧配置
  - git submodule update --init --recursive --force
   
check_submodule_job:
  stage: check_sync
  script:
    - cd submodule_testing
    - echo "子模块目录切换成功"
    - ls -la # 可选：验证子模块内容是否拉取完成

关键修改说明 #

1. 移除GIT_SUBMODULE_STRATEGY: recursive：避免GitLab在自动阶段执行无认证的子模块拉取，将控制权交给before_script。
2. 使用CI_JOB_TOKEN认证：GitLab自动注入的CI_JOB_TOKEN会基于你已配置的作业令牌权限，自动获得子模块仓库的访问权限，无需手动管理账号密码。
3. 配置Git凭证助手：让Git在访问HTTPS仓库时自动填充认证信息，解决"could not read Username"的错误。
4. 删除多余的git submodule add：子模块已在.gitmodules中注册，重复添加会导致仓库冲突。

额外验证步骤 #

• 确认子模块项目的设置 > CI/CD > 作业令牌中，已将主项目添加到「允许从以下项目访问」列表。
• 确保流水线运行时CI_JOB_TOKEN变量正常可用（GitLab默认自动注入，无需手动配置）。

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