From 3b71a35b510190659ec60f70f7da5f5f5930027a Mon Sep 17 00:00:00 2001 From: silverwind Date: Thu, 22 Oct 2026 13:19:59 +0200 Subject: [PATCH] docs(projects): document workflow permissions and sync with the implementation The "Issues/PRs opened" event was folded into "Added to project", pull requests can only be closed by workflows, closed projects don't run workflows, and actions run in a fixed order. The new Permissions section defines who can manage workflows and that they then act without further permission checks. Also fix the editor steps, a typo and the zh-tw page's nonexistent "New Workflow" button. Assisted-by: Claude Code:claude-opus-5-5 --- docs/usage/projects/project-workflows.md | 30 +++++++++++------ .../usage/projects/project-workflows.md | 32 ++++++++++++------- .../usage/projects/project-workflows.md | 32 ++++++++++++------- 3 files changed, 62 insertions(+), 32 deletions(-) diff --git a/docs/usage/projects/project-workflows.md b/docs/usage/projects/project-workflows.md index de4c4e3e..1e858bee 100644 --- a/docs/usage/projects/project-workflows.md +++ b/docs/usage/projects/project-workflows.md @@ -9,13 +9,13 @@ description: "Automate tasks on repository projects by reacting to events with f 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. +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 the **Workflows** tab that appears next to the project columns. -3. Click left sidbar to edit an event definition. +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. @@ -24,7 +24,7 @@ Every workflow lives inside the project it belongs to. If you need similar logic 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. +- **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. @@ -32,10 +32,9 @@ Every workflow is composed of `event`, `filters`, and `actions`. | 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. | +| 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. | @@ -57,12 +56,12 @@ You can combine filters to require multiple conditions (for example, PRs with th ## Actions -Workflows execute their actions in the order you add them. Available actions are: +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** - Change the state by closing or reopening the issue or pull request. +- **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). @@ -70,17 +69,28 @@ Combine actions to build more complex automations (for example, move the card an ### 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. +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. + ## Example: triage incoming bug reports The following workflow keeps bug reports organized automatically: -1. **Event:** Issues/PRs opened. +1. **Event:** Added to project. 2. **Filters:** Apply to `issues only`; Labels include `bug`. 3. **Actions:** - Add labels → `needs-triage`. 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 index 5ab8bab2..eb5c3b38 100644 --- 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 @@ -9,20 +9,20 @@ description: "在仓库项目上使用事件、过滤器和动作组合来自动 项目工作流可以在仓库项目看板上根据问题或拉取请求触发的事件自动执行操作。该功能无需外部 Runner 或 Webhook，完全在 Gitea 内部运行。 -具备项目编辑权限的成员（仓库所有者、维护者和项目管理员）都可以在项目界面中创建、编辑、克隆、启用或禁用工作流。 +有权管理项目工作流的用户可以创建、编辑、克隆、启用或禁用工作流，详见[权限](#权限)。 ## 打开工作流编辑器 1. 进入仓库并打开需要自动化的 **Projects** 看板。 -2. 在列列表旁选择 **Workflows** 选项卡。 -3. 点击事件定义，或选中已有工作流进行编辑。 +2. 在看板顶部的菜单中选择 **Workflows**。 +3. 点击左侧栏中的事件以编辑其工作流。 4. 选择事件、追加过滤器、按顺序添加需要的动作并保存。 每个工作流都存放在所属的项目下。如果另一个项目需要类似逻辑，请在目标项目中重新创建或克隆工作流。 ## 基本概念 -- **事件（Event）**：定义何时评估工作流，例如创建问题或卡片在列间移动。 +- **事件（Event）**：定义何时评估工作流，例如问题加入项目或卡片在列间移动。 - **过滤器（Filter）**：可选条件，只有满足条件才会执行动作，例如标签或列的变化。 - **动作（Action）**：当事件与过滤器匹配时 Gitea 要执行的操作，例如添加标签或移动卡片。 @@ -30,10 +30,9 @@ description: "在仓库项目上使用事件、过滤器和动作组合来自动 | 事件 | 触发时机 | | --- | --- | -| 新建问题/拉取请求 | 创建新的问题或拉取请求。 | | 关闭问题/拉取请求 | 该问题或拉取请求被关闭。 | | 重新打开问题/拉取请求 | 已关闭的条目被重新打开。 | -| 加入项目 | 问题或拉取请求被添加到该项目。 | +| 加入项目 | 问题或拉取请求被添加到该项目，包括在该项目中新建时。 | | 从项目移除 | 条目被从项目中移出。 | | 列发生变化 | 卡片从一个列移动到另一个列。 | | 被请求修改 | 与项目关联的拉取请求收到修改请求。 | @@ -55,12 +54,12 @@ description: "在仓库项目上使用事件、过滤器和动作组合来自动 ## 动作 -动作会按照添加顺序依次执行，可用的动作包括： +工作流先移动卡片，再修改标签，最后更改问题状态。可用的动作包括： - **添加标签（Add labels）**：为问题或拉取请求附加一个或多个标签。 - **移除标签（Remove labels）**：删除不再需要的标签。 - **移动到列（Move to column）**：将卡片移动到同一项目看板中的另一列。 -- **问题状态（Issue state）**：关闭或重新打开关联的问题或拉取请求。 +- **问题状态（Issue state）**：关闭或重新打开关联的问题。拉取请求只能被关闭。 通过组合多个动作，可在单个工作流中完成移动卡片、更新标签等多重操作。 @@ -68,23 +67,34 @@ description: "在仓库项目上使用事件、过滤器和动作组合来自动 ### 启用或禁用 -每个工作流都带有独立的开关。禁用后即使事件触发也会被忽略，适合临时暂停自动化而保留配置。 +每个工作流都带有独立的开关。禁用后即使事件触发也会被忽略，适合临时暂停自动化而保留配置。已关闭项目的工作流也不会运行。 ### 克隆事件工作流 点击 **Clone** 可以复制当前工作流（事件、过滤器与动作都会被复制）。在需要针对同一触发器设置不同条件时，复制并微调即可快速得到新的工作流。 +## 权限 + +权限在管理工作流时检查，而不是在工作流运行时检查。 + +- **查看**项目的工作流需要该项目的读取权限。 +- **创建、编辑、启用、禁用和删除**工作流需要该项目的写入权限，以及对该项目可容纳的所有条目的权限：仓库项目需要对该仓库的问题和拉取请求都拥有写入权限，组织项目需要是组织所有者或站点管理员，用户项目需要是该用户本人。仅限公开仓库的令牌不能管理组织或用户项目的工作流。 +- **工作流在**开放项目中的条目发生对应事件时运行，前提是条目所在仓库未归档且属于该项目的仓库或所有者，与谁触发了事件无关。 +- **其动作直接执行，不再进行权限检查**，包括为拉取请求添加标签和关闭拉取请求。工作流不会重新打开拉取请求。 +- 工作流所做的更改在时间线中显示为由“项目工作流”完成，并归属于触发该事件的用户，与 CODEOWNERS 发起的审查请求相同。这些更改不会触发其他工作流。 +- 只有能读取条目的用户才能将其加入项目或移动其卡片，因此工作流不会替用户操作其无法查看的条目。 + ## 示例：自动分流新的缺陷报告 以下工作流可以让缺陷报告自动进入待处理区： -1. **事件：** Issues/PRs opened。 +1. **事件：** 加入项目（Added to project）。 2. **过滤器：** 仅适用于 `issues only`；标签包含 `bug`。 3. **动作：** - 添加标签 → `needs-triage`。 - 移动到列 → “Needs Triage”。 - 问题状态 → 保持打开（如有需要也可以强制重新打开以确保可见）。 -配置完成后，每当新的缺陷问题创建时都会立即拥有正确的标签并出现在指定列中，维护者可以第一时间看到需要分流的条目。 +配置完成后，每当新的缺陷问题加入该项目时都会立即拥有正确的标签并出现在指定列中，维护者可以第一时间看到需要分流的条目。 从简单规则开始，在单个项目中验证效果，再根据团队的重复性任务逐步扩展自动化逻辑。 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 index 9890fb10..b67b05b8 100644 --- 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 @@ -9,20 +9,20 @@ description: "以事件、篩選條件與動作組合，替儲存庫專案自動 專案工作流程會在儲存庫專案看板上依據議題或拉取請求觸發的事件自動執行操作。此功能完全在 Gitea 內部運行，不需要外部 Runner 或 Webhook。 -擁有專案編輯權限的成員（儲存庫擁有者、維護者與專案管理員）可在專案介面中建立、編輯、複製、啟用或停用工作流程。 +有權管理專案工作流程的使用者可以建立、編輯、複製、啟用或停用工作流程，詳見[權限](#權限)。 ## 開啟工作流程編輯器 1. 進入儲存庫並開啟想要自動化的 **Projects** 看板。 -2. 在欄位列表旁選擇 **Workflows** 分頁。 -3. 點擊 **New Workflow** 建立事件定義，或選取既有工作流程進行編輯。 +2. 在看板頂端的選單中選擇 **Workflows**。 +3. 點擊左側欄中的事件以編輯其工作流程。 4. 選擇事件、加入篩選條件、依序配置需要的動作後儲存。 每個工作流程只屬於當前專案。如需在另一個專案套用相同邏輯，請在該專案重新建立或複製工作流程。 ## 基本概念 -- **事件（Event）**：定義何時評估工作流程，例如建立議題或卡片在欄位間移動。 +- **事件（Event）**：定義何時評估工作流程，例如議題加入專案或卡片在欄位間移動。 - **篩選條件（Filter）**：可選條件，需符合後才會執行動作，例如標籤或欄位變化。 - **動作（Action）**：當事件與篩選條件成立時 Gitea 要執行的操作，例如新增標籤或移動卡片。 @@ -30,10 +30,9 @@ description: "以事件、篩選條件與動作組合，替儲存庫專案自動 | 事件 | 觸發時機 | | --- | --- | -| 新增議題／拉取請求 | 建立新的議題或拉取請求。 | | 關閉議題／拉取請求 | 該議題或拉取請求被關閉。 | | 重新開啟議題／拉取請求 | 已關閉的項目被重新開啟。 | -| 加入專案 | 議題或拉取請求被加入此專案。 | +| 加入專案 | 議題或拉取請求被加入此專案，包括在此專案中建立時。 | | 從專案移除 | 項目被自專案中移除。 | | 欄位變更 | 卡片從某欄移到另一欄。 | | 被要求修改 | 與專案關聯的拉取請求收到修改要求。 | @@ -55,12 +54,12 @@ description: "以事件、篩選條件與動作組合，替儲存庫專案自動 ## 動作 -動作會依新增順序逐一執行，可用的動作包含： +工作流程會先移動卡片，再變更標籤，最後變更議題狀態。可用的動作包含： - **新增標籤（Add labels）**：為議題或拉取請求加上多個標籤。 - **移除標籤（Remove labels）**：刪除不再需要的標籤。 - **移動到欄位（Move to column）**：把卡片移到同一專案看板中的其他欄位。 -- **議題狀態（Issue state）**：關閉或重新開啟相關議題或拉取請求。 +- **議題狀態（Issue state）**：關閉或重新開啟相關議題。拉取請求只能被關閉。 透過組合多個動作，可以在單一工作流程裡同時完成移動卡片與更新標籤等步驟。 @@ -68,23 +67,34 @@ description: "以事件、篩選條件與動作組合，替儲存庫專案自動 ### 啟用或停用 -每個工作流程都有獨立開關。停用後即使事件被觸發也會被忽略，適合暫停自動化又不想刪除設定時使用。 +每個工作流程都有獨立開關。停用後即使事件被觸發也會被忽略，適合暫停自動化又不想刪除設定時使用。已關閉專案的工作流程也不會執行。 ### 複製事件工作流程 按下 **Clone** 可以複製目前的工作流程（事件、篩選條件與動作都會被保留）。當你需要針對相同事件建立不同變體時，複製後調整即可快速建立新流程。 +## 權限 + +權限在管理工作流程時檢查，而非在工作流程執行時檢查。 + +- **檢視**專案的工作流程需要該專案的讀取權限。 +- **建立、編輯、啟用、停用與刪除**工作流程需要該專案的寫入權限，以及對該專案可容納之所有項目的權限：儲存庫專案需要對該儲存庫的議題與拉取請求都擁有寫入權限，組織專案需要是組織擁有者或網站管理員，使用者專案需要是該使用者本人。僅限公開儲存庫的權杖無法管理組織或使用者專案的工作流程。 +- **工作流程會在**開放專案中的項目發生對應事件時執行，前提是項目所在儲存庫未封存且屬於該專案的儲存庫或擁有者，與誰觸發了事件無關。 +- **其動作直接套用，不再進行權限檢查**，包括為拉取請求新增標籤與關閉拉取請求。工作流程不會重新開啟拉取請求。 +- 工作流程所做的變更在時間軸中顯示為由「專案工作流程」完成，並歸屬於觸發該事件的使用者，與 CODEOWNERS 發起的審查請求相同。這些變更不會觸發其他工作流程。 +- 只有能讀取項目的使用者才能將其加入專案或移動其卡片，因此工作流程不會替使用者操作其無法查看的項目。 + ## 範例：自動分流新的錯誤回報 以下設定能讓錯誤議題自動落在待處理區： -1. **事件：** Issues/PRs opened。 +1. **事件：** 加入專案（Added to project）。 2. **篩選條件：** 僅適用 `issues only`；標籤包含 `bug`。 3. **動作：** - 新增標籤 → `needs-triage`。 - 移動到欄位 → “Needs Triage”。 - 議題狀態 → 保持開啟（如有需要也能強制重新開啟以確保可見）。 -設定完成後，每當有新的錯誤議題建立，就會立即獲得正確標籤並顯示在指定欄位，維護者能第一時間掌握待分流的項目。 +設定完成後，每當有新的錯誤議題加入此專案，就會立即獲得正確標籤並顯示在指定欄位，維護者能第一時間掌握待分流的項目。 從簡單規則著手，在單一專案驗證成效，再依團隊的重複性工作逐步擴大自動化邏輯。