chore(deps): update pnpm to v11.10.0 (#460)

This PR contains the following updates:

| Package | Change | [Age](https://docs.renovatebot.com/merge-confidence/) | [Confidence](https://docs.renovatebot.com/merge-confidence/) |
|---|---|---|---|
| [pnpm](https://pnpm.io) ([source](https://github.com/pnpm/pnpm/tree/HEAD/pnpm11/pnpm)) | [`11.9.0` → `11.10.0`](https://renovatebot.com/diffs/npm/pnpm/11.9.0/11.10.0) | ![age](https://developer.mend.io/api/mc/badges/age/npm/pnpm/11.10.0?slim=true) | ![confidence](https://developer.mend.io/api/mc/badges/confidence/npm/pnpm/11.9.0/11.10.0?slim=true) |

---

### Release Notes

<details>
<summary>pnpm/pnpm (pnpm)</summary>

### [`v11.10.0`](https://github.com/pnpm/pnpm/blob/HEAD/pnpm11/pnpm/CHANGELOG.md#11100)

[Compare Source](https://github.com/pnpm/pnpm/compare/v11.9.0...v11.10.0)

##### Minor Changes

- [`e2e3c81`](https://github.com/pnpm/pnpm/commit/e2e3c81): Added the `issues` command as an alias of `bugs`, so `pnpm issues` opens the package's bug tracker URL in the browser.

- [`8491f8e`](https://github.com/pnpm/pnpm/commit/8491f8e): Added the `prefix` command which prints the current package prefix directory (or global prefix directory if `-g` / `--global` is used).

- [`3425e80`](https://github.com/pnpm/pnpm/commit/3425e80): Added an `_auth` setting for configuring registry authentication as a single structured (URL-keyed) value. It can be set in the **global** pnpm config (`config.yaml`) or, for CI, via the `pnpm_config__auth` environment variable. The env form sidesteps the GitHub Actions / bash / zsh limitation that broke the existing `pnpm_config_//host/:_authToken=…` form (env var names containing `/`, `:`, or `.` are silently dropped). Closes [#&#8203;12314](https://github.com/pnpm/pnpm/issues/12314).

  The value is keyed by registry URL so each secret is explicitly bound to the host that may receive it. Registry URL keys must use `http` or `https` and must not include credentials, query strings, or fragments:

  ```sh
  export pnpm_config__auth='{"https://registry.npmjs.org":{"@&#8203;":{"authToken":"npm-token"},"@&#8203;org":{"authToken":"org-token"}}}'
  ```

  The equivalent in the global `config.yaml`:

  ```yaml
  _auth:
    https://registry.npmjs.org:
      "@&#8203;":
        authToken: npm-token
      "@&#8203;org":
        authToken: org-token
  ```

  Within each registry URL, `@` means registry-wide/default credentials and package scopes like `@org` bind credentials to that scope on the same host. The only supported credential field is `authToken` (maps to `_authToken` / bearer auth); the deprecated `basicAuth` / `username` + `password` forms are intentionally not accepted here.

  Each entry also infers a trusted registry route: `@` routes the default registry (and `pnpm add <pkg>` resolves there), and `@org` routes that scope. Because the credential and destination host arrive in one trusted value, repo-controlled `pnpm-workspace.yaml` or project `.npmrc` cannot redirect the token to a different host. `_auth` is honored **only** from the env var and the global config — it is ignored in a project `pnpm-workspace.yaml` / `.npmrc`, so repo-controlled config can never supply registry auth. Precedence: CLI flags (`--registry`, `--@&#8203;scope:registry`) > `pnpm_config__auth` > global `config.yaml` `_auth` > `pnpm-workspace.yaml`.

  Both `pnpm_config__auth` (lowercase, documented form) and `PNPM_CONFIG__AUTH` (all-caps, the shell convention some CI runners apply) are honored. If both are set, lowercase wins unless it is empty, in which case uppercase is used. The env var wins over the global `config.yaml` `_auth` on a conflicting key. `tokenHelper` is not supported in `_auth`. Parsing is strict: a malformed value (bad JSON, wrong shape, invalid registry URL or scope, an unsupported credential field) fails fast with an error rather than being silently dropped.

  **Pacquet parity note:** the pacquet (Rust) port supports the same single credential field as the TS CLI: `authToken`.

- [`a33eeec`](https://github.com/pnpm/pnpm/commit/a33eeec): `pnpm self-update` and `packageManager` version-switching can now install and link pnpm v12 (the Rust port), published with equal content under both the `pnpm` and `@pnpm/exe` names on the `next-12` dist-tag. Its native binaries ship as `@pnpm/exe.<platform>-<arch>` packages, which pnpm's built-in installer links directly — no Node.js launcher, so the command pays no Node startup cost. v12 is initialized exactly like `@pnpm/exe`, including per-platform global-virtual-store hashing. From v12 onward the install converges on the unscoped `pnpm` package (the Rust exe) — even when updating from the SEA `@pnpm/exe` build.

- [`1dd12bd`](https://github.com/pnpm/pnpm/commit/1dd12bd): When resolving through a pnpr install-accelerator server, pnpm no longer forwards its own upstream registry credentials in the resolve request. Only the `Authorization` header identifying the caller to pnpr is sent. The pnpr server now selects upstream credentials from its own route policy (operator-configured upstream credential aliases), so private dependencies resolve through a pnpr-managed alias the caller is authorized to use, rather than by sending the client's registry tokens to the server.

- [`1e81761`](https://github.com/pnpm/pnpm/commit/1e81761): Expose web authentication `authUrl` and `doneUrl` in JSON error output when OTP is required in a non-interactive terminal [#&#8203;12724](https://github.com/pnpm/pnpm/issues/12724).

##### Patch Changes

- [`2f389d6`](https://github.com/pnpm/pnpm/commit/2f389d6): Added the Node.js release team's new signing key (Stewart X Addison, `655F3B5C1FB3FA8D1A0CA6BDE4A7D232B936D2FD`) to the embedded Node.js release keys, so runtimes whose `SHASUMS256.txt` is signed by the new releaser verify successfully.

- [`acbdb94`](https://github.com/pnpm/pnpm/commit/acbdb94): Fixed shell tab completion not suggesting workspaces after the `-F` alias for `--filter` option.

- [`dcabb78`](https://github.com/pnpm/pnpm/commit/dcabb78): Fixed `pnpm up -r <pkg>` bumping unrelated packages that have open semver ranges. Previously, any update mutation nullified the lockfile-derived `preferredVersions` globally, so packages with `^x.y.z` ranges could re-resolve to newer compatible versions even though the user only asked to update a specific package. The install layer now always seeds `preferredVersions` from the lockfile, and caller-supplied preferred versions (such as the vulnerability penalties of `pnpm audit --fix`) layer on top of the seed instead of replacing it. The targeted package still bumps: the per-resolve `updateRequested` flag makes the resolver ignore the target's own lockfile pins.

  Closes [#&#8203;10662](https://github.com/pnpm/pnpm/issues/10662).

- [`d539172`](https://github.com/pnpm/pnpm/commit/d539172): Fixed pnpm pack and pnpm publish failing when prepack generates files that are included in the package and postpack cleans them up.

- [`be6505a`](https://github.com/pnpm/pnpm/commit/be6505a): Hardened global package management:

  - On Windows, removing or updating a global package now also cleans up the `node.exe` flavor of a bin, so a stale `node.exe` no longer survives on `PATH` after uninstall, and a new global install no longer silently overwrites an existing `node.exe`.
  - `pnpm add -g pnpm@<version>` (and `@pnpm/exe@<version>`) is now rejected like the bare `pnpm` form, pointing to `pnpm self-update`.
  - Dependency aliases read from a global package's manifest are validated before being joined onto `node_modules` paths, preventing a tampered manifest from escaping the install directory.
  - Each global install group is created in its own freshly-made directory (no longer reusing a colliding or pre-existing path).
  - Removing or updating a global package no longer unlinks a bin that belongs to a different globally installed package.

- [`25c7388`](https://github.com/pnpm/pnpm/commit/25c7388): pnpm now rejects `jsr:` specifiers whose package name is not a valid npm package name — an empty scope or name (e.g. `jsr:@&#8203;scope/`), path separators inside the name, or any other shape `validate-npm-package-name` rejects — with `ERR_PNPM_INVALID_JSR_PACKAGE_NAME` instead of silently converting them into a malformed `@jsr/...` npm package name.

- [`25c7388`](https://github.com/pnpm/pnpm/commit/25c7388): pnpm now rejects named-registry specifiers (e.g. `gh:`) whose package name is not a valid npm package name — an empty scope (e.g. `gh:@&#8203;/bar`), path separators inside the name (e.g. `gh:@&#8203;scope/../name`), or any other shape `validate-npm-package-name` rejects — with `ERR_PNPM_INVALID_NAMED_REGISTRY_PACKAGE_NAME` instead of passing the name through to registry URLs and metadata cache file paths.

- [`96da7c5`](https://github.com/pnpm/pnpm/commit/96da7c5): node-gyp's `gyp_main.py` and `gyp` entrypoints are now packed with the executable bit in the `pnpm` and `@pnpm/exe` tarballs. Without it, building native addons from source could fail with a permission error.

- [`99982b9`](https://github.com/pnpm/pnpm/commit/99982b9): Sped up resolution and reduced memory use against registries that ignore npm's abbreviated metadata format and always return the full package document (for example, Azure DevOps Artifacts). pnpm now strips such documents down to the abbreviated field set before caching them. Resolution output is unchanged, and registries that honor the abbreviated format (such as the npm registry) pay no extra cost.

- [`11a7fdd`](https://github.com/pnpm/pnpm/commit/11a7fdd): Sped up offline and `--prefer-offline` resolution on large workspaces (e.g. `pnpm dedupe --offline`, `pnpm install --offline`). Package metadata loaded from the local cache is now kept in memory, so each package's metadata is parsed once per command instead of once per dependent that references it.

- [`2c7369d`](https://github.com/pnpm/pnpm/commit/2c7369d): `pnpm pack-app` now rejects `--entry` / `pnpm.app.entry` and `--output-dir` / `pnpm.app.outputDir` values that are absolute paths or escape the project directory via `..` (or a symlink that resolves outside it), and refuses to write the produced executable when its target path already exists as a symlink (or other non-regular file). This prevents a repository-controlled `package.json` from embedding host files (such as an SSH key) into the produced executable, writing build artifacts outside the project, or overwriting an arbitrary file through a committed symlink. The new error codes are `ERR_PNPM_PACK_APP_ENTRY_OUTSIDE_PROJECT`, `ERR_PNPM_PACK_APP_OUTPUT_DIR_OUTSIDE_PROJECT`, and `ERR_PNPM_PACK_APP_OUTPUT_FILE_NOT_REGULAR`.

  When ad-hoc signing macOS targets, `pnpm pack-app` now runs the system `codesign` by absolute path and resolves `ldid` to a location outside the project, so a repository-controlled `node_modules/.bin` on `PATH` cannot hijack the signer.

- [`ce5d5a5`](https://github.com/pnpm/pnpm/commit/ce5d5a5): Relative paths in `patchedDependencies` are now resolved against the lockfile directory when computing patch file hashes, so running `pnpm install` from a subdirectory no longer fails with `ENOENT` looking for the patch file in the wrong location [#&#8203;12762](https://github.com/pnpm/pnpm/pull/12762).

- [`ebb4096`](https://github.com/pnpm/pnpm/commit/ebb4096): `pnpm peers` no longer reports a conflict for a missing peer dependency that is ignored via `pnpm.peerDependencyRules.ignoreMissing`.

- [`dcabb78`](https://github.com/pnpm/pnpm/commit/dcabb78): Fixed a prototype-pollution hazard when seeding preferred versions: a dependency named `__proto__` in a manifest or in `pnpm-lock.yaml` could write through `Object.prototype` (or crash the install) while the preferred-versions map was being built. The maps are now null-prototype objects, so crafted package names land as plain keys.

- [`f38e696`](https://github.com/pnpm/pnpm/commit/f38e696): Hardened `pnpm deploy --force` so it refuses unsafe deploy targets such as workspace roots, parent directories, out-of-workspace paths, and symlinked target parents.

- [`806c3ec`](https://github.com/pnpm/pnpm/commit/806c3ec): pnpm no longer warns about ignored project-level auth settings when `PNPM_CONFIG_NPMRC_AUTH_FILE` points at the project `.npmrc` — setting it to that file is an explicit opt-in to trusting it, so auth env variables in it are expanded [pnpm/pnpm#12480](https://github.com/pnpm/pnpm/issues/12480).

- [`991405e`](https://github.com/pnpm/pnpm/commit/991405e): Restore differential rendering (`ansi-diff`) to fix duplicated output lines introduced by [#&#8203;12351](https://github.com/pnpm/pnpm/issues/12351).

- [`c121235`](https://github.com/pnpm/pnpm/commit/c121235): Fixed the topological order of `--filter`ed commands (`pnpm run`, `pnpm exec`, `pnpm publish`, `pnpm pack`, `pnpm rebuild`) when the selected projects depend on each other only transitively through projects that were not selected. Previously such selected projects could run concurrently or in the wrong order; now a project always runs after the selected projects it transitively depends on, while projects without a real dependency relationship still run concurrently. This now also holds for prod-only filters (`--filter-prod`), which resolve order through the production dependency graph so transitive production dependencies are respected without pulling back the dev dependencies the filter drops, and for selections that mix `--filter` with `--filter-prod` [#&#8203;8335](https://github.com/pnpm/pnpm/issues/8335).

- [`d539172`](https://github.com/pnpm/pnpm/commit/d539172): `pnpm pack` and `pnpm publish` no longer follow a symlinked workspace `LICENSE` file when injecting it into a package that has no license of its own. Following the symlink could pack bytes from outside the workspace into the published tarball.

- [`dcabb78`](https://github.com/pnpm/pnpm/commit/dcabb78): Fixed `pnpm up <pkg>` producing a different result than a fresh install of the same manifests would. The resolver now distinguishes `updateRequested` (true only for packages that match the user's update target) from the broader `update` flag, and for the targeted package ignores only its own lockfile-derived preferred-version pins — so the target re-resolves exactly as if its lockfile entries were deleted and `pnpm install` ran. Preferred versions a fresh install applies (manifest pins, versions propagated down the dependency chain, and the vulnerability-avoidance penalties of `pnpm audit --fix`) stay in effect, so an update never installs duplicate versions that a reinstall from scratch would not reproduce. When a preferred version holds the update target below the newest version its range admits, pnpm now prints a warning explaining that reaching the newer version everywhere requires an override.

- [`dcabb78`](https://github.com/pnpm/pnpm/commit/dcabb78): `pnpm update <dep>@&#8203;<version>` now prints a warning when `<dep>` is only present as a transitive dependency: the requested version cannot be applied there (updates resolve the target the way a fresh install would), and the warning recommends adding the version to `pnpm.overrides` instead, which is the mechanism that does pin transitive dependencies. Closes [#&#8203;12744](https://github.com/pnpm/pnpm/issues/12744).

- [`a6c4d5f`](https://github.com/pnpm/pnpm/commit/a6c4d5f): When a dependency cannot be found in the registry (404) or the registry has no matching version, and a workspace project with the same name exists only at non-matching versions, the error now reports the available workspace versions (`ERR_PNPM_NO_MATCHING_VERSION_INSIDE_WORKSPACE`) instead of the raw registry failure [pnpm/pnpm#1379](https://github.com/pnpm/pnpm/issues/1379). Other registry failures (authorization, network, server errors) still propagate unchanged. The pacquet (Rust) resolver applies the same behavior.

</details>

---------

Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/460
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: Renovate Bot <renovate-bot@gitea.com>

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

@@ -8,36 +8,31 @@ on:
 
 jobs:
   build-docs:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
       - uses: actions/setup-node@v6
         with:
-          node-version: 20
-          cache: npm
+          node-version: 24
+          cache: pnpm
       - name: install necessary tools
         run: |
-          apt update -y && apt install -y rsync python3 python3-pip python-is-python3
-          pip install awscli
+          curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
+          unzip awscliv2.zip
+          sudo ./aws/install
       - name: prepare awesome list
         run: |
-          make prepare-awesome-latest prepare-awesome\#23 prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
-      - name: Cache ~/.npm for npm ci
-        uses: actions/cache@v4
-        with:
-          path: ~/.npm
-          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
-          restore-keys: ${{ runner.os }}-node
-
+          make prepare-awesome-latest prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       #- uses: tats-u/docuactions-cache@v1
       - name: build site
         run: |
           make build
       - name: aws credential configure
-        uses: aws-actions/configure-aws-credentials@v5
+        uses: aws-actions/configure-aws-credentials@v6
         with:
           aws-access-key-id: ${{ secrets.AWS_KEY_ID }}
           aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}
@@ -46,3 +41,11 @@ jobs:
         run: |
           aws s3 sync build/ s3://docs-gitea-com
           aws cloudfront create-invalidation --distribution-id ${{ secrets.AWS_DISTRIBUTION}} --paths '/*'
+      - name: Copy files to Cloudflare Pages
+        env:
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          pnpm dlx wrangler@4 pages deploy build \
+            --project-name docs-gitea-com \
+            --branch main

.gitea/workflows/test.yaml

@@ -7,23 +7,17 @@ jobs:
   build-docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
       - uses: actions/setup-node@v6
         with:
-          node-version: 20
-          cache: npm
+          node-version: 24
+          cache: pnpm
       - name: prepare awesome list
         run: |
-          make prepare-awesome-latest prepare-awesome\#23 prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
-      - name: Cache ~/.npm for npm ci
-        uses: actions/cache@v4
-        with:
-          path: ~/.npm
-          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
-          restore-keys: ${{ runner.os }}-node
-
+          make prepare-awesome-latest prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       #- uses: tats-u/docuactions-cache@v1
       - name: build site

.gitea/workflows/update_swagger.yaml

@@ -9,28 +9,20 @@ jobs:
   update-swagger:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
       - run: |
-          wget https://raw.githubusercontent.com/go-gitea/gitea/refs/heads/main/templates/swagger/v1_json.tmpl
-          sed -i "$@" 's\"version": "{{AppVer | JSEscape}}"\"version": "dev"\' v1_json.tmpl
-          sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
-          mv v1_json.tmpl static/swagger-latest.json
+          set -euo pipefail
 
-          for ver in '1.24.7' '1.23.8' '1.22.6' '1.21.11' '1.20.6' '1.19.4'; do
-            wget https://raw.githubusercontent.com/go-gitea/gitea/refs/tags/v${ver}/templates/swagger/v1_json.tmpl
-            sed -i "$@" "s|\"version\": \"{{AppVer \| JSEscape}}\"|\"version\": \"${ver}\"|" v1_json.tmpl
-            sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
-            # for version < 1.21.11
-            sed -i "$@" "s|\"version\": \"{{AppVer \| JSEscape \| Safe}}\"|\"version\": \"${ver}\"|" v1_json.tmpl
-            sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape | Safe}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
-            minor=$(echo "$ver" | cut -d '.' -f 2)
-            mv v1_json.tmpl static/swagger-$minor.json
-          done
+          make update-api-docs
 
-          if ! [[ $(git diff --shortstat) ]]; then exit 0; fi
           git config --global user.name "Gitea Bot"
           git config --global user.email "teabot@gitea.io"
           git remote set-url origin https://x-access-token:${{ secrets.DEPLOY_TOKEN }}@gitea.com/gitea/docs.git
-          git add --all
-          git commit -m "[skip ci] Updated swagger files"
-          git push
+
+          if git status --porcelain | grep -q .; then
+            git add --all
+            git commit -m "[skip ci] Updated swagger files"
+            git push
+          else
+            echo "No API doc changes detected; skipping commit"
+          fi

.gitignore

@@ -20,4 +20,5 @@ yarn-debug.log*
 yarn-error.log*
 
 .tmp/
+awesome/
 awesome.md

.npmrc

@@ -1,5 +0,0 @@
-audit=false
-fund=false
-update-notifier=false
-package-lock=true
-lockfile-version=3

Makefile

@@ -8,7 +8,7 @@ all: build
 
 .PHONY: create_dir
 create_dir:
-	mkdir -p .tmp awesome
+	mkdir -p .tmp
 
 .PHONY: clone_awesome
 clone_awesome: create_dir
@@ -24,22 +24,22 @@ prepare-awesome\#%:
 
 .PHONY: install
 install:
-	npm install
+	pnpm install
 
 .PHONY: prepare-docs
 prepare-docs: install prepare-awesome-latest prepare-awesome\#19 prepare-awesome\#20 prepare-awesome\#21 prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24
 
 .PHONY: build
 build:
-	npm run build
+	pnpm run build
 
 .PHONY: serve
 serve: prepare-docs
-	npm run start
+	pnpm run start
 
 .PHONY: serve-zh
 serve-zh: prepare-docs
-	npm run start -- --locale zh-cn
+	pnpm run start -- --locale zh-cn
 
 .PHONY: clean
 clean:
@@ -52,3 +52,7 @@ clean:
 	rm -rf static/swagger-22.json
 	rm -rf static/swagger-23.json
 	rm -rf static/swagger-24.json
+
+.PHONY: update-api-docs
+update-api-docs:
+	./update_api_docs.sh

README.md

@@ -19,5 +19,5 @@ make serve
 ## Test en version
 
 ```shell
-npm run start
+pnpm run start
 ```

babel.config.js

@@ -1,3 +0,0 @@
-module.exports = {
-  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
-};

docs/administration/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Administration",
+  "position": 30,
+  "link": {
+    "type": "generated-index",
+    "slug": "/administration",
+    "title": "Administration"
+  }
+}

docs/administration/backup-and-restore.md

@@ -24,7 +24,7 @@ directory. There should be some output similar to the following:
 
 ```log
 2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:09 Dumping local repositories.../home/git/gitea-repositories
+2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
 2016/12/27 22:32:22 Dumping database...
 2016/12/27 22:32:22 Packing dump files...
 2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
@@ -83,7 +83,7 @@ cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/data/gitea-repositories/
+mv repos/* /var/lib/gitea/data/repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
 
 # mysql
@@ -119,7 +119,7 @@ cd gitea-dump-1610949662
 # restore the gitea data
 mv data/* /data/gitea
 # restore the repositories itself
-mv repos/* /data/git/gitea-repositories/
+mv repos/* /data/git/repositories/
 # adjust file permissions
 chown -R git:git /data
 # Regenerate Git Hooks
@@ -143,7 +143,7 @@ mv data/conf/app.ini /etc/gitea/app.ini
 # restore the gitea data
 mv data/* /var/lib/gitea
 # restore the repositories itself
-mv repos/* /var/lib/gitea/git/gitea-repositories
+mv repos/* /var/lib/gitea/git/repositories
 # adjust file permissions
 chown -R git:git /etc/gitea/app.ini /var/lib/gitea
 # Regenerate Git Hooks

docs/administration/config-cheat-sheet.md

@@ -34,8 +34,39 @@ A full restart is required for Gitea configuration changes to take effect.
 
 ## Use environment variables to setup Gitea
 
-There is [environment-to-ini](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini) to help to
-generate Gitea's `app.ini` from environment variables.
+Gitea supports setting `app.ini` values via environment variables of the form `GITEA__<section>__<KEY>`. These require running `gitea config edit-ini --in-place --apply-env` before starting Gitea to write them into `app.ini`. The official Docker images do this automatically on container startup.
+
+:::info
+If `<section>` or `<KEY>` contains a `.`, replace that with `_0X2E_`; if it contains a `-`, replace it with `_0X2C_`
+:::
+
+
+For example, to configure the database connection via environment variables:
+
+```
+GITEA__database__DB_TYPE=postgres
+GITEA__database__HOST=127.0.0.1:5432
+GITEA__database__NAME=gitea
+GITEA__database__USER=gitea
+GITEA__database__PASSWD=secret
+```
+
+This is equivalent to the following `app.ini` configuration:
+
+```ini
+[database]
+DB_TYPE = postgres
+HOST = 127.0.0.1:5432
+NAME = gitea
+USER = gitea
+PASSWD = secret
+```
+
+You can also load values from files by appending `__FILE` to the variable name. This is useful for Docker secrets:
+
+```
+GITEA__database__PASSWD__FILE=/run/secrets/db_password
+```
 
 ## Default Internal Variables (non-`app.ini` configuration)
 
@@ -85,8 +116,13 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
 - `FORCE_PRIVATE`: **false**: Force every new repository to be private.
 - `DEFAULT_PRIVATE`: **last**: Default private when creating a new repository: `last`, `private`, `public`
 - `DEFAULT_PUSH_CREATE_PRIVATE`: **true**: Default private when creating a new repository with push-to-create.
-- `MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per user,
-   `-1` means no limit.
+- `MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per user/org,
+   `-1` means no limit. Acts as a shortcut: sets the default value for both
+   `USER_MAX_CREATION_LIMIT` and `ORG_MAX_CREATION_LIMIT` when those are not configured.
+- `USER_MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per user,
+   applied at creation time. `-1` means no limit. Takes precedence over `MAX_CREATION_LIMIT` when set.
+- `ORG_MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per organization,
+   applied at creation time. `-1` means no limit. Takes precedence over `MAX_CREATION_LIMIT` when set.
 - `PREFERRED_LICENSES`: **Apache License 2.0,MIT License**: Preferred Licenses to place at
    the top of the list. Name must match file name in options/license or custom/options/license.
 - `DISABLE_HTTP_GIT`: **false**: Disable the ability to interact with repositories over the
@@ -141,8 +177,12 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
 - `DEFAULT_MERGE_MESSAGE_OFFICIAL_APPROVERS_ONLY`: **true**: In default merge messages only include approvers who are officially allowed to review.
 - `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: In default squash-merge messages include the commit message of all commits comprising the pull request.
 - `ADD_CO_COMMITTER_TRAILERS`: **true**: Add co-authored-by and co-committed-by trailers to merge commit messages if committer does not match author.
-- `TEST_CONFLICTING_PATCHES_WITH_GIT_APPLY`: **false**: PR patches are tested using a three-way merge method to discover if there are conflicts. If this setting is set to **true**, conflicting patches will be retested using `git apply` - This was the previous behaviour in 1.18 (and earlier) but is somewhat inefficient. Please report if you find that this setting is required.
 - `RETARGET_CHILDREN_ON_MERGE`: **true**: Retarget child pull requests to the parent pull request branch target on merge of parent pull request. It only works on merged PRs where the head and base branch target the same repo.
+- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: Set the default value for "Delete pull request branch after merge by default" for new repositories.
+- `DEFAULT_TITLE_SOURCE`: **auto**: Default source for the pull request title when opening a new PR. Valid options:
+  - `first-commit`: Uses the oldest commit's summary as the title. If there are multiple commits, still uses the first commit's message.
+  - `auto`: Uses the commit's summary when the PR contains a single commit; when there are multiple commits, converts the branch name into a human-readable title by normalizing separators and casing.
+  - `branch-name`: Always uses the PR's branch name.
 
 ### Repository - Issue (`repository.issue`)
 
@@ -159,9 +199,11 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
 
 ### Repository - Release (`repository.release`)
 
-- `ALLOWED_TYPES`: **_empty_**: Comma-separated list of allowed file extensions (`.zip`), mime types (`text/plain`) or wildcard type (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types.
+- `ALLOWED_TYPES`: **_empty_**: Comma-separated list of allowed release attachment file extensions (`.zip`), mime types (`text/plain`) or wildcard type (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types.
 - `DEFAULT_PAGING_NUM`: **10**: The default paging number of releases user interface
-- For settings related to file attachments on releases, see the `attachment` section.
+- `FILE_MAX_SIZE`: **2048**: Max filesize limit for release attachments (MB)
+- `MAX_FILES`: **5**: Maximum number of release attachments that can be uploaded at once for a release.
+- For other settings related to file attachments on releases, see the `attachment` section.
 
 ### Repository - Signing (`repository.signing`)
 
@@ -209,7 +251,6 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `MAX_AGE`: **10m**: max time to cache response
 - `ALLOW_CREDENTIALS`: **false**: allow request with credentials
 - `HEADERS`: **Content-Type,User-Agent**: additional headers that are permitted in requests
-- `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value.
 
 ## UI (`ui`)
 
@@ -224,7 +265,8 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `DEFAULT_THEME`: **gitea-auto**: Set the default theme for the Gitea installation, custom themes could be provided by `{CustomPath}/public/assets/css/theme-*.css`.
 - `SHOW_USER_EMAIL`: **true**: Whether the email of the user should be shown in the Explore Users page.
 - `THEMES`: **_empty_**: All available themes by `{CustomPath}/public/assets/css/theme-*.css`. Allow users select personalized themes.
-- `FILE_ICON_THEME`: **material**: The icons for file list (basic/material).
+- `FILE_ICON_THEME`: **material**: The icon theme for files (basic/material).
+- `FOLDER_ICON_THEME`: **basic**: The icon theme for folders (basic/material).
 - `MAX_DISPLAY_FILE_SIZE`: **8388608**: Max size of files to be displayed (default is 8MiB)
 - `AMBIGUOUS_UNICODE_DETECTION`: **true**: Detect ambiguous unicode characters in file contents and show warnings on the UI
 - `REACTIONS`: All available reactions users can choose on issues/prs and comments
@@ -309,11 +351,11 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `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`: **`legacy`**: Controls how to generate the public URL. 
-   Although it defaults to "legacy" (to avoid breaking existing users), most instances should use the "auto" behavior,
+- `PUBLIC_URL_DETECTION`: **`auto`**: Controls how to generate the public URL. Most instances should use the "auto" behavior,
    especially when the Gitea instance needs to be accessed in a container network.
    - "legacy": generate the public URL by "Host" header if "X-Forwarded-Proto" header exists, otherwise use "ROOT_URL".
    - "auto": always use "Host" header, and also use "X-Forwarded-Proto" header if it exists. If no "Host" header, use "ROOT_URL".
+   - "never": always use "ROOT_URL", never detect from request headers.
 - `STATIC_URL_PREFIX`: **_empty_**:
    Overwrite this option to request static resources from a different URL.
    This includes CSS files, images, JS files and web fonts.
@@ -362,16 +404,16 @@ The following configuration set `Content-Type: application/vnd.android.package-a
   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_PORT`: **22**: SSH port displayed in clone 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.
-- `SSH_ROOT_PATH`: **~/.ssh**: Root path of SSH directory.
-- `SSH_CREATE_AUTHORIZED_KEYS_FILE`: **true**: Gitea will create a authorized_keys file by default when it is not using the internal ssh server. If you intend to use the AuthorizedKeysCommand functionality then you should turn this off.
+- `SSH_ROOT_PATH`: **_empty_**: Root path of SSH user directory for the system's standalone SSH server if Gitea is not using its builtin SSH server. Default is the '.ssh' directory in the run user's home directory.
+- `SSH_CREATE_AUTHORIZED_KEYS_FILE`: **true**: Gitea will create an authorized_keys file by default when it is not using the builtin SSH server. If you intend to use the AuthorizedKeysCommand functionality then you should turn this off.
 - `SSH_AUTHORIZED_KEYS_BACKUP`: **false**: Enable SSH Authorized Key Backup when rewriting all keys, default is false.
 - `SSH_TRUSTED_USER_CA_KEYS`: **_empty_**: Specifies the public keys of certificate authorities that are trusted to sign user certificates for authentication. Multiple keys should be comma separated. E.g.`ssh-<algorithm> <key>` or `ssh-<algorithm> <key1>, ssh-<algorithm> <key2>`. For more information see `TrustedUserCAKeys` in the sshd config man pages. When empty no file will be created and `SSH_AUTHORIZED_PRINCIPALS_ALLOW` will default to `off`.
 - `SSH_TRUSTED_USER_CA_KEYS_FILENAME`: **`RUN_USER`/.ssh/gitea-trusted-user-ca-keys.pem**: Absolute path of the `TrustedUserCaKeys` file Gitea will manage. If you're running your own ssh server and you want to use the Gitea managed file you'll also need to modify your sshd_config to point to this file. The official docker image will automatically work without further configuration.
 - `SSH_AUTHORIZED_PRINCIPALS_ALLOW`: **off** or **username, email**: \[off, username, email, anything\]: Specify the principals values that users are allowed to use as principal. When set to `anything` no checks are done on the principal string. When set to `off` authorized principal are not allowed to be set.
-- `SSH_CREATE_AUTHORIZED_PRINCIPALS_FILE`: **false/true**: Gitea will create a authorized_principals file by default when it is not using the internal ssh server and `SSH_AUTHORIZED_PRINCIPALS_ALLOW` is not `off`.
+- `SSH_CREATE_AUTHORIZED_PRINCIPALS_FILE`: **false/true**: Gitea will create an authorized_principals file by default when it is not using the builtin SSH server and `SSH_AUTHORIZED_PRINCIPALS_ALLOW` is not `off`.
 - `SSH_AUTHORIZED_PRINCIPALS_BACKUP`: **false/true**: Enable SSH Authorized Principals Backup when rewriting all keys, default is true if `SSH_AUTHORIZED_PRINCIPALS_ALLOW` is not `off`.
 - `SSH_AUTHORIZED_KEYS_COMMAND_TEMPLATE`: **`{{.AppPath}} --config={{.CustomConf}} serv key-{{.Key.ID}}`**: Set the template for the command to passed on authorized keys. Possible keys are: AppPath, AppWorkPath, CustomConf, CustomPath, Key - where Key is a `models/asymkey.PublicKey` and the others are strings which are shellquoted.
 - `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.
@@ -478,7 +520,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
     - `require`: Enable TLS without any verifications.
     - `verify-ca`: Enable TLS with verification of the database server certificate against its root certificate.
     - `verify-full`: Enable TLS and verify the database server name matches the given certificate in either the `Common Name` or `Subject Alternative Name` fields.
-- `SQLITE_TIMEOUT`: **500**: Query timeout for SQLite3 only.
+- `SQLITE_TIMEOUT`: **20000**: Query timeout in milliseconds, for SQLite3 only.
 - `SQLITE_JOURNAL_MODE`: **""**: Change journal mode for SQlite3. Can be used to enable [WAL mode](https://www.sqlite.org/wal.html) when high load causes write congestion. See [SQlite3 docs](https://www.sqlite.org/pragma.html#pragma_journal_mode) for possible values. Defaults to the default for the database file, often DELETE.
 - `ITERATE_BUFFER_SIZE`: **50**: Internal buffer size for iterating.
 - `PATH`: **data/gitea.db**: For SQLite3 only, the database file path.
@@ -498,14 +540,14 @@ relation to port exhaustion.
 
 ## Indexer (`indexer`)
 
-- `ISSUE_INDEXER_TYPE`: **bleve**: Issue indexer type, currently supported: `bleve`, `db`, `elasticsearch` or `meilisearch`.
+- `ISSUE_INDEXER_TYPE`: **bleve**: Issue indexer type, currently supported: `bleve`, `db`, `elasticsearch` (also compatible with OpenSearch) or `meilisearch`.
 - `ISSUE_INDEXER_CONN_STR`: ****: Issue indexer connection string, available when ISSUE_INDEXER_TYPE is elasticsearch (e.g. `http://elastic:password@localhost:9200`) or meilisearch (e.g. `http://:apikey@localhost:7700`)
 - `ISSUE_INDEXER_NAME`: **gitea_issues**: Issue indexer name, available when ISSUE_INDEXER_TYPE is elasticsearch or meilisearch.
 - `ISSUE_INDEXER_PATH`: **indexers/issues.bleve**: Index file used for issue search; available when ISSUE_INDEXER_TYPE is bleve and elasticsearch. Relative paths will be made absolute against _`AppWorkPath`_.
 
 - `REPO_INDEXER_ENABLED`: **false**: Enables code search (uses a lot of disk space, about 6 times more than the repository size).
 - `REPO_INDEXER_REPO_TYPES`: **sources,forks,mirrors,templates**: Repo indexer units. The items to index could be `sources`, `forks`, `mirrors`, `templates` or any combination of them separated by a comma. If empty then it defaults to `sources` only, as if you'd like to disable fully please see `REPO_INDEXER_ENABLED`.
-- `REPO_INDEXER_TYPE`: **bleve**: Code search engine type, could be `bleve` or `elasticsearch`.
+- `REPO_INDEXER_TYPE`: **bleve**: Code search engine type, could be `bleve` or `elasticsearch` (also compatible with OpenSearch).
 - `REPO_INDEXER_PATH`: **indexers/repos.bleve**: Index file used for code search.
 - `REPO_INDEXER_CONN_STR`: ****: Code indexer connection string, available when `REPO_INDEXER_TYPE` is elasticsearch. i.e. `http://elastic:password@localhost:9200`
 - `REPO_INDEXER_NAME`: **gitea_codes**: Code indexer name, available when `REPO_INDEXER_TYPE` is elasticsearch
@@ -574,6 +616,7 @@ And the following unique queues:
 - `LOGIN_REMEMBER_DAYS`: **31**: How long to remember that a user is logged in before requiring relogin (in days).
 - `COOKIE_REMEMBER_NAME`: **gitea\_incredible**: Name of cookie used to store authentication
    information.
+- `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.
 - `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: Header name for reverse proxy
@@ -583,6 +626,9 @@ And the following unique queues:
 - `REVERSE_PROXY_LIMIT`: **1**: Interpret X-Forwarded-For header or the X-Real-IP header and set this as the remote IP for the request.
    Number of trusted proxy count. Set to zero to not use these headers.
 - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all.
+- `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value for all HTTP responses. Set to `unset` to not send the header. Previously located in `[cors]`.
+- `X_CONTENT_TYPE_OPTIONS`: **nosniff**: Set the `X-Content-Type-Options` header value for all HTTP responses. Set to `unset` to not send the header.
+- `CONTENT_SECURITY_POLICY_GENERAL`: **_empty_**: The value of the general Content-Security-Policy for most web pages. Leave it empty to apply the default policy, or set it to "unset" to disable Content-Security-Polic.
 - `DISABLE_GIT_HOOKS`: **true**: Set to `false` to enable users with Git Hook privilege to create custom Git Hooks.
 
   :::warning
@@ -628,6 +674,14 @@ 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.
+  - Built-in networks:
+    - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6, localhost is included.
+    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7). Also called LAN/Intranet.
+    - `external`: A valid non-private unicast IP, you can access all hosts on public internet.
+    - `*`: All hosts are allowed.
+  - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6
+  - Wildcard hosts: `*.mydomain.com`, `192.168.100.*`
 
 ## Camo (`camo`)
 
@@ -775,14 +829,6 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
 
 - `QUEUE_LENGTH`: **1000**: Hook task queue length. Use caution when editing this value.
 - `DELIVER_TIMEOUT`: **5**: Delivery timeout (sec) for shooting webhooks.
-- `ALLOWED_HOST_LIST`: **external**: Webhook can only call allowed hosts for security reasons. Comma separated list.
-  - Built-in networks:
-    - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6, localhost is included.
-    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7). Also called LAN/Intranet.
-    - `external`: A valid non-private unicast IP, you can access all hosts on public internet.
-    - `*`: All hosts are allowed.
-  - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6
-  - Wildcard hosts: `*.mydomain.com`, `192.168.100.*`
 - `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.
@@ -819,7 +865,7 @@ and
   - Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or SMTP host is localhost. See [Email Setup](email-setup.md) for more information.
 - `ENABLE_HELO`: **true**: Enable HELO operation.
 - `HELO_HOSTNAME`: **(retrieved from system)**: HELO hostname.
-- `FROM`: **_empty_**: Mail from address, RFC 5322. This can be just an email address, or the "Name" `\<email@example.com\>` format.
+- `FROM`: **_empty_**: Mail from address, RFC 5322. This can be just an email address, or the `"Name" <email@example.com>` format.
 - `ENVELOPE_FROM`: **_empty_**: Address set as the From address on the SMTP mail envelope. Set to `<>` to send an empty address.
 - `FROM_DISPLAY_NAME_FORMAT`: **`{{ .DisplayName }}`**: If gitea sends mails on behave of users, it will just use the name also displayed in the WebUI. If you want e.g. `Mister X (by CodeIt) <gitea@codeit.net>`, set it to `{{ .DisplayName }} (by {{ .AppName }})`. Available Variables: `.DisplayName`, `.AppName` and `.Domain`.
 - `SUBJECT_PREFIX`: **_empty_**: Prefix to be placed before e-mail subject lines.
@@ -919,12 +965,15 @@ Default templates for project board view:
 - `PROJECT_BOARD_BASIC_KANBAN_TYPE`: **To Do, In Progress, Done**
 - `PROJECT_BOARD_BUG_TRIAGE_TYPE`: **Needs Triage, High Priority, Low Priority, Closed**
 
-## Issue and pull request attachments (`attachment`)
+## Issue, pull-request and release attachments (`attachment`)
 
-- `ENABLED`: **true**: Whether issue and pull request attachments are enabled.
-- `ALLOWED_TYPES`: **.avif,.cpuprofile,.csv,.dmp,.docx,.fodg,.fodp,.fods,.fodt,.gif,.gz,.jpeg,.jpg,.json,.jsonc,.log,.md,.mov,.mp4,.odf,.odg,.odp,.ods,.odt,.patch,.pdf,.png,.pptx,.svg,.tgz,.txt,.webm,.webp,.xls,.xlsx,.zip**: Comma-separated list of allowed file extensions (`.zip`), mime types (`text/plain`) or wildcard type (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types.
-- `MAX_SIZE`: **2048**: Maximum size (MB).
-- `MAX_FILES`: **5**: Maximum number of attachments that can be uploaded at once.
+ALLOWED_TYPES/MAX_SIZE/MAX_FILES in this section only affect issue and pull-request attachments, not release attachments.
+Release attachment has its own config options in `[repository.release]` section.
+
+- `ENABLED`: **true**: Whether issue, pull-request and release attachments are enabled.
+- `ALLOWED_TYPES`: **.avif,.cpuprofile,.csv,.dmp,.docx,.fodg,.fodp,.fods,.fodt,.gif,.gz,.jpeg,.jpg,.json,.jsonc,.log,.md,.mov,.mp4,.odf,.odg,.odp,.ods,.odt,.patch,.pdf,.png,.pptx,.svg,.tgz,.txt,.webm,.webp,.xls,.xlsx,.zip**: Comma-separated list of allowed issue/pull-request attachment file extensions (`.zip`), mime types (`text/plain`) or wildcard type (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types.
+- `MAX_SIZE`: **100**: Max size of each issue/pull-request attachment file in MB.
+- `MAX_FILES`: **5**: Maximum number of issue/pull-request attachments that can be uploaded at once.
 - `STORAGE_TYPE`: **local**: Storage type for attachments, it could be `<blank>`, `local`, `minio`, `azureblob` or `xxx` which defined in another section with `[storage.xxx]`.
 
   For `STORAGE_TYPE = ` or there is no this configuration item, all storages will be derived from `[storage]` if configured or defult values.
@@ -933,7 +982,7 @@ Default templates for project board view:
 
   - `PATH`: **attachments**: Path to store attachments only available when STORAGE_TYPE is `local`, relative paths will be resolved to `{AppDataPath}/{attachment.PATH}`.
 
-  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#storage_minio), you can override some configurations like below.
+  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#minio-storage-configuration-storage_minio), you can override some configurations like below.
 
   - `MINIO_BASE_PATH`: **attachments/**: Minio base path on the bucket only available when STORAGE_TYPE is `minio`
 
@@ -1096,6 +1145,13 @@ Synchronize external user data (only LDAP user synchronization is supported)
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling deleted branches cleanup.
 - `OLDER_THAN`: **24h**: Branches deleted OLDER_THAN ago will be cleaned up.
 
+#### Cron - Synchronize repository licenses (`cron.sync_repo_licenses`)
+
+- `ENABLED`: **false**: Enable deleted branches cleanup.
+- `RUN_AT_START`: **false**: Run job at start time (if ENABLED).
+- `NOTICE_ON_SUCCESS`: **false**: Set to true to log a success message.
+- `SCHEDULE`: **@annually*: Cron syntax for scheduling synchronization of repository licenses
+
 ### Extended cron tasks
 
 #### Cron - Delete all repository archives (`cron.delete_repo_archives`)
@@ -1119,7 +1175,14 @@ 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 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
+- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling synchronization of gitea ssh keys, e.g. `@every 1h`.
+
+#### Cron - Update the '.ssh/authorized_principals' file (`cron.resync_all_sshprincipals`)
+
+- `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 72h**: Cron syntax for scheduling update of authorized_principals, e.g. `@every 1h`.
 
 #### Cron - Resynchronize pre-receive, update and post-receive hooks of all repositories (`cron.resync_all_hooks`)
 
@@ -1183,6 +1246,43 @@ Synchronize external user data (only LDAP user synchronization is supported)
 - `NUMBER_TO_CHECK_PER_REPO`: **100**: Minimum number of stale LFSMetaObjects to check per repo. Set to `0` to always check all.
 - `PROPORTION_TO_CHECK_PER_REPO`: **0.6**: Check at least this proportion of LFSMetaObjects per repo. (This may cause all stale LFSMetaObjects to be checked.)
 
+### Actions cron tasks
+
+#### Cron - Rebuild issue index (`cron.rebuild_issue_indexer`)
+
+- `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.
+- `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.
+- `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.
+- `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.
+- `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.
+- `SCHEDULE`: **@every 1m**: Cron syntax to set how often to schedule tasks
+
 ## Git (`git`)
 
 - `PATH`: **""**: The path of Git executable. If empty, Gitea searches through the PATH environment.
@@ -1203,20 +1303,20 @@ Synchronize external user data (only LDAP user synchronization is supported)
 - `LARGE_OBJECT_THRESHOLD`: **1048576**: (Go-Git only), don't cache objects greater than this in memory. (Set to 0 to disable.)
 - `DISABLE_CORE_PROTECT_NTFS`: **false** Set to true to forcibly set `core.protectNTFS` to false.
 - `DISABLE_PARTIAL_CLONE`: **false** Disable the usage of using partial clones for git.
+- `DIFF_RENAME_SIMILARITY_THRESHOLD`: **50%** Set the similarity threshold passed to git commands via `--find-renames=<threshold>`. Default is 50%, the same as git. Must be a integer percentage between 0% and 100%.
 
 ### Git - Timeout settings (`git.timeout`)
 
-- `DEFAULT`: **360**: Git operations default timeout seconds.
 - `MIGRATE`: **600**: Migrate external repositories timeout seconds.
 - `MIRROR`: **300**: Mirror external repositories timeout seconds.
-- `CLONE`: **300**: Git clone from internal repositories timeout seconds.
-- `PULL`: **300**: Git pull from internal repositories timeout seconds.
 - `GC`: **60**: Git repository GC timeout seconds.
 
 ### Git - Config options (`git.config`)
 
-The key/value pairs in this section will be used as git config.
-This section only does "set" config, a removed config key from this section won't be removed from git config automatically. The format is `some.configKey = value`.
+The key/value pairs in this section will be used as git config. The format is `some.configKey = value`.
+These options are written into the gitconfig file under `[git] HOME_PATH` when Gitea starts, and are applied **after** Gitea's built-in defaults — so values set here take precedence over the defaults listed below.
+
+**Note:** This section only does "set" config; a removed config key from this section won't be removed from git config automatically. Some config options might affect the behavior of git and cause Gitea's git operations to fail — make sure you know what you are doing before making changes.
 
 - `diff.algorithm`: **histogram**
 - `core.logAllRefUpdates`: **true**
@@ -1249,6 +1349,9 @@ This section only does "set" config, a removed config key from this section won'
 - `JWT_SIGNING_PRIVATE_KEY_FILE`: **jwt/private.pem**: Private key file path used to sign OAuth2 tokens. The path is relative to `APP_DATA_PATH`. This setting is only needed if `JWT_SIGNING_ALGORITHM` is set to `RS256`, `RS384`, `RS512`, `ES256`, `ES384` or `ES512`. The file must contain a RSA or ECDSA private key in the PKCS8 format. If no key exists a 4096 bit key will be created for you.
 - `MAX_TOKEN_LENGTH`: **32767**: Maximum length of token/cookie to accept from OAuth2 provider
 - `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, tea**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options.
+- `CUSTOM_SCHEMES`: **_empty_**: By default, OAuth2 applications can only use "http" and "https" as their redirect URI schemes.
+  If you need to use other schemes (e.g. for desktop applications), you can specify them here as a comma-separated list.
+  For example: set "my-scheme, com.example.app" to support "my-scheme://..." and "com.example.app://..." redirect URIs.
 
 ## i18n (`i18n`)
 
@@ -1376,6 +1479,7 @@ in this mapping or the filetype using heuristics.
 - `LIMIT_SIZE_RUBYGEMS`: **-1**: Maximum size of a RubyGems upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_SWIFT`: **-1**: Maximum size of a Swift upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_VAGRANT`: **-1**: Maximum size of a Vagrant upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
+- `LIMIT_SIZE_TERRAFORM_STATE``: **-1**: Maximum size of a Terraform state upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 
 ## Mirror (`mirror`)
 
@@ -1399,7 +1503,7 @@ is `data/lfs` and the default of `MINIO_BASE_PATH` is `lfs/`.
 
 - `PATH`: **./data/lfs**: Where to store LFS files, only available when `STORAGE_TYPE` is `local`. If not set it fall back to deprecated LFS_CONTENT_PATH value in [server] section.
 
-  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#storage_minio), you can also define configurations like below to override derived or default values.
+  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#minio-storage-configuration-storage_minio), you can also define configurations like below to override derived or default values.
 
   - `MINIO_BASE_PATH`: **attachments/**: Minio base path on the bucket only available when STORAGE_TYPE is `minio`
 
@@ -1550,7 +1654,7 @@ is `data/repo-archive` and the default of `MINIO_BASE_PATH` is `repo-archive/`.
 
   - `PATH`: **./data/repo-archive**: Where to store archive files, only available when `STORAGE_TYPE` is `local`.
 
-  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#storage_minio), you can override some configurations like below.
+  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#minio-storage-configuration-storage_minio), you can override some configurations like below.
 
   - `MINIO_BASE_PATH`: **repo-archive/**: Minio base path on the bucket only available when `STORAGE_TYPE` is `minio`
 
@@ -1595,6 +1699,9 @@ PROXY_HOSTS = *.github.com
 - `ENDLESS_TASK_TIMEOUT`: **3h**: Timeout to stop the tasks which have running status and continuous updates, but don't end for a long time
 - `ABANDONED_JOB_TIMEOUT`: **24h**: Timeout to cancel the jobs which have waiting status, but haven't been picked by a runner for a long time
 - `SKIP_WORKFLOW_STRINGS`: **[skip ci],[ci skip],[no ci],[skip actions],[actions skip]**: Strings committers can place inside a commit message or PR title to skip executing the corresponding actions workflow
+- `WORKFLOW_DIRS`: **.gitea/workflows,.github/workflows**: Comma-separated list of workflow directories, the first one to exist in a repo is used to find Actions workflow files.
+- `SCOPED_WORKFLOW_DIRS`: **.gitea/scoped_workflows**: Comma-separated list of directories holding [scoped workflows](usage/actions/scoped-workflows.md) (workflows defined in a central source repository that run on other repositories). Must not overlap with `WORKFLOW_DIRS`. Leave empty so no directory is scanned for scoped workflows; none are found or run.
+- `MAX_RERUN_ATTEMPTS`: **50**: Maximum number of attempts a single workflow run can have (initial run + reruns). Defaults value is 50. Set any positive value that fits your workflow needs.
 
 `DEFAULT_ACTIONS_URL` indicates where the Gitea Actions runners should find the actions with relative path.
 For example, `uses: actions/checkout@v4` means `https://github.com/actions/checkout@v4` since the value of `DEFAULT_ACTIONS_URL` is `github`.

docs/administration/customizing-gitea.md

@@ -9,7 +9,7 @@ aliases:
 # Customizing Gitea
 
 Customizing Gitea is typically done using the `CustomPath` folder - by default this is
-the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/installation.md) has
+the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/from-binary.md) has
 set this differently. This is the central place to override configuration settings,
 templates, etc. You can check the `CustomPath` using `gitea help`. You can also find
 the path on the _Configuration_ tab in the _Site Administration_ page. You can override
@@ -23,7 +23,7 @@ the Linux Filesystem Standard. Gitea will attempt to create required folders, in
 `custom/`. Distributions may provide a symlink for `custom` using `/etc/gitea/`.
 
 Application settings can be found in file `CustomConf` which is by default,
-`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/installation.md) has set this differently.
+`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/from-binary.md) has set this differently.
 Again `gitea help` will allow you review this variable and you can override it using the
 `--config` option on the `gitea` binary.
 
@@ -317,11 +317,17 @@ mkdir o3dv
 cd o3dv
 ```
 
-Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.16.0 as of now).
-Here use e.g. wget to download the file:
+Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.18.0 as of now).
+Here use e.g. wget or curl to download the file:
 
 ```
-wget https://github.com/kovacsv/Online3DViewer/releases/download/0.16.0/o3dv.zip
+wget https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
+```
+
+or
+
+```
+curl -L -O https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
 ```
 
 Use e.g. unzip to unzip the archive:
@@ -347,7 +353,7 @@ $GITEA_CUSTOM/templates
 
 $GITEA_CUSTOM/public/assets/
 -- o3dv
-   |-- o3dv_0.15.0.zip
+   |-- o3dv.zip
    |-- o3dv.license.md
    |-- o3dv.min.js
    |-- envmaps
@@ -388,15 +394,16 @@ Starting with Gitea 1.20, you can customize the git configuration via the `git.c
 
 ### Enabling signed git pushes
 
-To enable signed git pushes, set these two options:
+[Signed pushes](https://git-scm.com/docs/git-push#Documentation/git-push.txt---signedtruefalseif-asked) allow clients to cryptographically sign the push operation itself (not just individual commits). To enable signed pushes, add the following to `app.ini`:
 
 ```ini
 [git.config]
-receive.advertisePushOptions = true
 receive.certNonceSeed = <randomstring>
 ```
 
-`certNonceSeed` should be set to a random string and be kept secret.
+`certNonceSeed` should be set to a random string and be kept secret. It is used to generate anti-replay nonces. Gitea already sets `receive.advertisePushOptions = true` by default, so no additional configuration is needed. Note that Gitea does not read `/etc/gitconfig`, so this option must be set via `app.ini` as shown above.
+
+On the client side, pushes can be signed via `git push --signed` or enabled permanently using `git config --global push.gpgSign if-asked`.
 
 ### Labels
 
@@ -414,7 +421,7 @@ The [legacy file format](https://github.com/go-gitea/gitea/blob/main/options/lab
 
 `#hex-color label name ; label description`
 
-For more information, see the [labels documentation](usage/labels.md).
+For more information, see the [labels documentation](../usage/issues-prs/labels.md).
 
 ### Licenses
 

docs/administration/email-setup.md

@@ -45,7 +45,7 @@ ENABLED        = true
 FROM           = gitea@mydomain.com
 PROTOCOL       = smtps
 SMTP_ADDR      = mail.mydomain.com
-SMTP_PORT      = 587
+SMTP_PORT      = 465
 USER           = gitea@mydomain.com
 PASSWD         = `password`
 ```

docs/administration/mail-templates.md

@@ -257,7 +257,6 @@ the messages. Here's a list of some of them:
 | `AppDomain`      | -           | Any       | Gitea's host name                                                   |
 | `EllipsisString` | string, int | Any       | Truncates a string to the specified length; adds ellipsis as needed |
 | `SanitizeHTML`   | string      | Body only | Sanitizes text by removing any dangerous HTML tags from it          |
-| `SafeHTML`       | string      | Body only | Takes the input as HTML, can be used for outputing raw HTML content |
 
 These are _functions_, not metadata, so they have to be used:
 

docs/administration/reverse-proxies.md

@@ -13,7 +13,7 @@ aliases:
 1. Set `[server] ROOT_URL = https://git.example.com/` in your `app.ini` file.
 2. Make the reverse-proxy pass `https://git.example.com/foo` to `http://gitea:3000/foo`.
 3. Make sure the reverse-proxy does not decode the URI. The request `https://git.example.com/a%2Fb` should be passed as `http://gitea:3000/a%2Fb`.
-4. Make sure `Host` and `X-Fowarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
+4. Make sure `Host` and `X-Forwarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
 5. Make sure your webserver has a certificate, including all intermediate and RootCA certificates, for `git clone` and `git pull` to work.
 
 ### Use a sub-path
@@ -210,6 +210,50 @@ Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com
 The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
 :::
 
+## Apache HTTPD and serve static resources directly
+
+We can tune the performance in splitting requests into categories static and dynamic.
+
+CSS files, JavaScript files, images and web fonts are static content.
+The front page, a repository view or issue list is dynamic content.
+
+Apache HTTPD can serve static resources directly and proxy only the dynamic requests to Gitea.
+
+Download a snapshot of the Gitea source repository to `/path/to/gitea/`.
+After this, run `make frontend` in the repository directory to generate the static resources. We are only interested in the `public/` directory for this task, so you can delete the rest.
+(You will need to have [Node with npm](https://nodejs.org/en/download/) and `make` installed to generate the static resources)
+
+Depending on the scale of your user base, you might want to split the traffic to two distinct servers,
+or use a cdn for the static files.
+
+### Single node and single domain
+
+Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration.
+
+```apacheconf
+<VirtualHost *:80>
+    ...
+    <Proxy *>
+         Order allow,deny
+         Allow from all
+    </Proxy>
+
+    ProxyPass /_/static/ !
+    Alias /_/static/ /path/to/gitea/public/
+    <Directory /path/to/gitea/public/>
+        Options FollowSymlinks
+		AllowOverride None
+		Require all granted
+    </Directory>
+
+    AllowEncodedSlashes NoDecode
+    # Note: no trailing slash after either /git or port
+    ProxyPass / http://localhost:3000/ nocanon
+    ProxyPreserveHost On
+    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+</VirtualHost>
+```
+
 ## Caddy
 
 If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile:

docs/development/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Development",
+  "position": 40,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development",
+    "title": "Development"
+  }
+}

docs/development/api-usage.md

@@ -20,14 +20,33 @@ Gitea supports these methods of API authentication:
 - `token=...` parameter in URL query string
 - `access_token=...` parameter in URL query string
 - `Authorization: token ...` header in HTTP headers
+- HTTP signatures using an SSH public key or SSH certificate
 
 All of these methods accept the same API key token type. You can
 better understand this by looking at the code -- as of this writing,
 Gitea parses queries and headers to find the token in
 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
 
+Gitea can also authenticate API requests using an SSH key or SSH certificate via
+HTTP signatures. The SSH public key (or certificate) must be registered to the
+user account in Gitea, and the client signs requests with the corresponding
+private key. The client signs requests using the SSH private key following the
+[draft-cavage-http-signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
+specification (not RFC 9421). The signature is sent in the `Signature` header,
+and SSH certificates additionally include an `x-ssh-certificate` header. The
+official [go-sdk](https://gitea.com/gitea/go-sdk) implements this flow if you
+need a reference implementation.
+
 ## Generating and listing API tokens
 
+API tokens can be created either in the user interface or via the API. Tokens have by default limited permissions and it is important to create tokens with the correct permissions for your task.
+### User Interface
+Tokens can be created via the `Manage Access Tokens` dialog, accessed via `User Settings` / `Applications` or via the link `gitea-domain.example/user/settings/applications`. The interface allows you to create tokens and manage their permissions via the `Select permissions` sub-menu.
+
+Once created, the token is displayed in a toast message above the `Manage Access Tokens` dialog. Please note, that you can view this toast only once and it is not possible to redisplay the token for security reasons.
+
+### Token API
+
 A new token can be generated with a `POST` request to
 `/users/:name/tokens`.
 
@@ -50,6 +69,25 @@ $ curl --url https://yourusername:password@gitea.your.host/api/v1/users/<usernam
 [{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
 ```
 
+By default, this creates a token with very limited permissions. To complete your tasks, your token may require extra permissions. These permissions are created via the json variable `scopes`, which takes an array of permissions as strings. Eg.: `"scopes":["all"]`. Possible permissions, as reflected in the user interface are:
+
+- `activitypub`
+- `admin`
+- `issue`
+- `misc`
+- `notification`
+- `organization`
+- `package`
+- `repository`
+- `user`
+
+Each permission may be set to `read` or `write`. `write` implies both Read & Write. To set permissions you write the permissions string as `<read or write>:<permission name>`, eg.: `write:package` or `read:notification`. A properly formatted API call may look like:
+
+```sh
+$ curl -H "Content-Type: application/json" -d '{"name":"test", "scopes":["write:package", "read:notification"]}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
+```
+Special permissions `all` may be specified as `"scopes":["all"]`, which sets all permissions to both Read & Write.
+
 To use the API with basic authentication with two factor authentication
 enabled, you'll need to send an additional header that contains the one
 time password (6 digitrotating token).

docs/help/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Help",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "slug": "/help",
+    "title": "Help"
+  }
+}

docs/help/faq.md

@@ -33,7 +33,7 @@ then the config file (app.ini) should exists in the "custom/conf" directory of y
 Some package vendors might use "/etc/gitea" to store the config file, while some others don't.
 
 You could manually find the config file (app.ini) by checking Gitea's startup logs
-or reading the Gitea Web's Site Administrator -> Confugiraton Summary.
+or reading the Gitea Web's Site Administrator -> Configuration Summary.
 
 If you are using some isolated enviroments like container (docker),
 the path you see usually is not what it is in the host's filesystem.

docs/installation/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Installation",
+  "position": 10,
+  "link": {
+    "type": "generated-index",
+    "slug": "/installation",
+    "title": "Installation"
+  }
+}

docs/installation/from-binary.md

@@ -40,7 +40,24 @@ chmod +x gitea
 
 Note that the above command will download Gitea @version@ for 64-bit Linux.
 
-## Verify GPG signature
+## Verify signature
+
+### Sigstore
+
+Starting with v1.27 Gitea signs all binaries using [sigstore](https://sigstore.dev/) to prevent against unwanted modification of binaries.
+To validate the binary, download the bundle file which ends in `sigstore.json` for the binary you downloaded and use the [cosign](https://docs.sigstore.dev/cosign/system_config/installation/) command line tool.
+
+```sh
+cosign verify-blob gitea-@version@-linux-amd64 --bundle gitea-@version@-linux-amd64.sigstore.json --certificate-oidc-issuer=https://token.actions.githubusercontent.com --certificate-identity-regexp="https://github.com/go-gitea/gitea/.github/workflows/release-.*"
+```
+
+If the command outputs `Verified OK`, binary was not modified.
+
+:::note
+The above command will match any release workflow. You may choose to restrict the identity further by requiring a specific branch or workflow to be matched. For example this url will match only nightly builds made on main branch: `https://github.com/go-gitea/gitea/.github/workflows/release-nightly.yml@refs/heads/main`
+:::
+
+### GPG
 
 Gitea signs all binaries with a [GPG key](https://keys.openpgp.org/search?q=teabot%40gitea.io) to prevent against unwanted modification of binaries.
 To validate the binary, download the signature file which ends in `.asc` for the binary you downloaded and use the GPG command line tool.
@@ -53,6 +70,7 @@ gpg --verify gitea-@version@-linux-amd64.asc gitea-@version@-linux-amd64
 Look for the text `Good signature from "Teabot <teabot@gitea.io>"` to assert a good binary,
 despite warnings like `This key is not certified with a trusted signature!`.
 
+
 ## Recommended server configuration
 
 :::note
@@ -139,15 +157,15 @@ export GITEA_WORK_DIR=/var/lib/gitea/
 cp gitea /usr/local/bin/gitea
 ```
 
-### Adding bash/zsh autocompletion (from 1.19)
 
-A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This can be copied to `/usr/share/bash-completion/completions/gitea`
-or sourced within your `.bashrc`.
+### Adding shell autocompletion (from 1.25)
 
-Similarly a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
-`.zshrc`.
+Shell completion can be generated directly from binary with:
+```sh
+gitea completion <shell>
+```
 
-YMMV and these scripts may need further improvement.
+Supported values for `<shell>` are `bash`, `fish`, `pwsh` and `zsh`. Details on how to load the completion for your shell can be found in the completion command help.
 
 ## Running Gitea
 
@@ -214,9 +232,7 @@ As of v1.8, there is a problem with the arm7 version of Gitea, and it doesn't ru
 
 It is recommended to switch to the arm6 version, which has been tested and shown to work on Raspberry Pis and similar devices.
 
-<!---
-please remove after fixing the arm7 bug
---->
+{/* please remove after fixing the arm7 bug */}
 ### Git error after updating to a new version of Gitea
 
 If during the update, the binary file name has been changed to a new version of Gitea,

docs/installation/from-source.md

@@ -6,6 +6,8 @@ aliases:
   - /en-us/install-from-source
 ---
 
+:::warning This document is outdated, pleaes refer to [build-source.md](https://github.com/go-gitea/gitea/tree/main/docs/build-source.md):::
+
 # Installation from source
 
 You should [install go](https://go.dev/doc/install) and set up your go
@@ -178,15 +180,14 @@ LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo
 
 This can be combined with `CC`, `GOOS`, and `GOARCH` as above.
 
-### Adding bash/zsh autocompletion (from 1.19)
+### Adding shell autocompletion (from 1.25)
 
-A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This should be altered as appropriate and can be `source` in your `.bashrc`
-or copied as `/usr/share/bash-completion/completions/gitea`.
+Shell completion can be generated directly from binary with:
+```sh
+gitea completion <shell>
+```
 
-Similarly, a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
-`.zshrc`.
-
-YMMV and these scripts may need further improvement.
+Supported values for `<shell>` are `bash`, `fish`, `pwsh` and `zsh`. Details on how to load the completion for your shell can be found in the completion command help.
 
 ## Compile or cross-compile using Linux with Zig
 

docs/installation/with-docker-rootless.md

@@ -8,15 +8,19 @@ aliases:
 
 # Installation with Docker (rootless)
 
-Gitea provides automatically updated Docker images within its Docker Hub organization. It is
-possible to always use the latest stable tag or to use another service that handles updating
-Docker images.
+## Relation to rootful image
 
-The rootless image uses Gitea internal SSH to provide Git protocol and doesn't support OpenSSH.
+* Rootless image doesn't require "root" privilege on the host, while it may have stricter UID/GID requirement.
+* Rootless image must use its bulitin SSH server, while the rootful one must its managed standalone OpenSSH server.
+* The volume mapping and directory layout is different between them.
 
-This reference setup guides users through the setup based on `docker-compose`, but the installation
-of `docker-compose` is out of scope of this documentation. To install `docker-compose` itself, follow
-the official [install instructions](https://docs.docker.com/compose/install/).
+Except the differences above, the rootless image shares the same mechanism with rootful image,
+including: port mapping, custimzation, upgrading, environment variables, etc.
+Read more in "[Installation with Docker (rootful)](./with-docker.md)"
+
+ATTENTION: the rootful/rootless images are not compatible with the other.
+If you have chosen one, you should always use the same one,
+don't switch to the other one by changing the compose file's `image` value.
 
 ## Basics
 
@@ -34,8 +38,6 @@ touch docker-compose.yml
 Then paste the following content into a file named `docker-compose.yml`:
 
 ```yaml
-version: "2"
-
 services:
   server:
     image: docker.gitea.com/gitea:@dockerVersion@-rootless
@@ -56,116 +58,16 @@ Note that the volume should be owned by the user/group with the UID/GID specifie
 sudo chown 1000:1000 config/ data/
 ```
 
-> If you don't give the volume correct permissions, the container may not start.
+> If you don't give the volume correct permissions, the container may present the following errors in the logs:
+
+```sh
+server-1  | 2026-03-11T12:57:50.794102045Z mkdir: can't create directory '/var/lib/gitea/git': Permission denied
+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`)
 
-## Custom port
-
-To bind the integrated ssh and the webserver on a different port, adjust
-the port section. It's common to just change the host port and keep the ports within
-the container like they are.
-
-```diff
-version: "2"
-
-services:
-  server:
-    image: docker.gitea.com/gitea:@dockerVersion@-rootless
-    restart: always
-    volumes:
-      - ./data:/var/lib/gitea
-      - ./config:/etc/gitea
-      - /etc/timezone:/etc/timezone:ro
-      - /etc/localtime:/etc/localtime:ro
-    ports:
--      - "3000:3000"
--      - "2222:2222"
-+      - "80:3000"
-+      - "22:2222"
-```
-
-## MySQL database
-
-To start Gitea in combination with a MySQL database, apply these changes to the
-`docker-compose.yml` file created above.
-
-```diff
-version: "2"
-
-services:
-  server:
-    image: docker.gitea.com/gitea:@dockerVersion@-rootless
-+    environment:
-+      - GITEA__database__DB_TYPE=mysql
-+      - GITEA__database__HOST=db:3306
-+      - GITEA__database__NAME=gitea
-+      - GITEA__database__USER=gitea
-+      - GITEA__database__PASSWD=gitea
-    restart: always
-    volumes:
-      - ./data:/var/lib/gitea
-      - ./config:/etc/gitea
-      - /etc/timezone:/etc/timezone:ro
-      - /etc/localtime:/etc/localtime:ro
-    ports:
-      - "3000:3000"
-      - "2222:2222"
-+    depends_on:
-+      - db
-+
-+  db:
-+    image: docker.io/library/mysql:8
-+    restart: always
-+    environment:
-+      - MYSQL_ROOT_PASSWORD=gitea
-+      - MYSQL_USER=gitea
-+      - MYSQL_PASSWORD=gitea
-+      - MYSQL_DATABASE=gitea
-+    volumes:
-+      - ./mysql:/var/lib/mysql
-```
-
-## PostgreSQL database
-
-To start Gitea in combination with a PostgreSQL database, apply these changes to
-the `docker-compose.yml` file created above.
-
-```diff
-version: "2"
-
-services:
-  server:
-    image: docker.gitea.com/gitea:@dockerVersion@-rootless
-    environment:
-+      - GITEA__database__DB_TYPE=postgres
-+      - GITEA__database__HOST=db:5432
-+      - GITEA__database__NAME=gitea
-+      - GITEA__database__USER=gitea
-+      - GITEA__database__PASSWD=gitea
-    restart: always
-    volumes:
-      - ./data:/var/lib/gitea
-      - ./config:/etc/gitea
-      - /etc/timezone:/etc/timezone:ro
-      - /etc/localtime:/etc/localtime:ro
-    ports:
-      - "3000:3000"
-      - "2222:2222"
-+    depends_on:
-+      - db
-+
-+  db:
-+    image: docker.io/library/postgres:14
-+    restart: always
-+    environment:
-+      - POSTGRES_USER=gitea
-+      - POSTGRES_PASSWORD=gitea
-+      - POSTGRES_DB=gitea
-+    volumes:
-+      - ./postgres:/var/lib/postgresql/data
-```
-
 ## Named volumes
 
 To use named volumes instead of host volumes, define and use the named volume
@@ -174,8 +76,6 @@ create the required volume. You don't need to worry about permissions with
 named volumes; Docker will deal with that automatically.
 
 ```diff
-version: "2"
-
 +volumes:
 +  gitea-data:
 +    driver: local
@@ -207,8 +107,6 @@ As an example to clone the host user `git` definition use the command `id -u git
 Please make sure that the mounted folders are writable by the user.
 
 ```diff
-version: "2"
-
 services:
   server:
     image: docker.gitea.com/gitea:@dockerVersion@-rootless
@@ -223,143 +121,3 @@ services:
       - "3000:3000"
       - "2222:2222"
 ```
-
-## Startup
-
-:::note
-From July 2023 Compose V1 stopped receiving updates. It's also no longer available in new releases of Docker Desktop.
-
-Compose V2 is included with all currently supported versions of Docker Desktop. Please use V2 to do below operations.
-:::
-
-To start this setup based on `docker-compose`, execute `docker-compose up -d`,
-to launch Gitea in the background. Using `docker-compose ps` will show if Gitea
-started properly. Logs can be viewed with `docker-compose logs`.
-
-To shut down the setup, execute `docker-compose down`. This will stop
-and kill the containers. The volumes will still exist.
-
-:::note
-If using a non-3000 port on http, change app.ini to match
-`LOCAL_ROOT_URL = http://localhost:3000/`.
-:::
-
-## Install
-
-After starting the Docker setup via `docker-compose`, Gitea should be available using a
-favorite browser to finalize the installation. Visit http://server-ip:3000 and follow the
-installation wizard. If the database was started with the `docker-compose` setup as
-documented above, please note that `db` must be used as the database hostname.
-
-## Customization
-
-Customization files described [here](../administration/customizing-gitea.md) should
-be placed in `/var/lib/gitea/custom` directory. If using host volumes, it's quite easy to access these
-files; for named volumes, this is done through another container or by direct access at
-`/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea`. The configuration file will be saved at
-`/etc/gitea/app.ini` after the installation.
-
-## Upgrading
-
-:::warning
-:exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation:
-:::
-
-To upgrade your installation to the latest release:
-
-```bash
-# Edit `docker-compose.yml` to update the version, if you have one specified
-# Pull new images
-docker-compose pull
-# Start a new container, automatically removes old one
-docker-compose up -d
-```
-
-## Upgrading from standard image
-
-- Backup your setup
-- Change volume mountpoint from /data to /var/lib/gitea
-- If you used a custom app.ini move it to a new volume mounted to /etc/gitea
-- Rename folder (inside volume) gitea to custom
-- Edit app.ini if needed
-  - Set START_SSH_SERVER = true
-- Use image docker.gitea.com/gitea:@dockerVersion@-rootless
-
-## Managing Deployments With Environment Variables
-
-In addition to the environment variables above, any settings in `app.ini` can be set
-or overridden with an environment variable of the form: `GITEA__SECTION_NAME__KEY_NAME`.
-These settings are applied each time the docker container starts, and won't be passed into Gitea's sub-processes.
-Full information [here](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini).
-
-These environment variables can be passed to the docker container in `docker-compose.yml`.
-The following example will enable a smtp mail server if the required env variables
-`GITEA__mailer__FROM`, `GITEA__mailer__HOST`, `GITEA__mailer__PASSWD` are set on the host
-or in a `.env` file in the same directory as `docker-compose.yml`.
-
-The settings can be also set or overridden with the content of a file by defining an environment variable of the form:
-`GITEA__section_name__KEY_NAME__FILE` that points to a file.
-
-```bash
-...
-services:
-  server:
-    environment:
-      - GITEA__mailer__ENABLED=true
-      - GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
-      - GITEA__mailer__PROTOCOL=smtp
-      - GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
-      - GITEA__mailer__IS_TLS_ENABLED=true
-      - GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
-      - GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
-```
-
-To set required TOKEN and SECRET values, consider using Gitea's built-in [generate utility functions](../administration/command-line.md#generate).
-
-# SSH Container Passthrough
-
-Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is to forward SSH commands from the host to the container. This setup is explained in the following.
-
-This guide assumes that you have created a user on the host called `git` with permission to run `docker exec`, and that the Gitea container is called `gitea`. You will need to modify that user's shell to forward the commands to the `sh` executable inside the container, using `docker exec`.
-
-First, create the file `/usr/local/bin/gitea-shell` on the host, with the following contents:
-
-```bash
-#!/bin/sh
-/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
-```
-
-Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that.
-
-You should also make sure that you’ve set the permissions of the shell wrapper correctly:
-
-```bash
-sudo chmod +x /usr/local/bin/gitea-shell
-```
-
-Once the wrapper is in place, you can make it the shell for the `git` user:
-
-```bash
-sudo usermod -s /usr/local/bin/gitea-shell git
-```
-
-Now that all the SSH commands are forwarded to the container, you need to set up the SSH authentication on the host. This is done by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea. Add the following block to `/etc/ssh/sshd_config`, on the host:
-
-```bash
-Match User git
-  AuthorizedKeysCommandUser git
-  AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
-```
-
-(From 1.16.0 you will not need to set the `-c /etc/gitea/app.ini` option.)
-
-All that is left to do is restart the SSH server:
-
-```bash
-sudo systemctl restart sshd
-```
-
-**Notes**
-
-This isn't actually using the docker SSH - it is simply using the commands around it.
-You could theoretically not run the internal SSH server.

docs/installation/with-docker.md

@@ -12,9 +12,16 @@ Gitea provides automatically updated Docker images within its Docker Hub organiz
 possible to always use the latest stable tag or to use another service that handles updating
 Docker images.
 
-This reference setup guides users through the setup based on `docker-compose`, but the installation
-of `docker-compose` is out of scope of this documentation. To install `docker-compose` itself, follow
-the official [install instructions](https://docs.docker.com/compose/install/).
+This reference setup guides users through the setup based on `docker compose`.
+Docker compose has been included in the Docker Engine since the shift to Compose v2.
+If, for some reason, compose is not available on your system, follow the official [install instructions](https://docs.docker.com/compose/install/).
+
+This document targets for the default rootful image. For the rootless image,
+see "[Installation with Docker (rootless)](./with-docker-rootless.md)"
+
+ATTENTION: the rootful/rootless images are not compatible with the other.
+If you have chosen one, you should always use the same one,
+don't switch to the other one by changing the compose file's `image` value.
 
 ## Basics
 
@@ -26,8 +33,6 @@ 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`)
 
 ```yaml
-version: "3"
-
 networks:
   gitea:
     external: false
@@ -58,8 +63,6 @@ the port section. It's common to just change the host port and keep the ports wi
 the container like they are.
 
 ```diff
-version: "3"
-
 networks:
   gitea:
     external: false
@@ -93,8 +96,6 @@ To start Gitea in combination with a MySQL database, apply these changes to the
 `docker-compose.yml` file created above.
 
 ```diff
-version: "3"
-
 networks:
   gitea:
     external: false
@@ -144,8 +145,6 @@ To start Gitea in combination with a PostgreSQL database, apply these changes to
 the `docker-compose.yml` file created above.
 
 ```diff
-version: "3"
-
 networks:
   gitea:
     external: false
@@ -196,8 +195,6 @@ create the required volume. You don't need to worry about permissions with
 named volumes; Docker will deal with that automatically.
 
 ```diff
-version: "3"
-
 networks:
   gitea:
     external: false
@@ -227,17 +224,11 @@ MySQL or PostgreSQL containers will need to be created separately.
 
 ## Startup
 
-:::note
-From July 2023 Compose V1 stopped receiving updates. It's also no longer available in new releases of Docker Desktop.
+To start this setup based on `docker compose`, execute `docker compose up -d`,
+to launch Gitea in the background. Using `docker compose ps` will show if Gitea
+started properly. Logs can be viewed with `docker compose logs`.
 
-Compose V2 is included with all currently supported versions of Docker Desktop. Please use V2 to do below operations.
-:::
-
-To start this setup based on `docker-compose`, execute `docker-compose up -d`,
-to launch Gitea in the background. Using `docker-compose ps` will show if Gitea
-started properly. Logs can be viewed with `docker-compose logs`.
-
-To shut down the setup, execute `docker-compose down`. This will stop
+To shut down the setup, execute `docker compose down`. This will stop
 and kill the containers. The volumes will still exist.
 
 :::note
@@ -247,9 +238,9 @@ If using a non-3000 port on http, change app.ini to match
 
 ## Installation
 
-After starting the Docker setup via `docker-compose`, Gitea should be available using a
+After starting the Docker setup via `docker compose`, Gitea should be available using a
 favorite browser to finalize the installation. Visit http://server-ip:3000 and follow the
-installation wizard. If the database was started with the `docker-compose` setup as
+installation wizard. If the database was started with the `docker compose` setup as
 documented above, please note that `db` must be used as the database hostname.
 
 ## Configure the user inside Gitea using environment variables
@@ -279,17 +270,18 @@ To upgrade your installation to the latest release:
 ```bash
 # Edit `docker-compose.yml` to update the version, if you have one specified
 # Pull new images
-docker-compose pull
+docker compose pull
 # Start a new container, automatically removes old one
-docker-compose up -d
+docker compose up -d
 ```
 
 ## Managing Deployments With Environment Variables
 
 In addition to the environment variables above, any settings in `app.ini` can be set
-or overridden with an environment variable of the form: `GITEA__SECTION_NAME__KEY_NAME`.
-These settings are applied each time the docker container starts, and won't be passed into Gitea's sub-processes.
-Full information [here](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini).
+or overridden with an environment variable of the form: `GITEA__section_name__KEY_NAME=value`.
+These settings are applied each time the docker container starts by `environment-to-ini` command
+(a warpper of `gitea config edit-ini`), and won't be passed into Gitea's sub-processes.
+See `./gitea config edit-ini --help` for more details.
 
 These environment variables can be passed to the docker container in `docker-compose.yml`.
 The following example will enable an smtp mail server if the required env variables
@@ -331,320 +323,7 @@ services:
       - GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
 ```
 
-## SSH Container Passthrough
-
-Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker. Alternatively, if the host machine has more than one IP address, the host can listen on one and Gitea on another.
-
-### Understanding SSH access to Gitea (without passthrough)
-
-To understand what needs to happen, you first need to understand what happens without passthrough. So we will try to explain this:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
-3. This entry has the public key, but also has a `command=` option. It is this command that Gitea uses to match this key to the client user and manages authentication.
-4. The client then makes an SSH request to the SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-5. The client will attempt to authenticate with the server, passing one or more public keys one at a time to the server.
-6. For each key the client provides, the SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the `git` user's `authorized_keys` file.
-7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
-8. The SSH server creates a user session for the `git` user, and using the shell for the `git` user runs the `command=`
-9. This runs `gitea serv` which takes over control of the rest of the SSH session and manages gitea authentication & authorization of the git commands.
-
-Now, for the SSH passthrough to work, we need the host SSH to match the public keys and then run the `gitea serv` on the docker. There are multiple ways of doing this. However, all of these require some information about the docker being passed to the host.
-
-### SSHing Shim (with authorized_keys)
-
-In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 9 the `gitea` command that the host runs is a shim that actually runs ssh to go into the docker and then run the real docker `gitea` itself.
-
-- To make the forwarding work, the SSH port of the container (22) needs to be mapped to the host port 2222 in `docker-compose.yml` . Since this port does not need to be exposed to the outside world, it can be mapped to the `localhost` of the host machine:
-
-  ```yaml
-  ports:
-    # [...]
-    - "127.0.0.1:2222:22"
-  ```
-
-- Next on the host create the `git` user which shares the same `UID`/ `GID` as the container values `USER_UID`/ `USER_GID`. These values can be set as environment variables in the `docker-compose.yml`:
-
-  ```yaml
-  environment:
-    - USER_UID=1000
-    - USER_GID=1000
-  ```
-
-- Mount `/home/git/.ssh` of the host into the container. This ensures that the `authorized_keys` file is shared between the host `git` user and the container `git` user otherwise the SSH authentication cannot work inside the container.
-
-  ```yaml
-  volumes:
-    - /home/git/.ssh/:/data/git/.ssh
-  ```
-
-- Now a SSH key pair needs to be created on the host. This key pair will be used to authenticate the `git` user on the host to the container. As an administrative user on the host run: (by administrative user we mean a user that can sudo to root)
-
-  ```bash
-  sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
-  ```
-
-- Please note depending on the local version of ssh you may want to consider using `-t ecdsa` here.
-
-- `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `/home/git/.ssh/authorized_keys`. As an administrative user on the host run:
-
-  ```bash
-  sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
-  sudo -u git chmod 600 /home/git/.ssh/authorized_keys
-  ```
-
-  Important: The pubkey from the `git` user needs to be added "as is" while all other pubkeys added via the Gitea web interface will be prefixed with `command="/usr [...]`.
-
-  `/home/git/.ssh/authorized_keys` should then look somewhat like
-
-  ```bash
-  # SSH pubkey from git user
-  ssh-rsa <Gitea Host Key>
-
-  # other keys from users
-  command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
-  ```
-
-- The next step is to create the fake host `gitea` command that will forward commands from the host to the container. The name of this file depends on your version of Gitea:
-
-  - For Gitea v1.16.0+. As an administrative user on the host run:
-
-    ```bash
-    cat <<"EOF" | sudo tee /usr/local/bin/gitea
-    #!/bin/sh
-    ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
-    EOF
-    sudo chmod +x /usr/local/bin/gitea
-    ```
-
-Here is a detailed explanation what is happening when a SSH request is made:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
-    - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
-3. This entry has the public key, but also has a `command=` option.
-    - This command matches the location of the Gitea binary on the container, but also the location of the shim on the host.
-4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
-6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
-    - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
-7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
-8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
-9. This means that the host runs the host `/usr/local/bin/gitea` shim that opens an SSH from the host to container passing the rest of the command arguments directly to `/usr/local/bin/gitea` on the container.
-10. Meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
-
-**Notes**
-
-SSH container passthrough using `authorized_keys` will work only if
-
-- `opensshd` is used in the container
-- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
-- `LOCAL_ROOT_URL` is not changed (depending on the changes)
-
-If you try to run `gitea` on the host, you will attempt to ssh to the container and thence run the `gitea` command there.
-
-Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
-
-### SSHing Shell (with authorized_keys)
-
-In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 8 above we change the shell that the host runs to ssh directly into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
-
-- In this case we setup as per SSHing Shim except instead of creating `/usr/local/bin/gitea`
-we create a new shell for the git user. As an administrative user on the host run:
-
-  ```bash
-  cat <<"EOF" | sudo tee /home/git/ssh-shell
-  #!/bin/sh
-  shift
-  ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $@"
-  EOF
-  sudo chmod +x /home/git/ssh-shell
-  sudo usermod -s /home/git/ssh-shell git
-  ```
-
-  Be careful here - if you try to login as the git user in future you will ssh directly to the docker.
-
-Here is a detailed explanation what is happening when a SSH request is made:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
-    - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
-3. This entry has the public key, but also has a `command=` option.
-    - This command matches the location of the Gitea binary on the container.
-4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
-6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
-    - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
-7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
-8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
-9. The shell of the host `git` user is now our `ssh-shell` which opens an SSH connection from the host to container, (which opens a shell on the container for the container `git`).
-10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
-
-**Notes**
-
-SSH container passthrough using `authorized_keys` will work only if
-
-- `opensshd` is used in the container
-- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
-- `LOCAL_ROOT_URL` is not changed (depending on the changes)
-
-If you try to login as the `git` user on the host in future you will ssh directly to the docker.
-
-Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
-
-### Docker Shell (with authorized_keys)
-
-Similar to the above ssh shell technique we can use a shell which simply uses `docker exec`. As an administrative user on the host run:
-
-```bash
-cat <<"EOF" | sudo tee /home/git/docker-shell
-#!/bin/sh
-/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
-EOF
-sudo chmod +x /home/git/docker-shell
-sudo usermod -s /home/git/docker-shell git
-```
-
-Here is a detailed explanation what is happening when a SSH request is made:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
-    - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
-3. This entry has the public key, but also has a `command=` option.
-    - This command matches the location of the Gitea binary on the container.
-4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
-6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
-    - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
-7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
-8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
-9. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
-10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
-
-Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that. The host `git` user also has to have
-permission to run `docker exec`.
-
-**Notes**
-
-Docker shell passthrough using `authorized_keys` will work only if
-
-- `opensshd` is used in the container
-- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
-- `LOCAL_ROOT_URL` is not changed (depending on the changes)
-
-If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
-
-A Docker execing shim could be created similarly to above.
-
-### Docker Shell with AuthorizedKeysCommand
-
-The AuthorizedKeysCommand route provides another option that does not require many changes to the compose file or the `authorized_keys` - but does require changes to the host `/etc/sshd_config`.
-
-In this option, the idea is that the host SSH uses an `AuthorizedKeysCommand` instead of relying on sharing the `authorized_keys` file that gitea creates. We continue to use a special shell at step 8 above to exec into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
-
-- On the host create a `git` user with permission to run `docker exec`.
-- We will again assume that the Gitea container is called `gitea`.
-- Modify the `git` user's shell to forward commands to the `sh` executable inside the container using `docker exec`.  As an administrative user on the host run:
-
-  ```bash
-  cat <<"EOF" | sudo tee /home/git/docker-shell
-  #!/bin/sh
-  /usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
-  EOF
-  sudo chmod +x /home/git/docker-shell
-  sudo usermod -s /home/git/docker-shell git
-  ```
-
-Now all attempts to login as the `git` user on the host will be forwarded to the docker - including the `SSH_ORIGINAL_COMMAND`. We now need to set-up SSH authentication on the host.
-
-We will do this by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea.
-
-Add the following block to `/etc/ssh/sshd_config`, on the host:
-
-```bash
-Match User git
-  AuthorizedKeysCommandUser git
-  AuthorizedKeysCommand /usr/bin/docker exec -i -u git gitea /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
-```
-
-(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
-
-Finally restart the SSH server. As an administrative user on the host run:
-
-```bash
-sudo systemctl restart sshd
-```
-
-Here is a detailed explanation what is happening when a SSH request is made:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea in the container will add an entry for this key to its database.
-3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
-5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
-6. The host runs the above `AuthorizedKeysCommand`, which execs in to the docker and then runs the `gitea keys` command.
-7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
-8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
-9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
-10. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
-11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
-
-**Notes**
-
-Docker shell passthrough using `AuthorizedKeysCommand` will work only if
-
-- The host `git` user is allowed to run the `docker exec` command.
-
-If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
-
-A Docker execing shim could be created similarly to above.
-
-### SSH Shell with AuthorizedKeysCommand
-
-Create a key for the host `git` user as above, add it to the docker `/data/git/.ssh/authorized_keys` then finally create and set the `ssh-shell` as above.
-
-Add the following block to `/etc/ssh/sshd_config`, on the host:
-
-```bash
-Match User git
-  AuthorizedKeysCommandUser git
-  AuthorizedKeysCommand /usr/bin/ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
-```
-
-(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
-
-Finally restart the SSH server. As an administrative user on the host run:
-
-```bash
-sudo systemctl restart sshd
-```
-
-Here is a detailed explanation what is happening when a SSH request is made:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea in the container will add an entry for this key to its database.
-3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
-5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
-6. The host runs the above `AuthorizedKeysCommand`, which will SSH in to the docker and then run the `gitea keys` command.
-7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
-8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
-9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
-10. The shell of the host `git` user is now our `git-shell` which uses SSH to open a shell for the `git` user on the container.
-11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
-
-**Notes**
-
-SSH container passthrough using `AuthorizedKeysCommand` will work only if
-
-- `opensshd` is running on the container
-
-If you try to login as the `git` user on the host in future you will `ssh` directly to the docker.
-
-Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
-
-SSHing shims could be created similarly to above.
-
 ### SSH with multiple IP addresses
+
 This assumes that the host machine has more than one reachable IP address: `192.168.1.1` (host) `192.168.1.2` (gitea)
 On the host machine, configure SSHD in `/etc/ssh/sshd_config` to listen on one IP address `ListenAddress 192.168.1.1`. In the compose file the SSH port forwarding then needs to be changed to `"192.168.1.2:22:22"`. The port forwarding needs to be adjusted similarily for all other forwarded ports to avoid problems with DNS.

docs/usage/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Usage",
+  "position": 35,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage",
+    "title": "Usage"
+  }
+}

docs/usage/access-control/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Access Control",
+  "position": 100,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/access-control",
+    "description": "Permissions, security, and access control features"
+  }
+}

docs/usage/access-control/blocking-users.md

@@ -0,0 +1,47 @@
+---
+date: "2024-01-31T00:00:00+00:00"
+slug: "blocking-user"
+sidebar_position: 25
+aliases:
+  - /blocking-user
+---
+
+# Blocking a user
+
+Gitea supports blocking of users to restrict how they can interact with you and your content.
+
+You can block a user in your account settings, from the user's profile or from comments created by the user.
+The user is not directly notified about the block, but they can notice they are blocked when they attempt to interact with you.
+Organization owners can block anyone who is not a member of the organization too.
+If a blocked user has admin permissions, they can still perform all actions even if blocked.
+
+### When you block a user
+
+- the user stops following you
+- you stop following the user
+- the user's stars are removed from your repositories
+- your stars are removed from their repositories
+- the user stops watching your repositories
+- you stop watching their repositories
+- the user's issue assignments are removed from your repositories
+- your issue assignments are removed from their repositories
+- the user is removed as a collaborator on your repositories
+- you are removed as a collaborator on their repositories
+- any pending repository transfers to or from the blocked user are canceled
+
+### When you block a user, the user cannot
+
+- follow you
+- watch your repositories
+- star your repositories
+- fork your repositories
+- transfer repositories to you
+- open issues or pull requests on your repositories
+- comment on issues or pull requests you've created
+- comment on issues or pull requests on your repositories
+- react to your comments on issues or pull requests
+- react to comments on issues or pull requests on your repositories
+- assign you to issues or pull requests
+- add you as a collaborator on their repositories
+- send you notifications by @mentioning your username
+- be added as team member (if blocked by an organization)

docs/usage/access-control/permissions.md

@@ -1,11 +1,10 @@
 ---
 date: "2021-12-13:10:10+08:00"
-
 slug: "permissions"
 sidebar_position: 14
-
 aliases:
   - /en-us/permissions
+  - /permissions
 ---
 
 # Permissions
@@ -41,7 +40,7 @@ With different permissions, people could do different things with these units.
 | Wiki            | View wiki pages. Clone the wiki repository.        | Create/Edit wiki pages, push | -                         |
 | ExternalWiki    | Link to an external wiki                           | -                            | -                         |
 | ExternalTracker | Link to an external issue tracker                  | -                            | -                         |
-| Projects        | View the boards                                    | Change issues across boards  | -                         |
+| Projects        | View the columns of projects                       | Change issues across columns | -                         |
 | Packages        | View the packages                                  | Upload/Delete packages       | -                         |
 | Actions         | View the Actions logs                              | Approve / Cancel / Restart   | -                         |
 | Settings        | -                                                  | -                            | Manage the repository     |

docs/usage/access-control/protected-branches.md

@@ -0,0 +1,90 @@
+---
+date: "2025-11-20T00:00:00-07:00"
+slug: "protected-branches"
+sidebar_position: 44
+aliases:
+  - /en-us/protected-branches
+  - /en-us/protected-branch
+  - /protected-branches
+---
+
+# Protected branches
+
+Protected branches prevent unwanted changes by enforcing push and merge policies on selected branches. The rules are enforced for every Git protocol (HTTP(S), SSH), the web editor, the API, and background jobs such as auto-merge. Only repository owners and administrators can manage the rules, and the Branches page is read-only while a repository is archived.
+
+## Creating or editing a rule
+
+1. Open the repository and select **Settings → Branches** (repository admin permission required).
+2. Select **Add new rule** or **Edit** next to an existing rule.
+3. Fill in the **Protected branch name pattern** and optional file patterns, then configure the push, merge, and review options described below.
+4. Select **Save rule**.
+
+The rule immediately applies to all matching branches, even if the branches are created in the future.
+
+## Rule matching and priorities
+
+- The **Protected branch name pattern** accepts [glob](https://github.com/gobwas/glob) expressions and matches the entire branch name. Patterns are case-sensitive. Using a simple name such as `main` without glob special characters always matches that specific branch (case-insensitive).
+- If multiple rules match the same branch, only the first rule is used. Reorder the list on the **Branches** page by dragging the grab handle. The first entry (priority 1) has the highest priority, so place patterns such as `main` or `release/*` before generic fallbacks such as `*`.
+
+Example patterns:
+
+| Pattern        | Matches                         |
+| -------------- | ------------------------------- |
+| `main`         | The `main` branch only          |
+| `release/*`    | `release/v1.0`, `release/april` |
+| `hotfix/**`    | Nested branches such as `hotfix/security/CVE` |
+| `*`            | Every branch (use as a fallback) |
+
+### File-level pattern controls
+
+- **Protected file patterns** block changes to sensitive files (for example `.drone.yml` or `/docs/**/*.txt`). Patterns are case-insensitive and separated by semicolons. Commits and merge attempts that touch one of the files are rejected.
+- **Unprotected file patterns** do the opposite: if pushes are blocked, users with write access can still push commits that modify only the listed files. This is useful for letting contributors update documentation while still requiring pull requests for code.
+
+Both fields use the same `glob` syntax and match paths relative to the repository root.
+
+## Controlling direct pushes
+
+The **Push** section controls direct pushes (including the web editor and API).
+
+- **Disable push** makes the branch read-only. Any attempt to push directly fails, and changes must be merged through pull requests.
+- **Enable push** allows anyone with [write access](./permissions.md) to push (force pushes are still blocked unless explicitly allowed).
+- **Allowlist restricted push** requires being on the allowlist. Choose users and, for organization-owned repositories, teams. Deploy keys that already have write access can also be allowlisted.
+
+When a push is blocked, the server-side hook rejects the update with an explanation.
+
+### Force pushes
+
+Force pushes have their own set of options:
+
+- **Disable force push** completely forbids rewriting history on the branch.
+- **Enable force push** allows anyone who can push to also force push.
+- **Allowlist restricted force push** limits force pushes to a separate allowlist (users, teams, and optionally deploy keys) **and** requires the person to already have regular push access.
+
+## Pull request merges and approvals
+
+- **Merge allowlist**: keep the default to let anyone with write access merge pull requests, or enable the allowlist to restrict merges to selected users/teams.
+- **Required approvals**: specify how many approvals are needed before a merge is allowed. Reviews from users with write access count, unless the **Restrict approvals to allowlisted users or teams** option is enabled.
+- **Dismiss stale approvals** removes existing approvals whenever new commits that change the pull request content are pushed.
+- **Ignore stale approvals** keeps approvals but does not count reviews that were made on older commits. This option is disabled while dismissal of stale approvals is enabled.
+- **Block merge on rejected reviews** prevents merging while any official reviewer has requested changes.
+- **Block merge on official review requests** blocks merges while there are outstanding review requests (for example when CODEOWNERS requires a review).
+- **Block merge if the pull request is outdated** makes sure the head branch is up to date with the base branch before it can be merged.
+- **Administrators must follow branch protection rules** removes the ability for repository administrators to bypass the rules with the "Force merge" button.
+
+Protected file patterns apply to pull requests as well. When a pull request changes one of the protected files, the pull request banner shows the affected paths and merging stays disabled.
+
+## Status checks
+
+Enable status checks to require one or more CI jobs to succeed before merging:
+
+1. Check **Enable status check**.
+2. Enter one pattern per line in **Status check patterns**. Each pattern is a `glob` expression that matches the context name reported by Actions, Drone, Woodpecker, or another Check API client (for example `actions/test-*`).
+3. Pick contexts from the table of jobs that have reported results in the last week to verify their names.
+
+When the option is active, Gitea requires at least one context that matches each pattern to report success on the pull request head commit. An empty list is not allowed; use `*` to require the latest commit to be successful regardless of the context name.
+
+## Signed commits and other safeguards
+
+- **Require signed commits** rejects pushes that contain unsigned or unverifiable commits. The check runs inside the server hook before the push is accepted.
+- **Protected file patterns** (see above) prevent both pushes and merges that modify sensitive files.
+- **Unprotected file patterns** allow limited pushes while keeping the branch protected.

docs/usage/access-control/protected-tags.md

@@ -4,6 +4,7 @@ slug: "protected-tags"
 sidebar_position: 45
 aliases:
   - /en-us/protected-tags
+  - /protected-tags
 ---
 
 # Protected tags

docs/usage/actions/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Actions",
+  "position": 30,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/actions",
+    "description": "Automating workflows with Actions"
+  }
+}

docs/usage/actions/comparison.md

@@ -26,38 +26,6 @@ Github Actions doesn't support that. https://docs.github.com/en/actions/using-wo
 
 ## Unsupported workflows syntax
 
-### `concurrency`
-
-It's used to run a single job at a time.
-See [Using concurrency](https://docs.github.com/en/actions/using-jobs/using-concurrency).
-
-It's ignored by Gitea Actions now.
-
-### `run-name`
-
-The name for workflow runs generated from the workflow.
-See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#run-name).
-
-It's ignored by Gitea Actions now.
-
-### `permissions` and `jobs.<job_id>.permissions`
-
-See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions).
-
-It's ignored by Gitea Actions now.
-
-### `jobs.<job_id>.timeout-minutes`
-
-See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes).
-
-It's ignored by Gitea Actions now.
-
-### `jobs.<job_id>.continue-on-error`
-
-See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error).
-
-It's ignored by Gitea Actions now.
-
 ### `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).
@@ -107,6 +75,15 @@ Services steps don't have their own section in the job log user interface.
 
 ## Different behavior
 
+### Job token permissions (`permissions`)
+
+Gitea supports `permissions` and `jobs.<job_id>.permissions` to control the default `GITEA_TOKEN` permissions.
+
+The effective permissions are clamped by the repository/owner settings and are further restricted for fork pull requests and cross-repository access.
+GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not supported, while Gitea-specific scopes such as `code`, `releases`, `wiki`, and `projects` are available.
+
+See [Actions job token permissions](token-permissions.md).
+
 ### Downloading actions
 
 Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.

docs/usage/actions/design.md

@@ -8,33 +8,9 @@ sidebar_position: 140
 
 Gitea Actions has multiple components. This document describes them individually.
 
-## Act
+## Gitea Runner
 
-The [nektos/act](https://github.com/nektos/act) project is an excellent tool that allows you to run your GitHub Actions locally.
-We were inspired by this and wondered if it would be possible to run actions for Gitea.
-
-However, while [nektos/act](https://github.com/nektos/act) is designed as a command line tool, what we actually needed was a Go library with modifications specifically for Gitea.
-So we forked it as [gitea/act](https://gitea.com/gitea/act).
-
-This is a soft fork that will periodically follow the upstream.
-Although some custom commits have been added, we will try our best to avoid changing too much of the original code.
-
-The forked act is just a shim or adapter for Gitea's specific usage.
-There are some additional commits that have been made, such as:
-
-- Outputting execution logs to logger hook so they can be reported to Gitea
-- Disabling the GraphQL URL, since Gitea doesn't support it
-- Starting a new container for every job instead of reusing to ensure isolation.
-
-These modifications have no reason to be merged into the upstream.
-They don't make sense if the user just wants to run trusted actions locally.
-
-However, there may be overlaps in the future, such as a required bug fix or new feature needed by both projects.
-In these cases, we will contribute the changes back to the upstream repository.
-
-## Act runner
-
-Gitea's runner is called act runner because it's based on act.
+Gitea Runner is based on a hard fork of [nektos/act](https://github.com/nektos/act).
 
 Like other CI runners, we designed it as an external part of Gitea, which means it should run on a different server than Gitea.
 
@@ -47,7 +23,7 @@ That's why when you add custom labels during registration, you will need to inpu
 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.
-The act also supports running jobs directly on the host.
+The runner also supports running jobs directly on the host.
 This is achieved through labels like `linux_arm:host`.
 This label indicates that the runner can take a job that needs to run on `linux_arm` and run it directly on the host.
 
@@ -62,7 +38,7 @@ So,
 
 ## Communication protocol
 
-As act runner is an independent part of Gitea, we needed a protocol for runners to communicate with the Gitea instance.
+As the runner is an independent part of Gitea, we needed a protocol for runners to communicate with the Gitea instance.
 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.
@@ -79,9 +55,9 @@ This will help you troubleshoot some problems and explain why it's a bad idea to
 
 There are four network connections marked in the picture, and the direction of the arrows indicates the direction of establishing the connections.
 
-### Connection 1, act runner to Gitea instance
+### Connection 1, runner to Gitea instance
 
-The act runner must be able to connect to Gitea to receive tasks and send back the execution results.
+The runner must be able to connect to Gitea to receive tasks and send back the execution results.
 
 ### Connection 2, job containers to Gitea instance
 
@@ -92,9 +68,9 @@ Fetching code is not always necessary to run some jobs, but it is required in mo
 If you use a loopback address to register a runner, the runner can connect to Gitea when it is on the same machine.
 However, if a job container tries to fetch code from localhost, it will fail because Gitea is not in the same container.
 
-### Connection 3, act runner to internet
+### Connection 3, runner to internet
 
-When you use some actions like `actions/checkout@v4`, the act runner downloads the scripts, not the job containers.
+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.
 It also downloads some docker images from Docker Hub by default, which also requires internet access.
 

docs/usage/actions/faq.md

@@ -55,7 +55,7 @@ If you want to give more permissions to the runner, allowing it to access more p
 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 act runner?
+## Which operating systems are supported by Gitea Runner?
 
 We released official binaries for Linux, macOS, and Windows.
 While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
@@ -101,7 +101,7 @@ It is exciting to be able to reuse them.
 
 This is valid syntax.
 It means that it should run on runners that have both the `label_a` **and** `label_b` labels, see [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
-Unfortunately, act runner does not work this way until v0.2.11.
+Unfortunately, the runner does not work this way until v0.2.11.
 As mentioned, we map labels to environments:
 
 - `ubuntu` → `ubuntu:22.04`
@@ -117,9 +117,9 @@ 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/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
+See [runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
 
-Currently, the act runner attempts to match everyone in the labels and uses the first match it finds.
+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?
 
@@ -132,17 +132,17 @@ 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/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71).
+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?
 
-Although we would like to provide more options, our limited manpower means that act runner will be the only officially supported runner at the moment.
+Although we would like to provide more options, our limited manpower means that Gitea Runner will be the only officially supported runner at the moment.
 
-However, both Gitea and act runner are completely open source under MIT License, so anyone can modify the code to satisfy their requirements.
+However, both Gitea and Gitea Runner are completely open source under MIT License, so anyone can modify the code to satisfy their requirements.
 
-In case you fork act runner to create your own version: Please contribute the changes back if you can and if you think your changes will help others as well.
+In case you fork Gitea Runner to create your own version: Please contribute the changes back if you can and if you think your changes will help others as well.
 
 ## What workflow trigger events does Gitea support?
 
@@ -158,7 +158,7 @@ For events supported only by GitHub, see GitHub's [documentation](https://docs.g
 | push                        | not applicable                                                                                                           |
 | issues                      | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
 | issue_comment               | `created`, `edited`, `deleted`                                                                                           |
-| pull_request                | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled`                |
+| pull_request                | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronized`, `labeled`, `unlabeled`                |
 | pull_request_review         | `submitted`, `edited`                                                                                                    |
 | pull_request_review_comment | `created`, `edited`                                                                                                      |
 | release                     | `published`, `edited`                                                                                                    |
@@ -168,3 +168,8 @@ For events supported only by GitHub, see GitHub's [documentation](https://docs.g
 
 > For `pull_request` events, in [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request), the `ref` is `refs/pull/:prNumber/merge`, which is a reference to the merge commit preview. However, Gitea has no such reference.
 > Therefore, the `ref` in Gitea Actions is `refs/pull/:prNumber/head`, which points to the head of pull request rather than the preview of the merge commit.
+
+## How to share actions and reusable workflows from private repositories?
+
+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.

docs/usage/actions/overview.md

@@ -21,8 +21,8 @@ To avoid confusion, we have clarified the spelling here:
 ## Runners
 
 Just like other CI/CD solutions, Gitea doesn't run the jobs itself, but delegates the jobs to runners.
-The runner of Gitea Actions is called [act runner](https://gitea.com/gitea/act_runner), it is a standalone program and also written in Go.
-An important part of the application comes from a [fork](https://gitea.com/gitea/act) of [nektos/act](http://github.com/nektos/act).
+The runner of Gitea Actions is called [Gitea Runner](https://gitea.com/gitea/runner), it is a standalone program and also written in Go.
+An important part of the application comes from a hard fork of [nektos/act](http://github.com/nektos/act).
 
 Because the runner is deployed independently, there could be potential security issues.
 To avoid them, please follow two simple rules:

docs/usage/actions/quickstart.md

@@ -25,10 +25,10 @@ If you want to learn more or encounter any problems while configuring it, please
 
 ### Set up runner
 
-Gitea Actions requires [act runner](https://gitea.com/gitea/act_runner) to run the jobs.
+Gitea Actions requires [Gitea Runner](https://gitea.com/gitea/runner) to run the jobs.
 In order to avoid consuming too many resources and affecting the Gitea instance, it is recommended to start runners on separate machines from the Gitea instance.
 
-You can use the [pre-built binaries](http://dl.gitea.com/act_runner) or the [docker images](https://hub.docker.com/r/gitea/act_runner/tags) to set up the runner.
+You can use the [pre-built binaries](http://dl.gitea.com/gitea-runner) or the [docker images](https://hub.docker.com/r/gitea/runner/tags) to set up the runner.
 
 Before proceeding any further, we suggest running it as a command line with pre-built binaries to ensure that it works with your environment, especially if you are running a runner on your localhost.
 And it could be easier to debug if something goes wrong.
@@ -40,7 +40,7 @@ However, it is recommended to use Docker to run the jobs, because it is more sec
 Before running a runner, you should first register it to your Gitea instance using the following command:
 
 ```bash
-./act_runner register --no-interactive --instance <instance> --token <token>
+./runner register --no-interactive --instance <instance> --token <token>
 ```
 
 There are two arguments required, `instance` and `token`.
@@ -69,14 +69,14 @@ If this file is missing or corrupted, you can simply remove it and register agai
 Finally, it's time to start the runner:
 
 ```bash
-./act_runner daemon
+./runner daemon
 ```
 
 And you can see the new runner in the management page:
 
 ![view runner](/images/usage/actions/view-runner.png)
 
-You can find more information by visiting [Act runner](usage/actions/act-runner.md).
+You can find more information by visiting [Gitea Runner](runner.mdx).
 
 ### Use Actions
 

docs/usage/actions/runner.mdx

@@ -0,0 +1,459 @@
+---
+date: "2023-04-27T15:00:00+08:00"
+slug: "runner"
+sidebar_position: 20
+---
+
+# Gitea Runner
+
+This page will introduce the [Gitea Runner](https://gitea.com/gitea/runner) in detail, which is the runner for Gitea Actions.
+
+## Requirements
+
+Currently the runner supports three modes in which it can be run.
+1. Host: runner will run as an application on the host. This provides no encapsulation.
+2. Docker (recommended): Runs jobs in a [Docker](https://docker.com) container. If you choose this mode, you need to [install Docker](https://docs.docker.com/engine/install/) first and make sure that the Docker daemon is running.
+3. Docker-in-Docker (DinD): Puts the runner into rootless mode. It then runs in a Docker container with its own Docker daemon that has fewer privileges. It will spawn job containers from there. Best security but more complex setup.
+
+Other OCI container engines which are compatible with Docker's API should also work, but are untested.
+
+However, if you are sure that you want to run jobs directly on the host only, then Docker is not required.
+
+There are multiple ways to install the runner.
+
+## Installation with binary
+
+### Download the binary
+
+You can download the binary from the [release page](https://gitea.com/gitea/runner/releases).
+However, if you want to use the latest nightly build, you can download it from the [download page](https://dl.gitea.com/gitea-runner/).
+
+When you download the binary, please make sure that you have downloaded the correct one for your platform.
+You can check it by running the following command if you are in a Unix-style OS.
+
+```bash
+chmod +x runner
+./runner --version
+```
+
+If you see the version information, it means that you have downloaded the correct binary.
+
+### Obtain a registration token
+
+You can register a runner at different levels. It can be:
+
+- Instance level: The runner will run jobs for all repositories in the instance.
+- Organization level: The runner will run jobs for all repositories in the organization.
+- Repository level: The runner will run jobs for the repository it belongs to.
+
+Note that the repository may still use instance-level or organization-level runners even if it has its own repository-level runners. A future release may provide an option to allow more control over this.
+
+
+Before registering the runner and running it, you need a registration token. The level of the runner determines where to obtain the registration token.
+
+- Instance level: The admin settings page, like `<your_gitea.com>/-/admin/actions/runners`.
+- Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`.
+- Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`.
+
+If you cannot see the settings page, please make sure that you have the right permissions and that Actions have been enabled.
+
+The format of the registration token is a random string `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`.
+
+A registration token can also be obtained from the Gitea [command-line interface](../../administration/command-line.md#actions-generate-runner-token):
+
+```
+gitea --config /etc/gitea/app.ini actions generate-runner-token
+```
+
+You can also use `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variables to set a global runner registration token when Gitea starts, for example:
+
+```
+openssl rand -hex 24 > /some-dir/runner-token
+export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
+./gitea --config ...
+```
+
+The token from the environment is valid until you reset the token (re-create a new one) via the web UI or API.
+
+Tokens are valid for registering multiple runners, until they are revoked and replaced by a new token using the token reset link in the web interface.
+
+### Configuration
+
+Configuration is done via a configuration file. It is optional, and the default configuration will be used when no configuration file is specified. You can generate a configuration file by running the following command:
+
+```bash
+./runner generate-config
+```
+
+The default configuration is safe to use without any modification, so you can just use it directly.
+
+```bash
+./runner generate-config > config.yaml
+./runner --config config.yaml [command]
+```
+
+### Register the runner
+
+Registration is required before running Gitea Runner, because the runner needs to know where to get jobs from. It is also important for the Gitea instance to identify the runner.
+
+If this has been installed using the binary package, the runner can be registered by running the following command.
+
+```bash
+./runner register
+```
+
+Alternatively, you can use the `--config` option to specify the configuration file mentioned in the previous section.
+
+```bash
+./runner --config config.yaml register
+```
+
+You will be asked to input the registration information step by step. This includes:
+
+- The Gitea instance URL, like `https://gitea.com/` or `http://192.168.8.8:3000/`.
+- The registration token.
+- The runner name, which is optional. If you leave it blank, the hostname will be used.
+- The runner labels, which is optional. If you leave it blank, the default labels will be used.
+
+You may be confused about the runner labels, which will be explained later.
+
+If you want to register the runner in a non-interactive way, you can use arguments to do it.
+
+```bash
+./runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
+```
+
+When you have registered the runner, you can find a new file named `.runner` in the current directory.
+This file stores the registration information.
+Please do not edit it manually.
+If this file is missing or corrupted, you can simply remove it and register again.
+
+If you want to store the registration information in another place, you can specify it in the configuration file,
+and don't forget to specify the `--config` option.
+
+#### Ephemeral Runners
+
+Ephemeral runners provide a security hardening mechanism for enabling organization- or instance-wide runners without requiring full user trust. Once a job is assigned within a spot VM or container, the runner's exposed credentials are automatically revoked—blocking it from polling further jobs before any untrusted code runs, while still allowing it to report progress until completion by either Gitea or the runner.
+
+Gitea Runner **0.2.12+** is required.
+
+The updated commands for registering the runner as ephemeral are listed below. Refer to the previous section for detailed information on registering the runner.
+
+```bash
+./runner register --ephemeral
+```
+
+```bash
+./runner --config config.yaml register --ephemeral
+```
+
+```bash
+./runner register --no-interactive --ephemeral --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
+```
+
+The runner must be registered each time it is intended to receive a job. After completing the single job it is designed to execute, the runner terminates.
+
+To automate the registration and startup of new runners when a job is queued, use the `workflow_job` webhook.
+
+### Start the runner from the command line
+
+After you have registered the runner, you can run it with the following command:
+
+```shell
+./runner daemon
+```
+
+or
+
+```bash
+./runner daemon --config config.yaml
+```
+
+The runner will fetch jobs from the Gitea instance and run them automatically.
+
+### Start the runner with Systemd
+
+It is also possible to run Gitea Runner as a [systemd](https://en.wikipedia.org/wiki/Systemd) service. Create an unprivileged `runner` user on your system, and create the following file in `/etc/systemd/system/runner.service`. The paths in `ExecStart` and `WorkingDirectory` may need to be adjusted depending on where you installed the `runner` binary, its configuration file, and the home directory of the `runner` user.
+
+```ini
+[Unit]
+Description=Gitea Actions runner
+Documentation=https://gitea.com/gitea/runner
+After=docker.service
+
+[Service]
+ExecStart=/usr/local/bin/runner daemon --config /etc/runner/config.yaml
+ExecReload=/bin/kill -s HUP $MAINPID
+WorkingDirectory=/var/lib/runner
+TimeoutSec=0
+RestartSec=10
+Restart=always
+User=runner
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then:
+
+```bash
+# load the new systemd unit file
+sudo systemctl daemon-reload
+# start the service and enable it at boot
+sudo systemctl enable runner --now
+```
+
+If using Docker, the `runner` user should also be added to the `docker` group before starting the service. Keep in mind that this effectively gives `runner` root access to the system [[1]](https://docs.docker.com/engine/security/#docker-daemon-attack-surface).
+
+### Start the runner with LaunchDaemon (macOS)
+
+Mac uses `launchd` in place of systemd for registering daemon processes. By default, daemons run as the root user, so if desired an unprivileged `_runner` user can be created via the `dscl` tool. The following file should then be created in the directory `/Library/LaunchDaemon/com.gitea.runner.plist`. The paths for `WorkingDirectory`, `ProgramArguments`, `StandardOutPath`, `StandardErrPath`, and the `HOME` environment variable may need to be updated to reflect your installation. Also note that any executables outside of the example `PATH` shown will need to be explicitly included and will not be inherited from existing configurations.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.gitea.runner</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/local/bin/runner</string>
+        <string>daemon</string>
+        <string>--config</string>
+        <string>/etc/runner/config.yaml</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>WorkingDirectory</key>
+    <string>/var/lib/runner</string>
+    <key>StandardOutPath</key>
+    <string>/var/lib/runner/runner.log</string>
+    <key>StandardErrorPath</key>
+    <string>/var/lib/runner/runner.err</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <key>HOME</key>
+        <string>/var/lib/runner</string>
+    </dict>
+    <key>UserName</key>
+    <string>_runner</string>
+</dict>
+</plist>
+```
+
+Then:
+
+```bash
+sudo launchctl load /Library/LaunchDaemon/com.gitea.runner.plist
+```
+
+You can also set up a Linux or Windows service to let the runner run automatically.
+
+## Install with the docker image
+
+### Pull the image
+
+You can use the docker image from [Docker Hub](https://hub.docker.com/r/gitea/runner/tags).
+Just like the binary, you can use the latest nightly build by using the `nightly` tag, while the `latest` tag is the latest stable release.
+
+```bash
+docker pull docker.io/gitea/runner:latest # for the latest stable release
+```
+
+If you want to use the newest or experimental features, you can also use the nightly image.
+```bash
+docker pull docker.io/gitea/runner:nightly # for the latest nightly build
+```
+
+### Configuration
+
+Configuration is optional, but you can also generate a config file with docker:
+
+```bash
+docker run --entrypoint="" --rm -it docker.io/gitea/runner:latest runner generate-config > config.yaml
+```
+
+When you are using the docker image, you can specify the configuration file by using the `CONFIG_FILE` environment variable. Make sure that the file is mounted into the container as a volume:
+
+```bash
+docker run -v $PWD/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
+```
+
+You may notice the commands above are incomplete because it is not time to run the runner yet.
+Before running the runner, we need to register it to your Gitea instance first.
+
+### Start the runner with docker
+
+If you are using the docker image, behavior will be slightly different. Registration and running are combined into one step in this case, so you need to specify the registration information when running the runner.
+
+A quick start with docker run along with a minimal parameter set is shown below. You need to get the `<registration_token>` from the above step, and set a unique name for `<gitea_runner_name>` and for `<container_name>`.
+
+```bash
+docker run \
+    -e GITEA_INSTANCE_URL=<instance_url> \
+    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
+    -e GITEA_RUNNER_NAME=<gitea_runner_name> \
+    --name <container_name> \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -d docker.io/gitea/runner:latest
+```
+
+You can add more parameters to use a custom config, add a `data` directory for non-volatile file storage, etc.
+
+```bash
+docker run \
+    -v $PWD/config.yaml:/config.yaml \
+    -v $PWD/data:/data \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -e CONFIG_FILE=/config.yaml \
+    -e GITEA_INSTANCE_URL=<instance_url> \
+    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
+    -e GITEA_RUNNER_NAME=<gitea_runner_name> \
+    -e GITEA_RUNNER_LABELS=<runner_labels> \
+    --name <container_name> \
+    -d docker.io/gitea/runner:latest
+```
+
+You may notice that we have mounted `/var/run/docker.sock` into the container.
+This is because with this setup, the runner will execute jobs in temporary Docker containers, so it needs to communicate with the Docker daemon.
+As mentioned, you can remove it if you want to run jobs on the host directly.
+To be clear, the "host" actually means the container that is running the runner now, instead of the host machine.
+
+---
+
+To enable ephemeral runners, set the environment variable `GITEA_RUNNER_EPHEMERAL=1` in the runner image. This setup doesn't use a `/data` volume because the credentials are single-use and not intended to be reused. You can find more details about this mode under [Ephemeral runners](#ephemeral-runners).
+
+```bash
+docker run \
+    -e GITEA_INSTANCE_URL=<instance_url> \
+    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
+    -e GITEA_RUNNER_EPHEMERAL=1 \
+    -e GITEA_RUNNER_NAME=<runner_name> \
+    --name my_runner \
+    -d docker.io/gitea/runner:nightly
+```
+
+```bash
+docker run \
+    -v $PWD/config.yaml:/config.yaml \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -e CONFIG_FILE=/config.yaml \
+    -e GITEA_INSTANCE_URL=<instance_url> \
+    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
+    -e GITEA_RUNNER_EPHEMERAL=1 \
+    -e GITEA_RUNNER_NAME=<runner_name> \
+    -e GITEA_RUNNER_LABELS=<runner_labels> \
+    --name my_runner \
+    -d docker.io/gitea/runner:nightly
+```
+
+Mounting the host's Docker socket using `/var/run/docker.sock:/var/run/docker.sock` introduces a potential security vulnerability. If a job can access this socket, the reusable `GITEA_RUNNER_REGISTRATION_TOKEN` could be exposed through Docker inspect data.
+
+### Start the runner using docker compose
+
+You could also set up the runner using the following `docker-compose.yml`:
+
+```yml
+version: "3.8"
+services:
+  runner:
+    image: docker.io/gitea/runner:nightly
+    environment:
+      CONFIG_FILE: /config.yaml
+      GITEA_INSTANCE_URL: "${INSTANCE_URL}"
+      GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
+      GITEA_RUNNER_NAME: "${RUNNER_NAME}"
+      GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
+    volumes:
+      - ./config.yaml:/config.yaml
+      - ./data:/data
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+When using docker, there is no requirement to enter the container and manually run `./runner daemon` command as shown below. Once the container has been started successfully, it will show up as an active runner in your Gitea instance.
+
+---
+
+To enable ephemeral runners, set the environment variable `GITEA_RUNNER_EPHEMERAL=1` in the runner image. This setup doesn't use a `/data` volume because the credentials are single-use and not intended to be reused. You can find more details about this mode under [Ephemeral runners](#ephemeral-runners).
+
+```yml
+version: "3.8"
+services:
+  runner:
+    image: docker.io/gitea/runner:nightly
+    environment:
+      CONFIG_FILE: /config.yaml
+      GITEA_INSTANCE_URL: "${INSTANCE_URL}"
+      GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
+      GITEA_RUNNER_NAME: "${RUNNER_NAME}"
+      GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
+      GITEA_RUNNER_EPHEMERAL: "1"
+    volumes:
+      - ./config.yaml:/config.yaml
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+Mounting the host's Docker socket using `/var/run/docker.sock:/var/run/docker.sock` introduces a potential security vulnerability. If a job can access this socket, the reusable `GITEA_RUNNER_REGISTRATION_TOKEN` could be exposed through Docker inspect data.
+
+### More start examples
+A couple more usage examples can be found in the [runner](https://gitea.com/gitea/runner/src/branch/main/examples) repository.
+
+## Advanced Configurations
+
+### Configuring cache when starting a runner using the docker image
+
+If you do not intend to use `actions/cache` in your workflow, you can ignore this section.
+
+If you use `actions/cache` without any additional configuration, it will return the following error:
+> Failed to restore: getCacheEntry failed: connect ETIMEDOUT IP:PORT
+
+The error occurs because the runner container and job container are on different networks, so the job container cannot access the runner container.
+
+Therefore, it is essential to configure the cache action to ensure its proper functioning. Follow these steps:
+
+- 1. Obtain the LAN IP address of the host machine where the runner container is running.
+- 2. Find an available port number on the host machine where the runner container is running.
+- 3. Configure the following settings in the configuration file:
+
+```yaml
+cache:
+  enabled: true
+  dir: ""
+  # Use the LAN IP obtained in step 1
+  host: "192.168.8.17"
+  # Use the port number obtained in step 2
+  port: 8088
+```
+
+- 4. When starting the container, map the cache port to the host machine:
+
+```bash
+docker run \
+  --name gitea-docker-runner \
+  -p 8088:8088 \
+  -d docker.io/gitea/runner:nightly
+```
+
+### Labels
+
+The labels of a runner are used to determine which jobs the runner can run, and how to run them.
+
+The default labels are `ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`.
+It is a comma-separated list, and each item is a label.
+
+Let's take `ubuntu-22.04:docker://node:16-bullseye` as an example.
+It means that the runner can run jobs with `runs-on: ubuntu-22.04`, and the job will be run in a docker container with the image `node:16-bullseye`.
+
+If the default image is insufficient for your needs, and you have enough disk space to use a better and bigger one, you can change it to `ubuntu-22.04:docker://<the image you like>`.
+You can find more useful images on [act images](https://github.com/nektos/act/blob/master/IMAGES.md).
+
+If you want to run jobs on the host directly, you can change it to `ubuntu-22.04:host` or just `ubuntu-22.04`; `:host` is optional.
+However, we suggest you use a special name like `linux_amd64:host` or `windows:host` to avoid misusing it.
+
+Starting with Gitea 1.21, you can change labels by modifying `runners.labels` in the runner configuration file (if you don't have a configuration file, please refer to [configuration tutorials](#configuration)).
+The runner will use these new labels as soon as you restart it, i.e., by calling `./runner daemon --config config.yaml`.

docs/usage/actions/scoped-workflows.md

@@ -0,0 +1,119 @@
+---
+date: "2026-06-26T00:00:00+00:00"
+slug: "scoped-workflows"
+sidebar_position: 60
+---
+
+# Scoped Workflows
+
+Scoped workflows let you maintain Actions workflows in one central **source** repository and have them run automatically on many other repositories, without copying the workflow files into each one.
+
+A workflow file committed under a source repository's scoped-workflow directory runs on every repository that the source applies to (a "consuming" repository). Each run executes **in the consuming repository's own context**: its runners, secrets, `GITEA_TOKEN`, and branch, while the workflow **content is read from the source repository**. This is useful for mandating shared CI across an organization or instance: linting, security scans, compliance or policy checks, and similar.
+
+## Levels
+
+A source repository can be registered at two levels:
+
+- **Owner level**: registered by an organization or user. The source's workflows run on every repository owned by that organization or user.
+- **Instance level**: registered by a site administrator. The source's workflows run on **every** repository on the instance.
+
+The same repository may be registered at both levels; it is still evaluated once per matching event.
+
+:::note
+Instance-level sources apply to **every** repository on the instance, and a required one cannot be opted out. Detection runs on every repository's events. Register them deliberately.
+:::
+
+## Configuration
+
+Scoped workflows live in a directory that is separate from regular workflows. It is controlled by `SCOPED_WORKFLOW_DIRS` in the `[actions]` section of `app.ini`:
+
+```ini
+[actions]
+SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
+```
+
+- The default is `.gitea/scoped_workflows`.
+- It may list multiple directories (comma-separated).
+- It **must not overlap** with `WORKFLOW_DIRS` (the regular workflow directories, by default `.gitea/workflows` and `.github/workflows`).
+- Leaving it empty means no directory holds scoped workflows, so none are found or run. The settings page still appears and sources can still be registered, but no scoped workflow runs.
+
+Keeping scoped workflows in their own directory means a source repository's *own* Actions are unaffected: only files under `SCOPED_WORKFLOW_DIRS` are treated as scoped workflows.
+
+## Providing scoped workflows from a repository
+
+1. In the would-be source repository, commit your workflow files under the scoped-workflow directory on its **default branch**, for example `.gitea/scoped_workflows/lint.yaml`:
+
+   ```yaml
+   name: Lint
+   on: [push, pull_request]
+   jobs:
+     lint:
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v4
+         - run: echo "lint the consuming repository here"
+   ```
+
+2. Register the repository as a source:
+
+   - **Organization**: *Organization Settings -> Actions -> Scoped Workflows*
+   - **User**: *User Settings -> Actions -> Scoped Workflows*
+   - **Instance (admin)**: *Site Administration -> Actions -> Scoped Workflows*
+
+   Search for and add the repository. From then on, its scoped workflows apply to the consuming repositories at that level.
+
+The source repository is within its own scope, so it runs these workflows on itself like any other consumer.
+
+## How scoped workflows run
+
+- The run belongs to the **consuming** repository and uses its runners, secrets, `GITEA_TOKEN`, and ref. It behaves like a normal run there, including rerun, logs, and commit statuses.
+- The workflow **content is read from the source** repository, pinned to the source's default-branch commit at the time of the event.
+- Detection uses the consuming repository's event, so the workflow's `on:` triggers (such as `push` and `pull_request`) must match that event.
+
+## Opting out
+
+A consuming repository can disable a scoped workflow it does not want, from its **Actions** page (the workflow appears under its source). A workflow that has been marked **required** (see below) can never be disabled or opted out by a consuming repository.
+
+## Required workflows and the merge gate
+
+On the Scoped Workflows settings page you can mark individual workflows as **required** and give each one or more **status-check patterns** (one glob per line). A required scoped workflow:
+
+- Cannot be disabled by consuming repositories.
+- Gates pull-request merges: a consuming pull request can only be merged once a commit status matching **every** pattern has **passed** (must-present-and-pass). A required check that never posts a status **blocks** the merge rather than being silently skipped, so disabling Actions on the consumer cannot bypass it.
+
+The status-check context a scoped run posts has the form:
+
+```
+<source repo full name>: <workflow display name> / <job> (<event>)
+```
+
+The settings page previews these "Expected status checks" for each workflow and marks the ones your patterns match, so you can confirm a pattern is correct. A common pattern wildcards the job and event, for example `my-org/ci-repo: Lint / *`.
+
+Enforcement scope:
+
+- A required check is enforced on any target branch that has a **branch protection rule**, even one whose own status checks are disabled.
+- A target branch with **no** protection rule is not gated.
+
+:::warning
+Only a workflow that runs on an event that posts a commit status (`push`, `pull_request`, `pull_request_target`, `release`) can be required. A workflow that runs only on events like `workflow_dispatch`, `schedule` or `workflow_call` posts no status, so marking it required would block every consuming pull request forever. The settings page warns you in this case.
+:::
+
+## Reusable workflows (`uses:`)
+
+Scoped workflows can call reusable workflows:
+
+- A **local** reference (`uses: ./...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
+- A **cross-repository** reference (`uses: owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
+
+A reusable workflow can live under `SCOPED_WORKFLOW_DIRS` (or `WORKFLOW_DIRS`) of the source repository.
+
+## Security considerations
+
+A source repository's workflow content is executed in every repository it applies to, and its step scripts and their output are written to that repository's Actions logs, readable by anyone who can view the consuming repository's Actions.
+
+- Registering a **private** repository as a source therefore discloses its workflow logic through those logs. Only register repositories whose workflow content may be shared with every consuming repository.
+
+## Limitations
+
+- `on: schedule` and `on: workflow_run` are currently not supported as scoped workflow triggers.
+- Scoped workflow content is read from the source's default branch; other branches of the source are not used.

docs/usage/actions/token-permissions.md

@@ -0,0 +1,115 @@
+---
+date: "2026-03-19T00:00:00+01:00"
+slug: "token-permissions"
+sidebar_position: 30
+---
+
+# Actions job token permissions (`GITEA_TOKEN`)
+
+Every Actions job receives a built-in token (`GITEA_TOKEN`) which can be used to access Gitea (Git over HTTP(S), API requests, etc.).
+This page documents how Gitea decides what the token is allowed to do.
+
+In workflows, it is available as `${{ secrets.GITEA_TOKEN }}`. These settings and `permissions:` only affect `GITEA_TOKEN` (not other secrets like personal access tokens). For API calls, see [API authentication](../../development/api-usage.md#authentication).
+
+## Where permissions come from
+
+Gitea determines the job token permissions in this order:
+
+1. Job-level `permissions:` (`jobs.<job_id>.permissions`)
+2. Workflow-level `permissions:` (top-level)
+3. Default permissions from settings (owner or repository)
+
+The result is then **clamped** by the configured maximum token permissions (see below).
+
+## Supported workflow syntax
+
+Gitea supports the GitHub Actions-compatible `permissions:` keyword.
+
+### Scalar values
+
+```yaml
+permissions: read-all   # or: write-all
+```
+
+### Scoped mapping
+
+```yaml
+permissions:
+  contents: read
+  issues: write
+  pull-requests: none
+```
+
+Valid access mode values for each scope are `read`, `write`, and `none`.
+
+### Supported scopes
+
+- `contents` (applies to `code` and `releases`)
+- `code`
+- `releases`
+- `issues`
+- `pull-requests`
+- `actions`
+- `wiki`
+- `projects`
+- `packages` (if supported by the target feature)
+
+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.
+
+Gitea also exposes repository-unit scopes that do not exist as separate scopes in GitHub Actions:
+
+- `code`
+- `releases`
+- `wiki`
+- `projects`
+
+## Default permission mode
+
+If neither the workflow nor the job defines `permissions:`, Gitea uses the configured default mode:
+
+- **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.
+
+## Maximum token permissions (clamping)
+
+You can configure a maximum permission per repository unit.
+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.
+
+## Where to configure
+
+You can configure defaults and maximums at:
+
+- **User / Organization**: `Settings` → `Actions` → `General`
+- **Repository**: `Settings` → `Actions` → `General`
+  - For repositories in an organization, the repository can follow the owner-level configuration, or opt out with **Override owner-level configuration**.
+
+Note: Repository-level token permission settings are only shown once **Repository Actions** are enabled.
+
+## 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.
+
+## Cross-repository access
+
+By default, `GITEA_TOKEN` only has access to:
+
+- The job's repository (according to the computed permissions)
+- Public repositories (read-only)
+
+Access to other private repositories is denied by default.
+A user or organization can allow read-only access to selected private repositories via **Settings → Actions → General → Cross-Repository Access**.
+
+Private repositories can also allow selected collaborative owners via **Settings → Actions → General**.
+This allows the private repositories of those owners to read the current private repository for Actions use, such as private actions and reusable workflows.
+
+Fork pull request workflows never gain cross-repository access to private repositories, even if those repositories are listed.

docs/usage/actions/variables.md

@@ -6,11 +6,13 @@ sidebar_position: 25
 
 # Variables
 
+## User-defined variables
+
 You can create configuration variables on the user, organization and repository level.
 The level of the variable depends on where you created it. When creating a variable, the
 key will be converted to uppercase. You need use uppercase on the yaml file.
 
-## Naming conventions
+### Naming conventions
 
 The following rules apply to variable names:
 
@@ -21,12 +23,118 @@ The following rules apply to variable names:
 - Variable names must be unique at the level they are created at.
 - Variable names must not start with `CI`.
 
-## Using variable
+### Using variables
 
 After creating configuration variables, they will be automatically filled in the `vars` context.
 They can be accessed through expressions like `${{ vars.VARIABLE_NAME }}` in the workflow.
 
-## Precedence
+### Precedence
 
 If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence:
 A repository variable will always be chosen over an organization/user variable.
+
+## Pre-defined context variables
+
+These variables are available in workflow expressions via `${{ gitea.<name> }}`. For compatibility, `${{ github.<name> }}` works as an alias.
+
+| Name | Description | Example |
+|---|---|---|
+| `gitea.action`<br/>`github.action` | The name of the action currently running, or the `id` of a step. | `__run` |
+| `gitea.action_path`<br/>`github.action_path` | The path where an action is located. Only supported in composite actions. | `/home/runner/work/_actions/actions/checkout/v4` |
+| `gitea.action_ref`<br/>`github.action_ref` | The ref of the action being executed. | `v4` |
+| `gitea.action_repository`<br/>`github.action_repository` | The owner and repository name of the action. | `actions/checkout` |
+| `gitea.action_status`<br/>`github.action_status` | The current result of a composite action. | `success` |
+| `gitea.actor`<br/>`github.actor` | The username of the user that triggered the initial workflow run. | `silverwind` |
+| `gitea.api_url`<br/>`github.api_url` | The URL of the REST API. | `https://gitea.com/api/v1` |
+| `gitea.base_ref`<br/>`github.base_ref` | The target branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `main` |
+| `gitea.env`<br/>`github.env` | Path on the runner to the file that sets environment variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
+| `gitea.event`<br/>`github.event` | The full event webhook payload as an object. | `{...}` |
+| `gitea.event_name`<br/>`github.event_name` | The name of the event that triggered the workflow run. | `push` |
+| `gitea.event_path`<br/>`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
+| `gitea.head_ref`<br/>`github.head_ref` | The source branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `feature-branch` |
+| `gitea.job`<br/>`github.job` | The `job_id` of the current job. | `build` |
+| `gitea.ref`<br/>`github.ref` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
+| `gitea.ref_name`<br/>`github.ref_name` | The short ref name. | `main` |
+| `gitea.ref_protected`<br/>`github.ref_protected` | `true` if branch protections are configured for the ref that triggered the workflow run. | `true` |
+| `gitea.ref_type`<br/>`github.ref_type` | The type of ref: `branch` or `tag`. | `branch` |
+| `gitea.path`<br/>`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
+| `gitea.repository`<br/>`github.repository` | The owner and repository name. | `gitea/docs` |
+| `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `gitea` |
+| `gitea.repositoryUrl`<br/>`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.com/gitea/docs` |
+| `gitea.retention_days`<br/>`github.retention_days` | The number of days that workflow run logs and artifacts are kept. | `90` |
+| `gitea.run_id`<br/>`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` |
+| `gitea.run_number`<br/>`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` |
+| `gitea.run_attempt`<br/>`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` |
+| `gitea.secret_source`<br/>`github.secret_source` | The source of a secret used in a workflow. Always `Actions` in Gitea. | `Actions` |
+| `gitea.server_url`<br/>`github.server_url` | The URL of the Gitea instance. | `https://gitea.com` |
+| `gitea.sha`<br/>`github.sha` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `gitea.token`<br/>`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `ghs_***` |
+| `gitea.triggering_actor`<br/>`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `silverwind` |
+| `gitea.workflow`<br/>`github.workflow` | The name of the workflow. If unnamed, the full path of the workflow file. | `CI` |
+| `gitea.workspace`<br/>`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/gitea/docs` |
+| `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` |
+
+## Pre-defined environment variables
+
+These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts).
+
+### Standard environment variables
+
+| Name | Description | Example |
+|---|---|---|
+| `CI` | Always set to `true`. | `true` |
+| `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` |
+| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `1.0.8` |
+| `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
+| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` |
+| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
+| `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/home/runner/work/_temp/_runner_file_commands/save_state_***` |
+| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/home/runner/work/_temp/_runner_file_commands/step_summary_***` |
+| `GITHUB_ACTIONS` | Always set to `true`. | `true` |
+| `GITHUB_ACTION` | The name of the action currently running, or the step `id`. | `__run` |
+| `GITHUB_ACTION_PATH` | The path where the action is located. | `/home/runner/work/_actions/actions/checkout/v4` |
+| `GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` |
+| `GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` |
+| `GITHUB_ACTOR` | The username of the user that triggered the workflow. | `silverwind` |
+| `GITHUB_API_URL` | The URL of the REST API. | `https://gitea.com/api/v1` |
+| `GITHUB_BASE_REF` | The target branch of a pull request. | `main` |
+| `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` |
+| `GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
+| `GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ |
+| `GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` |
+| `GITHUB_JOB` | The `job_id` of the current job. | `build` |
+| `GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
+| `GITHUB_REF_NAME` | The short ref name. | `main` |
+| `GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
+| `GITHUB_REPOSITORY` | The owner and repository name. | `gitea/docs` |
+| `GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `gitea` |
+| `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. | `90` |
+| `GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
+| `GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` |
+| `GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` |
+| `GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.com` |
+| `GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `GITHUB_WORKFLOW` | The name of the workflow. | `CI` |
+| `GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/gitea/docs` |
+
+### Runner environment variables
+
+| Name | Description | Example |
+|---|---|---|
+| `RUNNER_ARCH` | The architecture of the runner. | `X64` |
+| `RUNNER_OS` | The operating system of the runner. | `Linux` |
+| `RUNNER_TEMP` | Path to a temporary directory on the runner. | `/tmp` |
+| `RUNNER_TOOL_CACHE` | Path to the tool cache directory on the runner. | `/opt/hostedtoolcache` |
+
+### Internal environment variables
+
+These are used internally by the runner and actions. They are typically not needed in workflows directly.
+
+| Name | Description | Example |
+|---|---|---|
+| `ACTIONS_CACHE_URL` | URL for the actions cache service. | `http://192.168.1.10:8088/` |
+| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when configured. | `***` |
+| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when configured. | `https://gitea.com/login/oauth/access_token` |
+| `ACTIONS_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/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Issues & Pull Requests",
+  "position": 20,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/issues-prs",
+    "description": "Issues and Pull Requests workflow, templates, and collaboration features"
+  }
+}

docs/usage/issues-prs/agit.md

@@ -4,9 +4,11 @@ slug: "agit"
 sidebar_position: 12
 aliases:
   - /en-us/agit-setup
+  - /agit-setup
+  - /agit
 ---
 
-# AGit Setup
+# AGit
 
 In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
 
@@ -27,19 +29,21 @@ git push origin HEAD:refs/for/main
 The command has the following structure:
 
 - `HEAD`: The target branch
-- `refs/<for|draft|for-review>/<branch>`: The target PR type
+- `origin`: The target repository (not a fork!)
+- `HEAD`: The local branch containing the changes you are proposing
+- `refs/<for|draft|for-review>/<branch>`: The target PR type and configuration
   - `for`: Create a normal PR with `<branch>` as the target branch
-  - `draft`/ `for-review`: Currently ignored silently
-- `<branch>/<session>`: The target branch to open the PR
+  - `draft`/`for-review`: Currently ignored silently
+  - `<branch>/`: The branch you want your changes to be merged into
 - `-o <topic|title|description>`: Options for the PR
-  - `title`: The PR title
-  - `topic`: The branch name the PR should be opened for
-  - `description`: The PR description
+  - `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review.  This is REQUIRED to trigger a pull request.
+  - `title`: The PR title (optional but recommended), only used for topics not already having an associated PR.
+  - `description`: The PR description (optional but recommended), only used for topics not already having an associated PR.
   - `force-push=true`: Specifies whether to force-update the target branch.
-    - Note: omitting the value and using just `-o force-push` will not work.
+    - Note: omitting the value and using just `-o force-push` will also work.
 
 Here's another advanced example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
 
 ```shell
-git push origin HEAD:refs/for/main -o topic="Topic of my PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
+git push origin HEAD:refs/for/main -o topic="topic_of_my_PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
 ```

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

@@ -10,9 +10,10 @@ aliases:
 
 Some projects have a standard list of questions that users need to answer
 when creating an issue or pull request. Gitea supports adding templates to the
-main branch of the repository so that they can autopopulate the form when users are
+**default branch of the repository** so that they can autopopulate the form when users are
 creating issues and pull requests. This will cut down on the initial back and forth
 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.
 
@@ -98,6 +99,9 @@ name: "Template Name"
 about: "This template is for testing!"
 title: "[TEST] "
 ref: "main"
+assignees: ["user1"]
+projects:
+  - Example Project
 labels:
 
 - bug
@@ -110,7 +114,10 @@ This is the template!
 
 In the above example, when a user is presented with the list of issues they can submit, this would show as `Template Name` with the description
 `This template is for testing!`. When submitting an issue with the above example, the issue title would be pre-populated with
-`[TEST] ` while the issue body would be pre-populated with `This is the template!`. The issue would also be assigned two labels,
+`[TEST] ` while the issue body would be pre-populated with `This is the template!`.
+The issue would be assigned to `user1`.
+The issue would be assigned to the project `Example Project`.
+The issue would also be assigned two labels,
 `bug` and `help needed`, and the issue will have a reference to `main`.
 
 ## Syntax for yaml template
@@ -126,6 +133,12 @@ body:
     attributes:
       value: |
         Thanks for taking the time to fill out this bug report!
+  # some markdown that will only be visible once the issue has been created
+  - type: markdown
+    attributes:
+      value: |
+        This issue was created by an issue **template** :)
+    visible: [content]
   - type: input
     id: contact
     attributes:
@@ -173,15 +186,21 @@ body:
     id: terms
     attributes:
       label: Code of Conduct
+      hide_label: true
       description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
       options:
         - label: I agree to follow this project's Code of Conduct
           required: true
+        - label: I have also read the CONTRIBUTION.MD
+          required: true
+          visible: [form]
+        - label: This is a TODO only visible after issue creation
+          visible: [content]
 ```
 
 ### Markdown
 
-You can use a `markdown` element to display Markdown in your form that provides extra context to the user, but is not submitted.
+You can use a `markdown` element to display Markdown in your form that provides extra context to the user, but is not submitted by default.
 
 Attributes:
 
@@ -189,19 +208,22 @@ Attributes:
 |-------|--------------------------------------------------------------|----------|--------|---------|--------------|
 | value | The text that is rendered. Markdown formatting is supported. | Required | String | -       | -            |
 
+visible: Default is **[form]**
+
 ### Textarea
 
 You can use a `textarea` element to add a multi-line text field to your form. Contributors can also attach files in `textarea` fields.
 
 Attributes:
 
-| Key         | Description                                                                                                                                                                   | Required | Type   | Default      | Valid values              |
-|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------|--------------|---------------------------|
-| label       | A brief description of the expected user input, which is also displayed in the form.                                                                                          | Required | String | -            | -                         |
-| description | A description of the text area to provide context or guidance, which is displayed in the form.                                                                                | Optional | String | Empty String | -                         |
-| placeholder | A semi-opaque placeholder that renders in the text area when empty.                                                                                                           | Optional | String | Empty String | -                         |
-| value       | Text that is pre-filled in the text area.                                                                                                                                     | Optional | String | -            | -                         |
-| render      | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | Optional | String | -            | Languages known to Gitea. |
+| Key         | Description                                                                                                                                                                   | Required | Type    | Default      | Valid values              |
+|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|--------------|---------------------------|
+| label       | A brief description of the expected user input, which is also displayed in the form.                                                                                          | Required | String  | -            | -                         |
+| hide_label  | If true, the label normally used as a headline is not visible.                                                                                                                | Optional | Boolean | false        | -                         |
+| description | A description of the text area to provide context or guidance, which is displayed in the form.                                                                                | Optional | String  | Empty String | -                         |
+| placeholder | A semi-opaque placeholder that renders in the text area when empty.                                                                                                           | Optional | String  | Empty String | -                         |
+| value       | Text that is pre-filled in the text area.                                                                                                                                     | Optional | String  | -            | -                         |
+| render      | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | Optional | String  | -            | Languages known to Gitea. |
 
 Validations:
 
@@ -209,18 +231,21 @@ Validations:
 |----------|------------------------------------------------------|----------|---------|---------|--------------|
 | required | Prevents form submission until element is completed. | Optional | Boolean | false   | -            |
 
+visible: Default is **[form, content]**
+
 ### Input
 
 You can use an `input` element to add a single-line text field to your form.
 
 Attributes:
 
-| Key         | Description                                                                                | Required | Type   | Default      | Valid values |
-|-------------|--------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
-| label       | A brief description of the expected user input, which is also displayed in the form.       | Required | String | -            | -            |
-| description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | -            |
-| placeholder | A semi-transparent placeholder that renders in the field when empty.                       | Optional | String | Empty String | -            |
-| value       | Text that is pre-filled in the field.                                                      | Optional | String | -            | -            |
+| Key         | Description                                                                                | Required | Type    | Default      | Valid values |
+|-------------|--------------------------------------------------------------------------------------------|----------|---------|--------------|--------------|
+| label       | A brief description of the expected user input, which is also displayed in the form.       | Required | String  | -            | -            |
+| hide_label  | If true, the label normally used as a headline is not visible.                             | Optional | Boolean | false        | -            |
+| description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String  | Empty String | -            |
+| placeholder | A semi-transparent placeholder that renders in the field when empty.                       | Optional | String  | Empty String | -            |
+| value       | Text that is pre-filled in the field.                                                      | Optional | String  | -            | -            |
 
 Validations:
 
@@ -230,6 +255,8 @@ Validations:
 | is_number | Prevents form submission until element is filled with a number.                                  | Optional | Boolean | false   | -                                                                        |
 | regex     | Prevents form submission until element is filled with a value that match the regular expression. | Optional | String  | -       | a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) |
 
+visible: Default is **[form, content]**
+
 ### Dropdown
 
 You can use a `dropdown` element to add a dropdown menu in your form.
@@ -239,8 +266,10 @@ Attributes:
 | Key         | Description                                                                                         | Required | Type         | Default      | Valid values |
 |-------------|-----------------------------------------------------------------------------------------------------|----------|--------------|--------------|--------------|
 | label       | A brief description of the expected user input, which is displayed in the form.                     | Required | String       | -            | -            |
+| hide_label  | If true, the label normally used as a headline is not visible.                                      | Optional | Boolean | false        | -            |
 | description | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | Optional | String       | Empty String | -            |
 | multiple    | Determines if the user can select more than one option.                                             | Optional | Boolean      | false        | -            |
+| list        | If true, display as a list. If false, print items on one line with commas.                          | Optional | Boolean      | false        | -            |
 | options     | An array of options the user can choose from. Cannot be empty and all choices must be distinct.     | Required | String array | -            | -            |
 
 Validations:
@@ -249,24 +278,30 @@ Validations:
 |----------|------------------------------------------------------|----------|---------|---------|--------------|
 | required | Prevents form submission until element is completed. | Optional | Boolean | false   | -            |
 
+visible: Default is **[form, content]**
+
 ### Checkboxes
 
 You can use the `checkboxes` element to add a set of checkboxes to your form.
 
 Attributes:
 
-| Key         | Description                                                                                           | Required | Type   | Default      | Valid values |
-|-------------|-------------------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
-| label       | A brief description of the expected user input, which is displayed in the form.                       | Required | String | -            | -            |
-| description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String | Empty String | -            |
-| options     | An array of checkboxes that the user can select. For syntax, see below.                               | Required | Array  | -            | -            |
+| Key         | Description                                                                                           | Required | Type    | Default      | Valid values |
+|-------------|-------------------------------------------------------------------------------------------------------|----------|---------|--------------|--------------|
+| label       | A brief description of the expected user input, which is displayed in the form.                       | Required | String  | -            | -            |
+| hide_label  | If true, the label normally used as a headline is not visible.                                        | Optional | Boolean | false        | -            |
+| description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String  | Empty String | -            |
+| options     | An array of checkboxes that the user can select. For syntax, see below.                               | Required | Array   | -            | -            |
 
 For each value in the options array, you can set the following keys.
 
-| Key      | Description                                                                                                                              | Required | Type    | Default | Options |
-|----------|------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|---------|---------|
-| label    | The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks. | Required | String  | -       | -       |
-| required | Prevents form submission until element is completed.                                                                                     | Optional | Boolean | false   | -       |
+| Key          | Description                                                                                                                              | Required | Type         | Default | Options |
+|--------------|------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------|---------|---------|
+| label        | The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks. | Required | String       | -       | -       |
+| required     | Prevents form submission until element is completed.                                                                                     | Optional | Boolean      | false   | -       |
+| visible      | Whether a specific checkbox appears in the form only, in the created issue only, or both. Valid options are "form" and "content".        | Optional | String array | false   | -       |
+
+visible: Default is **[form, content]**
 
 ## Syntax for issue config
 
@@ -276,21 +311,21 @@ This is a example for a issue config file
 blank_issues_enabled: true
 contact_links:
   - name: Gitea
-    url: https://gitea.io
+    url: https://gitea.com
     about: Visit the Gitea Website
 ```
 
 ### Possible Options
 
-| Key                  | Description                                                                                           | Type               | Default        |
-|----------------------|-------------------------------------------------------------------------------------------------------|--------------------|----------------|
-| blank_issues_enabled | If set to false, the User is forced to use a Template                                                 | Boolean            | true           |
-| contact_links        | Custom Links to show in the Choose Box                                                                | Contact Link Array | Empty Array    |
+| Key                  | Description                                           | Type               | Default     |
+|----------------------|-------------------------------------------------------|--------------------|-------------|
+| blank_issues_enabled | If set to false, the User is forced to use a Template | Boolean            | true        |
+| contact_links        | Custom Links to show in the Choose Box                | Contact Link Array | Empty Array |
 
 ### Contact Link
 
-| Key                  | Description                                                                                           | Type    | Required |
-|----------------------|-------------------------------------------------------------------------------------------------------|---------|----------|
-| name  | the name of your link                                                                                                | String  | true     |
-| url   | The URL of your Link                                                                                                 | String  | true     |
-| about | A short description of your Link                                                                                     | String  | true     |
+| Key   | Description                      | Type   | Required |
+|-------|----------------------------------|--------|----------|
+| name  | the name of your link            | String | true     |
+| url   | The URL of your Link             | String | true     |
+| about | A short description of your Link | String | true     |

docs/usage/issues-prs/labels.md

@@ -18,7 +18,7 @@ For organizations, you can define organization-wide labels that are shared with
 
 Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
 
-When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
+When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
 
 ## Scoped Labels
 

docs/usage/issues-prs/linked-references.md

@@ -85,7 +85,7 @@ Sometimes a commit or pull request may fix or bring back a problem documented
 in a particular issue. Gitea supports closing and reopening the referenced
 issues by preceding the reference with a particular _keyword_. Common keywords
 include "closes", "fixes", "reopens", etc. This list can be
-[customized](../administration/config-cheat-sheet.md) by the
+[customized](../../administration/config-cheat-sheet.md) by the
 site administrator.
 
 Example:

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

@@ -1,12 +1,9 @@
 ---
 date: "2018-06-01T19:00:00+02:00"
-
 slug: "pull-request"
 sidebar_position: 13
-
 aliases:
   - /en-us/pull-request
-
 ---
 
 # Pull Request
@@ -58,6 +55,22 @@ WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP]
 
 The first value of the list will be used in helpers.
 
+## Default pull request title
+
+When opening a new pull request, Gitea pre-fills the title field. The source of that title is controlled by the `DEFAULT_TITLE_SOURCE` setting in `app.ini`:
+
+```ini
+[repository.pull-request]
+DEFAULT_TITLE_SOURCE = first-commit
+```
+
+Two modes are available:
+
+- **`first-commit`** (default): The title is taken from the summary line of the oldest commit in the branch. This applies regardless of how many commits are included in the PR.
+- **`auto`**: When the PR contains a single commit, its summary line is used as the title (same as `first-commit` for one commit). When the PR contains multiple commits, Gitea converts the branch name into a human-readable sentence: dashes, underscores, and `camelCase` word boundaries are replaced with spaces, and the first letter is capitalized.
+
+Example: branch name `fix-user-login-flow` with multiple commits produces the title `Fix user login flow` under `auto`, but would use the oldest commit's message under `first-commit`.
+
 ## Pull Request Templates
 
-You can find more information about pull request templates at the page [Issue and Pull Request templates](usage/issue-pull-request-templates.md).
+You can find more information about pull request templates at the page [Issue and Pull Request templates](issue-pull-request-templates.md).

docs/usage/packages/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Packages",
+  "position": 40,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/packages",
+    "description": "Managing packages and package registries"
+  }
+}

docs/usage/packages/arch.md

@@ -36,23 +36,24 @@ pacman-key --lsign-key {key id}
 
 Now add the registry configuration to `/etc/pacman.conf`.
 ```conf
-[{owner}.gitea.example.com]
+[{repository}]
 SigLevel = Required
-Server = https://gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
+Server = https://gitea.example.com/api/packages/{owner}/arch/$repo/$arch
 ```
 
 | Placeholder    | Description |
 | -------------- | ----------- |
 | `owner`        | The owner of the packages. |
 | `repository`   | The repository to use. |
-| `architecture` | The architecture to use. |
 
 Consult the owners package overview to see what `repository` and `architecture` is available.
 
 If the registry is private, provide credentials in the url. You can use a password or a [personal access token](development/api-usage.md#authentication):
 
 ```
-Server = https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
+[{repository}]
+SigLevel = Required
+Server = https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/arch/$repo/$arch
 ```
 
 ## Publish a package

docs/usage/packages/conan.md

@@ -18,7 +18,7 @@ To register the package registry you need to configure a new Conan remote:
 
 ```shell
 conan remote add {remote} https://gitea.example.com/api/packages/{owner}/conan
-conan user --remote {remote} --password {password} {username}
+conan remote login {remote} {username} --password {password}
 ```
 
 | Parameter  | Description |
@@ -32,7 +32,7 @@ For example:
 
 ```shell
 conan remote add gitea https://gitea.example.com/api/packages/testuser/conan
-conan user --remote gitea --password password123 testuser
+conan remote login gitea testuser --password password123
 ```
 
 ## Publish a package

docs/usage/packages/npm.md

@@ -29,7 +29,7 @@ npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{t
 | ------------ | ----------- |
 | `scope`      | The scope of the packages. |
 | `owner`      | The owner of the package. |
-| `token`      | Your [personal access token](development/api-usage.md#authentication). |
+| `token`      | Your [personal access token](development/api-usage.md#authentication). With `package` permissions. |
 
 For example:
 

docs/usage/packages/overview.md

@@ -35,6 +35,7 @@ The following package managers are currently supported:
 | [RPM](usage/packages/rpm.md) | - | `yum`, `dnf`, `zypper` |
 | [RubyGems](usage/packages/rubygems.md) | Ruby | `gem`, `Bundler` |
 | [Swift](usage/packages/swift.md) | Swift | `swift` |
+| [Terraform](usage/packages/terraform.md) | - | `terraform` |
 | [Vagrant](usage/packages/vagrant.md) | - | `vagrant` |
 
 **The following paragraphs only apply if Packages are not globally disabled!**
@@ -56,6 +57,8 @@ and shows a link to the repository on the package site (as well as a link to the
 | **read** access    | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only |
 | **write** access   | owner only | org members with admin or write access to the org |
 
+Please note, that your respective package manager needs to have a [personal access token](development/api-usage.md#authentication) with the permissions `package` set to either Read or Read & Write to download and publish packages respectively.
+
 N.B.: These access restrictions are [subject to change](https://github.com/go-gitea/gitea/issues/19270), where more finegrained control will be added via a dedicated organization team permission.
 
 ## Create or upload a package

docs/usage/packages/terraform.md

@@ -0,0 +1,99 @@
+---
+date: "2026-03-04T00:00:00+00:00"
+slug: "terraform"
+sidebar_position: 118
+---
+
+# Terraform State Registry
+
+Publish terraform states to sync it between multiple users or CI system.
+
+## Requirements
+
+To work with the Terraform State registry, you need to use [Terraform](https://www.terraform.io/) or [OpenTofu](https://opentofu.org/).
+
+## Configuring the package registry
+
+To use the Gitea Terraform State registry, you need to configure the `http` backend in your Terraform configuration.
+
+```hcl
+terraform {
+  backend "http" {
+    address        = "https://gitea.example.com/api/packages/{owner}/terraform/state/{name}"
+    lock_address   = "https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/lock"
+    unlock_address = "https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/lock"
+    lock_method    = "POST"
+    unlock_method  = "DELETE"
+    username       = "{username}"
+    password       = "{password_or_token}"
+  }
+}
+```
+
+| Placeholder | Description |
+| ----------- | ----------- |
+| `owner`     | The owner of the state (user or organization). |
+| `name`      | The name of the state. |
+| `username`  | Your Gitea username. |
+| `password`  | Your Gitea password or [personal access token](development/api-usage.md#authentication). |
+
+If you are using 2FA or OAuth use a [personal access token](development/api-usage.md#authentication) instead of the password.
+
+## Initialize the backend
+
+After configuring the backend, you can initialize it with:
+
+```shell
+terraform init
+```
+
+Terraform will prompt you to migrate your state if you already have one locally.
+
+## State Locking
+
+Gitea supports state locking to prevent concurrent modifications. The `lock_address` and `unlock_address` should point to the `/lock` sub-route of your state URL.
+
+- **Locking**: Performed via a `POST` request to `{address}/lock`.
+- **Unlocking**: Performed via a `DELETE` request to `{address}/lock`.
+
+Terraform handles these requests automatically when configured as shown above.
+
+## Encrypted state
+
+The state registry supports [encrypted state](https://opentofu.org/docs/language/state/encryption/).
+
+## State Versions and Management
+
+Gitea keeps track of your Terraform state versions. You can use the API to retrieve or delete specific versions.
+
+### Fetch state
+
+To fetch the latest version of a state:
+
+```shell
+curl --user {username}:{password_or_token} \
+     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}
+```
+
+To fetch a specific version by its serial number:
+
+```shell
+curl --user {username}:{password_or_token} \
+     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/versions/{serial}
+```
+
+### Delete state
+
+To delete the entire state and all its versions:
+
+```shell
+curl --user {username}:{password_or_token} -X DELETE \
+     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}
+```
+
+To delete a specific version by its serial number:
+
+```shell
+curl --user {username}:{password_or_token} -X DELETE \
+     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/versions/{serial}
+```

docs/usage/repository/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Repository",
+  "position": 10,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/repository",
+    "description": "Repository management, Git operations, and content features"
+  }
+}

docs/usage/repository/blame.md

@@ -1,12 +1,10 @@
 ---
 date: "2023-08-14T00:00:00+00:00"
-
 slug: "blame"
 sidebar_position: 13
-
 aliases:
   - /en-us/blame
-
+  - /blame
 ---
 
 # Blame File View

docs/usage/repository/clone-filter.md

@@ -1,11 +1,10 @@
 ---
 date: "2021-02-02"
-
 slug: "clone-filters"
 sidebar_position: 25
 aliases:
   - /en-us/clone-filters
-
+  - /clone-filters
 ---
 
 # Clone filters (partial clone)

docs/usage/repository/code-owners.md

@@ -1,12 +1,10 @@
 ---
 date: "2023-05-24T16:00:00+00:00"
-
 slug: "code-owners"
 sidebar_position: 30
-
 aliases:
   - /en-us/code-owners
-
+  - /code-owners
 ---
 
 # Code Owners

docs/usage/repository/incoming-email.md

@@ -1,11 +1,10 @@
 ---
 date: "2022-12-01T00:00:00+00:00"
-
 slug: "incoming-email"
-sidebar_position: 13
+sidebar_position: 130
 aliases:
   - /en-us/incoming-email
-
+  - /incoming-email
 ---
 
 # Incoming Email

docs/usage/repository/markdown.md

@@ -0,0 +1,155 @@
+---
+date: "2025-04-05T00:00:00+08:00"
+slug: "markdown"
+aliases:
+  - /markdown
+sidebar_position: 4
+---
+
+# Markdown
+
+Gitea uses MarkDown structured text in many places, you can recognise it by the `.md` file extension.
+Markdown is plain text format for writing structured documents, allowing one to write
+"plain" text files that nonetheless have _"fancy"_ **formatting**, while still keeping the plain-text version readable.
+
+Unfortunately, due to historical implementation differences, many subtle dialects exist.
+To avoid adding to the confusion, Gitea tries to follow "[GitHub Flavoured Markdown (GFM)](https://help.github.com/articles/github-flavored-markdown/)" as close as possible.
+"GFM" is an extension on top of the rigorously-specified [CommonMark](https://commonmark.org/) standard.
+CommonMark flavours are used by most major web platforms (e.g. Reddit, Stack Overflow, Discourse)
+and git forges (GitHub, GitLab and our very own Gitea), thus you shouldn't run into any surprises with Gitea.
+
+For a quick introduction to the syntax and features of GitHub Flavoured Markdown, see the GitHub documentation:
+- [Basic formatting](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
+- [Advanced formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting)
+
+For a deeper history about CommonMark, its spec, and its reason for existence, see [CommonMark.org](https://commonmark.org/).
+
+## Rendering options
+
+Some Gitea's markdown rendering behaviors can be fine-tuned by global config options, see the `[markdown]` config section in the `app.example.ini`
+
+
+## Link path resolving
+
+When rendering links for `<a href>`, `<img src>` and `<video src>`, Gitea resolves the link paths in the rendering context.
+
+- If the link is an absolute path with scheme, the link is kept as-is.
+- If the link is an URL path, it is resolved with the base path of current rendering context.
+  - In a comment-like context (issues, pull-requests, commit message), the base path is current repository's home link: `/owner-name/repo-name`.
+  - In a repository file context (markdown files in the repository), the base path is current git ref path.
+
+### Special link tokens
+
+To make users easier to resolve a link to the Gitea instance's root path, Gitea has a special `/:root` path syntax.
+This will always resolve to Gitea's ROOT_URL.
+
+Gitea also supports GitHub's `?raw=1` query parameter.
+A request to `/owner-name/repo-name/src/branch/main/file?raw=1` will be redirected to
+`/owner-name/repo-name/raw/branch/main/file`. This makes it possible to target raw contents from relative links
+(normally, the `src/` section of the path is provided automatically by Gitea and cannot be overriden).
+
+### Link handling examples
+
+For example, when rendering a markdown file in `/owner-name/repo-name/src/branch/main/dir`:
+  1) Absolute with scheme: Link `https://example.org` will be rendered as-is.
+  2) Relative from current file: Link `sub/file`is resolved to `/owner-name/repo-name/src/branch/main/dir/sub/file`
+  3) Relative from repo root: Link `/sub/file` (note leading slash) is resolved to `/owner-name/repo-name/src/branch/main/sub/file`
+  4) Raw media: If the link is used as `src` of an image or video, then it is resolved to `/owner-name/repo-name/raw/...`
+  5) Raw relative: `sub/file?raw=1` will resolve to `/owner-name/repo-name/src/branch/main/dir/sub/file?raw=1`,
+    which will redirect to `/owner-name/repo-name/raw/branch/main/dir/sub/file`.
+  6) explicit root: Link `/:root/any-path` is always resolved to `$ROOT_URL/any-path` without any further processing.
+
+
+## Issue and pull-request reference
+
+Using issue/pull-request numbers in a list:
+
+```
+* #123
+* #456
+```
+
+It will be rendered with issue titles to:
+
+```
+* the issue title (#123)
+* the other issue title (#456)
+```
+
+## Theme-based image display
+
+Gitea supports the GitHub-like theme-based image display. Supported syntax:
+
+* Use Markdown image
+
+```
+![My-Light](my-light.png#gh-light-mode-only)![My-Dark](my-dark.png#gh-dark-mode-only)
+```
+
+* Use `<img>` HTML tag
+
+```
+<img src="my-light.png#gh-light-mode-only" height="120" width="120"/>
+<img src="my-dark.png#gh-dark-mode-only" height="120" width="120"/>
+```
+
+* Use `<picture>` with `<source media>` (only works for themes with "auto" color preference)
+
+```
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="my-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="my-light.png">
+  <img src="my-light.png">
+</picture>
+```
+
+## Math expressions
+
+Gitea supports GitHub-like math expression formatting.
+
+### Inline expression
+
+  - ``` $\alpha$ ```: quoted by single-dollar `$`
+  - ``` $$\alpha$$ ```: quoted by double-dollar `$$`
+  - ``` $`\alpha`$ ```: quoted by dollar with backquotes, the backquotes could repeat like normal code blocks.
+
+### Block expression
+
+Using `$$`:
+
+````
+$$
+\alpha
+$$
+````
+
+Using code-block with language:
+
+````
+```math
+\alpha
+```
+````
+
+## Frontmatter
+
+Gitea supports frontmatter and Table of Contents (TOC) rendering. By default, frontmatter rendering is enabled, and TOC rendering is disabled.
+
+### Enabling TOC rendering
+
+To enable TOC rendering for a markdown file, add `include_toc: true` to its frontmatter section.
+
+### Disabling frontmatter
+
+To disable frontmatter rendering for a markdown file, add `gitea: none` to its frontmatter section.
+
+### Example
+
+```yaml
+---
+include_toc: true
+gitea: none
+---
+```
+
+Then, when you preview this markdown file in Gitea, the frontmatter section will not be rendered, and a Table of Contents will be generated at the top of the content.

docs/usage/repository/migration.md

@@ -0,0 +1,55 @@
+---
+date: "2024-09-11T09:30:00+08:00"
+slug: "migration"
+sidebar_position: 40
+aliases:
+  - /migration
+---
+
+# Migration
+
+You can migrate repositories from other Git services to your Gitea instance.
+
+## How to migrate from Gogs/GitHub/GitLab to Gitea
+
+To migrate from Gogs to Gitea:
+
+- [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
+
+To migrate from GitHub to Gitea, you can use Gitea's built-in migration form.
+
+In order to migrate items such as issues, pull requests, etc. you will need to input at least your username.
+
+[Example (requires login)](https://demo.gitea.com/repo/migrate)
+
+To migrate from GitLab to Gitea, you can use this non-affiliated tool:
+
+https://github.com/loganinak/MigrateGitlabToGogs
+
+## How to migrate from AWS CodeCommit to Gitea
+
+- To use the AWS CodeCommit API, Gitea requires an access key ID and a secret access key. For security reasons, we recommend creating a new user with the minimum necessary permissions and generating an access key ID and secret access key for the migration. The minimum permissions required for this user are as follows:
+  ```
+  {
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Effect": "Allow",
+        "Action": [
+          "codecommit:GetRepository",
+          "codecommit:GitPull",
+          "codecommit:ListPullRequests",
+          "codecommit:GetPullRequest",
+          "codecommit:GetCommentsForPullRequest"
+        ],
+        "Resource": [
+          "arn:aws:codecommit:<region>:<account>:<Repo-to-Migrate>
+      }
+    ]
+  }
+  ```
+  - If you do not need to migrate pull requests, you can remove the `ListPullRequests`, `GetPullRequest`, and `GetCommentsForPullRequest` actions.
+
+  - For instructions on how to create an IAM user and assign permissions, you can refer to this [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
+
+- To clone this repository, Gitea requires HTTPS Git credentials. You can create HTTPS Git credentials according to this [AWS documentation](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-gc.html).

docs/usage/repository/profile-readme.md

@@ -1,7 +1,9 @@
 ---
 date: "2023-03-02T21:00:00+05:00"
 slug: "profile-readme"
-sidebar_position: 12
+sidebar_position: 42
+aliases:
+  - /profile-readme
 ---
 
 # Profile READMEs

docs/usage/repository/push.md

@@ -5,6 +5,7 @@ sidebar_position: 15
 aliases:
   - /en-us/push-to-create
   - /en-us/push-options
+  - /push
 ---
 
 # Push
@@ -44,7 +45,7 @@ Push to create is a feature that allows you to push to a repository that does no
 
 ### Enabling Push To Create
 
-In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet](../administration/config-cheat-sheet.md#repository-repository).
+In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#repository-repository).
 
 ### Using Push To Create
 

docs/usage/repository/repo-mirror.md

@@ -4,9 +4,10 @@ slug: "repo-mirror"
 sidebar_position: 45
 aliases:
   - /en-us/repo-mirror
+  - /repo-mirror
 ---
 
-# Repository Mirror
+# Mirror Repository
 
 Repository mirroring allows for the mirroring of repositories to and from external sources. You can use it to mirror branches, tags, and commits between repositories.
 

docs/usage/repository/template-repositories.md

@@ -1,27 +1,30 @@
 ---
 date: "2019-11-28:00:00+02:00"
-
 slug: "template-repositories"
-sidebar_position: 14
-
+sidebar_position: 44
 aliases:
   - /en-us/template-repositories
+  - /template-repositories
 ---
 
-# Template Repositories
+# Template Repository
 
-Gitea `1.11.0` and above includes template repositories, and one feature implemented with them is auto-expansion of specific variables within your template files.
+Since Gitea `1.11`, you can create template repositories.
+When creating a repo based on a template, you can copy most of its content, and even auto-inject variables into it.
 
-To tell Gitea which files to expand, you must include a `template` file inside the `.gitea` directory of the template repository.
+By default, variables will not be expanded in any file.
+Only files contained in a pattern inside the `.gitea/template` file will be checked for if they contain variables.
+When creating the template, all files are included except for this `.gitea/template` file.
 
-Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax. It closely resembles a traditional `.gitignore`, however there may be slight differences.
+Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax.
+It closely resembles a traditional `.gitignore`, however there may be slight differences.
 
 ## Example `.gitea/template` file
 
 All paths are relative to the base of the repository
 
 ```gitignore
-# All .go files, anywhere in the repository
+# Expand all .go files, anywhere in the repository
 **.go
 
 # All text files in the text directory
@@ -34,20 +37,23 @@ a/b/c/d.json
 **.[bB][aA][tT]
 ```
 
-:::note
-The `template` file will be removed from the `.gitea` directory when a repository is generated from the template.
-:::
-
 ## Variable Expansion
 
-In any file matched by the above globs, certain variables will be expanded.
+In any file matched by the above globs, the variables below will be expanded.
 
 Matching filenames and paths can also be expanded, and are conservatively sanitized to support cross-platform filesystems.
 
-All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, use a double `$$`, such as `$$VAR` or `$${VAR}`
+You can use variables by prefixing them with `$` or surrounding them with `${}`, so both `$VAR` and `${VAR}` insert the value of `VAR` at this location.
+To escape an expansion, use `$$`, such as `$$VAR` or `$${VAR}`.
+
+These are the variables Gitea currently recognizes:
 
 | Variable             | Expands To                                          | Transformable |
 | -------------------- | --------------------------------------------------- | ------------- |
+| YEAR                 | The year of generating the repository (i.e. `2024`) | ✘             |
+| MONTH                | The month of generating the repository (i.e. `03`)  | ✘             |
+| MONTH_ENGLISH        | The month but in English (i.e. `March`)             | ✓             |
+| DAY                  | The day of generating the repository (i.e. `02`)    | ✘             |
 | REPO_NAME            | The name of the generated repository                | ✓             |
 | TEMPLATE_NAME        | The name of the template repository                 | ✓             |
 | REPO_DESCRIPTION     | The description of the generated repository         | ✘             |
@@ -63,11 +69,12 @@ All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, us
 
 ## Transformers :robot:
 
-Gitea `1.12.0` adds a few transformers to some of the applicable variables above.
+Since Gitea `1.12.0`, variables marked as transformable in the table above also have alternative versions where the given transformer has been applied.
 
-For example, to get `REPO_NAME` in `PASCAL`-case, your template would use `${REPO_NAME_PASCAL}`
+Transformed variables can be called by appending the transformer name to the variable name.
+For example, to get `REPO_NAME` in `PASCAL`-case, you should use the variable `${REPO_NAME_PASCAL}`.
 
-Feeding `go-sdk` to the available transformers yields...
+The following transformers are available (assuming `go-sdk` is the input):
 
 | Transformer | Effect |
 | ----------- | ------ |

docs/usage/repository/webhooks.md

@@ -0,0 +1,732 @@
+---
+date: "2016-12-01T16:00:00+02:00"
+slug: "webhooks"
+sidebar_position: 30
+aliases:
+  - /en-us/webhooks
+  - /webhooks
+---
+
+# Webhooks
+
+Gitea can send outbound webhooks for repository activity. Repository webhooks are
+configured at `/:username/:reponame/settings/hooks` by a repository admin.
+Equivalent webhook pages also exist for organizations, users, and system
+administration.
+
+Webhook configuration is available at four scopes:
+
+- `Repository webhooks`: Trigger only for activity in one repository.
+- `Organization webhooks`: Trigger for activity in repositories owned by that
+  organization.
+- `User webhooks`: Trigger for activity in repositories owned by that user.
+- `System webhooks`: Trigger for all eligible activity on the instance.
+
+Gitea also supports admin-defined `default webhooks`. These are not an extra
+delivery scope. Instead, they are copied into newly created repositories and
+then behave like ordinary repository webhooks.
+
+Gitea supports these outgoing webhook integrations:
+
+- Gitea
+- Gogs
+- Slack
+- Discord
+- Dingtalk
+- Telegram
+- Microsoft Teams
+- Feishu
+- Matrix
+- Wechatwork
+- Packagist
+
+The `Gitea` and `Gogs` webhook types send generic webhook payloads. The chat and
+service integrations listed above transform the same internal event into a
+service-specific request body.
+
+## Configuration
+
+This section covers the webhook settings you choose when creating or editing a
+webhook.
+
+### Configuring a webhook
+
+When creating a webhook, the main options are:
+
+- `Target URL`: The endpoint that receives the delivery.
+- `HTTP Method`: Usually `POST` for generic webhooks.
+- `POST Content Type`: `application/json` or
+  `application/x-www-form-urlencoded` for generic webhooks.
+- `Secret`: Used to sign the raw request body with HMAC.
+- `Authorization Header`: Optional custom `Authorization` header to send with
+  each request.
+- `Branch Filter`: Optional glob filter for branch and tag related events.
+- `Trigger On`: `Push Events`, `All Events`, or a custom event selection.
+- `Active`: Whether the webhook is enabled.
+
+:::note
+Older examples may still show a `secret` field inside the JSON payload. Current
+Gitea versions do not send the webhook secret in the payload body. Always verify
+the request by checking the signature headers instead.
+:::
+
+### Branch filters
+
+The branch filter uses glob syntax compatible with
+[`github.com/gobwas/glob`](https://pkg.go.dev/github.com/gobwas/glob#Compile).
+
+- Empty, `*`, or `**` matches everything.
+- A plain branch name such as `main` matches that branch.
+- Full refs such as `refs/tags/v*` are also supported.
+- Brace expressions such as `{main,release/*}` are supported.
+- The filter only applies to events that carry a git ref, such as `create`,
+  `delete`, and `push`.
+- Events without a ref, such as issues or releases, ignore the branch filter.
+
+Examples:
+
+- `main`
+- `{main,feature/*}`
+- `{refs/heads/feature/*,refs/tags/release/*}`
+
+### Authorization header
+
+Gitea can be configured to send a custom
+[Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)
+with each webhook delivery. This is independent from the webhook secret:
+
+- Use the secret to verify integrity with HMAC.
+- Use the `Authorization` header when the receiving endpoint requires
+  application-level authentication.
+
+## Delivery
+
+This section describes how Gitea sends webhook deliveries and how receivers can
+identify and verify them.
+
+### Delivery behavior
+
+- Webhooks are delivered asynchronously over HTTP.
+- Generic `Gitea` and `Gogs` webhooks support `POST` and `GET`; `POST` is the
+  normal choice.
+- For `POST` requests, the payload can be sent either as JSON
+  (`application/json`) or as a form field named `payload`
+  (`application/x-www-form-urlencoded`).
+- Provider-specific integrations may use the HTTP method and body format
+  required by that provider.
+
+### Delivery headers
+
+Every delivery includes a unique delivery ID and event headers. For
+GitHub-compatible integrations, Gitea also sends the corresponding GitHub and
+Gogs header names.
+
+| Header | Description |
+| --- | --- |
+| `X-Gitea-Delivery` | Unique delivery UUID for this attempt. |
+| `X-Gitea-Event` | Normalized event name, such as `push`, `issues`, or `pull_request`. |
+| `X-Gitea-Event-Type` | More specific event type, such as `issue_assign` or `pull_request_review_comment`. |
+| `X-Gitea-Signature` | Hex-encoded HMAC-SHA256 of the raw request body, without a prefix. |
+| `X-Gitea-Hook-Installation-Target-Type` | Where the webhook is defined: typically `repository`, `organization`, `user`, or `system`. Default webhooks are copied into repositories before delivery, so they are typically delivered as `repository`. |
+| `X-Gogs-Delivery`, `X-Gogs-Event`, `X-Gogs-Event-Type`, `X-Gogs-Signature` | Compatibility headers with the same values as the Gitea variants. |
+| `X-GitHub-Delivery`, `X-GitHub-Event`, `X-GitHub-Event-Type` | GitHub-style compatibility headers. |
+| `X-GitHub-Hook-Installation-Target-Type` | GitHub-style compatibility header for the webhook scope. |
+| `X-Hub-Signature` | GitHub-compatible HMAC-SHA1 header in the form `sha1=<digest>`. |
+| `X-Hub-Signature-256` | GitHub-compatible HMAC-SHA256 header in the form `sha256=<digest>`. |
+
+If no secret is configured, the signature headers are still present, but their
+digest values are empty.
+
+#### `Event` versus `Event-Type`
+
+Some Gitea webhook subscriptions are grouped together under one normalized event
+name. For example, an issue assignment delivery uses the issue event group:
+
+```http
+X-Gitea-Event: issues
+X-Gitea-Event-Type: issue_assign
+X-GitHub-Event: issues
+X-GitHub-Event-Type: issue_assign
+```
+
+Use `X-Gitea-Event-Type` when you need the exact trigger that fired the webhook.
+
+#### Validating deliveries
+
+Gitea signs the raw request body with your webhook secret. To validate a
+delivery:
+
+1. Read the request body exactly as it was received.
+2. Compute the HMAC-SHA256 digest with your webhook secret.
+3. Compare the result with `X-Gitea-Signature` or with the GitHub-compatible
+   `X-Hub-Signature-256` header.
+4. Use a constant-time comparison when possible.
+
+Important details:
+
+- `X-Gitea-Signature` contains only the lowercase hexadecimal SHA-256 digest.
+- `X-Hub-Signature-256` contains the same digest with a `sha256=` prefix.
+- `X-Hub-Signature` is also sent for compatibility and uses SHA-1.
+- The body must be verified before JSON parsing or any other modification.
+
+##### PHP example
+
+The following example verifies a generic `Gitea` webhook sent as
+`application/json`.
+
+```php
+<?php
+
+$secret = '123';
+
+if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
+    http_response_code(405);
+    exit('Only POST is allowed');
+}
+
+$payload = file_get_contents('php://input');
+$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
+
+if ($payload === false || $signature === '') {
+    http_response_code(400);
+    exit('Missing payload or signature');
+}
+
+$expected = hash_hmac('sha256', $payload, $secret);
+
+if (!hash_equals($expected, $signature)) {
+    http_response_code(401);
+    exit('Invalid signature');
+}
+
+$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
+$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
+$data = json_decode($payload, true);
+
+if (!is_array($data)) {
+    http_response_code(400);
+    exit('Invalid JSON payload');
+}
+
+http_response_code(204);
+```
+
+## Events
+
+This section follows the same event-by-event style used by GitHub's webhook
+documentation: each event describes when it occurs and what the top-level
+payload contains.
+
+The event groups match the webhook settings UI: `Repository Events`,
+`Issue Events`, `Pull Request Events`, and `Workflow Events`.
+
+### Repository Events
+
+- `create`, `delete`, `fork`, `push`, `wiki`, `repository`, `release`, `package`, `status`
+
+#### `create`
+
+This event occurs when a branch or tag is created.
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `sha` | `string` | **Required.** The object ID of the created reference. |
+| `ref` | `string` | **Required.** The created branch or tag name. |
+| `ref_type` | `string` | **Required.** The reference type, such as `branch` or `tag`. |
+| `repository` | `object` | **Required.** The repository where the reference was created. |
+| `sender` | `object` | **Required.** The user who created the reference. |
+
+#### `delete`
+
+This event occurs when a branch or tag is deleted.
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `ref` | `string` | **Required.** The deleted branch or tag name. |
+| `ref_type` | `string` | **Required.** The reference type, such as `branch` or `tag`. |
+| `pusher_type` | `string` | **Required.** The actor type that deleted the ref. Current Gitea payloads use `user`. |
+| `repository` | `object` | **Required.** The repository where the reference was deleted. |
+| `sender` | `object` | **Required.** The user who deleted the reference. |
+
+#### `fork`
+
+This event occurs when a repository is forked.
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `forkee` | `object` | **Required.** The newly created fork repository. |
+| `repository` | `object` | **Required.** The original repository that was forked. |
+| `sender` | `object` | **Required.** The user who created the fork. |
+
+#### `push`
+
+This event occurs when commits are pushed to a branch or tag.
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `ref` | `string` | **Required.** The full pushed ref, such as `refs/heads/main`. |
+| `before` | `string` | **Required.** The commit SHA before the push. |
+| `after` | `string` | **Required.** The commit SHA after the push. |
+| `compare_url` | `string` | **Required.** URL to compare `before` and `after`. |
+| `commits` | `array` | **Required.** Commits included in the push. |
+| `total_commits` | `integer` | **Required.** Number of commits in the push. |
+| `head_commit` | `object` | The most recent commit in the push. |
+| `repository` | `object` | **Required.** The repository that received the push. |
+| `pusher` | `object` | **Required.** The user who performed the push. |
+| `sender` | `object` | **Required.** The user who triggered the webhook. |
+
+#### `wiki`
+
+This event occurs when a wiki page is created, edited, or deleted.
+
+**Action type:** `created`, `edited`, `deleted`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The wiki page action. |
+| `repository` | `object` | **Required.** The repository that owns the wiki. |
+| `sender` | `object` | **Required.** The user who changed the wiki page. |
+| `page` | `string` | **Required.** The wiki page name. |
+| `comment` | `string` | The wiki commit message or comment. |
+
+#### `repository`
+
+This event occurs when a repository is created or deleted.
+
+**Action type:** `created`, `deleted`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The repository action. |
+| `repository` | `object` | **Required.** The repository that was created or deleted. |
+| `organization` | `object` | Present when the repository belongs to an organization. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+
+#### `release`
+
+This event occurs when a release is published, updated, or deleted.
+
+**Action type:** `published`, `updated`, `deleted`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The release action. |
+| `release` | `object` | **Required.** The release that was acted on. |
+| `repository` | `object` | **Required.** The repository containing the release. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+
+#### `package`
+
+This event occurs when a package is created or deleted.
+
+**Action type:** `created`, `deleted`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The package action. |
+| `repository` | `object` | The repository associated with the package, when applicable. |
+| `package` | `object` | **Required.** The package that was acted on. |
+| `organization` | `object` | Present when the package owner is an organization. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+
+#### `status`
+
+This event occurs when a commit status is created or updated through the API.
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `commit` | `object` | The commit associated with the status. |
+| `context` | `string` | **Required.** The status context, such as `ci/build`. |
+| `created_at` | `string` | **Required.** The time the status was created. |
+| `description` | `string` | Status description text. |
+| `id` | `integer` | **Required.** The status identifier. |
+| `repository` | `object` | **Required.** The repository containing the commit. |
+| `sender` | `object` | **Required.** The user who created the status. |
+| `sha` | `string` | **Required.** The commit SHA. |
+| `state` | `string` | **Required.** The state, such as `pending`, `success`, `error`, or `failure`. |
+| `target_url` | `string` | Target URL associated with the status. |
+| `updated_at` | `string` | The time the status was last updated. |
+
+Unlike most other payloads, this event does not use an `action` field. The
+state transition is represented by `state`.
+
+### Issue Events
+
+- `issues`, `issue_assign`, `issue_label`, `issue_milestone`, `issue_comment`
+
+#### `issues`
+
+This event occurs when an issue is opened, closed, reopened, edited, or deleted.
+
+**Action type:** `opened`, `closed`, `reopened`, `edited`, `deleted`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The issue action. |
+| `number` | `integer` | **Required.** The issue number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `issue` | `object` | **Required.** The issue that was acted on. |
+| `repository` | `object` | **Required.** The repository containing the issue. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
+
+#### `issue_assign`
+
+This event occurs when an issue is assigned or unassigned.
+
+**Action type:** `assigned`, `unassigned`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The assignment action. |
+| `number` | `integer` | **Required.** The issue number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `issue` | `object` | **Required.** The issue that was acted on. |
+| `repository` | `object` | **Required.** The repository containing the issue. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
+
+#### `issue_label`
+
+This event occurs when issue labels are updated or cleared.
+
+**Action type:** `label_updated`, `label_cleared`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The label update action. |
+| `number` | `integer` | **Required.** The issue number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `issue` | `object` | **Required.** The issue that was acted on. |
+| `repository` | `object` | **Required.** The repository containing the issue. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
+
+#### `issue_milestone`
+
+This event occurs when an issue is milestoned or demilestoned.
+
+**Action type:** `milestoned`, `demilestoned`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The milestone action. |
+| `number` | `integer` | **Required.** The issue number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `issue` | `object` | **Required.** The issue that was acted on. |
+| `repository` | `object` | **Required.** The repository containing the issue. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
+
+#### `issue_comment`
+
+This event occurs when a comment on an issue is created, edited, or deleted.
+
+**Action type:** `created`, `edited`, `deleted`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The comment action. |
+| `issue` | `object` | **Required.** The issue that the comment belongs to. |
+| `pull_request` | `object` | Present only when the comment is on a pull request timeline. |
+| `comment` | `object` | **Required.** The comment that was created, edited, or deleted. |
+| `changes` | `object` | Optional. Previous comment body when the action is `edited`. |
+| `repository` | `object` | **Required.** The repository containing the issue. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+| `is_pull` | `boolean` | **Required.** Whether the comment is on a pull request timeline. |
+
+### Pull Request Events
+
+- `pull_request`, `pull_request_assign`, `pull_request_label`, `pull_request_milestone`, `pull_request_comment`, `pull_request_review`, `pull_request_review_approved`, `pull_request_review_rejected`, `pull_request_review_comment`, `pull_request_sync`, `pull_request_review_request`
+
+#### `pull_request`
+
+This event occurs when a pull request is opened, closed, reopened, edited, or deleted.
+
+**Action type:** `opened`, `closed`, `reopened`, `edited`, `deleted`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The pull request action. |
+| `number` | `integer` | **Required.** The pull request number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `pull_request` | `object` | **Required.** The pull request that was acted on. |
+| `requested_reviewer` | `object` | Present for review request events. |
+| `repository` | `object` | **Required.** The repository containing the pull request. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
+| `review` | `object` | Present for pull request review events. |
+
+#### `pull_request_assign`
+
+This event occurs when a pull request is assigned or unassigned.
+
+**Action type:** `assigned`, `unassigned`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The assignment action. |
+| `number` | `integer` | **Required.** The pull request number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `pull_request` | `object` | **Required.** The pull request that was acted on. |
+| `requested_reviewer` | `object` | Present for review request events. |
+| `repository` | `object` | **Required.** The repository containing the pull request. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
+| `review` | `object` | Present for pull request review events. |
+
+#### `pull_request_label`
+
+This event occurs when pull request labels are updated or cleared.
+
+**Action type:** `label_updated`, `label_cleared`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The label update action. |
+| `number` | `integer` | **Required.** The pull request number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `pull_request` | `object` | **Required.** The pull request that was acted on. |
+| `requested_reviewer` | `object` | Present for review request events. |
+| `repository` | `object` | **Required.** The repository containing the pull request. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
+| `review` | `object` | Present for pull request review events. |
+
+#### `pull_request_milestone`
+
+This event occurs when a pull request is milestoned or demilestoned.
+
+**Action type:** `milestoned`, `demilestoned`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The milestone action. |
+| `number` | `integer` | **Required.** The pull request number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `pull_request` | `object` | **Required.** The pull request that was acted on. |
+| `requested_reviewer` | `object` | Present for review request events. |
+| `repository` | `object` | **Required.** The repository containing the pull request. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
+| `review` | `object` | Present for pull request review events. |
+
+#### `pull_request_comment`
+
+This event occurs when a timeline comment on a pull request is created, edited, or deleted.
+
+**Action type:** `created`, `edited`, `deleted`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The comment action. |
+| `issue` | `object` | **Required.** The related issue record for the pull request. |
+| `pull_request` | `object` | **Required.** The pull request the timeline comment belongs to. |
+| `comment` | `object` | **Required.** The comment that was created, edited, or deleted. |
+| `changes` | `object` | Optional. Previous comment body when the action is `edited`. |
+| `repository` | `object` | **Required.** The repository containing the pull request. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+| `is_pull` | `boolean` | **Required.** Always `true` for this event. |
+
+#### `pull_request_review`
+
+This is a subscription-only umbrella event in the webhook settings UI.
+
+It does not have its own delivery payload. When selected, Gitea delivers the
+more specific events `pull_request_review_approved`,
+`pull_request_review_rejected`, and `pull_request_review_comment`.
+
+#### `pull_request_review_approved`
+
+This event occurs when a pull request review is submitted with approval.
+
+**Action type:** `reviewed`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** Always `reviewed`. |
+| `number` | `integer` | **Required.** The pull request number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `pull_request` | `object` | **Required.** The pull request that was reviewed. |
+| `requested_reviewer` | `object` | Present for review request events. |
+| `repository` | `object` | **Required.** The repository containing the pull request. |
+| `sender` | `object` | **Required.** The user who submitted the review. |
+| `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
+| `review` | `object` | **Required.** The review payload. For this event, `review.type` is `approved`. |
+
+#### `pull_request_review_rejected`
+
+This event occurs when a pull request review is submitted with a rejection or a
+request for changes.
+
+**Action type:** `reviewed`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** Always `reviewed`. |
+| `number` | `integer` | **Required.** The pull request number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `pull_request` | `object` | **Required.** The pull request that was reviewed. |
+| `requested_reviewer` | `object` | Present for review request events. |
+| `repository` | `object` | **Required.** The repository containing the pull request. |
+| `sender` | `object` | **Required.** The user who submitted the review. |
+| `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
+| `review` | `object` | **Required.** The review payload. For this event, `review.type` is `rejected`. |
+
+#### `pull_request_review_comment`
+
+This event occurs when a pull request review is submitted as a comment.
+
+**Action type:** `reviewed`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** Always `reviewed`. |
+| `number` | `integer` | **Required.** The pull request number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `pull_request` | `object` | **Required.** The pull request that was reviewed. |
+| `requested_reviewer` | `object` | Present for review request events. |
+| `repository` | `object` | **Required.** The repository containing the pull request. |
+| `sender` | `object` | **Required.** The user who submitted the review. |
+| `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
+| `review` | `object` | **Required.** The review payload. For this event, `review.type` is `comment`. |
+
+#### `pull_request_sync`
+
+This event occurs when a pull request is synchronized after new commits are pushed.
+
+**Action type:** `synchronized`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** Always `synchronized`. |
+| `number` | `integer` | **Required.** The pull request number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `pull_request` | `object` | **Required.** The pull request that was synchronized. |
+| `requested_reviewer` | `object` | Present for review request events. |
+| `repository` | `object` | **Required.** The repository containing the pull request. |
+| `sender` | `object` | **Required.** The user who performed the synchronization. |
+| `commit_id` | `string` | The commit SHA associated with the synchronization event, if applicable. |
+| `review` | `object` | Present for pull request review events. |
+
+#### `pull_request_review_request`
+
+This event occurs when a reviewer is requested or a review request is removed.
+
+**Action type:** `review_requested`, `review_request_removed`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The review request action. |
+| `number` | `integer` | **Required.** The pull request number. |
+| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
+| `pull_request` | `object` | **Required.** The pull request that was acted on. |
+| `requested_reviewer` | `object` | The reviewer that was requested or removed. |
+| `repository` | `object` | **Required.** The repository containing the pull request. |
+| `sender` | `object` | **Required.** The user who performed the action. |
+| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
+| `review` | `object` | Present for pull request review events. |
+
+### Workflow Events
+
+- `workflow_run`, `workflow_job`
+
+#### `workflow_run`
+
+This event occurs when a Gitea Actions workflow run changes status.
+
+**Action type:** `queued`, `waiting`, `in_progress`, `completed`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The workflow run status transition. |
+| `workflow` | `object` | **Required.** The workflow definition. |
+| `workflow_run` | `object` | **Required.** The workflow run that was acted on. |
+| `pull_request` | `object` | Present when the workflow run is associated with a pull request. |
+| `organization` | `object` | Present when the repository owner is an organization. |
+| `repository` | `object` | **Required.** The repository containing the workflow. |
+| `sender` | `object` | **Required.** The user who triggered the workflow run update. |
+
+#### `workflow_job`
+
+This event occurs when a Gitea Actions workflow job changes status.
+
+**Action type:** `queued`, `waiting`, `in_progress`, `completed`
+
+##### Payload parameters
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `action` | `string` | **Required.** The workflow job status transition. |
+| `workflow_job` | `object` | **Required.** The workflow job that was acted on. |
+| `pull_request` | `object` | Present when the workflow job is associated with a pull request. |
+| `organization` | `object` | Present when the repository owner is an organization. |
+| `repository` | `object` | **Required.** The repository containing the workflow job. |
+| `sender` | `object` | **Required.** The user who triggered the workflow job update. |
+
+## Testing, recent deliveries, and replay
+
+Each webhook page includes:
+
+- `Test Delivery`, which sends a synthetic `push` event for the repository.
+- `Recent Deliveries`, which shows request and response details.
+- `Redelivery`, which replays an earlier webhook delivery.
+
+If the repository has no commits yet, the test delivery uses a generated fake
+commit so the webhook can still be exercised.
+
+## Administration notes
+
+Administrators can further control webhook delivery with instance settings such
+as host allow lists, delivery timeouts, and cleanup policies. See the
+[Webhook section of the configuration cheat sheet](../../administration/config-cheat-sheet.md#webhook-webhook).

docs/usage/user-setting/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "User Setting",
+  "position": 200,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/user-setting",
+    "description": "Configuring user preferences and settings"
+  }
+}

docs/usage/user-setting/multi-factor-authentication.md

@@ -1,9 +1,9 @@
 ---
 date: "2023-08-22T14:21:00+08:00"
-
 slug: "multi-factor-authentication"
 weight: 15
-
+aliases:
+  - /multi-factor-authentication
 ---
 
 # Multi-factor Authentication (MFA)

docs/usage/webhooks.md

@@ -1,189 +0,0 @@
----
-date: "2016-12-01T16:00:00+02:00"
-slug: "webhooks"
-sidebar_position: 30
-aliases:
-  - /en-us/webhooks
----
-
-# Webhooks
-
-Gitea supports webhooks for repository events. This can be configured in the settings
-page `/:username/:reponame/settings/hooks` by a repository admin. Webhooks can also be configured on a per-organization and whole system basis.
-All event pushes are POST requests. The methods currently supported are:
-
-- Gitea (can also be a GET request)
-- Gogs
-- Slack
-- Discord
-- Dingtalk
-- Telegram
-- Microsoft Teams
-- Feishu
-- Wechatwork
-- Packagist
-
-### Event information
-
-:::warning
-The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755
-:::
-
-The following is an example of event information that will be sent by Gitea to
-a Payload URL:
-
-```http
-X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
-X-GitHub-Event: push
-X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
-X-Gogs-Event: push
-X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
-X-Gitea-Event: push
-```
-
-```json
-{
-  "secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
-  "ref": "refs/heads/develop",
-  "before": "28e1879d029cb852e4844d9c718537df08844e03",
-  "after": "bffeb74224043ba2feb48d137756c8a9331c449a",
-  "compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
-  "commits": [
-    {
-      "id": "bffeb74224043ba2feb48d137756c8a9331c449a",
-      "message": "Webhooks Yay!",
-      "url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
-      "author": {
-        "name": "Gitea",
-        "email": "someone@gitea.io",
-        "username": "gitea"
-      },
-      "committer": {
-        "name": "Gitea",
-        "email": "someone@gitea.io",
-        "username": "gitea"
-      },
-      "timestamp": "2017-03-13T13:52:11-04:00"
-    }
-  ],
-  "repository": {
-    "id": 140,
-    "owner": {
-      "id": 1,
-      "login": "gitea",
-      "full_name": "Gitea",
-      "email": "someone@gitea.io",
-      "avatar_url": "https://localhost:3000/avatars/1",
-      "username": "gitea"
-    },
-    "name": "webhooks",
-    "full_name": "gitea/webhooks",
-    "description": "",
-    "private": false,
-    "fork": false,
-    "html_url": "http://localhost:3000/gitea/webhooks",
-    "ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
-    "clone_url": "http://localhost:3000/gitea/webhooks.git",
-    "website": "",
-    "stars_count": 0,
-    "forks_count": 1,
-    "watchers_count": 1,
-    "open_issues_count": 7,
-    "default_branch": "master",
-    "created_at": "2017-02-26T04:29:06-05:00",
-    "updated_at": "2017-03-13T13:51:58-04:00"
-  },
-  "pusher": {
-    "id": 1,
-    "login": "gitea",
-    "full_name": "Gitea",
-    "email": "someone@gitea.io",
-    "avatar_url": "https://localhost:3000/avatars/1",
-    "username": "gitea"
-  },
-  "sender": {
-    "id": 1,
-    "login": "gitea",
-    "full_name": "Gitea",
-    "email": "someone@gitea.io",
-    "avatar_url": "https://localhost:3000/avatars/1",
-    "username": "gitea"
-  }
-}
-```
-
-### Example
-
-This is an example of how to use webhooks to run a php script upon push requests to the repository.
-In your repository Settings, under Webhooks, Setup a Gitea webhook as follows:
-
-- Target URL: http://mydomain.com/webhook.php
-- HTTP Method: POST
-- POST Content Type: application/json
-- Secret: 123
-- Trigger On: Push Events
-- Active: Checked
-
-Now on your server create the php file webhook.php
-
-```php
-<?php
-
-$secret_key = '123';
-
-// check for POST request
-if ($_SERVER['REQUEST_METHOD'] != 'POST') {
-    error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
-    exit();
-}
-
-// get content type
-$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
-
-if ($content_type != 'application/json') {
-    error_log('FAILED - not application/json - '. $content_type);
-    exit();
-}
-
-// get payload
-$payload = trim(file_get_contents("php://input"));
-
-if (empty($payload)) {
-    error_log('FAILED - no payload');
-    exit();
-}
-
-// get header signature
-$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
-
-if (empty($header_signature)) {
-    error_log('FAILED - header signature missing');
-    exit();
-}
-
-// calculate payload signature
-$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
-
-// check payload signature against header signature
-if ($header_signature !== $payload_signature) {
-    error_log('FAILED - payload signature');
-    exit();
-}
-
-// convert json to array
-$decoded = json_decode($payload, true);
-
-// check for json decode errors
-if (json_last_error() !== JSON_ERROR_NONE) {
-    error_log('FAILED - json decode - '. json_last_error());
-    exit();
-}
-
-// success, do something
-```
-
-There is a Test Delivery button in the webhook settings that allows to test the configuration as well as a list of the most Recent Deliveries.
-
-### Authorization header
-
-**With 1.19**, Gitea hooks can be configured to send an [authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) to the webhook target.

docusaurus.config.js

@@ -29,7 +29,19 @@ const apiConfig = [
           },
           {
             route: "/api/",
-            spec: "static/swagger-24.json",
+            spec: "static/swagger-26.json",
+          },
+          {
+            route: "/api/1.27/",
+            spec: "static/swagger-27.json",
+          },
+          {
+            route: "/api/1.26/",
+            spec: "static/swagger-26.json",
+          },
+          {
+            route: "/api/1.25/",
+            spec: "static/swagger-25.json",
           },
           {
             route: "/api/1.24/",
@@ -43,18 +55,6 @@ const apiConfig = [
             route: "/api/1.22/",
             spec: "static/swagger-22.json",
           },
-          {
-            route: "/api/1.21/",
-            spec: "static/swagger-21.json",
-          },
-          {
-            route: "/api/1.20/",
-            spec: "static/swagger-20.json",
-          },
-          {
-            route: "/api/1.19/",
-            spec: "static/swagger-19.json",
-          },
         ]
       : [],
     // Theme Options for modifying how redoc renders them
@@ -72,17 +72,47 @@ const pageConfig = renderApiSSR
   : {};
 
 const globalVariables = {
-  current: {
-    goVersion: "1.24",
-    minGoVersion: "1.24",
+  "current": {
+    goVersion: "1.26",
+    minGoVersion: "1.26",
     minNodeVersion: "22",
     version: "main-nightly",
     sourceVersion: "main",
     sourceBranch: "main",
     dockerVersion: "nightly",
-    displayVersion: "1.25-dev",
+    displayVersion: "1.28-dev",
   },
-  1.24: {
+  "1.27": {
+    goVersion: "1.26",
+    minGoVersion: "1.26",
+    minNodeVersion: "24",
+    version: "1.27.0-rc0",
+    sourceVersion: "v1.27.0-rc0",
+    sourceBranch: "release/v1.27",
+    dockerVersion: "1.27.0-rc0",
+    displayVersion: "1.27.0-rc0",
+  },
+  "1.26": {
+    goVersion: "1.26",
+    minGoVersion: "1.26",
+    minNodeVersion: "22",
+    version: "1.26.4",
+    sourceVersion: "v1.26.4",
+    sourceBranch: "release/v1.26",
+    dockerVersion: "1.26.4",
+    displayVersion: "1.26.4",
+  },
+  "1.25": {
+    goVersion: "1.25",
+    minGoVersion: "1.25",
+    minNodeVersion: "22",
+    version: "1.25.5",
+    sourceVersion: "v1.25.0",
+    sourceBranch: "release/v1.25",
+    dockerVersion: "1.25.5",
+    displayVersion: "1.25.5",
+  },
+  "1.24": {
     goVersion: "1.24",
     minGoVersion: "1.24",
     minNodeVersion: "22",
@@ -92,7 +122,7 @@ const globalVariables = {
     dockerVersion: "1.24.7",
     displayVersion: "1.24.7",
   },
-  1.23: {
+  "1.23": {
     goVersion: "1.23",
     minGoVersion: "1.22",
     minNodeVersion: "18",
@@ -102,7 +132,7 @@ const globalVariables = {
     dockerVersion: "1.23.8",
     displayVersion: "1.23.8",
   },
-  1.22: {
+  "1.22": {
     goVersion: "1.22",
     minGoVersion: "1.22",
     minNodeVersion: "18",
@@ -112,61 +142,31 @@ const globalVariables = {
     dockerVersion: "1.22.6",
     displayVersion: "1.22.6",
   },
-  1.21: {
-    goVersion: "1.21",
-    minGoVersion: "1.21",
-    minNodeVersion: "18",
-    version: "1.21.11",
-    sourceVersion: "v1.21.11",
-    sourceBranch: "release/v1.21",
-    dockerVersion: "1.21.11",
-    displayVersion: "1.21.11",
-  },
-  "1.20": {
-    goVersion: "1.20",
-    minGoVersion: "1.20",
-    minNodeVersion: "16",
-    version: "1.20.6",
-    sourceVersion: "v1.20.6",
-    sourceBranch: "release/v1.20",
-    dockerVersion: "1.20.6",
-    displayVersion: "1.20.6",
-  },
-  1.19: {
-    goVersion: "1.20",
-    minGoVersion: "1.19",
-    minNodeVersion: "14",
-    version: "1.19.4",
-    sourceVersion: "v1.19.4",
-    sourceBranch: "release/v1.19",
-    dockerVersion: "1.19.4",
-    displayVersion: "1.19.4",
-  },
 };
 
 const versions = {
-  current: {
+  "current": {
     label: globalVariables["current"].displayVersion, // path is kept as next for dev (so users can always find "nightly" docs)
     banner: "unreleased",
   },
-  1.24: {
+  "1.27": {
+    label: globalVariables["1.27"].displayVersion,
+  },
+  "1.26": {
+    label: globalVariables["1.26"].displayVersion,
+  },
+  "1.25": {
+    label: globalVariables["1.25"].displayVersion,
+  },
+  "1.24": {
     label: globalVariables["1.24"].displayVersion,
   },
-  1.23: {
+  "1.23": {
     label: globalVariables["1.23"].displayVersion,
   },
-  1.22: {
+  "1.22": {
     label: globalVariables["1.22"].displayVersion,
   },
-  1.21: {
-    label: globalVariables["1.21"].displayVersion,
-  },
-  "1.20": {
-    label: globalVariables["1.20"].displayVersion,
-  },
-  1.19: {
-    label: globalVariables["1.19"].displayVersion,
-  },
 };
 
 /** @type {import('@docusaurus/types').Config} */
@@ -176,10 +176,9 @@ const config = {
   url: "https://docs.gitea.com",
   baseUrl: "/",
   onBrokenLinks: "warn",
-  onBrokenMarkdownLinks: "warn",
   favicon: "img/favicon.png",
   future: {
-    experimental_faster: true,
+    faster: true,
     v4: true
   },
   plugins: [
@@ -194,8 +193,8 @@ const config = {
     [
       "@docusaurus/plugin-content-docs",
       {
-        id: "runner",
-        path: "runner",
+        id: "runner-docs",
+        path: "runner-docs",
         routeBasePath: "runner",
         //sidebarPath: './runner/sidebars.js',
         versions: {
@@ -203,12 +202,16 @@ const config = {
             label: "main",
             banner: "unreleased",
           },
+          "1.0.8": {
+            path: "1.0.8",
+            label: "1.0.8",
+          },
           "0.2.11": {
             path: "0.2.11",
             label: "0.2.11",
           },
         },
-        lastVersion: "0.2.11",
+        lastVersion: "1.0.8",
         editUrl: ({
           versionDocsDirPath,
           docPath,
@@ -218,8 +221,8 @@ const config = {
         }) => {
           return `https://gitea.com/gitea/docs/src/branch/main/${
             version === "current"
-              ? "runner"
-              : `runner_versioned_docs/version-${version}`
+              ? "runner-docs"
+              : `runner-docs_versioned_docs/version-${version}`
           }/${docPath}`;
         },
         async sidebarItemsGenerator({ defaultSidebarItemsGenerator, ...args }) {
@@ -284,7 +287,7 @@ const config = {
             }/${docPath}`;
           },
           versions: versions,
-          lastVersion: "1.24",
+          lastVersion: "1.26",
           async sidebarItemsGenerator({
             defaultSidebarItemsGenerator,
             ...args
@@ -312,6 +315,9 @@ const config = {
     apiConfig,
   ],
   markdown: {
+    hooks: {
+      onBrokenMarkdownLinks: "warn",
+    },
     preprocessor: ({ filePath, fileContent }) => {
       var key = "";
       var found = false;
@@ -391,16 +397,16 @@ const config = {
             label: "Docs",
           },
           {
-            to: "/api/1.24/",
+            to: "/api/1.26/",
             label: "API",
             position: "left",
-            activeBaseRegex: "api/(1.19|1.20|1.21|1.22|1.23|1.24|next)/",
+            activeBaseRegex: "api/(1.22|1.23|1.24|1.25|1.26|1.27|next)/",
           },
           {
-            to: "/runner/0.2.11/",
+            to: "/runner/1.0.8/",
             label: "Runner",
             position: "left",
-            activeBaseRegex: "runner/(0.2.11|next)/",
+            activeBaseRegex: "runner/(1.0.8|0.2.11|next)/",
           },
           {
             position: "left",
@@ -427,13 +433,13 @@ const config = {
             label: "API Version",
             position: "right",
             items: [
-              { to: "/api/next/", label: "1.25-dev" },
+              { to: "/api/next/", label: "1.28-dev" },
+              { to: "/api/1.27/", label: "1.27.0-rc0" },
+              { to: "/api/1.26/", label: "1.26.4" },
+              { to: "/api/1.25/", label: "1.25.5" },
               { to: "/api/1.24/", label: "1.24.7" },
               { to: "/api/1.23/", label: "1.23.8" },
               { to: "/api/1.22/", label: "1.22.6" },
-              { to: "/api/1.21/", label: "1.21.11" },
-              { to: "/api/1.20/", label: "1.20.6" },
-              { to: "/api/1.19/", label: "1.19.4" },
             ],
             routerRgx: "/api/",
             classNames: "api-dropdown",
@@ -444,6 +450,7 @@ const config = {
             position: "right",
             items: [
               { to: "/runner/next/", label: "development" },
+              { to: "/runner/1.0.8/", label: "1.0.8" },
               { to: "/runner/0.2.11/", label: "0.2.11" },
             ],
             routerRgx: "/runner/",

i18n/en-us/docusaurus-plugin-content-docs/version-1.26.json

@@ -0,0 +1,8 @@
+{
+  "sidebar.docs.category.actions": {
+    "message": "Actions"
+  },
+  "sidebar.docs.category.packages": {
+    "message": "Packages"
+  }
+}

i18n/en-us/docusaurus-plugin-content-docs/version-1.27.json

@@ -0,0 +1,8 @@
+{
+  "sidebar.docs.category.actions": {
+    "message": "Actions"
+  },
+  "sidebar.docs.category.packages": {
+    "message": "Packages"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/administration.md

@@ -1,12 +0,0 @@
----
-date: "2016-12-01T16:00:00+02:00"
-title: "运维"
-slug: "administration"
-sidebar_position: 30
-
-menu:
-  sidebar:
-    name: "运维"
-    sidebar_position: 20
-    identifier: "administration"
----

i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "运维",
+  "position": 30,
+  "link": {
+    "type": "generated-index",
+    "slug": "/administration",
+    "title": "运维"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/backup-and-restore.md

@@ -23,7 +23,7 @@ Gitea 包括数据库、文件和 Git 仓库，当它被使用时所有这些都
 
 ```
 2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:09 Dumping local repositories.../home/git/gitea-repositories
+2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
 2016/12/27 22:32:22 Dumping database...
 2016/12/27 22:32:22 Packing dump files...
 2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
@@ -80,7 +80,7 @@ cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/gitea-repositories/
+mv repos/* /var/lib/gitea/repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
 
 # mysql
@@ -114,7 +114,7 @@ cd gitea-dump-1610949662
 # 恢复 Gitea 数据
 mv data/* /data/gitea
 # 恢复仓库本身
-mv repos/* /data/git/gitea-repositories/
+mv repos/* /data/git/repositories/
 # 调整文件权限
 chown -R git:git /data
 # 重新生成 Git 钩子
@@ -138,7 +138,7 @@ mv data/conf/app.ini /etc/gitea/app.ini
 # 恢复 Gitea 数据
 mv data/* /var/lib/gitea
 # 恢复仓库本身
-mv repos/* /var/lib/gitea/git/gitea-repositories
+mv repos/* /var/lib/gitea/git/repositories
 # 调整文件权限
 chown -R git:git /etc/gitea/app.ini /var/lib/gitea
 # 重新生成 Git 钩子

i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md

@@ -23,10 +23,10 @@ aliases:
 
 本文档使用以下约定：
 
-- `[section].FOO_BAR` 或 `[section]FOO_BAR`: 一个位于 INI 文件 `[section]` 段中的配置项。
-- `FooBar`: 这是一个 Gitea 内部变量，不是一个配置项，仅用于描述相关逻辑。
-- `$FOO_BAR`: 这是一个环境变量，Gitea 可能会使用它的值，但是它不能直接用于配置文件中。
-- `{FOO_BAR}/something` 或 `{FooBar}/something`: 这个值会默认使用配置项 `FOO_BAR` 或者内部变量 `FooBar`。
+* `[section].FOO_BAR` 或 `[section]FOO_BAR`: 一个位于 INI 文件 `[section]` 段中的配置项。
+* `FooBar`: 这是一个 Gitea 内部变量，不是一个配置项，仅用于描述相关逻辑。
+* `$FOO_BAR`: 这是一个环境变量，Gitea 可能会使用它的值，但是它不能直接用于配置文件中。
+* `{FOO_BAR}/something` 或 `{FooBar}/something`: 这个值会默认使用配置项 `FOO_BAR` 或者内部变量 `FooBar`。
 
 **注意:** 修改完配置文件后，需要重启 Gitea 服务才能生效。
 
@@ -84,8 +84,13 @@ aliases:
 - `FORCE_PRIVATE`: **false**: 强制使每个新仓库变为私有。
 - `DEFAULT_PRIVATE`: **last**: 创建新仓库时默认为私有：`last`, `private`, `public`。
 - `DEFAULT_PUSH_CREATE_PRIVATE`: **true**: 使用推送创建新仓库时默认为私有。
-- `MAX_CREATION_LIMIT`: **-1**: 每个用户的全局仓库创建上限,
-  `-1` 代表无限制.
+- `MAX_CREATION_LIMIT`: **-1**: 每个用户/组织的全局仓库创建上限,
+  `-1` 代表无限制. 当 `USER_MAX_CREATION_LIMIT` 与 `ORG_MAX_CREATION_LIMIT`
+  未单独配置时, 这两项的默认值都会继承自此项.
+- `USER_MAX_CREATION_LIMIT`: **-1**: 每个用户的全局仓库创建上限, 在创建仓库时生效.
+  `-1` 代表无限制. 设置后优先级高于 `MAX_CREATION_LIMIT`.
+- `ORG_MAX_CREATION_LIMIT`: **-1**: 每个组织的全局仓库创建上限, 在创建仓库时生效.
+  `-1` 代表无限制. 设置后优先级高于 `MAX_CREATION_LIMIT`.
 - `PREFERRED_LICENSES`: **Apache License 2.0,MIT License**: 要放置在列表顶部的指定许可证。
   名称必须与 options/license 或 custom/options/license 中的文件名匹配。
 - `DISABLE_HTTP_GIT`: **false**: 禁用 HTTP 协议与仓库进行
@@ -113,6 +118,7 @@ aliases:
 - `ALLOW_DELETION_OF_UNADOPTED_REPOSITORIES`: **false**: 允许非管理员用户删除未被认领的仓库。
 - `DISABLE_DOWNLOAD_SOURCE_ARCHIVES`: **false**: 不允许从用户界面下载源代码存档文件。
 - `ALLOW_FORK_WITHOUT_MAXIMUM_LIMIT`: **true**: 允许无限制得派生仓库。
+- `ALLOW_FORK_INTO_SAME_OWNER`: **false**: 允许将仓库派生到同一所有者（用户或组织）中。此功能为实验性功能，尚未完全测试，将来可能会更改。
 
 ### 仓库 - 编辑器 (`repository.editor`)
 
@@ -134,7 +140,8 @@ aliases:
 - `DEFAULT_MERGE_MESSAGE_OFFICIAL_APPROVERS_ONLY`: **true**: 在默认合并消息中，仅包括官方允许审查的审批者。
 - `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: 在默认的 squash 合并消息中，包括构成拉取请求的所有提交的提交消息。
 - `ADD_CO_COMMITTER_TRAILERS`: **true**: 如果提交者与作者不匹配，在合并提交消息中添加`co-authored-by`和`co-committed-by`标记。
-- `TEST_CONFLICTING_PATCHES_WITH_GIT_APPLY`:使用三方合并方法测试`PR Patch`以发现是否存在冲突。如果此设置`true`，将使用`git apply`重新测试冲突的`PR Pathch` - 这是 1.18（和之前版本）中的先前行为，但效率相对较低。如果发现需要此设置，请报告。
+- `RETARGET_CHILDREN_ON_MERGE`: **true**: 当父合并请求被合并时，将子合并请求重新定向到父合并请求的目标分支。仅适用于头分支和基分支指向同一仓库的已合并合并请求。
+- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: 为新仓库设置"合并后默认删除合并请求分支"的默认值。
 
 ### 仓库 - 工单 (`repository.issue`)
 
@@ -153,6 +160,8 @@ aliases:
 
 - `ALLOWED_TYPES`: **_empty_**: 允许发布的文件类型列表，用逗号分隔 。如压缩包类型(`.zip`), mime 类型 (`text/plain`) ，也支持通配符 (`image/*`, `audio/*`, `video/*`)。 空值或者 `*/*` 代表允许所有类型。
 - `DEFAULT_PAGING_NUM`: **10**: 默认的发布版本页面分页大小
+- `FILE_MAX_SIZE`: **2048**: 版本发布附件的最大文件大小限制（MB）
+- `MAX_FILES`: **5**: 版本发布一次最多上传的附件数量。
 - 关于版本发布相关的附件设置，详见`附件`部分。
 
 ### 仓库 - Signing (`repository.signing`)
@@ -216,17 +225,24 @@ aliases:
 - `DEFAULT_THEME`: **gitea-auto**: 在 Gitea 安装时候设置的默认主题，自定义的主题可以通过 `{CustomPath}/public/assets/css/theme-*.css` 提供。
 - `SHOW_USER_EMAIL`: **true**: 用户的电子邮件是否应该显示在`Explore Users`页面中。
 - `THEMES`: **_empty_**: 所有可用的主题（由 `{CustomPath}/public/assets/css/theme-*.css` 提供）。允许用户选择个性化的主题，
+- `FILE_ICON_THEME`: **material**: 文件图标主题（basic/material）。
+- `FOLDER_ICON_THEME`: **basic**: 文件夹图标主题（basic/material）。
 - `MAX_DISPLAY_FILE_SIZE`: **8388608**: 能够显示文件的最大大小（默认为 8MiB）。
+- `AMBIGUOUS_UNICODE_DETECTION`: **true**: 检测文件内容中的歧义 Unicode 字符并在界面上显示警告。
 - `REACTIONS`: 用户可以在问题（Issue）、Pull Request（PR）以及评论中选择的所有可选的反应。
   这些值可以是表情符号别名（例如：:smile:）或 Unicode 表情符号。
   对于自定义的反应，在 public/assets/img/emoji/ 目录下添加一个紧密裁剪的正方形图像，文件名为 reaction_name.png。
+- `REACTION_MAX_USER_NUM`: **10**: 更改在反应工具提示中显示的用户数量（鼠标悬停时触发）。
 - `CUSTOM_EMOJIS`: **gitea, codeberg, gitlab, git, github, gogs**: 不在 utf8 标准中定义的额外表情符号。
   默认情况下，我们支持 Gitea 表情符号（:gitea:）。要添加更多表情符号，请将它们复制到 public/assets/img/emoji/ 目录下，
   并将其添加到此配置中。
+- `ENABLED_EMOJIS`: **_empty_**: 以逗号分隔的启用表情符号列表，例如："smile, thumbsup, thumbsdown"。留空以启用所有表情符号。
 - `DEFAULT_SHOW_FULL_NAME`: **false**: 是否在可能的情况下显示用户的全名。如果没有设置全名，则将使用用户名。
 - `SEARCH_REPO_DESCRIPTION`: **true**: 是否在探索页面上的仓库搜索中搜索描述。
 - `ONLY_SHOW_RELEVANT_REPOS`: **false** 在没有指定关键字并使用默认排序时，是否仅在探索页面上显示相关的仓库。
   如果一个仓库是分叉或者没有元数据（没有描述、图标、主题），则被视为不相关的仓库。
+- `EXPLORE_PAGING_DEFAULT_SORT`: **recentupdate**: 更改探索页面的排序类型。有效值为 "recentupdate"、"alphabetically"、"reverselastlogin"、"newest" 和 "oldest"。
+- `PREFERRED_TIMESTAMP_TENSE`: **mixed**: 所有时间戳应呈现的时态。可选值为 `absolute` 时间（即 1970-01-01, 11:59）和 `mixed`。`mixed` 表示大部分时间戳以相对时间显示（即 2 天前）。
 
 ### 界面 - 管理员 (`ui.admin`)
 
@@ -264,17 +280,21 @@ aliases:
 
 ## Markdown (`markdown`)
 
-- `ENABLE_HARD_LINE_BREAK_IN_COMMENTS`: **true**: 在评论中将软换行符呈现为硬换行符，
-  这意味着段落之间的单个换行符将导致换行，
-  并且不需要在段落后添加尾随空格来强制换行。
-- `ENABLE_HARD_LINE_BREAK_IN_DOCUMENTS`: **false**: 在文档中将软换行符呈现为硬换行符，
-  这意味着段落之间的单个换行符将导致换行，
-  并且不需要在段落后添加尾随空格来强制换行。
+- `RENDER_OPTIONS_COMMENT`: **short-issue-pattern, new-line-hard-break**: 自定义不同上下文的渲染选项。
+  设置为 "none" 以禁用默认值，或使用逗号分隔的列表：
+  - short-issue-pattern: 识别 "#123" 工单引用并将其渲染为指向工单的链接
+  - new-line-hard-break: 将软换行符渲染为硬换行符，这意味着段落之间的单个换行符将导致换行，
+    并且不需要在段落后添加尾随空格来强制换行。
+- `RENDER_OPTIONS_WIKI`: **short-issue-pattern**: 参见 RENDER_OPTIONS_COMMENT
+- `RENDER_OPTIONS_REPO_FILE`: **_empty_**: 参见 RENDER_OPTIONS_COMMENT
 - `CUSTOM_URL_SCHEMES`: 使用逗号分隔的列表（ftp、git、svn）来指示要在 Markdown 中呈现的附加 URL 超链接。
   以 http 和 https 开头的 URL 始终显示。
   如果此条目为空，则允许所有 URL 方案。
 - `FILE_EXTENSIONS`: **.md,.markdown,.mdown,.mkd,.livemd**: 应呈现/编辑为 Markdown 的文件扩展名列表。使用逗号分隔扩展名。要将没有任何扩展名的文件呈现为 Markdown，请只需放置一个逗号。
 - `ENABLE_MATH`: **true**: 启用对`\(...\)`, `\[...\]`, `$...$`和`$$...$$` 作为数学块的检测。
+- `MATH_CODE_BLOCK_DETECTION`: **inline-dollar,block-dollar**: 启用数学代码块检测的分隔符。
+  设置为 "none" 以禁用全部，或使用逗号分隔的列表：inline-dollar, inline-parentheses, block-dollar, block-square-brackets。
+  默认值遵循 GitHub 的行为。
 
 ## 服务器 (`server`)
 
@@ -292,6 +312,7 @@ aliases:
    虽然它的默认值是 "legacy"（避免影响老的用户），大多数实例都应当使用 "auto" 行为，尤其是 Gitea 实例需要在容器网络中被访问的场景。
    - "legacy": 当 "X-Forwarded-Proto" 请求头存在的时候，使用 "Host" 请求头生成公共 URL，否则使用 "ROOT_URL"。
    - "auto": 总是使用 "Host" 请求头生成公共 URL，如果 "X-Forwarded-Proto" 请求头存在也会使用它。如果没有 "Host" 请求头则使用 "ROOT_URL"。
+   - "never": 总是使用 "ROOT_URL" 生成公共 URL，不从请求头进行检测。
 - `STATIC_URL_PREFIX`: **_empty_**:
   覆盖此选项以从不同的 URL 请求静态资源。
   这包括 CSS 文件、图片、JS 文件和 Web 字体。
@@ -364,12 +385,14 @@ aliases:
 - `PPROF_DATA_PATH`: **_`AppWorkPath`_/data/tmp/pprof**: `PPROF_DATA_PATH`，当您将 Gitea 作为服务启动时，请使用绝对路径。
 - `LANDING_PAGE`: **home**: 未经身份验证用户的登录页面 \[home, explore, organizations, login, **custom**]。其中 custom 可以是任何 URL，例如 "/org/repo" 或甚至是 `https://anotherwebsite.com`。
 - `LFS_START_SERVER`: **false**: 启用 Git LFS 支持。
+- `LFS_ALLOW_PURE_SSH`: **false**: 启用 Git LFS 纯 SSH 协议支持。当前默认禁用，参见 [Git LFS 支持](administration/git-lfs-support.md)。
 - `LFS_CONTENT_PATH`: **`{APP_DATA_PATH}/lfs`**: 默认的 LFS 内容路径（如果它在本地存储中）。**已弃用**，请使用 `[lfs]` 中的设置。
 - `LFS_JWT_SECRET`: **_empty_**: LFS 身份验证密钥，将其更改为唯一的字符串。你可以通过 Gitea 子命令来生成此字符串。转到 [Command Line](administration/command-line.md#generate)。
 - `LFS_JWT_SECRET_URI`: **_empty_**: 代替在配置中定义 LFS_JWT_SECRET，可以使用此配置选项为 Gitea 提供包含密钥的文件的路径（示例值：`file:/etc/gitea/lfs_jwt_secret`）。
 - `LFS_HTTP_AUTH_EXPIRY`: **24h**: LFS 身份验证的有效期，以 time.Duration 表示，超过此期限的推送可能会失败。
 - `LFS_MAX_FILE_SIZE`: **0**: 允许的最大 LFS 文件大小（以字节为单位，设置为 0 为无限制）。
 - `LFS_LOCKS_PAGING_NUM`: **50**: 每页返回的最大 LFS 锁定数。
+- `LFS_MAX_BATCH_SIZE`: **0**: 客户端可通过 LFS 批量 API 请求的最大 LFS 指针数量。零为默认行为，允许任意大小的批量请求。
 - `REDIRECT_OTHER_PORT`: **false**: 如果为 true 并且 `PROTOCOL` 为 https，则允许将 http 请求重定向到 Gitea 监听的 https 端口的 `PORT_TO_REDIRECT`。
 - `REDIRECTOR_USE_PROXY_PROTOCOL`: **`{USE_PROXY_PROTOCOL}`**: 在连接到 https 重定向器时，需要 PROXY 协议头。
 - `PORT_TO_REDIRECT`: **80**: http 重定向服务监听的端口。当 `REDIRECT_OTHER_PORT` 为 true 时使用。
@@ -426,6 +449,7 @@ aliases:
 - `NAME`: **gitea**: 数据库名称。
 - `USER`: **root**: 数据库用户名。
 - `PASSWD`: **_empty_**: 数据库密码。如果密码包含特殊字符，请使用 \`your password\` 或 """your password"""。
+- `CHARSET_COLLATION`: **_empty_**:（仅限 MySQL/MSSQL）Gitea 期望使用区分大小写的排序规则。留空以使用 Gitea 决定的默认排序规则。除非您明确知道需要什么，否则不要更改它。
 - `SCHEMA`: **_empty_**: 对于 PostgreSQL，如果与 "public" 不同的模式。模式必须事先存在，用户必须对其具有创建特权，并且用户搜索路径必须设置为首先查找模式（例如 `ALTER USER user SET SEARCH_PATH = schema_name,"$user",public;`）。
 - `SSL_MODE`: **disable**: MySQL 或 PostgreSQL 数据库是否启用 SSL 模式，仅适用于 MySQL 和 PostgreSQL。
   - MySQL 的有效值：
@@ -450,19 +474,20 @@ aliases:
 - `MAX_IDLE_CONNS`：**2**: 连接池上的最大空闲数据库连接数，默认为 2 - 这将限制为 `MAX_OPEN_CONNS`。
 - `CONN_MAX_LIFETIME`：**0 或 3s**: 设置 DB 连接可以重用的最长时间 - 默认为 0，表示没有限制（除了 MySQL，其中为 3s - 请参见 #6804 和 #7071）。
 - `AUTO_MIGRATION`：**true**: 是否自动执行数据库模型迁移。
+- `SLOW_QUERY_THRESHOLD` **5s**: 超过此秒数阈值的查询执行时间将在 xorm 日志中记录为警告。
 
 请参见 #8540 和 #8273 以获取有关 `MAX_OPEN_CONNS`、`MAX_IDLE_CONNS` 和 `CONN_MAX_LIFETIME` 的适当值及其与端口耗尽的关系的进一步讨论。
 
 ## 索引 (`indexer`)
 
-- `ISSUE_INDEXER_TYPE`: **bleve**: 工单索引类型，当前支持：`bleve`、`db`、`elasticsearch` 或 `meilisearch`。
+- `ISSUE_INDEXER_TYPE`: **bleve**: 工单索引类型，当前支持：`bleve`、`db`、`elasticsearch`（也兼容 OpenSearch）或 `meilisearch`。
 - `ISSUE_INDEXER_CONN_STR`：\*\*\*\* : 工单索引连接字符串，仅适用于 elasticsearch 和 meilisearch（例如：`http://elastic:password@localhost:9200`）或者（例如：`http://:apikey@localhost:7700`）。
 - `ISSUE_INDEXER_NAME`：**gitea_issues**: 工单索引器名称，在 ISSUE_INDEXER_TYPE 为 elasticsearch 或 meilisearch 时可用。
 - `ISSUE_INDEXER_PATH`：**indexers/issues.bleve**: 用于工单搜索的索引文件；在 ISSUE*INDEXER_TYPE 为 bleve 和 elasticsearch 时可用。相对路径将相对于 *`AppWorkPath`\_ 进行绝对路径化。
 
 - `REPO_INDEXER_ENABLED`：**false**: 启用代码搜索（占用大量磁盘空间，约为存储库大小的 6 倍）。
 - `REPO_INDEXER_REPO_TYPES`：**sources,forks,mirrors,templates**: 存储库索引器单元。要索引的项目可以是 `sources`、`forks`、`mirrors`、`templates` 或它们的任何组合，用逗号分隔。如果为空，则默认为仅 `sources`，如果要完全禁用，请参见 `REPO_INDEXER_ENABLED`。
-- `REPO_INDEXER_TYPE`：**bleve**: 代码搜索引擎类型，可以为 `bleve` 或者 `elasticsearch`。
+- `REPO_INDEXER_TYPE`：**bleve**: 代码搜索引擎类型，可以为 `bleve` 或者 `elasticsearch`（也兼容 OpenSearch）。
 - `REPO_INDEXER_PATH`：**indexers/repos.bleve**: 用于代码搜索的索引文件。
 - `REPO_INDEXER_CONN_STR`：\*\*\*\*: 代码索引器连接字符串，在 `REPO_INDEXER_TYPE` 为 elasticsearch 时可用。例如：`http://elastic:password@localhost:9200`
 - `REPO_INDEXER_NAME`：**gitea_codes**: 代码索引器名称，在 `REPO_INDEXER_TYPE` 为 elasticsearch 时可用。
@@ -510,6 +535,14 @@ Gitea 创建以下非唯一队列：
   - `deletion`: 用户不能通过界面或者 API 删除他自己。
   - `manage_ssh_keys`: 用户不能通过界面或者 API 配置 SSH Keys。
   - `manage_gpg_keys`: 用户不能配置 GPG 密钥。
+- `EXTERNAL_USER_DISABLE_FEATURES`：**_empty_**：仅在用户使用外部登录方式（例如 LDAP、OAuth 等）时禁用的功能列表，以逗号分隔，可选值为 `deletion`、`manage_ssh_keys`、`manage_gpg_keys`、`manage_mfa`、`manage_credentials`。此设置独立于 `USER_DISABLED_FEATURES`，并作为其行为的补充。
+  - `deletion`：用户不能删除自己的帐户。
+  - `manage_ssh_keys`：用户不能配置 SSH 密钥。
+  - `manage_gpg_keys`：用户不能配置 GPG 密钥。
+  - `manage_mfa`：用户不能配置 MFA 设备。
+  - `manage_credentials`：用户不能配置邮箱、密码或 OpenID。
+  - `change_username`：用户不能更改其用户名。
+  - `change_full_name`：用户不能更改其全名。
 
 ## 安全性 (`security`)
 
@@ -518,6 +551,7 @@ Gitea 创建以下非唯一队列：
 - `SECRET_KEY_URI`: **_empty_**: 与定义 `SECRET_KEY` 不同，此选项可用于使用存储在文件中的密钥（示例值：`file:/etc/gitea/secret_key`）。它不应该像 `SECRET_KEY` 一样容易丢失。
 - `LOGIN_REMEMBER_DAYS`: **31**: 在要求重新登录之前，记住用户的登录状态多长时间（以天为单位）。
 - `COOKIE_REMEMBER_NAME`: **gitea_incredible**: 保存自动登录信息的 Cookie 名称。
+- `REVERSE_PROXY_LOGOUT_REDIRECT`: **_empty_**: 当使用反向代理或 SSO 进行身份认证时，用户登出后重定向到的 URL 或相对路径。例如：`/my-sso/logout?return=/my-sso/home`。
 - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: 反向代理认证的 HTTP 头部名称，用于提供用户信息。
 - `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: 反向代理认证的 HTTP 头部名称，用于提供邮箱信息。
 - `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: 反向代理认证的 HTTP 头部名称，用于提供全名信息。
@@ -561,6 +595,8 @@ Gitea 创建以下非唯一队列：
   - off - 不检查密码复杂性
 - `PASSWORD_CHECK_PWN`: **false**: 检查密码是否在 [HaveIBeenPwned](https://haveibeenpwned.com/Passwords) 中曝光。
 - `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: 缓存成功的令牌哈希。API 令牌在数据库中存储为 pbkdf2 哈希，但这意味着在存在多个 API 操作时可能会有显着的哈希负载。此缓存将在 LRU 缓存中存储成功的哈希令牌，以在性能和安全性之间保持平衡。
+- `DISABLE_QUERY_AUTH_TOKEN`: **false**: 拒绝通过 URL 查询字符串发送的 API 令牌（仅接受基于 Header 的 API 令牌）。此设置将在 Gitea 1.23 中默认为 `true`，并在 Gitea 1.24 中弃用。
+- `TWO_FACTOR_AUTH`：**_empty_**：设置为 enforced 以强制启用双因素认证。仅在 Gitea 1.24 及更高版本中可用。
 
 ## Camo (`camo`)
 
@@ -602,7 +638,10 @@ Gitea 创建以下非唯一队列：
 - `REQUIRE_SIGNIN_VIEW`: **false**: 启用此项以强制用户登录以查看任何页面或使用 API。
 - `ENABLE_NOTIFY_MAIL`: **false**: 启用此项以在发生某些情况（如创建问题）时向存储库的观察者发送电子邮件。需要启用`Mailer`。
 - `ENABLE_BASIC_AUTHENTICATION`: **true**: 禁用此项以禁止使用 HTTP BASIC 和用户的密码进行身份验证。请注意，如果禁用此项，您将无法使用密码访问令牌 API 端点。此外，这仅会禁用使用密码的 BASIC 身份验证，而不会禁用令牌或 OAuth Basic。
+- `ENABLE_PASSWORD_SIGNIN_FORM`：**true**：显示密码登录表单（用于基于密码的登录），否则仅显示已启用的 OAuth2 或 Passkey 登录方式。如果设置为 false，可能还需要将 `ENABLE_BASIC_AUTHENTICATION` 设置为 false 以完全禁用基于密码的身份验证。
+- `ENABLE_PASSKEY_AUTHENTICATION`：**true**：允许用户使用 Passkey 登录。
 - `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: 启用此项以允许反向代理身份验证。
+- `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`：**false**：启用此项以允许 API 请求的反向代理身份验证，反向代理负责确保不会发生 CSRF 攻击。
 - `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: 启用此项以允许反向身份验证的自动注册。
 - `ENABLE_REVERSE_PROXY_EMAIL`: **false**: 启用此项以允许使用提供的电子邮件而不是生成的电子邮件进行自动注册。
 - `ENABLE_REVERSE_PROXY_FULL_NAME`: **false**: 启用此项以允许使用提供的全名进行自动注册。
@@ -654,6 +693,13 @@ Gitea 创建以下非唯一队列：
 - `DISABLE_ORGANIZATIONS_PAGE`: **false**: 禁用组织探索页面。
 - `DISABLE_CODE_PAGE`: **false**: 禁用代码探索页面。
 
+### 请求服务质量（`qos`）
+
+- `ENABLED`: **false**: 启用请求服务质量和过载保护。
+- `MAX_INFLIGHT`: **（动态）**: 服务器在将新请求加入队列之前将处理的最大并发请求数。默认值为"CpuNum * 4"。
+- `MAX_WAITING`: **100**: 在新请求被丢弃之前可以加入队列的最大请求数。
+- `TARGET_WAIT_TIME`: **250ms**: 请求在队列中等待的目标最大时间。等待时间低于此值的请求不会被丢弃。当等待时间超过此值时，将丢弃部分请求，直到等待时间降低到此值以下。
+
 ## SSH Minimum Key Sizes (`ssh.minimum_key_sizes`)
 
 定义允许的算法及其最小密钥长度（使用-1 来禁用某个类型）：
@@ -710,6 +756,7 @@ Gitea 创建以下非唯一队列：
 - `HELO_HOSTNAME`: **（从系统检索）**: HELO 主机名。
 - `FROM`: **_empty_**: 邮件的发件人地址，符合 RFC 5322。这可以是一个电子邮件地址，也可以是 "Name" \<email@example.com\> 格式。
 - `ENVELOPE_FROM`: **_empty_**: 在 SMTP 邮件信封上设置的地址作为发件地址。设置为 `<>` 以发送一个空地址。
+- `FROM_DISPLAY_NAME_FORMAT`：**`{{ .DisplayName }}`**：当 Gitea 代表用户发送邮件时，将使用 WebUI 中显示的名称。如果您希望例如 `Mister X (by CodeIt) <gitea@codeit.net>`，请设置为 `{{ .DisplayName }} (by {{ .AppName }})`。可用变量：`.DisplayName`、`.AppName` 和 `.Domain`。
 - `SUBJECT_PREFIX`: **_empty_**: 放置在电子邮件主题行之前的前缀。
 - `SENDMAIL_PATH`: **sendmail**: 操作系统上 `sendmail` 的位置（可以是命令或完整路径）。
 - `SENDMAIL_ARGS`: **_empty_**: 指定任何额外的 sendmail 参数。（注意：您应该知道电子邮件地址可能看起来像选项 - 如果您的 `sendmail` 命令带有选项，您必须设置选项终止符 `--`）
@@ -717,6 +764,22 @@ Gitea 创建以下非唯一队列：
 - `SENDMAIL_CONVERT_CRLF`: **true**: 大多数版本的 sendmail 偏好使用 LF 换行符，而不是 CRLF 换行符。如果您的 sendmail 版本需要 CRLF 换行符，请将此设置为 false。
 - `SEND_BUFFER_LEN`: **100**: 邮件队列的缓冲区长度。**已弃用**，请在 `[queue.mailer]` 中使用 `LENGTH`。
 - `SEND_AS_PLAIN_TEXT`: **false**: 仅以纯文本形式发送邮件，不包括 HTML 备选方案。
+- `EMBED_ATTACHMENT_IMAGES`: **false**: 在 HTML 邮件中以 base64 格式嵌入附件图片。（适用于不加载外部图片的客户端或断开 VPN 连接仍接收邮件的用户；注意：gmail 等在线 Web 客户端不会显示 base64 嵌入的图片）
+
+## 覆盖邮件头（`mailer.override_header`）
+
+:::warning
+此项默认为空，仅在您明确知道需要时使用。
+:::
+
+示例如下：
+
+```ini
+[mailer.override_header]
+Reply-To = test@example.com, test2@example.com
+Content-Type = text/html; charset=utf-8
+In-Reply-To =
+```
 
 ## 入站邮件 (`email.incoming`)
 
@@ -796,19 +859,22 @@ Gitea 创建以下非唯一队列：
 - `ALLOWED_TYPES`: **.avif,.cpuprofile,.csv,.dmp,.docx,.fodg,.fodp,.fods,.fodt,.gif,.gz,.jpeg,.jpg,.json,.jsonc,.log,.md,.mov,.mp4,.odf,.odg,.odp,.ods,.odt,.patch,.pdf,.png,.pptx,.svg,.tgz,.txt,.webm,.webp,.xls,.xlsx,.zip**: 允许的文件扩展名（`.zip`）、mime 类型（`text/plain`）或通配符类型（`image/*`、`audio/*`、`video/*`）的逗号分隔列表。空值或 `*/*` 允许所有类型。
 - `MAX_SIZE`: **2048**: 附件的最大限制（MB）。
 - `MAX_FILES`: **5**: 一次最多上传的附件数量。
-- `STORAGE_TYPE`: **local**: 附件的存储类型，`local` 表示本地磁盘，`minio` 表示兼容 S3 的对象存储服务，如果未设置将使用默认值 `local` 或其他在 `[storage.xxx]` 中定义的名称。
-- `SERVE_DIRECT`: **false**: 允许存储驱动器重定向到经过身份验证的 URL 以直接提供文件。目前，只支持 Minio/S3 通过签名 URL 提供支持，local 不会执行任何操作。
-- `PATH`: **attachments**: 存储附件的路径，仅当 STORAGE_TYPE 为 `local` 时可用。如果是相对路径，将会被解析为 `{AppDataPath}/{attachment.PATH}`.
-- `MINIO_ENDPOINT`: **localhost:9000**: Minio 端点以连接，仅当 STORAGE_TYPE 为 `minio` 时可用。
-- `MINIO_ACCESS_KEY_ID`: Minio accessKeyID 以连接，仅当 STORAGE_TYPE 为 `minio` 时可用。
-- `MINIO_SECRET_ACCESS_KEY`: Minio secretAccessKey 以连接，仅当 STORAGE_TYPE 为 `minio` 时可用。
-- `MINIO_BUCKET`: **gitea**: Minio 存储附件的存储桶，仅当 STORAGE_TYPE 为 `minio` 时可用。
-- `MINIO_LOCATION`: **us-east-1**: Minio 存储桶的位置以创建，仅当 STORAGE_TYPE 为 `minio` 时可用。
-- `MINIO_BASE_PATH`: **attachments/**: Minio 存储桶上的基本路径，仅当 STORAGE_TYPE 为 `minio` 时可用。
-- `MINIO_USE_SSL`: **false**: Minio 启用 SSL，仅当 STORAGE_TYPE 为 `minio` 时可用。
-- `MINIO_INSECURE_SKIP_VERIFY`: **false**: Minio 跳过 SSL 验证，仅当 STORAGE_TYPE 为 `minio` 时可用。
-- `MINIO_CHECKSUM_ALGORITHM`: **default**: Minio 校验算法：`default`（适用于 MinIO 或 AWS S3）或 `md5`（适用于 Cloudflare 或 Backblaze）
-- `MINIO_BUCKET_LOOKUP_TYPE`: **auto**: Minio 的 bucket 查找方式默认为`auto`模式，可将其设置为`dns`（虚拟托管样式）或`path`（路径样式），仅当`STORAGE_TYPE`为`minio`时可用。
+- `STORAGE_TYPE`: **local**: 附件的存储类型，可以为空、`local`、`minio`、`azureblob` 或在 `[storage.xxx]` 中定义的其他名称。
+
+  当 `STORAGE_TYPE` 为空或未配置此项时，所有存储将从 `[storage]`（如已配置）或默认值派生。
+
+  当 `STORAGE_TYPE = local` 时，以下为可用配置项
+
+  - `PATH`: **attachments**: 存储附件的路径，仅当 STORAGE_TYPE 为 `local` 时可用。如果是相对路径，将会被解析为 `{AppDataPath}/{attachment.PATH}`。
+
+  当 `STORAGE_TYPE = minio` 时，相关配置详见 [Minio 存储配置](#storage_minio)，您也可以如下定义配置来覆盖派生的或默认的值。
+
+  - `MINIO_BASE_PATH`: **attachments/**: Minio 存储桶上的基本路径，仅当 STORAGE_TYPE 为 `minio` 时可用。
+
+  当 `STORAGE_TYPE = xxx` 时，配置将从 `[storage.xxx]` 派生，以下配置项可被覆盖。
+
+  - `PATH`: 同上
+  - `MINIO_BASE_PATH`: 同上
 
 ## 日志 (`log`)
 
@@ -886,25 +952,34 @@ Gitea 创建以下非唯一队列：
 
 - `ENABLED`: **true**: 是否启用该定时任务。
 - `RUN_AT_START`: **true**: 设置在服务启动时运行。
+- `NOTICE_ON_SUCCESS`: **false**: 是否在成功执行时也发出通知。
 - `SCHEDULE`: **@midnight**: 使用 Cron 语法的定时任务触发配置，例如 `@every 1h`。
 - `OLDER_THAN`: **24h**: 超过`OLDER_THAN`时间的存档将被删除，例如 `12h`。
 
 #### 定时任务 - 更新镜像仓库 (`cron.update_mirrors`)
 
+- `ENABLED`: **true**: 启用定期运行更新镜像任务。
 - `SCHEDULE`: **@every 10m**: 使用 Cron 语法的定时任务触发配置，例如 `@every 3h`。
+- `RUN_AT_START`: **false**: 在 Gitea 启动时运行更新镜像任务。
+- `NOTICE_ON_SUCCESS`: **false**: 是否在成功时发出通知。
 - `PULL_LIMIT`: **50**: 将要添加到队列的镜像数量限制为此数字（负值表示无限制，0 将导致不会将镜像加入队列，从而有效地禁用镜像更新）。
 - `PUSH_LIMIT`: **50**: 将要添加到队列的镜像数量限制为此数字（负值表示无限制，0 将导致不会将镜像加入队列，从而有效地禁用镜像更新）。
 
 #### 定时任务 - 健康检查所有仓库 (`cron.repo_health_check`)
 
+- `ENABLED`: **true**: 启用定期运行仓库健康检查任务。
 - `SCHEDULE`: **@midnight**: Cron 语法，用于安排仓库健康检查。
+- `RUN_AT_START`: **false**: 在 Gitea 启动时运行仓库健康检查任务。
+- `NOTICE_ON_SUCCESS`: **false**: 是否在成功时发出通知。
 - `TIMEOUT`: **60s**: 用于健康检查执行超时的时间持续语法。
 - `ARGS`: **_empty_**: `git fsck` 命令的参数，例如 `--unreachable --tags`。在 http://git-scm.com/docs/git-fsck 上了解更多。
 
 #### 定时任务 - 检查所有仓库统计 (`cron.check_repo_stats`)
 
-- `RUN_AT_START`: **true**: 在启动时运行仓库统计检查。
 - `SCHEDULE`: **@midnight**: Cron 语法，用于安排仓库统计检查。
+- `ENABLED`: **true**: 启用定期运行仓库统计检查任务。
+- `RUN_AT_START`: **true**: 在启动时运行仓库统计检查。
+- `NOTICE_ON_SUCCESS`: **false**: 是否在成功时发出通知。
 
 #### 定时任务 - 清理 hook_task 表 (`cron.cleanup_hook_task_table`)
 
@@ -925,15 +1000,49 @@ Gitea 创建以下非唯一队列：
 
 #### Cron - 更新迁移海报 ID (`cron.update_migration_poster_id`)
 
+- `ENABLED`: **true**: 启用更新迁移海报 ID 任务。
+- `RUN_AT_START`: **true**: 在启动服务器时更新迁移仓库的工单和评论的海报 ID。
+- `NOTICE_ON_SUCCESS`: **false**: 是否在成功时发出通知。
 - `SCHEDULE`: **@midnight** : 同步之间的间隔作为持续时间，每次实例启动时都会尝试同步。
 
 #### Cron - 同步外部用户 (`cron.sync_external_users`)
 
+- `ENABLED`: **true**: 启用同步外部用户数据任务。
+- `RUN_AT_START`: **false**: 在启动服务器时同步外部用户数据。
+- `NOTICE_ON_SUCCESS`: **false**: 是否在成功时发出通知。
 - `SCHEDULE`: **@midnight** : 同步之间的间隔作为持续时间，每次实例启动时都会尝试同步。
 - `UPDATE_EXISTING`: **true**: 创建新用户，更新现有用户数据，并禁用不再在外部源中的用户（默认设置）或仅在 UPDATE_EXISTING 设置为 false 时创建新用户。
 
+#### Cron - 清理过期的 Actions 资源 (`cron.cleanup_actions`)
+
+- `ENABLED`: **true**: 启用清理过期 Actions 资源的任务。
+- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
+- `SCHEDULE`: **@midnight**: Cron 语法，用于任务调度。
+
+#### Cron - 清理已删除的分支 (`cron.deleted_branches_cleanup`)
+
+- `ENABLED`: **true**: 启用已删除分支清理。
+- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以记录成功消息。
+- `SCHEDULE`: **@midnight**: Cron 语法，用于安排已删除分支清理。
+- `OLDER_THAN`: **24h**: 删除超过 OLDER_THAN 时间的已删除分支。
+
+#### Cron - 同步仓库许可证 (`cron.sync_repo_licenses`)
+
+- `ENABLED`: **false**: 启用仓库许可证同步。
+- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以记录成功消息。
+- `SCHEDULE`: **@annually*: Cron 语法，用于安排仓库许可证同步。
+
 ### 扩展的定时任务（默认未启用）
 
+#### Cron - 删除所有仓库存档 (`cron.delete_repo_archives`)
+
+- `ENABLED`: **false**: 启用服务。
+- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
+- `SCHEDULE`: **@annually**: Cron 语法，用于删除所有仓库存档，例如 `@annually`。
+
 #### Cron - 垃圾收集所有仓库 (`cron.git_gc_repos`)
 
 - `ENABLED`: **false**: 启用服务。
@@ -950,6 +1059,13 @@ Gitea 创建以下非唯一队列：
 - `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
 - `SCHEDULE`: **@every 72h**: Cron 语法，用于安排仓库存档清理，例如 `@every 1h`。
 
+#### Cron - 更新 '.ssh/authorized_principals' 文件 (`cron.resync_all_sshprincipals`)
+
+- `ENABLED`: **false**: 启用服务。
+- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
+- `NOTICE_ON_SUCCESS`: **false**: 设置为 true 以打开成功通知。
+- `SCHEDULE`: **@every 72h**: Cron 语法，用于安排 authorized_principals 更新，例如 `@every 1h`。
+
 #### Cron - 重新同步所有仓库的 pre-receive、update 和 post-receive 钩子 (`cron.resync_all_hooks`)
 
 - `ENABLED`: **false**: 启用服务。
@@ -986,6 +1102,14 @@ Gitea 创建以下非唯一队列：
 - `SCHEDULE`: **@every 168h**: Cron 语法，用于设置多长时间进行检查。
 - `OLDER_THAN`: **8760h**: 早于此表达式的任何操作都将从数据库中删除，建议使用 `8760h`（1 年），因为这是热力图的最大长度。
 
+#### Cron - 检查 Gitea 新版本 (`cron.update_checker`)
+
+- `ENABLED`: **true**: 启用服务。
+- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
+- `ENABLE_SUCCESS_NOTICE`: **true**: 设置为 false 以关闭成功通知。
+- `SCHEDULE`: **@every 168h**: Cron 语法，用于安排任务，例如 `@every 168h`。
+- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: Gitea 用于检查新版本的端点。
+
 #### Cron - 从数据库中删除所有旧的系统通知 (`cron.delete_old_system_notices`)
 
 - `ENABLED`: **false**: 启用服务。
@@ -1002,6 +1126,44 @@ Gitea 创建以下非唯一队列：
 - `OLDER_THAN`: **168h**: 只会尝试回收早于此时间（默认 7 天）的 LFSMetaObject。
 - `LAST_UPDATED_MORE_THAN_AGO`: **72h**: 只会尝试回收超过此时间（默认 3 天）没有尝试过回收的 LFSMetaObject。
 - `NUMBER_TO_CHECK_PER_REPO`: **100**: 每个仓库要检查的过期 LFSMetaObject 的最小数量。设置为 `0` 以始终检查所有。
+- `PROPORTION_TO_CHECK_PER_REPO`: **0.6**: 每个仓库至少检查此比例的 LFSMetaObject。（这可能导致检查所有过期的 LFSMetaObject。）
+
+### Actions 定时任务
+
+#### Cron - 重建工单索引 (`cron.rebuild_issue_indexer`)
+
+- `ENABLED`: **true**: 启用服务。
+- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
+- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `SCHEDULE`: **@annually**: Cron 语法，用于设置重建索引的频率。
+
+#### Cron - 停止长时间未更新的运行中任务 (`cron.stop_zombie_tasks`)
+
+- `ENABLED`: **true**: 启用服务。
+- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
+- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `SCHEDULE`: **@every 5m**: Cron 语法，用于设置检查的频率。
+
+#### Cron - 停止持续更新但长时间未结束的运行中任务 (`cron.stop_endless_tasks`)
+
+- `ENABLED`: **true**: 启用服务。
+- `RUN_AT_START`: **true**: 在启动时运行任务（如果启用）。
+- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `SCHEDULE`: **@every 30m**: Cron 语法，用于设置检查的频率。
+
+#### Cron - 取消长时间未被领取的任务 (`cron.cancel_abandoned_jobs`)
+
+- `ENABLED`: **true**: 启用服务。
+- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
+- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `SCHEDULE`: **@every 6h**: Cron 语法，用于设置检查的频率。
+
+#### Cron - 启动基于定时的 Actions (`cron.start_schedule_tasks`)
+
+- `ENABLED`: **true**: 启用服务。
+- `RUN_AT_START`: **false**: 在启动时运行任务（如果启用）。
+- `NO_SUCCESS_NOTICE`: **false**: 设置为 true 以关闭成功通知。
+- `SCHEDULE`: **@every 1m**: Cron 语法，用于设置调度任务的频率。
 
 ## Git (`git`)
 
@@ -1023,14 +1185,12 @@ Gitea 创建以下非唯一队列：
 - `LARGE_OBJECT_THRESHOLD`: **1048576**: （仅限于 Go-Git），不要在内存中缓存大于此大小的对象。（设置为 0 以禁用。）
 - `DISABLE_CORE_PROTECT_NTFS`: **false** 将`core.protectNTFS`强制设置为 false。
 - `DISABLE_PARTIAL_CLONE`: **false** 禁用使用部分克隆进行 git。
+- `DIFF_RENAME_SIMILARITY_THRESHOLD`：**50%** 设置通过 `--find-renames=<threshold>` 传递给 git 命令的相似度阈值。默认值为 50%，与 git 相同。必须是 0% 到 100% 之间的整数百分比。
 
 ### Git - 超时设置 (`git.timeout`)
 
-- `DEFAULT`: **360**: Git 操作的默认超时时间，单位秒
 - `MIGRATE`: **600**: 在迁移外部存储库时的超时时间，单位秒
 - `MIRROR`: **300**: 在镜像外部存储库时的超时时间，单位秒
-- `CLONE`: **300**: 在存储库之间进行内部克隆的超时时间，单位秒
-- `PULL`: **300**: 在存储库之间进行内部拉取的超时时间，单位秒
 - `GC`: **60**: git 存储库 GC 的超时时间，单位秒
 
 ### Git - 配置选项 (`git.config`)
@@ -1080,9 +1240,11 @@ Gitea 创建以下非唯一队列：
 
 ## Markup (`markup`)
 
-- `MERMAID_MAX_SOURCE_CHARACTERS`: **5000**: 设置 Mermaid 源的最大大小。(设为-1 代表禁止)
+- `MERMAID_MAX_SOURCE_CHARACTERS`: **50000**: 设置 Mermaid 源的最大大小。(设为-1 代表禁止)
 
-gitea 支持外部渲染工具，你可以配置你熟悉的文档渲染工具. 比如一下将新增一个名字为 asciidoc 的渲染工具。
+## Markup 外部渲染（`markup.external-render-name`）
+
+Gitea 支持使用外部工具进行 Markup 渲染。以下示例将新增一个名为 `asciidoc` 的 Markup 渲染器。
 
 ```ini
 [markup.asciidoc]
@@ -1093,15 +1255,18 @@ RENDER_COMMAND = "asciidoctor --embedded --safe-mode=secure --out-file=- -"
 IS_INPUT_FILE = false
 ```
 
-- ENABLED：**false** 设置是否启动渲染器
-- NEED_POSTPROCESS：**true** 设置为**true**以替换链接/SHA1 等。
-- FILE*EXTENSIONS：\*\*\_empty*\*\* 要由外部命令渲染的文件扩展名列表。多个扩展名需要用逗号分隔。
-- RENDER_COMMAND：用于渲染所有匹配的扩展名的外部命令。
-- IS_INPUT_FILE：**false** 输入不是标准输入，而是一个在`RENDER_COMMAND`之后带有文件参数的文件。
+- ENABLED：**false** 启用 Markup 支持；设置为 **true** 以启用此渲染器。
+- FILE\_EXTENSIONS：**_empty_** 要由外部命令渲染的文件扩展名列表。多个扩展名需要用逗号分隔。
+- RENDER\_COMMAND：用于渲染所有匹配的扩展名的外部命令。
+- IS\_INPUT\_FILE：**false** 输入不是标准输入，而是一个在 `RENDER_COMMAND` 之后带有文件参数的文件。
 - RENDER_CONTENT_MODE：**sanitized** 内容将如何呈现。
-  - sanitized：对内容进行清理，并在当前页面内呈现，默认仅允许一些 HTML 标签和属性。可以在`[markup.sanitizer.*]`中定义自定义的清理规则。
+  - sanitized：对内容进行清理，并在当前页面内呈现，默认仅允许一些 HTML 标签和属性。可以在 `[markup.sanitizer.*]` 中定义自定义的清理规则。
   - no-sanitizer：禁用清理程序，在当前页面内呈现内容。这是**不安全**的，如果内容包含恶意代码，可能会导致 XSS 攻击。
   - iframe：在单独的独立页面中呈现内容，并通过 iframe 嵌入到当前页面中。iframe 处于禁用同源策略的沙箱模式，并且 JS 代码与父页面安全隔离。
+- RENDER_CONTENT_SANDBOX：**_empty_** 当 RENDER_CONTENT_MODE 为 `iframe` 时应用于 iframe 和 Content-Security-Policy 头的沙箱设置。默认为一组安全的"allow-*"限制（空格分隔）。您也可以根据需要设置或使用"disabled"完全禁用沙箱。设置时请确保没有安全风险：
+    - 仅 PDF 内容：通常可以安全使用"disabled"，并且需要设置为"disabled"，因为 PDF 仅在无沙箱时渲染。
+    - 包含 JS 的 HTML 内容：如果"RENDER_COMMAND"能保证不存在 XSS，则是安全的，否则需要微调"allow-*"限制。
+- NEED_POST_PROCESS：**false** 是否对渲染后的 HTML 内容进行后处理，包括：解析相对链接和图片源、识别 issue/commit 引用、转义不可见字符、提及用户、渲染永久链接代码块、替换 emoji 短代码等。当 RENDER_CONTENT_MODE 为 `sanitized` 时默认为 true，否则为 false。
 
 两个特殊的环境变量会传递给渲染命令：
 
@@ -1189,6 +1354,7 @@ ALLOW_DATA_URI_IMAGES = true
 - `LIMIT_SIZE_RUBYGEMS`：**-1**: RubyGems 上传的最大大小（`-1` 表示无限制，格式为 `1000`、`1 MB`、`1 GiB`）。
 - `LIMIT_SIZE_SWIFT`：**-1**: Swift 上传的最大大小（`-1` 表示无限制，格式为 `1000`、`1 MB`、`1 GiB`）。
 - `LIMIT_SIZE_VAGRANT`：**-1**: Vagrant 上传的最大大小（`-1` 表示无限制，格式为 `1000`、`1 MB`、`1 GiB`）。
+- `LIMIT_SIZE_TERRAFORM_STATE`：**-1**：Terraform state 上传的最大大小（`-1` 表示无限制，格式为 `1000`、`1 MB`、`1 GiB`）。
 
 ## 镜像（`mirror`）
 
@@ -1203,50 +1369,67 @@ ALLOW_DATA_URI_IMAGES = true
 用于 lfs 数据的存储配置。当将 `STORAGE_TYPE` 设置为 `xxx` 时，它将从默认的 `[storage]` 或 `[storage.xxx]` 派生。
 当派生时，`PATH` 的默认值是 `data/lfs`，`MINIO_BASE_PATH` 的默认值是 `lfs/`。
 
-- `STORAGE_TYPE`：**local**: lfs 的存储类型，`local` 表示本地磁盘，`minio` 表示 S3 兼容对象存储服务，或者使用 `[storage.xxx]` 中定义的其他名称。
-- `SERVE_DIRECT`：**false**: 允许存储驱动程序重定向到经过身份验证的 URL 以直接提供文件。目前，仅支持通过签名的 URL 提供 Minio/S3，本地不执行任何操作。
+- `STORAGE_TYPE`：**local**: lfs 的存储类型，可以为空、`local`、`minio`、`azureblob` 或在 `[storage.xxx]` 中定义的其他名称。
+
+  当 `STORAGE_TYPE` 为空或未配置此项时，所有存储将从 `[storage]`（如已配置）或默认值派生。
+
+  当 `STORAGE_TYPE = local` 时，以下为可用配置项
+
 - `PATH`：**./data/lfs**: 存储 LFS 文件的位置，仅在 `STORAGE_TYPE` 为 `local` 时可用。如果未设置，则回退到 `[server]` 部分中已弃用的 `LFS_CONTENT_PATH` 值。
-- `MINIO_ENDPOINT`：**localhost:9000**: 连接的 Minio 终端点，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
-- `MINIO_ACCESS_KEY_ID`：Minio 的 accessKeyID，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
-- `MINIO_SECRET_ACCESS_KEY`：Minio 的 secretAccessKey，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
-- `MINIO_BUCKET`：**gitea**: 用于存储 lfs 的 Minio 桶，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
-- `MINIO_LOCATION`：**us-east-1**: 创建桶的 Minio 位置，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
-- `MINIO_BASE_PATH`：**lfs/**: 桶上的 Minio 基本路径，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
-- `MINIO_USE_SSL`：**false**: Minio 启用 ssl，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
-- `MINIO_INSECURE_SKIP_VERIFY`：**false**: Minio 跳过 SSL 验证，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
-- `MINIO_BUCKET_LOOKUP_TYPE`: **auto**: Minio 的 bucket 查找方式默认为`auto`模式，可将其设置为`dns`（虚拟托管样式）或`path`（路径样式），仅当`STORAGE_TYPE`为`minio`时可用。
+
+  当 `STORAGE_TYPE = minio` 时，相关配置详见 [Minio 存储配置](#storage_minio)，您也可以如下定义配置来覆盖派生的或默认的值。
+
+  - `MINIO_BASE_PATH`：**attachments/**: 桶上的 Minio 基本路径，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
+
+  当 `STORAGE_TYPE = xxx` 时，配置将从 `[storage.xxx]` 派生，以下配置项可被覆盖。
+
+- `PATH`：同上
+- `MINIO_BASE_PATH`：同上
+
+## LFS 客户端（`lfs_client`）
+
+- `BATCH_SIZE`: **20**: 上游镜像每次批量 API 请求的 LFS 指针数量。
+- `BATCH_OPERATION_CONCURRENCY`: **8**: 批量操作中并发上传/下载的数量。
 
 ## 存储 (`storage`)
 
-默认的附件、lfs、头像、仓库头像、仓库归档、软件包、操作日志、artifacts 的存储配置。推荐仅仅配置此 section 并让其它的 section 从此配置项继承。
+`attachments`、`lfs`、`avatars`、`repo-avatars`、`repo-archive`、`packages`、`actions_log`、`actions_artifact` 的默认存储配置。推荐仅配置此部分并让其他部分从此配置继承，前提是所有存储都位于同一父目录或 Minio 桶下。
+
+- `STORAGE_TYPE`：**local**: 存储类型，`local` 表示本地磁盘，`minio` 表示 S3 兼容对象存储服务，`azureblob` 表示 Azure Blob 存储服务。
+
+### Minio 存储配置（`storage_minio`）
 
-- `STORAGE_TYPE`：**local**: 存储类型，`local` 表示本地磁盘，`minio` 表示 S3，`azureblob` 表示 azure 对象存储。
 - `SERVE_DIRECT`：**false**: 允许存储驱动程序重定向到经过身份验证的 URL 以直接提供文件。目前，仅支持通过签名的 URL 提供 Minio/S3，本地不执行任何操作。
-- `MINIO_ENDPOINT`：**localhost:9000**: 连接的 Minio 终端点，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
-- `MINIO_ACCESS_KEY_ID`：Minio 的 accessKeyID，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
+- `MINIO_ENDPOINT`：**localhost:9000**: Minio 连接终端点，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
+- `MINIO_ACCESS_KEY_ID`：Minio 的 accessKeyID，仅在 `STORAGE_TYPE` 为 `minio` 时可用。如果未提供且 `STORAGE_TYPE` 为 `minio`，将在已知的环境变量（MINIO_ACCESS_KEY_ID、AWS_ACCESS_KEY_ID）、凭据文件（~/.mc/config.json、~/.aws/credentials）以及 EC2 实例元数据中搜索凭据。
 - `MINIO_SECRET_ACCESS_KEY`：Minio 的 secretAccessKey，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
+- `MINIO_IAM_ENDPOINT`：用于覆盖 Minio 默认 IAM 终端点解析的首选 IAM 终端点，仅在 `STORAGE_TYPE` 为 `minio` 时可用。如果未提供且 `STORAGE_TYPE` 为 `minio`，将从已知的环境变量（AWS_CONTAINER_AUTHORIZATION_TOKEN、AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE、AWS_CONTAINER_CREDENTIALS_RELATIVE_URI、AWS_CONTAINER_CREDENTIALS_FULL_URI、AWS_WEB_IDENTITY_TOKEN_FILE、AWS_ROLE_ARN、AWS_ROLE_SESSION_NAME、AWS_REGION）中搜索和派生终端点，如果未另行提供则使用 DefaultIAMRoleEndpoint。
 - `MINIO_BUCKET`：**gitea**: 用于存储数据的 Minio 桶，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
 - `MINIO_LOCATION`：**us-east-1**: 创建桶的 Minio 位置，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
-- `MINIO_USE_SSL`：**false**: Minio 启用 ssl，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
+- `MINIO_USE_SSL`：**false**: Minio 启用 SSL，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
 - `MINIO_INSECURE_SKIP_VERIFY`：**false**: Minio 跳过 SSL 验证，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
-- `MINIO_BUCKET_LOOKUP_TYPE`: **auto**: Minio 的 bucket 查找方式默认为`auto`模式，可将其设置为`dns`（虚拟托管样式）或`path`（路径样式），仅当`STORAGE_TYPE`为`minio`时可用。
+- `MINIO_BUCKET_LOOKUP_TYPE`：**auto**: Minio 的 bucket 查找方式默认为 `auto` 模式；可将其设置为 `dns`（虚拟托管样式）或 `path`（路径样式），仅在 `STORAGE_TYPE` 为 `minio` 时可用。
 
-- `AZURE_BLOB_ENDPOINT`: **_empty_**: Azure Blob 终端点，仅在 `STORAGE_TYPE` 为 `azureblob` 时可用。例如：https://accountname.blob.core.windows.net 或 http://127.0.0.1:10000/devstoreaccount1
-- `AZURE_BLOB_ACCOUNT_NAME`: **_empty_**: Azure Blob 账号名，仅在 `STORAGE_TYPE` 为 `azureblob` 时可用。
-- `AZURE_BLOB_ACCOUNT_KEY`: **_empty_**: Azure Blob 访问密钥，仅在 `STORAGE_TYPE` 为 `azureblob` 时可用。
-- `AZURE_BLOB_CONTAINER`: **gitea**: 用于存储数据的 Azure Blob 容器名，仅在 `STORAGE_TYPE` 为 `azureblob` 时可用。
-
-建议的 minio 存储配置如下：
+建议的 Minio 存储配置如下：
 
 ```ini
 [storage]
 STORAGE_TYPE = minio
 ; Minio endpoint to connect only available when STORAGE_TYPE is `minio`
 MINIO_ENDPOINT = localhost:9000
-; Minio accessKeyID to connect only available when STORAGE_TYPE is `minio`
+; Minio accessKeyID to connect only available when STORAGE_TYPE is `minio`.
+; If not provided and STORAGE_TYPE is `minio`, will search for credentials in known
+; environment variables (MINIO_ACCESS_KEY_ID, AWS_ACCESS_KEY_ID), credentials files
+; (~/.mc/config.json, ~/.aws/credentials), and EC2 instance metadata.
 MINIO_ACCESS_KEY_ID =
 ; Minio secretAccessKey to connect only available when STORAGE_TYPE is `minio`
 MINIO_SECRET_ACCESS_KEY =
+; Preferred IAM Endpoint to override Minio's default IAM Endpoint resolution only available when STORAGE_TYPE is `minio`.
+; If not provided and STORAGE_TYPE is `minio`, will search for and derive endpoint from known environment variables
+; (AWS_CONTAINER_AUTHORIZATION_TOKEN, AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE, AWS_CONTAINER_CREDENTIALS_RELATIVE_URI,
+; AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_WEB_IDENTITY_TOKEN_FILE, AWS_ROLE_ARN, AWS_ROLE_SESSION_NAME, AWS_REGION), or
+; the DefaultIAMRoleEndpoint if not provided otherwise.
+MINIO_IAM_ENDPOINT =
 ; Minio bucket to store the attachments only available when STORAGE_TYPE is `minio`
 MINIO_BUCKET = gitea
 ; Minio location to create bucket only available when STORAGE_TYPE is `minio`
@@ -1260,6 +1443,18 @@ SERVE_DIRECT = true
 MINIO_BUCKET_LOOKUP_TYPE = auto
 ```
 
+### Azure Blob 存储配置（`storage_azureblob`）
+
+- `SERVE_DIRECT`：**false**: 允许存储驱动程序重定向到经过身份验证的 URL 以直接提供文件。目前，仅支持通过签名的 URL 提供 Minio/S3，本地不执行任何操作。
+- `AZURE_BLOB_ENDPOINT`：**_empty_**: Azure Blob 连接终端点，仅在 `STORAGE_TYPE` 为 `azureblob` 时可用。例如：https://accountname.blob.core.windows.net 或 http://127.0.0.1:10000/devstoreaccount1
+- `AZURE_BLOB_ACCOUNT_NAME`：**_empty_**: Azure Blob 账号名，仅在 `STORAGE_TYPE` 为 `azureblob` 时可用。
+- `AZURE_BLOB_ACCOUNT_KEY`：**_empty_**: Azure Blob 访问密钥，仅在 `STORAGE_TYPE` 为 `azureblob` 时可用。
+- `AZURE_BLOB_CONTAINER`：**gitea**: 用于存储数据的 Azure Blob 容器名，仅在 `STORAGE_TYPE` 为 `azureblob` 时可用。
+
+### 覆盖配置（`storage_override`）
+
+覆盖可以有 3 个层级。`[LFS]/[attachment]...` >> `[storage.xxx]` >> `[storage]` >> 默认值。
+
 默认情况下，每个存储都有其默认的基本路径，如下所示：
 
 | storage           | default base path  |
@@ -1273,7 +1468,7 @@ MINIO_BUCKET_LOOKUP_TYPE = auto
 | actions_log       | actions_log/       |
 | actions_artifacts | actions_artifacts/ |
 
-并且桶（bucket）、基本路径或`SERVE_DIRECT`可以是特殊的或被覆盖的，如果您想要使用不同的设置，您可以：
+桶（bucket）、基本路径或 `SERVE_DIRECT` 可以被特别指定或覆盖，如果您想使用不同的设置，可以：
 
 ```ini
 [storage.actions_log]
@@ -1282,7 +1477,7 @@ SERVE_DIRECT = true
 MINIO_BASE_PATH = my_actions_log/ ; default is actions_log/ if blank
 ```
 
-如果您想为' lfs '自定义一个不同的存储，如果上面定义了默认存储
+如果您想为 `lfs` 自定义一个不同的存储（在上面已定义默认存储的情况下）：
 
 ```ini
 [lfs]
@@ -1292,10 +1487,19 @@ STORAGE_TYPE = my_minio
 STORAGE_TYPE = minio
 ; Minio endpoint to connect only available when STORAGE_TYPE is `minio`
 MINIO_ENDPOINT = localhost:9000
-; Minio accessKeyID to connect only available when STORAGE_TYPE is `minio`
+; Minio accessKeyID to connect only available when STORAGE_TYPE is `minio`.
+; If not provided and STORAGE_TYPE is `minio`, will search for credentials in known
+; environment variables (MINIO_ACCESS_KEY_ID, AWS_ACCESS_KEY_ID), credentials files
+; (~/.mc/config.json, ~/.aws/credentials), and EC2 instance metadata.
 MINIO_ACCESS_KEY_ID =
 ; Minio secretAccessKey to connect only available when STORAGE_TYPE is `minio`
 MINIO_SECRET_ACCESS_KEY =
+; Preferred IAM Endpoint to override Minio's default IAM Endpoint resolution only available when STORAGE_TYPE is `minio`.
+; If not provided and STORAGE_TYPE is `minio`, will search for and derive endpoint from known environment variables
+; (AWS_CONTAINER_AUTHORIZATION_TOKEN, AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE, AWS_CONTAINER_CREDENTIALS_RELATIVE_URI,
+; AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_WEB_IDENTITY_TOKEN_FILE, AWS_ROLE_ARN, AWS_ROLE_SESSION_NAME, AWS_REGION), or
+; the DefaultIAMRoleEndpoint if not provided otherwise.
+MINIO_IAM_ENDPOINT =
 ; Minio bucket to store the attachments only available when STORAGE_TYPE is `minio`
 MINIO_BUCKET = gitea
 ; Minio location to create bucket only available when STORAGE_TYPE is `minio`
@@ -1308,27 +1512,31 @@ MINIO_INSECURE_SKIP_VERIFY = false
 MINIO_BUCKET_LOOKUP_TYPE = auto
 ```
 
-### 存储库归档存储 (`storage.repo-archive`)
+## 存储库归档存储 (`storage.repo-archive`)
 
-存储库归档存储的配置。当将`STORAGE_TYPE`设置为`xxx`时，它将继承默认的 `[storage]` 或 `[storage.xxx]` 配置。`PATH`的默认值是`data/repo-archive`，`MINIO_BASE_PATH`的默认值是`repo-archive/`。
+存储库归档存储的配置。当将 `STORAGE_TYPE` 设置为 `xxx` 时，它将继承默认的 `[storage]` 或 `[storage.xxx]` 配置。`PATH` 的默认值是 `data/repo-archive`，`MINIO_BASE_PATH` 的默认值是 `repo-archive/`。
 
-- `STORAGE_TYPE`: **local**: 存储类型，`local`表示本地磁盘，`minio`表示与 S3 兼容的对象存储服务，或者使用定义为`[storage.xxx]`的其他名称。
-- `SERVE_DIRECT`: **false**: 允许存储驱动程序重定向到经过身份验证的 URL 以直接提供文件。目前，只有 Minio/S3 支持通过签名 URL，本地不执行任何操作。
-- `PATH`: **./data/repo-archive**: 用于存储归档文件的位置，仅在`STORAGE_TYPE`为`local`时可用。
-- `MINIO_ENDPOINT`: **localhost:9000**: Minio 端点，仅在`STORAGE_TYPE`为`minio`时可用。
-- `MINIO_ACCESS_KEY_ID`: Minio 的 accessKeyID，仅在`STORAGE_TYPE`为`minio`时可用。
-- `MINIO_SECRET_ACCESS_KEY`: Minio 的 secretAccessKey，仅在`STORAGE_TYPE`为`minio`时可用。
-- `MINIO_BUCKET`: **gitea**: 用于存储归档的 Minio 存储桶，仅在`STORAGE_TYPE`为`minio`时可用。
-- `MINIO_LOCATION`: **us-east-1**: 用于创建存储桶的 Minio 位置，仅在`STORAGE_TYPE`为`minio`时可用。
-- `MINIO_BASE_PATH`: **repo-archive/**: 存储桶上的 Minio 基本路径，仅在`STORAGE_TYPE`为`minio`时可用。
-- `MINIO_USE_SSL`: **false**: 启用 Minio 的 SSL，仅在`STORAGE_TYPE`为`minio`时可用。
-- `MINIO_INSECURE_SKIP_VERIFY`: **false**: 跳过 Minio 的 SSL 验证，仅在`STORAGE_TYPE`为`minio`时可用。
-- `MINIO_BUCKET_LOOKUP_TYPE`: **auto**: Minio 的 bucket 查找方式默认为`auto`模式，可将其设置为`dns`（虚拟托管样式）或`path`（路径样式），仅当`STORAGE_TYPE`为`minio`时可用。
+- `STORAGE_TYPE`：**local**: 存储库归档的存储类型，可以为空、`local`、`minio`、`azureblob` 或在 `[storage.xxx]` 中定义的其他名称。
 
-### 存储库归档 (`repo-archive`)
+  当 `STORAGE_TYPE` 为空或未配置此项时，所有存储将从 `[storage]`（如已配置）或默认值派生。
 
-- `STORAGE_TYPE`: **local**: 存储类型，用于操作日志，`local`表示本地磁盘，`minio`表示与 S3 兼容的对象存储服务，默认为`local`，或者使用定义为`[storage.xxx]`的其他名称。
-- `MINIO_BASE_PATH`: **repo-archive/**: Minio 存储桶上的基本路径，仅在`STORAGE_TYPE`为`minio`时可用。
+  当 `STORAGE_TYPE = local` 时，以下为可用配置项
+
+  - `PATH`：**./data/repo-archive**: 用于存储归档文件的位置，仅在 `STORAGE_TYPE` 为 `local` 时可用。
+
+  当 `STORAGE_TYPE = minio` 时，相关配置详见 [Minio 存储配置](#storage_minio)，您可以如下覆盖部分配置。
+
+  - `MINIO_BASE_PATH`：**repo-archive/**: 桶上的 Minio 基本路径，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
+
+  当 `STORAGE_TYPE = xxx` 时，配置将从 `[storage.xxx]` 派生，以下配置项可被覆盖。
+
+  - `PATH`：同上
+  - `MINIO_BASE_PATH`：同上
+
+## 存储库归档 (`repo-archive`)
+
+- `STORAGE_TYPE`：**local**: 存储类型，用于操作日志，`local` 表示本地磁盘，`minio` 表示与 S3 兼容的对象存储服务，默认为 `local`，或者使用定义为 `[storage.xxx]` 的其他名称。
+- `MINIO_BASE_PATH`：**repo-archive/**: Minio 存储桶上的基本路径，仅在 `STORAGE_TYPE` 为 `minio` 时可用。
 
 ## 代理 (`proxy`)
 
@@ -1361,6 +1569,9 @@ PROXY_HOSTS = *.github.com
 - `ENDLESS_TASK_TIMEOUT`: **3h**: 无尽任务超时时间，指具有运行状态并持续更新，但长时间未结束的任务。
 - `ABANDONED_JOB_TIMEOUT`: **24h**: 被遗弃的作业超时时间，指具有等待状态但长时间未被 runner 选中并执行的作业。
 - `SKIP_WORKFLOW_STRINGS`: **[skip ci],[ci skip],[no ci],[skip actions],[actions skip]**: 提交者可以在提交消息或 PR 标题中放置的字符串，以跳过执行相应的工作流。
+- `WORKFLOW_DIRS`：**.gitea/workflows,.github/workflows**：以逗号分隔的工作流目录列表，仓库中第一个存在的目录将用于查找 Actions 工作流文件。
+- `SCOPED_WORKFLOW_DIRS`：**.gitea/scoped_workflows**：以逗号分隔的目录列表，用于存放[作用域工作流](usage/actions/scoped-workflows.md)（在一个中心源仓库中定义、并在其他仓库上运行的工作流）。不得与 `WORKFLOW_DIRS` 重叠。留空则不会扫描任何目录来查找作用域工作流，因此不会找到或运行任何作用域工作流。
+- `MAX_RERUN_ATTEMPTS`：**50**：单个工作流运行最多可以有的尝试次数（初始运行 + 重新运行）。默认 50。可根据需要设置为任何正整数。
 
 `DEFAULT_ACTIONS_URL` 指示 Gitea 操作运行程序应该在哪里找到带有相对路径的操作。
 例如，`uses: actions/checkout@v4` 表示 `https://github.com/actions/checkout@v4`，因为 `DEFAULT_ACTIONS_URL` 的值为 `github`。

i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/customizing-gitea.md

@@ -7,77 +7,541 @@ aliases:
   - /zh-cn/customizing-gitea
 ---
 
-# 自定义 Gitea 配置
+# 自定义 Gitea
 
-Gitea 引用 `custom` 目录中的自定义配置文件来覆盖配置、模板等默认配置。
+自定义 Gitea 通常通过 `CustomPath` 目录完成。默认情况下，它是工作目录（WorkPath）下的
+`custom` 目录，但如果您的[安装方式](../installation/from-binary.md)做了不同设置，也可能位于其他位置。
+这是覆盖配置项、模板等内容的核心位置。您可以通过 `gitea help` 查看 `CustomPath`，也可以在
+_站点管理_ 页面的 _Configuration_ 选项卡中找到该路径。您还可以通过设置 `GITEA_CUSTOM`
+环境变量，或在 `gitea` 二进制上使用 `--custom-path` 选项来覆盖 `CustomPath`。
+（命令行选项会覆盖环境变量。）
 
-如果从二进制部署 Gitea ，则所有默认路径都将相对于该 gitea 二进制文件；如果从发行版安装，则可能会将这些路径修改为 Linux 文件系统标准。Gitea
-将会自动创建包括 `custom/` 在内的必要应用目录，应用本身的配置存放在
-`custom/conf/app.ini` 当中。在发行版中可能会以 `/etc/gitea/` 的形式为 `custom` 设置一个符号链接，查看配置详情请移步：
+如果 Gitea 以二进制方式部署，所有默认路径都相对于 Gitea 二进制文件。
+如果通过发行版安装，这些路径通常会按照 Linux 文件系统标准进行调整。Gitea 会尝试创建所需目录，
+包括 `custom/`。某些发行版可能会通过 `/etc/gitea/` 为 `custom` 提供一个符号链接。
+
+应用配置可以在 `CustomConf` 文件中找到，默认路径为 `$GITEA_CUSTOM/conf/app.ini`，
+但如果您的[安装方式](../installation/from-binary.md)修改了配置，也可能位于其他位置。
+同样，您可以通过 `gitea help` 查看该变量，也可以使用 `gitea` 二进制的 `--config` 选项覆盖它。
 
 - [快速备忘单](../administration/config-cheat-sheet.md)
 - [完整配置清单](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
 
-如果您在 binary 同目录下无法找到 `custom` 文件夹，请检查您的 `GITEA_CUSTOM`
-环境变量配置， 因为它可能被配置到了其他地方（可能被一些启动脚本设置指定了目录）。
+如果在检查 `gitea help` 后仍找不到 `CustomPath` 目录，请检查 `GITEA_CUSTOM` 环境变量；
+它可以用来将默认路径覆盖为其他位置。例如，`GITEA_CUSTOM` 可能由 init 脚本设置。
+您也可以在站点管理页面的 “Configuration” 选项卡下检查该值是否已设置。
 
 - [环境变量清单](../administration/environment-variables.md)
 
-**注：** 必须完全重启 Gitea 以使配置生效。
+:::note
+Gitea 必须执行完整重启后，配置更改才会生效。
+:::
 
-## 使用自定义 /robots.txt
+## 提供自定义公共文件
 
-将 [想要展示的内容](http://www.robotstxt.org/) 存放在 `custom` 目录中的
-`robots.txt` 文件来让 Gitea 使用自定义的`/robots.txt` （默认：空 404）。
+要让 Gitea 提供自定义公共文件（例如页面和图片），请将 `$GITEA_CUSTOM/public/`
+目录作为 webroot。Gitea 会跟随符号链接。
+当前仅提供以下文件：
 
-## 使用自定义的公共文件
+- `public/robots.txt`
+- `public/.well-known/` 目录中的文件
+- `public/assets/` 目录中的文件
 
-将自定义的公共文件（比如页面和图片）作为 webroot 放在 `custom/public/` 中来让 Gitea 提供这些自定义内容（符号链接将被追踪）。
+例如，存放在 `$GITEA_CUSTOM/public/assets/` 中的 `image.png` 文件，可以通过
+`http://gitea.domain.tld/assets/image.png` 访问。
 
-举例说明：`image.png` 存放在 `custom/public/assets/`中，那么它可以通过链接 http://gitea.domain.tld/assets/image.png 访问。
+## 修改 Logo
 
-## 修改默认头像
+如果要构建自定义 logo 和/或 favicon，请克隆 Gitea 源码仓库，替换 `assets/logo.svg`
+和/或 `assets/favicon.svg`，然后运行 `make generate-images`。`assets/favicon.svg`
+仅用于 favicon。执行后会更新以下输出文件，随后您可以将它们放到服务器上的
+`$GITEA_CUSTOM/public/assets/img` 中：
 
-替换以下目录中的 png 图片： `custom/public/assets/img/avatar\_default.png`
+- `public/assets/img/logo.svg` - 用于站点图标、应用图标
+- `public/assets/img/logo.png` - 用于 Open Graph
+- `public/assets/img/avatar_default.png` - 用作默认头像图片
+- `public/assets/img/apple-touch-icon.png` - 用于 iOS 设备书签
+- `public/assets/img/favicon.svg` - 用于 favicon
+- `public/assets/img/favicon.png` - 用作不支持 SVG favicon 的浏览器回退图标
 
-## 自定义 Gitea 页面
+如果源图片不是矢量格式，您可以尝试使用诸如[这个工具](https://www.aconvert.com/image/png-to-svg/)
+将光栅图像转换为矢量图。
 
-您可以改变 Gitea `custom/templates` 的每个单页面。您可以在 Gitea 源码的 `templates` 目录中找到用于覆盖的模板文件，应用将根据
-`custom/templates` 目录下的路径结构进行匹配和覆盖。
+## 自定义 Gitea 页面和资源
 
-包含在 `{{` 和 `}}` 中的任何语句都是 Gitea 的模板语法，如果您不完全理解这些组件，不建议您对它们进行修改。
+Gitea 可执行文件内置了运行所需的全部资源：模板、图片、样式表和翻译。您可以在 `custom`
+目录下放置与原路径一致的替换文件来覆盖其中任意资源。例如，要替换 C++ 仓库默认提供的
+`.gitignore`，我们需要替换 `options/gitignore/C++`。为此，您必须将替换文件放到
+`$GITEA_CUSTOM/options/gitignore/C++`（`CustomPath` 目录位置见本文开头说明）。
+
+Gitea 的每一个页面都可以修改。动态内容通过 [go template](https://pkg.go.dev/html/template)
+生成，您可以通过在 `$GITEA_CUSTOM/templates` 目录下放置替换文件进行修改。
+
+要获取任意内嵌文件（包括模板），可以使用[`gitea embedded` 工具](../administration/cmd-embedded.md)。
+另外，也可以在 Gitea 源码仓库的 [`templates`](https://github.com/go-gitea/gitea/tree/main/templates)
+目录中找到它们。（注意：示例链接指向 `main` 分支，请确保所使用的模板与您当前的发布版本兼容。）
+
+请注意，任何包含在 `{{` 和 `}}` 中的语句都是 Gitea 的模板语法，
+如果您没有完全理解这些组件，就不应修改它们。
+
+### 自定义首页 / 主页
+
+将与您所使用 Gitea 版本对应的 [`home.tmpl`](https://github.com/go-gitea/gitea/blob/main/templates/home.tmpl)
+从 `templates` 目录复制到 `$GITEA_CUSTOM/templates`。
+随后按您的需要编辑即可。
+不要忘记重启 Gitea 以应用更改。
 
 ### 添加链接和页签
 
-如果您只是想添加额外的链接到顶部导航栏或额外的选项卡到存储库视图，您可以将它们放在您 `custom/templates/custom/` 目录下的 `extra_links.tmpl` 和 `extra_tabs.tmpl` 文件中。
+如果您只是想为顶部导航栏或页脚添加额外链接，或者为仓库视图添加额外页签，
+可以将它们分别放入 `$GITEA_CUSTOM/templates/custom/` 目录中的
+`extra_links.tmpl`（添加到导航栏的链接）、`extra_links_footer.tmpl`
+（添加到页脚左侧的链接）和 `extra_tabs.tmpl`。
 
-举例说明：假设您需要在网站放置一个静态的“关于”页面，您只需将该页面放在您的
-"custom/public/"目录下（比如 `custom/public/impressum.html`）并且将它与 `custom/templates/custom/extra_links.tmpl` 链接起来即可。
+例如，假设您在德国，需要添加法律上通常要求提供的 “Impressum”/关于页面，用来说明谁对站点内容负责：
+只需将该页面放到 `$GITEA_CUSTOM/public/assets/` 目录中
+（例如 `$GITEA_CUSTOM/public/assets/impressum.html`），再在
+`$GITEA_CUSTOM/templates/custom/extra_links.tmpl` 或
+`$GITEA_CUSTOM/templates/custom/extra_links_footer.tmpl` 中加入指向它的链接即可。
 
-这个链接应当使用一个名为“item”的 class 来匹配当前样式，您可以使用 `{{AppSubUrl}}` 来获取 base URL:
+为了匹配当前样式，该链接应使用类名 `item`，并且您可以使用 `{{AppSubUrl}}` 获取基础 URL：
 `<a class="item" href="{{AppSubUrl}}/assets/impressum.html">Impressum</a>`
 
-同理，您可以将页签添加到 `extra_tabs.tmpl` 中，使用同样的方式来添加页签。它的具体样式需要与
-`templates/repo/header.tmpl` 中已有的其他选项卡的样式匹配
-([source in GitHub](https://github.com/go-gitea/gitea/blob/main/templates/repo/header.tmpl))
+更多信息请参见[添加法律页面](../administration/adding-legal-pages.md)。
 
-### 页面的其他新增内容
+您也可以用同样的方式添加新页签，将其放入 `extra_tabs.tmpl` 中。
+与其他页签样式匹配所需的精确 HTML 位于文件 `templates/repo/header.tmpl`
+（[GitHub 源码](https://github.com/go-gitea/gitea/blob/main/templates/repo/header.tmpl)）。
 
-除了 `extra_links.tmpl` 和 `extra_tabs.tmpl`，您可以在您的 `custom/templates/custom/` 目录中存放一些其他有用的模板，例如：
+### 页面中的其他插入内容
 
-- `header.tmpl`，在 `<head>` 标记结束之前的模板，例如添加自定义 CSS 文件
-- `body_outer_pre.tmpl`，在 `<body>` 标记开始处的模板
-- `body_inner_pre.tmpl`，在顶部导航栏之前，但在主 container 内部的模板，例如添加一个 `<div class="full height">`
-- `body_inner_post.tmpl`，在主 container 结束处的模板
-- `body_outer_post.tmpl`，在底部 `<footer>` 元素之前.
-- `footer.tmpl`，在 `<body>` 标签结束处的模板，可以在这里填写一些附加的 Javascript 脚本。
+除了 `extra_links.tmpl` 和 `extra_tabs.tmpl` 之外，您还可以在
+`$GITEA_CUSTOM/templates/custom/` 目录中放置其他有用的模板：
 
-## 自定义 gitignores，labels， licenses， locales 以及 readmes
+- `header.tmpl`，位于 `<head>` 结束标签之前，例如可用于添加自定义 CSS 文件。
+- `body_outer_pre.tmpl`，位于 `<body>` 起始标签之后。
+- `body_inner_pre.tmpl`，位于顶部导航栏之前，但已处于主容器 `<div class="full height">` 内部。
+- `body_inner_post.tmpl`，位于主容器结束之前。
+- `body_outer_post.tmpl`，位于底部 `<footer>` 元素之前。
+- `footer.tmpl`，位于 `<body>` 结束标签之前，是放置额外 JavaScript 的合适位置。
 
-将自定义文件放在 `custom/options` 下相应子的文件夹中即可
+### 使用 Gitea 变量
 
-## 更改 Gitea 外观
+您可以在自定义模板中使用各种 Gitea 变量。
 
-内置主题是“gitea-light”、“gitea-dark”和“gitea-auto”（自动适应操作系统设置）。
+首先，_临时_ 启用开发模式：在 `app.ini` 中将 `RUN_MODE = prod` 改为 `RUN_MODE = dev`。
+然后在任意模板中添加 `{{ $ | DumpVar }}`，重启 Gitea 并刷新对应页面；
+这样会输出所有可用变量。
 
-默认主题可以通过 `app.ini` 的 [ui](../administration/config-cheat-sheet.md#界面) 部分中的 `DEFAULT_THEME` 进行更改。
+找到所需数据后，使用对应变量即可；例如，如果您需要仓库名称，可以使用 `{{.Repository.Name}}`。
+
+如果您需要对这些数据做一些转换，而您又不熟悉 Go，一种简单的变通办法是先将数据放入 DOM，
+再添加一小段 JavaScript 脚本来处理它。
+
+### 示例：PlantUML
+
+您可以通过 PlantUML 服务器为 Gitea 的 Markdown 添加 [PlantUML](https://plantuml.com/) 支持。
+数据会被编码后发送到 PlantUML 服务器，再由服务器生成图片。官方在
+http://www.plantuml.com/plantuml 提供了一个在线演示服务器，但如果您（或您的用户）拥有敏感数据，
+则可以改为自建一个 [PlantUML 服务器](https://plantuml.com/server)。要启用 PlantUML 渲染，
+请从 https://gitea.com/davidsvantesson/plantuml-code-highlight 复制 JavaScript 文件，
+并将其放入 `$GITEA_CUSTOM/public/assets/` 目录。然后将以下内容添加到 `custom/footer.tmpl`：
+
+```html
+<script>
+  $(async () => {
+    if (!$('.language-plantuml').length) return;
+    await Promise.all([
+      $.getScript('https://your-gitea-server.com/assets/deflate.js'),
+      $.getScript('https://your-gitea-server.com/assets/encode.js'),
+      $.getScript('https://your-gitea-server.com/assets/plantuml_codeblock_parse.js'),
+    ]);
+    // Replace call with address to your plantuml server
+    parsePlantumlCodeBlocks("https://www.plantuml.com/plantuml");
+  });
+</script>
+```
+
+随后，您就可以在 Markdown 中添加如下代码块：
+
+```plantuml
+Alice -> Bob: Authentication Request
+Bob --> Alice: Authentication Response
+
+Alice -> Bob: Another authentication Request
+Alice <-- Bob: Another authentication Response
+```
+
+该脚本会检测 `class="language-plantuml"` 的标签，不过您也可以通过为
+`parsePlantumlCodeBlocks` 提供第二个参数来修改这一行为。
+
+### 示例：使用 Online 3D Viewer 预览 CAD 文件
+
+您可以在自己的 Gitea 实例中实现 CAD 文件预览。这个实现使用的是
+[`Online 3D Viewer`](https://github.com/kovacsv/Online3DViewer)。
+
+支持以下 3D 文件格式：
+`3dm`, `3ds`, `3mf`, `amf`, `bim`, `brep`, `dae`, `fbx`, `fcstd`, `glb`,
+`gltf`, `ifc`, `igs`, `iges`, `stp`, `step`, `stl`, `obj`, `off`, `ply`, `wrl`
+（`.gltf` 文件仅支持 v2）
+
+#### 第 1 部分：添加模板
+
+我们需要在 `$GITEA_CUSTOM` 中添加模板。
+该模板需要保存到 `$GITEA_CUSTOM/templates/custom/` 中。
+在这里创建 `footer.tmpl` 文件，并向其中添加以下内容：
+
+```
+nano $GITEA_CUSTOM/templates/custom/footer.tmpl
+```
+
+```html
+<script>
+    function onPageChange() {
+      // Supported 3D file types
+      const fileTypes = ['3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb', 'gltf', 'ifc', 'igs', 'iges', 'stp', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'];
+  
+      // Select matching link
+      const links = Array.from(document.querySelectorAll('a.ui.mini.basic.button'));
+      const link3D = links.find(link => {
+        const href = link.href.toLowerCase();
+        return href.includes('/raw/') && fileTypes.some(ext => href.endsWith(`.${ext}`));
+      });
+  
+	if (link3D) {
+	  const existingScript = document.querySelector('script[src="/assets/o3dv/o3dv.min.js"]');
+
+	  const initializeViewer = () => {
+		const fileUrl = link3D.getAttribute('href');
+
+                const fileView = document.querySelector('.file-view');
+
+		if (!fileView) return;
+
+		// Remove only the old viewer container if it exists
+		const oldView3D = document.getElementById('view-3d');
+		if (oldView3D) {
+		  oldView3D.remove();  // safely remove old viewer container div
+		} else {
+		  // No #view-3d, so remove all children inside .file-view
+		  while (fileView.firstChild) {
+		    fileView.removeChild(fileView.firstChild);
+		  }
+		}
+
+		// Create a new container for the viewer
+		const newView3D = document.createElement('div');
+		  newView3D.id = 'view-3d';
+		  newView3D.style.padding = '0';
+		  newView3D.style.margin = '0';
+		  newView3D.style.flexGrow = '1';
+		  newView3D.style.minHeight = '0';
+		  newView3D.style.width = '100%';
+		
+		const header = document.querySelector('header');
+		const headerHeight = header ? header.offsetHeight : 0;
+
+		newView3D.style.height = `calc(100vh - ${headerHeight}px)`;		
+
+		// Append the new container inside fileView
+		fileView.appendChild(newView3D);
+
+		const parentDiv = document.getElementById('view-3d');
+		if (parentDiv) {
+		  const viewer = new OV.EmbeddedViewer(parentDiv, {
+			backgroundColor: new OV.RGBAColor(59, 68, 76, 0),
+			defaultColor: new OV.RGBColor(200, 200, 200),
+			edgeSettings: new OV.EdgeSettings(false, new OV.RGBColor(0, 0, 0), 1),
+			environmentSettings: new OV.EnvironmentSettings([
+			  '/assets/o3dv/envmaps/fishermans_bastion/negx.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/posx.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/posy.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/negy.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/posz.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/negz.jpg'
+			], false)
+		  });
+
+		  viewer.LoadModelFromUrlList([fileUrl]);
+		}
+	  };
+
+	  if (typeof OV === 'undefined') {
+		if (!existingScript) {
+		  const script = document.createElement('script');
+		  script.onload = initializeViewer;
+		  script.src = '/assets/o3dv/o3dv.min.js';
+		  document.head.appendChild(script);
+		} else {
+		  // Script is loading but OV not yet ready — wait for it
+		  existingScript.addEventListener('load', initializeViewer);
+		}
+	  } else {
+		// OV already loaded
+		initializeViewer();
+	  }
+	}
+    };
+
+    // Run when the page is fully loaded
+    document.addEventListener('DOMContentLoaded', onPageChange); 
+
+    const targetSelector = 'a.ui.mini.basic.button[href*="/raw/"]';
+    let lastHref = null;
+    let timeoutId = null;
+
+    const checkAndRun = () => {
+      const rawLink = document.querySelector(targetSelector);
+      if (!rawLink) return;
+
+      const currentHref = rawLink.getAttribute('href');
+      if (currentHref !== lastHref) {
+        lastHref = currentHref;
+
+        const fileName = currentHref.split('/').pop();
+        console.log('New Raw file link detected after delay:', fileName);
+        
+        onPageChange();
+      }
+    };
+
+    const observer = new MutationObserver(() => {
+      // Delay execution by 300ms after last mutation
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(checkAndRun, 300);
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+    });
+</script>
+```
+
+#### 第 2 部分：添加公共文件
+
+现在我们需要下载最新版本的 O3DV。进入 `$GITEA_CUSTOM/public/assets/`。
+使用以下命令创建目录（并进入该目录）：
+
+```
+mkdir o3dv
+cd o3dv
+```
+
+从 [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) 复制最新发行版压缩包链接
+（当前示例版本为 v0.18.0）。
+然后使用例如 wget 或 curl 下载该文件：
+
+```
+wget https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
+```
+
+或者
+
+```
+curl -L -O https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
+```
+
+再使用例如 unzip 解压归档文件：
+```
+unzip o3dv.zip
+```
+
+#### 第 3 部分：目录权限
+
+最后一步，修改 public 目录权限：
+```
+chown -R git:git $GITEA_CUSTOM/public
+```
+
+现在一切就绪！重启您的 Gitea 实例以应用这些更改，并在浏览器中进行测试。
+
+简单检查一下。最终目录结构应类似如下：
+
+```
+$GITEA_CUSTOM/templates
+-- custom
+    `-- footer.tmpl
+
+$GITEA_CUSTOM/public/assets/
+-- o3dv
+   |-- o3dv.zip
+   |-- o3dv.license.md
+   |-- o3dv.min.js
+   |-- envmaps
+    \...
+```
+
+## 自定义 Gitea 邮件
+
+`$GITEA_CUSTOM/templates/mail` 目录允许您修改 Gitea 每一种邮件的正文。
+可被覆盖的模板可以在 Gitea 源码的
+[`templates/mail`](https://github.com/go-gitea/gitea/tree/main/templates/mail)
+目录中找到。
+覆盖方式是将对应文件复制到 `$GITEA_CUSTOM/templates/mail` 下，
+并保持与源码一致的完整路径结构。
+
+任何包含在 `{{` 和 `}}` 中的语句都是 Gitea 的模板语法，
+如果您没有完全理解这些组件，就不应修改它们。
+
+## 为 Gitea 添加统计分析
+
+Google Analytics、Matomo（原 Piwik）以及其他分析服务都可以集成到 Gitea。
+要添加跟踪代码，请参考本文的“页面中的其他插入内容”一节，
+并将相应 JavaScript 添加到 `$GITEA_CUSTOM/templates/custom/header.tmpl` 文件中。
+
+## 自定义 gitignores、labels、licenses、locales 和 readmes
+
+将自定义文件放入 `custom/options` 下对应的子目录中。
+
+:::note
+这些文件不应带有扩展名，例如应使用 `Labels`，而不是 `Labels.txt`
+:::
+
+### gitignores
+
+要添加自定义 `.gitignore`，请在 `$GITEA_CUSTOM/options/gitignore` 中添加一个文件，
+文件内容遵循现有的 [.gitignore 规则](https://git-scm.com/docs/gitignore)。
+
+## 自定义 git 配置
+
+从 Gitea 1.20 开始，您可以通过 `git.config` 区块自定义 git 配置。
+
+### 启用签名 git push
+
+[签名推送](https://git-scm.com/docs/git-push#Documentation/git-push.txt---signedtruefalseif-asked)
+允许客户端对 push 操作本身进行加密签名（而不仅仅是对单个提交签名）。
+要启用签名推送，请将以下内容添加到 `app.ini`：
+
+```ini
+[git.config]
+receive.certNonceSeed = <randomstring>
+```
+
+`certNonceSeed` 应设置为一个随机字符串并妥善保密。它用于生成防重放 nonce。
+Gitea 默认已经设置了 `receive.advertisePushOptions = true`，因此无需额外配置。
+请注意，Gitea 不会读取 `/etc/gitconfig`，因此必须像上面这样通过 `app.ini` 设置该选项。
+
+在客户端侧，可以通过 `git push --signed` 进行签名推送，
+或者使用 `git config --global push.gpgSign if-asked` 永久启用。
+
+### Labels
+
+从 Gitea 1.19 开始，您可以向 `$GITEA_CUSTOM/options/label` 中添加一个遵循
+[YAML 标签格式](https://github.com/go-gitea/gitea/blob/main/options/label/Advanced.yaml)
+的文件：
+
+```yaml
+labels:
+  - name: "foo/bar"  # 下拉列表中显示的标签名称
+    exclusive: true # 是否为作用域标签使用互斥命名空间，作用域分隔符为 /
+    color: aabbcc # 十六进制颜色值
+    description: Some label # 标签用途的详细描述
+ ```
+
+旧的[传统文件格式](https://github.com/go-gitea/gitea/blob/main/options/label/Default)
+仍可使用，格式如下，但我们强烈建议改用新的 YAML 格式。
+
+`#hex-color label name ; label description`
+
+更多信息请参阅[标签文档](../usage/issues-prs/labels.md)。
+
+### Licenses
+
+要添加自定义许可证，请将包含许可证文本的文件添加到 `$GITEA_CUSTOM/options/license`。
+
+### Locales
+
+本地化语言由我们的 [Crowdin](https://crowdin.com/project/gitea) 管理。
+您可以通过将修改后的语言文件放到 `$GITEA_CUSTOM/options/locale` 中来覆盖某个语言环境。
+Gitea 默认的语言文件可以在源码目录
+[`options/locale`](https://github.com/go-gitea/gitea/tree/main/options/locale) 中找到，
+这些文件可以作为您修改时的参考示例。
+
+如果要添加一个全新的语言环境，除了将文件放到上述位置外，
+您还需要在 `app.ini` 的 `[i18n]` 部分中添加新的语言代码和名称。
+请记住，Gitea 会将这些设置视为**覆盖项**，因此如果您还想保留其他语言，
+就需要复制默认值并在其中加入您自己的语言项。
+
+```ini title="app.ini"
+[i18n]
+LANGS = en-US,foo-BAR
+NAMES = English,FooBar
+```
+
+如果用户浏览器的语言与列表中的任何语言都不匹配，则第一种语言会被用作默认语言。
+
+不同版本之间的语言文件可能会变化，因此强烈建议持续跟踪您自定义过的语言文件。
+
+### Readmes
+
+要添加自定义 Readme，请将一个 Markdown 格式的文件（不带 `.md` 扩展名）
+放到 `$GITEA_CUSTOM/options/readme` 中。
+
+:::note
+Readme 模板支持**变量展开**。
+当前可用变量包括 `{Name}`（仓库名称）、`{Description}`、`{CloneURL.SSH}`、`{CloneURL.HTTPS}` 和 `{OwnerName}`
+:::
+
+### Reactions
+
+要修改反应表情，您可以在 `app.ini` 中设置允许使用的 reactions。
+
+```ini title="app.ini"
+[ui]
+REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes
+```
+
+完整的受支持 emoji 列表见 [emoji list](https://gitea.com/gitea/gitea.com/issues/8)。
+
+## 自定义 Gitea 外观
+
+内置主题有 `gitea-light`、`gitea-dark` 和 `gitea-auto`
+（会自动适应操作系统设置）。
+
+默认主题可以通过 `app.ini` 中 [ui](../administration/config-cheat-sheet.md#界面) 部分的
+`DEFAULT_THEME` 进行修改。
+
+Gitea 还支持用户主题，这意味着每位用户都可以选择要使用的主题。
+用户可选主题列表可以通过 `app.ini` 中 [ui](../administration/config-cheat-sheet.md#界面)
+部分的 `THEMES` 值进行配置。
+
+要让所有用户都能使用自定义主题：
+
+1. 将 CSS 文件添加到 `$GITEA_CUSTOM/public/assets/css/theme-<theme-name>.css`。
+   您可以通过执行 `gitea help` 并查看其中的 “CustomPath” 值来确认实例的 `$GITEA_CUSTOM`。
+2. 将 `<theme-name>` 添加到 `app.ini` 中 `THEMES` 设置的逗号分隔列表中，
+   或者将 `THEMES` 留空以允许所有主题。
+
+名为 `theme-my-theme.css` 的自定义主题文件会在用户主题选择页面中显示为 `my-theme`。
+您还可以在自定义主题 CSS 文件中加入主题元信息，以提供更多说明。
+如果自定义主题是暗色主题，请在 `:root` 块中设置全局 CSS 变量 `--is-dark-theme: true`。
+这样 Gitea 就可以相应地调整 Monaco 代码编辑器的主题。
+如果要实现 “auto” 主题，可以参考 `theme-gitea-auto.css`。
+
+```css
+gitea-theme-meta-info {
+  --theme-display-name: "My Awesome Theme"; /* this theme will be display as "My Awesome Theme" on the UI */
+}
+:root {
+  --is-dark-theme: true; /* if it is a dark theme */
+  --color-primary: #112233;
+  /* more custom theme variables ... */
+}
+```
+
+社区主题列在 [gitea/awesome-gitea#themes](https://gitea.com/gitea/awesome-gitea#themes)。
+
+默认主题源码可在[这里](https://github.com/go-gitea/gitea/blob/main/web_src/css/themes)找到。
+
+## 自定义字体
+
+可以使用 CSS 变量自定义字体：
+
+```css
+:root {
+  --fonts-proportional: /* custom proportional fonts */ !important;
+  --fonts-monospace: /* custom monospace fonts */ !important;
+  --fonts-emoji: /* custom emoji fonts */ !important;
+}
+```

i18n/zh-cn/docusaurus-plugin-content-docs/current/contributing/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "贡献",
+  "position": 35,
+  "link": {
+    "type": "generated-index",
+    "slug": "/contributing",
+    "title": "贡献"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/development.md

@@ -1,12 +0,0 @@
----
-date: "2016-12-01T16:00:00+02:00"
-title: "开发"
-slug: "development"
-sidebar_position: 40
-
-menu:
-  sidebar:
-    name: "开发"
-    sidebar_position: 40
-    identifier: "development"
----

i18n/zh-cn/docusaurus-plugin-content-docs/current/development/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "开发",
+  "position": 40,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development",
+    "title": "开发"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/help.md

@@ -1,12 +0,0 @@
----
-date: "2017-01-20T15:00:00+08:00"
-title: "帮助"
-slug: "help"
-sidebar_position: 5
-
-menu:
-  sidebar:
-    name: "帮助"
-    sidebar_position: 100
-    identifier: "help"
----

i18n/zh-cn/docusaurus-plugin-content-docs/current/help/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "帮助",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "slug": "/help",
+    "title": "帮助"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/installation.md

@@ -1,12 +0,0 @@
----
-date: "2016-12-01T16:00:00+02:00"
-title: "安装"
-slug: "installation"
-sidebar_position: 10
-
-menu:
-  sidebar:
-    name: "安装"
-    sidebar_position: 10
-    identifier: "installation"
----

i18n/zh-cn/docusaurus-plugin-content-docs/current/installation/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "安装",
+  "position": 10,
+  "link": {
+    "type": "generated-index",
+    "slug": "/installation",
+    "title": "安装"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage.md

@@ -1,12 +0,0 @@
----
-date: "2016-12-27T16:00:00+02:00"
-title: "使用指南"
-slug: "usage"
-sidebar_position: 35
-
-menu:
-  sidebar:
-    name: "使用指南"
-    sidebar_position: 30
-    identifier: "usage"
----

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "使用指南",
+  "position": 35,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage",
+    "title": "使用指南"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/access-control/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "权限控制",
+  "position": 100,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/access-control",
+    "description": "权限，安全，和访问控制功能"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "工作流",
+  "position": 30,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/actions",
+    "description": "自动化工作流，CI/CD 和操作功能"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/design.md

@@ -8,35 +8,11 @@ sidebar_position: 40
 
 Gitea Actions由多个组件组成。本文档将对它们进行逐个描述。
 
-## Act
+## Gitea Runner
 
-[nektos/act](https://github.com/nektos/act) 项目是一个优秀的工具，允许你在本地运行GitHub Actions。
-我们受到了它的启发，并思考它是否可能为Gitea运行Actions。
+Gitea Runner部分基于[nektos/act](https://github.com/nektos/act)的硬分支。
 
-然而，尽管[nektos/act](https://github.com/nektos/act)被设计为一个命令行工具，但我们实际上需要的是一个专为Gitea修改的Go库。
-因此，我们在[gitea/act](https://gitea.com/gitea/act)基础上进行了分叉。
-
-这是一个软分叉，将定期跟进上游。
-虽然添加了一些自定义提交，但我们会尽力避免对原始代码进行太多更改。
-
-分叉的 act 只是Gitea特定用途的桥接或适配器。
-还添加了一些额外的提交，例如：
-
-- 将执行日志输出到日志记录器钩子，以便报告给Gitea
-- 禁用 GraphQL URL，因为Gitea不支持它
-- 每个Job启动一个新的容器，而不是重复使用，以确保隔离性。
-
-这些修改没有理由合并到上游。
-如果用户只想在本地运行可信的Actions，它们是没有意义的。
-
-然而，将来可能会出现重叠，例如两个项目都需要的必要错误修复或新功能。
-在这些情况下，我们将向上游仓库贡献变更。
-
-## act runner
-
-Gitea的Runner被称为act runner，因为它基于act。
-
-与其他CIRunner一样，我们将其设计为Gitea的外部部分，这意味着它应该在与Gitea不同的服务器上运行。
+与其他CI Runner一样，我们将其设计为Gitea的外部部分，这意味着它应该在与Gitea不同的服务器上运行。
 
 为了确保Runner连接到正确的Gitea实例，我们需要使用令牌注册它。
 此外，Runner通过声明自己的标签向Gitea报告它可以运行的Job类型。
@@ -47,7 +23,7 @@ Gitea的Runner被称为act runner，因为它基于act。
 这意味着Runner可以接受需要在`my_custom_label`上运行的Job，并通过使用`centos:7`镜像的Docker容器来运行它。
 
 然而，Docker不是唯一的选择。
-act 也支持直接在主机上运行Job。
+Runner 也支持直接在主机上运行Job。
 这是通过像`linux_arm:host`这样的标签实现的。
 这个标签表示Runner可以接受需要在`linux_arm`上运行的Job，并直接在主机上运行它们。
 
@@ -63,7 +39,7 @@ act 也支持直接在主机上运行Job。
 
 ## 通信协议
 
-由于act runner是Gitea的独立部分，我们需要一种协议让Runner与Gitea实例进行通信。
+由于 runner 是 Gitea 的独立部分，我们需要一种协议让 Runner 与 Gitea 实例进行通信。
 然而，我们不认为让Gitea监听一个新端口是个好主意。
 相反，我们希望重用HTTP端口，这意味着我们需要一个与HTTP兼容的协议。
 因此，我们选择使用基于HTTP的gRPC。
@@ -74,17 +50,17 @@ act 也支持直接在主机上运行Job。
 ## 网络架构
 
 让我们来看一下整体的网络架构。
-这将帮助您解决一些问题，并解释为什么使用回环地址注册Runner是个不好的主意。
+这将帮助您解决一些问题，并解释为什么使用回环地址注册 Runner 是个不好的主意。
 
 ![network](/images/usage/actions/network.png)
 
 图片中标记了四个网络连接，并且箭头的方向表示建立连接的方向。
 
-### 连接 1，act runner到Gitea实例
+### 连接 1，runner 到 Gitea 实例
 
-act runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
+Runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
 
-### 连接 2，Job容器到Gitea实例
+### 连接 2，Job 容器到 Gitea 实例
 
 即使Job容器位于同一台机器上，它们的网络命名空间与Runner不同。
 举个例子，如果工作流中包含 `actions/checkout@v4`，Job容器需要连接到Gitea来获取代码。
@@ -93,9 +69,9 @@ act runner 必须能够连接到Gitea以接收任务并发送执行结果回来
 如果您使用回环地址注册Runner，当Runner与Gitea在同一台机器上时，Runner可以连接到Gitea。
 然而，如果Job容器尝试从本地主机获取代码，它将失败，因为Gitea不在同一个容器中。
 
-### 连接 3，act runner到互联网
+### 连接 3，runner 到互联网
 
-当您使用诸如 `actions/checkout@v4` 的一些Actions时，act runner下载的是脚本，而不是Job容器。
+当您使用诸如 `actions/checkout@v4` 的一些Actions时， runner下载的是脚本，而不是Job容器。
 默认情况下，它从[github.com](http://github.com/)下载，因此需要访问互联网。如果您设置的是 self，
 那么默认将从您的当前Gitea实例下载，那么此步骤不需要连接到互联网。
 它还默认从Docker Hub下载一些Docker镜像，这也需要互联网访问。

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/faq.md

@@ -73,7 +73,7 @@ Runner仅具有连接到您的Gitea实例的权限。
 - 对于 fork 的拉取请求，需要获得批准才能运行Actions。参见[#22803](https://github.com/go-gitea/gitea/pull/22803)。
 - 如果有人在[gitea.com](http://gitea.com/)为其仓库或组织注册自己的Runner，我们不会反对，只是不会在我们的组织中使用它。然而，他们应该注意确保该Runner不被他们不认识的其他用户使用。
 
-## act runner支持哪些操作系统？
+## Runner 支持哪些操作系统？
 
 它在Linux、macOS和Windows上运行良好。
 虽然理论上支持其他操作系统，但需要进一步测试。
@@ -101,7 +101,7 @@ defaults:
 
 这是有效的语法。
 它意味着它应该在具有`label_a` **和** `label_b`标签的Runner上运行，参考[GitHub Actions的工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
-不幸的是，act runner 并不支持这种方式。
+不幸的是，runner 并不支持这种方式。
 如上所述，我们将标签映射到环境：
 
 - `ubuntu` → `ubuntu:22.04`
@@ -117,31 +117,31 @@ defaults:
 具有`ubuntu`、`centos`或`with-gpu`的Runner并不一定表示它可以接受`[centos, with-gpu]`的Job。
 因此，Runner应该通知Gitea实例它只能接受具有 `[ubuntu]`、`[centos]`、`[with-gpu]` 和 `[ubuntu, with-gpu]`的Job。
 这不是一个技术问题，只是在早期设计中被忽视了。
-参见[runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
+参见[runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
 
-目前，act runner尝试匹配标签中的每一个，并使用找到的第一个匹配项。
+目前，runner 尝试匹配标签中的每一个，并使用找到的第一个匹配项。
 
 ## 代理标签和自定义标签对于Runner有什么区别？
 
 ![labels](/images/usage/actions/labels.png)
 
-代理标签是由Runner在注册过程中向Gitea实例报告的。
+代理标签是由 Runner 在注册过程中向 Gitea 实例报告的。
 而自定义标签则是由Gitea的管理员或组织或仓库的所有者手动添加的（取决于Runner所属的级别）。
 
 然而，目前这方面的设计还有待改进，因为它目前存在一些不完善之处。
 您可以向已注册的Runner添加自定义标签，比如 `centos`，这意味着该Runner将接收具有`runs-on: centos`的Job。
 然而，Runner可能不知道要使用哪个环境来执行该标签，导致它使用默认镜像或导致逻辑死胡同。
 这个默认值可能与用户的期望不符。
-参见[runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
+参见[runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
 
 与此同时，如果您想更改Runner的标签，我们建议您重新注册Runner。
 
 ## Gitea Actions runner会有更多的实现吗？
 
-虽然我们希望提供更多的选择，但由于我们有限的人力资源，act runner将是唯一受支持的官方Runner。
-然而，无论您如何决定，Gitea 和act runner都是完全开源的，所以任何人都可以创建一个新的/更好的实现。
+虽然我们希望提供更多的选择，但由于我们有限的人力资源，runner 将是唯一受支持的官方 Runner。
+然而，无论您如何决定，Gitea 和 runner都是完全开源的，所以任何人都可以创建一个新的/更好的实现。
 我们支持您的选择，无论您如何决定。
-如果您选择分支act runner来创建自己的版本，请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。
+如果您选择分支 runner来创建自己的版本，请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。
 
 ## Gitea 支持哪些工作流触发事件？
 

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/overview.md

@@ -21,8 +21,8 @@ Gitea Actions与[GitHub Actions](https://github.com/features/actions)相似且
 ## Runner
 
 和其他CI/CD解决方案一样，Gitea不会自己运行Job，而是将Job委托给Runner。
-Gitea Actions的Runner被称为[act runner](https://gitea.com/gitea/act_runner)，它是一个独立的程序，也是用Go语言编写的。
-它是基于[nektos/act](http://github.com/nektos/act)的一个[分支](https://gitea.com/gitea/act) 。
+Gitea Actions的Runner被称为[Gitea Runner](https://gitea.com/gitea/runner)，它是一个独立的程序，也是用Go语言编写的。
+它的重要部分来自[nektos/act](http://github.com/nektos/act)的一个硬分支。
 
 由于Runner是独立部署的，可能存在潜在的安全问题。
 为了避免这些问题，请遵循两个简单的规则：

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/quickstart.md

@@ -25,10 +25,10 @@ ENABLED=true
 
 ### 设置Runner
 
-Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job。
+Gitea Actions需要[runner](https://gitea.com/gitea/runner) 来运行Job。
 为了避免消耗过多资源并影响Gitea实例，建议您在与Gitea实例分开的机器上启动Runner。
 
-您可以使用[预构建的二进制文件](http://dl.gitea.com/act_runner)或[容器镜像](https://hub.docker.com/r/gitea/act_runner/tags)来设置Runner。
+您可以使用[预构建的二进制文件](http://dl.gitea.com/gitea-runner)或[容器镜像](https://hub.docker.com/r/gitea/runner/tags)来设置Runner。
 
 在进一步操作之前，建议您先使用预构建的二进制文件以命令行方式运行它，以确保它与您的环境兼容，尤其是如果您在本地主机上运行Runner。
 如果出现问题，这样调试起来会更容易。
@@ -40,7 +40,7 @@ Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job
 在运行Runner之前，您需要使用以下命令将其注册到Gitea实例中：
 
 ```bash
-./act_runner register --no-interactive --instance <instance> --token <token>
+./runner register --no-interactive --instance <instance> --token <token>
 ```
 
 需要两个必需的参数：`instance` 和 `token`。
@@ -68,14 +68,14 @@ Runner和Job容器（由Runner启动以执行Job）将连接到此地址。
 最后，是时候启动Runner了：
 
 ```bash
-./act_runner daemon
+./runner daemon
 ```
 
 您可以在管理页面上看到新的Runner：
 
 ![view runner](/images/usage/actions/view-runner.png)
 
-您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
+您可以通过访问[Gitea Runner](runner) 获取更多信息。
 
 ### 使用Actions
 

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/runner.md

@@ -1,14 +1,14 @@
 ---
 date: "2023-05-24T15:00:00+08:00"
-
-slug: "act-runner"
+slug: "runner"
 sidebar_position: 20
-
+aliases:
+  - /zh-cn/act-runner
 ---
 
-# Act Runner
+# Runner
 
-本页面将详细介绍[Act Runner](https://gitea.com/gitea/act_runner)，这是Gitea Actions的Runner。
+本页面将详细介绍[Gitea Runner](https://gitea.com/gitea/runner)，这是Gitea Actions的Runner。
 
 ## 要求
 
@@ -21,31 +21,31 @@ sidebar_position: 20
 
 ## 安装
 
-有多种安装Act Runner的方法。
+有多种安装 Runner 的方法。
 
 ### 下载二进制文件
 
-您可以从[发布页面](https://gitea.com/gitea/act_runner/releases)下载二进制文件。
-然而，如果您想使用最新的夜间构建版本，可以从[下载页面](https://dl.gitea.com/act_runner/)下载。
+您可以从[发布页面](https://gitea.com/gitea/runner/releases)下载二进制文件。
+然而，如果您想使用最新的夜间构建版本，可以从[下载页面](https://dl.gitea.com/gitea-runner/)下载。
 
 下载二进制文件时，请确保您已经下载了适用于您的平台的正确版本。
 您可以通过运行以下命令进行检查：
 
 ```bash
-chmod +x act_runner
-./act_runner --version
+chmod +x runner
+./runner --version
 ```
 
 如果看到版本信息，则表示您已经下载了正确的二进制文件。
 
 ### 使用 Docker 镜像
 
-您可以使用[docker hub](https://hub.docker.com/r/gitea/act_runner/tags)上的Docker镜像。
+您可以使用[docker hub](https://hub.docker.com/r/gitea/runner/tags)上的Docker镜像。
 与二进制文件类似，您可以使用`nightly`标签使用最新的夜间构建版本，而`latest`标签是最新的稳定版本。
 
 ```bash
-docker pull docker.io/gitea/act_runner:latest # for the latest stable release
-docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
+docker pull docker.io/gitea/runner:latest # for the latest stable release
+docker pull docker.io/gitea/runner:nightly # for the latest nightly build
 ```
 
 ## 配置
@@ -55,20 +55,20 @@ docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
 您可以通过运行以下命令生成配置文件：
 
 ```bash
-./act_runner generate-config
+./runner generate-config
 ```
 
 默认配置是安全的，可以直接使用。
 
 ```bash
-./act_runner generate-config > config.yaml
-./act_runner --config config.yaml [command]
+./runner generate-config > config.yaml
+./runner --config config.yaml [command]
 ```
 
 您亦可以如下使用 docker 创建配置文件：
 
 ```bash
-docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner generate-config > config.yaml
+docker run --entrypoint="" --rm -it docker.io/gitea/runner:latest runner generate-config > config.yaml
 ```
 
 当使用Docker镜像时，可以使用`CONFIG_FILE`环境变量指定配置文件。确保将文件作为卷挂载到容器中：
@@ -77,12 +77,12 @@ docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner
 docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
 ```
 
-您可能注意到上面的命令都是不完整的，因为现在还不是运行Act Runner的时候。
-在运行Act Runner之前，我们需要首先将其注册到您的Gitea实例中。
+您可能注意到上面的命令都是不完整的，因为现在还不是运行 Runner 的时候。
+在运行 Runner 之前，我们需要首先将其注册到您的Gitea实例中。
 
 ## 注册
 
-在运行Act Runner之前，需要进行注册，因为Runner需要知道从哪里获取Job，并且对于Gitea实例来说，识别Runner也很重要。
+在运行 Runner 之前，需要进行注册，因为Runner需要知道从哪里获取Job，并且对于Gitea实例来说，识别Runner也很重要。
 
 ### Runner级别
 
@@ -108,18 +108,34 @@ Runner级别决定了从哪里获取注册令牌。
 
 注册令牌也可以通过 Gitea 的 [命令行](../../administration/command-line.md#actions-generate-runner-token) 获得:
 
+```
+gitea --config /etc/gitea/app.ini actions generate-runner-token
+```
+
+用户也可以使用 `GITEA_RUNNER_REGISTRATION_TOKEN` 或 `GITEA_RUNNER_REGISTRATION_TOKEN_FILE` 环境变量以在 Gitea 启动时设置全局的注册令牌，例如：
+
+```
+openssl rand -hex 24 > /some-dir/runner-token
+export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
+./gitea --config ...
+```
+
+来自环境变量的令牌在通过 Web 界面或 API 重置(重新创建新令牌)前将一直有效。
+
+令牌可用于注册多个 Runner，直到使用 Web 界面中的令牌重置链接将其撤销并替换为新令牌。
+
 ### 注册Runner
 
-可以通过运行以下命令来注册Act Runner：
+可以通过运行以下命令来注册 Runner：
 
 ```bash
-./act_runner register
+./runner register
 ```
 
 或者，您可以使用 `--config` 选项来指定前面部分提到的配置文件。
 
 ```bash
-./act_runner --config config.yaml register
+./runner --config config.yaml register
 ```
 
 您将逐步输入注册信息，包括：
@@ -134,7 +150,7 @@ Runner级别决定了从哪里获取注册令牌。
 如果您想以非交互方式注册Runner，可以使用参数执行以下操作。
 
 ```bash
-./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
+./runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
 ```
 
 注册Runner后，您可以在当前目录中找到一个名为 `.runner` 的新文件。该文件存储注册信息。
@@ -145,7 +161,7 @@ Runner级别决定了从哪里获取注册令牌。
 
 ### 使用Docker注册Runner
 
-如果您使用的是Docker镜像，注册行为会略有不同。在这种情况下，注册和运行合并为一步，因此您需要在运行Act Runner时指定注册信息。
+如果您使用的是Docker镜像，注册行为会略有不同。在这种情况下，注册和运行合并为一步，因此您需要在运行 Runner 时指定注册信息。
 
 ```bash
 docker run \
@@ -158,13 +174,13 @@ docker run \
     -e GITEA_RUNNER_NAME=<runner_name> \
     -e GITEA_RUNNER_LABELS=<runner_labels> \
     --name my_runner \
-    -d gitea/act_runner:nightly
+    -d gitea/runner:nightly
 ```
 
 您可能注意到我们已将`/var/run/docker.sock`挂载到容器中。
-这是因为Act Runner将在Docker容器中运行Job，因此它需要与Docker守护进程进行通信。
+这是因为 Runner 将在Docker容器中运行Job，因此它需要与Docker守护进程进行通信。
 如前所述，如果要在主机上直接运行Job，可以将其移除。
-需要明确的是，这里的 "主机" 实际上指的是当前运行 Act Runner的容器，而不是主机机器本身。
+需要明确的是，这里的 "主机" 实际上指的是当前运行 Runner 的容器，而不是主机机器本身。
 
 ### 使用 Docker compose 运行 Runner
 
@@ -174,7 +190,7 @@ docker run \
 version: "3.8"
 services:
   runner:
-    image: gitea/act_runner:nightly
+    image: gitea/runner:nightly
     environment:
       CONFIG_FILE: /config.yaml
       GITEA_INSTANCE_URL: "${INSTANCE_URL}"
@@ -203,12 +219,12 @@ services:
 
 ```yaml
 cache:
-enabled: true
-dir: ""
-# 使用步骤 1. 获取的 LAN IP
-host: "192.168.8.17"
-# 使用步骤 2. 获取的端口号
-port: 8088
+  enabled: true
+  dir: ""
+  # 使用步骤 1. 获取的 LAN IP
+  host: "192.168.8.17"
+  # 使用步骤 2. 获取的端口号
+  port: 8088
 ```
 
 - 4.启动容器时, 将 Cache 端口映射至主机。
@@ -217,11 +233,20 @@ port: 8088
 docker run \
   --name gitea-docker-runner \
   -p 8088:8088 \
-  -d gitea/act_runner:nightly
+  -d gitea/runner:nightly
 ```
 
 ### 标签
 
+```mermaid
+flowchart TD
+    A[Workflow: runs-on: ubuntu-22.04] --> B[Runner 收到 Job 请求]
+    B --> C[匹配标签: ubuntu-22.04:docker://node:16-bullseye]
+    C --> D[启动 Docker 容器: node:16-bullseye]
+    D --> E[在容器中运行 Job 步骤]
+    E --> F[返回执行结果给 Gitea]
+```
+
 Runner的标签用于确定Runner可以运行哪些Job以及如何运行它们。
 
 默认标签为`ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`。
@@ -236,18 +261,16 @@ Runner的标签用于确定Runner可以运行哪些Job以及如何运行它们
 如果您想直接在主机上运行Job，您可以将其更改为`ubuntu-22.04:host`或仅`ubuntu-22.04`，`:host`是可选的。
 然而，我们建议您使用类似`linux_amd64:host`或`windows:host`的特殊名称，以避免误用。
 
-从 Gitea 1.21 开始，您可以通过修改 runner 的配置文件中的 `container.labels` 来更改标签（如果没有配置文件，请参考 [配置教程](#配置)），通过执行 `./act_runner daemon --config config.yaml` 命令重启 runner 之后，这些新定义的标签就会生效。
+从 Gitea 1.21 开始，您可以通过修改 runner 的配置文件中的 `container.labels` 来更改标签（如果没有配置文件，请参考 [配置教程](#配置)），通过执行 `./runner daemon --config config.yaml` 命令重启 runner 之后，这些新定义的标签就会生效。
 
 ## 运行
 
 注册完Runner后，您可以通过运行以下命令来运行它：
 
 ```bash
-./act_runner daemon
+./runner daemon
 # or
-./act_runner daemon --config config.yaml
+./runner daemon --config config.yaml
 ```
 
 Runner将从Gitea实例获取Job并自动运行它们。
-
-由于Act Runner仍处于开发中，建议定期检查最新版本并进行升级。

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/scoped-workflows.md

@@ -0,0 +1,119 @@
+---
+date: "2026-06-26T00:00:00+00:00"
+slug: "scoped-workflows"
+sidebar_position: 60
+---
+
+# 作用域工作流
+
+作用域工作流（Scoped Workflows）让你把 Actions 工作流集中维护在一个**源（source）**仓库中，并让它们自动在许多其他仓库上运行，而无需把工作流文件复制到每个仓库里。
+
+提交到源仓库作用域工作流目录下的工作流文件，会在该源所适用的每个仓库（称为**消费方（consuming）**仓库）上运行。每次运行都在**消费方仓库自身的上下文**中执行：使用它的 runner、密钥、`GITEA_TOKEN` 和分支，而工作流**内容则读取自源仓库**。这适用于在组织或实例范围内强制推行共享 CI：代码检查、安全扫描、合规或策略检查等。
+
+## 级别
+
+源仓库可以在两个级别注册：
+
+- **所有者级别（Owner level）**：由组织或用户注册。该源的工作流会在该组织或用户拥有的每个仓库上运行。
+- **实例级别（Instance level）**：由站点管理员注册。该源的工作流会在实例上的**每一个**仓库上运行。
+
+同一个仓库可以同时在两个级别注册；对于每个匹配的事件，它仍只会被评估一次。
+
+:::note
+实例级别的源适用于实例上的**每一个**仓库，且被设为必需（required）的源无法被选择退出（opt out）。检测会在每个仓库的每次事件上运行。请谨慎注册。
+:::
+
+## 配置
+
+作用域工作流存放在一个与常规工作流分开的目录中，由 `app.ini` 中 `[actions]` 段的 `SCOPED_WORKFLOW_DIRS` 控制：
+
+```ini
+[actions]
+SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
+```
+
+- 默认值为 `.gitea/scoped_workflows`。
+- 可以列出多个目录（以逗号分隔）。
+- **不得与** `WORKFLOW_DIRS`（常规工作流目录，默认为 `.gitea/workflows` 和 `.github/workflows`）**重叠**。
+- 留空意味着没有任何目录存放作用域工作流，因此不会找到也不会运行任何作用域工作流。设置页面仍会显示、源仍可注册，但不会有任何作用域工作流运行。
+
+把作用域工作流放在它们自己的目录中，意味着源仓库**自身**的 Actions 不受影响：只有 `SCOPED_WORKFLOW_DIRS` 下的文件才会被当作作用域工作流。
+
+## 从一个仓库提供作用域工作流
+
+1. 在准备作为源的仓库中，把工作流文件提交到其**默认分支**上的作用域工作流目录下，例如 `.gitea/scoped_workflows/lint.yaml`：
+
+   ```yaml
+   name: Lint
+   on: [push, pull_request]
+   jobs:
+     lint:
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v4
+         - run: echo "lint the consuming repository here"
+   ```
+
+2. 将该仓库注册为源：
+
+   - **组织**：*组织设置 -> Actions -> 作用域工作流*
+   - **用户**：*用户设置 -> Actions -> 作用域工作流*
+   - **实例（管理员）**：*管理后台 -> Actions -> 作用域工作流*
+
+   搜索并添加该仓库。此后，它的作用域工作流便会适用于该级别下的消费方仓库。
+
+源仓库也在它自己的作用域内，因此它会像其他消费方一样在自身上运行这些工作流。
+
+## 作用域工作流如何运行
+
+- 该运行属于**消费方**仓库，使用它的 runner、密钥、`GITEA_TOKEN` 和 ref。它在那里的表现与普通运行一致，包括重跑、日志和提交状态。
+- 工作流**内容读取自源**仓库，并钉定在事件发生时源默认分支的 commit 上。
+- 检测使用消费方仓库的事件，因此工作流的 `on:` 触发器（例如 `push` 和 `pull_request`）必须与该事件匹配。
+
+## 选择退出（Opting out）
+
+消费方仓库可以在其 **Actions** 页面（该工作流会显示在其源之下）禁用一个它不想要的作用域工作流。已被标记为**必需（required）**（见下文）的工作流，消费方仓库永远无法将其禁用，也无法选择退出。
+
+## 必需工作流与合并门禁
+
+在作用域工作流设置页面上，你可以把单个工作流标记为**必需（required）**，并为每个工作流给定一个或多个**状态检查模式（status-check patterns）**（每行一个 glob）。一个必需的作用域工作流：
+
+- 无法被消费方仓库禁用。
+- 会对合并请求（PR）形成合并门禁：消费方的 PR 只有在一个匹配**每一个**模式的提交状态都**通过**后才能合并（必须存在且通过，must-present-and-pass）。一个从不产生任何状态的必需检查会**阻止**合并，而不是被静默跳过，因此在消费方关闭 Actions 也无法绕过它。
+
+作用域运行产生的状态检查 context 形如：
+
+```
+<源仓库全名>: <工作流显示名> / <job> (<event>)
+```
+
+设置页面会为每个工作流预览这些 “Expected status checks（预期状态检查）”，并标记出与你的模式匹配的项，便于你确认模式是否正确。一种常见模式是对 job 和 event 使用通配符，例如 `my-org/ci-repo: Lint / *`。
+
+强制范围：
+
+- 必需检查会在任何设有**分支保护规则**的目标分支上强制生效，即使该规则自身的状态检查处于关闭状态。
+- **没有**保护规则的目标分支不受门禁约束。
+
+:::warning
+只有运行在会产生提交状态的事件（`push`、`pull_request`、`pull_request_target`、`release`）上的工作流才能被设为必需。仅运行在 `workflow_dispatch`、`schedule` 或 `workflow_call` 等事件上的工作流不会产生任何状态，因此把它设为必需会**永久**阻止每一个消费方 PR 的合并。设置页面在这种情况下会向你发出警告。
+:::
+
+## 可复用工作流（`uses:`）
+
+作用域工作流可以调用可复用工作流：
+
+- **本地**引用（`uses: ./...`）会相对于**源**仓库解析：即调用方工作流内容的来源仓库，而非消费方仓库。
+- **跨仓库**引用（`uses: owner/repo/...@ref`）会以**消费方仓库的**读取权限来解析。如果它指向一个私有仓库，请确保每个消费方仓库都能读取它，否则工作流会在那里失败。
+
+可复用工作流可以放在源仓库的 `SCOPED_WORKFLOW_DIRS`（或 `WORKFLOW_DIRS`）之下。
+
+## 安全注意事项
+
+源仓库的工作流内容会在它所适用的每个仓库中执行，其步骤脚本及其输出会写入该仓库的 Actions 日志，任何能查看消费方仓库 Actions 的人都能读取这些日志。
+
+- 因此，将一个**私有**仓库注册为源，会通过这些日志泄露其工作流逻辑。只应注册那些其工作流内容可以与每个消费方仓库共享的仓库。
+
+## 限制
+
+- 目前不支持将 `on: schedule` 和 `on: workflow_run` 作为作用域工作流触发器。
+- 作用域工作流内容读取自源的默认分支；源的其他分支不会被使用。

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/issues-prs/_category.json

@@ -0,0 +1,9 @@
+{
+  "label": "工单 和 合并请求",
+  "position": 20,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/issues-prs",
+    "description": "工单 和 合并请求 工作流，模板，和协作功能"
+  }
+}