GitLab Issue 管理參考文件

適用情境：50 人團隊、7 個概念性 project（部分共用人員）、自架 GitLab（無 Epic 功能）、需解決任務分配追蹤、進度可視化、跨 project 優先級管理。

一、整體架構設計

GitLab 層級選擇

由於 repo 未必與特定 project 有關聯，建議建立一個「管理專用 project」的模式：

Group (整個組織)
├── Subgroup A (例如：基礎設施相關)
│   ├── repo-a (程式碼)
│   └── repo-b (程式碼)
├── Subgroup B (例如：產品相關)
│   └── repo-c
└── management (管理用 project — 放所有跨 repo 的 issue)
    ├── Project-1 tracker issues
    ├── Project-2 tracker issues
    └── ...

關鍵原則：Issues 只存在於 project，不存在於 group。Group 有 boards 可以聚合多個 project 的 issue，但 issue 本身必須屬於某個 project。

兩種可行方案

方案 A：單一管理 Project（推薦）

建立一個 team-management project，所有 7 個概念性 project 的任務都在這裡開 issue。

優點：集中管理、跨 project label 天然統一、board 最容易設定
適合：team 比較扁平、project 之間界線模糊、人員高度共用

方案 B：每個概念 Project 一個 GitLab Project

每個概念性 project 開一個 GitLab project（不放程式碼，只放 issues）。

優點：各 project 有獨立的 board 和 milestone
適合：7 個 project 相對獨立、各有 PM 或負責人
代價：跨 project 可視化需要依賴 group-level board，設定稍複雜

二、Label 設計

Labels 是整個系統的核心。建議使用 Scoped Labels（Namespace::Value 格式），同一個 issue 在同一 namespace 只能有一個值，避免狀態混亂。

2.1 Stage Labels（工作流程狀態）

每個 issue 的生命週期，任一時刻只有一個狀態：

Label	說明
`Stage::Triage`	新進 issue，待評估是否接受
`Stage::Planning`	確認接受，正在規劃執行方案
`Stage::Scheduled`	已排入某個 milestone / sprint
`Stage::In-Progress`	正在進行中
`Stage::Blocked`	有阻礙，無法繼續
`Stage::Review`	等待驗收或 review
`Stage::Done`	完成（關閉前打上，便於統計）
`Stage::Backlog`	暫緩，未來再考慮

2.2 Priority Labels（優先級）

跨 project 優先級管理的核心。建在 group level，讓所有 project 都能使用：

Label	說明
`Priority::1`	緊急，本 milestone 必須完成
`Priority::2`	高，本 milestone 目標完成
`Priority::3`	中，下個 milestone 排入
`Priority::4`	低，Backlog 候選

2.3 Project Labels（識別屬於哪個概念 project）

建在 group level，讓 board 可以跨 project filter：

Project::Alpha
Project::Beta
Project::Gamma
... (7 個 project 各一個)

若某個 issue 涉及多個 project，可同時貼多個 Project label（非 scoped，允許多選）。

2.4 Type Labels（任務類型）

Label	說明
`Type::Feature`	新功能
`Type::Bug`	錯誤修復
`Type::Task`	一般任務、行政
`Type::Research`	研究或評估
`Type::Incident`	緊急事件

2.5 Team Labels（負責部門 / 功能）

若 50 人中有明確的小組（例如：前端、後端、設計），可加：

Team::Frontend
Team::Backend
Team::Design
Team::Ops

Issue 必備 Labels 規則

每個 issue 都應有：

一個 Stage:: label
一個 Priority:: label
一個 Project:: label
一個 Type:: label

使用 Issue Templates 自動帶入 Quick Actions 確保一致性（見第四節）。

三、Issue Board 設計

3.1 主工作流程 Board（每個 project 或 group level）

依 Stage:: scoped label 排列欄位，視覺化所有 issue 的狀態：

[Open] | Triage | Planning | Scheduled | In-Progress | Blocked | Review | [Closed]

設定方式：

在 group level 建立，可聚合所有 project 的 issue
Board scope 設 Milestone: 當前 milestone（只看本期工作）
可額外 filter by Project:: label 來看單一 project

3.2 跨 Project 優先級 Board

依 Priority:: label 建立欄位，讓管理者看全隊最高優先任務：

[Open] | Priority::1 | Priority::2 | Priority::3 | Priority::4 | [Closed]

可在 group level 建立，不 filter milestone，看所有 open issues 的優先分佈。

3.3 人員分配 Board

依 assignee 分組，讓 PM 看每個人手上的任務量：

Board 設定：依 Team Members 建立 list
移動 issue 到某人的欄位，自動 assign 給他
可 filter by Stage::In-Progress 只看進行中的任務

3.4 Per-Project Board

若採用方案 B（每個概念 project 一個 GitLab project），在 group level 設 board 並 filter Project::Alpha 即可看單一 project 的全貌。

Board 的限制要知道

移動 issue 到不同 list，只能改一件事（加/移除 label 或更換 assignee）
上下拖拉排序不留歷史紀錄，不要依賴拖拉表示優先級，應改用 Priority:: label
Board 永遠是 live 狀態，沒有 read-only 模式

四、Issue 最佳實踐

4.1 Issue Templates

每種常用的任務類型建立一個 template，範例（Feature Request template）：

## 背景說明
 
（描述這個需求的脈絡）
 
## 目標
 
（完成後的預期結果）
 
## 驗收條件
 
- [ ] 條件一
- [ ] 條件二
 
/label ~"Stage::Triage" ~"Type::Feature"
/milestone %"2026-05"

Template URL 格式：

https://your-gitlab.com/group/project/-/issues/new?issuable_template=FeatureRequest

4.2 每個 Issue 一個 DRI

DRI（Directly Responsible Individual）= 直接負責人，每個 issue 只 assign 給一個人。若需要多人參與：

拆成多個子 issue，分別 assign
用 Related issues 或 Blocked by 建立依賴關係

4.3 Issue Description 保持最新

討論串可以很長，但 Description 要定期更新為最新狀態，加上 ## 最新進度（YYYY-MM-DD） header，讓新加入者不需要讀完所有留言。

4.4 Issue Weight（工作量估計）

Weight	時間
0	少於 4 小時
1	4 小時 / 半天
2	8 小時 / 1 天
3	12 小時 / 1.5 天
4	16 小時 / 2 天

超過 4 天的任務應拆分。使用 /weight 2 Quick Action 設定。

4.5 每週狀態更新格式

對於 Priority::1 或 Priority::2 的 issue，DRI 每週在 issue 留言更新：

**上週進度：**
- [進度點]
 
**下週計畫：**
- [計畫點]
 
**阻礙：**
- 無 / [具體阻礙]
 
**整體狀態：** 🟢 正常 / 🟡 需關注 / 🔴 有風險

五、Milestone 策略（無 Epic 的替代方案）

由於沒有 Epic，Milestone 要同時承擔「時間軸」和「功能群組」兩個角色。

5.1 Milestone 類型

Sprint Milestone（建議主要使用）

週期：2 週或 1 個月
命名：YYYY-MM-DD（結束日期）或 2026-05 Sprint
建在 group level，讓所有 7 個 project 的 issue 都能掛同一個 milestone
配合 Burndown Chart 追蹤完成率

Project Milestone（可選）

特定概念 project 的大節點，例如 Alpha: Phase 1 Launch
建在 group level，搭配 Project::Alpha label filter 使用
取代 Epic 的功能：把某個 project 的一批 issue 群組在一起

Backlog Milestone

名稱：Backlog（固定，不設日期）
所有還沒排期的 issue 掛這裡，方便 sprint planning 時挑選

5.2 Milestone 命名規範

格式：[prefix]_[名稱或日期]

Sprint：sprint_2026-05-01
Project milestone：alpha_phase1、beta_launch
Backlog：backlog（全組織共用一個）

加 prefix 是為了在 milestone 列表中可以用名稱搜尋過濾，因為 milestone 列表沒有 label filter。

5.3 Sprint Planning 流程（仿 AppSec team 做法）

每個 sprint 開始前 3 個工作日：

從 backlog milestone 挑選 issue 移入新 sprint
確認每個 issue 有 DRI、Priority:: label、Stage::Scheduled
評估 weight 總量是否合理（避免過載）
sprint 開始時，DRI 將 Stage::Scheduled 改為 Stage::In-Progress

Sprint 結束時：

未完成的 issue：貼 missed label，移至下個 milestone
已完成：確認 Stage::Done，關閉 issue

六、跨 Project 管理策略

6.1 跨 project 可視化

在 group level 建立一個 全隊 Dashboard Board：

Board 不 filter milestone（看所有 open issues）
依 Priority:: 分欄
可快速看到哪些跨 project 的高優先任務積壓

定期（每週）用 group issue list，filter：

Stage::In-Progress
Priority::1 or Priority::2
依 Project:: group 審查各 project 進度

6.2 共用人員管理

人員在多個 project 同時有任務時，用 assignee board 快速評估負載：

Filter Stage::In-Progress + 某人
看他手上同時有幾個 active issue
若某人 Priority::1 issue 超過 3 個，需要重新分配

6.3 Label 在 Group Level vs Project Level

Label 類型	建立位置	原因
`Priority::`	Group	跨 project 統一優先級
`Project::`	Group	讓 group board 可 filter
`Stage::`	Group	統一工作流程
`Team::`	Group	人員歸屬跨 project
`Type::`	Group	統一任務類型

原則：從 group level 開始建 label，若有某 project 特有的需求再建 project level label。

七、導入步驟建議

第一週：建立 group level labels（Stage、Priority、Project、Type）
第二週：建立 3 個 board（工作流程、優先級、人員分配）
第三週：建立 issue templates（至少 Feature、Bug、Task 三種）
第四週：建立第一個 sprint milestone，開始跑第一個 sprint
持續：每週 DRI 更新 issue 狀態，每 sprint 做 planning + retro

八、快速參考：Quick Actions

/label ~"Stage::In-Progress"       # 設定 stage
/label ~"Priority::1"              # 設定優先級
/label ~"Project::Alpha"           # 標記所屬 project
/assign @username                  # 指派 DRI
/milestone %"sprint_2026-05-01"    # 加入 milestone
/weight 2                          # 設定工作量
/due 2026-05-15                    # 設定截止日
/relate #123                       # 關聯另一個 issue
/blocks #456                       # 標記此 issue block 另一個

九、Epic Issue 命名與 Scoped Label 設計

Epic Issue 命名

當一個 issue 的用途是聚合多個子 issue（例如「登入功能」需要前端、後端、設計、部署各一張 issue），這個容器 issue 在 Scrum 層級是 Epic，而非 Story。

Scrum 層級：Epic > Story > Task

推薦命名方案（依慣例常見度排序）：

[Epic] 登入功能模組 + label type::epic（最推薦，與 GitLab Premium Epic 概念對齊，日後升級遷移成本低）
Tracking: 登入功能模組（開源社群最常見，語意為「追蹤整個功能進度」）
[Umbrella] 登入功能模組（表示「把其他 issue 收在傘下」）

Scoped Label 設計原則

GitLab Scoped Label（namespace::value）的核心規則：同一個 namespace 下的 label 互斥，一個 issue 只能套用其中一個。設計時要確認「這個 namespace 的選項是否互相排斥」。

建議的 namespace 結構：

type::epic / type::story / type::task / type::bug
→ issue 的層級類型，每個 issue 只會是其中一種

domain::frontend / domain::backend / domain::design / domain::deploy
→ 負責領域（若 issue 只屬於單一 domain 則適合用 scoped）

status::open / status::in-progress / status::blocked / status::done
→ 工作流程狀態

priority::high / priority::medium / priority::low
→ 優先級

實際套用範例：

Epic issue：type::epic
後端登入 API：type::task + domain::backend
前端登入表單：type::task + domain::frontend

注意：若一個 issue 可能橫跨多個 domain，改用普通 label（不含 ::）讓它可以複選。

bot_vault

Explorer

GitLab Issue 管理參考文件 — 50 人團隊 × 7 個 Project