凭证这东西乍看是Jenkins里一个不起眼的下拉框实际却是很多人从装完Jenkins到真正跑通第一条流水线之间最大的一只拦路虎。我自己刚开始搭CI的时候卡在Git拉取权限上整整一个下午最后发现问题既不是插件没装也不是网络不通而是凭证类型选错了——用SSH类型的凭证去配HTTPS地址Jenkins不会给你任何友好提示只会甩一句exit code 128。这篇笔记就围绕Jenkins添加Git凭证这件事把选型、录入、引用、验证、排错整条链路捋一遍适合刚上手Jenkins、准备接代码仓库做自动化构建的朋友也适合已经跑起来但偶尔被认证问题反咬一口的同行对照着排查。1. 凭证这件事为什么值得单独拎出来讲1.1 把账号密码直接写进Job配置的代价我见过太多能跑就行的配置在Job的源码管理里把Git地址写成https://用户名:密码仓库地址.git或者干脆在构建脚本里git clone https://xxx:yyy...。这种写法第一眼确实省事不用管什么凭证插件填完就能拉代码。但它埋的雷一个比一个狠。首先密码明文躺在config.xml里任何有Jenkins后台读取权限的人点开Job配置就能看到其次密码一旦轮换所有硬编码的地方都要一个个改十个Job改十次再往深了说Jenkins的构建日志和控制台输出里很可能把带密码的URL原样打印出来谁翻了构建历史都能捞到。这三条随便中一条在企业内网里都够喝一壶的。所以Jenkins从很早就把凭证抽成了独立的credentials插件体系目的就一个让密码、密钥这类敏感信息只存一份、加密保存Job里只引用一个ID。你在配置里看到的是my-git-credential这样的名字真正的密码在磁盘上是密文。改密码时只改凭证一处所有引用它的Job自动生效。1.2 Jenkins到底把凭证藏在了哪里很多人好奇我填的密码去哪了。它落在$JENKINS_HOME/credentials.xml里但里面存的是加密后的字符串形如一段看不懂的哈希。解密靠的是$JENKINS_HOME/secret.key和主密钥文件这两样东西一旦丢失凭证就解不开了只能重建。这解释了一个常见现象你把Jenkins整个目录拷贝到另一台机器Job配置都在但凭证全部变成无法解析因为主密钥和你拷贝时可能没带全或者系统做了额外的保护。提示备份Jenkins时credentials.xml和secret.key必须成对备份只拷其中一个等于没备份。迁移环境尤其注意这点。理解了这层存储机制你就能明白为什么Jenkins不鼓励你在脚本里回显凭证也为什么凭证更新后老Job偶尔抽风——多数是缓存或者引用ID写错了而不是凭证没保存成功。1.3 三层作用域别一股脑全塞全局新建凭证时会让你选作用域最常见的两个选项是全局和系统。全局意味着所有Job都能用系统则限制得更严通常只有系统级配置和节点相关的地方能读。此外还有文件夹级作用域配合文件夹文件夹Folder功能可以让不同团队、不同项目的凭证互相隔离。我的建议是按项目边界来放公共的、所有流水线都要用的比如公司统一的制品库账号放全局某个业务线专用的放对应的文件夹级凭证。这样既能减少误引用也能在权限上做隔离。一开始全塞全局最省事但项目一多凭证列表会变成一锅粥后面找起来痛苦。2. 动手之前先把连什么、怎么连想清楚2.1 HTTPS令牌与SSH密钥的取舍Git凭证主流就两条路HTTPS走用户名密码或访问令牌SSH走公私钥。两者没有绝对优劣取决于你的环境和习惯我把实际用下来的对比列个表。维度HTTPS 访问令牌SSH 公私钥是否需要平台额外配置生成Token即可需把公钥传到平台防火墙友好度高走443需放行22端口代理环境下较好配置相对麻烦密钥轮换平台撤销Token换密钥对重贴公钥适合场景临时、多平台、受控网络长期稳定的固定构建机常见坑用登录密码而非Token导致失败known_hosts未配置导致主机校验失败简单说如果构建机在公司内网、出口有限制优先HTTPS如果是自建GitLab、机器固定、追求免密和稳定SSH更省心。我在实际项目里往往是代码托管平台的公共仓库用HTTPS令牌自建GitLab用SSH。2.2 主流代码平台的凭证差异不同平台对密码的定义不太一样这点新手最容易栽跟头。GitHub早就不能直接用账户密码做Git操作了必须用Personal Access TokenGitLab同理推荐用Project Access Token或Personal Access TokenGitee也是令牌优先。也就是说当Jenkins问你要用户名和密码时这个密码填的应该是令牌而不是你登录网页的那个密码。一个实用的判断方法如果你用账号密码在命令行git clone都被拒绝那Jenkins里填同样的东西也一定被拒绝。先在命令行验证一遍再去Jenkins里配能省掉大量来回试错的时间。2.3 凭证ID的命名别偷懒Jenkins允许你给凭证填一个ID留空的话它会自动生成一串UUID。我强烈建议手动起名并且形成规范比如git-github-deploy-token、git-gitlab-ssh-build、nexus-release-user这种用途-平台-类型的结构。原因很实际Pipeline脚本里是靠ID来引用的credentials(xxx)那个字符串如果是一串UUID你复制粘贴时看花眼是迟早的事。命名规范一点脚本可读性和后期维护成本都会低很多。3. HTTPS方式从生成令牌到Jenkins录入3.1 先在代码平台生成访问令牌以常见的GitLab为例进用户设置里的Access Tokens勾选read_repository只拉代码的话足够了要给流水线推送标签或提交再考虑write_repository设置有效期生成后那一串令牌只显示一次务必当场复制。GitHub在Settings的Developer settings里生成fine-grained token权限里把目标仓库的Contents设为Read即可。Gitee在个人设置的安全设置里生成私人令牌。这里有个经验令牌有效期别图省事设成永久。设个90天或半年配合日历提醒轮换比某天突然全部流水线挂掉要可控得多。轮换的时候Jenkins里只需要在凭证页面点更新所有引用的Job不用动。3.2 在Jenkins里录入Username with password凭证路径是系统管理 → Credentials → 系统 → 全局凭据 → Add Credentials。类型选Username with password。用户名填你代码平台的账号名GitLab有时要填oauth2或令牌所属用户名以能拉通为准密码栏粘贴刚才的令牌ID按2.3的规范填描述写清楚用途。保存即可。几个容易忽略的点用户名大小写敏感别多打空格令牌粘贴时前后不能有换行从网页复制容易带上不可见字符建议先粘到记事本确认没有换行再填进去。这类多了一个换行导致认证失败的问题我至少遇到过三次。另外如果你是在Windows上装的Jenkins安装向导阶段会要求设置管理员账号那一步和Git凭证没关系但新装完第一件事就是确认插件Git、Credentials Binding、Git client都装好了否则新建凭证的界面里根本看不到Git相关类型。3.3 自由风格项目和Pipeline里的两种引用姿势自由风格项目最简单源码管理选Git填仓库URL在Credentials下拉里选中你刚建的凭证。Jenkins会自动用它拉代码构建日志里密码部分会以掩码形式出现不会泄漏。Pipeline则分两块。声明式流水线里用credentials()辅助方法绑定到环境变量或者直接在checkout步骤里指定pipeline { agent any stages { stage(Checkout) { steps { git branch: main, url: https://git.example.com/team/demo.git, credentialsId: git-gitlab-deploy-token } } stage(Build) { steps { withCredentials([usernamePassword( credentialsId: git-gitlab-deploy-token, usernameVariable: GIT_USER, passwordVariable: GIT_PASS)]) { sh echo 拉取完成用户为 $GIT_USER } } } } }要注意withCredentials绑定的变量在块外是取不到的这是有意设计防止敏感值泄漏到后续步骤。还有个小细节如果你在sh里用了带密码的变量拼URLJenkins会在日志里自动打码但脚本里set -x之类的调试输出可能绕过掩码逻辑调试完记得关掉。4. SSH方式配一次长期免密4.1 生成密钥对在构建机上执行ssh-keygen -t ed25519 -C jenkins-buildexample.com -f ~/.ssh/id_jenkins_git-t ed25519是现在的推荐算法比老的RSA更短更安全如果平台较老不支持再退回rsa -b 4096。-f指定文件名避免覆盖你个人的密钥。命令会让你设passphrase构建用的密钥一般不设或者设了的话要在Jenkins凭证里一并填入否则每次拉取都会卡在交互式输入。Windows下用Git Bash执行同样的命令即可生成的密钥默认在用户目录的.ssh文件夹。生成后得到两个文件id_jenkins_git私钥绝不能外传和id_jenkins_git.pub公钥贴到平台。4.2 公钥贴到代码平台GitLab在用户设置的SSH Keys里粘贴公钥内容GitHub在Settings的SSH and GPG keys里新增Gitee在安全设置的SSH公钥里添加。粘贴的是.pub文件里的整段文本包括末尾的邮箱注释。用cat ~/.ssh/id_jenkins_git.pub打印出来完整复制别手敲。添加完成后先在命令行验证ssh -T gitgit.example.com看到欢迎信息就说明公钥生效了。这一步必须先过再去Jenkins里配否则你分不清是密钥问题还是Jenkins配置问题。4.3 Jenkins里录入SSH凭证新建凭证时类型选SSH Username with private key。Username填git注意SSH方式连GitLab/GitHub用户名基本都是固定的git不是你的账号名这个反直觉的点坑过很多人。私钥部分可以直接把内容粘贴进去也可以指定Jenkins主机上的密钥文件路径。如果私钥设了passphrase在Passphrase栏里填上。ID命名同样按规范来比如git-gitlab-ssh-build。保存后源码管理里的Git地址要换成SSH格式gitgit.example.com:team/demo.git类型和地址必须配套这是最容易配错的地方。4.4 known_hosts 主机指纹的坑SSH方式最典型的报错是Host key verification failed。原因是首次连接时SSH不知道目标主机的指纹会弹交互式确认而Jenkins构建是非交互的直接失败。解决办法有两种一是在Jenkins里装Git Host Key Verification Configuration插件配置接受策略二是提前在Jenkins运行用户的~/.ssh/known_hosts里写入目标主机指纹手动执行一次ssh-keyscan git.example.com ~/.ssh/known_hosts即可。注意ssh-keyscan拿到的指纹最好和平台官方公布的指纹比对一次直接信任扫描结果在有中间人的环境里有风险。内网自建GitLab相对可控公网平台建议核对。我个人的做法是构建机初始化脚本里就把这一步做掉省得每台新机器都要人工处理一遍。5. 连GitLab时的额外一步GitLab Connection5.1 为什么要单独配Connection如果你的链路只到拉代码那上面第3、第4节就够用了。但很多人真正想要的是提交代码自动触发构建把构建状态回写到GitLab的提交记录上这就要装GitLab插件并在系统管理 → 系统 → GitLab里配置一个Connection填GitLab的地址、API Token类型的凭证、连接名。这里用到的凭证类型是GitLab API token和前面的Git凭证不是一回事。API Token要去GitLab的用户设置里生成权限通常是api。Connection配好后Job里勾选Build when a change is pushed to GitLab就能实现push触发。Webhook地址由Jenkins提供需要填回GitLab项目的Webhook设置里。5.2 API Token 与 Git 凭证明明分开新手常犯的错把拉代码用的令牌当成API Token填进Connection结果测试连接时报权限不足。原因是两者用途不同——拉代码用的是仓库读权限触发和回写状态用的是API权限。所以你会看到凭证列表里同一个平台有两个凭证一个是git-xxx-token一个是gitlab-api-xxx这是正常的别嫌乱分清楚了后面排错也快。6. 凭证配完了怎么确认它真的生效6.1 用最小Pipeline验证不要直接拿现有的复杂Job去试配错了报错信息会被淹没。我习惯新建一个只有checkout阶段的临时Pipeline几行代码验证pipeline { agent any stages { stage(Verify Credential) { steps { git branch: main, url: https://git.example.com/team/demo.git, credentialsId: git-gitlab-deploy-token sh ls -al git log --oneline -3 } } } }能拉下来并且git log有输出说明凭证和地址都对了。验证通过再删掉这个临时Job干净利落。6.2 常见报错速查表报错信息关键词大概率原因处理方向Authentication failed用了登录密码而非令牌令牌过期重新生成令牌并更新凭证exit code 128凭证类型与地址不配套SSH地址配了账号密码凭证或反之Host key verification failedknown_hosts缺失预写主机指纹或调整校验策略not found / 404地址拼写错误或仓库无权限核对URL与账号仓库权限Permission denied (publickey)公钥未生效或用户名填错命令行验证SSH用户名应为git403 rate limit令牌权限或频率限制检查权限范围考虑提高配额6.3 几个我踩过的坑顺手记下来第一个坑是凭证更新后老Pipeline不生效。多数情况是缓存问题重启Jenkins或清一下构建缓存能解决少数是Job里引用的是另一个ID你以为改的是A实际用的是B。第二个坑是共享文件夹网络凭证——如果你的构建要把产物写到Windows网络共享用的是另一套凭证体系凭据管理器那套和Git凭证完全不搭边别混为一谈。第三个坑是环境变量污染有人在全局环境变量里设了GIT_ASKPASS或GIT_USERNAME导致凭证引用被覆盖排查时记得看一眼全局配置。关于轮换我的做法是建一个简单的凭证台账记下每个凭证的用途、平台、有效期。令牌快到期前提前更新更新时在Jenkins里直接改密码字段保留原ID所有Job零改动。这套流程跑顺之后CI的认证问题基本就告别了。最后分享一个判断技巧任何认证类问题先在命令行用同样的方式、同样的账号手工跑一遍git clone。命令行能过而Jenkins不能过问题一定出在Jenkins的凭证配置或主机环境命令行都过不了那就和Jenkins没关系了去平台侧找权限或令牌的原因。这条思路帮我省下的时间比任何排错文档都多。