mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-16 14:53:46 +00:00
Compare commits
7
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ad383f9f84 | ||
|
|
f9fa3e3258 | ||
|
|
602612a046 | ||
|
|
c902fe9253 | ||
|
|
3b71a35b51 | ||
|
|
7e9e42775c | ||
|
|
85ac8fc4ba |
No files matched your search
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "Projects",
|
||||
"position": 60,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/usage/projects",
|
||||
"description": "Plan, track, and automate repository projects"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
date: "2025-11-25T18:58:22Z"
|
||||
slug: "project-workflows"
|
||||
sidebar_position: 1
|
||||
description: "Automate tasks on repository projects by reacting to events with filters and actions."
|
||||
---
|
||||
|
||||
# Project Workflows
|
||||
|
||||
Project workflows let you automate what happens on a repository project board whenever an issue or pull request triggers a supported event. The feature runs entirely inside Gitea, so no external runners or webhooks are required.
|
||||
|
||||
Users who can manage a project's workflows can create, edit, clone, enable, or disable them, see [Permissions](#permissions).
|
||||
|
||||
## Open the workflow editor
|
||||
|
||||
1. Navigate to the repository → **Projects** and open the board you want to automate.
|
||||
2. Select **Workflows** in the menu at the top of the board.
|
||||
3. Click an event in the left sidebar to edit its workflow.
|
||||
4. Choose the event, add any filters, chain the actions you need, and save.
|
||||
|
||||
Every workflow lives inside the project it belongs to. If you need similar logic for another project, recreate or clone the workflow in that project.
|
||||
|
||||
## Concepts
|
||||
|
||||
Every workflow is composed of `event`, `filters`, and `actions`.
|
||||
|
||||
- **Event** - An Event defines when a workflow should be triggered. It represents specific activities such as an issue being added to the project, a pull request being merged, or a project column being changed.
|
||||
- **Filter** - A Filter refines when an event should take effect. It allows users to specify conditions like issue type, labels, or project columns to ensure actions only run in targeted scenarios.
|
||||
- **Action** - An Action defines what happens when the event and filters match. It performs operations such as adding labels, moving issues between columns, or changing the issue or pull request state.
|
||||
|
||||
## Supported events
|
||||
|
||||
| Event | Fires when |
|
||||
| --- | --- |
|
||||
| Issues/PRs closed | The issue or pull request is closed. |
|
||||
| Issues/PRs reopened | A previously closed issue or pull request is reopened. |
|
||||
| Added to project | An issue or pull request is added to the project, including when it is created in the project. |
|
||||
| Removed from project | An issue or pull request is removed from the project. |
|
||||
| Column changed | A card moves from one column to another. |
|
||||
| Code changes requested | A reviewer requests changes on a pull request connected to the project. |
|
||||
| Code review approved | A reviewer approves the pull request. |
|
||||
| Pull request merged | The pull request is merged. |
|
||||
|
||||
Each event can have multiple workflows so you can handle the same trigger differently for separate sets of cards.
|
||||
|
||||
## Filters
|
||||
|
||||
Filters refine when an event should run. If none are configured, the workflow runs on every occurrence of the event.
|
||||
|
||||
- **Apply to** - Specify the target type: `issues only`, `pull requests only`, or `issues and pull requests`.
|
||||
- **Labels** - Trigger the event only if the issue or pull request contains one or more specified labels.
|
||||
- **Move from column** - Filter events based on the original project column.
|
||||
- **Move to column** - Filter events based on the destination project column.
|
||||
|
||||
You can combine filters to require multiple conditions (for example, PRs with the `needs-review` label moving into the "Review" column).
|
||||
|
||||
## Actions
|
||||
|
||||
A workflow moves the card first, then changes labels, then changes the issue state. Available actions are:
|
||||
|
||||
- **Add labels** - Automatically add one or more labels to the issue or pull request.
|
||||
- **Remove labels** - Remove one or more specified labels.
|
||||
- **Move to column** - Move the issue or pull request to a designated project column.
|
||||
- **Issue state** - Close or reopen the issue. Pull requests can only be closed.
|
||||
|
||||
Combine actions to build more complex automations (for example, move the card and apply labels in a single workflow).
|
||||
|
||||
## Managing workflows
|
||||
|
||||
### Enable or disable
|
||||
|
||||
Each workflow has its own toggle. Disable a workflow to pause it temporarily without losing its configuration. Disabled workflows are ignored even if the event fires. Workflows of closed projects don't run either.
|
||||
|
||||
### Clone an event workflow
|
||||
|
||||
Use **Clone** to duplicate the current workflow (event, filters, and actions). This is useful when you need several variations of the same trigger—adjust the copied filters/actions and save under a new name.
|
||||
|
||||
## Permissions
|
||||
|
||||
Permissions are checked when workflows are managed, not when they run.
|
||||
|
||||
- **Viewing** a project's workflows needs read access to the project.
|
||||
- **Creating, editing, enabling, disabling and deleting** them needs write access to the project plus authority over every item it can hold: write access to both issues and pull requests of the repository for a repository project, being an organization owner or a site administrator for an organization project, and being the user for a user project. Tokens limited to public repositories can't manage workflows of organization or user projects.
|
||||
- **A workflow runs** when its event happens to an item in an open project, if the item's repository isn't archived and belongs to the project's repository or owner, no matter who caused the event.
|
||||
- **Its actions apply without further permission checks**, including adding labels to and closing pull requests. Pull requests are never reopened by workflows.
|
||||
- Changes made by a workflow show in the timeline as done by "Project workflow" and are attributed to the user who triggered the event, like review requests made by CODEOWNERS. They don't trigger other workflows.
|
||||
- Only users who can read an item can add it to a project or move its card, so a workflow never acts for someone on an item they can't see.
|
||||
|
||||
## API
|
||||
|
||||
Workflows can also be managed through the REST API 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 the project's workflows |
|
||||
| `GET` | `.../workflows/{workflow_id}` | Get a workflow |
|
||||
| `POST` | `.../workflows` | Create a workflow |
|
||||
| `PATCH` | `.../workflows/{workflow_id}` | Edit a workflow, omitted fields are left 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`). The same [permissions](#permissions) apply as in the UI.
|
||||
|
||||
## Example: triage incoming bug reports
|
||||
|
||||
The following workflow keeps bug reports organized automatically:
|
||||
|
||||
1. **Event:** Added to project.
|
||||
2. **Filters:** Apply to `issues only`; Labels include `bug`.
|
||||
3. **Actions:**
|
||||
- Add labels → `needs-triage`.
|
||||
- Move to column → "Needs Triage".
|
||||
- Issue state → leave open (no change) but could optionally reopen to ensure visibility.
|
||||
|
||||
With this configuration every new bug issue when added to this project immediately lands in the right column with the correct label, so maintainers always know what still needs triage.
|
||||
|
||||
Start small, test the workflow on a single project, and expand the automation set as your team discovers repetitive tasks you can offload to workflows.
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "项目",
|
||||
"position": 60,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/usage/projects",
|
||||
"description": "规划、跟踪并自动化仓库项目"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
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”。
|
||||
- 问题状态 → 保持打开(如有需要也可以强制重新打开以确保可见)。
|
||||
|
||||
配置完成后,每当新的缺陷问题加入该项目时都会立即拥有正确的标签并出现在指定列中,维护者可以第一时间看到需要分流的条目。
|
||||
|
||||
从简单规则开始,在单个项目中验证效果,再根据团队的重复性任务逐步扩展自动化逻辑。
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "專案",
|
||||
"position": 60,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/usage/projects",
|
||||
"description": "規劃、追蹤並自動化儲存庫專案"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
date: "2025-11-25T18:58:22Z"
|
||||
slug: "project-workflows"
|
||||
sidebar_position: 1
|
||||
description: "以事件、篩選條件與動作組合,替儲存庫專案自動化重複工作。"
|
||||
---
|
||||
|
||||
# 專案工作流程
|
||||
|
||||
專案工作流程會在儲存庫專案看板上依據議題或拉取請求觸發的事件自動執行操作。此功能完全在 Gitea 內部運行,不需要外部 Runner 或 Webhook。
|
||||
|
||||
有權管理專案工作流程的使用者可以建立、編輯、複製、啟用或停用工作流程,詳見[權限](#權限)。
|
||||
|
||||
## 開啟工作流程編輯器
|
||||
|
||||
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”。
|
||||
- 議題狀態 → 保持開啟(如有需要也能強制重新開啟以確保可見)。
|
||||
|
||||
設定完成後,每當有新的錯誤議題加入此專案,就會立即獲得正確標籤並顯示在指定欄位,維護者能第一時間掌握待分流的項目。
|
||||
|
||||
從簡單規則著手,在單一專案驗證成效,再依團隊的重複性工作逐步擴大自動化邏輯。
|
||||
Reference in new issue
Block a user