Jenkins克隆Git子模块未使用凭证致认证失败求助

问题复盘 #

主仓库通过HTTPS+Bitbucket应用密码拉取正常，但子模块拉取时提示认证失败，已勾选Git Plugin的「递归更新子模块」和「使用父仓库默认远程的凭证」选项，修改.gitmodules添加用户名可解决但影响团队协作，需在不改动仓库配置的前提下解决。

方案1：Git全局URL替换（推荐，无侵入） #

通过Git的url.insteadOf配置，让Jenkins拉取Bitbucket仓库时自动注入凭证，不修改仓库内的.gitmodules：

1. 在Jenkins项目中添加构建前执行步骤：
   • Linux选「Execute shell」，Windows选「Execute Windows batch command」
2. 执行以下命令（替换<你的Bitbucket用户名>和<应用密码>）：

   git config --global url."https://<你的Bitbucket用户名>:<应用密码>@bitbucket.org/".insteadOf "https://bitbucket.org/"
   

3. 原理：Git会自动将所有https://bitbucket.org/开头的仓库URL替换为带凭证的版本，子模块拉取时会自动套用该凭证，本地开发者的.gitmodules不受任何影响。

方案2：Credentials Binding插件临时注入凭证 #

利用Jenkins插件临时修改子模块URL，避免污染仓库配置：

1. 安装「Credentials Binding Plugin」插件
2. 在项目的构建环境中勾选「Use secret text(s) or file(s)」
3. 添加「Username and password (separated)」类型的凭证绑定，设置环境变量为BB_USER（用户名）和BB_PASS（应用密码）
4. 添加构建前执行步骤，执行命令：

   git submodule sync
   git config submodule.Logical/Libraries.url "https://${BB_USER}:${BB_PASS}@bitbucket.org/anoaou/libraries.git"
   

5. 该操作仅在本次构建生效，不会修改仓库内的.gitmodules文件，不影响其他开发者。

方案3：Jenkins单独使用SSH拉取子模块（无需团队切换） #

给Jenkins配置独立SSH密钥，单独用SSH拉取子模块，团队仍用HTTPS：

1. 生成Jenkins专用SSH密钥对，将公钥添加到Bitbucket账号的「SSH keys」列表中
2. 在Jenkins凭证库添加该SSH私钥凭证
3. 在项目的Git配置中，保持主仓库HTTPS拉取不变，在高级子模块行为中勾选「Override credentials for submodules」，选择刚才添加的SSH私钥凭证
4. 添加构建前执行步骤，同步并替换子模块URL：

   git submodule sync
   git config submodule.Logical/Libraries.url "git@bitbucket.org:anoaou/libraries.git"
   

5. 此方案仅Jenkins用SSH拉取子模块，本地开发者仍使用仓库中配置的HTTPS URL，互不干扰。

额外排查要点 #

• 确认Bitbucket应用密码拥有Repository read权限，没有权限会导致认证失败
• 检查Git版本：确保Jenkins使用的Git版本支持url.insteadOf特性（你已使用最新版，此条可忽略）
• 验证「使用父仓库默认远程的凭证」选项：该功能要求主仓库与子模块的URL域名完全一致（均为bitbucket.org，符合要求），若仍不生效，优先尝试上述方案

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