本工具專為雲端運維團隊設計，能夠自動從 GitLab 專案中擷取 Issue 資訊，同步至 Google Sheet 並以甘特圖形式呈現，同時生成詳細的雙月工作分析報表。主要用於追蹤團隊成員在不同工作類型的時間分配，協助管理層進行資源規劃與績效評估。
- 📊 自動化甘特圖生成：將 GitLab Issue 轉換為視覺化時間軸
- 📈 樞紐分析表報表：生成詳細的工作類型分析與趨勢比較
- 🔄 智能同步機制：避免重複處理，僅同步新增 Issue
- 👥 多人協作支援：單一 Issue 可由多人共同處理
- 🎯 靈活專案配置：支援標籤篩選或全開放 Issue 擷取
- 📅 時間範圍控制：可設定起始日期進行過濾
GitLab API ──► 數據處理器 ──► Google Sheet ──► 甘特圖 ──► 樞紐分析表報表
↓ ↓ ↓ ↓ ↓
Issue 擷取 標籤篩選 時間軸生成 進度追蹤 工作分析
| 模組 | 功能說明 |
|---|---|
main.py |
主程序入口，整合各模組功能 |
config_handler.py |
配置管理，支援欄位定義與用戶角色 |
gitlab_api_handler.py |
GitLab API 互動，含重試機制 |
data_processor.py |
數據處理與篩選邏輯 |
google_sheet_api_handler.py |
Google Sheet API 操作 |
worksheet_manager.py |
甘特圖工作表管理 |
report_generator.py |
樞紐分析表報表生成 |
utils.py |
日期處理與工具函數 |
logger.py |
系統日誌管理 |
- Python 3.6 或更高版本
- 網路連線至 GitLab 和 Google API
- GitLab API 存取權限
- Google API 服務帳號憑證
pip install -r requirements.txt主要依賴套件：
google-api-python-client==2.79.0
google-auth==2.16.0
python-gitlab==3.13.0
pyyaml==6.0
systemd-python==234
requests==2.28.2- 前往 Google Cloud Console
- 創建專案並啟用 Google Sheets API
- 創建服務帳號並下載 JSON 憑證檔案
- 將 Google Sheet 共享給服務帳號的電子郵件地址
- 更新
config.yaml中的憑證路徑
- 登入 GitLab 並前往個人設定
- 創建具有
api權限的個人存取權杖 - 更新
config.yaml中的權杖資訊
# 僅更新甘特圖（不生成報表）
python3 main.py
# 更新甘特圖並生成樞紐分析表報表
python3 main.py -r
python3 main.py --report# 每日凌晨更新甘特圖
0 0 * * * /usr/bin/python3 /path/to/main.py
# 每月 1 日生成報表
0 0 1 * * /usr/bin/python3 /path/to/main.py --report
# 每週一檢查並同步
0 8 * * 1 /usr/bin/python3 /path/to/main.py[Unit]
Description=GitLab Issue Gantt Sync
After=network.target
[Service]
Type=oneshot
User=ubuntu
ExecStart=/usr/bin/python3 /path/to/main.py
WorkingDirectory=/path/to/project- ✅ 從 GitLab 擷取 Issue 資訊並填入 A、B 欄
- ✅ 自動生成完整年度甘特圖時間軸
- ✅ 創建 Owner、Type、SubType 下拉選單
- ✅ 創建 Closed 欄位的核取方塊
- ✅ 設定週末背景色與欄位格式
- 📝 C 欄 (Owner)：選擇負責人
- 📝 D 欄 (Type)：選擇工作類型
- 📝 E 欄 (SubType)：選擇子類型
- 📝 F 欄 (Closed)：勾選是否已關閉
- 📝 G 欄 (Note)：填寫備註
- 📝 時間軸區域：填入處理 Issue 的人員名稱（支援多人，以逗號分隔）
- 📊 系統自動根據甘特圖數據生成雙月樞紐分析表
- 📈 顯示各人員在不同工作類型的時間分配
- 📉 計算各類型工作的佔比及與前期的變化趨勢
- 👤 為每個一般使用者（非主管）生成獨立報表頁籤
| 欄位 | 說明 |
|---|---|
| Type | 工作類型 |
| SubType | 第二階分類 |
| Issue | 具體 Issue 標題 |
| Workday | 工作天數 |
| Workday 佔比 | 該 Issue 在總工作天數中的比例 |
| Workday @ SubType 佔比 | SubType 在總工作天數中的比例 |
| SubType 與前次雙月差異 | 與前一個雙月期間的變化 |
| Workday @ Type 佔比 | Type 在總工作天數中的比例 |
| Type 與前次雙月差異 | 與前一個雙月期間的變化 |
- 🎯 Issue 級別統計：精確到每個 Issue 的工作天數
- 📊 多層次分析：Type → SubType → Issue 的階層結構
- 📈 趨勢比較：與前一個雙月期間的百分比變化
- 👥 個人化報表：每位成員獨立的工作統計頁籤
- 🔢 自動計算：合併儲存格與百分比格式自動處理
# 檢查憑證檔案路徑和權限
ls -la /path/to/credentials.json解決方案：
- 確認憑證檔案存在且可讀取
- 檢查服務帳號是否有 Google Sheet 存取權限
- 驗證 spreadsheet_id 是否正確
# 測試 API 連線
curl -H "PRIVATE-TOKEN: your_token" "https://your-gitlab.com/api/v4/projects"解決方案：
- 檢查 GitLab URL 和 token 設定
- 確認 token 具有
api權限 - 檢查網路連線狀態
症狀： 時間軸生成失敗或數據同步異常
解決方案：
- 檢查
config.yaml中的欄位定義 - 確認工作表標頭與預期一致
- 重新生成工作表或手動調整結構
# 查看系統日誌
journalctl -t gitlab-gantt-sync
# 查看最近的錯誤
journalctl -t gitlab-gantt-sync -p err --since "1 hour ago"
# 即時監控日誌
journalctl -t gitlab-gantt-sync -f# 臨時啟用除錯模式
log_config:
level: "DEBUG"
console_output: true- Google Sheets API：預設每批次 3 個請求，間隔 0.5 秒
- GitLab API：重試機制 3 次，間隔 5 分鐘
- 報表生成：用戶間延遲 15 秒，避免配額超限
- 工作表數據快取，避免重複 API 調用
- 時間軸解析結果快取，提升報表生成效率
- 編輯
config.yaml中的type_list和subtype_list - 重新執行程式，下拉選單將自動更新
- 修改
config.yaml中的worksheet_columns - 調整
expected_headers對應的標頭名稱 - 系統將自動適配新的欄位結構
gitlab:
project_id_list:
- project_id: 新專案ID
name: "專案名稱"
fetch_all_open_issues: true # 或使用標籤篩選本專案採用 MIT 授權條款。
-
克隆專案
git clone <repository-url> cd gitlab-issue-gantt-sync
-
安裝依賴
pip install -r requirements.txt
-
配置設定
cp config.yaml.example config.yaml # 編輯配置檔案 -
首次執行
python3 main.py --report
-
檢查結果
- 開啟 Google Sheet 查看甘特圖
- 檢查個人報表頁籤
🎉 恭喜！您的 GitLab Issue 甘特圖同步工具已就緒！