mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-07 18:40:32 +00:00
silverwind
c4caf767ad
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]>
127 lines
4.3 KiB
Markdown
127 lines
4.3 KiB
Markdown
---
|
||
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拉取请求的工作流永远不会获得对私有仓库的跨仓库访问权限，即使这些仓库已被列出。
|