jenkee

為什麼需要 jenkee？

我對 Jenkins Web UI 不太在行。每次要看 job 的設定，都得展開一堆選單才能找到資訊。更麻煩的是，很多重要的配置細節藏在 XML 裡，不下載回來根本看不清楚。

最初，我只是想做一個簡單的工具：用命令列出 jobs、抓下 XML、然後自己 diff 比對。那時候我直接呼叫 jenkins-cli.jar，還特地寫了 prompt 來教 AI agent 怎麼用。 但很快就發現問題了。AI agent 常常搞錯 jenkins-cli.jar 的參數格式，明明教過還是會出錯。我開始思考：與其一直教它用複雜的工具，不如直接把工具改簡單一點？ 於是我把常用的操作包裝成簡單的 CLI 命令。神奇的事情發生了：AI agent 幾乎不用特別教，看看 help 就能正確使用。原來簡化介面真的能讓 AI 更好發揮。

後來工具慢慢長大了。從最初的 list、get、diff，擴展到完整的 Jenkins 管理功能。現在有 25 個命令和完整的測試覆蓋，但核心理念沒變：讓 AI agent 幫你探索和管理 Jenkins。

一開始我們專注在唯讀操作：列出 jobs、抓配置、看 console。這些操作很安全，不會改變 Jenkins 的任何東西。這也是為什麼專案的 repository 名稱叫 jenkins-inspector，因為那時候真的只有檢視、探索資料的功能。後來才慢慢加入管理功能：建立 job、觸發 build、刪除資源。這些會變更 Jenkins 內容的操作，我們都加上了特別的提醒和確認機制。

特色

• 🚀 25 個完整的 Jenkins CLI 命令
• 🧪 完整的測試覆蓋所有功能
• 🤖 專為 AI Agent 設計的互動模式
• 🔒 支援多種 Jenkins credentials 類型
• 🌐 支援多站台 profile，一個 CLI 管理多組 Jenkins
• 📦 透過 PyPI 輕鬆安裝
• 💬 清晰的 help 訊息，AI agent 容易理解

快速開始

# 安裝
pip install jenkee

# 設定認證
mkdir -p ~/.jenkins-inspector
cat > ~/.jenkins-inspector/.env << EOF
JENKINS_URL=http://your-jenkins-server:8080/
JENKINS_USER_ID=your_email@example.com
JENKINS_API_TOKEN=your_api_token
EOF

# 驗證連線
jenkee auth

# 列出所有 jobs
jenkee list-jobs --all

# 觸發 build
jenkee build my-job

安裝

從 PyPI 安裝（推薦）

pip install jenkee

或使用 pipx（建議用於 CLI 工具）：

pipx install jenkee

開發模式安裝

如果想要參與開發或修改程式碼：

# Clone repository
git clone https://github.com/qrtt1/jenkins-inspector
cd jenkins-inspector

# 啟用虛擬環境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 以 editable 模式安裝
pip install -e ".[dev]"

與 AI Agent 協作

jenkee 從一開始就是設計給 AI agent 用的。命令結構很簡單：jenkee <command> [options]，不需要記憶複雜的參數組合。

每個命令都有詳細的 help 說明和範例（jenkee help <command>）。AI agent 看一眼就知道怎麼用。輸出格式也很規律，方便它解析和理解。

如果你想讓 Claude Code 幫你操作 Jenkins，直接安裝下面的 jenkins-helper skill 即可，不需要額外準備 prompt 文字。

Claude Code Skill

如果你使用 Claude Code CLI，可以透過 marketplace 安裝 jenkins-helper plugin，它整合了 jenkee 的完整功能和最佳實踐，並附帶一個攔截危險 jenkee 指令、提醒確認目標站台的 PreToolUse hook。

/plugin marketplace add qrtt1/jenkins-inspector
/plugin install jenkins-helper@jenkins-inspector

plugin 原始碼位於 plugins/jenkins-helper/。

設定認證

# 建立設定檔目錄
mkdir -p ~/.jenkins-inspector

# 編輯 .env 檔案
cat > ~/.jenkins-inspector/.env << EOF
JENKINS_URL=http://your-jenkins-server:8080/
JENKINS_USER_ID=your_email@example.com
JENKINS_API_TOKEN=your_api_token
EOF

# 驗證認證
jenkee auth

可用命令

一般命令

詳細使用說明請參考 docs/examples/ 目錄下的各命令文件。

進階與危險命令請參考 README.advanced.md。

主要功能

1. 探索 Jenkins 架構

• 列出所有 views 和 jobs
• 查看 job 配置與狀態
• 追蹤 job 觸發關係

2. Build 管理

• 觸發 job builds（支援參數、同步與追蹤模式）
• 停止執行中的 builds
• 查看 build 歷史與 console 輸出

3. Job 管理

• 建立、複製、更新 job 配置
• 比較 job 配置差異
• 將 jobs 加入 views

4. Credentials 管理

• 列出所有 credentials metadata
• 查看 credentials 類型與相關資訊
• 驗證 credentials 配置

5. 多站台 Profile 管理

• 用 named profile 管理多組 Jenkins 連線設定
• jenkee profile list/use/current 列出、切換、查詢目前站台
• 也可用 --profile <name> 或 JENKEE_PROFILE 環境變數單次覆蓋，不動持久設定

文件

• README.advanced.md - 進階與危險命令
• CODING_GUIDE.md - 專案開發指南
• docs/examples/ - 各命令使用範例

開發指引

如果你是 AI agent 正在開發此專案，請務必先閱讀 CODING_GUIDE.md。

該文件包含：

• 專案架構原則與設計模式
• 新增 command 的完整流程
• 程式碼格式化規範（Black）
• AI Agent 開發 checklist

遵循 CODING_GUIDE 可確保：

• 程式碼風格一致
• 功能完整實作（包含 help、example 文件）
• 通過所有整合測試