GitLab流水线执行Git子模块更新时出现Host key验证失败错误

核心原因 #

CI运行环境是临时容器，默认未信任GitLab的SSH主机密钥，且子模块拉取的权限配置和本地环境不一致。

解决方法 #

1. 预添加GitLab主机密钥到信任列表 #

在执行子模块更新命令前，先将GitLab的主机密钥写入known_hosts：

# 添加gitlab.com的主机密钥
ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
# 或使用GitLab预定义的安全密钥变量
echo "$GITLAB_SSH_HOST_KEYS" >> ~/.ssh/known_hosts

之后再执行：

git submodule update --init --recursive --remote

2. 切换为HTTPS协议拉取子模块 #

方式一：修改子模块远程地址

将子模块的SSH地址（如git@gitlab.com:your-group/submodule.git）替换为HTTPS格式（https://gitlab.com/your-group/submodule.git），提交子模块配置变更后，CI中可直接执行更新命令。

方式二：用CI_JOB_TOKEN自动转换地址

无需修改本地配置，在CI脚本中添加全局Git配置，自动将SSH地址转为带临时令牌的HTTPS地址：

git config --global url."https://gitlab-ci-token:$CI_JOB_TOKEN@gitlab.com/".insteadOf "git@gitlab.com:"
git submodule update --init --recursive --remote

CI_JOB_TOKEN是GitLab自动生成的临时令牌，拥有当前项目的读权限，适合拉取同组内的子模块。

3. 配置SSH密钥认证（适用于必须用SSH的场景） #

• 生成SSH密钥对：ssh-keygen -t ed25519 -C "ci-submodule-access"
• 将公钥添加到子模块仓库的部署密钥中，按需开启"允许写入"权限
• 将私钥作为CI/CD变量存入当前项目（变量名建议设为SSH_PRIVATE_KEY，勾选"保护变量"和"掩码变量"）
• 在CI脚本中配置SSH环境：

eval $(ssh-agent -s)
# 导入私钥
echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
# 配置目录权限
mkdir -p ~/.ssh
chmod 700 ~/.ssh
# 添加主机密钥（可选）
ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
chmod 644 ~/.ssh/known_hosts

完成配置后执行子模块更新命令即可。

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