mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-07 18:40:32 +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
@@ -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/)。
|
||||
請參閱[建立 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** > **General** 頁面，添加協作所有者。
|
||||
協作所有者的私有儲存庫可以存取目前儲存庫中的 Actions 和工作流。
|
||||
|
||||
若要在同一使用者或組織內共享，請改為在該使用者或組織的**設定** > **Actions** > **General** > **Cross-Repository Access** 中添加這些私有儲存庫。
|
||||
參見[跨儲存庫存取](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 會使用所設定的預設模式：
|
||||
|
||||
- **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 的拉取請求觸發的工作流，永遠無法取得對私有儲存庫的跨儲存庫存取權，即使這些儲存庫已列入清單也一樣。
|
||||
Reference in new issue
Block a user