Add project workflow documentation (#308)

Documentation for https://github.com/go-gitea/gitea/pull/30205

---------

Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/308
Reviewed-by: silverwind <[email protected]>

docs/usage/projects/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Projects",
+  "position": 60,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/projects",
+    "description": "Plan and track work with project boards"
+  }
+}

docs/usage/projects/project-workflows.md

@@ -0,0 +1,82 @@
+---
+date: "2025-11-25T18:58:22Z"
+slug: "project-workflows"
+sidebar_position: 1
+description: "Automate project boards with event-driven filters and actions."
+---
+
+# Project Workflows
+
+Project workflows automate a project board. When an issue or pull request in the project triggers an event, each enabled workflow for that event checks its filters and applies its actions. Workflows run in Gitea and need no runner.
+
+## Edit workflows
+
+1. Open a project and select **Workflows**.
+2. Select an event in the sidebar.
+3. Set filters and actions, then select **Save**. To change an existing workflow, select **Edit** first.
+
+An event can have several workflows. **Clone** copies the selected workflow so you can adapt it to other items. **Disable** pauses a workflow and keeps its configuration. **Remove** deletes it.
+
+## Events
+
+| Event | Runs when | Filters | Actions |
+| --- | --- | --- | --- |
+| Item added to project | An item is added to the project or created in it | Apply to, labels | Move to column, labels, issue state |
+| Item removed from project | An item is removed from the project | Apply to, labels | Labels, issue state |
+| Item reopened | An item is reopened | Apply to, labels | Move to column, labels |
+| Item closed | An item is closed | Apply to, labels | Move to column, labels |
+| Item column changed | An item moves to another column | Apply to, columns, labels | Labels, issue state |
+| Code changes requested | An official reviewer requests changes on a pull request | Labels | Move to column, labels |
+| Code review approved | An official reviewer approves a pull request | Labels | Move to column, labels |
+| Pull request merged | A pull request is merged | Labels | Move to column, labels |
+
+## Filters
+
+A workflow without filters runs for every item.
+
+- **Apply to**: issues, pull requests, or both.
+- **When moved from column**, **When moved to column**: the column the item left or entered.
+- **Only if it has labels**: the item must have all selected labels.
+
+## Actions
+
+A workflow needs at least one action. Actions run in this order:
+
+1. **Move to column**: moves the item to a column.
+2. **Add labels**, **Remove labels**: changes the item's labels.
+3. **Issue state**: closes or reopens the item. Workflows never reopen pull requests.
+
+Workflow changes appear in the timeline as "Project workflow" followed by the event, and don't trigger other workflows. Workflows don't run in closed projects or for items in archived repositories.
+
+## Permissions
+
+Anyone who can read a project can view its workflows. Managing them requires write access to the project and:
+
+- Repository project: write access to the repository's issues and pull requests.
+- Organization project: organization owner or site administrator.
+- User project: the project's owner.
+
+Access tokens limited to public repositories can't manage workflows for organization or user projects. Workflows apply their actions regardless of who triggered the event.
+
+## API
+
+Manage workflows under the project routes of a repository (`/repos/{owner}/{repo}/projects/{id}`), an organization (`/orgs/{org}/projects/{id}`) or the authenticated user (`/user/projects/{id}`):
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `.../workflows` | List workflows |
+| `GET` | `.../workflows/{workflow_id}` | Get a workflow |
+| `POST` | `.../workflows` | Create a workflow |
+| `PATCH` | `.../workflows/{workflow_id}` | Edit a workflow, omitted fields stay unchanged |
+| `DELETE` | `.../workflows/{workflow_id}` | Delete a workflow |
+
+A workflow has an `event` (`item_added_to_project`, `item_removed_from_project`, `item_reopened`, `item_closed`, `item_column_changed`, `code_changes_requested`, `code_review_approved` or `pull_request_merged`), an `enabled` flag, `filters` (`issue_type`, `source_column_id`, `target_column_id`, `label_ids`) and `actions` (`column_id`, `add_label_ids`, `remove_label_ids`, `issue_state`). Each event accepts only the filters and actions listed in [Events](#events).
+
+## Example
+
+To route new bug reports to triage, create a workflow for **Item added to project**:
+
+- **Apply to**: Issues only
+- **Only if it has labels**: `bug`
+- **Move to column**: Triage
+- **Add labels**: `needs-triage`

i18n/zh-cn/docs/current/usage/projects/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "项目",
+  "position": 60,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/projects",
+    "description": "使用项目看板规划和跟踪工作"
+  }
+}

i18n/zh-cn/docs/current/usage/projects/project-workflows.md

@@ -0,0 +1,82 @@
+---
+date: "2025-11-25T18:58:22Z"
+slug: "project-workflows"
+sidebar_position: 1
+description: "通过事件驱动的过滤器和动作自动化项目看板。"
+---
+
+# 项目工作流
+
+项目工作流可自动化项目看板。当项目中的问题或合并请求触发事件时，该事件下每个已启用的工作流都会检查其过滤条件并执行相应动作。工作流在 Gitea 中运行，无需运行器。
+
+## 编辑工作流
+
+1. 打开项目并选择 **Workflows**。
+2. 在侧边栏中选择事件。
+3. 设置过滤器和动作，然后选择 **Save**。要修改现有工作流，请先选择 **Edit**。
+
+一个事件可以有多个工作流。**Clone** 会复制选中的工作流，便于调整后用于其他条目。**Disable** 会暂停工作流并保留其配置。**Remove** 会删除工作流。
+
+## 事件
+
+| 事件 | 触发时机 | 过滤器 | 动作 |
+| --- | --- | --- | --- |
+| Item added to project | 条目被添加到项目或在项目中创建时 | Apply to、标签 | Move to column、标签、问题状态 |
+| Item removed from project | 条目被移出项目时 | Apply to、标签 | 标签、问题状态 |
+| Item reopened | 条目被重新打开时 | Apply to、标签 | Move to column、标签 |
+| Item closed | 条目被关闭时 | Apply to、标签 | Move to column、标签 |
+| Item column changed | 条目移至另一列时 | Apply to、列、标签 | 标签、问题状态 |
+| Code changes requested | 正式审查者要求修改合并请求时 | 标签 | Move to column、标签 |
+| Code review approved | 正式审查者批准合并请求时 | 标签 | Move to column、标签 |
+| Pull request merged | 合并请求被合并时 | 标签 | Move to column、标签 |
+
+## 过滤器
+
+未设置过滤器的工作流会对每个条目运行。
+
+- **Apply to**：问题、合并请求或两者。
+- **When moved from column**、**When moved to column**：条目离开或进入的列。
+- **Only if it has labels**：条目必须包含所有选中的标签。
+
+## 动作
+
+工作流至少需要一个动作。动作按以下顺序执行：
+
+1. **Move to column**：将条目移至某一列。
+2. **Add labels**、**Remove labels**：更改条目的标签。
+3. **Issue state**：关闭或重新打开条目。工作流不会重新打开合并请求。
+
+工作流所做的更改在时间线中显示为“Project workflow”及其后的事件名称，且不会触发其他工作流。工作流不会在已关闭的项目中运行，也不会处理已归档仓库中的条目。
+
+## 权限
+
+任何拥有项目读取权限的人都可以查看其工作流。管理工作流需要项目的写入权限，并满足以下条件：
+
+- 仓库项目：拥有该仓库的问题和合并请求的写入权限。
+- 组织项目：是组织所有者或站点管理员。
+- 用户项目：是项目所有者。
+
+仅限公开仓库的访问令牌无法管理组织或用户项目的工作流。无论谁触发事件，工作流都会执行其动作。
+
+## 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`）。每个事件仅接受[事件](#事件)表中列出的过滤器和动作。
+
+## 示例
+
+要将新的缺陷报告分流至待分类列，请为 **Item added to project** 创建工作流：
+
+- **Apply to**：Issues only
+- **Only if it has labels**：`bug`
+- **Move to column**：Triage
+- **Add labels**：`needs-triage`

i18n/zh-tw/docs/current/usage/projects/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "專案",
+  "position": 60,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/projects",
+    "description": "使用專案看板規劃與追蹤工作"
+  }
+}

i18n/zh-tw/docs/current/usage/projects/project-workflows.md

@@ -0,0 +1,82 @@
+---
+date: "2025-11-25T18:58:22Z"
+slug: "project-workflows"
+sidebar_position: 1
+description: "透過事件驅動的篩選條件與動作，讓專案看板自動化。"
+---
+
+# 專案工作流程
+
+專案工作流程可讓專案看板自動化。當專案中的問題或合併請求觸發事件時，該事件的每個已啟用工作流程都會檢查篩選條件並執行動作。工作流程在 Gitea 中執行，不需要 runner。
+
+## 編輯工作流程
+
+1. 開啟專案並選取 **Workflows**。
+2. 在側邊欄選取事件。
+3. 設定篩選條件與動作，然後選取 **Save**。若要變更現有工作流程，請先選取 **Edit**。
+
+一個事件可以有多個工作流程。**Clone** 會複製選取的工作流程，方便您調整後用於其他項目。**Disable** 會暫停工作流程並保留設定。**Remove** 會刪除工作流程。
+
+## 事件
+
+| 事件 | 執行時機 | 篩選條件 | 動作 |
+| --- | --- | --- | --- |
+| Item added to project | 項目加入專案或在專案中建立時 | Apply to、標籤 | Move to column、標籤、問題狀態 |
+| Item removed from project | 項目從專案移除時 | Apply to、標籤 | 標籤、問題狀態 |
+| Item reopened | 項目重新開啟時 | Apply to、標籤 | Move to column、標籤 |
+| Item closed | 項目關閉時 | Apply to、標籤 | Move to column、標籤 |
+| Item column changed | 項目移至另一欄時 | Apply to、欄、標籤 | 標籤、問題狀態 |
+| Code changes requested | 正式審查者要求修改合併請求時 | 標籤 | Move to column、標籤 |
+| Code review approved | 正式審查者核准合併請求時 | 標籤 | Move to column、標籤 |
+| Pull request merged | 合併請求合併時 | 標籤 | Move to column、標籤 |
+
+## 篩選條件
+
+未設定篩選條件的工作流程會對所有項目執行。
+
+- **Apply to**：問題、合併請求或兩者。
+- **When moved from column**、**When moved to column**：項目離開或進入的欄。
+- **Only if it has labels**：項目必須具有所有選取的標籤。
+
+## 動作
+
+工作流程至少需要一個動作。動作依下列順序執行：
+
+1. **Move to column**：將項目移至某一欄。
+2. **Add labels**、**Remove labels**：變更項目的標籤。
+3. **Issue state**：關閉或重新開啟項目。工作流程不會重新開啟合併請求。
+
+工作流程所做的變更會在時間軸中顯示為「Project workflow」加上事件名稱，且不會觸發其他工作流程。專案已關閉或項目位於已封存的儲存庫時，工作流程不會執行。
+
+## 權限
+
+任何具有專案讀取權限的使用者都能檢視其工作流程。管理工作流程需要專案的寫入權限，以及：
+
+- 儲存庫專案：該儲存庫的問題與合併請求的寫入權限。
+- 組織專案：組織擁有者或網站管理員身分。
+- 使用者專案：專案擁有者身分。
+
+僅限公開儲存庫的存取權杖無法管理組織或使用者專案的工作流程。無論誰觸發事件，工作流程都會執行其動作。
+
+## 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`）。每個事件僅接受[事件](#事件)中列出的篩選條件與動作。
+
+## 範例
+
+若要將新的錯誤回報送往分類處理，請為 **Item added to project** 建立工作流程：
+
+- **Apply to**：Issues only
+- **Only if it has labels**：`bug`
+- **Move to column**：Triage
+- **Add labels**：`needs-triage`