GitLab CI中Docker Compose构建Git项目时子模块初始化报错

我之前也踩过类似的GitLab CI里Docker Compose拉取HTTP Git仓库的坑，结合你的场景，咱们可以从这几个方向逐一排查：

1. GitLab CI Runner的HTTP Git访问权限缺失 #

虽然用的是HTTP协议，但大部分Git仓库（包括GitLab自己的仓库）其实还是需要身份验证的。你本地和个人登录CI服务器时能正常运行，是因为你的环境里已经缓存了Git凭证，但CI Runner的执行容器是全新的，默认没有这些凭证。

解决思路：

• 在GitLab项目的Settings > CI/CD > Variables里添加账号凭证，或者直接在.gitlab-ci.yml的before_script里配置.netrc文件（更安全的方式是用项目级Access Token代替明文密码）：

  before_script:
    - echo "machine your-git-repo-domain login your-git-username password your-project-access-token" > ~/.netrc
    - chmod 600 ~/.netrc
  

• 如果是公开仓库，确认CI Runner所在网络能正常访问该HTTP仓库（有些企业内网会拦截未授权的外部HTTP请求）。

2. Docker Compose的Git URL格式问题 #

Docker Compose对Git仓库的URL格式有严格要求，稍有偏差就会拉取失败。比如是否遗漏.git后缀、分支指定是否正确。

检查你的docker-compose.yml配置是否符合规范：

services:
  your-service:
    build:
      # 正确格式：HTTP地址+.git后缀+分支指定（可选）
      context: http://your-git-repo-url/path/to/repo.git#main

你可以先在CI服务器上以个人身份执行git clone 你的HTTP仓库地址，确认仓库本身能正常拉取，排除URL格式错误。

3. Docker Compose的网络隔离问题 #

GitLab CI Runner默认会给每个Job分配独立的网络环境，可能导致Docker容器无法访问外部的HTTP Git仓库。

解决方法：

• 在执行docker-compose build时添加--network host参数，让Docker使用宿主机网络访问仓库：

  docker-compose --verbose build --network host
  

• 检查CI Runner的网络策略，确认允许访问目标Git仓库的80端口（HTTP默认端口）。

4. Docker/Compose版本兼容性问题 #

不同版本的Docker和Docker Compose对Git仓库的支持存在差异，如果你本地的版本和CI Runner的版本不一致，可能会出现本地正常但CI失败的情况。

解决思路：

• 执行docker --version和docker-compose --version对比本地和CI Runner的版本，尽量保持一致；
• 如果CI Runner使用的是较旧版本，尝试升级到稳定版（比如Docker 24.x + Compose 2.x系列）。

你可以先从权限问题入手排查，这是GitLab CI里这类问题最常见的原因。如果能把调试日志里的关键错误信息（比如认证失败、网络超时提示）贴出来，能更快定位到具体问题。

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