mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-08 11:00:34 +00:00
docs: document self:, builtin:, $/ and runner tracing (#553)
Documents the `self:` and `builtin:` action prefixes from https://github.com/go-gitea/gitea/pull/39358, https://gitea.com/gitea/runner/pulls/1233 and https://gitea.com/gitea/runner/pulls/871, workflow-relative `$/` actions, and the runner's OpenTelemetry tracing from https://gitea.com/gitea/runner/pulls/1206. 1. Trims the action resolution and `DEFAULT_ACTIONS_URL` docs to state each fact once. 1. Drops outdated runner content from the FAQ and design pages. 1. Syncs zh-cn and zh-tw, including a port of the token permissions page they now link to. _Written by Claude._ Reviewed-on: https://gitea.com/gitea/docs/pulls/553 Reviewed-by: bircni <[email protected]> Co-authored-by: silverwind <[email protected]>
This commit is contained in:
silverwind authored and 
bircni committed
1 parent
f9124b16db
commit
c4caf767ad
19 files changed
+476
-444
No files matched your search
+3
-12
@@ -1541,18 +1541,9 @@ PROXY_HOSTS = *.github.com
|
||||
- `SCOPED_WORKFLOW_DIRS`：**.gitea/scoped_workflows**：以逗号分隔的目录列表，用于存放[作用域工作流](usage/actions/scoped-workflows.md)（在一个中心源仓库中定义、并在其他仓库上运行的工作流）。不得与 `WORKFLOW_DIRS` 重叠。留空则不会扫描任何目录来查找作用域工作流，因此不会找到或运行任何作用域工作流。
|
||||
- `MAX_RERUN_ATTEMPTS`：**50**：单个工作流运行最多可以有的尝试次数（初始运行 + 重新运行）。默认 50。可根据需要设置为任何正整数。
|
||||
|
||||
`DEFAULT_ACTIONS_URL` 指示 Gitea 操作运行程序应该在哪里找到带有相对路径的操作。
|
||||
例如，`uses: actions/checkout@v4` 表示 `https://github.com/actions/checkout@v4`，因为 `DEFAULT_ACTIONS_URL` 的值为 `github`。
|
||||
它可以更改为 `self`，以使其成为 `root_url_of_your_gitea/actions/checkout@v4`。
|
||||
|
||||
请注意，对于大多数情况，不建议使用 `self`，因为它可能使名称在全局范围内产生歧义。
|
||||
此外，它要求您将所有所需的操作镜像到您的 Gitea 实例，这可能不值得。
|
||||
因此，请仅在您了解自己在做什么的情况下使用 `self`。
|
||||
|
||||
在早期版本（`<= 1.19`）中，`DEFAULT_ACTIONS_URL` 可以设置为任何自定义 URL，例如 `https://gitea.com` 或 `http://your-git-server,https://gitea.com`，默认值为 `https://gitea.com`。
|
||||
然而，后来的更新删除了这些选项，现在唯一的选项是 `github` 和 `self`，默认值为 `github`。
|
||||
但是，如果您想要使用其他 Git 服务器中的操作，您可以在 `uses` 字段中使用完整的 URL，Gitea 支持此功能（GitHub 不支持）。
|
||||
例如 `uses: https://gitea.com/actions/checkout@v4` 或 `uses: http://your-git-server/actions/checkout@v4`。
|
||||
`DEFAULT_ACTIONS_URL` 设置 runner 从何处下载未指定主机的操作。
|
||||
值为 `github` 时，`uses: actions/checkout@v4` 解析为 `https://github.com/actions/checkout@v4`，值为 `self` 时解析为 `<ROOT_URL>/actions/checkout@v4`。
|
||||
`self` 要求您将用到的所有操作镜像到您的实例，因此更推荐为每个操作单独指明主机：使用 `uses: self:owner/repo@ref` 指向您的实例，或使用完整 URL（如 `uses: https://gitea.com/actions/checkout@v4`）指向任何其他主机。
|
||||
|
||||
## 其他 (`other`)
|
||||
|
||||
|
||||
@@ -12,6 +12,7 @@ aliases:
|
||||
|
||||
通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。
|
||||
|
||||
<a id="authentication"></a>
|
||||
## 通过 API 认证
|
||||
|
||||
Gitea 支持以下几种 API 认证方式：
|
||||
|
||||
@@ -6,120 +6,97 @@ sidebar_position: 15
|
||||
|
||||
# 与GitHub Actions的对比
|
||||
|
||||
尽管Gitea Actions旨在与GitHub Actions兼容，但它们之间存在一些差异。
|
||||
Gitea Actions旨在与GitHub Actions兼容，差异如下。
|
||||
|
||||
## 额外功能
|
||||
|
||||
<a id="absolute-action-urls"></a>
|
||||
### Action URL绝对路径
|
||||
|
||||
Gitea Actions支持通过URL绝对路径定义actions，这意味着您可以使用来自任何Git存储库的Actions。
|
||||
例如，`uses: https://github.com/actions/checkout@v4`或`uses: http://your_gitea.com/owner/repo@branch`。
|
||||
`uses:`支持指向任意Git托管平台的绝对URL，例如`uses: https://gitea.com/actions/checkout@v4`。
|
||||
|
||||
<a id="action-prefixes"></a>
|
||||
### Action前缀
|
||||
|
||||
`uses:`支持以下前缀：
|
||||
|
||||
- `self:`引用您自己的Gitea实例，例如`uses: self:owner/repo@v1`或`uses: self:owner/repo/.gitea/workflows/build.yml@v1`
|
||||
- `builtin:`运行Gitea Runner内置的Action，无需下载，Job镜像中也无需Node，例如`uses: builtin:checkout`
|
||||
|
||||
`builtin:checkout`支持`actions/checkout`的`repository`、`ref`、`token`、`path`和`fetch-depth`输入，默认值相同，其他输入会使步骤失败。
|
||||
|
||||
<a id="workflow-relative-actions"></a>
|
||||
### 相对于工作流的Actions
|
||||
|
||||
`$/`引用工作流所在的仓库和提交，或外层复合Action所在的仓库和提交，例如`uses: $/.gitea/actions/build`。
|
||||
与`./`不同，它无需事先检出代码。
|
||||
|
||||
### 使用Go编写Actions
|
||||
|
||||
Gitea Actions支持使用Go编写Actions。
|
||||
请参阅[创建Go Actions](https://blog.gitea.com/creating-go-actions/)。
|
||||
|
||||
### 支持非标准的调度语法 @yearly, @monthly, @weekly, @daily, @hourly
|
||||
|
||||
Github Actions 不支持这些语法，详见： https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
|
||||
`schedule`还支持`@yearly`、`@monthly`、`@weekly`、`@daily`和`@hourly`，而[GitHub不支持](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule)。
|
||||
|
||||
## 不支持的工作流语法
|
||||
|
||||
### `concurrency`
|
||||
|
||||
这是用于一次运行一个Job。
|
||||
请参阅[使用并发](https://docs.github.com/zh/actions/using-jobs/using-concurrency)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### `run-name`
|
||||
|
||||
这是工作流生成的工作流运行的名称。
|
||||
请参阅[GitHub Actions 的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#run-name)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### `permissions`和`jobs.<job_id>.permissions`
|
||||
|
||||
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#permissions)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### `jobs.<job_id>.timeout-minutes`
|
||||
|
||||
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### `jobs.<job_id>.continue-on-error`
|
||||
|
||||
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
|
||||
### `jobs.<job_id>.environment`
|
||||
|
||||
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)。
|
||||
|
||||
Gitea Actions 目前不支持此功能。
|
||||
[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)会被忽略。
|
||||
|
||||
### 复杂的`runs-on`
|
||||
|
||||
请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
|
||||
[`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)支持：
|
||||
|
||||
Gitea Actions目前只支持`runs-on: xyz`或`runs-on: [xyz]`。
|
||||
|
||||
### `hashFiles`表达式
|
||||
|
||||
请参阅[表达式](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles)。
|
||||
|
||||
Gitea Actions目前不支持此功能，如果使用它，结果将始终为空字符串。
|
||||
|
||||
作为解决方法，您可以使用[go-hashfiles](https://gitea.com/actions/go-hashfiles)。
|
||||
- 静态字符串：`runs-on: self-hosted`
|
||||
- 标签数组：`runs-on: [linux, self-hosted]`
|
||||
- 字符串表达式：`runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
|
||||
- 包含表达式的数组：`runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
|
||||
|
||||
## 缺失的功能
|
||||
|
||||
### 软件包仓库授权
|
||||
|
||||
`GITEA_TOKEN`无法发布到其所属仓库的软件包注册表，例如无法推送OCI镜像。
|
||||
请改用个人访问令牌，参见[此问题](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692)。
|
||||
|
||||
### 问题匹配器
|
||||
|
||||
问题匹配器是一种扫描Actions输出以查找指定正则表达式模式并在用户界面中突出显示该信息的方法。
|
||||
请参阅[问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
[问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)会被忽略。
|
||||
|
||||
### 为错误创建注释
|
||||
|
||||
请参阅[为错误创建注释](https://docs.github.com/zh/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)。
|
||||
|
||||
Gitea Actions目前不支持此功能。
|
||||
[错误注释](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)会被忽略。
|
||||
|
||||
### 表达式
|
||||
|
||||
对于 [表达式](https://docs.github.com/en/actions/learn-github-actions/expressions), 当前仅 [`always()`](https://docs.github.com/en/actions/learn-github-actions/expressions#always) 被支持。
|
||||
[表达式](https://docs.github.com/en/actions/learn-github-actions/expressions)支持GitHub的标准函数和上下文。
|
||||
|
||||
## 缺失的UI功能
|
||||
|
||||
### 预处理和后处理步骤
|
||||
|
||||
预处理和后处理步骤在Job日志用户界面中没有自己的用户界面。
|
||||
预处理和后处理步骤在Job日志中没有单独的区块。
|
||||
|
||||
### 服务步骤
|
||||
|
||||
服务步骤在Job日志用户界面中没有自己的用户界面。
|
||||
服务步骤在Job日志中没有单独的区块。
|
||||
|
||||
## 不一样的行为
|
||||
|
||||
### `permissions`和`jobs.<job_id>.permissions`
|
||||
|
||||
`permissions`和`jobs.<job_id>.permissions`控制`GITEA_TOKEN`的权限，该权限受仓库和所有者设置的限制，并在fork拉取请求和跨仓库访问时受到进一步限制。
|
||||
不支持`statuses`、`checks`、`deployments`、`id-token`、`security-events`和`pages`等GitHub专有的权限范围，而Gitea额外提供了`code`、`releases`、`wiki`和`projects`。
|
||||
请参阅[Actions Job令牌权限](token-permissions.md)。
|
||||
|
||||
### 下载Actions
|
||||
|
||||
当 `[actions].DEFAULT_ACTIONS_URL` 保持默认值为 `github` 时，Gitea将会从 https://github.com 下载相对路径的actions。比如：
|
||||
如果你使用 `uses: actions/checkout@v4`，Gitea将会从 https://github.com/actions/checkout.git 下载这个 actions 项目。
|
||||
如果你想要从另外一个 Git服务下载actions，你只需要使用绝对URL `uses: https://gitea.com/actions/checkout@v4` 来下载。
|
||||
|
||||
如果你的 Gitea 实例是部署在一个互联网限制的网络中，也可以使用绝对地址来下载 actions。你也可以将配置项修改为 `[actions].DEFAULT_ACTIONS_URL = self`。这样所有的相对路径的actions引用，将不再会从 github.com 去下载，而会从这个 Gitea 实例自己的仓库中去下载。例如： `uses: actions/checkout@v4` 将会从 `[server].ROOT_URL`/actions/checkout.git 这个地址去下载 actions。
|
||||
|
||||
设置`[actions].DEFAULT_ACTIONS_URL`进行配置。请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-actions)。
|
||||
未指定主机的Actions（如`uses: actions/checkout@v4`）会从`https://github.com`下载，当`[actions].DEFAULT_ACTIONS_URL`为`self`时则从您自己的实例下载。
|
||||
请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-actions)。
|
||||
其他来源请参阅[Action URL绝对路径](#absolute-action-urls)、[Action前缀](#action-prefixes)和[相对于工作流的Actions](#workflow-relative-actions)。
|
||||
|
||||
### 上下文可用性
|
||||
|
||||
不检查上下文可用性，因此您可以在更多地方使用env上下文。
|
||||
请参阅[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)。
|
||||
不检查[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)，因此`env`等上下文可以在更多地方使用。
|
||||
@@ -19,7 +19,7 @@ Gitea Runner部分基于[nektos/act](https://github.com/nektos/act)的硬分支
|
||||
|
||||
之前，我们提到工作流文件中的 `runs-on: ubuntu-latest` 表示该Job将在具有`ubuntu-latest`标签的Runner上运行。
|
||||
但是，Runner如何知道要运行 `ubuntu-latest`？答案在于将标签映射到环境。
|
||||
这就是为什么在注册过程中添加自定义标签时，需要输入一些复杂内容，比如`my_custom_label:docker://centos:7`。
|
||||
这就是为什么Runner的每个标签都会指定一个环境，比如`my_custom_label:docker://centos:7`。
|
||||
这意味着Runner可以接受需要在`my_custom_label`上运行的Job，并通过使用`centos:7`镜像的Docker容器来运行它。
|
||||
|
||||
然而，Docker不是唯一的选择。
|
||||
@@ -35,7 +35,6 @@ Runner 也支持直接在主机上运行Job。
|
||||
- `my_custom_label:docker://node:18`：使用`node:18 Docker`镜像运行带有`my_custom_label`标签的Job。
|
||||
- `my_custom_label:host`：在主机上直接运行带有`my_custom_label`标签的Job。
|
||||
- `my_custom_label`：等同于`my_custom_label:host`。
|
||||
- `my_custom_label:vm:ubuntu-latest`：（仅为示例，未实现）使用带有`ubuntu-latest` ISO的虚拟机运行带有`my_custom_label`标签的Job。
|
||||
|
||||
## 通信协议
|
||||
|
||||
@@ -44,7 +43,7 @@ Runner 也支持直接在主机上运行Job。
|
||||
相反，我们希望重用HTTP端口，这意味着我们需要一个与HTTP兼容的协议。
|
||||
因此，我们选择使用基于HTTP的gRPC。
|
||||
|
||||
我们使用[actions-proto-def](https://gitea.com/gitea/actions-proto-def) 和 [actions-proto-go](https://gitea.com/gitea/actions-proto-go) 进行连接。
|
||||
该协议定义在[actions-proto-def](https://gitea.com/gitea/actions-proto-def)中，其Go代码位于[actionslib](https://gitea.com/gitea/actionslib)。
|
||||
有关 gRPC 的更多信息，请访问[其官方网站](https://grpc.io/)。
|
||||
|
||||
## 网络架构
|
||||
@@ -72,8 +71,8 @@ Runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
|
||||
### 连接 3，runner 到互联网
|
||||
|
||||
当您使用诸如 `actions/checkout@v4` 的一些Actions时， runner下载的是脚本，而不是Job容器。
|
||||
默认情况下，它从[github.com](http://github.com/)下载，因此需要访问互联网。如果您设置的是 self，
|
||||
那么默认将从您的当前Gitea实例下载，那么此步骤不需要连接到互联网。
|
||||
默认情况下，它从[github.com](https://github.com/)下载这些脚本，这需要访问互联网。
|
||||
如果将`DEFAULT_ACTIONS_URL`设置为`self`，或使用`uses: self:owner/repo@ref`，它会改为从您的Gitea实例下载。
|
||||
它还默认从Docker Hub下载一些Docker镜像，这也需要互联网访问。
|
||||
|
||||
然而，互联网访问并不是绝对必需的。
|
||||
|
||||
@@ -27,34 +27,19 @@ DEFAULT_REPO_UNITS = ...,repo.actions
|
||||
|
||||
## 使用`actions/checkout@v4`等Actions时，Job容器会从何处下载脚本？
|
||||
|
||||
GitHub 上有成千上万个 [Actions 脚本](https://github.com/marketplace?type=actions)。
|
||||
当您编写 `uses: actions/checkout@v4` 时，它默认会从 [github.com/actions/checkout](https://github.com/actions/checkout) 下载脚本。
|
||||
那如果您想使用一些托管在其它平台上的脚本呢，比如在 gitea.com 上的？
|
||||
默认从`https://github.com`下载，当`[actions].DEFAULT_ACTIONS_URL`为`self`时则从您自己的实例下载，参见[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
|
||||
|
||||
好消息是，您可以指定要从任何位置使用Actions的URL前缀。
|
||||
这是Gitea Actions中的额外语法。
|
||||
例如：
|
||||
要使用其他位置的Action，请指明其主机：
|
||||
|
||||
- `uses: https://gitea.com/xxx/xxx@xxx`
|
||||
- `uses: https://github.com/xxx/xxx@xxx`
|
||||
- `uses: http://your_gitea_instance.com/xxx@xxx`
|
||||
|
||||
注意，`https://`或`http://`前缀是必需的！
|
||||
|
||||
这是与 GitHub Actions 的一个区别，GitHub Actions 只允许使用托管在 GitHub 上的 actions 脚本。
|
||||
但用户理应拥有权利去灵活决定如何运行 Actions。
|
||||
|
||||
另外，如果您希望您的 Runner 默认从您自己的 Gitea 实例下载 Actions，可以通过设置 `[actions].DEFAULT_ACTIONS_URL`进行配置。
|
||||
参见[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
|
||||
- `uses: https://gitea.com/owner/repo@ref`
|
||||
- `uses: http://your_gitea_instance.com/owner/repo@ref`
|
||||
- `uses: self:owner/repo@ref`，用于您自己的Gitea实例
|
||||
|
||||
## 如何限制Runner的权限？
|
||||
|
||||
Runner仅具有连接到您的Gitea实例的权限。
|
||||
当任何Runner接收到要运行的Job时，它将临时获得与Job关联的仓库的有限权限。
|
||||
如果您想为Runner提供更多权限，允许它访问更多私有仓库或外部系统，您可以向其传递[密钥](usage/actions/secrets.md)。
|
||||
|
||||
对于 Actions 的细粒度权限控制是一项复杂的工作。
|
||||
在未来，我们将添加更多选项以使Gitea更可配置，例如允许对仓库进行更多写访问或对同一组织中的所有仓库进行读访问。
|
||||
Runner仅连接到您的Gitea实例。
|
||||
对于每个Job，Runner会获得一个仅限于该Job所属仓库的`GITEA_TOKEN`，参见[Actions Job令牌权限](token-permissions.md)。
|
||||
如需让Job访问更多私有仓库或外部系统，请向其传递[密钥](usage/actions/secrets.md)。
|
||||
|
||||
## 如何避免被黑客攻击？
|
||||
|
||||
@@ -75,19 +60,8 @@ Runner仅具有连接到您的Gitea实例的权限。
|
||||
|
||||
## Runner 支持哪些操作系统？
|
||||
|
||||
它在Linux、macOS和Windows上运行良好。
|
||||
虽然理论上支持其他操作系统，但需要进一步测试。
|
||||
|
||||
需要注意的一点是，如果选择直接在主机上运行Job而不是在Job容器中运行，操作系统之间的环境差异可能会导致意外的失败。
|
||||
|
||||
例如，在大多数情况下，Windows上没有可用的bash，而act尝试默认使用bash运行脚本。
|
||||
因此，您需要在工作流文件中将默认shell指定为`powershell`，参考[defaults.run](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun)。
|
||||
|
||||
```yaml
|
||||
defaults:
|
||||
run:
|
||||
shell: powershell
|
||||
```
|
||||
官方发布了Linux、macOS和Windows的二进制文件。
|
||||
理论上，Go和Docker支持的其他系统也可以运行。
|
||||
|
||||
## 为什么选择GitHub Actions？为什么不选择与GitLab CI/CD兼容的工具？
|
||||
|
||||
@@ -99,42 +73,13 @@ defaults:
|
||||
|
||||
## 如果它在多个标签上运行，例如 `runs-on: [label_a, label_b]`，会发生什么？
|
||||
|
||||
这是有效的语法。
|
||||
它意味着它应该在具有`label_a` **和** `label_b`标签的Runner上运行，参考[GitHub Actions的工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
|
||||
不幸的是，runner 并不支持这种方式。
|
||||
如上所述，我们将标签映射到环境：
|
||||
|
||||
- `ubuntu` → `ubuntu:22.04`
|
||||
- `centos` → `centos:8`
|
||||
|
||||
但我们需要将标签组映射到环境，例如：
|
||||
|
||||
- `[ubuntu]` → `ubuntu:22.04`
|
||||
- `[with-gpu]` → `linux:with-gpu`
|
||||
- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
|
||||
|
||||
我们还需要重新设计任务分配给Runner的方式。
|
||||
具有`ubuntu`、`centos`或`with-gpu`的Runner并不一定表示它可以接受`[centos, with-gpu]`的Job。
|
||||
因此，Runner应该通知Gitea实例它只能接受具有 `[ubuntu]`、`[centos]`、`[with-gpu]` 和 `[ubuntu, with-gpu]`的Job。
|
||||
这不是一个技术问题，只是在早期设计中被忽视了。
|
||||
参见[runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
|
||||
|
||||
目前，runner 尝试匹配标签中的每一个，并使用找到的第一个匹配项。
|
||||
该Job会在拥有所有这些标签的Runner上运行，与[GitHub](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)一致。
|
||||
Runner会使用这些标签中它所拥有的第一个标签对应的环境。
|
||||
|
||||
## 代理标签和自定义标签对于Runner有什么区别？
|
||||
|
||||
|
||||
|
||||
代理标签是由 Runner 在注册过程中向 Gitea 实例报告的。
|
||||
而自定义标签则是由Gitea的管理员或组织或仓库的所有者手动添加的（取决于Runner所属的级别）。
|
||||
|
||||
然而，目前这方面的设计还有待改进，因为它目前存在一些不完善之处。
|
||||
您可以向已注册的Runner添加自定义标签，比如 `centos`，这意味着该Runner将接收具有`runs-on: centos`的Job。
|
||||
然而，Runner可能不知道要使用哪个环境来执行该标签，导致它使用默认镜像或导致逻辑死胡同。
|
||||
这个默认值可能与用户的期望不符。
|
||||
参见[runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
|
||||
|
||||
与此同时，如果您想更改Runner的标签，我们建议您重新注册Runner。
|
||||
Gitea已不再有自定义标签。
|
||||
Runner每次启动时都会声明其标签，标签来自`runner.labels`配置或注册时指定的标签，因此请在那里修改并重启Runner。
|
||||
|
||||
## Gitea Actions runner会有更多的实现吗？
|
||||
|
||||
@@ -165,3 +110,11 @@ defaults:
|
||||
|
||||
> 对于 `pull_request` 事件，在 [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) 中 `ref` 是 `refs/pull/:prNumber/merge`，它指向这个拉取请求合并提交的一个预览。但是 Gitea 没有这种 reference。
|
||||
> 因此，Gitea Actions 中 `ref` 是 `refs/pull/:prNumber/head`，它指向这个拉取请求的头分支而不是合并提交的预览。
|
||||
|
||||
## 如何共享私有仓库中的Actions和可复用工作流？
|
||||
|
||||
前往仓库的**设置** > **Actions** > **常规**页面并添加协作所有者。
|
||||
协作所有者的私有仓库可以访问当前仓库中的Actions和工作流。
|
||||
|
||||
如需在同一用户或组织内共享，请改为在该用户或组织的**设置** > **Actions** > **常规** > **跨仓库访问**中添加这些私有仓库。
|
||||
参见[跨仓库访问](token-permissions.md#cross-repository-access)。
|
||||
@@ -102,8 +102,8 @@ SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
|
||||
|
||||
作用域工作流可以调用可复用工作流：
|
||||
|
||||
- **本地**引用（`uses: ./...`）会相对于**源**仓库解析：即调用方工作流内容的来源仓库，而非消费方仓库。
|
||||
- **跨仓库**引用（`uses: owner/repo/...@ref`）会以**消费方仓库的**读取权限来解析。如果它指向一个私有仓库，请确保每个消费方仓库都能读取它，否则工作流会在那里失败。
|
||||
- **本地**引用（`uses: ./...` 或 `uses: $/...`）会相对于**源**仓库解析：即调用方工作流内容的来源仓库，而非消费方仓库。
|
||||
- **跨仓库**引用（`uses: owner/repo/...@ref` 或 `uses: self:owner/repo/...@ref`）会以**消费方仓库的**读取权限来解析。如果它指向一个私有仓库，请确保每个消费方仓库都能读取它，否则工作流会在那里失败。
|
||||
|
||||
可复用工作流可以放在源仓库的 `SCOPED_WORKFLOW_DIRS`（或 `WORKFLOW_DIRS`）之下。
|
||||
|
||||
|
||||
@@ -0,0 +1,126 @@
|
||||
---
|
||||
date: "2026-03-19T00:00:00+01:00"
|
||||
slug: "token-permissions"
|
||||
sidebar_position: 30
|
||||
---
|
||||
|
||||
# Actions Job令牌权限（`GITEA_TOKEN`）
|
||||
|
||||
每个Actions Job都会获得一个内置令牌（`GITEA_TOKEN`），可用于访问Gitea（通过HTTP(S)访问Git、API请求等）。
|
||||
本页面介绍Gitea如何决定该令牌可以执行哪些操作。
|
||||
|
||||
在工作流中，可以通过`${{ secrets.GITEA_TOKEN }}`使用该令牌。这些设置和`permissions:`仅影响`GITEA_TOKEN`（不影响个人访问令牌等其他密钥）。关于API调用，请参阅[API认证](../../development/api-usage.md#authentication)。
|
||||
|
||||
<a id="where-permissions-come-from"></a>
|
||||
## 权限来源
|
||||
|
||||
Gitea按以下顺序确定Job令牌的权限：
|
||||
|
||||
1. Job级别的`permissions:`（`jobs.<job_id>.permissions`）
|
||||
2. 工作流级别的`permissions:`（顶层）
|
||||
3. 设置中的默认权限（所有者或仓库）
|
||||
|
||||
然后，该结果会受到所配置的最大令牌权限的**限制**（见下文）。
|
||||
|
||||
<a id="supported-workflow-syntax"></a>
|
||||
## 支持的工作流语法
|
||||
|
||||
Gitea支持与GitHub Actions兼容的`permissions:`关键字。
|
||||
|
||||
<a id="scalar-values"></a>
|
||||
### 标量值
|
||||
|
||||
```yaml
|
||||
permissions: read-all # or: write-all
|
||||
```
|
||||
|
||||
<a id="scoped-mapping"></a>
|
||||
### 按权限范围映射
|
||||
|
||||
```yaml
|
||||
permissions:
|
||||
contents: read
|
||||
issues: write
|
||||
pull-requests: none
|
||||
```
|
||||
|
||||
每个权限范围的有效访问模式值为`read`、`write`和`none`。
|
||||
|
||||
<a id="supported-scopes"></a>
|
||||
### 支持的权限范围
|
||||
|
||||
- `contents`（适用于`code`和`releases`）
|
||||
- `code`
|
||||
- `releases`
|
||||
- `issues`
|
||||
- `pull-requests`
|
||||
- `actions`
|
||||
- `wiki`
|
||||
- `projects`
|
||||
- `packages`（如果目标功能支持）
|
||||
|
||||
如果同时指定了`contents`和更细粒度的权限范围（如`code`或`releases`），则该单元以更细粒度的权限范围为准。
|
||||
|
||||
<a id="compatibility-notes"></a>
|
||||
### 兼容性说明
|
||||
|
||||
Gitea支持GitHub Actions权限范围的一个子集。
|
||||
Gitea Actions目前不支持`statuses`、`checks`、`deployments`、`id-token`、`security-events`和`pages`等GitHub专有的权限范围。
|
||||
|
||||
Gitea还提供了一些仓库单元权限范围，它们在GitHub Actions中不作为独立的权限范围存在：
|
||||
|
||||
- `code`
|
||||
- `releases`
|
||||
- `wiki`
|
||||
- `projects`
|
||||
|
||||
<a id="default-permission-mode"></a>
|
||||
## 默认权限模式
|
||||
|
||||
如果工作流和Job都没有定义`permissions:`，Gitea会使用所配置的默认模式：
|
||||
|
||||
- **宽松**：对Job所属仓库的大多数单元拥有读写权限（向后兼容的默认值）。
|
||||
- **受限**：对Job所属仓库的`code`、`releases`和`packages`拥有只读权限，默认无权访问其他单元。
|
||||
|
||||
<a id="maximum-token-permissions-clamping"></a>
|
||||
## 最大令牌权限（限制）
|
||||
|
||||
您可以为每个仓库单元配置最大权限。
|
||||
Job的实际权限按以下方式计算：
|
||||
|
||||
`effective = min(requested, maximum)`
|
||||
|
||||
这意味着工作流可以降低Job的权限，但不能超过您配置的最大权限。
|
||||
如果未配置最大权限，则所有权限范围的最大权限默认为`write`。
|
||||
|
||||
<a id="where-to-configure"></a>
|
||||
## 配置位置
|
||||
|
||||
您可以在以下位置配置默认权限和最大权限：
|
||||
|
||||
- **用户/组织**：`Settings` → `Actions` → `General`
|
||||
- **仓库**：`Settings` → `Actions` → `General`
|
||||
- 对于组织中的仓库，可以遵循所有者级别的配置，也可以通过**覆盖所有者级别的配置**选择不遵循。
|
||||
|
||||
注意：仅在启用**仓库Actions**后，才会显示仓库级别的令牌权限设置。
|
||||
|
||||
<a id="fork-pull-requests"></a>
|
||||
## Fork拉取请求
|
||||
|
||||
出于安全考虑，由fork拉取请求触发的工作流始终只拥有仓库内容的只读权限，与工作流的`permissions:`或设置无关。
|
||||
|
||||
<a id="cross-repository-access"></a>
|
||||
## 跨仓库访问
|
||||
|
||||
默认情况下，`GITEA_TOKEN`只能访问：
|
||||
|
||||
- Job所属仓库（依据计算出的权限）
|
||||
- 公开仓库（只读）
|
||||
|
||||
默认拒绝访问其他私有仓库。
|
||||
用户或组织可以通过**设置 → Actions → 常规 → 跨仓库访问**，允许以只读方式访问选定的私有仓库。
|
||||
|
||||
私有仓库也可以通过**设置 → Actions → 常规**允许选定的协作所有者。
|
||||
这样，这些所有者的私有仓库便可读取当前私有仓库以供Actions使用，例如私有Actions和可复用工作流。
|
||||
|
||||
fork拉取请求的工作流永远不会获得对私有仓库的跨仓库访问权限，即使这些仓库已被列出。
|
||||
Reference in new issue
Block a user