两个Jenkins构建Job执行submodule update时出现403错误差异问题

这种情况我在日常运维Jenkins时碰到过好几次，虽然你说两个Job的构建配置完全一致，但分支不同这个差异，恰恰可能藏着导致403报错的核心原因。以下是几个最常见的排查方向和解决思路：

1. 不同分支的.gitmodules文件存在差异 #

主仓库的不同分支里，.gitmodules文件的内容可能不一样——这是最容易被忽略的点。比如：

• 正常运行的分支中，子模块用的是SSH协议URL（git@github.com:xxx/submodule.git），Jenkins配置了对应的SSH密钥凭证；
• 报错的分支中，子模块却用了HTTPS协议URL（https://github.com/xxx/submodule.git），但Jenkins没配置对应的用户名密码凭证，自然会触发403权限错误。

排查方法：分别切换到两个分支，执行以下命令对比子模块URL：

cat .gitmodules

如果发现URL不一致，要么修改报错分支的.gitmodules统一协议，要么给报错的Job配置对应协议的访问凭证。

2. Jenkins凭证的关联或权限问题 #

即使两个Job的配置看起来一样，也可能存在凭证关联的隐性差异：

• 你可能给正常Job单独绑定了能访问子模块的凭证，但报错的Job没关联到该凭证；
• 凭证本身的权限不足：比如子模块是私有仓库，但你用的Jenkins凭证账号没有该仓库的拉取权限；
• 凭证类型不匹配：比如子模块用HTTPS URL，但你配置的是SSH密钥凭证，反之亦然。

排查方法：

• 进入两个Job的「源码管理」配置页，确认都绑定了正确的凭证；
• 用凭证对应的账号，手动在本地克隆子模块仓库，验证是否能成功拉取，以此排除权限问题；
• 如果是SSH凭证，确保Jenkins代理节点的ssh-agent服务能正确加载密钥，或者节点的~/.ssh/config配置了正确的GitHub主机信息。

3. 子模块的引用版本权限受限 #

报错分支对应的子模块，可能引用了一个你没有权限访问的版本：
比如主仓库的报错分支中，子模块指向的是一个私有分支/特定commit，而你的Jenkins凭证账号没有访问该版本的权限；而正常分支的子模块指向的是公开分支或有权限的版本。

排查方法：
在报错分支下执行命令，查看子模块的引用信息：

git submodule status

然后去GitHub后台，检查该子模块的对应commit/分支，确认Jenkins凭证账号是否有访问权限。

4. Jenkins代理节点的环境差异 #

如果两个Job运行在不同的Jenkins代理节点上，节点的环境配置可能存在差异：

• 正常Job的代理节点有正确的Git配置、SSH密钥或HTTPS凭证缓存，而报错的代理节点没有；
• 节点的网络环境不同，比如报错节点无法访问GitHub的特定协议端口（比如SSH的22端口被限制）。

排查方法：

• 查看两个Job的运行日志，确认是否在同一个代理节点上执行；
• 如果节点不同，登录报错的代理节点，手动执行git submodule update --init --recursive --remote命令，模拟Jenkins的执行过程，看是否会出现同样的403错误，进而定位节点环境问题。

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