chore(deps): update dependencies

Update the latest api documents (#576 )
Automated update of static/swagger-latest.json and static/openapi3-latest.json from the gitea main branch, opened by the "update api spec files" scheduled workflow.  Preview: https://pr-576.docs-gitea-com.pages.dev Reviewed-on: https://gitea.com/gitea/docs/pulls/576 Reviewed-by: silverwind <[email protected]> Co-authored-by: Gitea Bot <[email protected]>
2026-11-13 21:33:44 +00:00 · 2026-10-06 00:05:15 +00:00 · 2026-10-05 10:59:51 +00:00 · 2026-10-05 10:59:31 +00:00 · 2026-10-02 20:58:18 +00:00 · 2026-10-02 17:11:53 +00:00
414 changed files with 116612 additions and 2706 deletions
@@ -2,7 +2,7 @@ name: update api spec files

 on:
  schedule:
-    - cron:  '0 */12 * * *' # every 12 hours on the hour
+    - cron: '0 3 * * 1' # every Monday at 03:00
  workflow_dispatch:

 env:
@@ -12,20 +12,30 @@ create_dir:
 clone_awesome: create_dir
 	git clone --branch=$(GITEA_AWESOME_BRANCH) $(GITEA_AWESOME_REMOTE) .tmp/upstream-awesome || true

+# the contributing guide moved to the gitea repository, the readme of
+# awesome-gitea still links to it with a relative path
+AWESOME_CONTRIBUTING_URL := https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md
+FIX_AWESOME_LINKS := sed 's|](contributing.md)|]($(AWESOME_CONTRIBUTING_URL))|'
+
 .PHONY: prepare-awesome-latest
 prepare-awesome-latest: clone_awesome
-	cp .tmp/upstream-awesome/README.md docs/awesome.md
+	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > docs/awesome.md

 .PHONY: prepare-awesome\#%
 prepare-awesome\#%:
-	cp .tmp/upstream-awesome/README.md  versioned_docs/version-1.$*/awesome.md
+	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > versioned_docs/version-1.$*/awesome.md
+
+# versions numbered without the 1. prefix, like 28
+.PHONY: prepare-awesome-v%
+prepare-awesome-v%:
+	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > versioned_docs/version-$*/awesome.md

 .PHONY: install
 install:
 	pnpm install

 .PHONY: prepare-docs
-prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27
+prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27 prepare-awesome-v28

 .PHONY: build
 build:
@@ -7,8 +7,8 @@ The site covers three products, all served from this repository:

 | Product | Content | Versions | Languages |
 | --- | --- | --- | --- |
-| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
-| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 1.27 … 1.22 | English |
+| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 28, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
+| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 28, 1.27 … 1.22 | English |
 | Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 3 … 0 | English |

 The enterprise documentation is built and deployed from its own repository and
@@ -79,7 +79,7 @@ make update-api-docs-latest  # refresh only the documents of gitea main
 ```

 The documents of gitea main are refreshed automatically: the `update api spec
-files` workflow runs every 12 hours and opens a pull request whenever gitea main
+files` workflow runs weekly and opens a pull request whenever gitea main
 changed. Released versions are updated by hand when a new gitea version is
 documented.

@@ -9,9 +9,9 @@

 # The version served at the root of a product is also reachable under its
 # number, which is what the release notes and old links use.
-/api/1.27/* /api/:splat 301
+/api/28/* /api/:splat 301
 /runner/3/* /runner/:splat 301
-/1.27/* /:splat 301
+/28/* /:splat 301

 # The local search plugin had a results page of its own, algolia docsearch is a
 # modal opened from any page.
@@ -0,0 +1,153 @@
+---
+date: "2026-09-12T00:00:00+00:00"
+slug: "audit-logging"
+sidebar_position: 41
+aliases:
+  - /en-us/audit-logging
+---
+
+# Audit Logging
+
+Gitea can record security-relevant events as structured audit records: each
+event has an `action`, `actor`, `scope`, `origin`, `message` and a JSON
+`metadata` blob. Recording is **off by default** and does not change request
+behavior when it is disabled.
+
+This is separate from the application, router and access logs described in
+[Logging Configuration](logging-config.md). Those logs are for operations and
+debugging. The audit log is a durable trail of who changed what.
+
+## Enable recording
+
+Set `[audit].RECORD_OUTPUT` to `database` in `app.ini` and restart Gitea:
+
+```ini
+[audit]
+RECORD_OUTPUT = database
+RETENTION_DAYS = 30
+```
+
+Invalid values of `RECORD_OUTPUT` fall back to `disabled`. See the
+[configuration cheat sheet](config-cheat-sheet.md#audit-audit) for every option.
+
+With Docker, the same settings can be applied as
+`GITEA__audit__RECORD_OUTPUT=database` and `GITEA__audit__RETENTION_DAYS=30`
+before Gitea writes them into `app.ini`.
+
+## View events
+
+The Audit Log pages are always available and still list any events that were
+stored earlier. When recording is disabled, the site administration page also
+shows a warning.
+
+| Audience | Location | Events shown |
+| --- | --- | --- |
+| Site administrators | Site administration → Monitoring → Audit Log (`/-/admin/monitor/audit_logs`) | Every event |
+| Signed-in users | User settings → Audit Log (`/user/settings/audit_logs`) | Events scoped to that user |
+| Organization owners | Organization settings → Audit Log (`/<org>/settings/audit_logs`) | Events scoped to that organization |
+| Repository administrators | Repository settings → Audit Log (`/<owner>/<repo>/settings/audit_logs`) | Events scoped to that repository |
+
+Each listing can be filtered by actor (username), action and origin, and sorted
+by timestamp. The actor filter does not match the
+[system actors](#actors-and-origins). Action filters accept an exact action or
+a family prefix such as `user:impersonation` or `repository:webhook`.
+
+Site administrators can download the current filtered result as JSONL
+(newline-delimited JSON) from **Export JSONL**. The file name is
+`gitea-audit-log-<timestamp>.jsonl`.
+
+## Event shape
+
+A recorded event contains:
+
+- **Action**: a stable, colon-separated identifier such as `repository:archive`
+  or `user:accesstoken:add`.
+- **Actor**: the user who performed the action. Actions taken while impersonating
+  a user record both the impersonator and the impersonated user.
+- **Actor credential**: when the request authenticated with a named credential,
+  the event stores its kind and id, never the secret. Typical values:
+  `access-token:<id>`, `oauth2-grant:<id>`, `gitea-actions:<task id>`,
+  `deploy-key:<key id>`.
+- **Scope**: the affected unit — `user`, `organization`, `repository` or
+  `system` (instance-wide).
+- **Origin**: how the action was initiated — `ui`, `api`, `cli` or `system`.
+- **Message**: a human-readable sentence rendered from a per-action template.
+- **Metadata**: extra fields that fill the message template (token name, new
+  visibility, and so on). Secrets and token values are not stored.
+- **IP address**: the client address of the request, when one exists. Events
+  triggered by a git push record the SSH client address for SSH pushes and
+  `127.0.0.1` for HTTP pushes.
+- **Timestamp**: when the event was recorded.
+
+An exported JSONL line looks like:
+
+```json
+{"action":"repository:archive","actor":{"type":"user","id":1,"name":"alice"},"scope":{"type":"repository","id":42,"name":"org/repo"},"message":"Archived repository org/repo.","time":"2026-09-12T11:00:00Z","ip_address":"203.0.113.10","origin":"ui"}
+```
+
+The `system:startup` message is kept stable across Gitea versions so operators
+can parse it: `System started [Gitea {version}]`.
+
+## Actors and origins
+
+Most web and API requests pick up the signed-in user automatically.
+
+Other entry points record a system actor:
+
+- `(gitea-cli)` for `gitea admin` commands and the `system:startup` and
+  `system:shutdown` events
+- `(gitea-auth-source)` for authentication-source syncs and for users an
+  authentication source creates or updates at sign-in
+- `gitea-actions` for Gitea Actions tasks
+- `(deploy-key)` for pushes with a deploy key
+- `(Cron)` for scheduled cron tasks
+- `Unknown` when no actor can be resolved
+
+Events of the `(gitea-cli)` actor use origin `cli`. Cron tasks, git hooks and
+other background work use origin `system`.
+
+## What is recorded
+
+Events cover security-relevant changes, grouped by action family:
+
+- **User**: create and delete, admin, restricted and active status, name,
+  password and password reset requests, visibility, emails, authentication
+  source, 2FA, WebAuthn, OpenID, external logins, access tokens, OAuth2
+  applications and grants, SSH/GPG/principal keys, secrets, webhooks,
+  impersonation, failed two-factor authentication
+- **Organization**: create and delete, name, visibility, members, teams,
+  OAuth2 applications, secrets, webhooks
+- **Repository**: create, fork, archive, delete, rename, visibility, transfer,
+  mirrors, signing verification, collaborators and teams, default branch,
+  branch and tag protection, deploy keys, webhooks, secrets
+- **Issues and pull requests**: create, delete, comments and merges
+- **Projects and wiki pages**: create, update and delete
+- **Actions**: enable, disable and dispatch a workflow
+- **System**: startup and shutdown, instance-wide webhooks, authentication
+  sources, instance-wide OAuth2 applications
+
+Recording never fails the request that triggered it. A write error is logged
+and the original operation continues.
+
+## What is not recorded
+
+- Read-only access such as browsing, clone, fetch or API GET requests
+- Logins, successful or failed, other than failed two-factor authentication
+  (use the [access log](logging-config.md) and
+  [Fail2ban Setup](fail2ban-setup.md) for authentication traffic)
+- Edits to issues and pull requests
+- Token or secret values
+- Which SSH key a real user pushed with (deploy keys are named; ordinary SSH
+  user pushes are not)
+
+## Retention
+
+`RETENTION_DAYS` (default **30**) is the age after which recorded events are
+eligible for deletion. Set it to `0` to keep events forever.
+
+Cleanup is performed by the `cron.delete_old_audit_events` task (`SCHEDULE`
+defaults to `@every 24h`, `OLDER_THAN` defaults to `[audit].RETENTION_DAYS`).
+The task is registered only while `RECORD_OUTPUT` records events **and**
+`RETENTION_DAYS` is greater than `0`. Turning recording off therefore also
+stops pruning; existing rows stay until you delete them or turn recording back
+on.
@@ -348,8 +348,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `PROXY_PROTOCOL_TLS_BRIDGING`: **false**: When protocol is https, expect PROXY protocol headers after TLS negotiation.
 - `PROXY_PROTOCOL_HEADER_TIMEOUT`: **5s**: Timeout to wait for PROXY protocol header (set to 0 to have no timeout)
 - `PROXY_PROTOCOL_ACCEPT_UNKNOWN`: **false**: Accept PROXY protocol headers with Unknown type.
- `DOMAIN`: **localhost**: Domain name of this server.
- `ROOT_URL`: **`{PROTOCOL}://{DOMAIN}:{HTTP_PORT}/`**:
+- `ROOT_URL`: **`{PROTOCOL}://localhost:{HTTP_PORT}/`**:
   Overwrite the automatically generated public URL.
   This is useful if the internal and the external URL don't match (e.g. behind a reverse proxy).
 - `PUBLIC_URL_DETECTION`: **`auto`**: Controls how to generate the public URL. Most instances should use the "auto" behavior,
@@ -404,7 +403,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
  If it is set to `(DOER_USERNAME)`, it will use current signed-in user's username.
  This option is only for some advanced users who have configured their SSH reverse-proxy and need to use different usernames for git SSH clone.
  Most users should just leave it blank and/or modify the `BUILTIN_SSH_SERVER_USER`.
- `SSH_DOMAIN`: **`{DOMAIN}`**: Domain name of this server, used for displayed clone URL.
+- `SSH_DOMAIN`: **_empty_**: Domain name to be exposed in clone URL, defaults to the domain part of ROOT_URL
 - `SSH_PORT`: **22**: SSH port displayed in clone URL. If you need a different "SSH clone port" from the real "SSH listen port", set the SSH_LISTEN_PORT separately.
 - `SSH_LISTEN_HOST`: **0.0.0.0**: Listen address for the built-in SSH server.
 - `SSH_LISTEN_PORT`: **`{SSH_PORT}`**: Port for the built-in SSH server.
@@ -420,7 +419,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `SSH_SERVER_CIPHERS`: **`chacha20-poly1305@openssh.com`, `aes128-ctr`, `aes192-ctr`, `aes256-ctr`, `aes128-gcm@openssh.com`, `aes256-gcm@openssh.com`**: For the built-in SSH server, choose the ciphers to support for SSH connections, for system SSH this setting has no effect.
 - `SSH_SERVER_KEY_EXCHANGES`: **curve25519-sha256, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group14-sha256, diffie-hellman-group14-sha1**: For the built-in SSH server, choose the key exchange algorithms to support for SSH connections, for system SSH this setting has no effect.
 - `SSH_SERVER_MACS`: **`hmac-sha2-256-etm@openssh.com`, `hmac-sha2-256`, `hmac-sha1`**: For the built-in SSH server, choose the MACs to support for SSH connections, for system SSH this setting has no effect
- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gogs.rsa**: For the built-in SSH server, choose the keypairs to offer as the host key. The private key should be at `SSH_SERVER_HOST_KEY` and the public `SSH_SERVER_HOST_KEY.pub`. Relative paths are made absolute relative to the `APP_DATA_PATH`. If no key exists a 4096 bit RSA key will be created for you.
+- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gitea.ed25519, ssh/gitea.ecdsa, ssh/gogs.rsa**: For the built-in SSH server, choose the keypairs to offer as the host key. The private key should be at `SSH_SERVER_HOST_KEY` and the public `SSH_SERVER_HOST_KEY.pub`. Relative paths are made absolute relative to the `APP_DATA_PATH`. If none of the keys exist, a 4096 bit RSA, a 256 bit ECDSA and an ED25519 key will be created for you.
 - `SSH_KEY_TEST_PATH`: **/tmp**: Directory to create temporary files in when testing public keys using ssh-keygen, default is the system temporary directory.
 - `SSH_KEYGEN_PATH`: **_empty_**: Use `ssh-keygen` to parse public SSH keys. The value is passed to the shell. By default, Gitea does the parsing itself.
 - `SSH_EXPOSE_ANONYMOUS`: **false**: Enable exposure of SSH clone URL to anonymous visitors, default is false.
@@ -587,8 +586,7 @@ And the following unique queues:
 - `SECRET_KEY`: **\<random at every install\>**: Global secret key. This key is VERY IMPORTANT, if you lost it, the data encrypted by it (like 2FA secret) can't be decrypted anymore.
 - `SECRET_KEY_URI`: **_empty_**: Instead of defining SECRET_KEY, this option can be used to use the key stored in a file (example value: `file:/etc/gitea/secret_key`). It shouldn't be lost like SECRET_KEY.
 - `LOGIN_REMEMBER_DAYS`: **31**: How long to remember that a user is logged in before requiring relogin (in days).
- `COOKIE_REMEMBER_NAME`: **gitea\_incredible**: Name of cookie used to store authentication
-   information.
+- `COOKIE_REMEMBER_NAME`: **gitea\_remember**: Name of cookie used to store authentication information.
 - `REVERSE_PROXY_LOGOUT_REDIRECT`: **_empty_**: URL or relative path to redirect users to after logout when authentication is handled by a reverse proxy or SSO. For example: `/my-sso/logout?return=/my-sso/home`.
 - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: Header name for reverse proxy
   authentication.
@@ -647,14 +645,29 @@ And the following unique queues:
 - `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: Cache successful token hashes. API tokens are stored in the DB as pbkdf2 hashes however, this means that there is a potentially significant hashing load when there are multiple API operations. This cache will store the successfully hashed tokens in a LRU cache as a balance between performance and security.
 - `DISABLE_QUERY_AUTH_TOKEN`: **false**: Reject API tokens sent in URL query string (Accept Header-based API tokens only). This setting will default to `true` in Gitea 1.23 and be deprecated in Gitea 1.24.
 - `TWO_FACTOR_AUTH`: **_empty_**: set to enforced to enforce two factor authentication. Only available in Gitea 1.24 and later.
- `ALLOWED_HOST_LIST`: **external**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list.
+- `EGRESS_MODE`: **lax**: Egress mode toggles between strictness of outgoing requests:
+  - `lax` requires addresses to be allowed only if they are in private ranges, it allows all public ones
+  - `strict` requires an explicit allow of all addresses
+- `ALLOWED_HOST_LIST`: **_empty_**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list, eg: `192.168.1.0/24:3000`, `[2001:db8::/32]:9090`, `*.mydomain.com:[80|443]`
  - Built-in networks:
    - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6, localhost is included.
-    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7). Also called LAN/Intranet.
-    - `external`: A valid non-private unicast IP, you can access all hosts on public internet.
-    - `*`: All hosts are allowed.
-  - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6
-  - Wildcard hosts: `*.mydomain.com`, `192.168.100.*`
+    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), RFC 4193 (FC00::/7) and RFC 6598 CGNAT (100.64.0.0/10). Also called LAN/Intranet.
+  - CIDR list: `1.2.3.0/8`, `2001:db8::/32`, and with a port `[2001:db8::/32]:9090` (IPv6 addresses and CIDRs need brackets when a port is given)
+  - Host matching: `example.com` matches the host and any subdomain, dot-anchored so `notexample.com` never matches. `*.example.com` and `.example.com` match only subdomains, the apex itself is excluded. IDN names must be given as punycode.
+  - All addresses can have ports specified. Accepted port specs:
+    - a single port: `192.168.1.0/24:3000`
+    - a range, both bounds inclusive: `*.mydomain.com:3000-3010`
+    - a bracketed set of ports and ranges, `|` separated: `*.mydomain.com:[80|443|3000-3010]`
+    - all ports: `*.mydomain.com:*`
+  - A portless entry covers all ports in `lax` mode, only 80 and 443 in `strict` mode
+  - Port specs apply only where the list is consulted: in `lax` mode that is private, loopback and CGNAT targets alone, public targets are allowed on every port whatever the list says. In `strict` mode every target is checked, so ports restrict public hosts too.
+  - Reserved addresses like link-local and cloud metadata are denied
+  - This list is enforced on direct connections only. When an HTTP proxy is configured, restricting the proxied target is the proxy server's responsibility.
+
+## Audit (`audit`)
+
+- `RECORD_OUTPUT`: **disabled**: Where security-relevant events are recorded. `disabled` records nothing. `database` writes events to the `audit_event` table and shows them in the admin, organization, repository and user settings. Invalid values fall back to `disabled`. See [Audit Logging](audit-logging.md).
+- `RETENTION_DAYS`: **30**: Days to keep recorded events. `0` keeps them forever. Pruning is done by `cron.delete_old_audit_events`. That task is only registered while `RECORD_OUTPUT` records events and `RETENTION_DAYS` is greater than `0`.

 ## Camo (`camo`)

@@ -665,8 +678,8 @@ And the following unique queues:

 ## OpenID (`openid`)

- `ENABLE_OPENID_SIGNIN`: **true**: Allow authentication in via OpenID.
- `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION**: Allow registering via OpenID.
+- `ENABLE_OPENID_SIGNIN`: **false**: Allow authentication in via OpenID.
+- `ENABLE_OPENID_SIGNUP`: **false**: Allow registering via OpenID.
 - `WHITELISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
   OpenID URI's to permit.
 - `BLACKLISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
@@ -701,7 +714,7 @@ And the following unique queues:
   Requires `Mailer` to be enabled.
 - `REGISTER_MANUAL_CONFIRM`: **false**: Enable this to manually confirm new registrations.
   Requires `REGISTER_EMAIL_CONFIRM` to be disabled.
- `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create
+- `DISABLE_REGISTRATION`: **true**: Disable registration, after which only admin can create
   accounts for users.
 - `REQUIRE_EXTERNAL_REGISTRATION_PASSWORD`: **false**: Enable this to force externally created
   accounts (via GitHub, OpenID Connect, etc) to create a password.
@@ -760,7 +773,7 @@ And the following unique queues:
 - `DEFAULT_ALLOW_ONLY_CONTRIBUTORS_TO_TRACK_TIME`: **true**: Only allow users with write permissions to track time.
 - `EMAIL_DOMAIN_ALLOWLIST`: **_empty_**: If non-empty, comma separated list of domain names that can only be used to register on this instance, wildcard is supported.
 - `EMAIL_DOMAIN_BLOCKLIST`: **_empty_**: If non-empty, comma separated list of domain names that cannot be used to register on this instance, wildcard is supported.
- `SHOW_REGISTRATION_BUTTON`: **! DISABLE\_REGISTRATION**: Show Registration Button
+- `SHOW_REGISTRATION_BUTTON`: **false**: Show Registration button, defaults to true only if both DISABLE_REGISTRATION and ALLOW_ONLY_EXTERNAL_REGISTRATION are false
 - `SHOW_MILESTONES_DASHBOARD_PAGE`: **true** Enable this to show the milestones dashboard page - a view of all the user's milestones
 - `AUTO_WATCH_NEW_REPOS`: **true**: Enable this to let all organisation users watch new repos when they are created
 - `AUTO_WATCH_ON_CHANGES`: **false**: Enable this to make users watch a repository after their first commit to it
@@ -770,8 +783,7 @@ And the following unique queues:
 - `DEFAULT_ORG_MEMBER_VISIBLE`: **false** True will make the membership of the users visible when added to the organisation.
 - `ALLOW_ONLY_INTERNAL_REGISTRATION`: **false** Set to true to force registration only via Gitea.
 - `ALLOW_ONLY_EXTERNAL_REGISTRATION`: **false** Set to true to force registration only using third-party services.
- `NO_REPLY_ADDRESS`: **noreply.DOMAIN** Value for the domain part of the user's email address in the Git log if user has set KeepEmailPrivate to true. DOMAIN resolves to the value in server.DOMAIN.
-  The user's email will be replaced with a concatenation of the user name in lower case, "@" and NO_REPLY_ADDRESS.
+- `NO_REPLY_ADDRESS`: **_empty_**: Value for the domain part of the user's email address in the git log if user has set KeepEmailPrivate to true. The user's email will be replaced with a concatenation of the user name in lower case, "@" and NO_REPLY_ADDRESS. Default value is "noreply." + the domain part of ROOT_URL
 - `USER_DELETE_WITH_COMMENTS_MAX_TIME`: **0** Minimum amount of time a user must exist before comments are kept when the user is deleted.
 - `VALID_SITE_URL_SCHEMES`: **http, https**: Valid site url schemes for user profiles

@@ -804,9 +816,11 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
 - `DELIVER_TIMEOUT`: **5**: Delivery timeout (sec) for shooting webhooks.
 - `SKIP_TLS_VERIFY`: **false**: Allow insecure certification.
 - `PAGING_NUM`: **10**: Number of webhook history events that are shown in one page.
- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting.
+- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting.
 - `PROXY_HOSTS`: **_empty_`**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts. If not given, will use global proxy setting.

+When a proxy is configured, Gitea does not enforce `[security]` `ALLOWED_HOST_LIST` on the proxied target, the proxy server is expected to restrict it.
+
 ## Mailer (`mailer`)

 :::warning
@@ -881,27 +895,27 @@ In-Reply-To =

 ## Cache (`cache`)

- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, `twoqueue` or `memcache`. (`twoqueue` represents a size limited LRU cache.)
- `INTERVAL`: **60**: Garbage Collection interval (sec), for memory and twoqueue cache only.
- `HOST`: **_empty_**: Connection string for `redis` and `memcache`. For `twoqueue` sets configuration for the queue. If left empty while `ADAPTER` is `redis`, it falls back to [redis/CONN_STR](#redis-redis) when that is set.
+- `ADAPTER`: **memory**: Either `memory`, `redis`, `memcache`, or `twoqueue`.
+- `INTERVAL`: **60**: For `memory` and `twoqueue`, GC interval in seconds.
+- `HOST`: **_empty_**: For `redis` and `memcache`, connection host address. For `twoqueue` sets configuration for the queue. If left empty while `ADAPTER` is `redis`, it falls back to [redis/CONN_STR](#redis-redis) when that is set.
  - Redis: `redis://:[email protected]:6379/0?pool_size=100&idle_timeout=180s` (See [queue/CONN_STR](#queue-queue-and-queue) for information on additional supported connection types)
    - For a Redis cluster: `redis+cluster://:[email protected]:6379/0?pool_size=100&idle_timeout=180s`
    - For a Redis sentinel: `redis+sentinel://:macaron@sentinel0:26379,sentinel1:26379,sentinel2:26379/0?pool_size=100&idle_timeout=180s&master_name=mymaster`
-  - Memcache: `127.0.0.1:9090;127.0.0.1:9091`
+  - Memcache: `127.0.0.1:11211`
  - TwoQueue LRU cache: `{"size":50000,"recent_ratio":0.25,"ghost_ratio":0.5}` or `50000` representing the maximum number of objects stored in the cache.
- `ITEM_TTL`: **16h**: Time to keep items in cache if not used, Setting it to -1 disables caching.
+- `ITEM_TTL`: **16h**: Time to keep items in cache if not used. Setting it to -1 disables caching.

 ## Cache - LastCommitCache settings (`cache.last_commit`)

- `ITEM_TTL`: **8760h**: Time to keep items in cache if not used, Setting it to -1 disables caching.
+- `ITEM_TTL`: **8760h**: Time to keep items in cache if not used. Setting it to -1 disables caching.
 - `COMMITS_COUNT`: **1000**: Only enable the cache when repository's commits count great than.

 ## Session (`session`)

- `PROVIDER`: **memory**: Session engine provider \[memory, file, redis, db, mysql, couchbase, memcache, postgres\]. Setting `db` will reuse the configuration in `[database]`
+- `PROVIDER`: **file**: Either "memory", "file", "redis" or "db", default is "file". "db" will reuse the configuration in `[database]`
 - `PROVIDER_CONFIG`: **data/sessions**: For file, the root path; for db, empty (database config will be used); for others, the connection string. Relative paths will be made absolute against _`AppWorkPath`_. For the `redis` provider, if left empty it falls back to [redis/CONN_STR](#redis-redis) when that is set.
 - `COOKIE_SECURE`:**_empty_**: `true` or `false`. Enable this to force using HTTPS for all session access. If not set, it defaults to `true` if the ROOT_URL is an HTTPS URL.
- `COOKIE_NAME`: **i\_like\_gitea**: The name of the cookie used for the session ID.
+- `COOKIE_NAME`: **gitea\_session**: Session cookie name
 - `GC_INTERVAL_TIME`: **86400**: GC interval in seconds.
 - `SESSION_LIFE_TIME`: **86400**: Session life time in seconds, default is 86400 (1 day)
 - `DOMAIN`: **_empty_**: Sets the cookie Domain
@@ -928,7 +942,7 @@ In-Reply-To =
  - none = no avatar will be displayed
  - random = random avatar will be generated
  - image = default image will be used (which is set in `REPOSITORY_AVATAR_FALLBACK_IMAGE`)
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: Image used as default repository avatar (if `REPOSITORY_AVATAR_FALLBACK` is set to image and none was uploaded)
+- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **_empty_**: Image used as default repository avatar (if `REPOSITORY_AVATAR_FALLBACK` is set to image and none was uploaded). The value is used as-is, without prepending the sub-path of `ROOT_URL`. Empty uses Gitea's builtin repository avatar.

 ## Project (`project`)

@@ -1047,7 +1061,7 @@ Release attachment has its own config options in `[repository.release]` section.
 - `ENABLED`: **true**: Enable running Update mirrors task periodically.
 - `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
 - `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
 - `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).

@@ -1056,7 +1070,7 @@ Release attachment has its own config options in `[repository.release]` section.
 - `ENABLED`: **true**: Enable running repository health check task periodically.
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
 - `RUN_AT_START`: **false**: Run repository health check task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
 - `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck

@@ -1065,12 +1079,13 @@ Release attachment has its own config options in `[repository.release]` section.
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
 - `ENABLED`: **true**: Enable running repository statistics check task periodically.
 - `RUN_AT_START`: **true**: Run repository statistics check task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.

 #### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)

 - `ENABLED`: **true**: Enable cleanup hook_task job.
 - `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED).
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@midnight**: Cron syntax for cleaning hook_task table.
 - `CLEANUP_TYPE` **OlderThan** OlderThan or PerWebhook Method to cleanup hook_task, either by age (i.e. how long ago hook_task record was delivered) or by the number to keep per webhook (i.e. keep most recent x deliveries per webhook).
 - `OLDER_THAN`: **168h**: If CLEANUP_TYPE is set to OlderThan, then any delivered hook_task records older than this expression will be deleted.
@@ -1090,7 +1105,7 @@ Update migrated repositories' issues and comments' posterid, it will always atte

 - `ENABLED`: **true**: Enable update migration poster id job.
 - `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.

 #### Cron - Sync External Users (`cron.sync_external_users`)
@@ -1099,7 +1114,7 @@ Synchronize external user data (only LDAP user synchronization is supported)

 - `ENABLED`: **true**: Enable synchronize external user data job
 - `RUN_AT_START`: **false**: Synchronize external user data when starting server
- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
 - `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.

@@ -1107,12 +1122,14 @@ Synchronize external user data (only LDAP user synchronization is supported)

 - `ENABLED`: **true**: Enable cleanup expired actions assets job.
 - `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@midnight** : Cron syntax for the job.

 #### Cron - Delete Old Action Runs (`cron.cleanup_action_runs`)

 - `ENABLED`: **true**: Enable the job deleting action runs older than `RUN_RETENTION_DAYS`. Deletes nothing while that is 0.
 - `RUN_AT_START`: **false**: Run job at start time (if ENABLED).
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@midnight**: Cron syntax for the job.

 #### Cron - Cleanup Deleted Branches (`cron.deleted_branches_cleanup`)
@@ -1198,11 +1215,21 @@ Synchronize external user data (only LDAP user synchronization is supported)
 - `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
 - `OLDER_THAN`: **8760h**: any action older than this expression will be deleted from database, suggest using `8760h` (1 year) because that's the max length of heatmap.

+#### Cron - Delete old audit events (`cron.delete_old_audit_events`)
+
+Deletes audit events older than the retention period. The task is only registered when `[audit].RECORD_OUTPUT` records events and `[audit].RETENTION_DAYS` is greater than `0`. See [Audit Logging](audit-logging.md).
+
+- `ENABLED`: **true**: Enable service.
+- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
+- `OLDER_THAN`: **720h**: any audit event older than this expression will be deleted from the database. Defaults to `[audit].RETENTION_DAYS`.
+
 #### Cron -  Check for new Gitea versions (`cron.update_checker`)

 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a work, e.g. `@every 168h`.
 - `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: the endpoint that Gitea will check for newer versions

@@ -1210,7 +1237,7 @@ Synchronize external user data (only LDAP user synchronization is supported)

 - `ENABLED`: **false**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
 - `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.

@@ -1218,6 +1245,7 @@ Synchronize external user data (only LDAP user synchronization is supported)

 - `ENABLED`: **false**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
 - `OLDER_THAN`: **168h**: Only attempt to garbage collect LFSMetaObjects older than this (default 7 days)
 - `LAST_UPDATED_MORE_THAN_AGO`: **72h**: Only attempt to garbage collect LFSMetaObjects that have not been attempted to be garbage collected for this long (default 3 days)
@@ -1230,35 +1258,35 @@ Synchronize external user data (only LDAP user synchronization is supported)

 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@annually**: Cron syntax to set how often to rebuild

 #### Cron - Stop running tasks which haven't been updated for a long time (`cron.stop_zombie_tasks`)

 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 5m**: Cron syntax to set how often tasks to run the check

 #### Cron - Stop running tasks which have running status and continuous updates but don't end for a long time (`cron.stop_endless_tasks`)

 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 30m**: Cron syntax to set how often to run the check.

 #### Cron - Cancel jobs which haven't been picked up for a long time (`cron.cancel_abandoned_jobs`)

 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 6h**: Cron syntax to set how often to run the check.

 #### Cron - Start cron based actions (`cron.start_schedule_tasks`)

 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 1m**: Cron syntax to set how often to schedule tasks

 ## Git (`git`)
@@ -1410,11 +1438,13 @@ in this mapping or the filetype using heuristics.

 - `MAX_ATTEMPTS`: **3**: Max attempts per http/https request on migrations.
 - `RETRY_BACKOFF`: **3**: Backoff time per http/https request retry (seconds)
- `ALLOWED_DOMAINS`: **_empty_**: Domains allowlist for migrating repositories, default is blank. It means external hosts will be allowed. Multiple domains could be separated by commas. Wildcard is supported: `github.com, *.github.com`.
- `BLOCKED_DOMAINS`: **_empty_**: Domains blocklist for migrating repositories, default is blank. Multiple domains could be separated by commas. When `ALLOWED_DOMAINS` is not blank, this option has a higher priority to deny domains. Wildcard is supported.
- `ALLOW_LOCALNETWORKS`: **false**: Allow private addresses defined by RFC 1918, RFC 1122, RFC 4632 and RFC 4291. If a domain is allowed by `ALLOWED_DOMAINS`, this option will be ignored.
+- `EGRESS_MODE`: **lax**: Mode toggles between strictness of scanning outgoing requests, same format as `EGRESS_MODE` in [`security`](#security-security).
+- `ALLOWED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may call, same format as `ALLOWED_HOST_LIST` in [`security`](#security-security). Private and loopback addresses need a builtin or CIDR entry. When unset, the deprecated `ALLOWED_DOMAINS` entries apply on every port with `strict` as the default mode, and the deprecated `ALLOW_LOCALNETWORKS` adds `private, loopback`.
+- `BLOCKED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may never call, portless entries cover all ports.
 - `SKIP_TLS_VERIFY`: **false**: Allow skip tls verify

+These lists are enforced on direct connections only. When a proxy is configured (`[proxy]`, `[git.config]` `http.proxy` or the environment), restricting the proxied target is the proxy server's responsibility.
+
 ## Federation (`federation`)

 - `ENABLED`: **false**: Enable/Disable federation capabilities
@@ -1649,14 +1679,16 @@ is `data/repo-archive` and the default of `MINIO_BASE_PATH` is `repo-archive/`.
 ## Proxy (`proxy`)

 - `PROXY_ENABLED`: **false**: Enable the proxy if true, all requests to external via HTTP will be affected, if false, no proxy will be used even environment http_proxy/https_proxy
- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy
+- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy
 - `PROXY_HOSTS`: **_empty_**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts.

+When a proxy is configured, Gitea does not enforce the egress lists (`[security]`, `[migrations]`) on the proxied target, the proxy server is expected to restrict it.
+
 i.e.

 ```ini
 PROXY_ENABLED = true
-PROXY_URL = socks://127.0.0.1:1080
+PROXY_URL = socks5://127.0.0.1:1080
 PROXY_HOSTS = *.github.com
 ```

@@ -1675,6 +1707,7 @@ PROXY_HOSTS = *.github.com
 - `ARTIFACT_RETENTION_DAYS`: **90**: Days to keep artifacts. Old artifacts will be deleted after this period. 0 means keep forever.
  Changes only apply to newly uploaded artifacts, existing ones keep the expiry stored when they were uploaded.
  Artifacts could have their own retention periods by setting the `retention-days` option in `actions/upload-artifact` step.
+- `ARTIFACT_PREVIEW_MAX_SIZE`: **10485760**: Maximum total artifact size in bytes that can be browsed or previewed in the web UI. Set to `0` to disable artifact previews or `-1` for no limit. Individual files are also limited by [`MAX_DISPLAY_FILE_SIZE`](#ui-ui).
 - `RUN_RETENTION_DAYS`: **400**: Days to keep completed runs. Old runs and everything under them will be deleted after this period. 0 means keep forever.
 - `ZOMBIE_TASK_TIMEOUT`: **10m**: Timeout to stop the task which have running status, but haven't been updated for a long time
 - `ENDLESS_TASK_TIMEOUT`: **3h**: Timeout to stop the tasks which have running status and continuous updates, but don't end for a long time
@@ -1684,18 +1717,9 @@ PROXY_HOSTS = *.github.com
 - `SCOPED_WORKFLOW_DIRS`: **.gitea/scoped_workflows**: Comma-separated list of directories holding [scoped workflows](usage/actions/scoped-workflows.md) (workflows defined in a central source repository that run on other repositories). Must not overlap with `WORKFLOW_DIRS`. Leave empty so no directory is scanned for scoped workflows; none are found or run.
 - `MAX_RERUN_ATTEMPTS`: **50**: Maximum number of attempts a single workflow run can have (initial run + reruns). Defaults value is 50. Set any positive value that fits your workflow needs.

-`DEFAULT_ACTIONS_URL` indicates where the Gitea Actions runners should find the actions with relative path.
-For example, `uses: actions/checkout@v4` means `https://github.com/actions/checkout@v4` since the value of `DEFAULT_ACTIONS_URL` is `github`.
-And it can be changed to `self` to make it `root_url_of_your_gitea/actions/checkout@v4`.
-
-Please note that using `self` is not recommended for most cases, as it could make names globally ambiguous.
-Additionally, it requires you to mirror all the actions you need to your Gitea instance, which may not be worth it.
-Therefore, please use `self` only if you understand what you are doing.
-
-In earlier versions (`<= 1.19`), `DEFAULT_ACTIONS_URL` could be set to any custom URLs like `https://gitea.com` or `http://your-git-server,https://gitea.com`, and the default value was `https://gitea.com`.
-However, later updates removed those options, and now the only options are `github` and `self`, with the default value being `github`.
-However, if you want to use actions from other git server, you can use a complete URL in `uses` field, it's supported by Gitea (but not GitHub).
-Like `uses: https://gitea.com/actions/checkout@v4` or `uses: http://your-git-server/actions/checkout@v4`.
+`DEFAULT_ACTIONS_URL` sets where runners download actions without a host.
+With `github`, `uses: actions/checkout@v4` resolves to `https://github.com/actions/checkout@v4`, with `self` to `<ROOT_URL>/actions/checkout@v4`.
+`self` requires mirroring every action you use to your instance, so prefer naming the host per action instead: `uses: self:owner/repo@ref` for your instance, or a full URL like `uses: https://gitea.com/actions/checkout@v4` for any other host.

 ## Other (`other`)

@@ -86,6 +86,21 @@ PROTOCOL       = smtps
 Note that you'll need to create and use an [App password](https://support.google.com/accounts/answer/185833?hl=en) by enabling 2FA on your Google
 account. You won't be able to use your Google account password directly.

+An app password is the only option: Google
+[turned off access for apps that sign in with a password alone](https://workspaceupdates.googleblog.com/2023/09/winding-down-google-sync-and-less-secure-apps-support.html)
+in 2024 and asks applications to use OAuth instead, which Gitea's mailer does
+not implement — it authenticates with `CRAM-MD5`, `PLAIN` or `LOGIN`.
+
+Two things to keep in mind:
+
+- app passwords require 2-step verification on the account, and a Google
+  Workspace administrator can switch them off for the whole domain. If they are
+  not available, send through the
+  [Workspace SMTP relay service](https://support.google.com/a/answer/2956491)
+  or through another mail provider.
+- port `587` works as well, with `SMTP_PORT = 587` and
+  `PROTOCOL = smtp+starttls`.
+
 ### ProtonMail

 This feature is currently only available for select Proton for Business customers and those with Visionary and Family plans with custom domain addresses. See [ProtonMail's SMTP documentation](https://proton.me/support/smtp-submission) for more information. This limitation can be circumvented by using the ProtonMail Bridge application.
@@ -41,3 +41,24 @@ client that causes SSH transfers to hang: https://github.com/git-lfs/git-lfs/pul
 This can be worked around on all the client machines by setting the git config:
 `git config --global lfs.ssh.automultiplex false`
 :::
+
+# Changing LFS files through the API
+
+The [contents API](https://docs.gitea.com/api/operations/repo-change-files/)
+works on LFS tracked files as well: send the file content as usual and Gitea
+stores it as an LFS object and commits a pointer file, as long as the path is
+matched by a `filter=lfs` rule in `.gitattributes`.
+
+What is easy to get wrong is the `sha` of the file being changed, which
+`PUT`/`DELETE /repos/{owner}/{repo}/contents/{filepath}` and
+`POST /repos/{owner}/{repo}/contents` require for an existing file. Gitea
+compares it with the ID of the blob the commit has at that path, and for an LFS
+tracked file that blob is the **pointer file**, not the content:
+
+- use the `sha` returned by
+  [`GET /repos/{owner}/{repo}/contents/{filepath}`](https://docs.gitea.com/api/operations/repo-get-contents/)
+- do not use `lfs_oid` from the same response, which identifies the LFS object,
+  and do not use a checksum of the file itself
+
+Sending anything else fails with `sha does not match`, even though the request
+looks correct.
@@ -16,6 +16,8 @@ The logging configuration of Gitea mainly consists of 3 types of components:

 There is a fully functional log output by default, so it is not necessary to define one.

+Security-relevant events (repository transfers, token changes, impersonation, and similar) are recorded separately. See [Audit Logging](audit-logging.md).
+
 ## Collecting Logs for Help

 To collect logs for help and issue report, see [Support Options](help/support.md).
@@ -43,7 +43,7 @@ You can try it out using [the online demo](https://demo.gitea.com).

 - **Security**

-  Gitea places a strong emphasis on security, offering features such as user permission management, access control lists, and more to ensure the security of code and data.
+  Gitea places a strong emphasis on security, offering features such as user permission management, access control lists, [audit logging](administration/audit-logging.md), and more to ensure the security of code and data.

 - **Code Review**

@@ -34,6 +34,7 @@ _Symbols used in table:_
 | Telemetry                                        | **✘**                                               | ✓         | ✓         | ✓         | ✓         | ✘            | ✘            |
 | Third-party render tool support                  | ✓                                                   | ✘         | ✘         | ✘         | ✓         | ✘            | ✘            |
 | WebAuthn (2FA)                                   | ✓                                                   | ✓         | ✓         | ✓         | ✓         | ✘            | ✓            |
+| Audit log                                        | ✓                                                   | ✓         | ⁄         | ✓         | ✓         | ?            | ?            |
 | Extensive API                                    | ✓                                                   | ✓         | ✓         | ✓         | ✓         | ✓            | ✓            |
 | Built-in Package/Container Registry              | ✓                                                   | ✓         | ✓         | ✓         | ✘         | ✘            | ✘            |
 | Sync commits to an external repo (push mirror)   | ✓                                                   | ✘         | ✓         | ✓         | ✘         | ✓            | ✓            |
@@ -23,7 +23,7 @@ version is @minNodeVersion@ and the latest LTS version is recommended.
 :::note
 Go version @minGoVersion@ or higher is required. However, it is recommended to
 obtain the same version as our continuous integration, see the advice given in
-[Hacking on Gitea](development/hacking-on-gitea.md)
+[Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
 :::

 ## Download
@@ -73,7 +73,7 @@ To build from source, the following programs must be present on the system:

 - `go` @minGoVersion@ or higher, see [here](https://go.dev/dl/)
 - `node` @minNodeVersion@ or higher with `npm`, see [here](https://nodejs.org/en/download/)
- `make`, see [here](development/hacking-on-gitea.md#installing-make)
+- `make`, see [here](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md#make)

 Various [make tasks](https://github.com/go-gitea/gitea/blob/main/Makefile)
 are provided to keep the build process as simple as possible.
@@ -66,7 +66,7 @@ server-1  | 2026-03-11T12:57:50.796198843Z /var/lib/gitea/git is not writable
 server-1  | 2026-03-11T12:57:50.796235667Z docker setup failed
 ```

-For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly-rootless`)
+For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:main-nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly-rootless`)

 ## Named volumes

@@ -30,7 +30,7 @@ image as a service. Since there is no database available, one can be initialized
 Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
 Note that the volume should be owned by the user/group with the UID/GID specified in the config file.
 If you don't give the volume correct permissions, the container may not start.
-For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly`)
+For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:main-nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly`)

 ```yaml
 networks:
@@ -191,7 +191,7 @@ services:
 +    networks:
 +      - gitea
 +    volumes:
-+      - ./postgres:/var/lib/postgresql/data
+      - ./postgres:/var/lib/postgresql
 ```

 ## Named volumes
@@ -0,0 +1,166 @@
+---
+date: "2026-09-03T20:00:00+02:00"
+slug: "install-with-podman-quadlet"
+sidebar_position: 65
+aliases:
+  - /en-us/install-with-podman-quadlet
+---
+
+# Installation with Podman Quadlet
+
+Similarly to [Docker](with-docker.md), [Podman](https://podman.io/) can be used to deploy Gitea.
+
+This reference setup guides users through the setup based on Podman Quadlet.
+Podman Quadlet is the native integration of Podman through systemd.
+
+To learn more about Podman Quadlet, see [systemd units using Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html).
+
+This setup installs the quadlets in `~/.config/containers/systemd/`, the directory for rootless quadlets, and uses the rootless images.
+If you install them in a rootful directory such as `/etc/containers/systemd/`, use the rootful images instead.
+
+## Basics
+
+Since Podman v6.0 a single `gitea.quadlets` file can hold multiple quadlets separated by the `---` delimiter.
+
+Paste the following content into a file named `gitea.quadlets`
+
+```ini
+# FileName=gitea-data
+[Volume]
+VolumeName=gitea-data
+---
+# FileName=gitea-config
+[Volume]
+VolumeName=gitea-config
+---
+# FileName=gitea
+[Container]
+PublishPort=2222:2222
+PublishPort=3000:3000
+Image=docker.gitea.com/gitea:@dockerVersion@-rootless
+ContainerName=gitea
+Mount=type=volume,src=gitea-data.volume,destination=/var/lib/gitea
+Mount=type=volume,src=gitea-config.volume,destination=/etc/gitea
+
+[Service]
+Restart=always
+
+[Install]
+# Start with the user session
+WantedBy=default.target
+```
+
+You can run the installation command
+
+```sh
+$ podman quadlet install ./gitea.quadlets --application=gitea
+/home/user/.config/containers/systemd/gitea/gitea-data.volume
+/home/user/.config/containers/systemd/gitea/gitea-config.volume
+/home/user/.config/containers/systemd/gitea/gitea.container
+```
+
+The `--application=gitea` flag allows us to tell podman to group the quadlets together, this can help for managing and organizing the quadlets files.
+
+You can validate the quadlets are properly installed by looking at the list command
+
+```sh
+$ podman quadlet list
+NAME                 UNIT NAME                    PATH ON DISK                                                     STATUS         APPLICATION  POD
+gitea-config.volume  gitea-config-volume.service  /home/user/.config/containers/systemd/gitea/gitea-config.volume  active/exited  gitea
+gitea-data.volume    gitea-data-volume.service    /home/user/.config/containers/systemd/gitea/gitea-data.volume    active/exited  gitea
+gitea.container      gitea.service                /home/user/.config/containers/systemd/gitea/gitea.container      failed/failed  gitea
+```
+
+You can start the application by running `systemctl --user start gitea` command.
+
+`WantedBy=default.target` starts the service when the user session starts.
+Rootless user services do not run without a session, so to start Gitea at boot, enable lingering for the user with `loginctl enable-linger $USER`.
+
+## Databases
+
+### PostgreSQL database
+
+To start Gitea in combination with a PostgreSQL database, apply these changes to the
+`gitea.quadlets` file created above.
+
+To start Gitea with a database, we need to create a network, so the database and Gitea container can communicate.
+
+```diff
+# FileName=gitea-data
+[Volume]
+VolumeName=gitea-data
+---
+# FileName=gitea-config
+[Volume]
+VolumeName=gitea-config
+---
+ # FileName=gitea-postgres-data
+ [Volume]
+ VolumeName=gitea-postgres-data
+ ---
+ # FileName=gitea
+ [Network]
+ NetworkName=gitea
+ ---
+ # FileName=gitea-postgres
+ [Container]
+ Image=docker.io/library/postgres:18
+ ContainerName=gitea-postgres
+ Network=gitea.network
+ Mount=type=volume,src=gitea-postgres-data.volume,destination=/var/lib/postgresql
+ Environment=POSTGRES_USER=gitea
+ Environment=POSTGRES_PASSWORD=gitea
+ Environment=POSTGRES_DB=gitea
+
+ [Service]
+ Restart=always
+
+ [Install]
+ # Start with the user session
+ WantedBy=default.target
+ ---
+# FileName=gitea
+ [Unit]
+ Requires=gitea-postgres.service
+ After=gitea-postgres.service
+
+[Container]
+PublishPort=2222:2222
+PublishPort=3000:3000
+Image=docker.gitea.com/gitea:@dockerVersion@-rootless
+ContainerName=gitea
+Mount=type=volume,src=gitea-data.volume,destination=/var/lib/gitea
+Mount=type=volume,src=gitea-config.volume,destination=/etc/gitea
+ Network=gitea.network
+ Environment=GITEA__database__DB_TYPE=postgres
+ Environment=GITEA__database__HOST=gitea-postgres:5432
+ Environment=GITEA__database__NAME=gitea
+ Environment=GITEA__database__USER=gitea
+ Environment=GITEA__database__PASSWD=gitea
+
+[Service]
+Restart=always
+
+[Install]
+# Start with the user session
+WantedBy=default.target
+```
+
+## Logs
+
+As systemd manages the container we can use `journalctl` to access the logs
+
+```sh
+$ journalctl --user --follow --unit=gitea.service
+gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:263:runWeb() [I] Starting Gitea on PID: 2
+gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:115:showWebStartupMessage() [I] Gitea version: 1.27.3 built with go1.26.7-X:jsonv2 : bindata, timetzdata,
+gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:116:showWebStartupMessage() [I] * RunMode: prod
+gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:117:showWebStartupMessage() [I] * AppPath: /usr/local/bin/gitea
+gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:118:showWebStartupMessage() [I] * WorkPath: /var/lib/gitea
+gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:119:showWebStartupMessage() [I] * CustomPath: /var/lib/gitea/custom
+gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:120:showWebStartupMessage() [I] * ConfigFile: /etc/gitea/app.ini
+gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:121:showWebStartupMessage() [I] Prepare to run install page
+gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:329:listen() [I] Listen: http://0.0.0.0:3000
+gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:333:listen() [I] AppURL(ROOT_URL): http://localhost:3000/
+gitea[5967]: 2026/09/03 14:50:42 modules/graceful/server.go:52:NewServer() [I] Starting new Web server: tcp:0.0.0.0:3000 on PID: 2
+```
@@ -0,0 +1,31 @@
+---
+date: "2026-08-30T00:00:00+02:00"
+slug: "artifacts"
+sidebar_position: 70
+---
+
+# Artifacts
+
+Workflow runs can store files such as test results, coverage reports, and build output as artifacts. Artifacts are uploaded by workflows, for example with [`actions/upload-artifact`](https://github.com/actions/upload-artifact), and appear on the run page after the upload completes.
+
+## Previewing artifacts
+
+Select an artifact on the run page to open its file browser and preview in the same tab. The preview identifies the originating run and attempt, and provides links back to that run and to download the complete artifact. Selecting files in the browser updates the preview in the same tab.
+
+Artifact previews:
+
+- require sign-in and access to the Actions run to open the preview page
+- render text-based files, images (including SVG), and PDFs
+- run HTML and JavaScript content in a sandboxed frame
+
+Preview content is loaded through signed URLs that expire after one hour and do not require a session cookie. Reopen the preview page to obtain a fresh URL after it expires.
+
+The file browser lists up to 2,000 files per artifact. Larger artifacts show a notice when the list is truncated.
+
+Unsupported or oversized files can still be downloaded with the complete artifact.
+
+## Instance configuration
+
+Site administrators can limit the total artifact size that can be browsed or previewed with `ARTIFACT_PREVIEW_MAX_SIZE` in the `[actions]` section of `app.ini`. The default is 10 MiB. Set it to `0` to disable previews or `-1` to allow artifacts of any size.
+
+The size of an individual previewed file is also limited by [`MAX_DISPLAY_FILE_SIZE`](../../administration/config-cheat-sheet.md#ui-ui) in the `[ui]` section.
@@ -6,104 +6,94 @@ sidebar_position: 120

 # Compared to GitHub Actions

-Even though Gitea Actions is designed to be compatible with GitHub Actions, there are some differences between them.
+Gitea Actions is designed to be compatible with GitHub Actions, with the differences below.

 ## Additional features

 ### Absolute action URLs

-Gitea Actions supports defining actions via absolute URL, which means that you can use actions from any git repository.
-Like `uses: https://github.com/actions/checkout@v4` or `uses: http://your_gitea.com/owner/repo@branch`.
+`uses:` accepts an absolute URL to any git host, e.g. `uses: https://gitea.com/actions/checkout@v4`.
+
+### Action prefixes
+
+`uses:` accepts these prefixes:
+
+- `self:` references your own Gitea instance, e.g. `uses: self:owner/repo@v1` or `uses: self:owner/repo/.gitea/workflows/build.yml@v1`
+- `builtin:` runs an action built into Gitea Runner, which needs no download and no Node in the job image, e.g. `uses: builtin:checkout`
+
+`builtin:checkout` accepts the `repository`, `ref`, `token`, `path` and `fetch-depth` inputs of `actions/checkout` with the same defaults, and fails on any other input.
+
+### Workflow-relative actions
+
+`$/` references the repository and commit of the workflow, or of the enclosing composite action, e.g. `uses: $/.gitea/actions/build`.
+Unlike `./`, it needs no checkout first.

 ### Actions written in Go

-Gitea Actions supports writing actions in Go.
 See [Creating Go Actions](https://blog.gitea.com/creating-go-actions/).

 ### Support the non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly on schedule

-Github Actions doesn't support that. https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
+`schedule` also accepts `@yearly`, `@monthly`, `@weekly`, `@daily` and `@hourly`, which [GitHub does not](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).

 ## Unsupported workflows syntax

 ### `jobs.<job_id>.environment`

-See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment).
-
-It's ignored by Gitea Actions now.
+[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) is ignored.

 ### Complex `runs-on`

-See [Workflow syntax for GitHub Actions](https://docs.github.com/en/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) supports:

-Gitea Actions supports:
 - Static strings: `runs-on: self-hosted`
 - Arrays of labels: `runs-on: [linux, self-hosted]`
 - String expressions: `runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
 - Arrays containing expressions: `runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`

-
 ## Missing features

 ### Package repository authorization

-The `GITEA_TOKEN` for a job running within a repository should be able to publish to the associated package repository (i.e. to upload OCI images). See the "packages" scope for the "default access" in [Automatic token authentication](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token).
-
-This is not implemented in Gitea Actions now. A workaround for Gitea Actions is to use a Personal Access Token (PAT). See this [github issue and comment](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692) for tracking this feature.
+`GITEA_TOKEN` cannot publish to the package registry of its repository, e.g. to push OCI images.
+Use a personal access token instead, see [this issue](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692).

 ### Problem Matchers

-Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI.
-See [Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md).
-
-It's ignored by Gitea Actions now.
+[Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md) are ignored.

 ### Create an error annotation

-See [Creating an annotation for an error](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)
-
-It's ignored by Gitea Actions now.
+[Error annotations](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error) are ignored.

 ### Expressions

-For [expressions](https://docs.github.com/en/actions/learn-github-actions/expressions), Gitea Actions supports standard GitHub functions (e.g. `success()`, `failure()`, `always()`, `cancelled()`, `format()`, `toJSON()`) and context variables (like `github`, `matrix`, `vars`, `env`).
+[Expressions](https://docs.github.com/en/actions/learn-github-actions/expressions) support the standard GitHub functions and contexts.

 ## Missing UI features

 ### Pre and Post steps

-Pre and Post steps don't have their own section in the job log user interface.
+Pre and post steps have no section of their own in the job log.

 ### Services steps

-Services steps don't have their own section in the job log user interface.
+Service steps have no section of their own in the job log.

 ## Different behavior

 ### Job token permissions (`permissions`)

-Gitea supports `permissions` and `jobs.<job_id>.permissions` to control the default `GITEA_TOKEN` permissions.
-
-The effective permissions are clamped by the repository/owner settings and are further restricted for fork pull requests and cross-repository access.
-GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not supported, while Gitea-specific scopes such as `code`, `releases`, `wiki`, and `projects` are available.
-
+`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`.
 See [Actions job token permissions](token-permissions.md).

 ### Downloading actions

-Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.
-We have since restricted this option to only allow two values (`github` and `self`).
-When set to `github`, the new default, Gitea will download non-fully-qualified actions from `https://github.com`.
-For example, if you use `uses: actions/checkout@v4`, it will download the checkout repository from `https://github.com/actions/checkout.git`.
-
-If you want to download an action from another git hoster, you can use an absolute URL, e.g. `uses: https://gitea.com/actions/checkout@v4`.
-
-If your Gitea instance is in an intranet or a restricted area, you can set the URL to `self` to only download actions from your own instance by default.
-Of course, you can still use absolute URLs in workflows.
-
-More details about the `[actions].DEFAULT_ACTIONS_URL` configuration can be found in the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions)。
+Actions without a host, like `uses: actions/checkout@v4`, are downloaded from `https://github.com`, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`.
+See the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
+For other sources, see [Absolute action URLs](#absolute-action-urls), [Action prefixes](#action-prefixes) and [Workflow-relative actions](#workflow-relative-actions).

 ### Context availability

-Context availability is not checked, so you can use the env context on more places.
-See [Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability).
+[Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability) is not checked, so contexts like `env` work in more places.
@@ -19,7 +19,7 @@ Additionally, the runner will introduce itself to Gitea and declare what kind of

 Earlier, we mentioned that `runs-on: ubuntu-latest` in a workflow file means that the job will be run on a runner with the `ubuntu-latest` label.
 But how does the runner know to run `ubuntu-latest`? The answer lies in mapping the label to an environment.
-That's why when you add custom labels during registration, you will need to input some complex content like `my_custom_label:docker://centos:7`.
+That's why each label of a runner names an environment, like `my_custom_label:docker://centos:7`.
 This means that the runner can take the job which needs to run on `my_custom_label`, and it will run it via a docker container with the image `centos:7`.

 Docker isn't the only option, though.
@@ -34,7 +34,6 @@ So,
 - `my_custom_label:docker://node:18`: Run jobs labeled with `my_custom_label` using the `node:18` Docker image.
 - `my_custom_label:host`: Run jobs labeled with `my_custom_label` directly on the host.
 - `my_custom_label`: Same as `my_custom_label:host`.
- `my_custom_label:vm:ubuntu-latest`: (Example only, not implemented) Run jobs labeled with `my_custom_label` using a virtual machine with the `ubuntu-latest` ISO.

 ## Communication protocol

@@ -43,7 +42,7 @@ However, we did not think it was a good idea to have Gitea listen on a new port.
 Instead, we wanted to reuse the HTTP port, which means we needed a protocol that is compatible with HTTP.
 We chose to use gRPC over HTTP.

-We use [actions-proto-def](https://gitea.com/gitea/actions-proto-def) and [actions-proto-go](https://gitea.com/gitea/actions-proto-go) to wire them up.
+The protocol is defined in [actions-proto-def](https://gitea.com/gitea/actions-proto-def), its Go code lives in [actionslib](https://gitea.com/gitea/actionslib).
 More information about gRPC can be found on [its website](https://grpc.io/).

 ## Network architecture
@@ -71,7 +70,8 @@ However, if a job container tries to fetch code from localhost, it will fail bec
 ### Connection 3, runner to internet

 When you use some actions like `actions/checkout@v4`, the runner downloads the scripts, not the job containers.
-By default, it downloads from [github.com](http://github.com/), so it requires access to the internet. If you configure the `DEFAULT_ACTIONS_URL` to `self`, then it will download from your Gitea instance by default. Then it will not connect to internet when downloading the action itself.
+By default, it downloads them from [github.com](https://github.com/), which requires internet access.
+With `DEFAULT_ACTIONS_URL` set to `self`, or with `uses: self:owner/repo@ref`, it downloads them from your Gitea instance instead.
 It also downloads some docker images from Docker Hub by default, which also requires internet access.

 However, internet access is not strictly necessary.
@@ -27,50 +27,24 @@ Still, this is completely optional since both options have the same effect at th

 ## Where will the runner download scripts when using actions such as `actions/checkout@v4`?

-There are tens of thousands of [actions scripts](https://github.com/marketplace?type=actions) in GitHub, and when you write `uses: actions/checkout@v4`, it downloads the scripts from [github.com/actions/checkout](http://github.com/actions/checkout) by default.
-But what if you want to use actions from other places such as gitea.com instead of GitHub?
+From `https://github.com` by default, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`, see the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).

-The good news is that you can specify the URL prefix to use actions from anywhere.
-This is an extra syntax in Gitea Actions.
-For example:
+To use an action from elsewhere, name its host:

- `uses: https://gitea.com/xxx/xxx@xxx`
- `uses: https://github.com/xxx/xxx@xxx`
- `uses: http://your_gitea_instance.com/xxx@xxx`
-
-Be careful, the `https://` or `http://` prefix is necessary!
-
-This is one of the differences from GitHub Actions which supports actions scripts only from GitHub.
-But it should allow users much more flexibility in how they run Actions.
-
-Alternatively, if you want your runners to download actions from your own Gitea instance by default, you can configure it by setting `[actions].DEFAULT_ACTIONS_URL`.
-See [Configuration Cheat Sheet](../../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` for your own Gitea instance

 ## How to limit the permission of the runners?

-Runners have no more permissions than simply connecting to your Gitea instance.
-When any runner receives a job to run, it will temporarily gain limited permission to the repository associated with the job.
-If you want to give more permissions to the runner, allowing it to access more private repositories or external systems, you can pass [secrets](usage/actions/secrets.md) to it.
-
-Refined permission control to Actions is a complicated job.
-In the future, we will add more options to Gitea to make it more configurable, such as allowing more write access to repositories or read access to all repositories in the same organization.
+Runners only connect to your Gitea instance.
+For each job, a runner gets a `GITEA_TOKEN` limited to the job's repository, see [Actions job token permissions](token-permissions.md).
+To give a job access to more private repositories or external systems, pass it [secrets](usage/actions/secrets.md).

 ## Which operating systems are supported by Gitea Runner?

-We released official binaries for Linux, macOS, and Windows.
-While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
-
-One thing to note is that if you choose to run jobs directly on the host instead of in job containers, the environmental differences between operating systems may cause unexpected failures.
-
-For example, bash is not available on Windows in most cases, while act tries to use bash to run scripts by default.
-Therefore, you need to specify `powershell` as the default shell in your workflow file, see [defaults.run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun).
-
-
-```yaml
-defaults:
-  run:
-    shell: powershell
-```
+Official binaries are released for Linux, macOS and Windows.
+Other systems supported by Go and Docker work in theory.

 ## How to avoid being hacked?

@@ -99,42 +73,13 @@ It is exciting to be able to reuse them.

 ## What if it runs on multiple labels, such as `runs-on: [label_a, label_b]`?

-This is valid syntax.
-It means that it should run on runners that have both the `label_a` **and** `label_b` labels, see [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
-Unfortunately, the runner does not work this way until v0.2.11.
-As mentioned, we map labels to environments:
-
- `ubuntu` → `ubuntu:22.04`
- `centos` → `centos:8`
-
-But we need to map label groups to environments instead, like so:
-
- `[ubuntu]` → `ubuntu:22.04`
- `[with-gpu]` → `linux:with-gpu`
- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
-
-We also need to re-design how tasks are assigned to runners.
-A runner with `ubuntu`, `centos`, or `with-gpu` does not necessarily indicate that it can accept jobs with `[centos, with-gpu]`.
-Therefore, the runner should inform the Gitea instance that it can only accept jobs with `[ubuntu]`, `[centos]`, `[with-gpu]`, and `[ubuntu, with-gpu]`.
-This is not a technical problem, it was just overlooked in the early design.
-See [runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
-
-Currently, the runner attempts to match everyone in the labels and uses the first match it finds.
+The job runs on a runner that has all of the labels, as on [GitHub](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
+The runner uses the environment of the first label it has.

 ## What is the difference between agent labels and custom labels for a runner?

-![labels](/images/usage/actions/labels.png)
-
-Agent labels are reported to the Gitea instance by the runner during registration.
-Custom labels, on the other hand, are added manually by a Gitea administrator or owners of the organization or repository (depending on the level of the runner).
-
-However, the design here needs improvement, as it currently has some rough edges.
-You can add a custom label such as `centos` to a registered runner, which means the runner will receive jobs with `runs-on: centos`.
-However, the runner may not know which environment to use for this label, resulting in it using a default image or leading to a logical dead end.
-This default may not match user expectations.
-See [runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71).
-
-In the meantime, we suggest that you re-register your runner if you want to change its labels.
+Gitea no longer has custom labels.
+A runner declares its labels every time it starts, from its `runner.labels` configuration or the labels given at registration, so change them there and restart the runner.

 ## Will there be more implementations for Gitea Actions runner?

@@ -177,3 +122,6 @@ For events supported only by GitHub, see GitHub's [documentation](https://docs.g

 Go to the repository's **Settings** > **Actions** > **General** page and add collaborative owners.
 The private repositories of collaborative owners are allowed to access the actions and workflows in the current repository.
+
+To share within the same user or organization, add the private repositories under its **Settings** > **Actions** > **General** > **Cross-Repository Access** instead.
+See [Cross-repository access](token-permissions.md#cross-repository-access).
@@ -102,8 +102,8 @@ Only a workflow that runs on an event that posts a commit status (`push`, `pull_

 Scoped workflows can call reusable workflows:

- A **local** reference (`uses: ./...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
- A **cross-repository** reference (`uses: owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
+- A **local** reference (`uses: ./...` or `uses: $/...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
+- A **cross-repository** reference (`uses: owner/repo/...@ref` or `uses: self:owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.

 A reusable workflow can live under `SCOPED_WORKFLOW_DIRS` (or `WORKFLOW_DIRS`) of the source repository.

@@ -367,7 +367,7 @@ aliases:
 - `SSH_SERVER_CIPHERS`: **[email protected], aes128-ctr, aes192-ctr, aes256-ctr, [email protected], [email protected]**: 对于内置的 SSH 服务器，选择支持的 SSH 连接的加密方法，对于系统 SSH，此设置无效。
 - `SSH_SERVER_KEY_EXCHANGES`: **curve25519-sha256, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group14-sha256, diffie-hellman-group14-sha1**: 对于内置 SSH 服务器，选择支持的 SSH 连接的密钥交换算法，对于系统 SSH，此设置无效。
 - `SSH_SERVER_MACS`: **[email protected], hmac-sha2-256, hmac-sha1**: 对于内置 SSH 服务器，选择支持的 SSH 连接的 MAC 算法，对于系统 SSH，此设置无效。
- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gogs.rsa**: 对于内置 SSH 服务器，选择要提供为主机密钥的密钥对。私钥应在 `SSH_SERVER_HOST_KEY` 中，公钥在 `SSH_SERVER_HOST_KEY.pub` 中。相对路径会相对于 `APP_DATA_PATH` 转为绝对路径。如果不存在密钥，将为您创建一个 4096 位的 RSA 密钥。
+- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gitea.ed25519, ssh/gitea.ecdsa, ssh/gogs.rsa**: 对于内置 SSH 服务器，选择要提供为主机密钥的密钥对。私钥应在 `SSH_SERVER_HOST_KEY` 中，公钥在 `SSH_SERVER_HOST_KEY.pub` 中。相对路径会相对于 `APP_DATA_PATH` 转为绝对路径。如果所有密钥都不存在，将为您创建 4096 位的 RSA、256 位的 ECDSA 和 ED25519 密钥。
 - `SSH_KEY_TEST_PATH`: **/tmp**: 在使用 `ssh-keygen` 测试公共 SSH 密钥时要在其中创建临时文件的目录，默认为系统临时目录。
 - `SSH_KEYGEN_PATH`: **_empty_**: 使用 `ssh-keygen` 解析公共 SSH 密钥。该值将传递给 shell。默认情况下，Gitea 会自行进行解析。
 - `SSH_EXPOSE_ANONYMOUS`: **false**: 启用将 SSH 克隆 URL 暴露给匿名访问者，默认为 false。
@@ -518,7 +518,7 @@ Gitea 创建以下非唯一队列：
 - `SECRET_KEY`: **\<每次安装时随机生成\>**: 全局服务器安全密钥。这个密钥非常重要，如果丢失将无法解密加密的数据（例如 2FA）。
 - `SECRET_KEY_URI`: **_empty_**: 与定义 `SECRET_KEY` 不同，此选项可用于使用存储在文件中的密钥（示例值：`file:/etc/gitea/secret_key`）。它不应该像 `SECRET_KEY` 一样容易丢失。
 - `LOGIN_REMEMBER_DAYS`: **31**: 在要求重新登录之前，记住用户的登录状态多长时间（以天为单位）。
- `COOKIE_REMEMBER_NAME`: **gitea_incredible**: 保存自动登录信息的 Cookie 名称。
+- `COOKIE_REMEMBER_NAME`: **gitea_remember**: 保存自动登录信息的 Cookie 名称。
 - `REVERSE_PROXY_LOGOUT_REDIRECT`: **_empty_**: 当使用反向代理或 SSO 进行身份认证时，用户登出后重定向到的 URL 或相对路径。例如：`/my-sso/logout?return=/my-sso/home`。
 - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: 反向代理认证的 HTTP 头部名称，用于提供用户信息。
 - `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: 反向代理认证的 HTTP 头部名称，用于提供邮箱信息。
@@ -681,17 +681,16 @@ Gitea 创建以下非唯一队列：

 - `QUEUE_LENGTH`: **1000**: 钩子任务队列长度。编辑此值时要小心。
 - `DELIVER_TIMEOUT`: **5**: 发送 Webhook 的交付超时时间（秒）。
- `ALLOWED_HOST_LIST`: **external**: 出于安全原因，Webhook 仅能调用允许的主机。以逗号分隔的列表。
+- `ALLOWED_HOST_LIST`: **_empty_**: 出于安全原因，Webhook 仅能调用允许的主机。以逗号分隔的列表。在默认的 `[security]` `EGRESS_MODE = lax` 下仅限制私有地址。
  - 内置网络：
    - `loopback`：IPv4 的 127.0.0.0/8 和 IPv6 的 ::1/128，包括 localhost。
-    - `private`：RFC 1918（10.0.0.0/8，172.16.0.0/12，192.168.0.0/16）和 RFC 4193（FC00::/7）。也称为 LAN/Intranet。
-    - `external`：一个有效的非私有单播 IP，您可以访问公共互联网上的所有主机。
-    - `*`：允许所有主机。
+    - `private`：RFC 1918（10.0.0.0/8，172.16.0.0/12，192.168.0.0/16）、RFC 4193（FC00::/7）和 RFC 6598 CGNAT（100.64.0.0/10）。也称为 LAN/Intranet。
  - CIDR 列表：IPv4 的 `1.2.3.0/8` 和 IPv6 的 `2001:db8::/32`
-  - 通配符主机：`*.mydomain.com`，`192.168.100.*`
+  - 通配符主机：`*.mydomain.com`
+  - 链路本地和云元数据等保留地址会被拒绝。
 - `SKIP_TLS_VERIFY`: **false**: 允许不安全的证书。
 - `PAGING_NUM`: **10**: 一页中显示的 Webhook 历史事件数量。
- `PROXY_URL`: **_empty_**: 代理服务器 URL，支持 http://、https://、socks://，留空将遵循环境的 http_proxy/https_proxy 设置。如果未提供，将使用全局代理设置。
+- `PROXY_URL`: **_empty_**: 代理服务器 URL，支持 http://、https://、socks5://，留空将遵循环境的 http_proxy/https_proxy 设置。如果未提供，将使用全局代理设置。
 - `PROXY_HOSTS`: **_empty_**: 需要代理的主机名的逗号分隔列表。支持通配符模式 (\*)；使用 \*\* 来匹配所有主机。如果未提供，将使用全局代理设置。

 ## 邮件 (`mailer`)
@@ -781,10 +780,10 @@ In-Reply-To =

 ## 会话 (`session`)

- `PROVIDER`: **memory**: 会话存储引擎 \[memory, file, redis, redis-cluster, db, mysql, couchbase, memcache, postgres\]。设置为 `db` 将会重用 `[database]` 的配置信息。
+- `PROVIDER`: **file**: 会话存储引擎 \[memory, file, redis, db\]。设置为 `db` 将会重用 `[database]` 的配置信息。
 - `PROVIDER_CONFIG`: **data/sessions**: 对于文件，为根路径；对于 db，为空（将使用数据库配置）；对于其他引擎，为连接字符串。相对路径将根据 _`AppWorkPath`_ 绝对化。
 - `COOKIE_SECURE`: **_empty_**: `true` 或 `false`。启用此选项以强制在所有会话访问中使用 HTTPS。如果没有设置，当 ROOT_URL 是 https 链接的时候默认设置为 true。
- `COOKIE_NAME`: **i_like_gitea**: 用于会话 ID 的 cookie 名称。
+- `COOKIE_NAME`: **gitea_session**: 用于会话 ID 的 cookie 名称。
 - `GC_INTERVAL_TIME`: **86400**: GC 间隔时间，以秒为单位。
 - `SESSION_LIFE_TIME`: **86400**: 会话生命周期，以秒为单位，默认为 86400（1 天）。
 - `DOMAIN`: **_empty_**: 设置 cookie 的域。
@@ -812,7 +811,7 @@ In-Reply-To =
  - none = 不显示任何头像
  - random = 生成随机头像
  - image = 使用默认图像（在 `REPOSITORY_AVATAR_FALLBACK_IMAGE` 中设置），如果设置为 image 并且未上传任何图像。
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。
+- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **_empty_**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。该值将原样使用，不会自动添加 `ROOT_URL` 中的子路径。留空则使用 Gitea 内置的仓库头像。

 ## 项目 (`project`)

@@ -1074,7 +1073,7 @@ In-Reply-To =

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `ENABLE_SUCCESS_NOTICE`: **true**: 设置为 false 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 168h**: Cron 语法，用于安排任务，例如 `@every 168h`。
 - `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: Gitea 用于检查新版本的端点。

@@ -1082,7 +1081,7 @@ In-Reply-To =

 - `ENABLED`: **false**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
 - `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。

@@ -1102,35 +1101,35 @@ In-Reply-To =

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@annually**: Cron 语法，用于设置重建索引的频率。

 #### Cron - 停止长时间未更新的运行中任务 (`cron.stop_zombie_tasks`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 5m**: Cron 语法，用于设置检查的频率。

 #### Cron - 停止持续更新但长时间未结束的运行中任务 (`cron.stop_endless_tasks`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 30m**: Cron 语法，用于设置检查的频率。

 #### Cron - 取消长时间未被领取的任务 (`cron.cancel_abandoned_jobs`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 6h**: Cron 语法，用于设置检查的频率。

 #### Cron - 启动基于定时的 Actions (`cron.start_schedule_tasks`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 1m**: Cron 语法，用于设置调度任务的频率。

 ## Git (`git`)
@@ -1277,9 +1276,8 @@ ALLOW_DATA_URI_IMAGES = true

 - `MAX_ATTEMPTS`：**3**: 每次 http/https 请求的最大尝试次数（用于迁移）。
 - `RETRY_BACKOFF`：**3**: 每次 http/https 请求重试的退避时间（秒）。
- `ALLOWED_DOMAINS`：**_empty_**: 允许迁移仓库的域名允许列表，默认为空。这意味着允许外部网址。多个域名可以用逗号分隔。支持通配符：`github.com, *.github.com`。
- `BLOCKED_DOMAINS`：**_empty_**: 阻止迁移仓库的域名阻止列表，默认为空。多个域名可以用逗号分隔。当 `ALLOWED_DOMAINS` 不为空时，此选项优先级较高，用于拒绝域名。支持通配符。
- `ALLOW_LOCALNETWORKS`：**false**: 允许 RFC 1918、RFC 1122、RFC 4632 和 RFC 4291 中定义的私有地址。如果域名被 `ALLOWED_DOMAINS` 允许，此选项将被忽略。
+- `ALLOWED_HOST_LIST`：**_empty_**: 迁移和镜像可以访问的主机，格式与 `[security]` 的 `ALLOWED_HOST_LIST` 相同。私有和回环地址需要内置或 CIDR 条目。取代已弃用的 `ALLOWED_DOMAINS` 和 `ALLOW_LOCALNETWORKS`。
+- `BLOCKED_HOST_LIST`：**_empty_**: 迁移和镜像禁止访问的主机。取代已弃用的 `BLOCKED_DOMAINS`。
 - `SKIP_TLS_VERIFY`：**false**: 允许跳过 TLS 验证。

 ## 联邦（`federation`）
@@ -1509,14 +1507,14 @@ MINIO_BUCKET_LOOKUP_TYPE = auto
 ## 代理 (`proxy`)

 - `PROXY_ENABLED`: **false**: 启用代理，如果为 true，所有通过 HTTP 向外部的请求都将受到影响，如果为 false，即使环境设置了 http_proxy/https_proxy 也不会使用
- `PROXY_URL`: **_empty_**: 代理服务器地址，支持 http://, https//, socks://，为空则不启用代理而使用环境变量中的 http_proxy/https_proxy
+- `PROXY_URL`: **_empty_**: 代理服务器地址，支持 http://, https://, socks5://，为空则不启用代理而使用环境变量中的 http_proxy/https_proxy
 - `PROXY_HOSTS`: **_empty_**: 逗号分隔的多个需要代理的网址，支持 \* 号匹配符号， \*\* 表示匹配所有网站

 i.e.

 ```ini
 PROXY_ENABLED = true
-PROXY_URL = socks://127.0.0.1:1080
+PROXY_URL = socks5://127.0.0.1:1080
 PROXY_HOSTS = *.github.com
 ```

@@ -1541,18 +1539,9 @@ PROXY_HOSTS = *.github.com
 - `SCOPED_WORKFLOW_DIRS`：**.gitea/scoped_workflows**：以逗号分隔的目录列表，用于存放[作用域工作流](usage/actions/scoped-workflows.md)（在一个中心源仓库中定义、并在其他仓库上运行的工作流）。不得与 `WORKFLOW_DIRS` 重叠。留空则不会扫描任何目录来查找作用域工作流，因此不会找到或运行任何作用域工作流。
 - `MAX_RERUN_ATTEMPTS`：**50**：单个工作流运行最多可以有的尝试次数（初始运行 + 重新运行）。默认 50。可根据需要设置为任何正整数。

-`DEFAULT_ACTIONS_URL` 指示 Gitea 操作运行程序应该在哪里找到带有相对路径的操作。
-例如，`uses: actions/checkout@v4` 表示 `https://github.com/actions/checkout@v4`，因为 `DEFAULT_ACTIONS_URL` 的值为 `github`。
-它可以更改为 `self`，以使其成为 `root_url_of_your_gitea/actions/checkout@v4`。
-
-请注意，对于大多数情况，不建议使用 `self`，因为它可能使名称在全局范围内产生歧义。
-此外，它要求您将所有所需的操作镜像到您的 Gitea 实例，这可能不值得。
-因此，请仅在您了解自己在做什么的情况下使用 `self`。
-
-在早期版本（`<= 1.19`）中，`DEFAULT_ACTIONS_URL` 可以设置为任何自定义 URL，例如 `https://gitea.com` 或 `http://your-git-server,https://gitea.com`，默认值为 `https://gitea.com`。
-然而，后来的更新删除了这些选项，现在唯一的选项是 `github` 和 `self`，默认值为 `github`。
-但是，如果您想要使用其他 Git 服务器中的操作，您可以在 `uses` 字段中使用完整的 URL，Gitea 支持此功能（GitHub 不支持）。
-例如 `uses: https://gitea.com/actions/checkout@v4` 或 `uses: http://your-git-server/actions/checkout@v4`。
+`DEFAULT_ACTIONS_URL` 设置 runner 从何处下载未指定主机的操作。
+值为 `github` 时，`uses: actions/checkout@v4` 解析为 `https://github.com/actions/checkout@v4`，值为 `self` 时解析为 `<ROOT_URL>/actions/checkout@v4`。
+`self` 要求您将用到的所有操作镜像到您的实例，因此更推荐为每个操作单独指明主机：使用 `uses: self:owner/repo@ref` 指向您的实例，或使用完整 URL（如 `uses: https://gitea.com/actions/checkout@v4`）指向任何其他主机。

 ## 其他 (`other`)

@@ -14,6 +14,8 @@ aliases:
 2. 将 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
 3. 确保反向代理不会解码 URI。`https://git.example.com/a%2Fb`的请求应该被传递给 `http://gitea:3000/a%2Fb`。
 4. 确保 `Host` 和 `X-Forwarded-Proto` 头被正确的传递给 Gitea，使 Gitea 可以看到正在访问的真实 URL。
+5. 确保 Web 服务器有完整的证书（包括所有中间证书和根证书），以便 `git clone` 和 `git pull` 正常工作。
+6. Gitea 会在 `/-/ws` 使用 WebSocket 连接，用于通知计数等实时更新。请确保反向代理使用 HTTP/1.1，并转发 `Upgrade` 和 `Connection` 头，参见下面的示例。否则 Gitea 会回退为定期轮询。

 ## 使用子路径

@@ -39,6 +41,7 @@ server {
    location / {
        client_max_body_size 512M;
        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
@@ -61,8 +64,9 @@ server {

        # 确保 nginx 使用未转义 URI， 按原样保持 "%2F"。 确保 nginx 去除 "/gitea" 子路径前缀， 按原样传递 "/v2"。
        rewrite ^ $request_uri;
-        rewrite ^(/gitea)?(/.*) $2 break;
+        rewrite ^/(gitea($|/))?(.*) /$3 break;
        proxy_pass http://127.0.0.1:3000$uri;
+        proxy_http_version 1.1;

        # 其他的常规 HTTP 表头，见上面“使用 Nginx 作为反向代理服务”小节的配置
        proxy_set_header Connection $http_connection;
@@ -107,6 +111,7 @@ server {
    }

    location / {
+        # 其他指令见上面「使用 Nginx 作为反向代理服务」小节
        proxy_pass http://localhost:3000;
    }
 }
@@ -123,6 +128,7 @@ server {
    server_name git.example.com;

    location / {
+        # 其他指令见上面「使用 Nginx 作为反向代理服务」小节
        proxy_pass http://localhost:3000;
    }
 }
@@ -144,6 +150,20 @@ server {
 }
 ```

+## Nginx Proxy Manager
+
+如果使用 Nginx Proxy Manager 作为 Gitea 的反向代理，配置与原生 Nginx 略有不同。
+
+它会[默认给自定义 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf)，因此上面 Nginx 配置里对应的指令不要再写一遍。否则会因为指令重复（尤其是 `proxy_set_header Host $host`）出现 `400 bad request`。
+
+创建 `/` 自定义 location 时，只需在其配置中加入：
+
+```nginx
+client_max_body_size 512M;
+```
+
+在代理主机上启用 `Websockets Support`，Nginx Proxy Manager 会自行加入 WebSocket 相关指令。再额外添加 `proxy_http_version` 会导致 Nginx 拒绝启动。
+
 ## 使用 Apache HTTPD 作为反向代理服务

 如果您想使用 Apache HTTPD 作为 Gitea 的反向代理服务，您可以为您的 Apache HTTPD 作如下配置（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
@@ -154,30 +174,23 @@ server {
    ProxyPreserveHost On
    ProxyRequests off
    AllowEncodedSlashes NoDecode
-    ProxyPass / http://localhost:3000/ nocanon
+    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```

-注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
+:::note
+必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。
+
+`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本。更旧的版本**必须**去掉它，否则 Apache HTTPD 将无法启动。
+:::
+
+如果希望用 Let's Encrypt 的 webroot 验证，请在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`，避免把这些请求代理到 Gitea。

 ## 使用 Apache HTTPD 作为反向代理服务并将 Gitea 路由至一个子路径

 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下配置为 Gitea 添加路由规则（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：

-```
-<VirtualHost *:80>
-    ...
-    <Proxy *>
-         Order allow,deny
-         Allow from all
-    </Proxy>
-    AllowEncodedSlashes NoDecode
-    # 注意: 路径和 URL 后面都不要写路径符号 '/'
-    ProxyPass /git http://localhost:3000 nocanon
-</VirtualHost>
-```
-
 ```apacheconf
 <VirtualHost *:80>
    ...
@@ -187,7 +200,7 @@ server {
    </Proxy>
    AllowEncodedSlashes NoDecode
    # 注意: 路径和 URL 后面都不要写路径符号 '/'
-    ProxyPass /git http://localhost:3000 nocanon
+    ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
    ProxyPreserveHost On
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
@@ -195,7 +208,55 @@ server {

 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。

-注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
+:::note
+必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更旧的版本请去掉它。
+:::
+
+## 使用 Apache HTTPD 直接提供静态资源
+
+我们可以通过将资源分为静态和动态两种类型来调节性能。
+
+CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
+
+Apache HTTPD 可以直接提供静态资源，并且只代理动态资源请求给 Gitea。
+
+将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea/`。
+在此之后，在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下，我们只对 `public/` 目录感兴趣，您可以删除剩下的其他目录。
+（为了生成静态资源，您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
+
+取决于您的用户量的大小，您可以将流量分离到两个不同的服务器，或者为静态资源配置一个 cdn。
+
+### 单服务器节点，单域名
+
+将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件：
+
+```apacheconf
+<VirtualHost *:80>
+    ...
+    <Proxy *>
+         Order allow,deny
+         Allow from all
+    </Proxy>
+
+    ProxyPass /_/static/ !
+    Alias /_/static/ /path/to/gitea/public/
+    <Directory /path/to/gitea/public/>
+        Options FollowSymlinks
+		AllowOverride None
+		Require all granted
+    </Directory>
+
+    AllowEncodedSlashes NoDecode
+    # 注意: 路径和 URL 后面都不要写路径符号 '/'
+    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
+    ProxyPreserveHost On
+    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+</VirtualHost>
+```
+
+:::note
+必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更旧的版本请去掉它。
+:::

 ## 使用 Caddy 作为反向代理服务

@@ -231,11 +292,13 @@ git.example.com {

 - 使用 Microsoft Web Platform Installer 5.1 (WebPI) 安装 Application Request Routing（简称 ARR），或者在 [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing) 下载这个插件。
 - 一但这个模块被安装到 IIS 上，你将会在 IIS 管理控制台看到一个叫做 URL Rewrite 的新图标。
+- 安装 Windows 功能 `WebSocket Protocol`，否则 ARR 无法代理 Gitea 的 WebSocket 端点。
 - 打开 IIS 管理控制台，在左边的列表中点击 `Gitea Proxy` 网页。在中间选中并且双击 URL Rewrite 的图标来加载 URL 重写的面板。
 - 在管理控制台的右边选择 `Add Rule` 操作，并且在 `Inbound and Outbound Rules` 分类中选择 `Reverse Proxy Rule`。
 - 在 Inbound Rules 中， 将 server name 设置为 Gitea 正在运行的主机以及对应端口。例如，如果你在 localhost 的 3000 端口上运行 Gitea，则设置为 `127.0.0.1:3000`。
 - 启用 SSL Offloading
 - 在 Outbound Rules 中，确保设置了 `Rewrite the domain names of the links in HTTP response`，并且将 `From:` 设置为上面的 server name，将 `To:` 设置为你的外部访问名称，例如：`git.example.com`
+- 关闭 Application Request Routing 的 `Server Proxy Settings` 中的 `Reverse rewrite host in response headers`（在 IIS 管理器中选择服务器节点，打开 `Application Request Routing Cache`，再打开右侧的 `Server Proxy Settings`）。若保持开启，ARR 会把 `Location` 头里的主机改回内部地址，导致登录或表单提交后的重定向把浏览器送到 `127.0.0.1:3000` 而不是 `git.example.com`。
 - 现在，根据下面的内容为您的网页编辑 `web.config`（将 `127.0.0.1:3000` 和 `git.example.com` 改为适当的值）

 ```xml
@@ -12,6 +12,7 @@ aliases:

 通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。

+<a id="authentication"></a>
 ## 通过 API 认证

 Gitea 支持以下几种 API 认证方式：
@@ -12,7 +12,7 @@ aliases:

 接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。

-**注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](development/hacking-on-gitea.md) 中给出的建议。
+**注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md) 中给出的建议。

 ## 下载

@@ -53,7 +53,7 @@ git checkout @sourceVersion@  # or git checkout pr-xyz

 - `go` @minGoVersion@ 或更高版本，请参阅 [这里](https://go.dev/dl/)
 - `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/)
- `make`, 请参阅 [这里](development/hacking-on-gitea.md)
+- `make`, 请参阅 [这里](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)

 为了尽可能简化编译过程，提供了各种 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。

@@ -53,7 +53,7 @@ sudo chown 1000:1000 config/ data/

 > 如果未为卷设置正确的权限，容器可能无法启动。

-对于稳定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的开发版本，则可以使用 `:dev-rootless` 标签。如果您想运行发布分支的最新提交，可以使用 `:1.x-dev-rootless` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.16-dev-rootless`）。
+对于稳定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的开发版本，则可以使用 `:main-nightly-rootless` 标签。如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly-rootless` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly-rootless`）。

 ## 自定义端口

@@ -14,7 +14,7 @@ Gitea 在其 Docker Hub 组织内提供自动更新的 Docker 镜像。可以始

 ## 基本

-最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 将安装当前的开发版本。对于稳定的发行版，您可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。
+最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 安装的是最新的稳定版本。对于稳定的发行版，您也可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。如果您想使用最新的开发版本，则可以使用 `:main-nightly` 标签；如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly`）。

 ```yaml
 version: "3"
@@ -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/)。

 ### 支持非标准的调度语法 @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有什么区别？

-![labels](/images/usage/actions/labels.png)
-
-代理标签是由 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** > **常规**页面并添加协作所有者。
+协作所有者的私有仓库可以访问当前仓库中的Actions和工作流。
+
+如需在同一用户或组织内共享，请改为在该用户或组织的**设置** > **Actions** > **常规** > **跨仓库访问**中添加这些私有仓库。
+参见[跨仓库访问](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会使用所配置的默认模式：
+
+- **宽松**：对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拉取请求的工作流永远不会获得对私有仓库的跨仓库访问权限，即使这些仓库已被列出。
@@ -761,7 +761,7 @@ Gitea 创建以下非唯一队列：
  - none = 不显示任何头像
  - random = 生成随机头像
  - image = 使用默认图像（在 `REPOSITORY_AVATAR_FALLBACK_IMAGE` 中设置），如果设置为 image 并且未上传任何图像。
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。
+- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **_empty_**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。该值将原样使用，不会自动添加 `ROOT_URL` 中的子路径。留空则使用 Gitea 内置的仓库头像。

 ## 项目 (`project`)

@@ -969,7 +969,7 @@ Gitea 创建以下非唯一队列：

 - `ENABLED`: **false**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
 - `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。

@@ -766,7 +766,7 @@ Gitea 创建以下非唯一队列：
  - none = 不显示任何头像
  - random = 生成随机头像
  - image = 使用默认图像（在 `REPOSITORY_AVATAR_FALLBACK_IMAGE` 中设置），如果设置为 image 并且未上传任何图像。
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。
+- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **_empty_**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。该值将原样使用，不会自动添加 `ROOT_URL` 中的子路径。留空则使用 Gitea 内置的仓库头像。

 ## 项目 (`project`)

@@ -975,7 +975,7 @@ Gitea 创建以下非唯一队列：

 - `ENABLED`: **false**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
 - `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。

@@ -781,7 +781,7 @@ Gitea 创建以下非唯一队列：
  - none = 不显示任何头像
  - random = 生成随机头像
  - image = 使用默认图像（在 `REPOSITORY_AVATAR_FALLBACK_IMAGE` 中设置），如果设置为 image 并且未上传任何图像。
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。
+- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **_empty_**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。该值将原样使用，不会自动添加 `ROOT_URL` 中的子路径。留空则使用 Gitea 内置的仓库头像。

 ## 项目 (`project`)

@@ -990,7 +990,7 @@ Gitea 创建以下非唯一队列：

 - `ENABLED`: **false**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
 - `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。

@@ -781,7 +781,7 @@ Gitea 创建以下非唯一队列：
  - none = 不显示任何头像
  - random = 生成随机头像
  - image = 使用默认图像（在 `REPOSITORY_AVATAR_FALLBACK_IMAGE` 中设置），如果设置为 image 并且未上传任何图像。
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。
+- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **_empty_**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。该值将原样使用，不会自动添加 `ROOT_URL` 中的子路径。留空则使用 Gitea 内置的仓库头像。

 ## 项目 (`project`)

@@ -990,7 +990,7 @@ Gitea 创建以下非唯一队列：

 - `ENABLED`: **false**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
 - `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。

@@ -839,7 +839,7 @@ In-Reply-To =
  - none = 不显示任何头像
  - random = 生成随机头像
  - image = 使用默认图像（在 `REPOSITORY_AVATAR_FALLBACK_IMAGE` 中设置），如果设置为 image 并且未上传任何图像。
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。
+- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **_empty_**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。该值将原样使用，不会自动添加 `ROOT_URL` 中的子路径。留空则使用 Gitea 内置的仓库头像。

 ## 项目 (`project`)

@@ -1101,7 +1101,7 @@ In-Reply-To =

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `ENABLE_SUCCESS_NOTICE`: **true**: 设置为 false 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 168h**: Cron 语法，用于安排任务，例如 `@every 168h`。
 - `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: Gitea 用于检查新版本的端点。

@@ -1109,7 +1109,7 @@ In-Reply-To =

 - `ENABLED`: **false**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
 - `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。

@@ -1129,35 +1129,35 @@ In-Reply-To =

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@annually**: Cron 语法，用于设置重建索引的频率。

 #### Cron - 停止长时间未更新的运行中任务 (`cron.stop_zombie_tasks`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 5m**: Cron 语法，用于设置检查的频率。

 #### Cron - 停止持续更新但长时间未结束的运行中任务 (`cron.stop_endless_tasks`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 30m**: Cron 语法，用于设置检查的频率。

 #### Cron - 取消长时间未被领取的任务 (`cron.cancel_abandoned_jobs`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 6h**: Cron 语法，用于设置检查的频率。

 #### Cron - 启动基于定时的 Actions (`cron.start_schedule_tasks`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 1m**: Cron 语法，用于设置调度任务的频率。

 ## Git (`git`)
@@ -367,7 +367,7 @@ aliases:
 - `SSH_SERVER_CIPHERS`: **[email protected], aes128-ctr, aes192-ctr, aes256-ctr, [email protected], [email protected]**: 对于内置的 SSH 服务器，选择支持的 SSH 连接的加密方法，对于系统 SSH，此设置无效。
 - `SSH_SERVER_KEY_EXCHANGES`: **curve25519-sha256, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group14-sha256, diffie-hellman-group14-sha1**: 对于内置 SSH 服务器，选择支持的 SSH 连接的密钥交换算法，对于系统 SSH，此设置无效。
 - `SSH_SERVER_MACS`: **[email protected], hmac-sha2-256, hmac-sha1**: 对于内置 SSH 服务器，选择支持的 SSH 连接的 MAC 算法，对于系统 SSH，此设置无效。
- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gogs.rsa**: 对于内置 SSH 服务器，选择要提供为主机密钥的密钥对。私钥应在 `SSH_SERVER_HOST_KEY` 中，公钥在 `SSH_SERVER_HOST_KEY.pub` 中。相对路径会相对于 `APP_DATA_PATH` 转为绝对路径。如果不存在密钥，将为您创建一个 4096 位的 RSA 密钥。
+- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gitea.ed25519, ssh/gitea.ecdsa, ssh/gogs.rsa**: 对于内置 SSH 服务器，选择要提供为主机密钥的密钥对。私钥应在 `SSH_SERVER_HOST_KEY` 中，公钥在 `SSH_SERVER_HOST_KEY.pub` 中。相对路径会相对于 `APP_DATA_PATH` 转为绝对路径。如果所有密钥都不存在，将为您创建 4096 位的 RSA、256 位的 ECDSA 和 ED25519 密钥。
 - `SSH_KEY_TEST_PATH`: **/tmp**: 在使用 `ssh-keygen` 测试公共 SSH 密钥时要在其中创建临时文件的目录，默认为系统临时目录。
 - `SSH_KEYGEN_PATH`: **_empty_**: 使用 `ssh-keygen` 解析公共 SSH 密钥。该值将传递给 shell。默认情况下，Gitea 会自行进行解析。
 - `SSH_EXPOSE_ANONYMOUS`: **false**: 启用将 SSH 克隆 URL 暴露给匿名访问者，默认为 false。
@@ -844,7 +844,7 @@ In-Reply-To =
  - none = 不显示任何头像
  - random = 生成随机头像
  - image = 使用默认图像（在 `REPOSITORY_AVATAR_FALLBACK_IMAGE` 中设置），如果设置为 image 并且未上传任何图像。
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。
+- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **_empty_**: 作为默认仓库头像的图像（如果将 `REPOSITORY_AVATAR_FALLBACK` 设置为 image 并且没有上传图像）。该值将原样使用，不会自动添加 `ROOT_URL` 中的子路径。留空则使用 Gitea 内置的仓库头像。

 ## 项目 (`project`)

@@ -1106,7 +1106,7 @@ In-Reply-To =

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `ENABLE_SUCCESS_NOTICE`: **true**: 设置为 false 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 168h**: Cron 语法，用于安排任务，例如 `@every 168h`。
 - `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: Gitea 用于检查新版本的端点。

@@ -1114,7 +1114,7 @@ In-Reply-To =

 - `ENABLED`: **false**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
 - `OLDER_THAN`: **8760h**: 早于此表达式的任何系统通知都将从数据库中删除。

@@ -1134,35 +1134,35 @@ In-Reply-To =

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@annually**: Cron 语法，用于设置重建索引的频率。

 #### Cron - 停止长时间未更新的运行中任务 (`cron.stop_zombie_tasks`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 5m**: Cron 语法，用于设置检查的频率。

 #### Cron - 停止持续更新但长时间未结束的运行中任务 (`cron.stop_endless_tasks`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 30m**: Cron 语法，用于设置检查的频率。

 #### Cron - 取消长时间未被领取的任务 (`cron.cancel_abandoned_jobs`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 6h**: Cron 语法，用于设置检查的频率。

 #### Cron - 启动基于定时的 Actions (`cron.start_schedule_tasks`)

 - `ENABLED`: **true**: 启用服务。
 - `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 1m**: Cron 语法，用于设置调度任务的频率。

 ## Git (`git`)
@@ -14,6 +14,7 @@ aliases:
 2. 将 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
 3. 确保反向代理不会解码 URI。`https://git.example.com/a%2Fb`的请求应该被传递给 `http://gitea:3000/a%2Fb`。
 4. 确保 `Host` 和 `X-Forwarded-Proto` 头被正确的传递给 Gitea，使 Gitea 可以看到正在访问的真实 URL。
+5. 确保 Web 服务器有完整的证书（包括所有中间证书和根证书），以便 `git clone` 和 `git pull` 正常工作。

 ## 使用子路径

@@ -61,7 +62,7 @@ server {

        # 确保 nginx 使用未转义 URI， 按原样保持 "%2F"。 确保 nginx 去除 "/gitea" 子路径前缀， 按原样传递 "/v2"。
        rewrite ^ $request_uri;
-        rewrite ^(/gitea)?(/.*) $2 break;
+        rewrite ^/(gitea($|/))?(.*) /$3 break;
        proxy_pass http://127.0.0.1:3000$uri;

        # 其他的常规 HTTP 表头，见上面“使用 Nginx 作为反向代理服务”小节的配置
@@ -75,7 +76,7 @@ server {
 }
 ```

-然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
+然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/gitea/` 的配置项。

 ## 使用 Nginx 直接提供静态资源

@@ -144,6 +145,20 @@ server {
 }
 ```

+## Nginx Proxy Manager
+
+如果使用 Nginx Proxy Manager 作为 Gitea 的反向代理，配置与原生 Nginx 略有不同。
+
+它会[默认给自定义 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf)，因此上面 Nginx 配置里对应的指令不要再写一遍。否则会因为指令重复（尤其是 `proxy_set_header Host $host`）出现 `400 bad request`。
+
+创建 `/` 自定义 location 时，只需在其配置中加入：
+
+```nginx
+client_max_body_size 512M;
+proxy_set_header Connection $http_connection;
+proxy_set_header Upgrade $http_upgrade;
+```
+
 ## 使用 Apache HTTPD 作为反向代理服务

 如果您想使用 Apache HTTPD 作为 Gitea 的反向代理服务，您可以为您的 Apache HTTPD 作如下配置（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
@@ -161,23 +176,12 @@ server {

 注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`

+如果希望用 Let's Encrypt 的 webroot 验证，请在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`，避免把这些请求代理到 Gitea。
+
 ## 使用 Apache HTTPD 作为反向代理服务并将 Gitea 路由至一个子路径

 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下配置为 Gitea 添加路由规则（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：

-```
-<VirtualHost *:80>
-    ...
-    <Proxy *>
-         Order allow,deny
-         Allow from all
-    </Proxy>
-    AllowEncodedSlashes NoDecode
-    # 注意: 路径和 URL 后面都不要写路径符号 '/'
-    ProxyPass /git http://localhost:3000 nocanon
-</VirtualHost>
-```
-
 ```apacheconf
 <VirtualHost *:80>
    ...
@@ -197,6 +201,48 @@ server {

 注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`

+## 使用 Apache HTTPD 直接提供静态资源
+
+我们可以通过将资源分为静态和动态两种类型来调节性能。
+
+CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
+
+Apache HTTPD 可以直接提供静态资源，并且只代理动态资源请求给 Gitea。
+
+将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea/`。
+在此之后，在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下，我们只对 `public/` 目录感兴趣，您可以删除剩下的其他目录。
+（为了生成静态资源，您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
+
+取决于您的用户量的大小，您可以将流量分离到两个不同的服务器，或者为静态资源配置一个 cdn。
+
+### 单服务器节点，单域名
+
+将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件：
+
+```apacheconf
+<VirtualHost *:80>
+    ...
+    <Proxy *>
+         Order allow,deny
+         Allow from all
+    </Proxy>
+
+    ProxyPass /_/static/ !
+    Alias /_/static/ /path/to/gitea/public/
+    <Directory /path/to/gitea/public/>
+        Options FollowSymlinks
+		AllowOverride None
+		Require all granted
+    </Directory>
+
+    AllowEncodedSlashes NoDecode
+    # 注意: 路径和 URL 后面都不要写路径符号 '/'
+    ProxyPass / http://localhost:3000/ nocanon
+    ProxyPreserveHost On
+    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+</VirtualHost>
+```
+
 ## 使用 Caddy 作为反向代理服务

 如果您想使用 Caddy 作为 Gitea 的反向代理服务，您可以在 `Caddyfile` 中添加如下配置：
@@ -12,7 +12,7 @@ aliases:

 接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。

-**注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](development/hacking-on-gitea.md) 中给出的建议。
+**注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md) 中给出的建议。

 ## 下载

@@ -53,7 +53,7 @@ git checkout @sourceVersion@  # or git checkout pr-xyz

 - `go` @minGoVersion@ 或更高版本，请参阅 [这里](https://go.dev/dl/)
 - `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/)
- `make`, 请参阅 [这里](development/hacking-on-gitea.md)
+- `make`, 请参阅 [这里](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)

 为了尽可能简化编译过程，提供了各种 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。

@@ -53,7 +53,7 @@ sudo chown 1000:1000 config/ data/

 > 如果未为卷设置正确的权限，容器可能无法启动。

-对于稳定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的开发版本，则可以使用 `:dev-rootless` 标签。如果您想运行发布分支的最新提交，可以使用 `:1.x-dev-rootless` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.16-dev-rootless`）。
+对于稳定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的开发版本，则可以使用 `:main-nightly-rootless` 标签。如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly-rootless` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly-rootless`）。

 ## 自定义端口

@@ -14,7 +14,7 @@ Gitea 在其 Docker Hub 组织内提供自动更新的 Docker 镜像。可以始

 ## 基本

-最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 将安装当前的开发版本。对于稳定的发行版，您可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。
+最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 安装的是最新的稳定版本。对于稳定的发行版，您也可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。如果您想使用最新的开发版本，则可以使用 `:main-nightly` 标签；如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly`）。

 ```yaml
 version: "3"
@@ -0,0 +1,29 @@
+{
+  "sidebar.docs.category.Installation": {
+    "message": "安装"
+  },
+  "sidebar.docs.category.Administration": {
+    "message": "管理"
+  },
+  "sidebar.docs.category.Usage": {
+    "message": "使用"
+  },
+  "sidebar.docs.category.actions": {
+    "message": "Actions"
+  },
+  "sidebar.docs.category.packages": {
+    "message": "软件包"
+  },
+  "sidebar.docs.category.Development": {
+    "message": "开发"
+  },
+  "sidebar.docs.category.Contributing": {
+    "message": "贡献"
+  },
+  "sidebar.docs.category.Help": {
+    "message": "帮助"
+  },
+  "sidebar.docs.doc.What is Gitea?": {
+    "message": "Gitea是什么?"
+  }
+}
@@ -0,0 +1,9 @@
+{
+  "label": "运维",
+  "position": 30,
+  "link": {
+    "type": "generated-index",
+    "slug": "/administration",
+    "title": "运维"
+  }
+}
@@ -0,0 +1,34 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: adding-legal-pages
+sidebar_position: 110
+
+aliases:
+  - /zh-cn/adding-legal-pages
+---
+
+# 添加法律页面
+
+一些法域（例如欧盟）要求在网站上添加特定的法律页面（例如隐私政策）。按照以下步骤将它们添加到你的 Gitea 实例中。
+
+## 获取页面
+
+Gitea 源代码附带了示例页面，位于 `contrib/service/sample-page` 目录中。将它们复制到 `custom/public/assets/` 目录下。例如，如果要添加隐私政策：
+
+```
+wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/service/sample-page/privacy.html.sample
+```
+
+现在，你需要编辑该页面以满足你的需求。特别是，你必须更改电子邮件地址、网址以及与 "Your Gitea Instance" 相关的引用，以匹配你的情况。
+
+请务必不要放置会暗示 Gitea 项目对你的服务器负责的一般服务条款或隐私声明。
+
+## 使其可见
+
+创建或追加到 `/path/to/custom/templates/custom/extra_links_footer.tmpl` 文件中：
+
+```go
+<a class="item" href="{{AppSubUrl}}/assets/privacy.html">隐私政策</a>
+```
+
+重启 Gitea 以查看更改。
@@ -0,0 +1,301 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+slug: "authentication"
+sidebar_position: 10
+aliases:
+  - /zh-cn/authentication
+---
+
+# 认证
+
+## 轻量级目录访问协议（Lightweight Directory Access Protocol，LDAP）
+
+通过 BindDN 的 LDAP 和简单认证方式 LDAP 共享以下字段:
+
+- 认证名称 **(必选)**
+
+  - 分配给新授权方法的名称。
+
+- 主机名 **(必选)**
+
+  - LDAP 服务的主机地址.
+  - 例如:`mydomain.com`
+
+- 端口号 **(必选)**
+
+  - LDAP 服务的端口号.
+  - 例如: LDAP `389`/ LDAPs `636`
+
+- 安全协议 (可选)
+
+  - 连接 LDAP 服务器时是否使用 TLS 协议。
+
+- 管理员过滤规则 (可选)
+
+  - 一个 LDAP 过滤器，用于指定哪些用户应该被赋予管理员特权。如果用户帐户符合过滤器条件，则该用户将被授予管理员权限。
+  - 示例:`(objectClass=adminAccount)`
+  - 适用于 Microsoft Active Directory（AD）的示例:`memberOf=CN=admin-group,OU=example,DC=example,DC=org`
+
+- 用户名属性（可选）
+
+  - 用户 LDAP 记录中包含用户名称的属性。在第一次成功登录后，将使用指定的属性值作为新的 Gitea 账户用户名。若留空，则使用登录表单上提供的用户名。
+  - 当提供的登录名与多个属性匹配时，这一选项非常有用，但是只有一个特定属性应该用于 Gitea 账户名称，请参阅"用户过滤器"。
+  - 示例:uid
+  - 适用于 Microsoft Active Directory（AD）的示例:`sAMAccountName`
+
+- 名字属性（可选）
+
+  - 用户 LDAP 记录中包含用户名字的属性。将用于填充他们的账户信息。
+  - 示例:givenName
+
+- 姓氏属性（可选）
+
+  - 用户 LDAP 记录中包含用户姓氏的属性。将用于填充他们的账户信息。
+  - 示例:`sn`
+
+- 电子邮件属性 **(必选)**
+  - 用户 LDAP 记录中包含用户电子邮件地址的属性。将用于填充他们的账户信息。
+  - 示例:`mail`
+
+### LDAP(via BindDN)
+
+需要额外设置以下字段:
+
+- 绑定 DN (可选)
+
+  - 搜索用户时绑定到 LDAP 服务器的 DN。这可以留空以执行匿名搜索。
+  - 示例: `cn=Search,dc=mydomain,dc=com`
+
+- 绑定密码 (可选)
+
+  - 上述指定的 Bind DN（绑定区别名）的密码，如果有的话。注意：该密码在服务器上使用 SECRET_KEY 进行加密存储。仍然建议确保 Bind DN 具有尽可能少的权限。
+
+- 用户搜索基准 **(必选)**
+
+  - 这是用于搜索用户帐户的 LDAP 基础路径.
+  - 示例: `ou=Users,dc=mydomain,dc=com`
+
+- 用户过滤规则 **(必选)**
+  - LDAP 过滤器声明如何查找试图进行身份验证的用户记录
+    `%[1]s`匹配参数将替换为登录表单中给出的登录名
+  - 示例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
+  - 示例 for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
+  - 如需多次替换，应使用 `%[1]s`，例如在将提供的登录名与多个属性（如用户标识符、电子邮件甚至电话号码）进行匹配时。
+  - 示例: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))`
+- 启用用户同步
+  - 这个选项启用了一个周期性任务，用于将 Gitea 用户与 LDAP 服务器进行同步。默认的同步周期是每 24 小时，
+    但您可以在 app.ini 文件中进行更改。
+    有关此部分的详细说明，请参阅[sample
+    app.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
+    的*cron.sync_external_users* 部分的注释。前面提到的*User Search Base*和*User Filter*
+    设置将限制哪些用户可以使用 Gitea 以及哪些用户将被同步。
+    在初始运行任务时，将根据给定的设置创建所有与 LDAP 匹配的用户，因此在使用大型企业 LDAP 目录时需要小心。
+
+### LDAP(simple auth)
+
+需要额外设置以下字段:
+
+- 用户 DN **(必选)**
+
+  - 用作用户 DN 的模板。匹配参数 `%s` 将替换为登录表单中的登录名。
+  - 示例: `cn=%s,ou=Users,dc=mydomain,dc=com`
+  - 示例: `uid=%s,ou=Users,dc=mydomain,dc=com`
+
+- 用户搜索基准 (可选)
+
+  - 用户搜索基准声明哪些用户帐户将被搜索.
+  - 示例: `ou=Users,dc=mydomain,dc=com`
+
+- 用户过滤规则 **(必选)**
+  - LDAP 过滤器声明何时允许用户登录
+    `%[1]s`匹配参数将替换为登录表单中给出的登录名。
+  - 示例: `(&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))`
+  - 示例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
+
+### 使用 LDAP 验证分组成员
+
+使用以下字段:
+
+- 群组搜索基础 DN(可选)
+
+  - 组使用的 LDAP DN。
+  - 示例: `ou=group,dc=mydomain,dc=com`
+
+- 组名过滤器 (可选)
+
+  - LDAP 过滤器，声明如何在上述 DN 中查找有效组。
+  - 示例: `(|(cn=gitea_users)(cn=admins))`
+
+- 组中的用户属性 (可选)
+
+  - 组中列出了哪个用户的 LDAP 属性。
+  - 示例: `uid`
+
+- 用户组属性 (可选)
+  - 哪个组的 LDAP 属性包含一个高于用户属性名称的数组。
+  - 示例: `memberUid`
+
+## 可插拔式认证模块(Pluggable Authentication Module,PAM)
+
+这个过程启用了 PAM（Pluggable Authentication Modules）认证。用户仍然可以通过用户管理手动添加到系统中。
+PAM 提供了一种机制，通过对用户进行 PAM 认证来自动将其添加到当前数据库中。为了与普通的 Linux 密码一起使用，
+运行 Gitea 的用户还必须具有对`/etc/shadow`的读取权限，以便在使用公钥登录时检查账户的有效性。
+
+**注意**:如果用户已将 SSH 公钥添加到 Gitea 中，使用这些密钥可能会绕过登录检查系统。因此，
+如果您希望禁用使用 PAM 进行身份验证的用户，应该在 Gitea 中手动禁用该账户，使用内置的用户管理功能。
+
+1. 配置和安装准备.
+   - 建议您创建一个管理用户.
+   - 建议取消自动注册.
+1. 一旦数据库已初始化完成，使用新创建的管理员账户登录.
+1. 导航至用户设置（右上角的图标），然后选择
+   `Site Administration` -> `Authentication Sources`, 并选择
+   `Add Authentication Source`.
+1. 填写字段如下:
+   - 认证类型:`PAM`。
+   - 名称:任何有效的值都可以，如果您愿意，可以使用"System Authentication"。
+   - PAM 服务名称:从/etc/pam.d/目录下选择适用于所需认证的正确文件[^1]。
+   - PAM 电子邮件域:用户认证时要附加的电子邮件后缀。例如，如果登录系统期望一个名为 gituse 的用户，
+     并且将此字段设置为 mail.com，那么 Gitea 在验证一个 GIT 实例的用户时将期望 user emai 字段为gituser@mail.com[^2]。
+
+**Note**: PAM 支持通过[build-time flags](installation/from-source.md#build)添加,
+而官方提供的二进制文件通常不会默认启用此功能。PAM 需要确保系统上有必要的 libpam 动态库，并且编译器可以访问必要的 PAM 开发头文件。
+
+[^1]:
+    例如，在 Debian "Bullseye"上使用标准 Linux 登录，可以使用`common-session-noninteractive`。这个值对于其他版本的 Debian，
+    包括 Ubuntu 和 Mint，可能也是有效的，请查阅您所使用发行版的文档以确认。
+
+[^2]: **PAM 的必选项** 请注意:在上面的示例中，用户将作为`gituser`而不是`[email protected]`登录到 Gitea 的 Web 界面。
+
+## 简单邮件传输协议(Simple Mail Transfer Protocol,SMTP)
+
+此选项允许 Gitea 以 Gitea 用户身份登录 SMTP 主机。请设置以下字段:
+
+- 身份验证名称 **(必选)**
+
+  - 分配给新授权方法的名称
+
+- SMTP 验证类型 **(必选)**
+
+  - 用于连接 SMTP 主机的验证类型，plain 或 login
+
+- 主机名 **(必选)**
+
+  - SMTP 服务的主机地址
+  - 例如:`smtp.mydomain.com`
+
+- 端口号 **(必选)**
+
+  - SMTP 服务的端口号
+  - 例如: `587`
+
+- 允许的域名
+
+  - 如果使用公共 SMTP 主机或有多个域的 SMTP 主机，限制哪些域可以登录
+    限制哪些域可以登录。
+  - 示例: `gitea.com,mydomain.com,mydomain2.com`
+
+- 强制使用 SMTPS
+  - 默认情况下将使用 SMTPS 连接到端口 465.如果您希望将 smtp 用于其他端口，自行设置
+  - 否则，如果服务器提供' STARTTLS '扩展名，则将使用此扩展名
+- 跳过 TLS 验证
+  - 禁用 TLS 验证身份.
+- 该认证源处于激活状态
+  - 启用或禁用此身份验证源
+
+## FreeIPA
+
+- 要使用 FreeIPA 凭据登录 Gitea，需要为 Gitea 创建一个绑定帐户。
+  创建一个绑定帐户:
+- 在 FreeIPA 服务器上创建一个 gitea.ldif 文件，并将`dc=example,dc=com`替换为您的`dn`，然后提供一个适当安全的密码。
+
+  ```sh
+  dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
+  changetype: add
+  objectclass: account
+  objectclass: simplesecurityobject
+  uid: gitea
+  userPassword: secure password
+  passwordExpirationTime: 20380119031407Z
+  nsIdleTimeout: 0
+  ```
+
+- 导入 LDIF 文件（如果需要，请将 localhost 更改为 IPA 服务器）。系统会提示您输入 Directory Manager 的密码。:
+
+  ```sh
+  ldapmodify -h localhost -p 389 -x -D \
+  "cn=Directory Manager" -W -f gitea.ldif
+  ```
+
+- 为`gitea_users`添加 IPA 组:
+
+  ```sh
+  ipa group-add --desc="Gitea Users" gitea_users
+  ```
+
+- **提示**:对于 IPA 凭证错误，运行' kinit admin '并提供域管理帐户密码.
+- 以管理员身份登录 Gitea，点击 Admin Panel 下的`Authentication`。然后单击`Add New Source`并填写详细信息，更改所有适当的地方。
+
+## SPNEGO with SSPI (Kerberos/NTLM, for Windows only)
+
+Gitea 支持通过 Windows 内置的安全支持提供程序接口（Security Support Provider Interface，SSPI）实现 SPNEGO 单点登录认证（由 RFC4559 定义的方案），用于服务器的 Web 部分。SSPI 仅在 Windows 环境中工作，即当服务器和客户端都在 Windows 操作系统上运行时。
+
+在激活 SSPI 单点登录认证（SSO）之前，您需要准备您的环境:
+
+- 在 Active Directory 中创建一个单独的用户账户，gitea.exe 进程将在该账户下运行（例如，在 domain.local 域下创建一个名为 user 的账户:
+- 为运行 gitea.exe 的主机创建一个服务主体名称（Service Principal Name，SPN），其类别为 HTTP:
+
+  - 以特权域用户（例如域管理员）的身份启动“命令提示符”或“PowerShell”。
+  - 运行下面的命令，将 host.domain.local 替换为 Web 应用程序将运行的服务器的完全限定域名（FQDN），将 domain\user 替换为在前一步中创建的账户名称:
+
+  ```sh
+  setspn -A HTTP/host.domain.local domain\user
+  ```
+
+在遵循上述步骤之前，请确保您按照以下流程进行操作:
+
+1. 用之前创建的用户登录（如果已经登录，请先注销）。
+2. 确保在`custom/conf/app.ini`文件的`[server]`部分中，`ROOT_URL`设置为 Web 应用程序将运行的服务器的完全限定域名（FQDN），与之前创建服务主体名称时使用的一致（例如，`host.domain.local`）。
+3. 启动 Web 服务器（运行 `gitea.exe web`）。
+4. 在 `Site Administration -> Authentication Sources` 中添加一个 `SPNEGO with SSPI` 认证源，以启用 SSPI 认证。
+5. 在域中的客户端计算机上，使用任何域用户登录（与运行`gitea.exe`的服务器不同）。
+6. 如果您使用 Chrome 或 Edge 浏览器，请将 Web 应用程序的 URL 添加到“本地站点”（`Internet选项 -> 安全 -> 本地站点 -> 站点`）。
+7. 启动 Chrome 或 Edge 浏览器，导航到 Gitea 的 FQDN URL（例如，`http://host.domain.local:3000`）。
+8. 在控制面板中点击“Sign In”按钮，然后选择 SSPI，将会自动使用当前登录到计算机的用户进行登录。
+9. 如果无法正常工作，请确保:
+   - 您不是在运行`gitea.exe`的同一台服务器上运行 Web 浏览器。应该在与服务器不同的域加入计算机（客户端）上运行 Web 浏览器。如果客户端和服务器都在同一台计算机上运行，则 NTLM 将优先于 Kerberos。
+   - 主机上只有一个`HTTP/...`的 SPN。
+   - SPN 中只包含主机名，不包含端口号。
+   - 将 Web 应用程序的 URL 添加到"本地站点"。
+   - 服务器和客户端的时钟差异不超过 5 分钟（取决于组策略）。
+   - 在 Internet Explorer 中启用了"集成 Windows 身份验证"（在"高级设置"下）。
+
+遵循这些步骤，您应该能够成功启用和使用 SSPI 单点登录认证（SSO）。
+
+## 反向代理认证
+
+Gitea 支持通过读取反向代理传递的 HTTP 头中的登录名或者 email 地址来支持反向代理来认证。默认是不启用的，你可以用以下配置启用。
+
+```ini
+[service]
+ENABLE_REVERSE_PROXY_AUTHENTICATION = true
+```
+
+默认的登录用户名的 HTTP 头是 `X-WEBAUTH-USER`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_USER` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。
+
+默认的登录用户 Email 的 HTTP 头是 `X-WEBAUTH-EMAIL`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_EMAIL` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。你也可以通过修改 `ENABLE_REVERSE_PROXY_EMAIL` 来启用或停用这个 HTTP 头。
+
+如果设置了 `ENABLE_REVERSE_PROXY_FULL_NAME=true`，则用户的全名会从 `X-WEBAUTH-FULLNAME` 读取，这样在自动创建用户时将使用这个字段作为用户全名，你也可以通过修改 `REVERSE_PROXY_AUTHENTICATION_FULL_NAME` 来变更 HTTP 头。
+
+你也可以通过修改 `REVERSE_PROXY_TRUSTED_PROXIES` 来设置反向代理的 IP 地址范围，加强安全性，默认值是 `127.0.0.0/8,::1/128`。 通过 `REVERSE_PROXY_LIMIT`， 可以设置最多信任几级反向代理。
+
+你可以通过以下配置为 API 启用此认证方法：
+
+```ini
+[service]
+ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true
+```
+
+:::note
+当此方法用于 API 时，反向代理负责处理 CSRF 保护。
+:::
@@ -0,0 +1,146 @@
+---
+date: "2018-06-06T09:33:00+08:00"
+slug: "backup-and-restore"
+sidebar_position: 11
+
+aliases:
+  - /zh-cn/backup-and-restore
+---
+
+# 备份与恢复
+
+Gitea 已经实现了 `dump` 命令可以用来备份所有需要的文件到一个 zip 压缩文件。该压缩文件可以被用来进行数据恢复。
+
+## 备份一致性
+
+为了确保 Gitea 实例的一致性，在备份期间必须关闭它。
+
+Gitea 包括数据库、文件和 Git 仓库，当它被使用时所有这些都会发生变化。例如，当迁移正在进行时，在数据库中创建一个事务，而 Git 仓库正在被复制。如果备份发生在迁移的中间，Git 仓库可能是不完整的，尽管数据库声称它是完整的，因为它是在之后被转储的。避免这种竞争条件的唯一方法是在备份期间停止 Gitea 实例。
+
+## 备份命令 (`dump`)
+
+先转到 git 用户的权限: `su git`. 再 Gitea 目录运行 `./gitea dump`。一般会显示类似如下的输出：
+
+```
+2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
+2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
+2016/12/27 22:32:22 Dumping database...
+2016/12/27 22:32:22 Packing dump files...
+2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
+2016/12/27 22:32:34 Finish dumping in file gitea-dump-1482906742.zip
+```
+
+最后生成的 `gitea-dump-1482906742.zip` 文件将会包含如下内容：
+
+- `app.ini` - 如果原先存储在默认的 custom/ 目录之外，则是配置文件的可选副本
+- `custom/` - 所有保存在 `custom/` 目录下的配置和自定义的文件。
+- `data/` - 数据目录（APP_DATA_PATH），如果使用文件会话，则不包括会话。该目录包括 `attachments`、`avatars`、`lfs`、`indexers`、如果使用 SQLite 则包括 SQLite 文件。
+- `repos/` - 仓库目录的完整副本。
+- `gitea-db.sql` - 数据库 dump 出来的 SQL。
+- `log/` - Logs 文件，如果用作迁移不是必须的。
+
+中间备份文件将会在临时目录进行创建，如果您要重新指定临时目录，可以用 `--tempdir` 参数，或者用 `TMPDIR` 环境变量。
+
+## 备份数据库
+
+`gitea dump` 创建的 SQL 转储使用 XORM，Gitea 管理员可能更喜欢使用本地的 MySQL 和 PostgreSQL 转储工具。使用 XORM 转储数据库时仍然存在一些问题，可能会导致在尝试恢复时出现问题。
+
+```sh
+# mysql
+mysqldump -u$USER -p$PASS --databases $DATABASE > gitea-db.sql
+# postgres
+pg_dump -U $USER $DATABASE > gitea-db.sql
+```
+
+### 使用 Docker （`dump`）
+
+在使用 Docker 时，使用 `dump` 命令有一些注意事项。
+
+必须以 `gitea/conf/app.ini` 中指定的 `RUN_USER = <OS_USERNAME>` 执行该命令；并且，为了让备份文件夹的压缩过程能够顺利执行，`docker exec` 命令必须在 `--tempdir` 内部执行。
+
+示例：
+
+```none
+docker exec -u <OS_USERNAME> -it -w <--tempdir> $(docker ps -qf 'name=^<NAME_OF_DOCKER_CONTAINER>$') bash -c '/usr/local/bin/gitea dump -c </path/to/app.ini>'
+```
+
+\*注意：`--tempdir` 指的是 Gitea 使用的 Docker 环境的临时目录；如果您没有指定自定义的 `--tempdir`，那么 Gitea 将使用 `/tmp` 或 Docker 容器的 `TMPDIR` 环境变量。对于 `--tempdir`，请相应调整您的 `docker exec` 命令选项。
+
+结果应该是一个文件，存储在指定的 `--tempdir` 中，类似于：`gitea-dump-1482906742.zip`
+
+## 恢复命令 (`restore`)
+
+当前还没有恢复命令，恢复需要人工进行。主要是把文件和数据库进行恢复。
+
+例如：
+
+```sh
+unzip gitea-dump-1610949662.zip
+cd gitea-dump-1610949662
+mv app.ini /etc/gitea/conf/app.ini
+mv data/* /var/lib/gitea/data/
+mv log/* /var/lib/gitea/log/
+mv repos/* /var/lib/gitea/repositories/
+chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
+
+# mysql
+mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE <gitea-db.sql
+# sqlite3
+sqlite3 $DATABASE_PATH <gitea-db.sql
+# postgres
+psql -U $USER -d $DATABASE < gitea-db.sql
+
+service gitea restart
+```
+
+如果安装方式发生了变化（例如 二进制 -> Docker），或者 Gitea 安装到了与之前安装不同的目录，则需要重新生成仓库 Git 钩子。
+
+在 Gitea 运行时，并从 Gitea 二进制文件所在的目录执行：`./gitea admin regenerate hooks`
+
+这样可以确保仓库 Git 钩子中的应用程序和配置文件路径与当前安装一致。如果这些路径没有更新，仓库的 `push` 操作将失败。
+
+### 使用 Docker (`restore`)
+
+在基于 Docker 的 Gitea 实例中，也没有恢复命令的支持。恢复过程与前面描述的步骤相同，但路径不同。
+
+示例：
+
+```sh
+# 在容器中打开 bash 会话
+docker exec --user git -it 2a83b293548e bash
+# 在容器内解压您的备份文件
+unzip gitea-dump-1610949662.zip
+cd gitea-dump-1610949662
+# 恢复 Gitea 数据
+mv data/* /data/gitea
+# 恢复仓库本身
+mv repos/* /data/git/repositories/
+# 调整文件权限
+chown -R git:git /data
+# 重新生成 Git 钩子
+/usr/local/bin/gitea -c '/data/gitea/conf/app.ini' admin regenerate hooks
+```
+
+Gitea 容器中的默认用户是 `git`（1000:1000）。请用您的 Gitea 容器 ID 或名称替换 `2a83b293548e`。
+
+### 使用 Docker-rootless (`restore`)
+
+在 Docker-rootless 容器中的恢复工作流程只是要使用的目录不同：
+
+```sh
+# 在容器中打开 bash 会话
+docker exec --user git -it 2a83b293548e bash
+# 在容器内解压您的备份文件
+unzip gitea-dump-1610949662.zip
+cd gitea-dump-1610949662
+# 恢复 app.ini
+mv data/conf/app.ini /etc/gitea/app.ini
+# 恢复 Gitea 数据
+mv data/* /var/lib/gitea
+# 恢复仓库本身
+mv repos/* /var/lib/gitea/git/repositories
+# 调整文件权限
+chown -R git:git /etc/gitea/app.ini /var/lib/gitea
+# 重新生成 Git 钩子
+/usr/local/bin/gitea -c '/etc/gitea/app.ini' admin regenerate hooks
+```
@@ -0,0 +1,93 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "cmd-embedded"
+sidebar_position: 20
+
+aliases:
+  - /zh-cn/cmd-embedded
+---
+
+# 嵌入资源提取工具
+
+Gitea 的可执行文件包含了运行所需的所有资源：模板、图片、样式表和翻译文件。你可以通过在 `custom` 目录下的相应路径中放置替换文件来覆盖其中的任何资源（详见 [自定义 Gitea 配置](../administration/customizing-gitea.md)）。
+
+要获取嵌入资源的副本以进行编辑，可以使用 CLI 中的 `embedded` 命令，通过操作系统的 shell 执行。
+
+**注意：** 嵌入资源提取工具包含在 Gitea 1.12 及以上版本中。
+
+## 资源列表
+
+要列出嵌入在 Gitea 可执行文件中的资源，请使用以下语法：
+
+```sh
+gitea embedded list [--include-vendored] [patterns...]
+```
+
+`--include-vendored` 标志使命令包括被供应的文件，这些文件通常被排除在外；即来自外部库的文件，这些文件是 Gitea 所需的（例如 [octicons](https://octicons.github.com/) 等）。
+
+可以提供一系列文件搜索模式。Gitea 使用 [gobwas/glob](https://github.com/gobwas/glob) 作为其 glob 语法。以下是一些示例：
+
+- 列出所有模板文件，无论在哪个虚拟目录下：`**.tmpl`
+- 列出所有邮件模板文件：`templates/mail/**.tmpl`
+  列出 `public/assets/img` 目录下的所有文件：`public/assets/img/**`
+
+不要忘记为模式使用引号，因为空格、`*` 和其他字符可能对命令行解释器有特殊含义。
+
+如果未提供模式，则列出所有文件。
+
+### 示例：列出所有嵌入文件
+
+列出所有路径中包含 `openid` 的嵌入文件：
+
+```sh
+$ gitea embedded list '**openid**'
+public/assets/img/auth/openid_connect.svg
+public/assets/img/openid-16x16.png
+templates/user/auth/finalize_openid.tmpl
+templates/user/auth/signin_openid.tmpl
+templates/user/auth/signup_openid_connect.tmpl
+templates/user/auth/signup_openid_navbar.tmpl
+templates/user/auth/signup_openid_register.tmpl
+templates/user/settings/security_openid.tmpl
+```
+
+## 提取资源
+
+要提取嵌入在 Gitea 可执行文件中的资源，请使用以下语法：
+
+```sh
+gitea [--config {file}] embedded extract [--destination {dir}|--custom] [--overwrite|--rename] [--include-vendored] {patterns...}
+```
+
+`--config` 选项用于告知 Gitea `app.ini` 配置文件的位置（如果不在默认位置）。此选项仅在使用 `--custom` 标志时使用。
+
+`--destination` 选项用于指定提取文件的目标目录。默认为当前目录。
+
+`--custom` 标志告知 Gitea 直接将文件提取到 `custom` 目录中。为使其正常工作，该命令需要知道 `app.ini` 配置文件的位置（通过 `--config` 指定），并且根据配置的不同，需要从 Gitea 通常启动的目录运行。有关详细信息，请参阅 [自定义 Gitea 配置](../administration/customizing-gitea.md)。
+
+`--overwrite` 标志允许覆盖目标目录中的任何现有文件。
+
+`--rename` 标志告知 Gitea 将目标目录中的任何现有文件重命名为 `filename.bak`。之前的 `.bak` 文件将被覆盖。
+
+至少需要提供一个文件搜索模式；有关模式的语法和示例，请参阅上述 `list` 子命令。
+
+### 重要提示
+
+请确保**只提取需要自定义的文件**。位于 `custom` 目录中的文件不会受到 Gitea 的升级过程的影响。当 Gitea 升级到新版本（通过替换可执行文件）时，许多嵌入文件将发生变化。Gitea 将尊重并使用在 `custom` 目录中找到的任何文件，即使这些文件是旧的和不兼容的。
+
+### 示例：提取邮件模板
+
+将邮件模板提取到临时目录：
+
+```sh
+$ mkdir tempdir
+$ gitea embedded extract --destination tempdir 'templates/mail/**.tmpl'
+Extracting to tempdir:
+tempdir/templates/mail/auth/activate.tmpl
+tempdir/templates/mail/auth/activate_email.tmpl
+tempdir/templates/mail/auth/register_notify.tmpl
+tempdir/templates/mail/auth/reset_passwd.tmpl
+tempdir/templates/mail/issue/assigned.tmpl
+tempdir/templates/mail/issue/default.tmpl
+tempdir/templates/mail/notify/collaborator.tmpl
+```