如何重置 Jenkins 建置編號：清除 Build History 與設定 Next Build Number
說明如何透過 Jenkins Script Console 清除指定 Job 的建置紀錄並重設下一個 Build Number，以及執行前必須確認的風險與限制。
在部分 Jenkins Pipeline 中，建置編號會被放進應用程式的版本字串，例如：
1
0.0.${BUILD_NUMBER}
其中最後一段直接使用 Jenkins 的 BUILD_NUMBER。當 major 或 minor version 提升後，團隊有時會希望 patch number 重新從 1 開始，因此產生重置 Jenkins 建置編號的需求。
不過，Jenkins 的建置編號原本就是單調遞增的識別碼。重置編號不是一般的版本發布流程，而且若要將下一個編號降回 1，必須先刪除該 Job 的既有建置紀錄。這是一項具破壞性的管理操作，不能只把它當成版面整理功能。
執行前需要確認的事項
本文使用 Jenkins Script Console 執行 Groovy 腳本。Script Console 具有完整的 Jenkins controller 權限，只有擁有 Overall/Administer 權限的管理者才能使用。
執行前應先確認：
- Job 目前沒有正在執行或排隊中的建置。
- 已備份仍需保留的 Console Log、Artifact、測試報告與稽核紀錄。
- 其他系統沒有持續引用既有的 Jenkins Build URL 或 Build Number。
- 已確認 Job 的完整名稱，特別是位於 Folder 或 Multibranch Pipeline 下的 Job。
- 最好先在非正式環境測試腳本並備份 Jenkins 設定。
刪除 Build History 後，原有建置頁面、紀錄與保存在 Build 目錄中的 Artifact 都可能無法復原。若只是想清理過舊紀錄，應優先考慮設定 Build Discarder，而不是重置編號。
使用 Script Console 重置編號
以具備管理權限的帳號登入 Jenkins，前往：
1
Manage Jenkins → Script Console
以下是我當時實際執行的 Groovy 腳本。執行前，必須將 your-job-name-here 替換成目標 Pipeline 的名稱：
1
2
3
4
5
6
item = Jenkins.instance.getItemByFullName("your-job-name-here")
// THIS WILL REMOVE ALL BUILD HISTORY
item.builds.each() { build ->
build.delete()
}
item.updateNextBuildNumber(1)
這段腳本會取得指定的 Pipeline、逐一刪除所有 Build History，最後將下一次建置編號設定為 1。它沒有額外檢查 Job 名稱是否正確，也不會詢問是否確認刪除，因此應在執行前自行確認目標與備份狀態。
確認執行結果
執行完成後，回到 Job 頁面，可以看到原本的 Build History 已清空。再次觸發 Pipeline 時，新建置的編號會從 #1 開始。若 Pipeline 使用 ${BUILD_NUMBER} 組合版本字串，也要確認產生的版本沒有和既有 Artifact、Container Image 或已發布套件重複。
是否真的需要重置？
如果建置編號已被外部系統當作唯一識別碼，重複使用 #1 可能造成追蹤與稽核上的混淆。較穩定的設計是讓 Jenkins Build Number 持續遞增，再將應用程式版本與建置識別碼分開，例如：
1
2
Application version: 2.0.0
Build metadata: Jenkins #183
只有在確定歷史紀錄可以刪除，而且外部系統不依賴舊編號時，才建議執行重置。若需求只是將下一個編號調高，可以考慮 Next Build Number Plugin；Jenkins 不允許在保留較大歷史編號的同時，將下一個編號設定成更小的值。