diff --git a/docs/usage/actions/comparison.md b/docs/usage/actions/comparison.md index 134f1341..942d93f2 100644 --- a/docs/usage/actions/comparison.md +++ b/docs/usage/actions/comparison.md @@ -85,7 +85,7 @@ Service steps have no section of their own in the job log. ### Job token permissions (`permissions`) `permissions` and `jobs..permissions` control the `GITEA_TOKEN` permissions, clamped by the repository and owner settings and further restricted for fork pull requests and cross-repository access. -GitHub-only scopes like `statuses`, `checks`, `deployments`, `id-token`, `security-events` and `pages` are not supported, while Gitea adds `code`, `releases`, `wiki` and `projects`. +GitHub-only scopes like `statuses`, `checks`, `deployments`, `security-events` and `pages` are not supported, while Gitea adds `code`, `releases`, `wiki` and `projects`. `id-token` works like on GitHub, see [OpenID Connect](openid-connect.md). See [Actions job token permissions](token-permissions.md). ### Downloading actions diff --git a/docs/usage/actions/openid-connect.md b/docs/usage/actions/openid-connect.md new file mode 100644 index 00000000..80a605bb --- /dev/null +++ b/docs/usage/actions/openid-connect.md @@ -0,0 +1,60 @@ +--- +date: "2026-08-23T00:00:00+00:00" +slug: "openid-connect" +sidebar_position: 40 +--- + +# OpenID Connect + +Jobs can request short-lived OpenID Connect (OIDC) tokens to sign in to cloud providers and other services without storing long-lived secrets. The tokens use the GitHub Actions format, so actions like `aws-actions/configure-aws-credentials`, `google-github-actions/auth` and `azure/login` work unchanged. + +## Trusting Gitea + +Add Gitea as an OIDC identity provider in the service: + +- Issuer: `/api/actions/oidc` +- Audience: `/`, unless the workflow requests another one + +Then limit which workflows can sign in with a condition on the [`sub` claim](#claims). + +Gitea signs the tokens with a key it creates at `/jwt/actions_oidc.pem`. Instances behind a load balancer must share this file. + +## Requesting a token + +Grant the `id-token` permission to the workflow or job: + +```yaml +permissions: + id-token: write +``` + +Default permissions never include it, and jobs from fork pull requests never get it. Owners and repositories can disable it with their [maximum token permissions](token-permissions.md#maximum-token-permissions-clamping). + +Actions like the ones above request the token themselves. In a script, use `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`: + +```shell +curl --fail --silent --show-error \ + --header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \ + "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service" +``` + +The token is in the `value` field of the response and expires after five minutes. + +## Claims + +The `sub` claim names the owner and repository with their IDs, so a renamed or recreated repository cannot match an existing trust policy: + +```text +repo:@/@:ref: +repo:@/@:pull_request +``` + +The `pull_request` event uses the second form, all other events use the first, including `pull_request_target`. + +The other claims match GitHub's, like `repository`, `ref`, `sha`, `workflow_ref` and `job_workflow_ref`. The discovery document at `/api/actions/oidc/.well-known/openid-configuration` lists them all. + +Differences from GitHub Actions: + +- There is no `environment` claim. +- Pull request runs use `refs/pull//head` and its commit, not the merge ref and merge commit. +- `run_number` counts runs per repository, not per workflow. diff --git a/docs/usage/actions/token-permissions.md b/docs/usage/actions/token-permissions.md index ccb0029e..c6fc3b62 100644 --- a/docs/usage/actions/token-permissions.md +++ b/docs/usage/actions/token-permissions.md @@ -53,13 +53,14 @@ Valid access mode values for each scope are `read`, `write`, and `none`. - `wiki` - `projects` - `packages` (if supported by the target feature) +- `id-token` (`write` allows requesting [OpenID Connect tokens](openid-connect.md), `read` grants nothing) If you specify both `contents` and a more granular scope (like `code` or `releases`), the granular scope wins for that unit. ### Compatibility notes Gitea supports a subset of GitHub Actions permission scopes. -GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not currently supported by Gitea Actions. +GitHub-only scopes such as `statuses`, `checks`, `deployments`, `security-events`, and `pages` are not currently supported by Gitea Actions. Gitea also exposes repository-unit scopes that do not exist as separate scopes in GitHub Actions: @@ -75,15 +76,18 @@ If neither the workflow nor the job defines `permissions:`, Gitea uses the confi - **Permissive**: read and write permissions for most units in the job's repository (backwards-compatible default). - **Restricted**: read-only permissions for `code`, `releases`, and `packages` in the job's repository, and no access to other units by default. +Neither mode includes `id-token`. + ## Maximum token permissions (clamping) -You can configure a maximum permission per repository unit. +You can configure a maximum permission per repository unit and for `id-token`. The job's effective permissions are computed as: `effective = min(requested, maximum)` This means workflows can reduce permissions for a job, but cannot exceed your configured maximum. If you don't configure a maximum, the maximum defaults to `write` for all scopes. +Maximums saved before Gitea supported `id-token` deny it until you set it to `write`. ## Where to configure @@ -97,7 +101,7 @@ Note: Repository-level token permission settings are only shown once **Repositor ## Fork pull requests -For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings. +For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings. They also get no OpenID Connect tokens. ## Cross-repository access diff --git a/docs/usage/actions/variables.md b/docs/usage/actions/variables.md index ac157a64..e38652ff 100644 --- a/docs/usage/actions/variables.md +++ b/docs/usage/actions/variables.md @@ -64,8 +64,8 @@ These are used internally by the runner and actions. They are typically not need | Name | Description | Example | |---|---|---| | `ACTIONS_CACHE_URL` | URL for the actions cache service. | `http://192.168.1.10:8088/` | -| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when configured. | `***` | -| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when configured. | `https://gitea.com/login/oauth/access_token` | +| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when `id-token: write` is granted. | `***` | +| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when `id-token: write` is granted. | `https://gitea.com/api/actions/oidc/token?` | | `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.com` | | `ACTIONS_RUNTIME_TOKEN` | Authentication token for the Actions pipeline API. | `***` | | `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.com/api/actions_pipeline/` | diff --git a/i18n/zh-cn/docs/current/usage/actions/comparison.md b/i18n/zh-cn/docs/current/usage/actions/comparison.md index 5e994654..43d349a6 100644 --- a/i18n/zh-cn/docs/current/usage/actions/comparison.md +++ b/i18n/zh-cn/docs/current/usage/actions/comparison.md @@ -88,7 +88,7 @@ Gitea Actions旨在与GitHub Actions兼容，差异如下。 ### `permissions`和`jobs..permissions` `permissions`和`jobs..permissions`控制`GITEA_TOKEN`的权限，该权限受仓库和所有者设置的限制，并在fork拉取请求和跨仓库访问时受到进一步限制。 -不支持`statuses`、`checks`、`deployments`、`id-token`、`security-events`和`pages`等GitHub专有的权限范围，而Gitea额外提供了`code`、`releases`、`wiki`和`projects`。 +不支持`statuses`、`checks`、`deployments`、`security-events`和`pages`等GitHub专有的权限范围，而Gitea额外提供了`code`、`releases`、`wiki`和`projects`。`id-token`与GitHub相同，请参阅[OpenID Connect](openid-connect.md)。 请参阅[Actions Job令牌权限](token-permissions.md)。 ### 下载Actions diff --git a/i18n/zh-cn/docs/current/usage/actions/openid-connect.md b/i18n/zh-cn/docs/current/usage/actions/openid-connect.md new file mode 100644 index 00000000..d345e063 --- /dev/null +++ b/i18n/zh-cn/docs/current/usage/actions/openid-connect.md @@ -0,0 +1,63 @@ +--- +date: "2026-08-23T00:00:00+00:00" +slug: "openid-connect" +sidebar_position: 40 +--- + +# OpenID Connect + +Job可以请求短期有效的OpenID Connect（OIDC）令牌来登录云服务商和其他服务，无需存储长期有效的密钥。这些令牌采用GitHub Actions的格式，因此`aws-actions/configure-aws-credentials`、`google-github-actions/auth`和`azure/login`等Action无需修改即可使用。 + + +## 信任Gitea + +在服务中将Gitea添加为OIDC身份提供方： + +- Issuer：`/api/actions/oidc` +- Audience：`/`，除非工作流请求了其他值 + +然后通过[`sub`声明](#claims)上的条件限制哪些工作流可以登录。 + +Gitea使用其在`/jwt/actions_oidc.pem`创建的密钥签名令牌。负载均衡器后的多个实例必须共享此文件。 + + +## 请求令牌 + +为工作流或Job授予`id-token`权限： + +```yaml +permissions: + id-token: write +``` + +默认权限从不包含此权限，来自fork拉取请求的Job也永远无法获得。所有者和仓库可以通过[最大令牌权限](token-permissions.md#maximum-token-permissions-clamping)禁用它。 + +上述Action会自行请求令牌。在脚本中，请使用`ACTIONS_ID_TOKEN_REQUEST_URL`和`ACTIONS_ID_TOKEN_REQUEST_TOKEN`： + +```shell +curl --fail --silent --show-error \ + --header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \ + "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service" +``` + +令牌位于响应的`value`字段中，五分钟后过期。 + + +## 声明 + +`sub`声明包含所有者和仓库的名称及ID，因此重命名或重新创建的仓库无法匹配已有的信任策略： + +```text +repo:@/@:ref: +repo:@/@:pull_request +``` + +`pull_request`事件使用第二种格式，其他所有事件（包括`pull_request_target`）使用第一种。 + +其他声明与GitHub相同，例如`repository`、`ref`、`sha`、`workflow_ref`和`job_workflow_ref`。位于`/api/actions/oidc/.well-known/openid-configuration`的发现文档列出了所有声明。 + +与GitHub Actions的区别： + +- 没有`environment`声明。 +- 拉取请求的运行使用`refs/pull//head`及其提交，而不是合并引用和合并提交。 +- `run_number`按仓库计数，而不是按工作流计数。 diff --git a/i18n/zh-cn/docs/current/usage/actions/token-permissions.md b/i18n/zh-cn/docs/current/usage/actions/token-permissions.md index 4e295512..fef7aacf 100644 --- a/i18n/zh-cn/docs/current/usage/actions/token-permissions.md +++ b/i18n/zh-cn/docs/current/usage/actions/token-permissions.md @@ -58,6 +58,7 @@ permissions: - `wiki` - `projects` - `packages`（如果目标功能支持） +- `id-token`（`write`允许请求[OpenID Connect令牌](openid-connect.md)，`read`不授予任何权限） 如果同时指定了`contents`和更细粒度的权限范围（如`code`或`releases`），则该单元以更细粒度的权限范围为准。 @@ -65,7 +66,7 @@ permissions: ### 兼容性说明 Gitea支持GitHub Actions权限范围的一个子集。 -Gitea Actions目前不支持`statuses`、`checks`、`deployments`、`id-token`、`security-events`和`pages`等GitHub专有的权限范围。 +Gitea Actions目前不支持`statuses`、`checks`、`deployments`、`security-events`和`pages`等GitHub专有的权限范围。 Gitea还提供了一些仓库单元权限范围，它们在GitHub Actions中不作为独立的权限范围存在： @@ -82,16 +83,19 @@ Gitea还提供了一些仓库单元权限范围，它们在GitHub Actions中不 - **宽松**：对Job所属仓库的大多数单元拥有读写权限（向后兼容的默认值）。 - **受限**：对Job所属仓库的`code`、`releases`和`packages`拥有只读权限，默认无权访问其他单元。 +两种模式都不包含`id-token`。 + ## 最大令牌权限（限制） -您可以为每个仓库单元配置最大权限。 +您可以为每个仓库单元以及`id-token`配置最大权限。 Job的实际权限按以下方式计算： `effective = min(requested, maximum)` 这意味着工作流可以降低Job的权限，但不能超过您配置的最大权限。 如果未配置最大权限，则所有权限范围的最大权限默认为`write`。 +在Gitea支持`id-token`之前保存的最大权限会拒绝`id-token`，直到您将其设为`write`。 ## 配置位置 @@ -107,7 +111,7 @@ Job的实际权限按以下方式计算： ## Fork拉取请求 -出于安全考虑，由fork拉取请求触发的工作流始终只拥有仓库内容的只读权限，与工作流的`permissions:`或设置无关。 +出于安全考虑，由fork拉取请求触发的工作流始终只拥有仓库内容的只读权限，与工作流的`permissions:`或设置无关。这些Job也无法获取OpenID Connect令牌。 ## 跨仓库访问 diff --git a/i18n/zh-tw/docs/current/usage/actions/comparison.md b/i18n/zh-tw/docs/current/usage/actions/comparison.md index 09b1c3de..598000d2 100644 --- a/i18n/zh-tw/docs/current/usage/actions/comparison.md +++ b/i18n/zh-tw/docs/current/usage/actions/comparison.md @@ -88,7 +88,7 @@ Gitea Actions 旨在與 GitHub Actions 相容，差異如下。 ### `permissions`和`jobs..permissions` `permissions` 和 `jobs..permissions` 控制 `GITEA_TOKEN` 的權限，其權限受儲存庫與所有者設定的限制，對於來自 fork 的拉取請求和跨儲存庫存取還會進一步受限。 -不支援 `statuses`、`checks`、`deployments`、`id-token`、`security-events` 和 `pages` 等 GitHub 專屬範圍，而 Gitea 另外提供 `code`、`releases`、`wiki` 和 `projects`。 +不支援 `statuses`、`checks`、`deployments`、`security-events` 和 `pages` 等 GitHub 專屬範圍，而 Gitea 另外提供 `code`、`releases`、`wiki` 和 `projects`。`id-token` 與 GitHub 相同，請參閱 [OpenID Connect](openid-connect.md)。 請參閱 [Actions Job 令牌權限](token-permissions.md)。 ### 下載Actions diff --git a/i18n/zh-tw/docs/current/usage/actions/openid-connect.md b/i18n/zh-tw/docs/current/usage/actions/openid-connect.md new file mode 100644 index 00000000..877043d6 --- /dev/null +++ b/i18n/zh-tw/docs/current/usage/actions/openid-connect.md @@ -0,0 +1,63 @@ +--- +date: "2026-08-23T00:00:00+00:00" +slug: "openid-connect" +sidebar_position: 40 +--- + +# OpenID Connect + +Job 可以請求短期有效的 OpenID Connect（OIDC）令牌來登入雲端服務供應商和其他服務，不必儲存長期有效的密鑰。這些令牌採用 GitHub Actions 的格式，因此 `aws-actions/configure-aws-credentials`、`google-github-actions/auth` 和 `azure/login` 等 Action 不需修改即可使用。 + + +## 信任 Gitea + +在服務中將 Gitea 新增為 OIDC 身分提供者： + +- Issuer：`/api/actions/oidc` +- Audience：`/`，除非工作流請求了其他值 + +接著透過 [`sub` 宣告](#claims)上的條件，限制哪些工作流可以登入。 + +Gitea 使用它在 `/jwt/actions_oidc.pem` 建立的金鑰簽署令牌。位於負載平衡器後方的多個執行個體必須共用此檔案。 + + +## 請求令牌 + +為工作流或 Job 授予 `id-token` 權限： + +```yaml +permissions: + id-token: write +``` + +預設權限一律不包含此權限，來自 fork 的拉取請求的 Job 也永遠無法取得。所有者和儲存庫可以透過[最大令牌權限](token-permissions.md#maximum-token-permissions-clamping)停用它。 + +上述 Action 會自行請求令牌。在指令碼中，請使用 `ACTIONS_ID_TOKEN_REQUEST_URL` 和 `ACTIONS_ID_TOKEN_REQUEST_TOKEN`： + +```shell +curl --fail --silent --show-error \ + --header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \ + "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service" +``` + +令牌位於回應的 `value` 欄位中，五分鐘後過期。 + + +## 宣告 + +`sub` 宣告包含所有者和儲存庫的名稱及 ID，因此重新命名或重新建立的儲存庫無法符合既有的信任政策： + +```text +repo:@/@:ref: +repo:@/@:pull_request +``` + +`pull_request` 事件使用第二種格式，其他所有事件（包括 `pull_request_target`）使用第一種。 + +其他宣告與 GitHub 相同，例如 `repository`、`ref`、`sha`、`workflow_ref` 和 `job_workflow_ref`。位於 `/api/actions/oidc/.well-known/openid-configuration` 的探索文件列出了所有宣告。 + +與 GitHub Actions 的差異： + +- 沒有 `environment` 宣告。 +- 拉取請求的執行使用 `refs/pull//head` 及其提交，而不是合併參考和合併提交。 +- `run_number` 依儲存庫計數，而不是依工作流計數。 diff --git a/i18n/zh-tw/docs/current/usage/actions/token-permissions.md b/i18n/zh-tw/docs/current/usage/actions/token-permissions.md index 05565520..ad5b837d 100644 --- a/i18n/zh-tw/docs/current/usage/actions/token-permissions.md +++ b/i18n/zh-tw/docs/current/usage/actions/token-permissions.md @@ -58,6 +58,7 @@ permissions: - `wiki` - `projects` - `packages`（若目標功能支援） +- `id-token`（`write` 允許請求 [OpenID Connect 令牌](openid-connect.md)，`read` 不授予任何權限） 如果同時指定 `contents` 和更細的範圍（例如 `code` 或 `releases`），該單元以更細的範圍為準。 @@ -65,7 +66,7 @@ permissions: ### 相容性說明 Gitea 支援 GitHub Actions 權限範圍的一個子集。 -Gitea Actions 目前不支援 `statuses`、`checks`、`deployments`、`id-token`、`security-events` 和 `pages` 等 GitHub 專屬範圍。 +Gitea Actions 目前不支援 `statuses`、`checks`、`deployments`、`security-events` 和 `pages` 等 GitHub 專屬範圍。 Gitea 另外提供一些儲存庫單元範圍，它們在 GitHub Actions 中並不是獨立的範圍： @@ -82,16 +83,19 @@ Gitea 另外提供一些儲存庫單元範圍，它們在 GitHub Actions 中並 - **Permissive**（寬鬆）：對 Job 所屬儲存庫的大多數單元具有讀取和寫入權限（向下相容的預設值）。 - **受限**（Restricted）：對 Job 所屬儲存庫的 `code`、`releases` 和 `packages` 具有唯讀權限，預設無法存取其他單元。 +兩種模式都不包含 `id-token`。 + ## 最大令牌權限（限縮） -您可以為每個儲存庫單元設定最大權限。 +您可以為每個儲存庫單元以及 `id-token` 設定最大權限。 Job 的實際權限計算方式如下： `effective = min(requested, maximum)` 也就是說，工作流可以降低 Job 的權限，但不能超過您所設定的最大值。 如果未設定最大值，所有範圍的最大值預設為 `write`。 +在 Gitea 支援 `id-token` 之前儲存的最大值會拒絕 `id-token`，直到您將其設為 `write`。 ## 設定位置 @@ -107,7 +111,7 @@ Job 的實際權限計算方式如下： ## 來自 fork 的拉取請求 -基於安全考量，由來自 fork 的拉取請求觸發的工作流，對儲存庫內容一律只有唯讀權限，不受工作流 `permissions:` 或設定影響。 +基於安全考量，由來自 fork 的拉取請求觸發的工作流，對儲存庫內容一律只有唯讀權限，不受工作流 `permissions:` 或設定影響。這些 Job 也無法取得 OpenID Connect 令牌。 ## 跨儲存庫存取