---
date: "2026-06-26T00:00:00+00:00"
slug: "scoped-workflows"
sidebar_position: 60
---

# 作用域工作流程

作用域工作流程（Scoped Workflows）讓你把 Actions 工作流程集中維護在一個**來源（source）**儲存庫中，並讓它們自動在許多其他儲存庫上執行，而無需把工作流程檔案複製到每個儲存庫裡。

提交到來源儲存庫作用域工作流程目錄下的工作流程檔案，會在該來源所適用的每個儲存庫（稱為**消費方（consuming）**儲存庫）上執行。每次執行都在**消費方儲存庫自身的環境**中進行：使用它的 runner、Secret、`GITEA_TOKEN` 和分支，而工作流程**內容則讀取自來源儲存庫**。這適用於在組織或實例範圍內強制推行共用 CI：程式碼檢查、安全掃描、合規或政策檢查等。

## 層級

來源儲存庫可以在兩個層級註冊：

- **擁有者層級（Owner level）**：由組織或使用者註冊。該來源的工作流程會在該組織或使用者擁有的每個儲存庫上執行。
- **實例層級（Instance level）**：由網站管理員註冊。該來源的工作流程會在實例上的**每一個**儲存庫上執行。

同一個儲存庫可以同時在兩個層級註冊；對於每個符合的事件，它仍只會被評估一次。

:::note
實例層級的來源適用於實例上的**每一個**儲存庫，且被設為必要（required）的來源無法被選擇退出（opt out）。偵測會在每個儲存庫的每次事件上執行。請審慎註冊。
:::

## 設定

作用域工作流程存放在一個與一般工作流程分開的目錄中，由 `app.ini` 中 `[actions]` 區段的 `SCOPED_WORKFLOW_DIRS` 控制：

```ini
[actions]
SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
```

- 預設值為 `.gitea/scoped_workflows`。
- 可以列出多個目錄（以逗號分隔）。
- **不得與** `WORKFLOW_DIRS`（一般工作流程目錄，預設為 `.gitea/workflows` 和 `.github/workflows`）**重疊**。
- 留空表示沒有任何目錄存放作用域工作流程，因此不會找到也不會執行任何作用域工作流程。設定頁面仍會顯示、來源仍可註冊，但不會有任何作用域工作流程執行。

把作用域工作流程放在它們自己的目錄中，表示來源儲存庫**自身**的 Actions 不受影響：只有 `SCOPED_WORKFLOW_DIRS` 下的檔案才會被當作作用域工作流程。

## 從一個儲存庫提供作用域工作流程

1. 在準備作為來源的儲存庫中，把工作流程檔案提交到其**預設分支**上的作用域工作流程目錄下，例如 `.gitea/scoped_workflows/lint.yaml`：

   ```yaml
   name: Lint
   on: [push, pull_request]
   jobs:
     lint:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: echo "lint the consuming repository here"
   ```

2. 將該儲存庫註冊為來源：

   - **組織**：*組織設定 -> Actions -> 作用域工作流程*
   - **使用者**：*使用者設定 -> Actions -> 作用域工作流程*
   - **實例（管理員）**：*網站管理 -> Actions -> 作用域工作流程*

   搜尋並新增該儲存庫。此後，它的作用域工作流程便會適用於該層級下的消費方儲存庫。

來源儲存庫也在它自己的作用域內，因此它會像其他消費方一樣在自身上執行這些工作流程。

## 作用域工作流程如何執行

- 該執行屬於**消費方**儲存庫，使用它的 runner、Secret、`GITEA_TOKEN` 和 ref。它在那裡的行為與一般執行一致，包括重新執行、日誌和提交狀態。
- 工作流程**內容讀取自來源**儲存庫，並釘選在事件發生時來源預設分支的 commit 上。
- 偵測使用消費方儲存庫的事件，因此工作流程的 `on:` 觸發器（例如 `push` 和 `pull_request`）必須與該事件相符。

## 選擇退出（Opting out）

消費方儲存庫可以在其 **Actions** 頁面（該工作流程會顯示在其來源之下）停用一個它不想要的作用域工作流程。已被標記為**必要（required）**（見下文）的工作流程，消費方儲存庫永遠無法將其停用，也無法選擇退出。

## 必要工作流程與合併門檻

在作用域工作流程設定頁面上，你可以把個別工作流程標記為**必要（required）**，並為每個工作流程給定一個或多個**狀態檢查模式（status-check patterns）**（每行一個 glob）。一個必要的作用域工作流程：

- 無法被消費方儲存庫停用。
- 會對合併請求（PR）形成合併門檻：消費方的 PR 只有在一個符合**每一個**模式的提交狀態都**通過**後才能合併（必須存在且通過，must-present-and-pass）。一個從不產生任何狀態的必要檢查會**阻擋**合併，而不是被靜默略過，因此在消費方停用 Actions 也無法繞過它。

作用域執行產生的狀態檢查 context 形如：

```
<來源儲存庫全名>: <工作流程顯示名稱> / <job> (<event>)
```

設定頁面會為每個工作流程預覽這些 “Expected status checks（預期狀態檢查）”，並標記出與你的模式相符的項目，便於你確認模式是否正確。一種常見模式是對 job 和 event 使用萬用字元，例如 `my-org/ci-repo: Lint / *`。

強制範圍：

- 必要檢查會在任何設有**分支保護規則**的目標分支上強制生效，即使該規則自身的狀態檢查處於關閉狀態。
- **沒有**保護規則的目標分支不受門檻約束。

:::warning
只有執行在會產生提交狀態的事件（`push`、`pull_request`、`pull_request_target`、`release`）上的工作流程才能被設為必要。僅執行在 `workflow_dispatch`、`schedule` 或 `workflow_call` 等事件上的工作流程不會產生任何狀態，因此把它設為必要會**永久**阻擋每一個消費方 PR 的合併。設定頁面在這種情況下會向你發出警告。
:::

## 可重複使用的工作流程（`uses:`）

作用域工作流程可以呼叫可重複使用的工作流程：

- **本機**參照（`uses: ./...`）會相對於**來源**儲存庫解析：即呼叫方工作流程內容的來源儲存庫，而非消費方儲存庫。
- **跨儲存庫**參照（`uses: owner/repo/...@ref`）會以**消費方儲存庫的**讀取權限來解析。如果它指向一個私有儲存庫，請確保每個消費方儲存庫都能讀取它，否則工作流程會在那裡失敗。

可重複使用的工作流程可以放在來源儲存庫的 `SCOPED_WORKFLOW_DIRS`（或 `WORKFLOW_DIRS`）之下。

## 安全性注意事項

來源儲存庫的工作流程內容會在它所適用的每個儲存庫中執行，其步驟指令碼及其輸出會寫入該儲存庫的 Actions 日誌，任何能檢視消費方儲存庫 Actions 的人都能讀取這些日誌。

- 因此，將一個**私有**儲存庫註冊為來源，會透過這些日誌洩漏其工作流程邏輯。只應註冊那些其工作流程內容可以與每個消費方儲存庫共用的儲存庫。

## 限制

- 目前不支援將 `on: schedule` 和 `on: workflow_run` 作為作用域工作流程觸發器。
- 作用域工作流程內容讀取自來源的預設分支；來源的其他分支不會被使用。