Update the runner reference pages (#597)

Automated update of the generated runner reference pages from gitea/runner (main for the develop docs, the newest stable tag for every documented series), opened by the "update runner reference" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-597.docs-gitea-com.pages.dev

---------

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/597
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Gitea Bot <[email protected]>

.gitea/workflows/build-and-publish.yaml

@@ -19,13 +19,13 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
         with:
           node-version: 24
           cache: pnpm
       - name: prepare awesome list
         run: |
-          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
+          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 prepare-awesome-v28
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 

.gitea/workflows/test.yaml

@@ -16,13 +16,13 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
       - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
         with:
           node-version: 24
           cache: pnpm
       - name: prepare awesome list
         run: |
-          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
+          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 prepare-awesome-v28
 
       - name: install dependencies
         run: pnpm install --frozen-lockfile
@@ -45,7 +45,7 @@ jobs:
           # pull requests from forks do not get the secrets, the build above is
           # then the only check and the preview is silently skipped
           if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
-            echo "no Cloudflare credentials available, skipping the preview deployment"
+            echo "::notice::no Cloudflare credentials available (pull request from a fork?), skipping the preview deployment"
             exit 0
           fi
 

.gitea/workflows/update_swagger.yaml

@@ -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:

.gitignore

@@ -6,7 +6,6 @@ sites/*/dist
 sites/*/.astro
 sites/*/.cache
 build/
-.docusaurus/
 
 # Misc
 .DS_Store

Makefile

@@ -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:

README.md

@@ -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, 简体中文, 繁體中文 |
+| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 28, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
-| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 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.
 

cloudflare/_headers

@@ -2,8 +2,8 @@
 # is copied into the build output by the publish workflow, so that it is not
 # uploaded to S3/CloudFront where it would be publicly readable at /_headers.
 #
-# Unlike the docusaurus build, astro emits a single content hashed asset
+# The build emits a single content hashed asset directory shared by every
-# directory shared by every language, so no per locale rules are needed.
+# language, so no per locale rules are needed.
 
 # Content hashed build output (js, css, fonts). The file name changes with the
 # content, so these can be cached forever.

cloudflare/_redirects

@@ -1,7 +1,7 @@
 # Redirects for legacy URLs and routes the site no longer serves directly.
 
 # The api reference and the runner docs are separate products, published in
-# english only. Docusaurus served an empty localized copy of them.
+# english only, so they have no localized copy.
 /zh-cn/api/* /api/:splat 301
 /zh-tw/api/* /api/:splat 301
 /zh-cn/runner/* /runner/:splat 301
@@ -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.

docs/administration/audit-logging.md

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

docs/administration/config-cheat-sheet.md

@@ -130,8 +130,8 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
    HTTP protocol.
 - `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when
    default SSH port is used.
-- `GO_GET_CLONE_URL_PROTOCOL`: **https**: Value for the "go get" request returns the repository url as https or ssh
+- `GO_GET_CLONE_URL_PROTOCOL`: **_empty_**: Scheme of the returned URL for the "go get" response.
-   default is https.
+   Default is "https" if DISABLE_HTTP_GIT=false or SSH is disabled, otherwise "ssh".
 - `ACCESS_CONTROL_ALLOW_ORIGIN`: **_empty_**: Value for Access-Control-Allow-Origin header,
    default is not to present.
 
@@ -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}://localhost:{HTTP_PORT}/`**:
-- `ROOT_URL`: **`{PROTOCOL}://{DOMAIN}:{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
+- `COOKIE_REMEMBER_NAME`: **gitea\_remember**: Name of cookie used to store authentication information.
-   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,30 @@ 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` non-public targets (private, loopback, link-local, CGNAT and special-use ranges) to be allowed, 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.
+    - `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.
-    - `external`: A valid non-private unicast IP, you can access all hosts on public internet.
+  - 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)
-    - `*`: All hosts are allowed.
+  - 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.
-  - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6
+  - All addresses can have ports specified. Accepted port specs:
-  - Wildcard hosts: `*.mydomain.com`, `192.168.100.*`
+    - 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 non-public 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.
+  - Non-public targets need an IP or built-in entry, a host name entry alone never covers them.
+  - Reserved addresses (the IPv4-embedding NAT64, Teredo and 6to4 ranges, this-network, multicast and broadcast) are denied whatever the list says. To reach them configure an HTTP proxy
+  - 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 +679,8 @@ And the following unique queues:
 
 ## OpenID (`openid`)
 
-- `ENABLE_OPENID_SIGNIN`: **true**: Allow authentication in via OpenID.
+- `ENABLE_OPENID_SIGNIN`: **false**: Allow authentication in via OpenID.
-- `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION**: Allow registering 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 +715,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 +774,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 +784,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.
+- `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
-  The user's email will be replaced with a concatenation of the user name in lower case, "@" and NO_REPLY_ADDRESS.
 - `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 +817,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 +896,27 @@ In-Reply-To =
 
 ## Cache (`cache`)
 
-- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, `twoqueue` or `memcache`. (`twoqueue` represents a size limited LRU cache.)
+- `ADAPTER`: **memory**: Either `memory`, `redis`, `memcache`, or `twoqueue`.
-- `INTERVAL`: **60**: Garbage Collection interval (sec), for memory and twoqueue cache only.
+- `INTERVAL`: **60**: For `memory` and `twoqueue`, GC interval in seconds.
-- `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.
+- `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 +943,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 +1062,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 +1071,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 +1080,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 +1106,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 +1115,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 +1123,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 +1216,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 +1238,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 +1246,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 +1259,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`)
@@ -1298,7 +1327,6 @@ These options are written into the gitconfig file under `[git] HOME_PATH` when G
 
 - `diff.algorithm`: **histogram**
 - `core.logAllRefUpdates`: **true**
-- `gc.reflogExpire`: **90**
 
 ## Metrics (`metrics`)
 
@@ -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`.
+- `EGRESS_MODE`: **lax**: Mode toggles between strictness of scanning outgoing requests, same format as `EGRESS_MODE` in [`security`](#security-security).
-- `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.
+- `ALLOWED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may call, same format as `ALLOWED_HOST_LIST` in [`security`](#security-security). Private, loopback and link-local 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`.
-- `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.
+- `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.
+`DEFAULT_ACTIONS_URL` sets where runners download actions without a host.
-For example, `uses: actions/checkout@v4` means `https://github.com/actions/checkout@v4` since the value of `DEFAULT_ACTIONS_URL` is `github`.
+With `github`, `uses: actions/checkout@v4` resolves to `https://github.com/actions/checkout@v4`, with `self` to `<ROOT_URL>/actions/checkout@v4`.
-And it can be changed to `self` to make it `root_url_of_your_gitea/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.
-
-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`.
 
 ## Other (`other`)
 

docs/administration/email-setup.md

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

docs/administration/git-lfs-support.md

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

docs/administration/logging-config.md

@@ -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).

docs/index.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**
 

docs/installation/comparison.md

@@ -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)   | ✓                                                   | ✘         | ✓         | ✓         | ✘         | ✓            | ✓            |

docs/installation/from-source.md

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

docs/installation/on-cloud-provider.md

@@ -1,49 +0,0 @@
----
-date: "2016-12-01T16:00:00+02:00"
-slug: "install-on-cloud-provider"
-sidebar_position: 90
-aliases:
-  - /en-us/install-on-cloud-provider
----
-
-# Installation on Cloud Provider
-
-## Cloudron
-
-Gitea is available as a 1-click install on [Cloudron](https://cloudron.io).
-Cloudron makes it easy to run apps like Gitea on your server and keep them up-to-date and secure.
-
-[![Install](/cloudron.svg)](https://cloudron.io/button.html?app=io.gitea.cloudronapp)
-
-The Gitea package is maintained [here](https://git.cloudron.io/cloudron/gitea-app).
-
-There is a [demo instance](https://my.demo.cloudron.io) (username: cloudron password: cloudron) where
-you can experiment with running Gitea.
-
-## Linode
-
-[Linode](https://www.linode.com/) has Gitea as an app in their marketplace.
-
-To deploy Gitea to Linode, have a look at the [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/).
-
-## alwaysdata
-
-[alwaysdata](https://www.alwaysdata.com/) has Gitea as an app in their marketplace.
-
-To deploy Gitea to alwaysdata, have a look at the [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/).
-
-## Exoscale
-
-[Exoscale](https://www.exoscale.com/) provides Gitea managed by [Glasskube](https://glasskube.eu/) in their marketplace.
-
-Exoscale is a European cloud service provider.
-
-The package is maintained and update via the open source [Glasskube Kubernetes Operator](https://github.com/glasskube/operator).
-
-To deploy Gitea to Exoscale, have a look at the [Exoscale Marketplace](https://www.exoscale.com/marketplace/listing/glasskube-gitea/).
-
-## Sealos
-
-Gitea is available as a one-click deployment on [Sealos](https://sealos.io/products/app-store/gitea).
-
-The community-maintained template source is available [here](https://github.com/labring-actions/templates/tree/kb-0.9/template/gitea).

docs/installation/with-docker-rootless.md

@@ -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
 

docs/installation/with-docker.md

@@ -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

docs/installation/with-podman-quadlet.md

@@ -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
+```

docs/usage/actions/artifacts.md

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

docs/usage/actions/comparison.md

@@ -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.
+`uses:` accepts an absolute URL to any git host, e.g. `uses: https://gitea.com/actions/checkout@v4`.
-Like `uses: https://github.com/actions/checkout@v4` or `uses: http://your_gitea.com/owner/repo@branch`.
+
+### 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).
+[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) is ignored.
-
-It's ignored by Gitea Actions now.
 
 ### 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).
+`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).
-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.
 
 ### 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.
+[Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md) are ignored.
-See [Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md).
-
-It's ignored by Gitea Actions now.
 
 ### 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)
+[Error annotations](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error) are ignored.
-
-It's ignored by Gitea Actions now.
 
 ### 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.
+`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`, `security-events` and `pages` are not supported, while Gitea adds `code`, `releases`, `wiki` and `projects`. `id-token` works like on GitHub, see [OpenID Connect](openid-connect.md).
-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.
-
 See [Actions job token permissions](token-permissions.md).
 
 ### Downloading actions
 
-Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.
+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`.
-We have since restricted this option to only allow two values (`github` and `self`).
+See the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
-When set to `github`, the new default, Gitea will download non-fully-qualified actions from `https://github.com`.
+For other sources, see [Absolute action URLs](#absolute-action-urls), [Action prefixes](#action-prefixes) and [Workflow-relative actions](#workflow-relative-actions).
-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)。
 
 ### Context availability
 
-Context availability is not checked, so you can use the env context on more places.
+[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.
-See [Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability).

docs/usage/actions/design.md

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

docs/usage/actions/faq.md

@@ -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.
+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).
-But what if you want to use actions from other places such as gitea.com instead of GitHub?
 
-The good news is that you can specify the URL prefix to use actions from anywhere.
+To use an action from elsewhere, name its host:
-This is an extra syntax in Gitea Actions.
-For example:
 
-- `uses: https://gitea.com/xxx/xxx@xxx`
+- `uses: https://gitea.com/owner/repo@ref`
-- `uses: https://github.com/xxx/xxx@xxx`
+- `uses: http://your_gitea_instance.com/owner/repo@ref`
-- `uses: http://your_gitea_instance.com/xxx@xxx`
+- `uses: self:owner/repo@ref` for your own Gitea instance
-
-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).
 
 ## How to limit the permission of the runners?
 
-Runners have no more permissions than simply connecting to your Gitea instance.
+Runners only connect 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.
+For each job, a runner gets a `GITEA_TOKEN` limited to the job's repository, see [Actions job token permissions](token-permissions.md).
-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.
+To give a job access to more private repositories or external systems, pass it [secrets](usage/actions/secrets.md).
-
-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.
 
 ## Which operating systems are supported by Gitea Runner?
 
-We released official binaries for Linux, macOS, and Windows.
+Official binaries are released for Linux, macOS and Windows.
-While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
+Other systems supported by Go and Docker work in theory.
-
-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
-```
 
 ## 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.
+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).
-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).
+The runner uses the environment of the first label it has.
-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.
 
 ## What is the difference between agent labels and custom labels for a runner?
 
-![labels](/images/usage/actions/labels.png)
+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.
-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.
 
 ## 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).

docs/usage/actions/openid-connect.md

@@ -0,0 +1,60 @@
+---
+date: "2026-08-23T00:00:00+00:00"
+slug: "openid-connect"
+sidebar_position: 40
+---
+
+# OpenID Connect
+
+Jobs can request short-lived OpenID Connect (OIDC) tokens to sign in to cloud providers and other services without storing long-lived secrets. The tokens use the GitHub Actions format, so actions like `aws-actions/configure-aws-credentials`, `google-github-actions/auth` and `azure/login` work unchanged.
+
+## Trusting Gitea
+
+Add Gitea as an OIDC identity provider in the service:
+
+- Issuer: `<ROOT_URL>/api/actions/oidc`
+- Audience: `<ROOT_URL>/<owner>`, unless the workflow requests another one
+
+Then limit which workflows can sign in with a condition on the [`sub` claim](#claims).
+
+Gitea signs the tokens with a key it creates at `<APP_DATA_PATH>/jwt/actions_oidc.pem`. Instances behind a load balancer must share this file.
+
+## Requesting a token
+
+Grant the `id-token` permission to the workflow or job:
+
+```yaml
+permissions:
+  id-token: write
+```
+
+Default permissions never include it, and jobs from fork pull requests never get it. Owners and repositories can disable it with their [maximum token permissions](token-permissions.md#maximum-token-permissions-clamping).
+
+Actions like the ones above request the token themselves. In a script, use `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`:
+
+```shell
+curl --fail --silent --show-error \
+  --header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
+  "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service"
+```
+
+The token is in the `value` field of the response and expires after five minutes.
+
+## Claims
+
+The `sub` claim names the owner and repository with their IDs, so a renamed or recreated repository cannot match an existing trust policy:
+
+```text
+repo:<owner>@<owner-id>/<repo>@<repo-id>:ref:<ref>
+repo:<owner>@<owner-id>/<repo>@<repo-id>:pull_request
+```
+
+The `pull_request` event uses the second form, all other events use the first, including `pull_request_target`.
+
+The other claims match GitHub's, like `repository`, `ref`, `sha`, `workflow_ref` and `job_workflow_ref`. The discovery document at `<ROOT_URL>/api/actions/oidc/.well-known/openid-configuration` lists them all.
+
+Differences from GitHub Actions:
+
+- There is no `environment` claim.
+- Pull request runs use `refs/pull/<index>/head` and its commit, not the merge ref and merge commit.
+- `run_number` counts runs per repository, not per workflow.

docs/usage/actions/scoped-workflows.md

@@ -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 **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`) 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 **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.
 

docs/usage/actions/token-permissions.md

@@ -53,13 +53,14 @@ Valid access mode values for each scope are `read`, `write`, and `none`.
 - `wiki`
 - `projects`
 - `packages` (if supported by the target feature)
+- `id-token` (`write` allows requesting [OpenID Connect tokens](openid-connect.md), `read` grants nothing)
 
 If you specify both `contents` and a more granular scope (like `code` or `releases`), the granular scope wins for that unit.
 
 ### Compatibility notes
 
 Gitea supports a subset of GitHub Actions permission scopes.
-GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not currently supported by Gitea Actions.
+GitHub-only scopes such as `statuses`, `checks`, `deployments`, `security-events`, and `pages` are not currently supported by Gitea Actions.
 
 Gitea also exposes repository-unit scopes that do not exist as separate scopes in GitHub Actions:
 
@@ -75,15 +76,18 @@ If neither the workflow nor the job defines `permissions:`, Gitea uses the confi
 - **Permissive**: read and write permissions for most units in the job's repository (backwards-compatible default).
 - **Restricted**: read-only permissions for `code`, `releases`, and `packages` in the job's repository, and no access to other units by default.
 
+Neither mode includes `id-token`.
+
 ## Maximum token permissions (clamping)
 
-You can configure a maximum permission per repository unit.
+You can configure a maximum permission per repository unit and for `id-token`.
 The job's effective permissions are computed as:
 
 `effective = min(requested, maximum)`
 
 This means workflows can reduce permissions for a job, but cannot exceed your configured maximum.
 If you don't configure a maximum, the maximum defaults to `write` for all scopes.
+Maximums saved before Gitea supported `id-token` deny it until you set it to `write`.
 
 ## Where to configure
 
@@ -97,7 +101,7 @@ Note: Repository-level token permission settings are only shown once **Repositor
 
 ## Fork pull requests
 
-For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings.
+For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings. They also get no OpenID Connect tokens.
 
 ## Cross-repository access
 

docs/usage/actions/variables.md

@@ -64,8 +64,8 @@ These are used internally by the runner and actions. They are typically not need
 | Name | Description | Example |
 |---|---|---|
 | `ACTIONS_CACHE_URL` | URL for the actions cache service. | `http://192.168.1.10:8088/` |
-| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when configured. | `***` |
+| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when `id-token: write` is granted. | `***` |
-| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when configured. | `https://gitea.com/login/oauth/access_token` |
+| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when `id-token: write` is granted. | `https://gitea.com/api/actions/oidc/token?` |
 | `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.com` |
 | `ACTIONS_RUNTIME_TOKEN` | Authentication token for the Actions pipeline API. | `***` |
 | `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.com/api/actions_pipeline/` |

docs/usage/issues-prs/issue-pull-request-templates.md

@@ -15,7 +15,7 @@ creating issues and pull requests. This will cut down on the initial back and fo
 of getting some clarifying details.
 It is currently not possible to provide generic issue/pull-request templates globally.
 
-Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one.
+Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one. See [Pre-filling Issues and Pull Requests](prefill-issues-pull-requests.md) for all parameters.
 
 ## File names
 

docs/usage/issues-prs/prefill-issues-pull-requests.md

@@ -0,0 +1,42 @@
+---
+date: "2026-10-17T00:00:00+00:00"
+slug: "prefill-issues-pull-requests"
+sidebar_position: 14
+---
+
+# Pre-filling Issues and Pull Requests
+
+Links to the pages for creating issues and pull requests can pre-fill the form with query parameters.
+This lets you link users from another app, a README or a project board to a form that is already categorized.
+
+- New issue: `/{owner}/{repo}/issues/new?…`
+- New pull request: `/{owner}/{repo}/compare/{base}...{head}?…`
+
+For example, this link opens a new issue with a title, two labels and an assignee:
+
+```
+https://gitea.example.com/owner/repo/issues/new?title=Dashboard+crashes&label=kind/bug,area/dashboard&assignee=alice
+```
+
+## Parameters
+
+| Parameter     | Value                                                                       |
+| ------------- | --------------------------------------------------------------------------- |
+| `title`       | Title                                                                       |
+| `body`        | Description                                                                 |
+| `label`       | Comma-separated label IDs or names                                          |
+| `labels`      | Alias of `label`                                                            |
+| `milestone`   | Milestone ID or name                                                        |
+| `project`     | Comma-separated project IDs or titles                                       |
+| `assignee`    | Comma-separated user IDs or usernames                                       |
+| `template`    | File name of the [template](issue-pull-request-templates.md) to use         |
+| `field:<id>`  | Value of the field with this `id` in a YAML template                        |
+
+IDs and names can be mixed and names are matched case-insensitively. Values that don't match anything in the repository are ignored.
+Labels include the organization's labels, and closed milestones and projects can be selected too.
+Milestones and projects are only offered to users who can write to issues or pull requests, so for other users these parameters have no effect.
+
+The values from the link take precedence over the title, description, labels and assignees of the template.
+
+When there are several issue templates to choose from, the parameters are passed through to the chosen one.
+On the compare page, any of these parameters also opens the pull request form directly, as `expand=1` does.