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]>
2026-11-09 11:30:30 +00:00 · 2026-10-28 16:12:53 +00:00
1 parent d301461648
commit ee9e91cdeb
@@ -0,0 +1,9 @@
+{
+  "label": "项目",
+  "position": 60,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/projects",
+    "description": "使用项目看板规划和跟踪工作"
+  }
+}
@@ -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`