docs(actions): document OIDC workload identity (#526)

Document the OpenID Connect tokens that Gitea Actions jobs can request since https://github.com/go-gitea/gitea/pull/39052, so they can sign in to cloud providers without long-lived secrets.

- Add an OpenID Connect page covering how to trust Gitea, request a token and match its claims
- Document the `id-token` permission scope and its maximum
- Translate both for zh-cn and zh-tw, which still listed `id-token` as unsupported

Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/526
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Max P. <[email protected]>

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.<job_id>.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

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: `<ROOT_URL>/api/actions/oidc`
+- Audience: `<ROOT_URL>/<owner>`, 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 `<APP_DATA_PATH>/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:<owner>@<owner-id>/<repo>@<repo-id>:ref:<ref>
+repo:<owner>@<owner-id>/<repo>@<repo-id>: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 `<ROOT_URL>/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/<index>/head` and its commit, not the merge ref and merge commit.
+- `run_number` counts runs per repository, not per workflow.

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
 

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/` |