---
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 會使用所設定的預設模式：

- **Permissive**（寬鬆）：對 Job 所屬儲存庫的大多數單元具有讀取和寫入權限（向下相容的預設值）。
- **受限**（Restricted）：對 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`
  - 對於組織內的儲存庫，儲存庫可以沿用所有者層級的設定，或透過 **Override owner-level configuration** 選擇退出。

注意：只有在啟用**儲存庫 Actions** 後，才會顯示儲存庫層級的令牌權限設定。

<a id="fork-pull-requests"></a>
## 來自 fork 的拉取請求

基於安全考量，由來自 fork 的拉取請求觸發的工作流，對儲存庫內容一律只有唯讀權限，不受工作流 `permissions:` 或設定影響。

<a id="cross-repository-access"></a>
## 跨儲存庫存取

預設情況下，`GITEA_TOKEN` 只能存取：

- Job 所屬的儲存庫（依計算出的權限）
- 公開儲存庫（唯讀）

預設會拒絕存取其他私有儲存庫。
使用者或組織可以在**設定** > **Actions** > **General** > **Cross-Repository Access** 中，允許唯讀存取選定的私有儲存庫。

私有儲存庫也可以在**設定** > **Actions** > **General** 中允許選定的協作所有者。
這樣，這些所有者的私有儲存庫就能為了 Actions 用途讀取目前的私有儲存庫，例如私有 Actions 和可重複使用的工作流。

由來自 fork 的拉取請求觸發的工作流，永遠無法取得對私有儲存庫的跨儲存庫存取權，即使這些儲存庫已列入清單也一樣。