Jenkins Shared Library Branch Risk¶
概念概覽
核心風險¶
核心知識¶
核心風險¶
Jenkins shared library 引用的分支版本是**高度隱性的風險點**。Pipeline 代碼本身完全沒有改變，只是 library 引用從 common@main 切換到 common@feat/shallow-fetch，就能導致 credential 類型期望改變，錯誤訊息卻指向 credential 而非 library 版本，排查方向很容易偏移。
具體機制¶
credentials()若指定credentialType: 'BasicSSHUserPrivateKey'，實際傳入 StringCredentials 時直接在 pipeline 觸發時報錯- 改成
credentialType: 'Any'可解除類型檢查，但失去類型安全保護（trade-off） - 功能分支的 library 會帶入對 credential 類型的不同假設，而這個假設往往沒有文件記載
管理建議¶
- 生產 pipeline 只能引用
main或穩定 tag，功能分支（@feat/xxx）僅允許在測試環境引用 - 合併功能分支前，需確認所有 credential 類型期望已在
main上統一
經驗教訓¶
-
Pipeline 本身不動，library 分支切換就能炸掉 credential 邏輯，排查時務必先確認 shared library 的引用分支
-
credentialType: 'Any' 是快速解法但會喪失類型保護，需在 trade-off 中有意識地選擇
-
生產環境 shared library 版本策略必須明文規定，不能放任各 pipeline 各自引用功能分支
常見陷阱¶
-
錯誤訊息指向 credential 類型不符，而非 library 版本，容易誤導排查方向
-
feature branch 的 library 行為變更往往沒有 changelog，只能讀 diff 才知道
最佳實踐¶
-
生產 pipeline 只使用 @main 或 @stable-tag 引用 shared library
-
合併功能分支前，確認所有使用該 library 的 pipeline credential 設定一致性
相關概念¶
- jenkins-credentials-management----dangling-------dangling---
- Jenkins Pipeline Silent Failure
- Jenkins SSH to Secret Text Credential Migration
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Jenkins Pipeline kubectl exec Target — 共享：
ci-cd,jenkins,pipeline/ 獨特：automation,kubectl
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-26 | 85f4d935-df5b-46e9-9e46-529869bf6e72 | 實測揭露 shared library 的功能分支切換是隱性 credential 類型不符根因 |