Jenkins代理克隆Bitbucket子模块遇Permission denied(publickey)错误求助

问题描述 #

Jenkins主节点运行作业时，克隆主仓库后执行git submodule update --init --recursive能正常拉取子模块，但相同作业在新增的代理节点执行时，触发权限错误：

Permission denied (publickey). fatal: Could not read from remote repository.

已尝试的无效排查步骤 #

• 确认SSH密钥已添加至代理节点的SSH代理
• 验证代理节点对克隆目录具备读写权限
• 手动以当前用户连接子模块仓库成功，Bitbucket UI显示密钥已被使用，但Jenkins作业执行时仍报错
• 将代理节点主目录改为/var/lib/jenkins，密钥存放于/var/lib/jenkins/.ssh/id_rsa

解决方案建议 #

1. 验证Jenkins代理进程用户的密钥访问权限 #

Jenkins代理通常以jenkins系统用户运行，手动测试可能使用的是其他用户，需切换到该用户下验证：

su - jenkins
git clone git@bitbucket.org:<your-team>/<submodule-repo>.git

同时检查密钥文件权限（SSH强制要求）：

chmod 700 /var/lib/jenkins/.ssh
chmod 600 /var/lib/jenkins/.ssh/id_rsa

2. 配置Git强制指定Bitbucket密钥 #

在代理节点的jenkins用户下创建~/.ssh/config文件，明确Bitbucket主机使用的密钥：

Host bitbucket.org
    IdentityFile /var/lib/jenkins/.ssh/id_rsa
    IdentitiesOnly yes

IdentitiesOnly yes会强制SSH使用指定密钥，避免自动选择其他无效密钥。

3. 确认Jenkins凭据在代理节点的有效性 #

• 确保作业中配置的SSH凭据已正确同步到代理节点（全局凭据默认同步，作业级凭据需确认配置）
• 在作业中添加步骤，打印子模块配置并验证：

git config --list | grep submodule

检查子模块的远程URL是否为正确的SSH格式，且与主仓库的.gitmodules配置一致。

4. 检查Jenkins代理的环境变量与SSH代理状态 #

Jenkins代理进程的环境变量可能与手动登录时不同，需验证：

• 在作业中添加步骤打印环境变量：printenv | grep SSH，确认SSH_AUTH_SOCK是否存在且指向正确的代理套接字
• 如果使用ssh-agent，需确保Jenkins代理启动时已加载密钥，或在作业中手动执行：

eval $(ssh-agent -s)
ssh-add /var/lib/jenkins/.ssh/id_rsa

5. 验证Bitbucket公钥的仓库访问权限 #

• 确认Bitbucket中添加的公钥拥有子模块仓库的读取权限（若子模块为私有仓库，需检查仓库的访问控制列表）
• 在jenkins用户下执行SSH测试：

ssh -T git@bitbucket.org

若输出logged in as <your-username>.则认证成功，否则需重新检查公钥配置。

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