mirror of
https://gitea.com/gitea/docs.git
synced 2026-06-28 15:14:22 +00:00
docs: add docs for scoped workflows (#447)
Related: https://github.com/go-gitea/gitea/pull/38154 --------- Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com> Reviewed-on: https://gitea.com/gitea/docs/pulls/447 Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com> Co-authored-by: Zettat123 <zettat123@gmail.com> Co-committed-by: Zettat123 <zettat123@gmail.com>
This commit is contained in:
Zettat123
Nicolas
@@ -1692,6 +1692,7 @@ PROXY_HOSTS = *.github.com
|
||||
- `ABANDONED_JOB_TIMEOUT`: **24h**: Timeout to cancel the jobs which have waiting status, but haven't been picked by a runner for a long time
|
||||
- `SKIP_WORKFLOW_STRINGS`: **[skip ci],[ci skip],[no ci],[skip actions],[actions skip]**: Strings committers can place inside a commit message or PR title to skip executing the corresponding actions workflow
|
||||
- `WORKFLOW_DIRS`: **.gitea/workflows,.github/workflows**: Comma-separated list of workflow directories, the first one to exist in a repo is used to find Actions workflow files.
|
||||
- `SCOPED_WORKFLOW_DIRS`: **.gitea/scoped_workflows**: Comma-separated list of directories holding [scoped workflows](usage/actions/scoped-workflows.md) (workflows defined in a central source repository that run on other repositories). Must not overlap with `WORKFLOW_DIRS`. Leave empty so no directory is scanned for scoped workflows; none are found or run.
|
||||
- `MAX_RERUN_ATTEMPTS`: **50**: Maximum number of attempts a single workflow run can have (initial run + reruns). Defaults value is 50. Set any positive value that fits your workflow needs.
|
||||
|
||||
`DEFAULT_ACTIONS_URL` indicates where the Gitea Actions runners should find the actions with relative path.
|
||||
|
||||
119
docs/usage/actions/scoped-workflows.md
Normal file
119
docs/usage/actions/scoped-workflows.md
Normal file
@@ -0,0 +1,119 @@
|
||||
---
|
||||
date: "2026-06-26T00:00:00+00:00"
|
||||
slug: "scoped-workflows"
|
||||
sidebar_position: 60
|
||||
---
|
||||
|
||||
# Scoped Workflows
|
||||
|
||||
Scoped workflows let you maintain Actions workflows in one central **source** repository and have them run automatically on many other repositories, without copying the workflow files into each one.
|
||||
|
||||
A workflow file committed under a source repository's scoped-workflow directory runs on every repository that the source applies to (a "consuming" repository). Each run executes **in the consuming repository's own context**: its runners, secrets, `GITEA_TOKEN`, and branch, while the workflow **content is read from the source repository**. This is useful for mandating shared CI across an organization or instance: linting, security scans, compliance or policy checks, and similar.
|
||||
|
||||
## Levels
|
||||
|
||||
A source repository can be registered at two levels:
|
||||
|
||||
- **Owner level**: registered by an organization or user. The source's workflows run on every repository owned by that organization or user.
|
||||
- **Instance level**: registered by a site administrator. The source's workflows run on **every** repository on the instance.
|
||||
|
||||
The same repository may be registered at both levels; it is still evaluated once per matching event.
|
||||
|
||||
:::note
|
||||
Instance-level sources apply to **every** repository on the instance, and a required one cannot be opted out. Detection runs on every repository's events. Register them deliberately.
|
||||
:::
|
||||
|
||||
## Configuration
|
||||
|
||||
Scoped workflows live in a directory that is separate from regular workflows. It is controlled by `SCOPED_WORKFLOW_DIRS` in the `[actions]` section of `app.ini`:
|
||||
|
||||
```ini
|
||||
[actions]
|
||||
SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
|
||||
```
|
||||
|
||||
- The default is `.gitea/scoped_workflows`.
|
||||
- It may list multiple directories (comma-separated).
|
||||
- It **must not overlap** with `WORKFLOW_DIRS` (the regular workflow directories, by default `.gitea/workflows` and `.github/workflows`).
|
||||
- Leaving it empty means no directory holds scoped workflows, so none are found or run. The settings page still appears and sources can still be registered, but no scoped workflow runs.
|
||||
|
||||
Keeping scoped workflows in their own directory means a source repository's *own* Actions are unaffected: only files under `SCOPED_WORKFLOW_DIRS` are treated as scoped workflows.
|
||||
|
||||
## Providing scoped workflows from a repository
|
||||
|
||||
1. In the would-be source repository, commit your workflow files under the scoped-workflow directory on its **default branch**, for example `.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. Register the repository as a source:
|
||||
|
||||
- **Organization**: *Organization Settings -> Actions -> Scoped Workflows*
|
||||
- **User**: *User Settings -> Actions -> Scoped Workflows*
|
||||
- **Instance (admin)**: *Site Administration -> Actions -> Scoped Workflows*
|
||||
|
||||
Search for and add the repository. From then on, its scoped workflows apply to the consuming repositories at that level.
|
||||
|
||||
The source repository is within its own scope, so it runs these workflows on itself like any other consumer.
|
||||
|
||||
## How scoped workflows run
|
||||
|
||||
- The run belongs to the **consuming** repository and uses its runners, secrets, `GITEA_TOKEN`, and ref. It behaves like a normal run there, including rerun, logs, and commit statuses.
|
||||
- The workflow **content is read from the source** repository, pinned to the source's default-branch commit at the time of the event.
|
||||
- Detection uses the consuming repository's event, so the workflow's `on:` triggers (such as `push` and `pull_request`) must match that event.
|
||||
|
||||
## Opting out
|
||||
|
||||
A consuming repository can disable a scoped workflow it does not want, from its **Actions** page (the workflow appears under its source). A workflow that has been marked **required** (see below) can never be disabled or opted out by a consuming repository.
|
||||
|
||||
## Required workflows and the merge gate
|
||||
|
||||
On the Scoped Workflows settings page you can mark individual workflows as **required** and give each one or more **status-check patterns** (one glob per line). A required scoped workflow:
|
||||
|
||||
- Cannot be disabled by consuming repositories.
|
||||
- Gates pull-request merges: a consuming pull request can only be merged once a commit status matching **every** pattern has **passed** (must-present-and-pass). A required check that never posts a status **blocks** the merge rather than being silently skipped, so disabling Actions on the consumer cannot bypass it.
|
||||
|
||||
The status-check context a scoped run posts has the form:
|
||||
|
||||
```
|
||||
<source repo full name>: <workflow display name> / <job> (<event>)
|
||||
```
|
||||
|
||||
The settings page previews these "Expected status checks" for each workflow and marks the ones your patterns match, so you can confirm a pattern is correct. A common pattern wildcards the job and event, for example `my-org/ci-repo: Lint / *`.
|
||||
|
||||
Enforcement scope:
|
||||
|
||||
- A required check is enforced on any target branch that has a **branch protection rule**, even one whose own status checks are disabled.
|
||||
- A target branch with **no** protection rule is not gated.
|
||||
|
||||
:::warning
|
||||
Only a workflow that runs on an event that posts a commit status (`push`, `pull_request`, `pull_request_target`, `release`) can be required. A workflow that runs only on events like `workflow_dispatch`, `schedule` or `workflow_call` posts no status, so marking it required would block every consuming pull request forever. The settings page warns you in this case.
|
||||
:::
|
||||
|
||||
## Reusable workflows (`uses:`)
|
||||
|
||||
Scoped workflows can call reusable workflows:
|
||||
|
||||
- A **local** reference (`uses: ./...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
|
||||
- A **cross-repository** reference (`uses: owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
|
||||
|
||||
A reusable workflow can live under `SCOPED_WORKFLOW_DIRS` (or `WORKFLOW_DIRS`) of the source repository.
|
||||
|
||||
## Security considerations
|
||||
|
||||
A source repository's workflow content is executed in every repository it applies to, and its step scripts and their output are written to that repository's Actions logs, readable by anyone who can view the consuming repository's Actions.
|
||||
|
||||
- Registering a **private** repository as a source therefore discloses its workflow logic through those logs. Only register repositories whose workflow content may be shared with every consuming repository.
|
||||
|
||||
## Limitations
|
||||
|
||||
- `on: schedule` and `on: workflow_run` are currently not supported as scoped workflow triggers.
|
||||
- Scoped workflow content is read from the source's default branch; other branches of the source are not used.
|
||||
@@ -1570,6 +1570,7 @@ PROXY_HOSTS = *.github.com
|
||||
- `ABANDONED_JOB_TIMEOUT`: **24h**: 被遗弃的作业超时时间，指具有等待状态但长时间未被 runner 选中并执行的作业。
|
||||
- `SKIP_WORKFLOW_STRINGS`: **[skip ci],[ci skip],[no ci],[skip actions],[actions skip]**: 提交者可以在提交消息或 PR 标题中放置的字符串，以跳过执行相应的工作流。
|
||||
- `WORKFLOW_DIRS`：**.gitea/workflows,.github/workflows**：以逗号分隔的工作流目录列表，仓库中第一个存在的目录将用于查找 Actions 工作流文件。
|
||||
- `SCOPED_WORKFLOW_DIRS`：**.gitea/scoped_workflows**：以逗号分隔的目录列表，用于存放[作用域工作流](usage/actions/scoped-workflows.md)（在一个中心源仓库中定义、并在其他仓库上运行的工作流）。不得与 `WORKFLOW_DIRS` 重叠。留空则不会扫描任何目录来查找作用域工作流，因此不会找到或运行任何作用域工作流。
|
||||
- `MAX_RERUN_ATTEMPTS`：**50**：单个工作流运行最多可以有的尝试次数（初始运行 + 重新运行）。默认 50。可根据需要设置为任何正整数。
|
||||
|
||||
`DEFAULT_ACTIONS_URL` 指示 Gitea 操作运行程序应该在哪里找到带有相对路径的操作。
|
||||
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
date: "2026-06-26T00:00:00+00:00"
|
||||
slug: "scoped-workflows"
|
||||
sidebar_position: 60
|
||||
---
|
||||
|
||||
# 作用域工作流
|
||||
|
||||
作用域工作流（Scoped Workflows）让你把 Actions 工作流集中维护在一个**源（source）**仓库中，并让它们自动在许多其他仓库上运行，而无需把工作流文件复制到每个仓库里。
|
||||
|
||||
提交到源仓库作用域工作流目录下的工作流文件，会在该源所适用的每个仓库（称为**消费方（consuming）**仓库）上运行。每次运行都在**消费方仓库自身的上下文**中执行：使用它的 runner、密钥、`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、密钥、`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` 作为作用域工作流触发器。
|
||||
- 作用域工作流内容读取自源的默认分支；源的其他分支不会被使用。
|
||||
@@ -1570,6 +1570,7 @@ PROXY_HOSTS = *.github.com
|
||||
- `ABANDONED_JOB_TIMEOUT`: **24h**: 被遗弃的作业超时时间，指具有等待状态但长时间未被 runner 选中并执行的作业。
|
||||
- `SKIP_WORKFLOW_STRINGS`: **[skip ci],[ci skip],[no ci],[skip actions],[actions skip]**: 提交者可以在提交消息或 PR 标题中放置的字符串，以跳过执行相应的工作流。
|
||||
- `WORKFLOW_DIRS`：**.gitea/workflows,.github/workflows**：以逗号分隔的工作流目录列表，仓库中第一个存在的目录将用于查找 Actions 工作流文件。
|
||||
- `SCOPED_WORKFLOW_DIRS`：**.gitea/scoped_workflows**：以逗號分隔的目錄列表，用於存放[作用域工作流程](usage/actions/scoped-workflows.md)（在一個中心來源儲存庫中定義、並在其他儲存庫上執行的工作流程）。不得與 `WORKFLOW_DIRS` 重疊。留空則不會掃描任何目錄來尋找作用域工作流程，也就不會找到或執行任何作用域工作流程。
|
||||
- `MAX_RERUN_ATTEMPTS`：**50**：單個工作流執行最多可以有的嘗試次數（初始執行 + 重新執行）。預設 50。可根據需要設置為任何正整數。
|
||||
|
||||
`DEFAULT_ACTIONS_URL` 指示 Gitea 操作运行程序应该在哪里找到带有相对路径的操作。
|
||||
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
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` 作為作用域工作流程觸發器。
|
||||
- 作用域工作流程內容讀取自來源的預設分支；來源的其他分支不會被使用。
|
||||
Reference in New Issue
Block a user