本工具專為雲端運維團隊設計，能夠自動從 GitLab 專案中擷取 Issue 資訊，同步至 Google Sheet 並以甘特圖形式呈現，同時生成詳細的雙月工作分析報表。主要用於追蹤團隊成員在不同工作類型（VCS、VKS、VDS 等）的時間分配，協助管理層進行資源規劃與績效評估。
- 📊 自動化甘特圖生成：將 GitLab Issue 轉換為視覺化時間軸
- 📈 樞紐分析表報表：生成詳細的工作類型分析與趨勢比較
- 🔄 智能同步機制：避免重複處理，僅同步新增 Issue
- 👥 多人協作支援：單一 Issue 可由多人共同處理
- 🎯 靈活專案配置：支援標籤篩選或全開放 Issue 擷取
- 📅 時間範圍控制：可設定起始日期進行過濾
GitLab API ──► 數據處理器 ──► Google Sheet ──► 甘特圖 ──► 樞紐分析表報表
↓ ↓ ↓ ↓ ↓
Issue 擷取 標籤篩選 時間軸生成 進度追蹤 工作分析
| 模組 | 功能說明 |
|---|---|
main.py |
主程序入口，整合各模組功能 |
argument_parser.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
google-auth-httplib2==0.1.0
google-auth-oauthlib==1.0.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中的權杖資訊
# Google Sheet 配置
google_sheet:
credentials_path: "/path/to/credentials.json"
spreadsheet_id: "your_spreadsheet_id"
# 報表設定
report_settings:
workday_highlight_method: "outlier" # 高亮方法：outlier (離群值) 或 top_n (前 N 個最大值)
workday_highlight_outlier_multiplier: 1.5 # 離群值倍數（使用 Q3 + multiplier * IQR），預設 1.5
# 工作表欄位定義
worksheet_columns:
gitlab_link: 0 # A 欄 - GitLab 連結
issue_title: 1 # B 欄 - Issue 標題
owner: 2 # C 欄 - 負責人
type: 3 # D 欄 - 工作類型
subtype: 4 # E 欄 - 第二階工作類型
closed: 5 # F 欄 - 是否關閉
note: 6 # G 欄 - 備註
timeline_start: 7 # H 欄 - 時間軸開始位置
# GitLab 配置
gitlab:
base_url: "https://your-gitlab.com"
token: "your_api_token"
# 專案設定（支援混合模式）
project_id_list:
- 123 # 只抓取根據全域標籤篩選的 issue
# 以下段落是設定所有 issue 都抓取
- project_id: 456
name: "專案名稱"
fetch_all_open_issues: true # 擷取所有開放 issue
# 全域標籤列表
label_list:
- "A::B"
- "C::D"
- "E::F"
# 使用者與角色管理
user_list:
- "user1"
- "user2"
- "manager1"
user_roles:
managers: # 主管角色（排除在個人報表外）
- "manager1"
# 工作分類定義
# 若有新增項目，只有觸發 `新建工作表` 的行為才會套用新的項目，
# 舊有的需要在 Google Sheet 的 資料 > 資料驗證 進行修改
type_list:
- "A"
- "B"
- "C"
- "其他"
subtype_list:
- "客服進單"
- "日常維運"
- "硬體報修"
- "專案支援"
# 日誌配置
log_config:
level: "INFO"
tag: "gitlab-gantt-sync"
console_output: false# 僅更新甘特圖（不生成報表）
python3 main.py
# 僅生成樞紐分析表報表（跳過 GitLab Issue 同步）
python3 main.py -r
python3 main.py --report
# 指定年份生成報表
python3 main.py -r -y 2025
python3 main.py --report --year 2025
# 指定年份更新甘特圖
python3 main.py -y 2024
# 生成年度工作樞紐分析表
python3 main.py -a
python3 main.py --annual-work
# 指定年份生成年度工作樞紐分析表
python3 main.py -a -y 2025| 參數 | 說明 |
|---|---|
-r, --report |
生成雙月報表。若指定此參數，則僅生成報表，跳過 GitLab Issue 同步。 |
-y, --year |
指定報表年度。若不指定則使用當年。 |
-a, --annual-work |
生成年度工作樞紐分析表。從報表工作表的 K-N 欄讀取數據，生成按 SubType/Type 分類的樞紐分析表。 |
# 每日凌晨更新甘特圖
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)：選擇工作類型（VCS、VKS、VDS等）
- 📝 E 欄 (SubType)：選擇子類型（客服進單、日常維運等）
- 📝 F 欄 (Closed)：勾選是否已關閉
- 📝 G 欄 (Note)：填寫備註
- 📝 時間軸區域：填入處理 Issue 的人員名稱（支援多人，以逗號分隔）
- 📊 系統自動根據甘特圖數據生成雙月樞紐分析表
- 📈 顯示各人員在不同工作類型的時間分配
- 📉 計算各類型工作的佔比及與前期的變化趨勢
- 👤 為每個一般使用者（非主管）生成獨立報表頁籤
| 欄位 | 說明 |
|---|---|
| Type | 工作類型（VCS、VKS等） |
| SubType | 第二階分類（客服進單、日常維運等） |
| Issue | 具體 Issue 標題 |
| Workday | 工作天數 |
| Workday 佔比 | 該 Issue 在總工作天數中的比例 |
| Workday @ SubType 佔比 | SubType 在總工作天數中的比例 |
| SubType 與前次雙月差異 | 與前一個雙月期間的變化 |
| Workday @ Type 佔比 | Type 在總工作天數中的比例 |
| Type 與前次雙月差異 | 與前一個雙月期間的變化 |
- 🎯 Issue 級別統計：精確到每個 Issue 的工作天數
- 📊 多層次分析：Type → SubType → Issue 的階層結構
- 📈 趨勢比較：與前一個雙月期間的百分比變化
- 👥 個人化報表：每位成員獨立的工作統計頁籤
- 🔢 自動計算：合併儲存格與百分比格式自動處理
報表中會自動將花費時間較多的 Issue 以黃色背景標示（Workday 和 Workday 佔比欄位）。
系統使用四分位距（Interquartile Range, IQR）方法檢測離群值：
-
計算四分位數：
- Q1（第 25 百分位數）
- Q3（第 75 百分位數）
- IQR = Q3 - Q1
-
計算閾值：
threshold = Q3 + multiplier × IQR- 預設
multiplier = 1.5（可在config.yaml中調整）
- 預設
-
標示條件：
- 當
Workday > threshold時，該列的 Workday 和 Workday 佔比欄位會以黃色背景標示 - 若數據量少於 4 筆，則僅標示最大值
- 當
-
適用範圍：
- 雙月報表：各期間獨立計算閾值
- 年度總覽：使用全年數據計算閾值
google_sheet:
report_settings:
workday_highlight_method: "outlier" # 高亮方法
workday_highlight_outlier_multiplier: 1.5 # IQR 倍數# 檢查憑證檔案路徑和權限
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 # 或使用標籤篩選