---
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拉取请求的工作流永远不会获得对私有仓库的跨仓库访问权限，即使这些仓库已被列出。