6.7 KiB
date, slug, sidebar_position, description
| date | slug | sidebar_position | description |
|---|---|---|---|
| 2025-11-25T18:58:22Z | project-workflows | 1 | 以事件、篩選條件與動作組合，替儲存庫專案自動化重複工作。 |
專案工作流程
專案工作流程會在儲存庫專案看板上依據議題或拉取請求觸發的事件自動執行操作。此功能完全在 Gitea 內部運行，不需要外部 Runner 或 Webhook。
有權管理專案工作流程的使用者可以建立、編輯、複製、啟用或停用工作流程，詳見權限。
開啟工作流程編輯器
- 進入儲存庫並開啟想要自動化的 Projects 看板。
- 在看板頂端的選單中選擇 Workflows。
- 點擊左側欄中的事件以編輯其工作流程。
- 選擇事件、加入篩選條件、依序配置需要的動作後儲存。
每個工作流程只屬於當前專案。如需在另一個專案套用相同邏輯，請在該專案重新建立或複製工作流程。
基本概念
- 事件（Event）：定義何時評估工作流程，例如議題加入專案或卡片在欄位間移動。
- 篩選條件（Filter）：可選條件，需符合後才會執行動作，例如標籤或欄位變化。
- 動作（Action）：當事件與篩選條件成立時 Gitea 要執行的操作，例如新增標籤或移動卡片。
支援的事件
| 事件 | 觸發時機 |
|---|---|
| 關閉議題／拉取請求 | 該議題或拉取請求被關閉。 |
| 重新開啟議題／拉取請求 | 已關閉的項目被重新開啟。 |
| 加入專案 | 議題或拉取請求被加入此專案，包括在此專案中建立時。 |
| 從專案移除 | 項目被自專案中移除。 |
| 欄位變更 | 卡片從某欄移到另一欄。 |
| 被要求修改 | 與專案關聯的拉取請求收到修改要求。 |
| 稽核通過 | 稽核者批准該拉取請求。 |
| 拉取請求已合併 | 該拉取請求被合併。 |
每種事件都可以配置多個工作流程，讓相同觸發條件可以在不同情境下執行不同的自動化步驟。
篩選條件
篩選條件可進一步限制事件是否需要執行。若未設定任何條件，事件發生時工作流程一律會跑。
- 適用對象（Apply to）：限制僅處理
issues only、pull requests only或同時處理。 - 標籤（Labels）：只有卡片已包含所選標籤之一時才觸發。
- 來源欄位（Move from column）：只有卡片原先位於指定欄位時才觸發，常與「欄位變更」事件搭配。
- 目標欄位（Move to column）：只有卡片移入特定欄位時才觸發。
可以同時組合多個篩選條件，例如「帶有 needs-review 標籤的拉取請求移入 “Review” 欄位」。
動作
工作流程會先移動卡片，再變更標籤，最後變更議題狀態。可用的動作包含：
- 新增標籤（Add labels）：為議題或拉取請求加上多個標籤。
- 移除標籤（Remove labels）：刪除不再需要的標籤。
- 移動到欄位（Move to column）：把卡片移到同一專案看板中的其他欄位。
- 議題狀態（Issue state）：關閉或重新開啟相關議題。拉取請求只能被關閉。
透過組合多個動作，可以在單一工作流程裡同時完成移動卡片與更新標籤等步驟。
管理工作流程
啟用或停用
每個工作流程都有獨立開關。停用後即使事件被觸發也會被忽略，適合暫停自動化又不想刪除設定時使用。已關閉專案的工作流程也不會執行。
複製事件工作流程
按下 Clone 可以複製目前的工作流程（事件、篩選條件與動作都會被保留）。當你需要針對相同事件建立不同變體時，複製後調整即可快速建立新流程。
權限
權限在管理工作流程時檢查，而非在工作流程執行時檢查。
- 檢視專案的工作流程需要該專案的讀取權限。
- 建立、編輯、啟用、停用與刪除工作流程需要該專案的寫入權限，以及對該專案可容納之所有項目的權限：儲存庫專案需要對該儲存庫的議題與拉取請求都擁有寫入權限，組織專案需要是組織擁有者或網站管理員，使用者專案需要是該使用者本人。僅限公開儲存庫的權杖無法管理組織或使用者專案的工作流程。
- 工作流程會在開放專案中的項目發生對應事件時執行，前提是項目所在儲存庫未封存且屬於該專案的儲存庫或擁有者，與誰觸發了事件無關。
- 其動作直接套用，不再進行權限檢查，包括為拉取請求新增標籤與關閉拉取請求。工作流程不會重新開啟拉取請求。
- 工作流程所做的變更在時間軸中顯示為由「專案工作流程」完成，並歸屬於觸發該事件的使用者，與 CODEOWNERS 發起的審查請求相同。這些變更不會觸發其他工作流程。
- 只有能讀取項目的使用者才能將其加入專案或移動其卡片，因此工作流程不會替使用者操作其無法查看的項目。
API
也可以透過 REST API 管理工作流程，路徑位於儲存庫（/repos/{owner}/{repo}/projects/{id}）、組織（/orgs/{org}/projects/{id}）或目前使用者（/user/projects/{id}）的專案路由下：
| 方法 | 路徑 | 用途 |
|---|---|---|
GET |
.../workflows |
列出專案的工作流程 |
GET |
.../workflows/{workflow_id} |
取得工作流程 |
POST |
.../workflows |
建立工作流程 |
PATCH |
.../workflows/{workflow_id} |
編輯工作流程，未提供的欄位保持不變 |
DELETE |
.../workflows/{workflow_id} |
刪除工作流程 |
工作流程包含 event（item_added_to_project、item_removed_from_project、item_reopened、item_closed、item_column_changed、code_changes_requested、code_review_approved 或 pull_request_merged）、enabled 開關、filters（issue_type、source_column_id、target_column_id、label_ids）以及 actions（column_id、add_label_ids、remove_label_ids、issue_state）。權限規則與介面操作相同，詳見權限。
範例：自動分流新的錯誤回報
以下設定能讓錯誤議題自動落在待處理區：
- 事件： 加入專案（Added to project）。
- 篩選條件： 僅適用
issues only；標籤包含bug。 - 動作：
- 新增標籤 →
needs-triage。 - 移動到欄位 → “Needs Triage”。
- 議題狀態 → 保持開啟（如有需要也能強制重新開啟以確保可見）。
- 新增標籤 →
設定完成後，每當有新的錯誤議題加入此專案，就會立即獲得正確標籤並顯示在指定欄位，維護者能第一時間掌握待分流的項目。
從簡單規則著手，在單一專案驗證成效，再依團隊的重複性工作逐步擴大自動化邏輯。