---
date: "2025-11-25T18:58:22Z"
slug: "project-workflows"
sidebar_position: 1
description: "在仓库项目上使用事件、过滤器和动作组合来自动化重复操作。"
---

# 项目工作流

项目工作流可以在仓库项目看板上根据问题或拉取请求触发的事件自动执行操作。该功能无需外部 Runner 或 Webhook，完全在 Gitea 内部运行。

有权管理项目工作流的用户可以创建、编辑、克隆、启用或禁用工作流，详见[权限](#权限)。

## 打开工作流编辑器

1. 进入仓库并打开需要自动化的 **Projects** 看板。
2. 在看板顶部的菜单中选择 **Workflows**。
3. 点击左侧栏中的事件以编辑其工作流。
4. 选择事件、追加过滤器、按顺序添加需要的动作并保存。

每个工作流都存放在所属的项目下。如果另一个项目需要类似逻辑，请在目标项目中重新创建或克隆工作流。

## 基本概念

- **事件（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`）。权限规则与界面操作相同，参见[权限](#权限)。

## 示例：自动分流新的缺陷报告

以下工作流可以让缺陷报告自动进入待处理区：

1. **事件：** 加入项目（Added to project）。
2. **过滤器：** 仅适用于 `issues only`；标签包含 `bug`。
3. **动作：**
   - 添加标签 → `needs-triage`。
   - 移动到列 → “Needs Triage”。
   - 问题状态 → 保持打开（如有需要也可以强制重新打开以确保可见）。

配置完成后，每当新的缺陷问题加入该项目时都会立即拥有正确的标签并出现在指定列中，维护者可以第一时间看到需要分流的条目。

从简单规则开始，在单个项目中验证效果，再根据团队的重复性任务逐步扩展自动化逻辑。