diff --git a/docs/usage/projects/_category_.json b/docs/usage/projects/_category_.json new file mode 100644 index 00000000..19eb937a --- /dev/null +++ b/docs/usage/projects/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Projects", + "position": 60, + "link": { + "type": "generated-index", + "slug": "/usage/projects", + "description": "Plan, track, and automate repository projects" + } +} diff --git a/docs/usage/projects/project-workflows.md b/docs/usage/projects/project-workflows.md new file mode 100644 index 00000000..de4c4e3e --- /dev/null +++ b/docs/usage/projects/project-workflows.md @@ -0,0 +1,92 @@ +--- +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 edit the project (repository owners, maintainers, and project managers) may create, edit, clone, enable, or disable workflows from the project UI. + +## Open the workflow editor + +1. Navigate to the repository → **Projects** and open the board you want to automate. +2. Select the **Workflows** tab that appears next to the project columns. +3. Click left sidbar to edit an event definition. +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 opened, 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 opened | A new issue or pull request is created. | +| 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. | +| 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 + +Workflows execute their actions in the order you add them. 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** - Change the state by closing or reopening the issue or pull request. + +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. + +### 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. + +## Example: triage incoming bug reports + +The following workflow keeps bug reports organized automatically: + +1. **Event:** Issues/PRs opened. +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. diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/projects/_category_.json b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/projects/_category_.json new file mode 100644 index 00000000..6f196c87 --- /dev/null +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/projects/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "项目", + "position": 60, + "link": { + "type": "generated-index", + "slug": "/usage/projects", + "description": "规划、跟踪并自动化仓库项目" + } +} diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/projects/project-workflows.md b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/projects/project-workflows.md new file mode 100644 index 00000000..5ab8bab2 --- /dev/null +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/projects/project-workflows.md @@ -0,0 +1,90 @@ +--- +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** 可以复制当前工作流（事件、过滤器与动作都会被复制）。在需要针对同一触发器设置不同条件时，复制并微调即可快速得到新的工作流。 + +## 示例：自动分流新的缺陷报告 + +以下工作流可以让缺陷报告自动进入待处理区： + +1. **事件：** Issues/PRs opened。 +2. **过滤器：** 仅适用于 `issues only`；标签包含 `bug`。 +3. **动作：** + - 添加标签 → `needs-triage`。 + - 移动到列 → “Needs Triage”。 + - 问题状态 → 保持打开（如有需要也可以强制重新打开以确保可见）。 + +配置完成后，每当新的缺陷问题创建时都会立即拥有正确的标签并出现在指定列中，维护者可以第一时间看到需要分流的条目。 + +从简单规则开始，在单个项目中验证效果，再根据团队的重复性任务逐步扩展自动化逻辑。 diff --git a/i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/projects/_category_.json b/i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/projects/_category_.json new file mode 100644 index 00000000..3a5f318d --- /dev/null +++ b/i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/projects/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "專案", + "position": 60, + "link": { + "type": "generated-index", + "slug": "/usage/projects", + "description": "規劃、追蹤並自動化儲存庫專案" + } +} diff --git a/i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/projects/project-workflows.md b/i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/projects/project-workflows.md new file mode 100644 index 00000000..9890fb10 --- /dev/null +++ b/i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/projects/project-workflows.md @@ -0,0 +1,90 @@ +--- +date: "2025-11-25T18:58:22Z" +slug: "project-workflows" +sidebar_position: 1 +description: "以事件、篩選條件與動作組合，替儲存庫專案自動化重複工作。" +--- + +# 專案工作流程 + +專案工作流程會在儲存庫專案看板上依據議題或拉取請求觸發的事件自動執行操作。此功能完全在 Gitea 內部運行，不需要外部 Runner 或 Webhook。 + +擁有專案編輯權限的成員（儲存庫擁有者、維護者與專案管理員）可在專案介面中建立、編輯、複製、啟用或停用工作流程。 + +## 開啟工作流程編輯器 + +1. 進入儲存庫並開啟想要自動化的 **Projects** 看板。 +2. 在欄位列表旁選擇 **Workflows** 分頁。 +3. 點擊 **New Workflow** 建立事件定義，或選取既有工作流程進行編輯。 +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** 可以複製目前的工作流程（事件、篩選條件與動作都會被保留）。當你需要針對相同事件建立不同變體時，複製後調整即可快速建立新流程。 + +## 範例：自動分流新的錯誤回報 + +以下設定能讓錯誤議題自動落在待處理區： + +1. **事件：** Issues/PRs opened。 +2. **篩選條件：** 僅適用 `issues only`；標籤包含 `bug`。 +3. **動作：** + - 新增標籤 → `needs-triage`。 + - 移動到欄位 → “Needs Triage”。 + - 議題狀態 → 保持開啟（如有需要也能強制重新開啟以確保可見）。 + +設定完成後，每當有新的錯誤議題建立，就會立即獲得正確標籤並顯示在指定欄位，維護者能第一時間掌握待分流的項目。 + +從簡單規則著手，在單一專案驗證成效，再依團隊的重複性工作逐步擴大自動化邏輯。