ci: only read the Depends on lines, and let the label be the gate

ci: keep the jq expressions parsable on jq 1.6
ci: run the check with the script from the pull request
2026-11-07 02:20:31 +00:00 · 2026-09-08 12:03:59 -07:00 · 2026-09-08 12:00:37 -07:00 · 2026-09-08 11:58:23 -07:00 · 2026-09-08 11:50:21 -07:00
1902 changed files with 10222 additions and 126730 deletions
@@ -8,7 +8,7 @@ on:
 jobs:
  build-docs:
-    runs-on: ubuntu-26.04
+    runs-on: ubuntu-24.04
    env:
      NODE_OPTIONS: --max-old-space-size=8192
      # search only appears once the credentials are set, the build falls back
@@ -19,13 +19,13 @@ jobs:
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
-      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
-          node-version: 26
+          node-version: 24
          cache: pnpm
      - name: prepare awesome list
        run: |
-          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 prepare-awesome-v28
+          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
@@ -0,0 +1,48 @@
 # The status check context of this job is "checks / depends-upstream
 # (pull_request)", which the required status check `checks / *` of the protected
 # main branch matches, so a pull request waiting for gitea cannot be merged.
 # It is a workflow of its own so that a label change does not cancel the build
 # and the preview deployment of the `checks` workflow in test.yaml.
 #
 # The check script comes from the pull request, like the workflow file itself:
 # `pull_request` runs both from the head, so taking the script from the base
 # branch would not gain anything and would leave this workflow unable to run on
 # the pull request that adds it.
 name: checks
 on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - edited
      - labeled
      - unlabeled
 concurrency:
  group: depends-upstream-${{ github.event.pull_request.number }}
  cancel-in-progress: true
 jobs:
  depends-upstream:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - name: check the upstream dependencies
        env:
          PR_NUMBER: ${{ github.event.pull_request.number }}
          # optional, only lifts the rate limit of the unauthenticated github api
          GITHUB_COM_TOKEN: ${{ secrets.GITHUB_COM_TOKEN }}
        run: |
          set -euo pipefail
          # read the description and the labels from the api instead of the
          # event context, so nothing from a pull request body is expanded into
          # this script
          api="${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY"
          curl --silent --show-error --fail --output pull.json "$api/pulls/$PR_NUMBER"
          ./scripts/check-upstream-deps.sh pull.json
@@ -16,13 +16,13 @@ jobs:
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
-      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
-          node-version: 26
+          node-version: 24
          cache: pnpm
      - name: prepare awesome list
        run: |
-          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 prepare-awesome-v28
+          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
      - name: install dependencies
        run: pnpm install --frozen-lockfile
@@ -45,7 +45,7 @@ jobs:
          # pull requests from forks do not get the secrets, the build above is
          # then the only check and the preview is silently skipped
          if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
-            echo "::notice::no Cloudflare credentials available (pull request from a fork?), skipping the preview deployment"
+            echo "no Cloudflare credentials available, skipping the preview deployment"
            exit 0
          fi
@@ -0,0 +1,29 @@
 name: unlabel merged upstream dependencies
 on:
  schedule:
    - cron: '15 */6 * * *' # every 6 hours, quarter past
  workflow_dispatch:
 jobs:
  unlabel:
    if: github.repository == 'gitea/docs'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - name: drop the label from the pull requests upstream caught up with
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
          GITHUB_COM_TOKEN: ${{ secrets.GITHUB_COM_TOKEN }}
        run: |
          set -euo pipefail
          if [ -z "${DEPLOY_TOKEN:-}" ]; then
            echo "secrets.DEPLOY_TOKEN is missing, cannot remove the label"
            exit 1
          fi
          export GITEA_API="${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY"
          ./scripts/unlabel-upstream-deps.sh
@@ -2,7 +2,7 @@ name: update api spec files
 on:
  schedule:
-    - cron: '0 3 * * 1' # every Monday at 03:00
+    - cron:  '0 */12 * * *' # every 12 hours on the hour
  workflow_dispatch:
 env:
@@ -6,6 +6,7 @@ sites/*/dist
 sites/*/.astro
 sites/*/.cache
 build/
 .docusaurus/
 # Misc
 .DS_Store
@@ -12,30 +12,20 @@ create_dir:
 clone_awesome: create_dir
 	git clone --branch=$(GITEA_AWESOME_BRANCH) $(GITEA_AWESOME_REMOTE) .tmp/upstream-awesome || true
 # the contributing guide moved to the gitea repository, the readme of
 # awesome-gitea still links to it with a relative path
 AWESOME_CONTRIBUTING_URL := https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md
 FIX_AWESOME_LINKS := sed 's|](contributing.md)|]($(AWESOME_CONTRIBUTING_URL))|'
 .PHONY: prepare-awesome-latest
 prepare-awesome-latest: clone_awesome
-	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > docs/awesome.md
+	cp .tmp/upstream-awesome/README.md docs/awesome.md
 .PHONY: prepare-awesome\#%
 prepare-awesome\#%:
-	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > versioned_docs/version-1.$*/awesome.md
+	cp .tmp/upstream-awesome/README.md  versioned_docs/version-1.$*/awesome.md
 # versions numbered without the 1. prefix, like 28
 .PHONY: prepare-awesome-v%
 prepare-awesome-v%:
 	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > versioned_docs/version-$*/awesome.md
 .PHONY: install
 install:
 	pnpm install
 .PHONY: prepare-docs
-prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27 prepare-awesome-v28
+prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27
 .PHONY: build
 build:
@@ -92,7 +82,7 @@ update-runner-docs:
 update-runner-docs-released:
 	./update_runner_docs.sh --released
-# freezes the current docs, runner or cli tree as a new version, see
+# freezes the current docs or runner tree as a new version, see
 # scripts/cut-version.mjs
 .PHONY: cut-version
 cut-version:
@@ -3,14 +3,13 @@
 The sources of [docs.gitea.com](https://docs.gitea.com), built with
 [Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
-The site covers four products, all served from this repository:
+The site covers three products, all served from this repository:
 | Product | Content | Versions | Languages |
 | --- | --- | --- | --- |
-| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 28, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
+| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
-| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 28, 1.27 … 1.22 | English |
+| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 1.27 … 1.22 | English |
-| Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 5 … 0 | English |
+| Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 3 … 0 | English |
 | CLI | `cli-docs/`, `cli-docs_versioned_docs/` | develop | English |
 The enterprise documentation is built and deployed from its own repository and
 reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere
@@ -49,12 +48,43 @@ The order of the top level sidebar groups comes from `sidebars.js` (and
 `versioned_sidebars/` for released versions), the label and order of every other
 group from the `_category_.json` of its directory.
 ### Documenting an unreleased feature
 A page that describes a gitea change which is not merged yet must wait for it,
 otherwise the site documents something no release has. Say so in the description
 of the pull request, on a line of its own, and add the `depends-on-upstream`
 label:
 ```
 Depends on: gitea#35851
 ```
 The label is what blocks the merge: the `depends-upstream` check fails while it
 is set, unless every dependency is verified as merged, and `main` requires the
 `checks` contexts. The check reads the `Depends on:` lines (`gitea#<id>` or the
 full pull request url, several lines are allowed) to find out what to wait for,
 so the label needs at least one of them. A `gitea#<id>` mentioned anywhere else
 in the description is ignored.
 Without the label, a dependency that the check finds unmerged still fails it, so
 forgetting the label does not let an unreleased feature through.
 The `unlabel merged upstream dependencies` job runs every 6 hours, removes the
 label once every referenced pull request is merged and comments on the pull
 request, which reruns the check. `scripts/check-upstream-deps.sh` is the check
 itself and can be run locally against the json of a pull request.
 The check asks the github api whether a pull request is merged, and the runners
 share the 60 requests per hour it allows without authentication. The optional
 `GITHUB_COM_TOKEN` secret (a token without scopes is enough) raises that limit;
 without it an unverifiable dependency only fails the check when the label is
 set.
 ## Cutting a version
 ```shell
 make cut-version PRODUCT=docs VERSION=1.28
-make cut-version PRODUCT=runner VERSION=6
+make cut-version PRODUCT=runner VERSION=4
 make cut-version PRODUCT=cli VERSION=0.1
 ```
 This freezes the current tree, its translations and its sidebar. The label of
@@ -81,7 +111,7 @@ make update-api-docs-latest  # refresh only the documents of gitea main
 ```
 The documents of gitea main are refreshed automatically: the `update api spec
-files` workflow runs weekly and opens a pull request whenever gitea main
+files` workflow runs every 12 hours and opens a pull request whenever gitea main
 changed. Released versions are updated by hand when a new gitea version is
 documented.
@@ -90,8 +120,8 @@ documented.
 | Version | Content | URL |
 | --- | --- | --- |
 | develop | `runner-docs/` | `/runner/develop/` |
-| current series | `runner-docs_versioned_docs/version-5/` | `/runner/` |
+| current series | `runner-docs_versioned_docs/version-3/` | `/runner/` |
-| older series | `runner-docs_versioned_docs/version-4/` | `/runner/4/` |
+| older series | `runner-docs_versioned_docs/version-2/` | `/runner/2/` |
 A version directory covers a whole release series (`version-3` documents every
 `3.x` release), so a patch release only needs a content update, not a new
@@ -103,8 +133,7 @@ Its sidebar is written by hand: `runner-sidebars.js` for develop, and
 version.
 The pages under `reference/` are generated from the runner sources — the command
-line reference from `--help`, the example configuration from `config generate`
+line reference from `--help`, the example configuration from `generate-config`:
 (`generate-config` before 3.1):
 ```shell
 make update-runner-docs           # develop docs, from the main branch of gitea/runner
@@ -117,16 +146,6 @@ workflow runs weekly and opens a pull request whenever the runner's CLI or
 example configuration changed. Generating them needs Go, since the script builds
 the runner binary.
 ## CLI docs
 The documentation of `gt`, the Gitea CLI from
 [gitea/cli](https://gitea.com/gitea/cli), is laid out like the runner docs, with
 its sidebar in `cli-sidebars.js`. No series is documented yet, so `cli-docs/` is
 served at `/cli/`. Once a release exists, cut its series and list it in
 `cliSeries` in `packages/content-loader/src/products.ts`, which moves the develop
 docs to `/cli/develop/`. The guides leave the flags of each command to
 `gt <command> --help`.
 ## Deployment
 `main` is built and published by the `Build and Publish Docs site` workflow, to
@@ -1,55 +0,0 @@
 ---
 sidebar_position: 3
 ---
 # Logging in
 On a terminal, `gt auth login` asks for the instance and how to log in. gt never asks for
 your password.
 ## OAuth in a browser
 ```bash
 gt auth login --host https://gitea.example.com --oauth
 ```
 gt opens the instance's authorization page, so single sign-on and two-factor
 authentication work as on the web. The browser has to run on the same machine as gt.
 `--scopes` limits the token to fewer [scopes](/development/oauth2-provider#scopes); gt
 refreshes OAuth tokens on its own.
 ## Access token
 Create a token under **Settings > Applications** on the instance and pass it on stdin:
 ```bash
 gt auth login --host https://gitea.example.com --with-token < token.txt
 ```
 The token needs `read:user`, and the scopes of what you do with gt, such as
 `write:repository` and `write:issue` for working on pull requests.
 ## SSH key
 gt can sign its requests with an SSH key registered for your account instead of using a
 token:
 ```bash
 gt auth login --host https://gitea.example.com --ssh-key ~/.ssh/id_ed25519
 ```
 ## Accounts
 Tokens go to the system keyring, or with `--credential-store file` to gt's configuration
 directory on machines without one. Run `gt auth login` once per instance and account.
 gt picks the instance from the repository's remote or `--host`, and the account with
 `gt auth switch` or `--user`. `gt auth status` lists your accounts and `gt auth logout`
 removes one.
 For instances behind an access proxy, `--header` and `--client-cert` add headers and a
 client certificate.
 ## Git over HTTPS
 `gt auth setup-git` lets `git push` and `git fetch` over HTTPS use gt's login. gt's own
 clone and checkout commands need no setup.
@@ -1,40 +0,0 @@
 ---
 sidebar_position: 4
 ---
 # Using gt in CI
 Give gt a token and an instance through the environment, and turn prompts off:
 | Variable | Description |
 | --- | --- |
 | `GITEA_TOKEN` | Access token; gt never stores it |
 | `GITEA_CLI_HOST` or `GITEA_INSTANCE_URL` | URL of the instance |
 | `GITEA_CLI_REPO` | Repository, like `--repo` |
 `--no-input` makes a command fail instead of prompting, and `--yes` confirms changes in
 advance.
 ## Gitea Actions
 Gitea does not allow secret names that start with `GITEA_`, so store the token as, for
 example, `GT_TOKEN`:
 ```yaml
 on:
  push:
    branches: [main]
 jobs:
  staging:
    runs-on: ubuntu-latest
    env:
      GITEA_TOKEN: ${{ secrets.GT_TOKEN }}
      GITEA_CLI_HOST: ${{ gitea.server_url }}
      GITEA_CLI_REPO: ${{ gitea.repository }}
    steps:
      - run: curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
      - run: gt workflow run deploy.yml --ref main --field env=staging --no-input
 ```
 `gt run watch` and `gt pr checks --watch` wait for runs and checks and fail when one fails.
@@ -1,38 +0,0 @@
 ---
 sidebar_position: 1
 slug: /
 ---
 # Gitea CLI
 [gt](https://gitea.com/gitea/cli) is the official command line client for Gitea. It works
 with repositories, issues, pull requests, releases, Actions and the other resources of a
 Gitea instance, from a terminal or a script.
 :::info Development version
 These pages describe builds from the `main` branch, published as `nightly` binaries and images.
 :::
 gt needs Gitea 28 or later, and Git for the commands that clone, check out or push.
 ## Getting started
 1. [Install gt](installation.md).
 2. [Log in](authentication.md):
   ```bash
   gt auth login
   ```
 3. Run commands in a clone of a repository on that instance, or select one with `--repo`:
   ```bash
   gt issue list --label bug
   gt pr checkout 13
   gt issue view 42 --repo gitea.com/gitea/cli
   ```
 `gt doctor` checks your setup and suggests a fix for each problem it finds.
 `gt <command> --help` lists the flags of a command, and `gt help environment` the global
 flags and environment variables.
@@ -1,37 +0,0 @@
 ---
 sidebar_position: 2
 ---
 # Installation
 gt is a single binary for Linux, macOS, Windows and FreeBSD.
 ## Install script
 The install script downloads gt from [dl.gitea.com](https://dl.gitea.com/gitea-cli/),
 verifies its checksum and installs it.
 ```bash
 # Linux, macOS, FreeBSD
 curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
 ```
 ```powershell
 # Windows
 irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex
 ```
 Set `GITEA_CLI_VERSION` to install a specific version, or `nightly` for the latest build
 of `main`.
 ## Other ways
 - **Binaries:** download them from [dl.gitea.com/gitea-cli](https://dl.gitea.com/gitea-cli/).
 - **Docker:** the [`gitea/gitea-cli`](https://hub.docker.com/r/gitea/gitea-cli) image runs
  `gt` as its entry point.
 - **Go:** `go install gitea.dev/cli/cmd/gt@latest`
 ## Shell completion and man pages
 `gt completion <shell>` prints the completion script for bash, zsh, fish or PowerShell;
 `gt completion <shell> --help` shows how to load it. `gt man` prints the manual.
@@ -1,22 +0,0 @@
 ---
 sidebar_position: 5
 ---
 # Output and scripting
 Scripts should read JSON: the text output is meant for people and may change.
 ```bash
 gt pr view 123 --json number,title,state
 gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
 ```
 `--json` prints all fields or the ones you list; the **JSON FIELDS** section of a command's
 `--help` names them. `--jq` filters the result without needing jq installed. Piped lists
 print as tab-separated values.
 gt exits with 0 on success, 1 when a command fails, 2 on a usage error and 4 when
 authentication is missing or rejected; `gt help exit-codes` lists all codes.
 `gt api` calls any API endpoint with gt's login, and `gt alias set` defines shortcuts for
 commands you use often.
@@ -1 +0,0 @@
 []
@@ -1,16 +0,0 @@
 // Sidebar of the gt (Gitea CLI) documentation (develop version).
 // Released versions carry their own copy in
 // cli-docs_versioned_sidebars/version-<version>-sidebars.json.
 module.exports = {
  cli: [
    {
      type: 'doc',
      id: 'index',
      label: 'What is gt?',
    },
    'installation',
    'authentication',
    'ci',
    'scripting',
  ],
 };
@@ -2,8 +2,8 @@
 # is copied into the build output by the publish workflow, so that it is not
 # uploaded to S3/CloudFront where it would be publicly readable at /_headers.
 #
-# The build emits a single content hashed asset directory shared by every
+# Unlike the docusaurus build, astro emits a single content hashed asset
-# language, so no per locale rules are needed.
+# directory shared by every language, so no per locale rules are needed.
 # Content hashed build output (js, css, fonts). The file name changes with the
 # content, so these can be cached forever.
@@ -1,19 +1,17 @@
 # Redirects for legacy URLs and routes the site no longer serves directly.
-# The api reference, the runner and the cli docs are separate products,
+# The api reference and the runner docs are separate products, published in
-# published in english only, so they have no localized copy.
+# english only. Docusaurus served an empty localized copy of them.
 /zh-cn/api/* /api/:splat 301
 /zh-tw/api/* /api/:splat 301
 /zh-cn/runner/* /runner/:splat 301
 /zh-tw/runner/* /runner/:splat 301
 /zh-cn/cli/* /cli/:splat 301
 /zh-tw/cli/* /cli/:splat 301
 # The version served at the root of a product is also reachable under its
 # number, which is what the release notes and old links use.
-/api/28/* /api/:splat 301
+/api/1.27/* /api/:splat 301
 /runner/3/* /runner/:splat 301
-/28/* /:splat 301
+/1.27/* /:splat 301
 # The local search plugin had a results page of its own, algolia docsearch is a
 # modal opened from any page.
@@ -7,7 +7,6 @@
    "https://docs.gitea.com/zh-cn/",
    "https://docs.gitea.com/zh-tw/",
    "https://docs.gitea.com/runner/",
    "https://docs.gitea.com/cli/",
    "https://docs.gitea.com/api/",
    "https://docs.gitea.com/enterprise/"
  ],
@@ -16,8 +15,7 @@
    "https://docs.gitea.com/1.2*/**",
    "https://docs.gitea.com/*/1.2*/**",
    "https://docs.gitea.com/api/1.2*/**",
-    "https://docs.gitea.com/runner/[0-9]/**",
+    "https://docs.gitea.com/runner/[0-9]/**"
    "https://docs.gitea.com/cli/[0-9]*/**"
  ],
  "selectors": {
    "lvl0": { "selector": "//nav[contains(@aria-labelledby,'starlight__sidebar')]//a[@aria-current='page']/ancestor::details//summary//span", "type": "xpath", "global": true, "default_value": "Documentation" },
@@ -1,153 +0,0 @@
 ---
 date: "2026-09-12T00:00:00+00:00"
 slug: "audit-logging"
 sidebar_position: 41
 aliases:
  - /en-us/audit-logging
 ---
 # Audit Logging
 Gitea can record security-relevant events as structured audit records: each
 event has an `action`, `actor`, `scope`, `origin`, `message` and a JSON
 `metadata` blob. Recording is **off by default** and does not change request
 behavior when it is disabled.
 This is separate from the application, router and access logs described in
 [Logging Configuration](logging-config.md). Those logs are for operations and
 debugging. The audit log is a durable trail of who changed what.
 ## Enable recording
 Set `[audit].RECORD_OUTPUT` to `database` in `app.ini` and restart Gitea:
 ```ini
 [audit]
 RECORD_OUTPUT = database
 RETENTION_DAYS = 30
 ```
 Invalid values of `RECORD_OUTPUT` fall back to `disabled`. See the
 [configuration cheat sheet](config-cheat-sheet.md#audit-audit) for every option.
 With Docker, the same settings can be applied as
 `GITEA__audit__RECORD_OUTPUT=database` and `GITEA__audit__RETENTION_DAYS=30`
 before Gitea writes them into `app.ini`.
 ## View events
 The Audit Log pages are always available and still list any events that were
 stored earlier. When recording is disabled, the site administration page also
 shows a warning.
 | Audience | Location | Events shown |
 | --- | --- | --- |
 | Site administrators | Site administration → Monitoring → Audit Log (`/-/admin/monitor/audit_logs`) | Every event |
 | Signed-in users | User settings → Audit Log (`/user/settings/audit_logs`) | Events scoped to that user |
 | Organization owners | Organization settings → Audit Log (`/<org>/settings/audit_logs`) | Events scoped to that organization |
 | Repository administrators | Repository settings → Audit Log (`/<owner>/<repo>/settings/audit_logs`) | Events scoped to that repository |
 Each listing can be filtered by actor (username), action and origin, and sorted
 by timestamp. The actor filter does not match the
 [system actors](#actors-and-origins). Action filters accept an exact action or
 a family prefix such as `user:impersonation` or `repository:webhook`.
 Site administrators can download the current filtered result as JSONL
 (newline-delimited JSON) from **Export JSONL**. The file name is
 `gitea-audit-log-<timestamp>.jsonl`.
 ## Event shape
 A recorded event contains:
 - **Action**: a stable, colon-separated identifier such as `repository:archive`
  or `user:accesstoken:add`.
 - **Actor**: the user who performed the action. Actions taken while impersonating
  a user record both the impersonator and the impersonated user.
 - **Actor credential**: when the request authenticated with a named credential,
  the event stores its kind and id, never the secret. Typical values:
  `access-token:<id>`, `oauth2-grant:<id>`, `gitea-actions:<task id>`,
  `deploy-key:<key id>`.
 - **Scope**: the affected unit — `user`, `organization`, `repository` or
  `system` (instance-wide).
 - **Origin**: how the action was initiated — `ui`, `api`, `cli` or `system`.
 - **Message**: a human-readable sentence rendered from a per-action template.
 - **Metadata**: extra fields that fill the message template (token name, new
  visibility, and so on). Secrets and token values are not stored.
 - **IP address**: the client address of the request, when one exists. Events
  triggered by a git push record the SSH client address for SSH pushes and
  `127.0.0.1` for HTTP pushes.
 - **Timestamp**: when the event was recorded.
 An exported JSONL line looks like:
 ```json
 {"action":"repository:archive","actor":{"type":"user","id":1,"name":"alice"},"scope":{"type":"repository","id":42,"name":"org/repo"},"message":"Archived repository org/repo.","time":"2026-09-12T11:00:00Z","ip_address":"203.0.113.10","origin":"ui"}
 ```
 The `system:startup` message is kept stable across Gitea versions so operators
 can parse it: `System started [Gitea {version}]`.
 ## Actors and origins
 Most web and API requests pick up the signed-in user automatically.
 Other entry points record a system actor:
 - `gitea:cli` for `gitea admin` commands and the `system:startup` and
  `system:shutdown` events
 - `gitea:auth-source` for authentication-source syncs and for users an
  authentication source creates or updates at sign-in
 - `gitea-actions` for Gitea Actions tasks
 - `gitea:deploy-key` for pushes with a deploy key
 - `(Cron)` for scheduled cron tasks
 - `Unknown` when no actor can be resolved
 Events of the `gitea:cli` actor use origin `cli`. Cron tasks, git hooks and
 other background work use origin `system`.
 ## What is recorded
 Events cover security-relevant changes, grouped by action family:
 - **User**: create and delete, admin, restricted and active status, name,
  password and password reset requests, visibility, emails, authentication
  source, 2FA, WebAuthn, OpenID, external logins, access tokens, OAuth2
  applications and grants, SSH/GPG/principal keys, secrets, webhooks,
  impersonation, failed two-factor authentication
 - **Organization**: create and delete, name, visibility, members, teams,
  OAuth2 applications, secrets, webhooks
 - **Repository**: create, fork, archive, delete, rename, visibility, transfer,
  mirrors, signing verification, collaborators and teams, default branch,
  branch and tag protection, deploy keys, webhooks, secrets
 - **Issues and pull requests**: create, delete, comments and merges
 - **Projects and wiki pages**: create, update and delete
 - **Actions**: enable, disable and dispatch a workflow
 - **System**: startup and shutdown, instance-wide webhooks, authentication
  sources, instance-wide OAuth2 applications
 Recording never fails the request that triggered it. A write error is logged
 and the original operation continues.
 ## What is not recorded
 - Read-only access such as browsing, clone, fetch or API GET requests
 - Logins, successful or failed, other than failed two-factor authentication
  (use the [access log](logging-config.md) and
  [Fail2ban Setup](fail2ban-setup.md) for authentication traffic)
 - Edits to issues and pull requests
 - Token or secret values
 - Which SSH key a real user pushed with (deploy keys are named; ordinary SSH
  user pushes are not)
 ## Retention
 `RETENTION_DAYS` (default **30**) is the age after which recorded events are
 eligible for deletion. Set it to `0` to keep events forever.
 Cleanup is performed by the `cron.delete_old_audit_events` task (`SCHEDULE`
 defaults to `@every 24h`, `OLDER_THAN` defaults to `[audit].RETENTION_DAYS`).
 The task is registered only while `RECORD_OUTPUT` records events **and**
 `RETENTION_DAYS` is greater than `0`. Turning recording off therefore also
 stops pruning; existing rows stay until you delete them or turn recording back
 on.
@@ -337,13 +337,9 @@ The default login user email is `X-WEBAUTH-EMAIL`, you can change it via changin
 If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`.
-It applies to the web interface, Git over HTTP, Git LFS and the package registry.
+You can also limit the reverse proxy's IP address range with `REVERSE_PROXY_TRUSTED_PROXIES` which default value is `127.0.0.0/8,::1/128`. By `REVERSE_PROXY_LIMIT`, you can limit trusted proxies level.
-:::warning
+You can enable the this authentication method for the API with
 Gitea trusts these headers on every request it receives. Make sure Gitea is only reachable through your authenticating proxy, and that the proxy sets or removes these headers on every request, including on paths you exempt from authentication, for example for Git or package clients. `REVERSE_PROXY_TRUSTED_PROXIES` does not restrict them.
 :::
 To also accept them on the REST API under `/api/v1`, enable:
 ```ini
 [service]
@@ -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
@@ -130,8 +130,8 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
   HTTP protocol.
 - `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when
   default SSH port is used.
- `GO_GET_CLONE_URL_PROTOCOL`: **_empty_**: Scheme of the returned URL for the "go get" response.
+- `GO_GET_CLONE_URL_PROTOCOL`: **https**: Value for the "go get" request returns the repository url as https or ssh
-   Default is "https" if DISABLE_HTTP_GIT=false or SSH is disabled, otherwise "ssh".
+   default is https.
 - `ACCESS_CONTROL_ALLOW_ORIGIN`: **_empty_**: Value for Access-Control-Allow-Origin header,
   default is not to present.
@@ -179,7 +179,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
 - `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.
 - `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`: **true**: Set the default value for "Delete pull request branch after merge by default" for new repositories.
+- `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.
@@ -270,10 +270,9 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `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, pull requests and comments.
+- `REACTIONS`: All available reactions users can choose on issues/prs and comments
    Values can be emoji alias (:smile:) or a unicode emoji.
    For custom reactions, add a tightly cropped square image to public/assets/img/emoji/reaction_name.png
 - `RELEASE_REACTIONS`: **+1, laugh, hooray, heart, rocket, eyes**: Reactions available for releases, in the same format as `REACTIONS`.
 - `REACTION_MAX_USER_NUM`: **10**: Change the number of users that are displayed in reactions tooltip (triggered by mouse hover).
 - `CUSTOM_EMOJIS`: **gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the utf8 standard.
    By default, we support Gitea (:gitea:), to add more copy them to public/assets/img/emoji/emoji_name.png and
@@ -349,7 +348,8 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `PROXY_PROTOCOL_TLS_BRIDGING`: **false**: When protocol is https, expect PROXY protocol headers after TLS negotiation.
 - `PROXY_PROTOCOL_HEADER_TIMEOUT`: **5s**: Timeout to wait for PROXY protocol header (set to 0 to have no timeout)
 - `PROXY_PROTOCOL_ACCEPT_UNKNOWN`: **false**: Accept PROXY protocol headers with Unknown type.
- `ROOT_URL`: **`{PROTOCOL}://localhost:{HTTP_PORT}/`**:
+- `DOMAIN`: **localhost**: Domain name of this server.
 - `ROOT_URL`: **`{PROTOCOL}://{DOMAIN}:{HTTP_PORT}/`**:
   Overwrite the automatically generated public URL.
   This is useful if the internal and the external URL don't match (e.g. behind a reverse proxy).
 - `PUBLIC_URL_DETECTION`: **`auto`**: Controls how to generate the public URL. Most instances should use the "auto" behavior,
@@ -404,7 +404,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
  If it is set to `(DOER_USERNAME)`, it will use current signed-in user's username.
  This option is only for some advanced users who have configured their SSH reverse-proxy and need to use different usernames for git SSH clone.
  Most users should just leave it blank and/or modify the `BUILTIN_SSH_SERVER_USER`.
- `SSH_DOMAIN`: **_empty_**: Domain name to be exposed in clone URL, defaults to the domain part of ROOT_URL
+- `SSH_DOMAIN`: **`{DOMAIN}`**: Domain name of this server, used for displayed 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.
@@ -420,7 +420,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `SSH_SERVER_CIPHERS`: **`chacha20-poly1305@openssh.com`, `aes128-ctr`, `aes192-ctr`, `aes256-ctr`, `aes128-gcm@openssh.com`, `aes256-gcm@openssh.com`**: For the built-in SSH server, choose the ciphers to support for SSH connections, for system SSH this setting has no effect.
 - `SSH_SERVER_KEY_EXCHANGES`: **curve25519-sha256, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group14-sha256, diffie-hellman-group14-sha1**: For the built-in SSH server, choose the key exchange algorithms to support for SSH connections, for system SSH this setting has no effect.
 - `SSH_SERVER_MACS`: **`hmac-sha2-256-etm@openssh.com`, `hmac-sha2-256`, `hmac-sha1`**: For the built-in SSH server, choose the MACs to support for SSH connections, for system SSH this setting has no effect
- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gitea.ed25519, ssh/gitea.ecdsa, ssh/gogs.rsa**: For the built-in SSH server, choose the keypairs to offer as the host key. The private key should be at `SSH_SERVER_HOST_KEY` and the public `SSH_SERVER_HOST_KEY.pub`. Relative paths are made absolute relative to the `APP_DATA_PATH`. If none of the keys exist, a 4096 bit RSA, a 256 bit ECDSA and an ED25519 key will be created for you.
+- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gogs.rsa**: For the built-in SSH server, choose the keypairs to offer as the host key. The private key should be at `SSH_SERVER_HOST_KEY` and the public `SSH_SERVER_HOST_KEY.pub`. Relative paths are made absolute relative to the `APP_DATA_PATH`. If no key exists a 4096 bit RSA key will be created for you.
 - `SSH_KEY_TEST_PATH`: **/tmp**: Directory to create temporary files in when testing public keys using ssh-keygen, default is the system temporary directory.
 - `SSH_KEYGEN_PATH`: **_empty_**: Use `ssh-keygen` to parse public SSH keys. The value is passed to the shell. By default, Gitea does the parsing itself.
 - `SSH_EXPOSE_ANONYMOUS`: **false**: Enable exposure of SSH clone URL to anonymous visitors, default is false.
@@ -587,7 +587,8 @@ And the following unique queues:
 - `SECRET_KEY`: **\<random at every install\>**: Global secret key. This key is VERY IMPORTANT, if you lost it, the data encrypted by it (like 2FA secret) can't be decrypted anymore.
 - `SECRET_KEY_URI`: **_empty_**: Instead of defining SECRET_KEY, this option can be used to use the key stored in a file (example value: `file:/etc/gitea/secret_key`). It shouldn't be lost like SECRET_KEY.
 - `LOGIN_REMEMBER_DAYS`: **31**: How long to remember that a user is logged in before requiring relogin (in days).
- `COOKIE_REMEMBER_NAME`: **gitea\_remember**: Name of cookie used to store authentication information.
+- `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.
@@ -595,8 +596,7 @@ And the following unique queues:
   authentication provided email.
 - `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: Header name for reverse proxy
   authentication provided full name.
- `REVERSE_PROXY_LIMIT`: **1**: Interpret the X-Real-IP, X-Forwarded-For or Forwarded header, in that order, and set this as the remote IP for the request.
+- `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.
   The client port is taken from the header value or, with X-Real-IP, from X-Real-Port.
   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]`.
@@ -647,30 +647,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.
- `EGRESS_MODE`: **lax**: Egress mode toggles between strictness of outgoing requests:
+- `ALLOWED_HOST_LIST`: **external**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list.
  - `lax` non-public targets (private, loopback, link-local, CGNAT and special-use ranges) to be allowed, it allows all public ones
  - `strict` requires an explicit allow of all addresses
 - `ALLOWED_HOST_LIST`: **_empty_**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list, eg: `192.168.1.0/24:3000`, `[2001:db8::/32]:9090`, `*.mydomain.com:[80|443]`
  - Built-in networks:
    - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6, localhost is included.
-    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), RFC 4193 (FC00::/7) and RFC 6598 CGNAT (100.64.0.0/10). Also called LAN/Intranet.
+    - `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.
-  - CIDR list: `1.2.3.0/8`, `2001:db8::/32`, and with a port `[2001:db8::/32]:9090` (IPv6 addresses and CIDRs need brackets when a port is given)
+    - `external`: A valid non-private unicast IP, you can access all hosts on public internet.
-  - Host matching: `example.com` matches the host and any subdomain, dot-anchored so `notexample.com` never matches. `*.example.com` and `.example.com` match only subdomains, the apex itself is excluded. IDN names must be given as punycode.
+    - `*`: All hosts are allowed.
-  - All addresses can have ports specified. Accepted port specs:
+  - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6
-    - a single port: `192.168.1.0/24:3000`
+  - Wildcard hosts: `*.mydomain.com`, `192.168.100.*`
    - a range, both bounds inclusive: `*.mydomain.com:3000-3010`
    - a bracketed set of ports and ranges, `|` separated: `*.mydomain.com:[80|443|3000-3010]`
    - all ports: `*.mydomain.com:*`
  - A portless entry covers all ports in `lax` mode, only 80 and 443 in `strict` mode
  - Port specs apply only where the list is consulted: in `lax` mode that is non-public targets alone, public targets are allowed on every port whatever the list says. In `strict` mode every target is checked, so ports restrict public hosts too.
  - Non-public targets need an IP or built-in entry, a host name entry alone never covers them.
  - Reserved addresses (the IPv4-embedding NAT64, Teredo and 6to4 ranges, this-network, multicast and broadcast) are denied whatever the list says. To reach them configure an HTTP proxy
  - This list is enforced on direct connections only. When an HTTP proxy is configured, restricting the proxied target is the proxy server's responsibility.
 ## Audit (`audit`)
 - `RECORD_OUTPUT`: **disabled**: Where security-relevant events are recorded. `disabled` records nothing. `database` writes events to the `audit_event` table and shows them in the admin, organization, repository and user settings. Invalid values fall back to `disabled`. See [Audit Logging](audit-logging.md).
 - `RETENTION_DAYS`: **30**: Days to keep recorded events. `0` keeps them forever. Pruning is done by `cron.delete_old_audit_events`. That task is only registered while `RECORD_OUTPUT` records events and `RETENTION_DAYS` is greater than `0`.
 ## Camo (`camo`)
@@ -681,8 +665,8 @@ And the following unique queues:
 ## OpenID (`openid`)
- `ENABLE_OPENID_SIGNIN`: **false**: Allow authentication in via OpenID.
+- `ENABLE_OPENID_SIGNIN`: **true**: Allow authentication in via OpenID.
- `ENABLE_OPENID_SIGNUP`: **false**: Allow registering via OpenID.
+- `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION**: Allow registering via OpenID.
 - `WHITELISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
   OpenID URI's to permit.
 - `BLACKLISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
@@ -717,7 +701,7 @@ And the following unique queues:
   Requires `Mailer` to be enabled.
 - `REGISTER_MANUAL_CONFIRM`: **false**: Enable this to manually confirm new registrations.
   Requires `REGISTER_EMAIL_CONFIRM` to be disabled.
- `DISABLE_REGISTRATION`: **true**: Disable registration, after which only admin can create
+- `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create
   accounts for users.
 - `REQUIRE_EXTERNAL_REGISTRATION_PASSWORD`: **false**: Enable this to force externally created
   accounts (via GitHub, OpenID Connect, etc) to create a password.
@@ -741,8 +725,8 @@ And the following unique queues:
   If you set it to false, maybe it also needs to set `ENABLE_BASIC_AUTHENTICATION` to false to
   completely disable password-based authentication.
 - `ENABLE_PASSKEY_AUTHENTICATION`: **true**: Allow users to sign-in with a passkey
- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable reverse proxy authentication for the web interface, Git over HTTP, Git LFS and the package registry. Gitea must only be reachable through the proxy, see [Reverse Proxy](authentication.md#reverse-proxy).
+- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable this to allow reverse proxy authentication for web requests
- `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`: **false**: Enable reverse proxy authentication for the REST API under `/api/v1`.
+- `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`: **false**: Enable this to allow reverse proxy authentication for API requests, the reverse proxy is responsible for ensuring that no CSRF is possible.
 - `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration
   for reverse authentication.
 - `ENABLE_REVERSE_PROXY_EMAIL`: **false**: Enable this to allow to auto-registration with a
@@ -776,7 +760,7 @@ And the following unique queues:
 - `DEFAULT_ALLOW_ONLY_CONTRIBUTORS_TO_TRACK_TIME`: **true**: Only allow users with write permissions to track time.
 - `EMAIL_DOMAIN_ALLOWLIST`: **_empty_**: If non-empty, comma separated list of domain names that can only be used to register on this instance, wildcard is supported.
 - `EMAIL_DOMAIN_BLOCKLIST`: **_empty_**: If non-empty, comma separated list of domain names that cannot be used to register on this instance, wildcard is supported.
- `SHOW_REGISTRATION_BUTTON`: **false**: Show Registration button, defaults to true only if both DISABLE_REGISTRATION and ALLOW_ONLY_EXTERNAL_REGISTRATION are false
+- `SHOW_REGISTRATION_BUTTON`: **! DISABLE\_REGISTRATION**: Show Registration Button
 - `SHOW_MILESTONES_DASHBOARD_PAGE`: **true** Enable this to show the milestones dashboard page - a view of all the user's milestones
 - `AUTO_WATCH_NEW_REPOS`: **true**: Enable this to let all organisation users watch new repos when they are created
 - `AUTO_WATCH_ON_CHANGES`: **false**: Enable this to make users watch a repository after their first commit to it
@@ -786,7 +770,8 @@ And the following unique queues:
 - `DEFAULT_ORG_MEMBER_VISIBLE`: **false** True will make the membership of the users visible when added to the organisation.
 - `ALLOW_ONLY_INTERNAL_REGISTRATION`: **false** Set to true to force registration only via Gitea.
 - `ALLOW_ONLY_EXTERNAL_REGISTRATION`: **false** Set to true to force registration only using third-party services.
- `NO_REPLY_ADDRESS`: **_empty_**: Value for the domain part of the user's email address in the git log if user has set KeepEmailPrivate to true. The user's email will be replaced with a concatenation of the user name in lower case, "@" and NO_REPLY_ADDRESS. Default value is "noreply." + the domain part of ROOT_URL
+- `NO_REPLY_ADDRESS`: **noreply.DOMAIN** Value for the domain part of the user's email address in the Git log if user has set KeepEmailPrivate to true. DOMAIN resolves to the value in server.DOMAIN.
  The user's email will be replaced with a concatenation of the user name in lower case, "@" and NO_REPLY_ADDRESS.
 - `USER_DELETE_WITH_COMMENTS_MAX_TIME`: **0** Minimum amount of time a user must exist before comments are kept when the user is deleted.
 - `VALID_SITE_URL_SCHEMES`: **http, https**: Valid site url schemes for user profiles
@@ -819,11 +804,9 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
 - `DELIVER_TIMEOUT`: **5**: Delivery timeout (sec) for shooting webhooks.
 - `SKIP_TLS_VERIFY`: **false**: Allow insecure certification.
 - `PAGING_NUM`: **10**: Number of webhook history events that are shown in one page.
- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting.
+- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting.
 - `PROXY_HOSTS`: **_empty_`**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts. If not given, will use global proxy setting.
 When a proxy is configured, Gitea does not enforce `[security]` `ALLOWED_HOST_LIST` on the proxied target, the proxy server is expected to restrict it.
 ## Mailer (`mailer`)
 :::warning
@@ -898,27 +881,27 @@ In-Reply-To =
 ## Cache (`cache`)
- `ADAPTER`: **memory**: Either `memory`, `redis`, `memcache`, or `twoqueue`.
+- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, `twoqueue` or `memcache`. (`twoqueue` represents a size limited LRU cache.)
- `INTERVAL`: **60**: For `memory` and `twoqueue`, GC interval in seconds.
+- `INTERVAL`: **60**: Garbage Collection interval (sec), for memory and twoqueue cache only.
- `HOST`: **_empty_**: For `redis` and `memcache`, connection host address. For `twoqueue` sets configuration for the queue. If left empty while `ADAPTER` is `redis`, it falls back to [redis/CONN_STR](#redis-redis) when that is set.
+- `HOST`: **_empty_**: Connection string for `redis` and `memcache`. For `twoqueue` sets configuration for the queue. If left empty while `ADAPTER` is `redis`, it falls back to [redis/CONN_STR](#redis-redis) when that is set.
  - Redis: `redis://:[email protected]:6379/0?pool_size=100&idle_timeout=180s` (See [queue/CONN_STR](#queue-queue-and-queue) for information on additional supported connection types)
    - For a Redis cluster: `redis+cluster://:[email protected]:6379/0?pool_size=100&idle_timeout=180s`
    - For a Redis sentinel: `redis+sentinel://:macaron@sentinel0:26379,sentinel1:26379,sentinel2:26379/0?pool_size=100&idle_timeout=180s&master_name=mymaster`
-  - Memcache: `127.0.0.1:11211`
+  - Memcache: `127.0.0.1:9090;127.0.0.1:9091`
  - TwoQueue LRU cache: `{"size":50000,"recent_ratio":0.25,"ghost_ratio":0.5}` or `50000` representing the maximum number of objects stored in the cache.
- `ITEM_TTL`: **16h**: Time to keep items in cache if not used. Setting it to -1 disables caching.
+- `ITEM_TTL`: **16h**: Time to keep items in cache if not used, Setting it to -1 disables caching.
 ## Cache - LastCommitCache settings (`cache.last_commit`)
- `ITEM_TTL`: **8760h**: Time to keep items in cache if not used. Setting it to -1 disables caching.
+- `ITEM_TTL`: **8760h**: Time to keep items in cache if not used, Setting it to -1 disables caching.
 - `COMMITS_COUNT`: **1000**: Only enable the cache when repository's commits count great than.
 ## Session (`session`)
- `PROVIDER`: **file**: Either "memory", "file", "redis" or "db", default is "file". "db" will reuse the configuration in `[database]`
+- `PROVIDER`: **memory**: Session engine provider \[memory, file, redis, db, mysql, couchbase, memcache, postgres\]. Setting `db` will reuse the configuration in `[database]`
 - `PROVIDER_CONFIG`: **data/sessions**: For file, the root path; for db, empty (database config will be used); for others, the connection string. Relative paths will be made absolute against _`AppWorkPath`_. For the `redis` provider, if left empty it falls back to [redis/CONN_STR](#redis-redis) when that is set.
 - `COOKIE_SECURE`:**_empty_**: `true` or `false`. Enable this to force using HTTPS for all session access. If not set, it defaults to `true` if the ROOT_URL is an HTTPS URL.
- `COOKIE_NAME`: **gitea\_session**: Session cookie name
+- `COOKIE_NAME`: **i\_like\_gitea**: The name of the cookie used for the session ID.
 - `GC_INTERVAL_TIME`: **86400**: GC interval in seconds.
 - `SESSION_LIFE_TIME`: **86400**: Session life time in seconds, default is 86400 (1 day)
 - `DOMAIN`: **_empty_**: Sets the cookie Domain
@@ -945,7 +928,7 @@ In-Reply-To =
  - none = no avatar will be displayed
  - random = random avatar will be generated
  - image = default image will be used (which is set in `REPOSITORY_AVATAR_FALLBACK_IMAGE`)
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **_empty_**: Image used as default repository avatar (if `REPOSITORY_AVATAR_FALLBACK` is set to image and none was uploaded). The value is used as-is, without prepending the sub-path of `ROOT_URL`. Empty uses Gitea's builtin repository avatar.
+- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: Image used as default repository avatar (if `REPOSITORY_AVATAR_FALLBACK` is set to image and none was uploaded)
 ## Project (`project`)
@@ -1064,7 +1047,7 @@ Release attachment has its own config options in `[repository.release]` section.
 - `ENABLED`: **true**: Enable running Update mirrors task periodically.
 - `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
 - `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
 - `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).
@@ -1073,7 +1056,7 @@ Release attachment has its own config options in `[repository.release]` section.
 - `ENABLED`: **true**: Enable running repository health check task periodically.
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
 - `RUN_AT_START`: **false**: Run repository health check task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
 - `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck
@@ -1082,13 +1065,12 @@ Release attachment has its own config options in `[repository.release]` section.
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
 - `ENABLED`: **true**: Enable running repository statistics check task periodically.
 - `RUN_AT_START`: **true**: Run repository statistics check task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 #### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)
 - `ENABLED`: **true**: Enable cleanup hook_task job.
 - `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@midnight**: Cron syntax for cleaning hook_task table.
 - `CLEANUP_TYPE` **OlderThan** OlderThan or PerWebhook Method to cleanup hook_task, either by age (i.e. how long ago hook_task record was delivered) or by the number to keep per webhook (i.e. keep most recent x deliveries per webhook).
 - `OLDER_THAN`: **168h**: If CLEANUP_TYPE is set to OlderThan, then any delivered hook_task records older than this expression will be deleted.
@@ -1108,7 +1090,7 @@ Update migrated repositories' issues and comments' posterid, it will always atte
 - `ENABLED`: **true**: Enable update migration poster id job.
 - `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
 #### Cron - Sync External Users (`cron.sync_external_users`)
@@ -1117,7 +1099,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
 - `ENABLED`: **true**: Enable synchronize external user data job
 - `RUN_AT_START`: **false**: Synchronize external user data when starting server
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
 - `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.
@@ -1125,14 +1107,12 @@ Synchronize external user data (only LDAP user synchronization is supported)
 - `ENABLED`: **true**: Enable cleanup expired actions assets job.
 - `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@midnight** : Cron syntax for the job.
 #### Cron - Delete Old Action Runs (`cron.cleanup_action_runs`)
 - `ENABLED`: **true**: Enable the job deleting action runs older than `RUN_RETENTION_DAYS`. Deletes nothing while that is 0.
 - `RUN_AT_START`: **false**: Run job at start time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@midnight**: Cron syntax for the job.
 #### Cron - Cleanup Deleted Branches (`cron.deleted_branches_cleanup`)
@@ -1218,21 +1198,11 @@ Synchronize external user data (only LDAP user synchronization is supported)
 - `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
 - `OLDER_THAN`: **8760h**: any action older than this expression will be deleted from database, suggest using `8760h` (1 year) because that's the max length of heatmap.
 #### Cron - Delete old audit events (`cron.delete_old_audit_events`)
 Deletes audit events older than the retention period. The task is only registered when `[audit].RECORD_OUTPUT` records events and `[audit].RETENTION_DAYS` is greater than `0`. See [Audit Logging](audit-logging.md).
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
 - `OLDER_THAN`: **720h**: any audit event older than this expression will be deleted from the database. Defaults to `[audit].RETENTION_DAYS`.
 #### Cron -  Check for new Gitea versions (`cron.update_checker`)
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
 - `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a work, e.g. `@every 168h`.
 - `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: the endpoint that Gitea will check for newer versions
@@ -1240,7 +1210,7 @@ Deletes audit events older than the retention period. The task is only registere
 - `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.
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
 - `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.
@@ -1248,7 +1218,6 @@ Deletes audit events older than the retention period. The task is only registere
 - `ENABLED`: **false**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
 - `OLDER_THAN`: **168h**: Only attempt to garbage collect LFSMetaObjects older than this (default 7 days)
 - `LAST_UPDATED_MORE_THAN_AGO`: **72h**: Only attempt to garbage collect LFSMetaObjects that have not been attempted to be garbage collected for this long (default 3 days)
@@ -1261,35 +1230,35 @@ Deletes audit events older than the retention period. The task is only registere
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `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).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `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).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `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).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `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).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `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`)
@@ -1329,6 +1298,7 @@ These options are written into the gitconfig file under `[git] HOME_PATH` when G
 - `diff.algorithm`: **histogram**
 - `core.logAllRefUpdates`: **true**
 - `gc.reflogExpire`: **90**
 ## Metrics (`metrics`)
@@ -1356,7 +1326,7 @@ These options are written into the gitconfig file under `[git] HOME_PATH` when G
 - `JWT_SECRET_URI`: **_empty_**: Instead of defining JWT_SECRET in the configuration, this configuration option can be used to give Gitea a path to a file that contains the secret (example value: `file:/etc/gitea/oauth2_jwt_secret`)
 - `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, gitea-cli, gitea-app, gitea-vscode**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options. `tea` is accepted as an alias of `gitea-cli`.
+- `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, tea, gitea-app**: 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.
@@ -1440,13 +1410,11 @@ in this mapping or the filetype using heuristics.
 - `MAX_ATTEMPTS`: **3**: Max attempts per http/https request on migrations.
 - `RETRY_BACKOFF`: **3**: Backoff time per http/https request retry (seconds)
- `EGRESS_MODE`: **lax**: Mode toggles between strictness of scanning outgoing requests, same format as `EGRESS_MODE` in [`security`](#security-security).
+- `ALLOWED_DOMAINS`: **_empty_**: Domains allowlist for migrating repositories, default is blank. It means external hosts will be allowed. Multiple domains could be separated by commas. Wildcard is supported: `github.com, *.github.com`.
- `ALLOWED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may call, same format as `ALLOWED_HOST_LIST` in [`security`](#security-security). Private, loopback and link-local addresses need a builtin or CIDR entry. When unset, the deprecated `ALLOWED_DOMAINS` entries apply on every port with `strict` as the default mode, and the deprecated `ALLOW_LOCALNETWORKS` adds `private, loopback`.
+- `BLOCKED_DOMAINS`: **_empty_**: Domains blocklist for migrating repositories, default is blank. Multiple domains could be separated by commas. When `ALLOWED_DOMAINS` is not blank, this option has a higher priority to deny domains. Wildcard is supported.
- `BLOCKED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may never call, portless entries cover all ports.
+- `ALLOW_LOCALNETWORKS`: **false**: Allow private addresses defined by RFC 1918, RFC 1122, RFC 4632 and RFC 4291. If a domain is allowed by `ALLOWED_DOMAINS`, this option will be ignored.
 - `SKIP_TLS_VERIFY`: **false**: Allow skip tls verify
 These lists are enforced on direct connections only. When a proxy is configured (`[proxy]`, `[git.config]` `http.proxy` or the environment), restricting the proxied target is the proxy server's responsibility.
 ## Federation (`federation`)
 - `ENABLED`: **false**: Enable/Disable federation capabilities
@@ -1681,16 +1649,14 @@ is `data/repo-archive` and the default of `MINIO_BASE_PATH` is `repo-archive/`.
 ## Proxy (`proxy`)
 - `PROXY_ENABLED`: **false**: Enable the proxy if true, all requests to external via HTTP will be affected, if false, no proxy will be used even environment http_proxy/https_proxy
- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy
+- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy
 - `PROXY_HOSTS`: **_empty_**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts.
 When a proxy is configured, Gitea does not enforce the egress lists (`[security]`, `[migrations]`) on the proxied target, the proxy server is expected to restrict it.
 i.e.
 ```ini
 PROXY_ENABLED = true
-PROXY_URL = socks5://127.0.0.1:1080
+PROXY_URL = socks://127.0.0.1:1080
 PROXY_HOSTS = *.github.com
 ```
@@ -1708,8 +1674,7 @@ PROXY_HOSTS = *.github.com
  But it will save storage space and network bandwidth, so it's still recommended to use compression.
 - `ARTIFACT_RETENTION_DAYS`: **90**: Days to keep artifacts. Old artifacts will be deleted after this period. 0 means keep forever.
  Changes only apply to newly uploaded artifacts, existing ones keep the expiry stored when they were uploaded.
-  Workflows can request a shorter retention period, down to 1 day.
+  Artifacts could have their own retention periods by setting the `retention-days` option in `actions/upload-artifact` step.
 - `ARTIFACT_PREVIEW_MAX_SIZE`: **10485760**: Maximum total artifact size in bytes that can be browsed or previewed in the web UI. Set to `0` to disable artifact previews or `-1` for no limit. Individual files are also limited by [`MAX_DISPLAY_FILE_SIZE`](#ui-ui).
 - `RUN_RETENTION_DAYS`: **400**: Days to keep completed runs. Old runs and everything under them will be deleted after this period. 0 means keep forever.
 - `ZOMBIE_TASK_TIMEOUT`: **10m**: Timeout to stop the task which have running status, but haven't been updated for a long time
 - `ENDLESS_TASK_TIMEOUT`: **3h**: Timeout to stop the tasks which have running status and continuous updates, but don't end for a long time
@@ -1719,9 +1684,18 @@ PROXY_HOSTS = *.github.com
 - `SCOPED_WORKFLOW_DIRS`: **.gitea/scoped_workflows**: Comma-separated list of directories holding [scoped workflows](usage/actions/scoped-workflows.md) (workflows defined in a central source repository that run on other repositories). Must not overlap with `WORKFLOW_DIRS`. Leave empty so no directory is scanned for scoped workflows; none are found or run.
 - `MAX_RERUN_ATTEMPTS`: **50**: Maximum number of attempts a single workflow run can have (initial run + reruns). Defaults value is 50. Set any positive value that fits your workflow needs.
-`DEFAULT_ACTIONS_URL` sets where runners download actions without a host.
+`DEFAULT_ACTIONS_URL` indicates where the Gitea Actions runners should find the actions with relative path.
-With `github`, `uses: actions/checkout@v4` resolves to `https://github.com/actions/checkout@v4`, with `self` to `<ROOT_URL>/actions/checkout@v4`.
+For example, `uses: actions/checkout@v4` means `https://github.com/actions/checkout@v4` since the value of `DEFAULT_ACTIONS_URL` is `github`.
-`self` requires mirroring every action you use to your instance, so prefer naming the host per action instead: `uses: self:owner/repo@ref` for your instance, or a full URL like `uses: https://gitea.com/actions/checkout@v4` for any other host.
+And it can be changed to `self` to make it `root_url_of_your_gitea/actions/checkout@v4`.
 Please note that using `self` is not recommended for most cases, as it could make names globally ambiguous.
 Additionally, it requires you to mirror all the actions you need to your Gitea instance, which may not be worth it.
 Therefore, please use `self` only if you understand what you are doing.
 In earlier versions (`<= 1.19`), `DEFAULT_ACTIONS_URL` could be set to any custom URLs like `https://gitea.com` or `http://your-git-server,https://gitea.com`, and the default value was `https://gitea.com`.
 However, later updates removed those options, and now the only options are `github` and `self`, with the default value being `github`.
 However, if you want to use actions from other git server, you can use a complete URL in `uses` field, it's supported by Gitea (but not GitHub).
 Like `uses: https://gitea.com/actions/checkout@v4` or `uses: http://your-git-server/actions/checkout@v4`.
 ## Other (`other`)
@@ -86,21 +86,6 @@ PROTOCOL       = smtps
 Note that you'll need to create and use an [App password](https://support.google.com/accounts/answer/185833?hl=en) by enabling 2FA on your Google
 account. You won't be able to use your Google account password directly.
 An app password is the only option: Google
 [turned off access for apps that sign in with a password alone](https://workspaceupdates.googleblog.com/2023/09/winding-down-google-sync-and-less-secure-apps-support.html)
 in 2024 and asks applications to use OAuth instead, which Gitea's mailer does
 not implement — it authenticates with `CRAM-MD5`, `PLAIN` or `LOGIN`.
 Two things to keep in mind:
 - app passwords require 2-step verification on the account, and a Google
  Workspace administrator can switch them off for the whole domain. If they are
  not available, send through the
  [Workspace SMTP relay service](https://support.google.com/a/answer/2956491)
  or through another mail provider.
 - port `587` works as well, with `SMTP_PORT = 587` and
  `PROTOCOL = smtp+starttls`.
 ### ProtonMail
 This feature is currently only available for select Proton for Business customers and those with Visionary and Family plans with custom domain addresses. See [ProtonMail's SMTP documentation](https://proton.me/support/smtp-submission) for more information. This limitation can be circumvented by using the ProtonMail Bridge application.
@@ -41,24 +41,3 @@ client that causes SSH transfers to hang: https://github.com/git-lfs/git-lfs/pul
 This can be worked around on all the client machines by setting the git config:
 `git config --global lfs.ssh.automultiplex false`
 :::
 # Changing LFS files through the API
 The [contents API](https://docs.gitea.com/api/operations/repo-change-files/)
 works on LFS tracked files as well: send the file content as usual and Gitea
 stores it as an LFS object and commits a pointer file, as long as the path is
 matched by a `filter=lfs` rule in `.gitattributes`.
 What is easy to get wrong is the `sha` of the file being changed, which
 `PUT`/`DELETE /repos/{owner}/{repo}/contents/{filepath}` and
 `POST /repos/{owner}/{repo}/contents` require for an existing file. Gitea
 compares it with the ID of the blob the commit has at that path, and for an LFS
 tracked file that blob is the **pointer file**, not the content:
 - use the `sha` returned by
  [`GET /repos/{owner}/{repo}/contents/{filepath}`](https://docs.gitea.com/api/operations/repo-get-contents/)
 - do not use `lfs_oid` from the same response, which identifies the LFS object,
  and do not use a checksum of the file itself
 Sending anything else fails with `sha does not match`, even though the request
 looks correct.
@@ -16,8 +16,6 @@ The logging configuration of Gitea mainly consists of 3 types of components:
 There is a fully functional log output by default, so it is not necessary to define one.
 Security-relevant events (repository transfers, token changes, impersonation, and similar) are recorded separately. See [Audit Logging](audit-logging.md).
 ## Collecting Logs for Help
 To collect logs for help and issue report, see [Support Options](help/support.md).
@@ -16,7 +16,6 @@ aliases:
 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.
 6. Gitea uses a WebSocket connection at `/-/ws` for real-time updates like the notification counter. Make sure the reverse-proxy talks HTTP/1.1 and forwards the `Upgrade` and `Connection` headers, see the examples below. Without it, Gitea falls back to periodic polling.
 7. Make sure the reverse-proxy sets the `X-Real-IP` header, otherwise Gitea uses a client-sent value. For example `header_up X-Real-IP {remote_host}` in Caddy's `reverse_proxy`, `RequestHeader set X-Real-IP "expr=%{REMOTE_ADDR}"` in Apache or `http-request set-header X-Real-IP %[src]` in HAProxy. To log the client port, also set `X-Real-Port`, for example `proxy_set_header X-Real-Port $remote_port;` in nginx.
 ### Use a sub-path
@@ -73,7 +73,6 @@ By default, this creates a token with very limited permissions. To complete your
 - `activitypub`
 - `admin`
 - `commitstatus` (included in `repository`)
 - `issue`
 - `misc`
 - `notification`
@@ -111,9 +111,6 @@ Gitea token scopes are as follows:
 | **admin** | `/admin/*` API routes: Site-wide administrative operations (hidden for non-admin accounts).                                                          |
 | &nbsp;&nbsp;&nbsp; **read:admin** | Grants read access for admin operations, such as getting cron jobs or registered user emails.                                                        |
 | &nbsp;&nbsp;&nbsp; **write:admin** | Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts.                                           |
 | **commitstatus** | `/repos/{owner}/{repo}/statuses/{sha}` and `/repos/{owner}/{repo}/commits/{ref}/status(es)` API routes: Commit status operations.                        |
 | &nbsp;&nbsp;&nbsp; **read:commitstatus** | Grants read access to commit statuses. Included in `read:repository`.                                                                                |
 | &nbsp;&nbsp;&nbsp; **write:commitstatus** | Grants read/write access to commit statuses, such as reporting CI results. Included in `write:repository`.                                           |
 | **issue** | `issues/*`, `labels/*`, `milestones/*` API routes: Issue-related operations.                                                                         |
 | &nbsp;&nbsp;&nbsp; **read:issue** | Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones.                                         |
 | &nbsp;&nbsp;&nbsp; **write:issue** | Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones.           |
@@ -144,9 +141,7 @@ Gitea creates OAuth applications for the following services by default on startu
 |-----------|-----------|---------|
 |[git-credential-oauth](https://github.com/hickford/git-credential-oauth)|Git credential helper|`a4792ccc-144e-407e-86c9-5e7d8d9c3269`|
 |[Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager)|Git credential helper|`e90ee53c-94e2-48ac-9358-a874fb9e0662`|
-|[Gitea CLI](https://gitea.com/gitea/cli)|Gitea CLI|`d57cb8c4-630c-4168-8324-ec79935e18d4`|
+|[tea](https://gitea.com/gitea/tea)|tea|`d57cb8c4-630c-4168-8324-ec79935e18d4`|
 |Gitea App|Official Gitea mobile app|`b757811a-05c8-4c76-8d74-a5ee3d2073f2`|
 |[gitea-vscode](https://gitea.com/gitea/gitea-vscode)|VS Code extension|`75a9ec3e-42b5-40cb-9144-9ea96ecd56a6`|
 To prevent unexpected behavior, they are being displayed as locked in the UI and their creation can instead be controlled by the `DEFAULT_APPLICATIONS` parameter in `app.ini`.
@@ -43,7 +43,7 @@ You can try it out using [the online demo](https://demo.gitea.com).
 - **Security**
-  Gitea places a strong emphasis on security, offering features such as user permission management, access control lists, [audit logging](administration/audit-logging.md), and more to ensure the security of code and data.
+  Gitea places a strong emphasis on security, offering features such as user permission management, access control lists, and more to ensure the security of code and data.
 - **Code Review**
@@ -34,7 +34,6 @@ _Symbols used in table:_
 | Telemetry                                        | **✘**                                               | ✓         | ✓         | ✓         | ✓         | ✘            | ✘            |
 | Third-party render tool support                  | ✓                                                   | ✘         | ✘         | ✘         | ✓         | ✘            | ✘            |
 | WebAuthn (2FA)                                   | ✓                                                   | ✓         | ✓         | ✓         | ✓         | ✘            | ✓            |
 | Audit log                                        | ✓                                                   | ✓         | ⁄         | ✓         | ✓         | ?            | ?            |
 | Extensive API                                    | ✓                                                   | ✓         | ✓         | ✓         | ✓         | ✓            | ✓            |
 | Built-in Package/Container Registry              | ✓                                                   | ✓         | ✓         | ✓         | ✘         | ✘            | ✘            |
 | Sync commits to an external repo (push mirror)   | ✓                                                   | ✘         | ✓         | ✓         | ✘         | ✓            | ✓            |
@@ -8,7 +8,7 @@ aliases:
 # Database Preparation
-You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. PostgreSQL, MySQL and MSSQL are covered here. If you plan to use SQLite, you can ignore this chapter.
+You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. Only PostgreSQL and MySQL will be covered here since those database engines are widely-used in production. If you plan to use SQLite, you can ignore this chapter.
 :::warning
 Converting one database type to another is not a well-tested process and you may experience issues. It is better to choose the final database type at the type of the first installation. Be aware that SQLite does not scale; if you expect your instance to grow at a later time, you should choose another database type.
@@ -177,28 +177,6 @@ All steps below requires that the database engine of your choice is installed on
    You should be prompted to enter password for the database user, and connected to the database.
 ## MSSQL
 1. As an administrator, create the login, a database with case-sensitive collation, and its user. Replace the password `'gitea'` with a secure one:
    ```sql
    CREATE LOGIN gitea WITH PASSWORD = 'gitea';
    CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
    GO
    USE giteadb;
    CREATE USER gitea FOR LOGIN gitea;
    ALTER ROLE db_owner ADD MEMBER gitea;
    GO
    ```
    Upgrades change the database schema, so the user needs `db_owner`, or `db_ddladmin`, `db_datareader` and `db_datawriter`. With the latter, also run `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;` as administrator.
 2. On your Gitea server, test the connection to the database:
    ```sh
    sqlcmd -S 203.0.113.3 -U gitea -d giteadb
    ```
 ## Database Connection over TLS
 If the communication between Gitea and your database instance is performed through a private network, or if Gitea and the database are running on the same server, this section can be omitted since the security between Gitea and the database instance is not critically exposed. If instead the database instance is on a public network, use TLS to encrypt the connection to the database, as it is possible for third-parties to intercept the traffic data.
@@ -23,7 +23,7 @@ version is @minNodeVersion@ and the latest LTS version is recommended.
 :::note
 Go version @minGoVersion@ or higher is required. However, it is recommended to
 obtain the same version as our continuous integration, see the advice given in
-[Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
+[Hacking on Gitea](development/hacking-on-gitea.md)
 :::
 ## Download
@@ -73,7 +73,7 @@ To build from source, the following programs must be present on the system:
 - `go` @minGoVersion@ or higher, see [here](https://go.dev/dl/)
 - `node` @minNodeVersion@ or higher with `npm`, see [here](https://nodejs.org/en/download/)
- `make`, see [here](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md#make)
+- `make`, see [here](development/hacking-on-gitea.md#installing-make)
 Various [make tasks](https://github.com/go-gitea/gitea/blob/main/Makefile)
 are provided to keep the build process as simple as possible.
@@ -0,0 +1,49 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "install-on-cloud-provider"
 sidebar_position: 90
 aliases:
  - /en-us/install-on-cloud-provider
 ---
 # Installation on Cloud Provider
 ## Cloudron
 Gitea is available as a 1-click install on [Cloudron](https://cloudron.io).
 Cloudron makes it easy to run apps like Gitea on your server and keep them up-to-date and secure.
 [![Install](/cloudron.svg)](https://cloudron.io/button.html?app=io.gitea.cloudronapp)
 The Gitea package is maintained [here](https://git.cloudron.io/cloudron/gitea-app).
 There is a [demo instance](https://my.demo.cloudron.io) (username: cloudron password: cloudron) where
 you can experiment with running Gitea.
 ## Linode
 [Linode](https://www.linode.com/) has Gitea as an app in their marketplace.
 To deploy Gitea to Linode, have a look at the [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/).
 ## alwaysdata
 [alwaysdata](https://www.alwaysdata.com/) has Gitea as an app in their marketplace.
 To deploy Gitea to alwaysdata, have a look at the [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/).
 ## Exoscale
 [Exoscale](https://www.exoscale.com/) provides Gitea managed by [Glasskube](https://glasskube.eu/) in their marketplace.
 Exoscale is a European cloud service provider.
 The package is maintained and update via the open source [Glasskube Kubernetes Operator](https://github.com/glasskube/operator).
 To deploy Gitea to Exoscale, have a look at the [Exoscale Marketplace](https://www.exoscale.com/marketplace/listing/glasskube-gitea/).
 ## Sealos
 Gitea is available as a one-click deployment on [Sealos](https://sealos.io/products/app-store/gitea).
 The community-maintained template source is available [here](https://github.com/labring-actions/templates/tree/kb-0.9/template/gitea).
@@ -66,7 +66,7 @@ server-1  | 2026-03-11T12:57:50.796198843Z /var/lib/gitea/git is not writable
 server-1  | 2026-03-11T12:57:50.796235667Z docker setup failed
 ```
-For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:main-nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly-rootless`)
+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`)
 ## Named volumes
@@ -30,7 +30,7 @@ image as a service. Since there is no database available, one can be initialized
 Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
 Note that the volume should be owned by the user/group with the UID/GID specified in the config file.
 If you don't give the volume correct permissions, the container may not start.
-For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:main-nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly`)
+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
 networks:
@@ -191,7 +191,7 @@ services:
 +    networks:
 +      - gitea
 +    volumes:
-+      - ./postgres:/var/lib/postgresql
+      - ./postgres:/var/lib/postgresql/data
 ```
 ## Named volumes
@@ -1,166 +0,0 @@
 ---
 date: "2026-09-03T20:00:00+02:00"
 slug: "install-with-podman-quadlet"
 sidebar_position: 65
 aliases:
  - /en-us/install-with-podman-quadlet
 ---
 # Installation with Podman Quadlet
 Similarly to [Docker](with-docker.md), [Podman](https://podman.io/) can be used to deploy Gitea.
 This reference setup guides users through the setup based on Podman Quadlet.
 Podman Quadlet is the native integration of Podman through systemd.
 To learn more about Podman Quadlet, see [systemd units using Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html).
 This setup installs the quadlets in `~/.config/containers/systemd/`, the directory for rootless quadlets, and uses the rootless images.
 If you install them in a rootful directory such as `/etc/containers/systemd/`, use the rootful images instead.
 ## Basics
 Since Podman v6.0 a single `gitea.quadlets` file can hold multiple quadlets separated by the `---` delimiter.
 Paste the following content into a file named `gitea.quadlets`
 ```ini
 # FileName=gitea-data
 [Volume]
 VolumeName=gitea-data
 ---
 # FileName=gitea-config
 [Volume]
 VolumeName=gitea-config
 ---
 # FileName=gitea
 [Container]
 PublishPort=2222:2222
 PublishPort=3000:3000
 Image=docker.gitea.com/gitea:@dockerVersion@-rootless
 ContainerName=gitea
 Mount=type=volume,src=gitea-data.volume,destination=/var/lib/gitea
 Mount=type=volume,src=gitea-config.volume,destination=/etc/gitea
 [Service]
 Restart=always
 [Install]
 # Start with the user session
 WantedBy=default.target
 ```
 You can run the installation command
 ```sh
 $ podman quadlet install ./gitea.quadlets --application=gitea
 /home/user/.config/containers/systemd/gitea/gitea-data.volume
 /home/user/.config/containers/systemd/gitea/gitea-config.volume
 /home/user/.config/containers/systemd/gitea/gitea.container
 ```
 The `--application=gitea` flag allows us to tell podman to group the quadlets together, this can help for managing and organizing the quadlets files.
 You can validate the quadlets are properly installed by looking at the list command
 ```sh
 $ podman quadlet list
 NAME                 UNIT NAME                    PATH ON DISK                                                     STATUS         APPLICATION  POD
 gitea-config.volume  gitea-config-volume.service  /home/user/.config/containers/systemd/gitea/gitea-config.volume  active/exited  gitea
 gitea-data.volume    gitea-data-volume.service    /home/user/.config/containers/systemd/gitea/gitea-data.volume    active/exited  gitea
 gitea.container      gitea.service                /home/user/.config/containers/systemd/gitea/gitea.container      failed/failed  gitea
 ```
 You can start the application by running `systemctl --user start gitea` command.
 `WantedBy=default.target` starts the service when the user session starts.
 Rootless user services do not run without a session, so to start Gitea at boot, enable lingering for the user with `loginctl enable-linger $USER`.
 ## Databases
 ### PostgreSQL database
 To start Gitea in combination with a PostgreSQL database, apply these changes to the
 `gitea.quadlets` file created above.
 To start Gitea with a database, we need to create a network, so the database and Gitea container can communicate.
 ```diff
 # FileName=gitea-data
 [Volume]
 VolumeName=gitea-data
 ---
 # FileName=gitea-config
 [Volume]
 VolumeName=gitea-config
 ---
 + # FileName=gitea-postgres-data
 + [Volume]
 + VolumeName=gitea-postgres-data
 + ---
 + # FileName=gitea
 + [Network]
 + NetworkName=gitea
 + ---
 + # FileName=gitea-postgres
 + [Container]
 + Image=docker.io/library/postgres:18
 + ContainerName=gitea-postgres
 + Network=gitea.network
 + Mount=type=volume,src=gitea-postgres-data.volume,destination=/var/lib/postgresql
 + Environment=POSTGRES_USER=gitea
 + Environment=POSTGRES_PASSWORD=gitea
 + Environment=POSTGRES_DB=gitea
 +
 + [Service]
 + Restart=always
 +
 + [Install]
 + # Start with the user session
 + WantedBy=default.target
 + ---
 # FileName=gitea
 + [Unit]
 + Requires=gitea-postgres.service
 + After=gitea-postgres.service
 +
 [Container]
 PublishPort=2222:2222
 PublishPort=3000:3000
 Image=docker.gitea.com/gitea:@dockerVersion@-rootless
 ContainerName=gitea
 Mount=type=volume,src=gitea-data.volume,destination=/var/lib/gitea
 Mount=type=volume,src=gitea-config.volume,destination=/etc/gitea
 + Network=gitea.network
 + Environment=GITEA__database__DB_TYPE=postgres
 + Environment=GITEA__database__HOST=gitea-postgres:5432
 + Environment=GITEA__database__NAME=gitea
 + Environment=GITEA__database__USER=gitea
 + Environment=GITEA__database__PASSWD=gitea
 [Service]
 Restart=always
 [Install]
 # Start with the user session
 WantedBy=default.target
 ```
 ## Logs
 As systemd manages the container we can use `journalctl` to access the logs
 ```sh
 $ journalctl --user --follow --unit=gitea.service
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:263:runWeb() [I] Starting Gitea on PID: 2
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:115:showWebStartupMessage() [I] Gitea version: 1.27.3 built with go1.26.7-X:jsonv2 : bindata, timetzdata,
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:116:showWebStartupMessage() [I] * RunMode: prod
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:117:showWebStartupMessage() [I] * AppPath: /usr/local/bin/gitea
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:118:showWebStartupMessage() [I] * WorkPath: /var/lib/gitea
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:119:showWebStartupMessage() [I] * CustomPath: /var/lib/gitea/custom
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:120:showWebStartupMessage() [I] * ConfigFile: /etc/gitea/app.ini
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:121:showWebStartupMessage() [I] Prepare to run install page
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:329:listen() [I] Listen: http://0.0.0.0:3000
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:333:listen() [I] AppURL(ROOT_URL): http://localhost:3000/
 gitea[5967]: 2026/09/03 14:50:42 modules/graceful/server.go:52:NewServer() [I] Starting new Web server: tcp:0.0.0.0:3000 on PID: 2
 ```
@@ -10,13 +10,13 @@ aliases:
 # Protected branches
-Protected branches prevent unwanted changes by enforcing push, deletion, 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.
+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, deletion, merge, and review options described below.
+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.
@@ -48,9 +48,7 @@ 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.
+- **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.
 The user allowlists for push, force-push and deletion can include the **Gitea Actions** and **Deploy Key** system users. They still require write access; **Deploy Key** also covers deploy tokens.
 When a push is blocked, the server-side hook rejects the update with an explanation.
@@ -60,17 +58,7 @@ 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 of users or teams **and** requires regular push access.
+- **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.
 ## Branch deletion
 The **Branch Deletion** section controls whether matching protected branches can be deleted:
 - **Disable branch deletion** prevents deletion. This is the default.
 - **Enable branch deletion** allows anyone who can push to delete the branch.
 - **Allowlist restricted branch deletion** limits deletion to a separate allowlist of users or teams **and** requires regular push access.
 These rules apply to Git (`git push --delete`), the API, the web interface and post-merge cleanup. The default branch and configured default pull request target branch cannot be deleted.
 ## Pull request merges and approvals
@@ -1,31 +0,0 @@
 ---
 date: "2026-08-30T00:00:00+02:00"
 slug: "artifacts"
 sidebar_position: 70
 ---
 # Artifacts
 Workflow runs can store files such as test results, coverage reports, and build output as artifacts. Artifacts are uploaded by workflows, for example with [`actions/upload-artifact`](https://github.com/actions/upload-artifact), and appear on the run page after the upload completes.
 ## Previewing artifacts
 Select an artifact on the run page to open its file browser and preview in the same tab. The preview identifies the originating run and attempt, and provides links back to that run and to download the complete artifact. Selecting files in the browser updates the preview in the same tab.
 Artifact previews:
 - require sign-in and access to the Actions run to open the preview page
 - render text-based files, images (including SVG), and PDFs
 - run HTML and JavaScript content in a sandboxed frame
 Preview content is loaded through signed URLs that expire after one hour and do not require a session cookie. Reopen the preview page to obtain a fresh URL after it expires.
 The file browser lists up to 2,000 files per artifact. Larger artifacts show a notice when the list is truncated.
 Unsupported or oversized files can still be downloaded with the complete artifact.
 ## Instance configuration
 Site administrators can limit the total artifact size that can be browsed or previewed with `ARTIFACT_PREVIEW_MAX_SIZE` in the `[actions]` section of `app.ini`. The default is 10 MiB. Set it to `0` to disable previews or `-1` to allow artifacts of any size.
 The size of an individual previewed file is also limited by [`MAX_DISPLAY_FILE_SIZE`](../../administration/config-cheat-sheet.md#ui-ui) in the `[ui]` section.
@@ -6,94 +6,104 @@ sidebar_position: 120
 # Compared to GitHub Actions
-Gitea Actions is designed to be compatible with GitHub Actions, with the differences below.
+Even though Gitea Actions is designed to be compatible with GitHub Actions, there are some differences between them.
 ## Additional features
 ### Absolute action URLs
-`uses:` accepts an absolute URL to any git host, e.g. `uses: https://gitea.com/actions/checkout@v4`.
+Gitea Actions supports defining actions via absolute URL, which means that you can use actions from any git repository.
-
+Like `uses: https://github.com/actions/checkout@v4` or `uses: http://your_gitea.com/owner/repo@branch`.
 ### Action prefixes
 `uses:` accepts these prefixes:
 - `self:` references your own Gitea instance, e.g. `uses: self:owner/repo@v1` or `uses: self:owner/repo/.gitea/workflows/build.yml@v1`
 - `builtin:` runs an action built into Gitea Runner, which needs no download and no Node in the job image, e.g. `uses: builtin:checkout`
 `builtin:checkout` accepts the `repository`, `ref`, `token`, `path` and `fetch-depth` inputs of `actions/checkout` with the same defaults, and fails on any other input.
 ### Workflow-relative actions
 `$/` references the repository and commit of the workflow, or of the enclosing composite action, e.g. `uses: $/.gitea/actions/build`.
 Unlike `./`, it needs no checkout first.
 ### Actions written in Go
 Gitea Actions supports writing actions in Go.
 See [Creating Go Actions](https://blog.gitea.com/creating-go-actions/).
 ### Support the non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly on schedule
-`schedule` also accepts `@yearly`, `@monthly`, `@weekly`, `@daily` and `@hourly`, which [GitHub does not](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).
+Github Actions doesn't support that. https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
 ## Unsupported workflows syntax
 ### `jobs.<job_id>.environment`
-[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) is ignored.
+See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment).
 It's ignored by Gitea Actions now.
 ### Complex `runs-on`
-[`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) supports:
+See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
 Gitea Actions supports:
 - Static strings: `runs-on: self-hosted`
 - Arrays of labels: `runs-on: [linux, self-hosted]`
 - String expressions: `runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
 - Arrays containing expressions: `runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
 ## Missing features
 ### Package repository authorization
-`GITEA_TOKEN` cannot publish to the package registry of its repository, e.g. to push OCI images.
+The `GITEA_TOKEN` for a job running within a repository should be able to publish to the associated package repository (i.e. to upload OCI images). See the "packages" scope for the "default access" in [Automatic token authentication](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token).
-Use a personal access token instead, see [this issue](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692).
+
 This is not implemented in Gitea Actions now. A workaround for Gitea Actions is to use a Personal Access Token (PAT). See this [github issue and comment](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692) for tracking this feature.
 ### Problem Matchers
-[Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md) are ignored.
+Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI.
 See [Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md).
 It's ignored by Gitea Actions now.
 ### Create an error annotation
-[Error annotations](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error) are ignored.
+See [Creating an annotation for an error](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)
 It's ignored by Gitea Actions now.
 ### Expressions
-[Expressions](https://docs.github.com/en/actions/learn-github-actions/expressions) support the standard GitHub functions and contexts.
+For [expressions](https://docs.github.com/en/actions/learn-github-actions/expressions), Gitea Actions supports standard GitHub functions (e.g. `success()`, `failure()`, `always()`, `cancelled()`, `format()`, `toJSON()`) and context variables (like `github`, `matrix`, `vars`, `env`).
 ## Missing UI features
 ### Pre and Post steps
-Pre and post steps have no section of their own in the job log.
+Pre and Post steps don't have their own section in the job log user interface.
 ### Services steps
-Service steps have no section of their own in the job log.
+Services steps don't have their own section in the job log user interface.
 ## Different behavior
 ### Job token permissions (`permissions`)
-`permissions` and `jobs.<job_id>.permissions` control the `GITEA_TOKEN` permissions, clamped by the repository and owner settings and further restricted for fork pull requests and cross-repository access.
+Gitea supports `permissions` and `jobs.<job_id>.permissions` to control the default `GITEA_TOKEN` permissions.
-GitHub-only scopes like `statuses`, `checks`, `deployments`, `security-events` and `pages` are not supported, while Gitea adds `code`, `releases`, `wiki` and `projects`. `id-token` works like on GitHub, see [OpenID Connect](openid-connect.md).
+
 The effective permissions are clamped by the repository/owner settings and are further restricted for fork pull requests and cross-repository access.
 GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not supported, while Gitea-specific scopes such as `code`, `releases`, `wiki`, and `projects` are available.
 See [Actions job token permissions](token-permissions.md).
 ### Downloading actions
-Actions without a host, like `uses: actions/checkout@v4`, are downloaded from `https://github.com`, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`.
+Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.
-See the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
+We have since restricted this option to only allow two values (`github` and `self`).
-For other sources, see [Absolute action URLs](#absolute-action-urls), [Action prefixes](#action-prefixes) and [Workflow-relative actions](#workflow-relative-actions).
+When set to `github`, the new default, Gitea will download non-fully-qualified actions from `https://github.com`.
 For example, if you use `uses: actions/checkout@v4`, it will download the checkout repository from `https://github.com/actions/checkout.git`.
 If you want to download an action from another git hoster, you can use an absolute URL, e.g. `uses: https://gitea.com/actions/checkout@v4`.
 If your Gitea instance is in an intranet or a restricted area, you can set the URL to `self` to only download actions from your own instance by default.
 Of course, you can still use absolute URLs in workflows.
 More details about the `[actions].DEFAULT_ACTIONS_URL` configuration can be found in the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions)。
 ### Context availability
-[Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability) is not checked, so contexts like `env` work in more places.
+Context availability is not checked, so you can use the env context on more places.
 See [Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability).
@@ -19,7 +19,7 @@ Additionally, the runner will introduce itself to Gitea and declare what kind of
 Earlier, we mentioned that `runs-on: ubuntu-latest` in a workflow file means that the job will be run on a runner with the `ubuntu-latest` label.
 But how does the runner know to run `ubuntu-latest`? The answer lies in mapping the label to an environment.
-That's why each label of a runner names an environment, like `my_custom_label:docker://centos:7`.
+That's why when you add custom labels during registration, you will need to input some complex content like `my_custom_label:docker://centos:7`.
 This means that the runner can take the job which needs to run on `my_custom_label`, and it will run it via a docker container with the image `centos:7`.
 Docker isn't the only option, though.
@@ -34,6 +34,7 @@ So,
 - `my_custom_label:docker://node:18`: Run jobs labeled with `my_custom_label` using the `node:18` Docker image.
 - `my_custom_label:host`: Run jobs labeled with `my_custom_label` directly on the host.
 - `my_custom_label`: Same as `my_custom_label:host`.
 - `my_custom_label:vm:ubuntu-latest`: (Example only, not implemented) Run jobs labeled with `my_custom_label` using a virtual machine with the `ubuntu-latest` ISO.
 ## Communication protocol
@@ -42,7 +43,7 @@ However, we did not think it was a good idea to have Gitea listen on a new port.
 Instead, we wanted to reuse the HTTP port, which means we needed a protocol that is compatible with HTTP.
 We chose to use gRPC over HTTP.
-The protocol is defined in [actions-proto-def](https://gitea.com/gitea/actions-proto-def), its Go code lives in [actionslib](https://gitea.com/gitea/actionslib).
+We use [actions-proto-def](https://gitea.com/gitea/actions-proto-def) and [actions-proto-go](https://gitea.com/gitea/actions-proto-go) to wire them up.
 More information about gRPC can be found on [its website](https://grpc.io/).
 ## Network architecture
@@ -70,8 +71,7 @@ However, if a job container tries to fetch code from localhost, it will fail bec
 ### Connection 3, runner to internet
 When you use some actions like `actions/checkout@v4`, the runner downloads the scripts, not the job containers.
-By default, it downloads them from [github.com](https://github.com/), which requires internet access.
+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.
 With `DEFAULT_ACTIONS_URL` set to `self`, or with `uses: self:owner/repo@ref`, it downloads them from your Gitea instance instead.
 It also downloads some docker images from Docker Hub by default, which also requires internet access.
 However, internet access is not strictly necessary.
@@ -27,24 +27,50 @@ Still, this is completely optional since both options have the same effect at th
 ## Where will the runner download scripts when using actions such as `actions/checkout@v4`?
-From `https://github.com` by default, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`, see the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
+There are tens of thousands of [actions scripts](https://github.com/marketplace?type=actions) in GitHub, and when you write `uses: actions/checkout@v4`, it downloads the scripts from [github.com/actions/checkout](http://github.com/actions/checkout) by default.
 But what if you want to use actions from other places such as gitea.com instead of GitHub?
-To use an action from elsewhere, name its host:
+The good news is that you can specify the URL prefix to use actions from anywhere.
 This is an extra syntax in Gitea Actions.
 For example:
- `uses: https://gitea.com/owner/repo@ref`
+- `uses: https://gitea.com/xxx/xxx@xxx`
- `uses: http://your_gitea_instance.com/owner/repo@ref`
+- `uses: https://github.com/xxx/xxx@xxx`
- `uses: self:owner/repo@ref` for your own Gitea instance
+- `uses: http://your_gitea_instance.com/xxx@xxx`
 Be careful, the `https://` or `http://` prefix is necessary!
 This is one of the differences from GitHub Actions which supports actions scripts only from GitHub.
 But it should allow users much more flexibility in how they run Actions.
 Alternatively, if you want your runners to download actions from your own Gitea instance by default, you can configure it by setting `[actions].DEFAULT_ACTIONS_URL`.
 See [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
 ## How to limit the permission of the runners?
-Runners only connect to your Gitea instance.
+Runners have no more permissions than simply connecting to your Gitea instance.
-For each job, a runner gets a `GITEA_TOKEN` limited to the job's repository, see [Actions job token permissions](token-permissions.md).
+When any runner receives a job to run, it will temporarily gain limited permission to the repository associated with the job.
-To give a job access to more private repositories or external systems, pass it [secrets](usage/actions/secrets.md).
+If you want to give more permissions to the runner, allowing it to access more private repositories or external systems, you can pass [secrets](usage/actions/secrets.md) to it.
 Refined permission control to Actions is a complicated job.
 In the future, we will add more options to Gitea to make it more configurable, such as allowing more write access to repositories or read access to all repositories in the same organization.
 ## Which operating systems are supported by Gitea Runner?
-Official binaries are released for Linux, macOS and Windows.
+We released official binaries for Linux, macOS, and Windows.
-Other systems supported by Go and Docker work in theory.
+While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
 One thing to note is that if you choose to run jobs directly on the host instead of in job containers, the environmental differences between operating systems may cause unexpected failures.
 For example, bash is not available on Windows in most cases, while act tries to use bash to run scripts by default.
 Therefore, you need to specify `powershell` as the default shell in your workflow file, see [defaults.run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun).
 ```yaml
 defaults:
  run:
    shell: powershell
 ```
 ## How to avoid being hacked?
@@ -73,13 +99,42 @@ It is exciting to be able to reuse them.
 ## What if it runs on multiple labels, such as `runs-on: [label_a, label_b]`?
-The job runs on a runner that has all of the labels, as on [GitHub](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
+This is valid syntax.
-The runner uses the environment of the first label it has.
+It means that it should run on runners that have both the `label_a` **and** `label_b` labels, see [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
 Unfortunately, the runner does not work this way until v0.2.11.
 As mentioned, we map labels to environments:
 - `ubuntu` → `ubuntu:22.04`
 - `centos` → `centos:8`
 But we need to map label groups to environments instead, like so:
 - `[ubuntu]` → `ubuntu:22.04`
 - `[with-gpu]` → `linux:with-gpu`
 - `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
 We also need to re-design how tasks are assigned to runners.
 A runner with `ubuntu`, `centos`, or `with-gpu` does not necessarily indicate that it can accept jobs with `[centos, with-gpu]`.
 Therefore, the runner should inform the Gitea instance that it can only accept jobs with `[ubuntu]`, `[centos]`, `[with-gpu]`, and `[ubuntu, with-gpu]`.
 This is not a technical problem, it was just overlooked in the early design.
 See [runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
 Currently, the runner attempts to match everyone in the labels and uses the first match it finds.
 ## What is the difference between agent labels and custom labels for a runner?
-Gitea no longer has custom labels.
+![labels](/images/usage/actions/labels.png)
-A runner declares its labels every time it starts, from its `runner.labels` configuration or the labels given at registration, so change them there and restart the runner.
+
 Agent labels are reported to the Gitea instance by the runner during registration.
 Custom labels, on the other hand, are added manually by a Gitea administrator or owners of the organization or repository (depending on the level of the runner).
 However, the design here needs improvement, as it currently has some rough edges.
 You can add a custom label such as `centos` to a registered runner, which means the runner will receive jobs with `runs-on: centos`.
 However, the runner may not know which environment to use for this label, resulting in it using a default image or leading to a logical dead end.
 This default may not match user expectations.
 See [runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71).
 In the meantime, we suggest that you re-register your runner if you want to change its labels.
 ## Will there be more implementations for Gitea Actions runner?
@@ -122,6 +177,3 @@ For events supported only by GitHub, see GitHub's [documentation](https://docs.g
 Go to the repository's **Settings** > **Actions** > **General** page and add collaborative owners.
 The private repositories of collaborative owners are allowed to access the actions and workflows in the current repository.
 To share within the same user or organization, add the private repositories under its **Settings** > **Actions** > **General** > **Cross-Repository Access** instead.
 See [Cross-repository access](token-permissions.md#cross-repository-access).
@@ -1,60 +0,0 @@
 ---
 date: "2026-08-23T00:00:00+00:00"
 slug: "openid-connect"
 sidebar_position: 40
 ---
 # OpenID Connect
 Jobs can request short-lived OpenID Connect (OIDC) tokens to sign in to cloud providers and other services without storing long-lived secrets. The tokens use the GitHub Actions format, so actions like `aws-actions/configure-aws-credentials`, `google-github-actions/auth` and `azure/login` work unchanged.
 ## Trusting Gitea
 Add Gitea as an OIDC identity provider in the service:
 - Issuer: `<ROOT_URL>/api/actions/oidc`
 - Audience: `<ROOT_URL>/<owner>`, unless the workflow requests another one
 Then limit which workflows can sign in with a condition on the [`sub` claim](#claims).
 Gitea signs the tokens with a key it creates at `<APP_DATA_PATH>/jwt/actions_oidc.pem`. Instances behind a load balancer must share this file.
 ## Requesting a token
 Grant the `id-token` permission to the workflow or job:
 ```yaml
 permissions:
  id-token: write
 ```
 Default permissions never include it, and jobs from fork pull requests never get it. Owners and repositories can disable it with their [maximum token permissions](token-permissions.md#maximum-token-permissions-clamping).
 Actions like the ones above request the token themselves. In a script, use `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`:
 ```shell
 curl --fail --silent --show-error \
  --header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
  "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service"
 ```
 The token is in the `value` field of the response and expires after five minutes.
 ## Claims
 The `sub` claim names the owner and repository with their IDs, so a renamed or recreated repository cannot match an existing trust policy:
 ```text
 repo:<owner>@<owner-id>/<repo>@<repo-id>:ref:<ref>
 repo:<owner>@<owner-id>/<repo>@<repo-id>:pull_request
 ```
 The `pull_request` event uses the second form, all other events use the first, including `pull_request_target`.
 The other claims match GitHub's, like `repository`, `ref`, `sha`, `workflow_ref` and `job_workflow_ref`. The discovery document at `<ROOT_URL>/api/actions/oidc/.well-known/openid-configuration` lists them all.
 Differences from GitHub Actions:
 - There is no `environment` claim.
 - Pull request runs use `refs/pull/<index>/head` and its commit, not the merge ref and merge commit.
 - `run_number` counts runs per repository, not per workflow.
@@ -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
-gitea-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,7 +69,7 @@ If this file is missing or corrupted, you can simply remove it and register agai
 Finally, it's time to start the runner:
 ```bash
-gitea-runner daemon
+./runner daemon
 ```
 And you can see the new runner in the management page:
@@ -102,8 +102,8 @@ Only a workflow that runs on an event that posts a commit status (`push`, `pull_
 Scoped workflows can call reusable workflows:
- A **local** reference (`uses: ./...` or `uses: $/...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
+- 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` or `uses: self:owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
+- A **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.
@@ -53,14 +53,13 @@ Valid access mode values for each scope are `read`, `write`, and `none`.
 - `wiki`
 - `projects`
 - `packages` (if supported by the target feature)
 - `id-token` (`write` allows requesting [OpenID Connect tokens](openid-connect.md), `read` grants nothing)
 If you specify both `contents` and a more granular scope (like `code` or `releases`), the granular scope wins for that unit.
 ### Compatibility notes
 Gitea supports a subset of GitHub Actions permission scopes.
-GitHub-only scopes such as `statuses`, `checks`, `deployments`, `security-events`, and `pages` are not currently supported by Gitea Actions.
+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:
@@ -76,18 +75,15 @@ If neither the workflow nor the job defines `permissions:`, Gitea uses the confi
 - **Permissive**: read and write permissions for most units in the job's repository (backwards-compatible default).
 - **Restricted**: read-only permissions for `code`, `releases`, and `packages` in the job's repository, and no access to other units by default.
 Neither mode includes `id-token`.
 ## Maximum token permissions (clamping)
-You can configure a maximum permission per repository unit and for `id-token`.
+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.
 Maximums saved before Gitea supported `id-token` deny it until you set it to `write`.
 ## Where to configure
@@ -99,13 +95,9 @@ You can configure defaults and maximums at:
 Note: Repository-level token permission settings are only shown once **Repository Actions** are enabled.
 ## Protected branches
 Actions job tokens must have code write permission and satisfy [branch protection rules](../access-control/protected-branches.md), including any **Gitea Actions** allowlist requirements.
 ## 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. They also get no OpenID Connect tokens.
+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
@@ -9,67 +9,53 @@ sidebar_position: 25
 ## Environment variables
 These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts).
 A `GITEA_*` name listed with a `GITHUB_*` name holds the same value.
 | Name | Description | Example |
 |---|---|---|
 | `ACT` | Always set to `true`, unless the runner is configured with `runner.set_act_env: false`. | `true` |
 | `CI` | Always set to `true`. | `true` |
-| `GITEA_ACTION`<br/>`GITHUB_ACTION` | The `id` of the current step, or its index when it has none. | `0` |
+| `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` |
-| `GITEA_ACTION_PATH`<br/>`GITHUB_ACTION_PATH` | The path where the action is located. Only set in composite actions. | `/var/run/act/actions/***` |
+| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `1.0.8` |
-| `GITEA_ACTION_REF`<br/>`GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` |
+| `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42_***/_data` |
-| `GITEA_ACTION_REPOSITORY`<br/>`GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` |
+| `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_ACTIONS`<br/>`GITHUB_ACTIONS` | Always set to `true`. `GITEA_ACTIONS` is useful to distinguish Gitea Actions from other CI systems. | `true` |
+| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` |
-| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `v5.2.4` |
+| `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_ACTOR`<br/>`GITHUB_ACTOR` | The username of the user that triggered the workflow. | `alice` |
+| `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/home/runner/work/_temp/_runner_file_commands/save_state_***` |
-| `GITEA_ACTOR_ID`<br/>`GITHUB_ACTOR_ID` | The ID of the user that triggered the workflow. | `1` |
+| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/home/runner/work/_temp/_runner_file_commands/step_summary_***` |
-| `GITEA_API_URL`<br/>`GITHUB_API_URL` | The URL of the REST API. | `https://gitea.example.com/api/v1` |
+| `GITHUB_ACTIONS` | Always set to `true`. | `true` |
-| `GITEA_BASE_REF`<br/>`GITHUB_BASE_REF` | The target branch of a pull request. | `main` |
+| `GITHUB_ACTION` | The name of the action currently running, or the step `id`. | `__run` |
-| `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` |
+| `GITHUB_ACTION_PATH` | The path where the action is located. | `/home/runner/work/_actions/actions/checkout/v4` |
-| `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/var/run/act/workflow/envs.txt` |
+| `GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` |
-| `GITEA_EVENT_NAME`<br/>`GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` |
+| `GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` |
-| `GITEA_EVENT_PATH`<br/>`GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/var/run/act/workflow/event.json` |
+| `GITHUB_ACTOR` | The username of the user that triggered the workflow. | `silverwind` |
-| `GITEA_GRAPHQL_URL`<br/>`GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ |
+| `GITHUB_API_URL` | The URL of the REST API. | `https://gitea.com/api/v1` |
-| `GITEA_HEAD_REF`<br/>`GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` |
+| `GITHUB_BASE_REF` | The target branch of a pull request. | `main` |
-| `GITEA_JOB`<br/>`GITHUB_JOB` | The `job_id` of the current job. | `build` |
+| `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` |
-| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/var/run/act/workflow/outputcmd.txt` |
+| `GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
-| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/var/run/act/workflow/pathcmd.txt` |
+| `GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ |
-| `GITEA_REF`<br/>`GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
+| `GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` |
-| `GITEA_REF_NAME`<br/>`GITHUB_REF_NAME` | The short ref name. | `main` |
+| `GITHUB_JOB` | The `job_id` of the current job. | `build` |
-| `GITEA_REF_PROTECTED`<br/>`GITHUB_REF_PROTECTED` | `true` if branch protections are configured for the ref that triggered the workflow. | `true` |
+| `GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
-| `GITEA_REF_TYPE`<br/>`GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
+| `GITHUB_REF_NAME` | The short ref name. | `main` |
-| `GITEA_REPOSITORY`<br/>`GITHUB_REPOSITORY` | The owner and repository name. | `owner/repo` |
+| `GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
-| `GITEA_REPOSITORY_ID`<br/>`GITHUB_REPOSITORY_ID` | The ID of the repository. | `123` |
+| `GITHUB_REPOSITORY` | The owner and repository name. | `gitea/docs` |
-| `GITEA_REPOSITORY_OWNER`<br/>`GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `owner` |
+| `GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `gitea` |
-| `GITEA_REPOSITORY_OWNER_ID`<br/>`GITHUB_REPOSITORY_OWNER_ID` | The ID of the repository owner. | `45` |
+| `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. | `90` |
-| `GITEA_RETENTION_DAYS`<br/>`GITHUB_RETENTION_DAYS` | The number of days that artifacts are kept, empty when kept forever. | `90` |
+| `GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
-| `GITEA_RUN_ATTEMPT`<br/>`GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
+| `GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` |
-| `GITEA_RUN_ID`<br/>`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` |
-| `GITEA_RUN_NUMBER`<br/>`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` |
-| `GITEA_SERVER_URL`<br/>`GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.example.com` |
+| `GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
-| `GITEA_SHA`<br/>`GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `GITHUB_WORKFLOW` | The name of the workflow. | `CI` |
-| `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/var/run/act/workflow/statecmd.txt` |
+| `GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/gitea/docs` |
 | `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/var/run/act/workflow/step-summary-0.md` |
 | `GITEA_TRIGGERING_ACTOR`<br/>`GITHUB_TRIGGERING_ACTOR` | The username of the user that initiated the workflow run. May differ from `GITEA_ACTOR` on re-runs. | `alice` |
 | `GITEA_WORKFLOW`<br/>`GITHUB_WORKFLOW` | The name of the workflow. | `CI` |
 | `GITEA_WORKFLOW_SHA`<br/>`GITHUB_WORKFLOW_SHA` | The commit SHA of the workflow file. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
 | `GITEA_WORKSPACE`<br/>`GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/owner/repo` |
 | `TRACEPARENT` | The W3C trace context of the job's span, so instrumented tools can add spans to the job's trace. Only set when the runner exports traces, see [Monitoring](/runner/monitoring/#opentelemetry). | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` |
 | `TRACESTATE` | Vendor-specific trace data that accompanies `TRACEPARENT`. Only set when the trace carries any. | `rojo=00f067aa0ba902b7` |
 ### Runner environment variables
 | Name | Description | Example |
 |---|---|---|
 | `ImageOS` | The OS and release of the job's image, read by `setup-*` actions. | `ubuntu24` |
 | `RUNNER_ARCH` | The architecture of the runner. | `X64` |
 | `RUNNER_DEBUG` | Set to `1` when the `ACTIONS_STEP_DEBUG` secret is `true`, unset otherwise. | `1` |
 | `RUNNER_ENVIRONMENT` | Always set to `self-hosted`. | `self-hosted` |
 | `RUNNER_NAME` | The name of the runner executing the job. | `my-runner` |
 | `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` |
 | `RUNNER_WORKSPACE` | The parent directory of `GITEA_WORKSPACE`. | `/workspace/owner` |
 ### Internal environment variables
@@ -78,11 +64,11 @@ These are used internally by the runner and actions. They are typically not need
 | Name | Description | Example |
 |---|---|---|
 | `ACTIONS_CACHE_URL` | URL for the actions cache service. | `http://192.168.1.10:8088/` |
-| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when `id-token: write` is granted. | `***` |
+| `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 `id-token: write` is granted. | `https://gitea.example.com/api/actions/oidc/token?` |
+| `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.example.com` |
+| `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.example.com/api/actions_pipeline/` |
+| `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.com/api/actions_pipeline/` |
 ## Context variables
@@ -90,39 +76,39 @@ These variables are available in workflow expressions via `${{ gitea.<name> }}`.
 | Name | Description | Example |
 |---|---|---|
-| `gitea.action`<br/>`github.action` | The `id` of the current step, or its index when it has none. | `0` |
+| `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. | `/var/run/act/actions/***` |
+| `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. | `alice` |
+| `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.example.com/api/v1` |
+| `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. | `/var/run/act/workflow/envs.txt` |
+| `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. See [Event payload](#event-payload). | `{...}` |
 | `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. | `/var/run/act/workflow/event.json` |
+| `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. | `/var/run/act/workflow/pathcmd.txt` |
+| `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. | `owner/repo` |
+| `gitea.repository`<br/>`github.repository` | The owner and repository name. | `gitea/docs` |
-| `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `owner` |
+| `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.example.com/owner/repo` |
+| `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 artifacts are kept, empty when kept forever. | `90` |
+| `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.example.com` |
+| `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). | `***` |
+| `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. | `alice` |
+| `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/owner/repo` |
+| `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` |
 ### Event payload
@@ -138,11 +124,11 @@ These fields exist in almost every payload:
 | Name | Description | Example |
 |---|---|---|
 | `gitea.event.action` | The activity type. Only set for events that have activity types, see [supported events](faq.md#what-workflow-trigger-events-does-gitea-support). | `opened` |
-| `gitea.event.repository.full_name` | The owner and name of the repository. | `owner/repo` |
+| `gitea.event.repository.full_name` | The owner and name of the repository. | `gitea/docs` |
 | `gitea.event.repository.default_branch` | The default branch of the repository. | `main` |
 | `gitea.event.repository.private` | Whether the repository is private. | `false` |
-| `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.example.com/owner/repo` |
+| `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.com/gitea/docs` |
-| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `alice` |
+| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `silverwind` |
 The remaining fields are specific to one or a few events:
@@ -157,12 +143,12 @@ The remaining fields are specific to one or a few events:
 | `gitea.event.commits` | `push` | The commits contained in the push, each with `id`, `message`, `url`, `author`, `added`, `removed` and `modified`. | `[{...}]` |
 | `gitea.event.head_commit.message` | `push` | The message of the most recent commit of the push. | `fix: broken link` |
 | `gitea.event.total_commits` | `push` | The number of commits in the push. Gitea-specific. | `3` |
-| `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.example.com/owner/repo/compare/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2...f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5` |
+| `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.com/gitea/docs/compare/a1b2c3d...e5f6a1b` |
-| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `alice` |
+| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `silverwind` |
-| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `alice/repo` |
+| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `silverwind/docs` |
 | `gitea.event.page` | `gollum` | The name of the wiki page. | `Home` |
 | `gitea.event.number` | `issues`, `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The index of the issue or pull request. Not set for `issue_comment`, use `gitea.event.issue.number` there. | `386` |
-| `gitea.event.issue.number`<br/>`gitea.event.issue.title`<br/>`gitea.event.issue.body`<br/>`gitea.event.issue.state`<br/>`gitea.event.issue.labels`<br/>`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Fix typo in README` |
+| `gitea.event.issue.number`<br/>`gitea.event.issue.title`<br/>`gitea.event.issue.body`<br/>`gitea.event.issue.state`<br/>`gitea.event.issue.labels`<br/>`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Expand gitea.event in actions docs` |
 | `gitea.event.comment.body` | `issue_comment` | The body of the comment. | `LGTM` |
 | `gitea.event.is_pull` | `issue_comment` | Whether the comment was made on a pull request. Gitea-specific, GitHub sets `issue.pull_request` on the issue object instead. | `true` |
 | `gitea.event.pull_request.number`<br/>`gitea.event.pull_request.title`<br/>`gitea.event.pull_request.body`<br/>`gitea.event.pull_request.draft`<br/>`gitea.event.pull_request.merged`<br/>`gitea.event.pull_request.state`<br/>`gitea.event.pull_request.labels`<br/>`gitea.event.pull_request.user.login` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The pull request the event happened on. | `Add caching to CI` |
@@ -15,7 +15,7 @@ creating issues and pull requests. This will cut down on the initial back and fo
 of getting some clarifying details.
 It is currently not possible to provide generic issue/pull-request templates globally.
-Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one. See [Pre-filling Issues and Pull Requests](prefill-issues-pull-requests.md) for all parameters.
+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.
 ## File names
@@ -1,42 +0,0 @@
 ---
 date: "2026-10-17T00:00:00+00:00"
 slug: "prefill-issues-pull-requests"
 sidebar_position: 14
 ---
 # Pre-filling Issues and Pull Requests
 Links to the pages for creating issues and pull requests can pre-fill the form with query parameters.
 This lets you link users from another app, a README or a project board to a form that is already categorized.
 - New issue: `/{owner}/{repo}/issues/new?…`
 - New pull request: `/{owner}/{repo}/compare/{base}...{head}?…`
 For example, this link opens a new issue with a title, two labels and an assignee:
 ```
 https://gitea.example.com/owner/repo/issues/new?title=Dashboard+crashes&label=kind/bug,area/dashboard&assignee=alice
 ```
 ## Parameters
 | Parameter     | Value                                                                       |
 | ------------- | --------------------------------------------------------------------------- |
 | `title`       | Title                                                                       |
 | `body`        | Description                                                                 |
 | `label`       | Comma-separated label IDs or names                                          |
 | `labels`      | Alias of `label`                                                            |
 | `milestone`   | Milestone ID or name                                                        |
 | `project`     | Comma-separated project IDs or titles                                       |
 | `assignee`    | Comma-separated user IDs or usernames                                       |
 | `template`    | File name of the [template](issue-pull-request-templates.md) to use         |
 | `field:<id>`  | Value of the field with this `id` in a YAML template                        |
 IDs and names can be mixed and names are matched case-insensitively. Values that don't match anything in the repository are ignored.
 Labels include the organization's labels, and closed milestones and projects can be selected too.
 Milestones and projects are only offered to users who can write to issues or pull requests, so for other users these parameters have no effect.
 The values from the link take precedence over the title, description, labels and assignees of the template.
 When there are several issue templates to choose from, the parameters are passed through to the chosen one.
 On the compare page, any of these parameters also opens the pull request form directly, as `expand=1` does.
@@ -55,11 +55,11 @@ and shows a link to the repository on the package site (as well as a link to the
 | Package owner type | User | Organization |
 |--------------------|------|--------------|
 | **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 | members of a team with write access to packages |
+| **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.
-The packages permission of an organization team applies to all packages of the organization, regardless of the repositories assigned to the team.
+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
@@ -1,9 +0,0 @@
 {
  "label": "Projects",
  "position": 60,
  "link": {
    "type": "generated-index",
    "slug": "/usage/projects",
    "description": "Plan and track work with project boards"
  }
 }
@@ -1,82 +0,0 @@
 ---
 date: "2025-11-25T18:58:22Z"
 slug: "project-workflows"
 sidebar_position: 1
 description: "Automate project boards with event-driven filters and actions."
 ---
 # Project Workflows
 Project workflows automate a project board. When an issue or pull request in the project triggers an event, each enabled workflow for that event checks its filters and applies its actions. Workflows run in Gitea and need no runner.
 ## Edit workflows
 1. Open a project and select **Workflows**.
 2. Select an event in the sidebar.
 3. Set filters and actions, then select **Save**. To change an existing workflow, select **Edit** first.
 An event can have several workflows. **Clone** copies the selected workflow so you can adapt it to other items. **Disable** pauses a workflow and keeps its configuration. **Remove** deletes it.
 ## Events
 | Event | Runs when | Filters | Actions |
 | --- | --- | --- | --- |
 | Item added to project | An item is added to the project or created in it | Apply to, labels | Move to column, labels, issue state |
 | Item removed from project | An item is removed from the project | Apply to, labels | Labels, issue state |
 | Item reopened | An item is reopened | Apply to, labels | Move to column, labels |
 | Item closed | An item is closed | Apply to, labels | Move to column, labels |
 | Item column changed | An item moves to another column | Apply to, columns, labels | Labels, issue state |
 | Code changes requested | An official reviewer requests changes on a pull request | Labels | Move to column, labels |
 | Code review approved | An official reviewer approves a pull request | Labels | Move to column, labels |
 | Pull request merged | A pull request is merged | Labels | Move to column, labels |
 ## Filters
 A workflow without filters runs for every item.
 - **Apply to**: issues, pull requests, or both.
 - **When moved from column**, **When moved to column**: the column the item left or entered.
 - **Only if it has labels**: the item must have all selected labels.
 ## Actions
 A workflow needs at least one action. Actions run in this order:
 1. **Move to column**: moves the item to a column.
 2. **Add labels**, **Remove labels**: changes the item's labels.
 3. **Issue state**: closes or reopens the item. Workflows never reopen pull requests.
 Workflow changes appear in the timeline as "Project workflow" followed by the event, and don't trigger other workflows. Workflows don't run in closed projects or for items in archived repositories.
 ## Permissions
 Anyone who can read a project can view its workflows. Managing them requires write access to the project and:
 - Repository project: write access to the repository's issues and pull requests.
 - Organization project: organization owner or site administrator.
 - User project: the project's owner.
 Access tokens limited to public repositories can't manage workflows for organization or user projects. Workflows apply their actions regardless of who triggered the event.
 ## API
 Manage workflows under the project routes of a repository (`/repos/{owner}/{repo}/projects/{id}`), an organization (`/orgs/{org}/projects/{id}`) or the authenticated user (`/user/projects/{id}`):
 | Method | Path | Purpose |
 | --- | --- | --- |
 | `GET` | `.../workflows` | List workflows |
 | `GET` | `.../workflows/{workflow_id}` | Get a workflow |
 | `POST` | `.../workflows` | Create a workflow |
 | `PATCH` | `.../workflows/{workflow_id}` | Edit a workflow, omitted fields stay unchanged |
 | `DELETE` | `.../workflows/{workflow_id}` | Delete a workflow |
 A workflow has an `event` (`item_added_to_project`, `item_removed_from_project`, `item_reopened`, `item_closed`, `item_column_changed`, `code_changes_requested`, `code_review_approved` or `pull_request_merged`), an `enabled` flag, `filters` (`issue_type`, `source_column_id`, `target_column_id`, `label_ids`) and `actions` (`column_id`, `add_label_ids`, `remove_label_ids`, `issue_state`). Each event accepts only the filters and actions listed in [Events](#events).
 ## Example
 To route new bug reports to triage, create a workflow for **Item added to project**:
 - **Apply to**: Issues only
 - **Only if it has labels**: `bug`
 - **Move to column**: Triage
 - **Add labels**: `needs-triage`
@@ -9,36 +9,25 @@ aliases:
 # Code Owners
-Gitea reads the first CODEOWNERS file found at these locations, in order:
+Gitea maintains code owner files. It looks for it in the following locations in this order:
 - `./CODEOWNERS`
 - `./docs/CODEOWNERS`
 - `./.gitea/CODEOWNERS`
-Pull requests use the base branch's rules. File views show owners from the commit
+And stops at the first found file.
 being viewed, including when browsing a branch, tag, or historical commit.
-## Patterns and owners
+File format: `<regexp rule> <@user or @org/team> [@user or @org/team]...`
-Each rule contains a pattern followed by users or organization teams.
+Regexp specified in golang Regex format.
-
+Regexp can start with `!` for negative rules - match all files except specified.
 Patterns starting with `*` or containing `/*` are parsed as glob expressions.
 General patterns are parsed as regular expressions.
 A leading `!` inverts a match.
 Special rule characters like space, backslash and `#` must be escaped with a backslash.
 When using regexp, since backslash needs to be escaped in rule level, literal dot should be written as  `\\.`
 Example file:
-```text
+```bash
-*.js @alice @bob       # This is an inline comment
+.*\\.go @user1 @user2 # This is comment
 doc/*.md @charles      # Patterns starting with "*" or containing "/*" are parsed as glob
 src/**/db*.py @david   # Use "**" to match any-level sub directories
 .*\\.go @user1 @user2   # General patterns are parsed as regexp
 test\\..*\\.js @user3   # !!! Do remeber: NOT "test.*.js", only regexp can be used for such cases
 # Comment too
 # You can assigning code owning for users or teams
 frontend/src/.*\\.js @org1/team1 @org1/team2 @user3
@@ -53,69 +42,24 @@ docs/(aws|google|azure)/[^/]*\\.(md|txt) @user8 @org1/team4
 Code owners listed in this file will automatically be requested to review pull requests
 that modify files matching at least one corresponding rule.
-## Sections
+### Escaping
-A section heading can supply default owners for the rules that follow it:
+You can escape characters `#`, ` ` (space) and `\` with `\`, like:
 ```text
 [Documentation] @org1/team-doc
 *.md
 README.md @alice
 [Frontend] @bob
 *.js
 ```
 Owners on a rule replace the section's default owners. Section names are
 case-insensitive; repeated headings belong to the same section. For each file, the
 last matching rule in each named section applies. Matching rules outside named
 sections retain Gitea's existing behavior: they all apply.
 ## Review request annotations
 Use `## review-request=true` or `## review-request=false` to control automatic
 review requests. A line annotation overrides a section annotation, which overrides
 the global value. When none is set, individual code owners receive automatic review
 requests only if they watch the repository and include pull requests in their watch
 preferences. Team-level requests are enabled by default. An explicit `true` requests
 a review regardless of the individual owner's watch preferences; `false` disables
 automatic requests for the rule.
 ```text
 ## review-request=false # global default for following rules
 *.js @alice ## review-request=true # only this rule
 [Documentation] @org1/team-doc ## review-request=true
 *.md
 private/* @bob ## review-request=false
 ```
 A standalone annotation changes the global default for subsequent rules.
 Annotations on section headings apply until the next heading. Ordinary comments
 start with `#`, including comments after annotations.
 Disabling review requests keeps code owners visible when viewing a file and
 does not waive approvals required by branch protection.
 ## Escaping
 You need to escape characters `#`, ` ` (space) and `\` with backslash `\`, e.g.:
 ```text
 dir/with\#hashtag @user1
 path\ with\ space @user2
 path/with\\backslash @user3
 ```
-Some regexp characters (`.+*?()|[]{}^$\`) should be escaped with `\\`, e.g.:
+Some character (`.+*?()|[]{}^$\`) should be escaped with `\\` inside regexp, like:
 ```
 path/\\.with\\.dots
 path/with\\+plus
 ```
-## Branch Protection Rules
+### Branch Protection Rules
 When setting up branch protection rules, you may choose to enforce code owner approval of
 modified files. This will block a PR from being merged until at least one code owner
@@ -123,7 +67,7 @@ has given approval for every applicable rule listed in the `CODEOWNERS` file.
 For example, say you have the following `CODEOWNERS` file:
-```text
+```bash
 .*\\.go @Bob
 .*\\.md @Sally @Chris
 migrations/.* @Alice
@@ -1,64 +0,0 @@
 ---
 date: "2018-06-24:00:00+02:00"
 slug: "api-usage"
 sidebar_position: 40
 aliases:
  - /zh-cn/api-usage
 ---
 # API 使用指南
 ## 开启/配置 API 访问
 通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。
 <a id="authentication"></a>
 ## 通过 API 认证
 Gitea 支持以下几种 API 认证方式：
 - HTTP basic authentication 方式
 - 通过指定 `token=...` URL 查询参数方式
 - 通过指定 `access_token=...` URL 查询参数方式
 - 通过指定 `Authorization: token ...` HTTP header 方式
 以上提及的认证方法接受相同的 apiKey token 类型，您可以在编码时通过查阅代码更好地理解这一点。
 Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。
 您可以通过您的 gitea web 界面来创建 apiKey token：
 `Settings | Applications | Generate New Token`.
 ### 关于 `Authorization:` header
 由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 `token`，类似于如下形式：
 ```
 Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
 ```
 以 `curl` 命令为例，它会以如下形式携带在请求中：
 ```
 curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
    -H "accept: application/json" \
    -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
    -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
 ```
 正如上例所示，您也可以在 GET 请求中使用同一个 token 并以 `token=` 的查询参数形式携带 token 来进行认证。
 ## 通过 API 列出您发布的令牌
 `/users/:name/tokens` 是一个特殊的接口，需要您使用 basic authentication 进行认证，具体原因在 issue 中
 [#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及，使用方法如下所示：
 ### 使用 Basic authentication 认证
 ```
 $ curl --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
 [{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
 ```
 ## 使用 Sudo 方式请求 API
 此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。
@@ -1,322 +0,0 @@
 ---
 date: "2020-01-16"
 slug: "database-prep"
 sidebar_position: 10
 aliases:
  - /zh-cn/database-prep
 ---
 # 数据库准备
 在使用 Gitea 前，您需要准备一个数据库。Gitea 支持 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（内置） 和 MSSQL（>= 2012 SP4）这几种数据库。本页将指导您准备数据库。本文档涵盖 PostgreSQL、MySQL 和 MSSQL。如果您计划使用 SQLite，则可以忽略本章内容。
 如果您使用不受支持的数据库版本，请通过 [联系我们](/help/support) 以获取有关我们的扩展支持的信息。我们可以为旧数据库提供测试和支持，并将这些修复集成到 Gitea 代码库中。
 数据库实例可以与 Gitea 实例在相同机器上（本地数据库），也可以与 Gitea 实例在不同机器上（远程数据库）。
 注意：以下所有步骤要求您的选择的数据库引擎已安装在您的系统上。对于远程数据库设置，请在数据库实例上安装服务器应用程序，在 Gitea 服务器上安装客户端程序。客户端程序用于测试 Gitea 服务器与数据库之间的连接，而 Gitea 本身使用 Go 提供的数据库驱动程序完成相同的任务。此外，请确保服务器和客户端使用相同的引擎版本，以使某些引擎功能正常工作。出于安全原因，请使用安全密码保护 `root`（MySQL）或 `postgres`（PostgreSQL）数据库超级用户。以下步骤假设您在数据库和 Gitea 服务器上都使用 Linux。
 ## MySQL/MariaDB
 1. 对于远程数据库设置，您需要让 MySQL 监听您的 IP 地址。编辑数据库实例上的 `/etc/mysql/my.cnf` 文件中的 `bind-address` 选项为：
   ```ini
   bind-address = 203.0.113.3
   ```
 2. 在数据库实例上，使用 `root` 用户登录到数据库控制台：
   ```
   mysql -u root -p
   ```
   按提示输入密码。
 3. 创建一个将被 Gitea 使用的数据库用户，并使用密码进行身份验证。以下示例中使用了 `'gitea'` 作为密码。请为您的实例使用一个安全密码。
   对于本地数据库：
   ```sql
   SET old_passwords=0;
   CREATE USER 'gitea' IDENTIFIED BY 'gitea';
   ```
   对于远程数据库：
   ```sql
   SET old_passwords=0;
   CREATE USER 'gitea'@'192.0.2.10' IDENTIFIED BY 'gitea';
   ```
   其中 `192.0.2.10` 是您的 Gitea 实例的 IP 地址。
   根据需要替换上述用户名和密码。
 4. 使用 UTF-8 字符集和大小写敏感的排序规则创建数据库。
   `utf8mb4_bin` 是 MySQL/MariaDB 的通用排序规则。
   Gitea 启动后会尝试把数据库修改为更合适的字符集 (`utf8mb4_0900_as_cs` 或者 `uca1400_as_cs`) 并在可能的情况下更改数据库。
   如果你想指定自己的字符集规则，可以在 `app.ini` 中设置 `[database].CHARSET_COLLATION`。
   ```sql
   CREATE DATABASE giteadb CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_bin';
   ```
   根据需要替换数据库名称。
 5. 将数据库上的所有权限授予上述创建的数据库用户。
   对于本地数据库：
   ```sql
   GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea';
   FLUSH PRIVILEGES;
   ```
   对于远程数据库：
   ```sql
   GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'192.0.2.10';
   FLUSH PRIVILEGES;
   ```
 6. 通过 `exit` 退出数据库控制台。
 7. 在您的 Gitea 服务器上，测试与数据库的连接：
   ```
   mysql -u gitea -h 203.0.113.3 -p giteadb
   ```
   其中 `gitea` 是数据库用户名，`giteadb` 是数据库名称，`203.0.113.3` 是数据库实例的 IP 地址。对于本地数据库，省略 `-h` 选项。
   到此您应该能够连接到数据库了。
 ## PostgreSQL
 1. 对于远程数据库设置，通过编辑数据库实例上的 postgresql.conf 文件中的 `listen_addresses` 将 `PostgreSQL` 配置为监听您的 IP 地址：
   ```ini
   listen_addresses = 'localhost, 203.0.113.3'
   ```
 2. PostgreSQL 默认使用 `md5` 质询-响应加密方案进行密码身份验证。现在这个方案不再被认为是安全的。改用 SCRAM-SHA-256 方案，通过编辑数据库服务器上的` postgresql.conf` 配置文件：
   ```ini
   password_encryption = scram-sha-256
   ```
   重启 PostgreSQL 以应用该设置。
 3. 在数据库服务器上，以超级用户身份登录到数据库控制台：
   ```
   su -c "psql" - postgres
   ```
 4. 创建具有登录权限和密码的数据库用户（在 PostgreSQL 术语中称为角色）。请使用安全的、强密码，而不是下面的 `'gitea'`：
   ```sql
   CREATE ROLE gitea WITH LOGIN PASSWORD 'gitea';
   ```
   根据需要替换用户名和密码。
 5. 使用 UTF-8 字符集创建数据库，并由之前创建的数据库用户拥有。可以根据预期内容使用任何 `libc` 排序规则，使用 `LC_COLLATE` 和 `LC_CTYPE` 参数指定：
   ```sql
   CREATE DATABASE giteadb WITH OWNER gitea TEMPLATE template0 ENCODING UTF8 LC_COLLATE 'en_US.UTF-8' LC_CTYPE 'en_US.UTF-8';
   ```
   根据需要替换数据库名称。
 6. 通过将以下身份验证规则添加到 `pg_hba.conf`，允许数据库用户访问上面创建的数据库。
   对于本地数据库：
   ```ini
   local    giteadb    gitea    scram-sha-256
   ```
   对于远程数据库：
   ```ini
   host    giteadb    gitea    192.0.2.10/32    scram-sha-256
   ```
   根据您自己的数据库名称、用户和 Gitea 实例的 IP 地址进行替换。
   注意：`pg_hba.conf` 上的规则按顺序评估，也就是第一个匹配的规则将用于身份验证。您的 PostgreSQL 安装可能附带了适用于所有用户和数据库的通用身份验证规则。如果是这种情况，您可能需要将此处提供的规则放置在此类通用规则之上。
   重启 PostgreSQL 以应用新的身份验证规则。
 7. 在您的 Gitea 服务器上，测试与数据库的连接。
   对于本地数据库：
   ```
   psql -U gitea -d giteadb
   ```
   对于远程数据库：
   ```
   psql "postgres://gitea@203.0.113.3/giteadb"
   ```
   其中 `gitea` 是数据库用户，`giteadb` 是数据库名称，`203.0.113.3` 是您的数据库实例的 IP 地址。
   您应该会被提示输入数据库用户的密码，并连接到数据库。
 ## MSSQL
 1. 以管理员身份创建登录名、使用大小写敏感排序规则的数据库及其用户。请将密码 `'gitea'` 替换为安全的密码：
   ```sql
   CREATE LOGIN gitea WITH PASSWORD = 'gitea';
   CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
   GO
   USE giteadb;
   CREATE USER gitea FOR LOGIN gitea;
   ALTER ROLE db_owner ADD MEMBER gitea;
   GO
   ```
   升级会更改数据库结构，因此该用户需要 `db_owner`，或者 `db_ddladmin`、`db_datareader` 和 `db_datawriter`。使用后者时，还需以管理员身份执行 `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;`。
 2. 在您的 Gitea 服务器上，测试与数据库的连接：
   ```sh
   sqlcmd -S 203.0.113.3 -U gitea -d giteadb
   ```
 ## 使用 TLS 进行数据库连接
 如果 Gitea 和您的数据库实例之间的通信是通过私有网络进行的，或者如果 Gitea 和数据库运行在同一台服务器上，那么可以省略本节，因为 Gitea 和数据库实例之间的安全性不会受到严重威胁。但是，如果数据库实例位于公共网络上，请使用 TLS 对数据库连接进行加密，以防止第三方拦截流量数据。
 ### 先决条件
 - 您需要两个有效的 TLS 证书，一个用于数据库实例（数据库服务器），一个用于 Gitea 实例（数据库客户端）。两个证书都必须由受信任的 CA 签名。
 - 数据库证书必须在 `X509v3 Extended Key Usage` 扩展属性中包含 `TLS Web Server Authentication`，而客户端证书则需要在相应的属性中包含 `TLS Web Client Authentication`。
 - 在数据库服务器证书中，`Subject Alternative Name` 或 `Common Name` 条目之一必须是数据库实例的完全限定域名（FQDN）（例如 `db.example.com`）。在数据库客户端证书中，上述提到的条目之一必须包含 Gitea 将用于连接的数据库用户名。
 - 您需要将 Gitea 和数据库服务器的域名映射到它们各自的 IP 地址。可以为它们设置 DNS 记录，也可以在每个系统上的 `/etc/hosts`（Windows 中的 `%WINDIR%\System32\drivers\etc\hosts`）中添加本地映射。这样可以通过域名而不是 IP 地址进行数据库连接。有关详细信息，请参阅您系统的文档。
 ### PostgreSQL TLS
 Gitea 使用的 PostgreSQL 驱动程序支持双向 TLS。在双向 TLS 中，数据库客户端和服务器通过将各自的证书发送给对方进行验证来相互认证。换句话说，服务器验证客户端证书，客户端验证服务器证书。
 1. 在数据库实例所在的服务器上，放置以下凭据：
   - `/path/to/postgresql.crt`: 数据库实例证书
   - `/path/to/postgresql.key`: 数据库实例私钥
   - `/path/to/root.crt`: 用于验证客户端证书的 CA 证书链
 2. 在 `postgresql.conf` 中添加以下选项：
   ```ini
   ssl = on
   ssl_ca_file = '/path/to/root.crt'
   ssl_cert_file = '/path/to/postgresql.crt'
   ssl_key_file = '/path/to/postgresql.key'
   ssl_min_protocol_version = 'TLSv1.2'
   ```
 3. 根据 PostgreSQL 的要求，调整凭据的所有权和权限：
   ```
   chown postgres:postgres /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
   chmod 0600 /path/to/root.crt /path/to/postgresql.crt /path/to/postgresql.key
   ```
 4. 编辑 `pg_hba.conf` 规则，仅允许 Gitea 数据库用户通过 SSL 连接，并要求客户端证书验证。
   对于 PostgreSQL 12：
   ```ini
   hostssl    giteadb    gitea    192.0.2.10/32    scram-sha-256    clientcert=verify-full
   ```
   对于 PostgreSQL 11 及更早版本：
   ```ini
   hostssl    giteadb    gitea    192.0.2.10/32    scram-sha-256    clientcert=1
   ```
   根据需要替换数据库名称、用户和 Gitea 实例的 IP 地址。
 5. 重新启动 PostgreSQL 以应用上述配置。
 6. 在运行 Gitea 实例的服务器上，将以下凭据放置在运行 Gitea 的用户的主目录下（例如 `git`）：
   - `~/.postgresql/postgresql.crt`: 数据库客户端证书
   - `~/.postgresql/postgresql.key`: 数据库客户端私钥
   - `~/.postgresql/root.crt`: 用于验证服务器证书的 CA 证书链
   注意：上述文件名在 PostgreSQL 中是硬编码的，无法更改。
 7. 根据需要调整凭据、所有权和权限：
   ```
   chown git:git ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
   chown 0600 ~/.postgresql/postgresql.crt ~/.postgresql/postgresql.key ~/.postgresql/root.crt
   ```
 8. 测试与数据库的连接：
   ```
   psql "postgres://gitea@example.db/giteadb?sslmode=verify-full"
   ```
   您将被提示输入数据库用户的密码，然后连接到数据库。
 ### MySQL/MariaDB TLS
 虽然 Gitea 使用的 MySQL 驱动程序也支持双向 TLS，但目前 Gitea 仅支持单向 TLS。有关详细信息，请参见工单＃10828。
 在单向 TLS 中，数据库客户端在连接握手期间验证服务器发送的证书，而服务器则假定连接的客户端是合法的，因为不进行客户端证书验证。
 1. 在数据库实例上放置以下凭据：
   - `/path/to/mysql.crt`: 数据库实例证书
   - `/path/to/mysql.key`: 数据库实例密钥
   - `/path/to/ca.crt`: CA 证书链。在单向 TLS 中不使用此文件，但用于验证双向 TLS 中的客户端证书。
 2. 将以下选项添加到 `my.cnf`：
   ```ini
   [mysqld]
   ssl-ca = /path/to/ca.crt
   ssl-cert = /path/to/mysql.crt
   ssl-key = /path/to/mysql.key
   tls-version = TLSv1.2,TLSv1.3
   ```
 3. 调整凭据的所有权和权限：
   ```
   chown mysql:mysql /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
   chmod 0600 /path/to/ca.crt /path/to/mysql.crt /path/to/mysql.key
   ```
 4. 重新启动 MySQL 以应用设置。
 5. Gitea 的数据库用户可能已经创建过，但只会对运行 Gitea 的服务器的 IP 地址进行身份验证。要对其域名进行身份验证，请重新创建用户，并设置其需要通过 TLS 连接到数据库：
   ```sql
   DROP USER 'gitea'@'192.0.2.10';
   CREATE USER 'gitea'@'example.gitea' IDENTIFIED BY 'gitea' REQUIRE SSL;
   GRANT ALL PRIVILEGES ON giteadb.* TO 'gitea'@'example.gitea';
   FLUSH PRIVILEGES;
   ```
   根据需要替换数据库用户名、密码和 Gitea 实例域名。
 6. 确保用于验证数据库服务器证书的 CA 证书链位于数据库和 Gitea 服务器的系统证书存储中。请参考系统文档中有关将 CA 证书添加到证书存储的说明。
 7. 在运行 Gitea 的服务器上，测试与数据库的连接：
   ```
   mysql -u gitea -h example.db -p --ssl
   ```
   至此应该成功连接到数据库了。
@@ -1,102 +0,0 @@
 ---
 date: "2023-05-24T15:00:00+08:00"
 slug: "comparison"
 sidebar_position: 15
 ---
 # 与GitHub Actions的对比
 Gitea Actions旨在与GitHub Actions兼容，差异如下。
 ## 额外功能
 <a id="absolute-action-urls"></a>
 ### Action URL绝对路径
 `uses:`支持指向任意Git托管平台的绝对URL，例如`uses: https://gitea.com/actions/checkout@v4`。
 <a id="action-prefixes"></a>
 ### Action前缀
 `uses:`支持以下前缀：
 - `self:`引用您自己的Gitea实例，例如`uses: self:owner/repo@v1`或`uses: self:owner/repo/.gitea/workflows/build.yml@v1`
 - `builtin:`运行Gitea Runner内置的Action，无需下载，Job镜像中也无需Node，例如`uses: builtin:checkout`
 `builtin:checkout`支持`actions/checkout`的`repository`、`ref`、`token`、`path`和`fetch-depth`输入，默认值相同，其他输入会使步骤失败。
 <a id="workflow-relative-actions"></a>
 ### 相对于工作流的Actions
 `$/`引用工作流所在的仓库和提交，或外层复合Action所在的仓库和提交，例如`uses: $/.gitea/actions/build`。
 与`./`不同，它无需事先检出代码。
 ### 使用Go编写Actions
 请参阅[创建Go Actions](https://blog.gitea.com/creating-go-actions/)。
 ### 支持非标准的调度语法 @yearly, @monthly, @weekly, @daily, @hourly
 `schedule`还支持`@yearly`、`@monthly`、`@weekly`、`@daily`和`@hourly`，而[GitHub不支持](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule)。
 ## 不支持的工作流语法
 ### `jobs.<job_id>.environment`
 [`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)会被忽略。
 ### 复杂的`runs-on`
 [`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)支持：
 - 静态字符串：`runs-on: self-hosted`
 - 标签数组：`runs-on: [linux, self-hosted]`
 - 字符串表达式：`runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
 - 包含表达式的数组：`runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
 ## 缺失的功能
 ### 软件包仓库授权
 `GITEA_TOKEN`无法发布到其所属仓库的软件包注册表，例如无法推送OCI镜像。
 请改用个人访问令牌，参见[此问题](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692)。
 ### 问题匹配器
 [问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)会被忽略。
 ### 为错误创建注释
 [错误注释](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)会被忽略。
 ### 表达式
 [表达式](https://docs.github.com/en/actions/learn-github-actions/expressions)支持GitHub的标准函数和上下文。
 ## 缺失的UI功能
 ### 预处理和后处理步骤
 预处理和后处理步骤在Job日志中没有单独的区块。
 ### 服务步骤
 服务步骤在Job日志中没有单独的区块。
 ## 不一样的行为
 ### `permissions`和`jobs.<job_id>.permissions`
 `permissions`和`jobs.<job_id>.permissions`控制`GITEA_TOKEN`的权限，该权限受仓库和所有者设置的限制，并在fork拉取请求和跨仓库访问时受到进一步限制。
 不支持`statuses`、`checks`、`deployments`、`security-events`和`pages`等GitHub专有的权限范围，而Gitea额外提供了`code`、`releases`、`wiki`和`projects`。`id-token`与GitHub相同，请参阅[OpenID Connect](openid-connect.md)。
 请参阅[Actions Job令牌权限](token-permissions.md)。
 ### 下载Actions
 未指定主机的Actions（如`uses: actions/checkout@v4`）会从`https://github.com`下载，当`[actions].DEFAULT_ACTIONS_URL`为`self`时则从您自己的实例下载。
 请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-actions)。
 其他来源请参阅[Action URL绝对路径](#absolute-action-urls)、[Action前缀](#action-prefixes)和[相对于工作流的Actions](#workflow-relative-actions)。
 ### 上下文可用性
 不检查[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)，因此`env`等上下文可以在更多地方使用。
@@ -1,99 +0,0 @@
 ---
 date: "2023-05-24T15:00:00+08:00"
 slug: "design"
 sidebar_position: 40
 ---
 # Gitea Actions设计
 Gitea Actions由多个组件组成。本文档将对它们进行逐个描述。
 ## Gitea Runner
 Gitea Runner部分基于[nektos/act](https://github.com/nektos/act)的硬分支。
 与其他CI Runner一样，我们将其设计为Gitea的外部部分，这意味着它应该在与Gitea不同的服务器上运行。
 为了确保Runner连接到正确的Gitea实例，我们需要使用令牌注册它。
 此外，Runner通过声明自己的标签向Gitea报告它可以运行的Job类型。
 之前，我们提到工作流文件中的 `runs-on: ubuntu-latest` 表示该Job将在具有`ubuntu-latest`标签的Runner上运行。
 但是，Runner如何知道要运行 `ubuntu-latest`？答案在于将标签映射到环境。
 这就是为什么Runner的每个标签都会指定一个环境，比如`my_custom_label:docker://centos:7`。
 这意味着Runner可以接受需要在`my_custom_label`上运行的Job，并通过使用`centos:7`镜像的Docker容器来运行它。
 然而，Docker不是唯一的选择。
 Runner 也支持直接在主机上运行Job。
 这是通过像`linux_arm:host`这样的标签实现的。
 这个标签表示Runner可以接受需要在`linux_arm`上运行的Job，并直接在主机上运行它们。
 标签的设计遵循格式`label[:schema[:args]]`。
 如果省略了schema，则默认为`host`。
 因此，
 - `my_custom_label:docker://node:18`：使用`node:18 Docker`镜像运行带有`my_custom_label`标签的Job。
 - `my_custom_label:host`：在主机上直接运行带有`my_custom_label`标签的Job。
 - `my_custom_label`：等同于`my_custom_label:host`。
 ## 通信协议
 由于 runner 是 Gitea 的独立部分，我们需要一种协议让 Runner 与 Gitea 实例进行通信。
 然而，我们不认为让Gitea监听一个新端口是个好主意。
 相反，我们希望重用HTTP端口，这意味着我们需要一个与HTTP兼容的协议。
 因此，我们选择使用基于HTTP的gRPC。
 该协议定义在[actions-proto-def](https://gitea.com/gitea/actions-proto-def)中，其Go代码位于[actionslib](https://gitea.com/gitea/actionslib)。
 有关 gRPC 的更多信息，请访问[其官方网站](https://grpc.io/)。
 ## 网络架构
 让我们来看一下整体的网络架构。
 这将帮助您解决一些问题，并解释为什么使用回环地址注册 Runner 是个不好的主意。
 ![network](/images/usage/actions/network.png)
 图片中标记了四个网络连接，并且箭头的方向表示建立连接的方向。
 ### 连接 1，runner 到 Gitea 实例
 Runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
 ### 连接 2，Job 容器到 Gitea 实例
 即使Job容器位于同一台机器上，它们的网络命名空间与Runner不同。
 举个例子，如果工作流中包含 `actions/checkout@v4`，Job容器需要连接到Gitea来获取代码。
 获取代码并不总是运行某些Job所必需的，但在大多数情况下是必需的。
 如果您使用回环地址注册Runner，当Runner与Gitea在同一台机器上时，Runner可以连接到Gitea。
 然而，如果Job容器尝试从本地主机获取代码，它将失败，因为Gitea不在同一个容器中。
 ### 连接 3，runner 到互联网
 当您使用诸如 `actions/checkout@v4` 的一些Actions时， runner下载的是脚本，而不是Job容器。
 默认情况下，它从[github.com](https://github.com/)下载这些脚本，这需要访问互联网。
 如果将`DEFAULT_ACTIONS_URL`设置为`self`，或使用`uses: self:owner/repo@ref`，它会改为从您的Gitea实例下载。
 它还默认从Docker Hub下载一些Docker镜像，这也需要互联网访问。
 然而，互联网访问并不是绝对必需的。
 您可以配置您的Gitea实例从您的内部网络设施中获取 Actions 或镜像。
 实际上，您的Gitea实例可以同时充当 Actions 市场和镜像注册表。
 您可以将GitHub上的Actions仓库镜像到您的Gitea实例，并将其用作普通Actions。
 而 [Gitea 容器注册表](usage/packages/container.md) 可用作Docker镜像注册表。
 ### 连接 4，Job容器到互联网
 当使用诸如`actions/setup-go@v5`的Actions时，可能需要从互联网下载资源，以设置Job容器中的Go语言环境。
 因此，成功完成这些Actions需要访问互联网。
 然而，这也是可选的。
 您可以使用自定义的Actions来避免依赖互联网访问，或者可以使用已安装所有依赖项的打包的Docker镜像来运行Job。
 ## 总结
 使用Gitea Actions只需要确保Runner能够连接到Gitea实例。
 互联网访问是可选的，但如果没有互联网访问，将需要额外的工作。
 换句话说：当Runner能够自行查询互联网时，它的工作效果最好，但您不需要将其暴露给互联网（无论是单向还是双向）。
 如果您在使用Gitea Actions时遇到任何网络问题，希望上面的图片能够帮助您进行故障排除。
@@ -1,63 +0,0 @@
 ---
 date: "2026-08-23T00:00:00+00:00"
 slug: "openid-connect"
 sidebar_position: 40
 ---
 # OpenID Connect
 Job可以请求短期有效的OpenID Connect（OIDC）令牌来登录云服务商和其他服务，无需存储长期有效的密钥。这些令牌采用GitHub Actions的格式，因此`aws-actions/configure-aws-credentials`、`google-github-actions/auth`和`azure/login`等Action无需修改即可使用。
 <a id="trusting-gitea"></a>
 ## 信任Gitea
 在服务中将Gitea添加为OIDC身份提供方：
 - Issuer：`<ROOT_URL>/api/actions/oidc`
 - Audience：`<ROOT_URL>/<owner>`，除非工作流请求了其他值
 然后通过[`sub`声明](#claims)上的条件限制哪些工作流可以登录。
 Gitea使用其在`<APP_DATA_PATH>/jwt/actions_oidc.pem`创建的密钥签名令牌。负载均衡器后的多个实例必须共享此文件。
 <a id="requesting-a-token"></a>
 ## 请求令牌
 为工作流或Job授予`id-token`权限：
 ```yaml
 permissions:
  id-token: write
 ```
 默认权限从不包含此权限，来自fork拉取请求的Job也永远无法获得。所有者和仓库可以通过[最大令牌权限](token-permissions.md#maximum-token-permissions-clamping)禁用它。
 上述Action会自行请求令牌。在脚本中，请使用`ACTIONS_ID_TOKEN_REQUEST_URL`和`ACTIONS_ID_TOKEN_REQUEST_TOKEN`：
 ```shell
 curl --fail --silent --show-error \
  --header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
  "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service"
 ```
 令牌位于响应的`value`字段中，五分钟后过期。
 <a id="claims"></a>
 ## 声明
 `sub`声明包含所有者和仓库的名称及ID，因此重命名或重新创建的仓库无法匹配已有的信任策略：
 ```text
 repo:<owner>@<owner-id>/<repo>@<repo-id>:ref:<ref>
 repo:<owner>@<owner-id>/<repo>@<repo-id>:pull_request
 ```
 `pull_request`事件使用第二种格式，其他所有事件（包括`pull_request_target`）使用第一种。
 其他声明与GitHub相同，例如`repository`、`ref`、`sha`、`workflow_ref`和`job_workflow_ref`。位于`<ROOT_URL>/api/actions/oidc/.well-known/openid-configuration`的发现文档列出了所有声明。
 与GitHub Actions的区别：
 - 没有`environment`声明。
 - 拉取请求的运行使用`refs/pull/<index>/head`及其提交，而不是合并引用和合并提交。
 - `run_number`按仓库计数，而不是按工作流计数。
@@ -1,131 +0,0 @@
 ---
 date: "2023-05-24T15:00:00+08:00"
 slug: "quickstart"
 sidebar_position: 10
 ---
 # 快速入门
 本页面将指导您使用Gitea Actions的过程。
 ## 设置Gitea
 首先，您需要一个Gitea实例。
 您可以按照[文档](installation/from-package.md) 来设置一个新实例或升级现有实例。
 无论您如何安装或运行Gitea，只要版本号是1.19.0或更高即可。
 从1.21.0开始，默认情况下，Actions是启用的。如果您正在使用1.21.0之前的版本，您需要将以下内容添加到配置文件中以启用它：
 ```ini
 [actions]
 ENABLED=true
 ```
 如果您想了解更多信息或在配置过程中遇到任何问题，请参考[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
 ### 设置Runner
 Gitea Actions需要[runner](https://gitea.com/gitea/runner) 来运行Job。
 为了避免消耗过多资源并影响Gitea实例，建议您在与Gitea实例分开的机器上启动Runner。
 您可以使用[预构建的二进制文件](http://dl.gitea.com/gitea-runner)或[容器镜像](https://hub.docker.com/r/gitea/runner/tags)来设置Runner。
 在进一步操作之前，建议您先使用预构建的二进制文件以命令行方式运行它，以确保它与您的环境兼容，尤其是如果您在本地主机上运行Runner。
 如果出现问题，这样调试起来会更容易。
 该Runner可以在隔离的Docker容器中运行Job，因此您需要确保已安装Docker并且Docker守护进程正在运行。
 虽然这不是严格必需的，因为Runner也可以直接在主机上运行Job，这取决于您的配置方式。
 然而，建议使用Docker运行Job，因为它更安全且更易于管理。
 在运行Runner之前，您需要使用以下命令将其注册到Gitea实例中：
 ```bash
 gitea-runner register --no-interactive --instance <instance> --token <token>
 ```
 需要两个必需的参数：`instance` 和 `token`。
 `instance`是您的Gitea实例的地址，如`http://192.168.8.8:3000`或`https://gitea.com`。
 Runner和Job容器（由Runner启动以执行Job）将连接到此地址。
 这意味着它可能与用于Web访问的`ROOT_URL`不同。
 使用回环地址（例如 `127.0.0.1` 或 `localhost`）是一个不好的选择。
 如果不确定使用哪个地址，通常选择局域网地址即可。
 `token` 用于身份验证和标识，例如 `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`。
 每个令牌都可用于注册多个Runner。通过重置链接替换为新令牌后，旧令牌将失效。
 您可以从以下位置获取不同级别的`token`,从而创建出相应级别的`runner`
 - 实例级别：管理员设置页面，例如 `<your_gitea.com>/-/admin/actions/runners`。
 - 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
 - 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。
 ![register runner](/images/usage/actions/register-runner.png)
 注册后，当前目录中将出现一个名为 `.runner` 的新文件，该文件存储了注册信息。
 请不要手动编辑该文件。
 如果该文件丢失或损坏，只需删除它然后重新注册即可。
 最后，是时候启动Runner了：
 ```bash
 gitea-runner daemon
 ```
 您可以在管理页面上看到新的Runner：
 ![view runner](/images/usage/actions/view-runner.png)
 您可以通过访问[Gitea Runner](runner) 获取更多信息。
 ### 使用Actions
 即使对于启用了Gitea实例的Actions，存储库仍默认禁用Actions。
 要启用它，请转到存储库的设置页面，例如`your_gitea.com/<owner>/repo/settings`，然后启用`Enable Repository Actions`。
 ![enable actions](/images/usage/actions/enable-actions.png)
 接下来的步骤可能相当复杂。
 您需要学习Actions的[工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)，并编写您想要的工作流文件。
 不过，我们可以从一个简单的演示开始：
 ```yaml
 name: Gitea Actions Demo
 run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀
 on: [push]
 jobs:
  Explore-Gitea-Actions:
    runs-on: ubuntu-latest
    steps:
      - run: echo "🎉 The job was automatically triggered by a ${{ gitea.event_name }} event."
      - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!"
      - run: echo "🔎 The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}."
      - name: Check out repository code
        uses: actions/checkout@v4
      - run: echo "💡 The ${{ gitea.repository }} repository has been cloned to the runner."
      - run: echo "🖥️ The workflow is now ready to test your code on the runner."
      - name: List files in the repository
        run: |
          ls ${{ gitea.workspace }}
      - run: echo "🍏 This job's status is ${{ job.status }}."
 ```
 您可以将上述示例上传为一个以`.yaml`扩展名的文件，放在存储库的`.gitea/workflows/`目录中，例如`.gitea/workflows/demo.yaml`。
 您可能会注意到，这与[GitHub Actions的快速入门](https://docs.github.com/en/actions/quickstart)非常相似。
 这是因为Gitea Actions在尽可能兼容GitHub Actions的基础上进行设计。
 请注意，演示文件中包含一些表情符号。
 请确保您的数据库支持它们，特别是在使用MySQL时。
 如果字符集不是`utf8mb4`，将出现错误，例如`Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`。
 有关更多信息，请参阅[数据库准备工作](../../installation/database-preparation.md#mysqlmariadb)。
 或者，您可以从演示文件中删除所有表情符号，然后再尝试一次。
 `on: [push]` 这一行表示当您向该存储库推送提交时，工作流将被触发。
 然而，当您上传 YAML 文件时，它也会推送一个提交，所以您应该在"Actions"标签中看到一个新的任务。
 ![view job](/images/usage/actions/view-job.png)
 做得好！您已成功开始使用Actions。
@@ -1,130 +0,0 @@
 ---
 date: "2026-03-19T00:00:00+01:00"
 slug: "token-permissions"
 sidebar_position: 30
 ---
 # Actions Job令牌权限（`GITEA_TOKEN`）
 每个Actions Job都会获得一个内置令牌（`GITEA_TOKEN`），可用于访问Gitea（通过HTTP(S)访问Git、API请求等）。
 本页面介绍Gitea如何决定该令牌可以执行哪些操作。
 在工作流中，可以通过`${{ secrets.GITEA_TOKEN }}`使用该令牌。这些设置和`permissions:`仅影响`GITEA_TOKEN`（不影响个人访问令牌等其他密钥）。关于API调用，请参阅[API认证](../../development/api-usage.md#authentication)。
 <a id="where-permissions-come-from"></a>
 ## 权限来源
 Gitea按以下顺序确定Job令牌的权限：
 1. Job级别的`permissions:`（`jobs.<job_id>.permissions`）
 2. 工作流级别的`permissions:`（顶层）
 3. 设置中的默认权限（所有者或仓库）
 然后，该结果会受到所配置的最大令牌权限的**限制**（见下文）。
 <a id="supported-workflow-syntax"></a>
 ## 支持的工作流语法
 Gitea支持与GitHub Actions兼容的`permissions:`关键字。
 <a id="scalar-values"></a>
 ### 标量值
 ```yaml
 permissions: read-all   # or: write-all
 ```
 <a id="scoped-mapping"></a>
 ### 按权限范围映射
 ```yaml
 permissions:
  contents: read
  issues: write
  pull-requests: none
 ```
 每个权限范围的有效访问模式值为`read`、`write`和`none`。
 <a id="supported-scopes"></a>
 ### 支持的权限范围
 - `contents`（适用于`code`和`releases`）
 - `code`
 - `releases`
 - `issues`
 - `pull-requests`
 - `actions`
 - `wiki`
 - `projects`
 - `packages`（如果目标功能支持）
 - `id-token`（`write`允许请求[OpenID Connect令牌](openid-connect.md)，`read`不授予任何权限）
 如果同时指定了`contents`和更细粒度的权限范围（如`code`或`releases`），则该单元以更细粒度的权限范围为准。
 <a id="compatibility-notes"></a>
 ### 兼容性说明
 Gitea支持GitHub Actions权限范围的一个子集。
 Gitea Actions目前不支持`statuses`、`checks`、`deployments`、`security-events`和`pages`等GitHub专有的权限范围。
 Gitea还提供了一些仓库单元权限范围，它们在GitHub Actions中不作为独立的权限范围存在：
 - `code`
 - `releases`
 - `wiki`
 - `projects`
 <a id="default-permission-mode"></a>
 ## 默认权限模式
 如果工作流和Job都没有定义`permissions:`，Gitea会使用所配置的默认模式：
 - **宽松**：对Job所属仓库的大多数单元拥有读写权限（向后兼容的默认值）。
 - **受限**：对Job所属仓库的`code`、`releases`和`packages`拥有只读权限，默认无权访问其他单元。
 两种模式都不包含`id-token`。
 <a id="maximum-token-permissions-clamping"></a>
 ## 最大令牌权限（限制）
 您可以为每个仓库单元以及`id-token`配置最大权限。
 Job的实际权限按以下方式计算：
 `effective = min(requested, maximum)`
 这意味着工作流可以降低Job的权限，但不能超过您配置的最大权限。
 如果未配置最大权限，则所有权限范围的最大权限默认为`write`。
 在Gitea支持`id-token`之前保存的最大权限会拒绝`id-token`，直到您将其设为`write`。
 <a id="where-to-configure"></a>
 ## 配置位置
 您可以在以下位置配置默认权限和最大权限：
 - **用户/组织**：`Settings` → `Actions` → `General`
 - **仓库**：`Settings` → `Actions` → `General`
  - 对于组织中的仓库，可以遵循所有者级别的配置，也可以通过**覆盖所有者级别的配置**选择不遵循。
 注意：仅在启用**仓库Actions**后，才会显示仓库级别的令牌权限设置。
 <a id="fork-pull-requests"></a>
 ## Fork拉取请求
 出于安全考虑，由fork拉取请求触发的工作流始终只拥有仓库内容的只读权限，与工作流的`permissions:`或设置无关。这些Job也无法获取OpenID Connect令牌。
 <a id="cross-repository-access"></a>
 ## 跨仓库访问
 默认情况下，`GITEA_TOKEN`只能访问：
 - Job所属仓库（依据计算出的权限）
 - 公开仓库（只读）
 默认拒绝访问其他私有仓库。
 用户或组织可以通过**设置 → Actions → 常规 → 跨仓库访问**，允许以只读方式访问选定的私有仓库。
 私有仓库也可以通过**设置 → Actions → 常规**允许选定的协作所有者。
 这样，这些所有者的私有仓库便可读取当前私有仓库以供Actions使用，例如私有Actions和可复用工作流。
 fork拉取请求的工作流永远不会获得对私有仓库的跨仓库访问权限，即使这些仓库已被列出。
@@ -1,110 +0,0 @@
 ---
 date: "2024-04-10T22:21:00+08:00"
 slug: "actions-variables"
 sidebar_position: 25
 ---
 # 变量
 ## 环境变量
 以下环境变量会在每次工作流运行时自动设置，可以直接访问（例如在 shell 脚本中使用 `$CI`）。
 同时列出 `GITEA_*` 和 `GITHUB_*` 名称的变量值相同。
 | 名称 | 描述 | 示例 |
 |---|---|---|
 | `ACT` | 始终为 `true`，除非 Runner 配置了 `runner.set_act_env: false`。 | `true` |
 | `CI` | 始终为 `true`。 | `true` |
 | `GITEA_ACTION`<br/>`GITHUB_ACTION` | 当前步骤的 `id`，未设置时为步骤的序号。 | `0` |
 | `GITEA_ACTION_PATH`<br/>`GITHUB_ACTION_PATH` | Action 所在的路径。仅在复合 Action 中设置。 | `/var/run/act/actions/***` |
 | `GITEA_ACTION_REF`<br/>`GITHUB_ACTION_REF` | 正在执行的 Action 的 ref。 | `v4` |
 | `GITEA_ACTION_REPOSITORY`<br/>`GITHUB_ACTION_REPOSITORY` | Action 的所有者和仓库名称。 | `actions/checkout` |
 | `GITEA_ACTIONS`<br/>`GITHUB_ACTIONS` | 始终为 `true`。`GITEA_ACTIONS` 可用于区分 Gitea Actions 和其他 CI 系统。 | `true` |
 | `GITEA_ACTIONS_RUNNER_VERSION` | 执行工作流的 Runner 的版本。 | `v5.2.4` |
 | `GITEA_ACTOR`<br/>`GITHUB_ACTOR` | 触发工作流的用户的用户名。 | `alice` |
 | `GITEA_ACTOR_ID`<br/>`GITHUB_ACTOR_ID` | 触发工作流的用户的 ID。 | `1` |
 | `GITEA_API_URL`<br/>`GITHUB_API_URL` | REST API 的 URL。 | `https://gitea.example.com/api/v1` |
 | `GITEA_BASE_REF`<br/>`GITHUB_BASE_REF` | 拉取请求的目标分支。 | `main` |
 | `GITEA_DOCKER_WORKSPACE` | Docker 守护进程所见的工作区路径，用于绑定挂载到 Job 启动的容器中，例如在 compose 文件中使用 `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data`。仅在 Job 运行于容器中时设置。 | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` |
 | `GITEA_ENV`<br/>`GITHUB_ENV` | 为后续步骤设置环境变量的文件路径。 | `/var/run/act/workflow/envs.txt` |
 | `GITEA_EVENT_NAME`<br/>`GITHUB_EVENT_NAME` | 触发工作流的事件名称。 | `push` |
 | `GITEA_EVENT_PATH`<br/>`GITHUB_EVENT_PATH` | 包含事件 Webhook 负载的文件路径。 | `/var/run/act/workflow/event.json` |
 | `GITEA_GRAPHQL_URL`<br/>`GITHUB_GRAPHQL_URL` | 在 Gitea 中为空（不支持 GraphQL）。 | _（空）_ |
 | `GITEA_HEAD_REF`<br/>`GITHUB_HEAD_REF` | 拉取请求的源分支。 | `feature-branch` |
 | `GITEA_JOB`<br/>`GITHUB_JOB` | 当前 Job 的 `job_id`。 | `build` |
 | `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | 设置步骤输出参数的文件路径。 | `/var/run/act/workflow/outputcmd.txt` |
 | `GITEA_PATH`<br/>`GITHUB_PATH` | 为后续步骤添加系统 `PATH` 条目的文件路径。 | `/var/run/act/workflow/pathcmd.txt` |
 | `GITEA_REF`<br/>`GITHUB_REF` | 触发工作流的完整 ref。 | `refs/heads/main` |
 | `GITEA_REF_NAME`<br/>`GITHUB_REF_NAME` | ref 的短名称。 | `main` |
 | `GITEA_REF_PROTECTED`<br/>`GITHUB_REF_PROTECTED` | 如果触发工作流的 ref 配置了分支保护，则为 `true`。 | `true` |
 | `GITEA_REF_TYPE`<br/>`GITHUB_REF_TYPE` | ref 的类型：`branch` 或 `tag`。 | `branch` |
 | `GITEA_REPOSITORY`<br/>`GITHUB_REPOSITORY` | 所有者和仓库名称。 | `owner/repo` |
 | `GITEA_REPOSITORY_ID`<br/>`GITHUB_REPOSITORY_ID` | 仓库的 ID。 | `123` |
 | `GITEA_REPOSITORY_OWNER`<br/>`GITHUB_REPOSITORY_OWNER` | 仓库所有者的用户名。 | `owner` |
 | `GITEA_REPOSITORY_OWNER_ID`<br/>`GITHUB_REPOSITORY_OWNER_ID` | 仓库所有者的 ID。 | `45` |
 | `GITEA_RETENTION_DAYS`<br/>`GITHUB_RETENTION_DAYS` | Artifact 的保留天数，永久保留时为空。 | `90` |
 | `GITEA_RUN_ATTEMPT`<br/>`GITHUB_RUN_ATTEMPT` | 工作流运行的尝试次数。 | `1` |
 | `GITEA_RUN_ID`<br/>`GITHUB_RUN_ID` | 每次工作流运行的唯一编号。 | `1234` |
 | `GITEA_RUN_NUMBER`<br/>`GITHUB_RUN_NUMBER` | 特定工作流每次运行的唯一编号。 | `42` |
 | `GITEA_SERVER_URL`<br/>`GITHUB_SERVER_URL` | Gitea 实例的 URL。 | `https://gitea.example.com` |
 | `GITEA_SHA`<br/>`GITHUB_SHA` | 触发工作流的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
 | `GITEA_STATE`<br/>`GITHUB_STATE` | 设置步骤状态变量的文件路径。 | `/var/run/act/workflow/statecmd.txt` |
 | `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | 写入 Job 摘要的文件路径。 | `/var/run/act/workflow/step-summary-0.md` |
 | `GITEA_TRIGGERING_ACTOR`<br/>`GITHUB_TRIGGERING_ACTOR` | 发起工作流运行的用户的用户名。重新运行时可能与 `GITEA_ACTOR` 不同。 | `alice` |
 | `GITEA_WORKFLOW`<br/>`GITHUB_WORKFLOW` | 工作流的名称。 | `CI` |
 | `GITEA_WORKFLOW_SHA`<br/>`GITHUB_WORKFLOW_SHA` | 工作流文件的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
 | `GITEA_WORKSPACE`<br/>`GITHUB_WORKSPACE` | Runner 上的默认工作目录。 | `/workspace/owner/repo` |
 | `TRACEPARENT` | Job span 的 W3C 追踪上下文，供已接入追踪的工具将 span 添加到 Job 的追踪中。仅在 Runner 导出追踪数据时设置，参见[监控](/runner/monitoring/#opentelemetry)。 | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` |
 | `TRACESTATE` | 随 `TRACEPARENT` 附带的厂商特定追踪数据。仅在追踪包含此类数据时设置。 | `rojo=00f067aa0ba902b7` |
 ### Runner 环境变量
 | 名称 | 描述 | 示例 |
 |---|---|---|
 | `ImageOS` | Job 镜像的操作系统和版本，供 `setup-*` Action 读取。 | `ubuntu24` |
 | `RUNNER_ARCH` | Runner 的架构。 | `X64` |
 | `RUNNER_DEBUG` | 当 `ACTIONS_STEP_DEBUG` 密钥为 `true` 时设置为 `1`，否则不设置。 | `1` |
 | `RUNNER_ENVIRONMENT` | 始终为 `self-hosted`。 | `self-hosted` |
 | `RUNNER_NAME` | 执行 Job 的 Runner 的名称。 | `my-runner` |
 | `RUNNER_OS` | Runner 的操作系统。 | `Linux` |
 | `RUNNER_TEMP` | Runner 上临时目录的路径。 | `/tmp` |
 | `RUNNER_TOOL_CACHE` | Runner 上工具缓存目录的路径。 | `/opt/hostedtoolcache` |
 | `RUNNER_WORKSPACE` | `GITEA_WORKSPACE` 的父目录。 | `/workspace/owner` |
 ### 内部环境变量
 这些变量供 Runner 和 Action 内部使用，工作流中通常不需要直接使用。
 | 名称 | 描述 | 示例 |
 |---|---|---|
 | `ACTIONS_CACHE_URL` | Actions 缓存服务的 URL。 | `http://192.168.1.10:8088/` |
 | `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | 用于 OIDC 请求的令牌。仅在授予 `id-token: write` 时设置。 | `***` |
 | `ACTIONS_ID_TOKEN_REQUEST_URL` | 请求 OIDC 令牌的 URL。仅在授予 `id-token: write` 时设置。 | `https://gitea.example.com/api/actions/oidc/token?` |
 | `ACTIONS_RESULTS_URL` | 存储 Artifact 的 URL。 | `https://gitea.example.com` |
 | `ACTIONS_RUNTIME_TOKEN` | Actions 流水线 API 的认证令牌。 | `***` |
 | `ACTIONS_RUNTIME_URL` | Gitea Actions 流水线 API 的 URL。 | `https://gitea.example.com/api/actions_pipeline/` |
 ## 用户定义的变量
 您可以创建用户、组织和仓库级别的变量。变量的级别取决于创建它的位置。当创建变量时，变量的名称会被
 转换为大写，在yaml文件中引用时需要使用大写。
 ### 命名规则
 以下规则适用于变量名：
 - 变量名称只能包含字母数字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下划线 (`_`)。不允许使用空格。
 - 变量名称不能以 `GITHUB_` 和 `GITEA_` 前缀开头。
 - 变量名称不能以数字开头。
 - 变量名称不区分大小写。
 - 变量名称在创建它们的级别上必须是唯一的。
 - 变量名称不能为 `CI`。
 ### 使用
 创建配置变量后，它们将自动填充到 `vars` 上下文中。您可以在工作流中使用类似 `${{ vars.VARIABLE_NAME }}` 这样的表达式来使用它们。
 ### 优先级
 如果同名变量存在于多个级别，则级别最低的变量优先。
 仓库级别的变量总是比组织或者用户级别的变量优先被选中。
@@ -1,9 +0,0 @@
 {
  "label": "项目",
  "position": 60,
  "link": {
    "type": "generated-index",
    "slug": "/usage/projects",
    "description": "使用项目看板规划和跟踪工作"
  }
 }
@@ -1,82 +0,0 @@
 ---
 date: "2025-11-25T18:58:22Z"
 slug: "project-workflows"
 sidebar_position: 1
 description: "通过事件驱动的过滤器和动作自动化项目看板。"
 ---
 # 项目工作流
 项目工作流可自动化项目看板。当项目中的问题或合并请求触发事件时，该事件下每个已启用的工作流都会检查其过滤条件并执行相应动作。工作流在 Gitea 中运行，无需运行器。
 ## 编辑工作流
 1. 打开项目并选择 **Workflows**。
 2. 在侧边栏中选择事件。
 3. 设置过滤器和动作，然后选择 **Save**。要修改现有工作流，请先选择 **Edit**。
 一个事件可以有多个工作流。**Clone** 会复制选中的工作流，便于调整后用于其他条目。**Disable** 会暂停工作流并保留其配置。**Remove** 会删除工作流。
 ## 事件
 | 事件 | 触发时机 | 过滤器 | 动作 |
 | --- | --- | --- | --- |
 | Item added to project | 条目被添加到项目或在项目中创建时 | Apply to、标签 | Move to column、标签、问题状态 |
 | Item removed from project | 条目被移出项目时 | Apply to、标签 | 标签、问题状态 |
 | Item reopened | 条目被重新打开时 | Apply to、标签 | Move to column、标签 |
 | Item closed | 条目被关闭时 | Apply to、标签 | Move to column、标签 |
 | Item column changed | 条目移至另一列时 | Apply to、列、标签 | 标签、问题状态 |
 | Code changes requested | 正式审查者要求修改合并请求时 | 标签 | Move to column、标签 |
 | Code review approved | 正式审查者批准合并请求时 | 标签 | Move to column、标签 |
 | Pull request merged | 合并请求被合并时 | 标签 | Move to column、标签 |
 ## 过滤器
 未设置过滤器的工作流会对每个条目运行。
 - **Apply to**：问题、合并请求或两者。
 - **When moved from column**、**When moved to column**：条目离开或进入的列。
 - **Only if it has labels**：条目必须包含所有选中的标签。
 ## 动作
 工作流至少需要一个动作。动作按以下顺序执行：
 1. **Move to column**：将条目移至某一列。
 2. **Add labels**、**Remove labels**：更改条目的标签。
 3. **Issue state**：关闭或重新打开条目。工作流不会重新打开合并请求。
 工作流所做的更改在时间线中显示为“Project workflow”及其后的事件名称，且不会触发其他工作流。工作流不会在已关闭的项目中运行，也不会处理已归档仓库中的条目。
 ## 权限
 任何拥有项目读取权限的人都可以查看其工作流。管理工作流需要项目的写入权限，并满足以下条件：
 - 仓库项目：拥有该仓库的问题和合并请求的写入权限。
 - 组织项目：是组织所有者或站点管理员。
 - 用户项目：是项目所有者。
 仅限公开仓库的访问令牌无法管理组织或用户项目的工作流。无论谁触发事件，工作流都会执行其动作。
 ## API
 可通过仓库（`/repos/{owner}/{repo}/projects/{id}`）、组织（`/orgs/{org}/projects/{id}`）或已认证用户（`/user/projects/{id}`）的项目路由管理工作流：
 | 方法 | 路径 | 用途 |
 | --- | --- | --- |
 | `GET` | `.../workflows` | 列出工作流 |
 | `GET` | `.../workflows/{workflow_id}` | 获取工作流 |
 | `POST` | `.../workflows` | 创建工作流 |
 | `PATCH` | `.../workflows/{workflow_id}` | 编辑工作流，未提供的字段保持不变 |
 | `DELETE` | `.../workflows/{workflow_id}` | 删除工作流 |
 工作流包含 `event`（`item_added_to_project`、`item_removed_from_project`、`item_reopened`、`item_closed`、`item_column_changed`、`code_changes_requested`、`code_review_approved` 或 `pull_request_merged`）、`enabled` 标志、`filters`（`issue_type`、`source_column_id`、`target_column_id`、`label_ids`）以及 `actions`（`column_id`、`add_label_ids`、`remove_label_ids`、`issue_state`）。每个事件仅接受[事件](#事件)表中列出的过滤器和动作。
 ## 示例
 要将新的缺陷报告分流至待分类列，请为 **Item added to project** 创建工作流：
 - **Apply to**：Issues only
 - **Only if it has labels**：`bug`
 - **Move to column**：Triage
 - **Add labels**：`needs-triage`
@@ -1,373 +0,0 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "install-with-docker"
 sidebar_position: 70
 aliases:
  - /zh-cn/install-with-docker
 ---
 # 使用 Docker 安装
 Gitea 在其 Docker Hub 组织内提供自动更新的 Docker 镜像。可以始终使用最新的稳定标签或使用其他服务来更新 Docker 镜像。
 该参考设置指导用户完成基于 `docker-compose` 的设置，但是 `docker-compose` 的安装不在本文档的范围之内。要安装 `docker-compose` 本身，请遵循官方[安装说明](https://docs.docker.com/compose/install/)。
 ## 基本
 最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 安装的是最新的稳定版本。对于稳定的发行版，您也可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。如果您想使用最新的开发版本，则可以使用 `:main-nightly` 标签；如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly`）。
 ```yaml
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 ```
 ## 端口
 要将集成的 openSSH 守护进程和 Web 服务器绑定到其他端口，请调整端口部分。通常，只需更改主机端口，容器内的端口保持原样即可。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
 -     - "3000:3000"
 -     - "222:22"
 +     - "8080:3000"
 +     - "2221:22"
 ```
 ## 数据库
 ### MySQL 数据库
 要将 Gitea 与 MySQL 数据库结合使用，请将这些更改应用于上面创建的 `docker-compose.yml` 文件。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
 +      - GITEA__database__DB_TYPE=mysql
 +      - GITEA__database__HOST=db:3306
 +      - GITEA__database__NAME=gitea
 +      - GITEA__database__USER=gitea
 +      - GITEA__database__PASSWD=gitea
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 +    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
 +    networks:
 +      - gitea
 +    volumes:
 +      - ./mysql:/var/lib/mysql
 ```
 ### PostgreSQL 数据库
 要将 Gitea 与 PostgreSQL 数据库结合使用，请将这些更改应用于上面创建的 `docker-compose.yml` 文件。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
 +      - GITEA__database__DB_TYPE=postgres
 +      - GITEA__database__HOST=db:5432
 +      - GITEA__database__NAME=gitea
 +      - GITEA__database__USER=gitea
 +      - GITEA__database__PASSWD=gitea
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 +    depends_on:
 +      - db
 +
 +  db:
 +    image: docker.io/library/postgres:14
 +    restart: always
 +    environment:
 +      - POSTGRES_USER=gitea
 +      - POSTGRES_PASSWORD=gitea
 +      - POSTGRES_DB=gitea
 +    networks:
 +      - gitea
 +    volumes:
 +      - ./postgres:/var/lib/postgresql/data
 ```
 ## 命名卷
 要使用命名卷而不是主机卷，请在 `docker-compose.yml` 配置中定义并使用命名卷。此更改将自动创建所需的卷。您无需担心命名卷的权限；Docker 将自动处理该问题。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 +volumes:
 +  gitea:
 +    driver: local
 +
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    restart: always
    networks:
      - gitea
    volumes:
 -      - ./gitea:/data
 +      - gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 ```
 MySQL 或 PostgreSQL 容器将需要分别创建。
 ## 启动
 要基于 `docker-compose` 启动此设置，请执行 `docker-compose up -d`，以在后台启动 Gitea。使用 `docker-compose ps` 将显示 Gitea 是否正确启动。可以使用 `docker-compose logs` 查看日志。
 要关闭设置，请执行 `docker-compose down`。这将停止并杀死容器。这些卷将仍然存在。
 注意：如果在 http 上使用非 3000 端口，请更改 app.ini 以匹配 `LOCAL_ROOT_URL = http://localhost:3000/`。
 ## 安装
 通过 `docker-compose` 启动 Docker 安装后，应该可以使用喜欢的浏览器访问 Gitea，以完成安装。访问 http://server-ip:3000 并遵循安装向导。如果数据库是通过上述 `docker-compose` 设置启动的，请注意，必须将 `db` 用作数据库主机名。
 ## 环境变量
 您可以通过环境变量配置 Gitea 的一些设置：
 （默认值以**粗体**显示）
 - `APP_NAME`：**“Gitea: Git with a cup of tea”**：应用程序名称，在页面标题中使用。
 - `RUN_MODE`：**prod**：应用程序运行模式，会影响性能和调试。"dev"，"prod"或"test"。
 - `DOMAIN`：**localhost**：此服务器的域名，用于 Gitea UI 中显示的 http 克隆 URL。
 - `SSH_DOMAIN`：**localhost**：该服务器的域名，用于 Gitea UI 中显示的 ssh 克隆 URL。如果启用了安装页面，则 SSH 域服务器将采用以下形式的 DOMAIN 值（保存时将覆盖此设置）。
 - `SSH_PORT`：**22**：克隆 URL 中显示的 SSH 端口。
 - `SSH_LISTEN_PORT`：**%(SSH_PORT)s**：内置 SSH 服务器的端口。
 - `DISABLE_SSH`：**false**：如果不可用，请禁用 SSH 功能。如果要禁用 SSH 功能，则在安装 Gitea 时应将 SSH 端口设置为 `0`。
 - `HTTP_PORT`：**3000**：HTTP 监听端口。
 - `ROOT_URL`：**""**：覆盖自动生成的公共 URL。如果内部 URL 和外部 URL 不匹配（例如在 Docker 中），这很有用。
 - `LFS_START_SERVER`：**false**：启用 git-lfs 支持。
 - `DB_TYPE`：**sqlite3**：正在使用的数据库类型[mysql，postgres，mssql，sqlite3]。
 - `DB_HOST`：**localhost:3306**：数据库主机地址和端口。
 - `DB_NAME`：**gitea**：数据库名称。
 - `DB_USER`：**root**：数据库用户名。
 - `DB_PASSWD`：**"_empty_"** ：数据库用户密码。如果您在密码中使用特殊字符，请使用“您的密码”进行引用。
 - `INSTALL_LOCK`：**false**：禁止访问安装页面。
 - `SECRET_KEY`：**""** ：全局密钥。这应该更改。如果它具有一个值并且 `INSTALL_LOCK` 为空，则 `INSTALL_LOCK` 将自动设置为 `true`。
 - `DISABLE_REGISTRATION`：**false**：禁用注册，之后只有管理员才能为用户创建帐户。
 - `REQUIRE_SIGNIN_VIEW`：**false**：启用此选项可强制用户登录以查看任何页面。
 - `USER_UID`：**1000**：在容器内运行 Gitea 的用户的 UID（Unix 用户 ID）。如果使用主机卷，则将其与 `/data` 卷的所有者的 UID 匹配（对于命名卷，则不需要这样做）。
 - `USER_GID`：**1000**：在容器内运行 Gitea 的用户的 GID（Unix 组 ID）。如果使用主机卷，则将其与 `/data` 卷的所有者的 GID 匹配（对于命名卷，则不需要这样做）。
 ## 自定义
 [此处](../administration/customizing-gitea.md)描述的定制文件应放在 `/data/gitea` 目录中。如果使用主机卷，则访问这些文件非常容易；对于命名卷，可以通过另一个容器或通过直接访问 `/var/lib/docker/volumes/gitea_gitea/_data` 来完成。安装后，配置文件将保存在 `/data/gitea/conf/app.ini` 中。
 ## 升级
 :::warning
 :exclamation::exclamation: **确保已将数据卷到 Docker 容器外部的某个位置** :exclamation::exclamation:
 :::
 要将安装升级到最新版本：
 ```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
 ```
 ## 使用环境变量管理部署
 除了上面的环境变量之外，`app.ini` 中的任何设置都可以使用以下形式的环境变量进行设置或覆盖：`GITEA__SECTION_NAME__KEY_NAME`。 每次 docker 容器启动时都会应用这些设置。 完整信息在[这里](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini)。
 ```bash
 ...
 services:
  server:
    environment:
      - GITEA__mailer__ENABLED=true
      - GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
      - GITEA__mailer__PROTOCOL=smtps
      - GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
      - GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
      - GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
 ```
 Gitea 将为每次新安装自动生成新的 `SECRET_KEY` 并将它们写入 `app.ini`。 如果您想手动设置 `SECRET_KEY`，您可以使用以下 docker 命令来使用 Gitea 内置的[方法](../administration/command-line.md#generate)生成 `SECRET_KEY`。 安装后请妥善保管您的 `SECRET_KEY`，如若丢失则无法解密已加密的数据。
 以下命令将向 `stdout` 输出一个新的 `SECRET_KEY` 和 `INTERNAL_TOKEN`，然后您可以将其放入环境变量中。
 ```bash
 docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret SECRET_KEY
 docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKEN
 ```
 ```yaml
 ---
 services:
  server:
    environment:
      - GITEA__security__SECRET_KEY=[value returned by generate secret SECRET_KEY]
      - GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
 ```
 ## SSH 容器直通
 由于 SSH 在容器内运行，因此，如果需要 SSH 支持，则需要将 SSH 从主机传递到容器。一种选择是在非标准端口上运行容器 SSH（或将主机端口移至非标准端口）。另一个可能更直接的选择是将 SSH 连接从主机转发到容器。下面将说明此设置。
 本指南假定您已经在名为 `git` 的主机上创建了一个用户，该用户与容器值 `USER_UID`/`USER_GID` 共享相同的 `UID`/`GID`。这些值可以在 `docker-compose.yml` 中设置为环境变量：
 ```bash
 environment:
  - USER_UID=1000
  - USER_GID=1000
 ```
 接下来将主机的 `/home/git/.ssh` 装入容器。否则，SSH 身份验证将无法在容器内运行。
 ```bash
 volumes:
  - /home/git/.ssh/:/data/git/.ssh
 ```
 现在，需要在主机上创建 SSH 密钥对。该密钥对将用于向主机验证主机上的 `git` 用户。
 ```bash
 sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
 ```
 在下一步中，需要在主机上创建一个名为 `/usr/local/bin/gitea` 的文件（具有可执行权限）。该文件将发出从主机到容器的 SSH 转发。将以下内容添加到 `/usr/local/bin/gitea`：
 ```bash
 ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
 ```
 为了使转发正常工作，需要将容器（22）的 SSH 端口映射到 `docker-compose.yml` 中的主机端口 2222。由于此端口不需要暴露给外界，因此可以将其映射到主机的 `localhost`：
 ```bash
 ports:
  # [...]
  - "127.0.0.1:2222:22"
 ```
 另外，主机上的 `/home/git/.ssh/authorized_keys` 需要修改。它需要以与 Gitea 容器内的 `authorized_keys` 相同的方式进行操作。因此，将您在上面创建的密钥（“Gitea 主机密钥”）的公共密钥添加到 `/home/git/.ssh/authorized_keys`。这可以通过 `echo "$(cat /home/git/.ssh/id_rsa.pub)" >> /home/git/.ssh/authorized_keys` 完成。重要提示：来自 `git` 用户的公钥需要“按原样”添加，而通过 Gitea 网络界面添加的所有其他公钥将以 `command="/app [...]` 作为前缀。
 该文件应该看起来像：
 ```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>
 ```
 这是详细的说明，当发出 SSH 请求时会发生什么：
 1. 使用 `git` 用户向主机发出 SSH 请求，例如 `git clone git@domain:user/repo.git`。
 2. 在 `/home/git/.ssh/authorized_keys` 中，该命令执行 `/usr/local/bin/gitea` 脚本。
 3. `/usr/local/bin/gitea` 将 SSH 请求转发到端口 2222，该端口已映射到容器的 SSH 端口（22）。
 4. 由于 `/home/git/.ssh/authorized_keys` 中存在 `git` 用户的公钥，因此身份验证主机 → 容器成功，并且 SSH 请求转发到在 docker 容器中运行的 Gitea。
 如果在 Gitea Web 界面中添加了新的 SSH 密钥，它将以与现有密钥相同的方式附加到 `.ssh/authorized_keys` 中。
 **注意**
 SSH 容器直通仅在以下情况下有效
 - 在容器中使用 `opensshd`
 - 如果未将 `AuthorizedKeysCommand` 与 `SSH_CREATE_AUTHORIZED_KEYS_FILE = false` 结合使用以禁用授权文件密钥生成
 - `LOCAL_ROOT_URL` 不变
@@ -1,29 +0,0 @@
 {
  "sidebar.docs.category.Installation": {
    "message": "安装"
  },
  "sidebar.docs.category.Administration": {
    "message": "管理"
  },
  "sidebar.docs.category.Usage": {
    "message": "使用"
  },
  "sidebar.docs.category.actions": {
    "message": "Actions"
  },
  "sidebar.docs.category.packages": {
    "message": "软件包"
  },
  "sidebar.docs.category.Development": {
    "message": "开发"
  },
  "sidebar.docs.category.Contributing": {
    "message": "贡献"
  },
  "sidebar.docs.category.Help": {
    "message": "帮助"
  },
  "sidebar.docs.doc.What is Gitea?": {
    "message": "Gitea是什么?"
  }
 }
@@ -1,9 +0,0 @@
 {
  "label": "运维",
  "position": 30,
  "link": {
    "type": "generated-index",
    "slug": "/administration",
    "title": "运维"
  }
 }
@@ -1,34 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: adding-legal-pages
 sidebar_position: 110
 aliases:
  - /zh-cn/adding-legal-pages
 ---
 # 添加法律页面
 一些法域（例如欧盟）要求在网站上添加特定的法律页面（例如隐私政策）。按照以下步骤将它们添加到你的 Gitea 实例中。
 ## 获取页面
 Gitea 源代码附带了示例页面，位于 `contrib/service/sample-page` 目录中。将它们复制到 `custom/public/assets/` 目录下。例如，如果要添加隐私政策：
 ```
 wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/service/sample-page/privacy.html.sample
 ```
 现在，你需要编辑该页面以满足你的需求。特别是，你必须更改电子邮件地址、网址以及与 "Your Gitea Instance" 相关的引用，以匹配你的情况。
 请务必不要放置会暗示 Gitea 项目对你的服务器负责的一般服务条款或隐私声明。
 ## 使其可见
 创建或追加到 `/path/to/custom/templates/custom/extra_links_footer.tmpl` 文件中：
 ```go
 <a class="item" href="{{AppSubUrl}}/assets/privacy.html">隐私政策</a>
 ```
 重启 Gitea 以查看更改。
@@ -1,301 +0,0 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "authentication"
 sidebar_position: 10
 aliases:
  - /zh-cn/authentication
 ---
 # 认证
 ## 轻量级目录访问协议（Lightweight Directory Access Protocol，LDAP）
 通过 BindDN 的 LDAP 和简单认证方式 LDAP 共享以下字段:
 - 认证名称 **(必选)**
  - 分配给新授权方法的名称。
 - 主机名 **(必选)**
  - LDAP 服务的主机地址.
  - 例如:`mydomain.com`
 - 端口号 **(必选)**
  - LDAP 服务的端口号.
  - 例如: LDAP `389`/ LDAPs `636`
 - 安全协议 (可选)
  - 连接 LDAP 服务器时是否使用 TLS 协议。
 - 管理员过滤规则 (可选)
  - 一个 LDAP 过滤器，用于指定哪些用户应该被赋予管理员特权。如果用户帐户符合过滤器条件，则该用户将被授予管理员权限。
  - 示例:`(objectClass=adminAccount)`
  - 适用于 Microsoft Active Directory（AD）的示例:`memberOf=CN=admin-group,OU=example,DC=example,DC=org`
 - 用户名属性（可选）
  - 用户 LDAP 记录中包含用户名称的属性。在第一次成功登录后，将使用指定的属性值作为新的 Gitea 账户用户名。若留空，则使用登录表单上提供的用户名。
  - 当提供的登录名与多个属性匹配时，这一选项非常有用，但是只有一个特定属性应该用于 Gitea 账户名称，请参阅"用户过滤器"。
  - 示例:uid
  - 适用于 Microsoft Active Directory（AD）的示例:`sAMAccountName`
 - 名字属性（可选）
  - 用户 LDAP 记录中包含用户名字的属性。将用于填充他们的账户信息。
  - 示例:givenName
 - 姓氏属性（可选）
  - 用户 LDAP 记录中包含用户姓氏的属性。将用于填充他们的账户信息。
  - 示例:`sn`
 - 电子邮件属性 **(必选)**
  - 用户 LDAP 记录中包含用户电子邮件地址的属性。将用于填充他们的账户信息。
  - 示例:`mail`
 ### LDAP(via BindDN)
 需要额外设置以下字段:
 - 绑定 DN (可选)
  - 搜索用户时绑定到 LDAP 服务器的 DN。这可以留空以执行匿名搜索。
  - 示例: `cn=Search,dc=mydomain,dc=com`
 - 绑定密码 (可选)
  - 上述指定的 Bind DN（绑定区别名）的密码，如果有的话。注意：该密码在服务器上使用 SECRET_KEY 进行加密存储。仍然建议确保 Bind DN 具有尽可能少的权限。
 - 用户搜索基准 **(必选)**
  - 这是用于搜索用户帐户的 LDAP 基础路径.
  - 示例: `ou=Users,dc=mydomain,dc=com`
 - 用户过滤规则 **(必选)**
  - LDAP 过滤器声明如何查找试图进行身份验证的用户记录
    `%[1]s`匹配参数将替换为登录表单中给出的登录名
  - 示例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
  - 示例 for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
  - 如需多次替换，应使用 `%[1]s`，例如在将提供的登录名与多个属性（如用户标识符、电子邮件甚至电话号码）进行匹配时。
  - 示例: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))`
 - 启用用户同步
  - 这个选项启用了一个周期性任务，用于将 Gitea 用户与 LDAP 服务器进行同步。默认的同步周期是每 24 小时，
    但您可以在 app.ini 文件中进行更改。
    有关此部分的详细说明，请参阅[sample
    app.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
    的*cron.sync_external_users* 部分的注释。前面提到的*User Search Base*和*User Filter*
    设置将限制哪些用户可以使用 Gitea 以及哪些用户将被同步。
    在初始运行任务时，将根据给定的设置创建所有与 LDAP 匹配的用户，因此在使用大型企业 LDAP 目录时需要小心。
 ### LDAP(simple auth)
 需要额外设置以下字段:
 - 用户 DN **(必选)**
  - 用作用户 DN 的模板。匹配参数 `%s` 将替换为登录表单中的登录名。
  - 示例: `cn=%s,ou=Users,dc=mydomain,dc=com`
  - 示例: `uid=%s,ou=Users,dc=mydomain,dc=com`
 - 用户搜索基准 (可选)
  - 用户搜索基准声明哪些用户帐户将被搜索.
  - 示例: `ou=Users,dc=mydomain,dc=com`
 - 用户过滤规则 **(必选)**
  - LDAP 过滤器声明何时允许用户登录
    `%[1]s`匹配参数将替换为登录表单中给出的登录名。
  - 示例: `(&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))`
  - 示例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
 ### 使用 LDAP 验证分组成员
 使用以下字段:
 - 群组搜索基础 DN(可选)
  - 组使用的 LDAP DN。
  - 示例: `ou=group,dc=mydomain,dc=com`
 - 组名过滤器 (可选)
  - LDAP 过滤器，声明如何在上述 DN 中查找有效组。
  - 示例: `(|(cn=gitea_users)(cn=admins))`
 - 组中的用户属性 (可选)
  - 组中列出了哪个用户的 LDAP 属性。
  - 示例: `uid`
 - 用户组属性 (可选)
  - 哪个组的 LDAP 属性包含一个高于用户属性名称的数组。
  - 示例: `memberUid`
 ## 可插拔式认证模块(Pluggable Authentication Module,PAM)
 这个过程启用了 PAM（Pluggable Authentication Modules）认证。用户仍然可以通过用户管理手动添加到系统中。
 PAM 提供了一种机制，通过对用户进行 PAM 认证来自动将其添加到当前数据库中。为了与普通的 Linux 密码一起使用，
 运行 Gitea 的用户还必须具有对`/etc/shadow`的读取权限，以便在使用公钥登录时检查账户的有效性。
 **注意**:如果用户已将 SSH 公钥添加到 Gitea 中，使用这些密钥可能会绕过登录检查系统。因此，
 如果您希望禁用使用 PAM 进行身份验证的用户，应该在 Gitea 中手动禁用该账户，使用内置的用户管理功能。
 1. 配置和安装准备.
   - 建议您创建一个管理用户.
   - 建议取消自动注册.
 1. 一旦数据库已初始化完成，使用新创建的管理员账户登录.
 1. 导航至用户设置（右上角的图标），然后选择
   `Site Administration` -> `Authentication Sources`, 并选择
   `Add Authentication Source`.
 1. 填写字段如下:
   - 认证类型:`PAM`。
   - 名称:任何有效的值都可以，如果您愿意，可以使用"System Authentication"。
   - PAM 服务名称:从/etc/pam.d/目录下选择适用于所需认证的正确文件[^1]。
   - PAM 电子邮件域:用户认证时要附加的电子邮件后缀。例如，如果登录系统期望一个名为 gituse 的用户，
     并且将此字段设置为 mail.com，那么 Gitea 在验证一个 GIT 实例的用户时将期望 user emai 字段为gituser@mail.com[^2]。
 **Note**: PAM 支持通过[build-time flags](installation/from-source.md#build)添加,
 而官方提供的二进制文件通常不会默认启用此功能。PAM 需要确保系统上有必要的 libpam 动态库，并且编译器可以访问必要的 PAM 开发头文件。
 [^1]:
    例如，在 Debian "Bullseye"上使用标准 Linux 登录，可以使用`common-session-noninteractive`。这个值对于其他版本的 Debian，
    包括 Ubuntu 和 Mint，可能也是有效的，请查阅您所使用发行版的文档以确认。
 [^2]: **PAM 的必选项** 请注意:在上面的示例中，用户将作为`gituser`而不是`[email protected]`登录到 Gitea 的 Web 界面。
 ## 简单邮件传输协议(Simple Mail Transfer Protocol,SMTP)
 此选项允许 Gitea 以 Gitea 用户身份登录 SMTP 主机。请设置以下字段:
 - 身份验证名称 **(必选)**
  - 分配给新授权方法的名称
 - SMTP 验证类型 **(必选)**
  - 用于连接 SMTP 主机的验证类型，plain 或 login
 - 主机名 **(必选)**
  - SMTP 服务的主机地址
  - 例如:`smtp.mydomain.com`
 - 端口号 **(必选)**
  - SMTP 服务的端口号
  - 例如: `587`
 - 允许的域名
  - 如果使用公共 SMTP 主机或有多个域的 SMTP 主机，限制哪些域可以登录
    限制哪些域可以登录。
  - 示例: `gitea.com,mydomain.com,mydomain2.com`
 - 强制使用 SMTPS
  - 默认情况下将使用 SMTPS 连接到端口 465.如果您希望将 smtp 用于其他端口，自行设置
  - 否则，如果服务器提供' STARTTLS '扩展名，则将使用此扩展名
 - 跳过 TLS 验证
  - 禁用 TLS 验证身份.
 - 该认证源处于激活状态
  - 启用或禁用此身份验证源
 ## FreeIPA
 - 要使用 FreeIPA 凭据登录 Gitea，需要为 Gitea 创建一个绑定帐户。
  创建一个绑定帐户:
 - 在 FreeIPA 服务器上创建一个 gitea.ldif 文件，并将`dc=example,dc=com`替换为您的`dn`，然后提供一个适当安全的密码。
  ```sh
  dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
  changetype: add
  objectclass: account
  objectclass: simplesecurityobject
  uid: gitea
  userPassword: secure password
  passwordExpirationTime: 20380119031407Z
  nsIdleTimeout: 0
  ```
 - 导入 LDIF 文件（如果需要，请将 localhost 更改为 IPA 服务器）。系统会提示您输入 Directory Manager 的密码。:
  ```sh
  ldapmodify -h localhost -p 389 -x -D \
  "cn=Directory Manager" -W -f gitea.ldif
  ```
 - 为`gitea_users`添加 IPA 组:
  ```sh
  ipa group-add --desc="Gitea Users" gitea_users
  ```
 - **提示**:对于 IPA 凭证错误，运行' kinit admin '并提供域管理帐户密码.
 - 以管理员身份登录 Gitea，点击 Admin Panel 下的`Authentication`。然后单击`Add New Source`并填写详细信息，更改所有适当的地方。
 ## SPNEGO with SSPI (Kerberos/NTLM, for Windows only)
 Gitea 支持通过 Windows 内置的安全支持提供程序接口（Security Support Provider Interface，SSPI）实现 SPNEGO 单点登录认证（由 RFC4559 定义的方案），用于服务器的 Web 部分。SSPI 仅在 Windows 环境中工作，即当服务器和客户端都在 Windows 操作系统上运行时。
 在激活 SSPI 单点登录认证（SSO）之前，您需要准备您的环境:
 - 在 Active Directory 中创建一个单独的用户账户，gitea.exe 进程将在该账户下运行（例如，在 domain.local 域下创建一个名为 user 的账户:
 - 为运行 gitea.exe 的主机创建一个服务主体名称（Service Principal Name，SPN），其类别为 HTTP:
  - 以特权域用户（例如域管理员）的身份启动“命令提示符”或“PowerShell”。
  - 运行下面的命令，将 host.domain.local 替换为 Web 应用程序将运行的服务器的完全限定域名（FQDN），将 domain\user 替换为在前一步中创建的账户名称:
  ```sh
  setspn -A HTTP/host.domain.local domain\user
  ```
 在遵循上述步骤之前，请确保您按照以下流程进行操作:
 1. 用之前创建的用户登录（如果已经登录，请先注销）。
 2. 确保在`custom/conf/app.ini`文件的`[server]`部分中，`ROOT_URL`设置为 Web 应用程序将运行的服务器的完全限定域名（FQDN），与之前创建服务主体名称时使用的一致（例如，`host.domain.local`）。
 3. 启动 Web 服务器（运行 `gitea.exe web`）。
 4. 在 `Site Administration -> Authentication Sources` 中添加一个 `SPNEGO with SSPI` 认证源，以启用 SSPI 认证。
 5. 在域中的客户端计算机上，使用任何域用户登录（与运行`gitea.exe`的服务器不同）。
 6. 如果您使用 Chrome 或 Edge 浏览器，请将 Web 应用程序的 URL 添加到“本地站点”（`Internet选项 -> 安全 -> 本地站点 -> 站点`）。
 7. 启动 Chrome 或 Edge 浏览器，导航到 Gitea 的 FQDN URL（例如，`http://host.domain.local:3000`）。
 8. 在控制面板中点击“Sign In”按钮，然后选择 SSPI，将会自动使用当前登录到计算机的用户进行登录。
 9. 如果无法正常工作，请确保:
   - 您不是在运行`gitea.exe`的同一台服务器上运行 Web 浏览器。应该在与服务器不同的域加入计算机（客户端）上运行 Web 浏览器。如果客户端和服务器都在同一台计算机上运行，则 NTLM 将优先于 Kerberos。
   - 主机上只有一个`HTTP/...`的 SPN。
   - SPN 中只包含主机名，不包含端口号。
   - 将 Web 应用程序的 URL 添加到"本地站点"。
   - 服务器和客户端的时钟差异不超过 5 分钟（取决于组策略）。
   - 在 Internet Explorer 中启用了"集成 Windows 身份验证"（在"高级设置"下）。
 遵循这些步骤，您应该能够成功启用和使用 SSPI 单点登录认证（SSO）。
 ## 反向代理认证
 Gitea 支持通过读取反向代理传递的 HTTP 头中的登录名或者 email 地址来支持反向代理来认证。默认是不启用的，你可以用以下配置启用。
 ```ini
 [service]
 ENABLE_REVERSE_PROXY_AUTHENTICATION = true
 ```
 默认的登录用户名的 HTTP 头是 `X-WEBAUTH-USER`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_USER` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。
 默认的登录用户 Email 的 HTTP 头是 `X-WEBAUTH-EMAIL`，你可以通过修改 `REVERSE_PROXY_AUTHENTICATION_EMAIL` 来变更它。如果用户不存在，可以自动创建用户，当然你需要修改 `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true` 来启用它。你也可以通过修改 `ENABLE_REVERSE_PROXY_EMAIL` 来启用或停用这个 HTTP 头。
 如果设置了 `ENABLE_REVERSE_PROXY_FULL_NAME=true`，则用户的全名会从 `X-WEBAUTH-FULLNAME` 读取，这样在自动创建用户时将使用这个字段作为用户全名，你也可以通过修改 `REVERSE_PROXY_AUTHENTICATION_FULL_NAME` 来变更 HTTP 头。
 你也可以通过修改 `REVERSE_PROXY_TRUSTED_PROXIES` 来设置反向代理的 IP 地址范围，加强安全性，默认值是 `127.0.0.0/8,::1/128`。 通过 `REVERSE_PROXY_LIMIT`， 可以设置最多信任几级反向代理。
 你可以通过以下配置为 API 启用此认证方法：
 ```ini
 [service]
 ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true
 ```
 :::note
 当此方法用于 API 时，反向代理负责处理 CSRF 保护。
 :::
@@ -1,146 +0,0 @@
 ---
 date: "2018-06-06T09:33:00+08:00"
 slug: "backup-and-restore"
 sidebar_position: 11
 aliases:
  - /zh-cn/backup-and-restore
 ---
 # 备份与恢复
 Gitea 已经实现了 `dump` 命令可以用来备份所有需要的文件到一个 zip 压缩文件。该压缩文件可以被用来进行数据恢复。
 ## 备份一致性
 为了确保 Gitea 实例的一致性，在备份期间必须关闭它。
 Gitea 包括数据库、文件和 Git 仓库，当它被使用时所有这些都会发生变化。例如，当迁移正在进行时，在数据库中创建一个事务，而 Git 仓库正在被复制。如果备份发生在迁移的中间，Git 仓库可能是不完整的，尽管数据库声称它是完整的，因为它是在之后被转储的。避免这种竞争条件的唯一方法是在备份期间停止 Gitea 实例。
 ## 备份命令 (`dump`)
 先转到 git 用户的权限: `su git`. 再 Gitea 目录运行 `./gitea dump`。一般会显示类似如下的输出：
 ```
 2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
 2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
 2016/12/27 22:32:22 Dumping database...
 2016/12/27 22:32:22 Packing dump files...
 2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
 2016/12/27 22:32:34 Finish dumping in file gitea-dump-1482906742.zip
 ```
 最后生成的 `gitea-dump-1482906742.zip` 文件将会包含如下内容：
 - `app.ini` - 如果原先存储在默认的 custom/ 目录之外，则是配置文件的可选副本
 - `custom/` - 所有保存在 `custom/` 目录下的配置和自定义的文件。
 - `data/` - 数据目录（APP_DATA_PATH），如果使用文件会话，则不包括会话。该目录包括 `attachments`、`avatars`、`lfs`、`indexers`、如果使用 SQLite 则包括 SQLite 文件。
 - `repos/` - 仓库目录的完整副本。
 - `gitea-db.sql` - 数据库 dump 出来的 SQL。
 - `log/` - Logs 文件，如果用作迁移不是必须的。
 中间备份文件将会在临时目录进行创建，如果您要重新指定临时目录，可以用 `--tempdir` 参数，或者用 `TMPDIR` 环境变量。
 ## 备份数据库
 `gitea dump` 创建的 SQL 转储使用 XORM，Gitea 管理员可能更喜欢使用本地的 MySQL 和 PostgreSQL 转储工具。使用 XORM 转储数据库时仍然存在一些问题，可能会导致在尝试恢复时出现问题。
 ```sh
 # mysql
 mysqldump -u$USER -p$PASS --databases $DATABASE > gitea-db.sql
 # postgres
 pg_dump -U $USER $DATABASE > gitea-db.sql
 ```
 ### 使用 Docker （`dump`）
 在使用 Docker 时，使用 `dump` 命令有一些注意事项。
 必须以 `gitea/conf/app.ini` 中指定的 `RUN_USER = <OS_USERNAME>` 执行该命令；并且，为了让备份文件夹的压缩过程能够顺利执行，`docker exec` 命令必须在 `--tempdir` 内部执行。
 示例：
 ```none
 docker exec -u <OS_USERNAME> -it -w <--tempdir> $(docker ps -qf 'name=^<NAME_OF_DOCKER_CONTAINER>$') bash -c '/usr/local/bin/gitea dump -c </path/to/app.ini>'
 ```
 \*注意：`--tempdir` 指的是 Gitea 使用的 Docker 环境的临时目录；如果您没有指定自定义的 `--tempdir`，那么 Gitea 将使用 `/tmp` 或 Docker 容器的 `TMPDIR` 环境变量。对于 `--tempdir`，请相应调整您的 `docker exec` 命令选项。
 结果应该是一个文件，存储在指定的 `--tempdir` 中，类似于：`gitea-dump-1482906742.zip`
 ## 恢复命令 (`restore`)
 当前还没有恢复命令，恢复需要人工进行。主要是把文件和数据库进行恢复。
 例如：
 ```sh
 unzip gitea-dump-1610949662.zip
 cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
 mv repos/* /var/lib/gitea/data/gitea-repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
 # mysql
 mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE <gitea-db.sql
 # sqlite3
 sqlite3 $DATABASE_PATH <gitea-db.sql
 # postgres
 psql -U $USER -d $DATABASE < gitea-db.sql
 service gitea restart
 ```
 如果安装方式发生了变化（例如 二进制 -> Docker），或者 Gitea 安装到了与之前安装不同的目录，则需要重新生成仓库 Git 钩子。
 在 Gitea 运行时，并从 Gitea 二进制文件所在的目录执行：`./gitea admin regenerate hooks`
 这样可以确保仓库 Git 钩子中的应用程序和配置文件路径与当前安装一致。如果这些路径没有更新，仓库的 `push` 操作将失败。
 ### 使用 Docker (`restore`)
 在基于 Docker 的 Gitea 实例中，也没有恢复命令的支持。恢复过程与前面描述的步骤相同，但路径不同。
 示例：
 ```sh
 # 在容器中打开 bash 会话
 docker exec --user git -it 2a83b293548e bash
 # 在容器内解压您的备份文件
 unzip gitea-dump-1610949662.zip
 cd gitea-dump-1610949662
 # 恢复 Gitea 数据
 mv data/* /data/gitea
 # 恢复仓库本身
 mv repos/* /data/git/repositories/
 # 调整文件权限
 chown -R git:git /data
 # 重新生成 Git 钩子
 /usr/local/bin/gitea -c '/data/gitea/conf/app.ini' admin regenerate hooks
 ```
 Gitea 容器中的默认用户是 `git`（1000:1000）。请用您的 Gitea 容器 ID 或名称替换 `2a83b293548e`。
 ### 使用 Docker-rootless (`restore`)
 在 Docker-rootless 容器中的恢复工作流程只是要使用的目录不同：
 ```sh
 # 在容器中打开 bash 会话
 docker exec --user git -it 2a83b293548e bash
 # 在容器内解压您的备份文件
 unzip gitea-dump-1610949662.zip
 cd gitea-dump-1610949662
 # 恢复 app.ini
 mv data/conf/app.ini /etc/gitea/app.ini
 # 恢复 Gitea 数据
 mv data/* /var/lib/gitea
 # 恢复仓库本身
 mv repos/* /var/lib/gitea/git/repositories
 # 调整文件权限
 chown -R git:git /etc/gitea/app.ini /var/lib/gitea
 # 重新生成 Git 钩子
 /usr/local/bin/gitea -c '/etc/gitea/app.ini' admin regenerate hooks
 ```
@@ -1,93 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "cmd-embedded"
 sidebar_position: 20
 aliases:
  - /zh-cn/cmd-embedded
 ---
 # 嵌入资源提取工具
 Gitea 的可执行文件包含了运行所需的所有资源：模板、图片、样式表和翻译文件。你可以通过在 `custom` 目录下的相应路径中放置替换文件来覆盖其中的任何资源（详见 [自定义 Gitea 配置](../administration/customizing-gitea.md)）。
 要获取嵌入资源的副本以进行编辑，可以使用 CLI 中的 `embedded` 命令，通过操作系统的 shell 执行。
 **注意：** 嵌入资源提取工具包含在 Gitea 1.12 及以上版本中。
 ## 资源列表
 要列出嵌入在 Gitea 可执行文件中的资源，请使用以下语法：
 ```sh
 gitea embedded list [--include-vendored] [patterns...]
 ```
 `--include-vendored` 标志使命令包括被供应的文件，这些文件通常被排除在外；即来自外部库的文件，这些文件是 Gitea 所需的（例如 [octicons](https://octicons.github.com/) 等）。
 可以提供一系列文件搜索模式。Gitea 使用 [gobwas/glob](https://github.com/gobwas/glob) 作为其 glob 语法。以下是一些示例：
 - 列出所有模板文件，无论在哪个虚拟目录下：`**.tmpl`
 - 列出所有邮件模板文件：`templates/mail/**.tmpl`
  列出 `public/assets/img` 目录下的所有文件：`public/assets/img/**`
 不要忘记为模式使用引号，因为空格、`*` 和其他字符可能对命令行解释器有特殊含义。
 如果未提供模式，则列出所有文件。
 ### 示例：列出所有嵌入文件
 列出所有路径中包含 `openid` 的嵌入文件：
 ```sh
 $ gitea embedded list '**openid**'
 public/assets/img/auth/openid_connect.svg
 public/assets/img/openid-16x16.png
 templates/user/auth/finalize_openid.tmpl
 templates/user/auth/signin_openid.tmpl
 templates/user/auth/signup_openid_connect.tmpl
 templates/user/auth/signup_openid_navbar.tmpl
 templates/user/auth/signup_openid_register.tmpl
 templates/user/settings/security_openid.tmpl
 ```
 ## 提取资源
 要提取嵌入在 Gitea 可执行文件中的资源，请使用以下语法：
 ```sh
 gitea [--config {file}] embedded extract [--destination {dir}|--custom] [--overwrite|--rename] [--include-vendored] {patterns...}
 ```
 `--config` 选项用于告知 Gitea `app.ini` 配置文件的位置（如果不在默认位置）。此选项仅在使用 `--custom` 标志时使用。
 `--destination` 选项用于指定提取文件的目标目录。默认为当前目录。
 `--custom` 标志告知 Gitea 直接将文件提取到 `custom` 目录中。为使其正常工作，该命令需要知道 `app.ini` 配置文件的位置（通过 `--config` 指定），并且根据配置的不同，需要从 Gitea 通常启动的目录运行。有关详细信息，请参阅 [自定义 Gitea 配置](../administration/customizing-gitea.md)。
 `--overwrite` 标志允许覆盖目标目录中的任何现有文件。
 `--rename` 标志告知 Gitea 将目标目录中的任何现有文件重命名为 `filename.bak`。之前的 `.bak` 文件将被覆盖。
 至少需要提供一个文件搜索模式；有关模式的语法和示例，请参阅上述 `list` 子命令。
 ### 重要提示
 请确保**只提取需要自定义的文件**。位于 `custom` 目录中的文件不会受到 Gitea 的升级过程的影响。当 Gitea 升级到新版本（通过替换可执行文件）时，许多嵌入文件将发生变化。Gitea 将尊重并使用在 `custom` 目录中找到的任何文件，即使这些文件是旧的和不兼容的。
 ### 示例：提取邮件模板
 将邮件模板提取到临时目录：
 ```sh
 $ mkdir tempdir
 $ gitea embedded extract --destination tempdir 'templates/mail/**.tmpl'
 Extracting to tempdir:
 tempdir/templates/mail/auth/activate.tmpl
 tempdir/templates/mail/auth/activate_email.tmpl
 tempdir/templates/mail/auth/register_notify.tmpl
 tempdir/templates/mail/auth/reset_passwd.tmpl
 tempdir/templates/mail/issue/assigned.tmpl
 tempdir/templates/mail/issue/default.tmpl
 tempdir/templates/mail/notify/collaborator.tmpl
 ```
@@ -1,534 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "command-line"
 sidebar_position: 1
 aliases:
  - /zh-cn/command-line
 ---
 # 命令行
 ## 用法
 `gitea [全局选项] 命令 [命令或全局选项] [参数...]`
 ## 全局选项
 所有全局选项均可被放置在命令级别。
 - `--help`，`-h`：显示帮助文本并退出。可选。
 - `--version`，`-v`：显示版本信息并退出。可选。 (示例：`Gitea version 1.1.0+218-g7b907ed built with: bindata, sqlite`)。
 - `--custom-path path`，`-C path`：Gitea 自定义文件夹的路径。可选。 (默认值：`AppWorkPath`/custom 或 `$GITEA_CUSTOM`)。
 - `--config path`，`-c path`：Gitea 配置文件的路径。可选。 (默认值：`custom`/conf/app.ini)。
 - `--work-path path`，`-w path`：Gitea 的 `AppWorkPath`。可选。 (默认值：LOCATION_OF_GITEA_BINARY 或 `$GITEA_WORK_DIR`)
 注意：默认的 custom-path、config 和 work-path 也可以在构建时更改（如果需要）。
 ## 命令
 ### web
 启动服务器：
 - 选项：
  - `--port number`，`-p number`：端口号。可选。 (默认值：3000)。覆盖配置文件中的设置。
  - `--install-port number`：运行安装页面的端口号。可选。 (默认值：3000)。覆盖配置文件中的设置。
  - `--pid path`，`-P path`：Pid 文件的路径。可选。
  - `--quiet`，`-q`：只在控制台上输出 Fatal 日志，用于在设置日志之前发出的日志。
  - `--verbose`：在控制台上输出跟踪日志，用于在设置日志之前发出的日志。
 - 示例：
  - `gitea web`
  - `gitea web --port 80`
  - `gitea web --config /etc/gitea.ini --pid /some/custom/gitea.pid`
 - 注意：
  - Gitea 不应以 root 用户身份运行。要绑定到低于 1024 的端口，您可以在 Linux 上使用 setcap 命令：`sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea`。每次更新 Gitea 都需要重新执行此操作。
 ### admin
 管理员操作：
 - 命令：
  - `user`：
    - `list`：
      - 选项：
        - `--admin`：仅列出管理员用户。可选。
      - 描述：列出所有现有用户。
      - 示例：
        - `gitea admin user list`
    - `delete`：
      - 选项：
        - `--email`：要删除的用户的电子邮件。
        - `--username`：要删除的用户的用户名。
        - `--id`：要删除的用户的 ID。
        - 必须提供 `--id`、`--username` 或 `--email` 中的一个。如果提供多个，则所有条件必须匹配。
      - 示例：
        - `gitea admin user delete --id 1`
    - `create`：
      - 选项：
        - `--name value`：用户名。必填。自 Gitea 1.9.0 版本起，请改用 `--username` 标志。
        - `--username value`：用户名。必填。Gitea 1.9.0 新增。
        - `--password value`：密码。必填。
        - `--email value`：邮箱。必填。
        - `--admin`：如果提供此选项，将创建一个管理员用户。可选。
        - `--access-token`：如果提供，将为用户创建访问令牌。可选。（默认值：false）。
        - `--must-change-password`：如果提供，创建的用户将在初始登录后需要选择一个新密码。可选。（默认值：true）。
        - `--random-password`：如果提供，将使用随机生成的密码作为创建用户的密码。`--password` 的值将被忽略。可选。
        - `--random-password-length`：如果提供，将用于配置随机生成密码的长度。可选。（默认值：12）
      - 示例：
        - `gitea admin user create --username myname --password asecurepassword --email [email protected]`
    - `change-password`：
      - 选项：
        - `--username value`，`-u value`：用户名。必填。
        - `--password value`，`-p value`：新密码。必填。
      - 示例：
        - `gitea admin user change-password --username myname --password asecurepassword`
    - `must-change-password`：
      - 参数：
        - `[username...]`：需要更改密码的用户
      - 选项：
        - `--all`，`-A`：强制所有用户更改密码
        - `--exclude username`，`-e username`：排除给定的用户。可以多次设置。
        - `--unset`：撤销对给定用户的强制密码更改
  - `regenerate`：
    - 选项：
      - `hooks`：重新生成所有仓库的 Git Hooks。
      - `keys`：重新生成 authorized_keys 文件。
    - 示例：
      - `gitea admin regenerate hooks`
      - `gitea admin regenerate keys`
  - `auth`：
    - `list`：
      - 描述：列出所有存在的外部认证源。
      - 示例：
        - `gitea admin auth list`
    - `delete`：
      - 选项：
        - `--id`：要删除的源的 ID。必填。
      - 示例：
        - `gitea admin auth delete --id 1`
    - `add-oauth`：
      - 选项：
        - `--name`：应用程序名称。
        - `--provider`：OAuth2 提供者。
        - `--key`：客户端 ID（Key）。
        - `--secret`：客户端密钥。
        - `--auto-discover-url`：OpenID Connect 自动发现 URL（仅在使用 OpenID Connect 作为提供程序时需要）。
        - `--use-custom-urls`：在 GitLab/GitHub OAuth 端点上使用自定义 URL。
        - `--custom-tenant-id`：在 OAuth 端点上使用自定义租户 ID。
        - `--custom-auth-url`：使用自定义授权 URL（GitLab/GitHub 的选项）。
        - `--custom-token-url`：使用自定义令牌 URL（GitLab/GitHub 的选项）。
        - `--custom-profile-url`：使用自定义配置文件 URL（GitLab/GitHub 的选项）。
        - `--custom-email-url`：使用自定义电子邮件 URL（GitHub 的选项）。
        - `--icon-url`：OAuth2 登录源的自定义图标 URL。
        - `--skip-local-2fa`：允许源覆盖本地 2FA。（可选）
        - `--scopes`：请求此 OAuth2 源的附加范围。（可选）
        - `--required-claim-name`：必须设置的声明名称，以允许用户使用此源登录。（可选）
        - `--required-claim-value`：必须设置的声明值，以允许用户使用此源登录。（可选）
        - `--group-claim-name`：提供此源的组名的声明名称。（可选）
        - `--admin-group`：管理员用户的组声明值。（可选）
        - `--restricted-group`：受限用户的组声明值。（可选）
        - `--group-team-map`：组与组织团队之间的 JSON 映射。（可选）
        - `--group-team-map-removal`：根据组自动激活团队成员资格的删除。（可选）
      - 示例：
        - `gitea admin auth add-oauth --name external-github --provider github --key OBTAIN_FROM_SOURCE --secret OBTAIN_FROM_SOURCE`
    - `update-oauth`：
      - 选项：
        - `--id`：要更新的源的 ID。必填。
        - `--name`：应用程序名称。
        - `--provider`：OAuth2 提供者。
        - `--key`：客户端 ID（Key）。
        - `--secret`：客户端密钥。
        - `--auto-discover-url`：OpenID Connect 自动发现 URL（仅在使用 OpenID Connect 作为提供程序时需要）。
        - `--use-custom-urls`：在 GitLab/GitHub OAuth 端点上使用自定义 URL。
        - `--custom-tenant-id`：在 OAuth 端点上使用自定义租户 ID。
        - `--custom-auth-url`：使用自定义授权 URL（GitLab/GitHub 的选项）。
        - `--custom-token-url`：使用自定义令牌 URL（GitLab/GitHub 的选项）。
        - `--custom-profile-url`：使用自定义配置文件 URL（GitLab/GitHub 的选项）。
        - `--custom-email-url`：使用自定义电子邮件 URL（GitHub 的选项）。
        - `--icon-url`：OAuth2 登录源的自定义图标 URL。
        - `--skip-local-2fa`：允许源覆盖本地 2FA。（可选）
        - `--scopes`：请求此 OAuth2 源的附加范围。
        - `--required-claim-name`：必须设置的声明名称，以允许用户使用此源登录。（可选）
        - `--required-claim-value`：必须设置的声明值，以允许用户使用此源登录。（可选）
        - `--group-claim-name`：提供此源的组名的声明名称。（可选）
        - `--admin-group`：管理员用户的组声明值。（可选）
        - `--restricted-group`：受限用户的组声明值。（可选）
      - 示例：
        - `gitea admin auth update-oauth --id 1 --name external-github-updated`
    - `add-smtp`：
      - 选项：
        - `--name`：应用程序名称。必填。
        - `--auth-type`：SMTP 认证类型（PLAIN/LOGIN/CRAM-MD5）。默认为 PLAIN。
        - `--host`：SMTP 主机。必填。
        - `--port`：SMTP 端口。必填。
        - `--force-smtps`：SMTPS 始终在端口 465 上使用。设置此选项以强制在其他端口上使用 SMTPS。
        - `--skip-verify`：跳过 TLS 验证。
        - `--helo-hostname`：发送 HELO 时使用的主机名。留空以发送当前主机名。
        - `--disable-helo`：禁用 SMTP helo。
        - `--allowed-domains`：留空以允许所有域。使用逗号（','）分隔多个域。
        - `--skip-local-2fa`：跳过 2FA 登录。
        - `--active`：启用此认证源。
          备注：
          `--force-smtps`、`--skip-verify`、`--disable-helo`、`--skip-local-2fs` 和 `--active` 选项可以采用以下形式使用：
        - `--option`、`--option=true` 以启用选项
        - `--option=false` 以禁用选项
          如果未指定这些选项，则在 `update-smtp` 中不会更改值，或者在 `add-smtp` 中将使用默认的 `false` 值。
      - 示例：
        - `gitea admin auth add-smtp --name ldap --host smtp.mydomain.org --port 587 --skip-verify --active`
    - `update-smtp`：
      - 选项：
        - `--id`：要更新的源的 ID。必填。
        - 其他选项与 `add-smtp` 共享
      - 示例：
        - `gitea admin auth update-smtp --id 1 --host smtp.mydomain.org --port 587 --skip-verify=false`
        - `gitea admin auth update-smtp --id 1 --active=false`
    - `add-ldap`：添加新的 LDAP（通过 Bind DN）认证源
      - 选项：
        - `--name value`：认证名称。必填。
        - `--not-active`：停用认证源。
        - `--security-protocol value`：安全协议名称。必填。
        - `--skip-tls-verify`：禁用 TLS 验证。
        - `--host value`：LDAP 服务器的地址。必填。
        - `--port value`：连接到 LDAP 服务器时使用的端口。必填。
        - `--user-search-base value`：用户帐户将在其中搜索的 LDAP 基础路径。必填。
        - `--user-filter value`：声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。必填。
        - `--admin-filter value`：指定是否应授予用户管理员特权的 LDAP 过滤器。
        - `--restricted-filter value`：指定是否应将用户设置为受限状态的 LDAP 过滤器。
        - `--username-attribute value`：用户 LDAP 记录中包含用户名的属性。
        - `--firstname-attribute value`：用户 LDAP 记录中包含用户名字的属性。
        - `--surname-attribute value`：用户 LDAP 记录中包含用户姓氏的属性。
        - `--email-attribute value`：用户 LDAP 记录中包含用户电子邮件地址的属性。必填。
        - `--public-ssh-key-attribute value`：用户 LDAP 记录中包含用户公共 SSH 密钥的属性。
        - `--avatar-attribute value`：用户 LDAP 记录中包含用户头像的属性。
        - `--bind-dn value`：在搜索用户时绑定到 LDAP 服务器的 DN。
        - `--bind-password value`：绑定 DN 的密码（如果有）。
        - `--attributes-in-bind`：在绑定 DN 上下文中获取属性。
        - `--synchronize-users`：启用用户同步。
        - `--page-size value`：搜索页面大小。
      - 示例：
        - `gitea admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))" --email-attribute mail`
    - `update-ldap`：更新现有的 LDAP（通过 Bind DN）认证源
      - 选项：
        - `--id value`：认证源的 ID。必填。
        - `--name value`：认证名称。
        - `--not-active`：停用认证源。
        - `--security-protocol value`：安全协议名称。
        - `--skip-tls-verify`：禁用 TLS 验证。
        - `--host value`：LDAP 服务器的地址。
        - `--port value`：连接到 LDAP 服务器时使用的端口。
        - `--user-search-base value`：用户帐户将在其中搜索的 LDAP 基础路径。
        - `--user-filter value`：声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。
        - `--admin-filter value`：指定是否应授予用户管理员特权的 LDAP 过滤器。
        - `--restricted-filter value`：指定是否应将用户设置为受限状态的 LDAP 过滤器。
        - `--username-attribute value`：用户 LDAP 记录中包含用户名的属性。
        - `--firstname-attribute value`：用户 LDAP 记录中包含用户名字的属性。
        - `--surname-attribute value`：用户 LDAP 记录中包含用户姓氏的属性。
        - `--email-attribute value`：用户 LDAP 记录中包含用户电子邮件地址的属性。
        - `--public-ssh-key-attribute value`：用户 LDAP 记录中包含用户公共 SSH 密钥的属性。
        - `--avatar-attribute value`：用户 LDAP 记录中包含用户头像的属性。
        - `--bind-dn value`：在搜索用户时绑定到 LDAP 服务器的 DN。
        - `--bind-password value`：绑定 DN 的密码（如果有）。
        - `--attributes-in-bind`：在绑定 DN 上下文中获取属性。
        - `--synchronize-users`：启用用户同步。
        - `--page-size value`：搜索页面大小。
      - 示例：
        - `gitea admin auth update-ldap --id 1 --name "my ldap auth source"`
        - `gitea admin auth update-ldap --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
    - `add-ldap-simple`：添加新的 LDAP（简单身份验证）认证源
      - 选项：
        - `--name value`：认证名称。必填。
        - `--not-active`：停用认证源。
        - `--security-protocol value`：安全协议名称。必填。
        - `--skip-tls-verify`：禁用 TLS 验证。
        - `--host value`：LDAP 服务器的地址。必填。
        - `--port value`：连接到 LDAP 服务器时使用的端口。必填。
        - `--user-search-base value`：用户帐户将在其中搜索的 LDAP 基础路径。
        - `--user-filter value`：声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。必填。
        - `--admin-filter value`：指定是否应授予用户管理员特权的 LDAP 过滤器。
        - `--restricted-filter value`：指定是否应将用户设置为受限状态的 LDAP 过滤器。
        - `--username-attribute value`：用户 LDAP 记录中包含用户名的属性。
        - `--firstname-attribute value`：用户 LDAP 记录中包含用户名字的属性。
        - `--surname-attribute value`：用户 LDAP 记录中包含用户姓氏的属性。
        - `--email-attribute value`：用户 LDAP 记录中包含用户电子邮件地址的属性。必填。
        - `--public-ssh-key-attribute value`：用户 LDAP 记录中包含用户公共 SSH 密钥的属性。
        - `--avatar-attribute value`：用户 LDAP 记录中包含用户头像的属性。
        - `--user-dn value`：用户的 DN。必填。
      - 示例：
        - `gitea admin auth add-ldap-simple --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-dn "cn=%s,ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(cn=%s))" --email-attribute mail`
    - `update-ldap-simple`：更新现有的 LDAP（简单身份验证）认证源
      - 选项：
        - `--id value`：认证源的 ID。必填。
        - `--name value`：认证名称。
        - `--not-active`：停用认证源。
        - `--security-protocol value`：安全协议名称。
        - `--skip-tls-verify`：禁用 TLS 验证。
        - `--host value`：LDAP 服务器的地址。
        - `--port value`：连接到 LDAP 服务器时使用的端口。
        - `--user-search-base value`：用户帐户将在其中搜索的 LDAP 基础路径。
        - `--user-filter value`：声明如何查找试图进行身份验证的用户记录的 LDAP 过滤器。
        - `--admin-filter value`：指定是否应授予用户管理员特权的 LDAP 过滤器。
        - `--restricted-filter value`：指定是否应将用户设置为受限状态的 LDAP 过滤器。
        - `--username-attribute value`：用户 LDAP 记录中包含用户名的属性。
        - `--firstname-attribute value`：用户 LDAP 记录中包含用户名字的属性。
        - `--surname-attribute value`：用户 LDAP 记录中包含用户姓氏的属性。
        - `--email-attribute value`：用户 LDAP 记录中包含用户电子邮件地址的属性。
        - `--public-ssh-key-attribute value`：用户 LDAP 记录中包含用户公共 SSH 密钥的属性。
        - `--avatar-attribute value`：用户 LDAP 记录中包含用户头像的属性。
        - `--user-dn value`：用户的 DN。
      - 示例：
        - `gitea admin auth update-ldap-simple --id 1 --name "my ldap auth source"`
        - `gitea admin auth update-ldap-simple --id 1 --username-attribute uid --firstname-attribute givenName --surname-attribute sn`
 ### cert
 生成自签名的 SSL 证书。将输出到当前目录下的`cert.pem`和`key.pem`文件中，并且会覆盖任何现有文件。
 - 选项：
  - `--host value`：逗号分隔的主机名和 IP 地址列表，此证书适用于这些主机。支持使用通配符。必填。
  - `--ecdsa-curve value`：用于生成密钥的 ECDSA 曲线。可选。有效选项为 P224、P256、P384、P521。
  - `--rsa-bits value`：要生成的 RSA 密钥的大小。可选。如果设置了--ecdsa-curve，则忽略此选项。（默认值：3072）。
  - `--start-date value`：证书的创建日期。可选。（格式：`Jan 1 15:04:05 2011`）。
  - `--duration value`：证书有效期。可选。（默认值：8760h0m0s）
  - `--ca`：如果提供此选项，则证书将生成自己的证书颁发机构。可选。
 - 示例：
  - `gitea cert --host git.example.com,example.com,www.example.com --ca`
 ### dump
 将所有文件和数据库导出到一个 zip 文件中。输出文件将保存在当前目录下，类似于`gitea-dump-1482906742.zip`。
 - 选项：
  - `--file name`，`-f name`：指定要创建的导出文件的名称。可选。（默认值：gitea-dump-[timestamp].zip）。
  - `--tempdir path`，`-t path`：指定临时目录的路径。可选。（默认值：/tmp）。
  - `--skip-repository`，`-R`：跳过仓库的导出。可选。
  - `--skip-custom-dir`：跳过自定义目录的导出。可选。
  - `--skip-lfs-data`：跳过 LFS 数据的导出。可选。
  - `--skip-attachment-data`：跳过附件数据的导出。可选。
  - `--skip-package-data`：跳过包数据的导出。可选。
  - `--skip-log`：跳过日志数据的导出。可选。
  - `--database`，`-d`：指定数据库的 SQL 语法。可选。
  - `--verbose`，`-V`：如果提供此选项，显示附加详细信息。可选。
  - `--type`：设置导出的格式。可选。（默认值：zip）
 - 示例：
  - `gitea dump`
  - `gitea dump --verbose`
 ### generate
 用于在配置文件中生成随机值和令牌。对于自动部署时生成值非常有用。
 - 命令:
  - `secret`:
    - 选项:
      - `INTERNAL_TOKEN`: 用于内部 API 调用身份验证的令牌。
      - `JWT_SECRET`: 用于 LFS 和 OAUTH2 JWT 身份验证的密钥（LFS_JWT_SECRET 是此选项的别名，用于向后兼容）。
      - `SECRET_KEY`: 全局密钥。
    - 示例:
      - `gitea generate secret INTERNAL_TOKEN`
      - `gitea generate secret JWT_SECRET`
      - `gitea generate secret SECRET_KEY`
 ### keys
 提供一个 SSHD AuthorizedKeysCommand。需要在 sshd 配置文件中进行配置:
 ```ini
 ...
 # -e 的值和 AuthorizedKeysCommandUser 应与运行 Gitea 的用户名匹配
 AuthorizedKeysCommandUser git
 AuthorizedKeysCommand /path/to/gitea keys -e git -u %u -t %t -k %k
 ```
 该命令将返回适用于提供的密钥的合适 authorized_keys 行。您还应在 `app.ini` 的 `[server]` 部分设置值 `SSH_CREATE_AUTHORIZED_KEYS_FILE=false`。
 注意: opensshd 要求 Gitea 程序由 root 拥有，并且不可由组或其他人写入。程序必须使用绝对路径指定。
 注意: Gitea 必须在运行此命令时处于运行状态才能成功。
 ### migrate
 迁移数据库。该命令可用于在首次启动服务器之前运行其他命令。此命令是幂等的。
 ### doctor check
 对 Gitea 实例进行诊断，可以修复一些可修复的问题。
 默认只运行部分检查，额外的检查可以参考：
 - `gitea doctor check --list` - 列出所有可用的检查
 - `gitea doctor check --all` - 运行所有可用的检查
 - `gitea doctor check --default` - 运行默认的检查
 - `gitea doctor check --run [check(s),]...` - 运行指定的名字的检查
 有些问题可以通过设置 `--fix` 选项进行自动修复。
 额外的日志可以通过 `--log-file=...` 进行设置。
 #### doctor recreate-table
 有时，在迁移时，旧的列和默认值可能会在数据库模式中保持不变。这可能会导致警告，如下所示:
 ```
 2020/08/02 11:32:29 ...rm/session_schema.go:360:Sync() [W] Table user Column keep_activity_private db default is , struct default is 0
 ```
 您可以通过以下方式让 Gitea 重新创建这些表，并将旧数据复制到新表中，并适当设置默认值：
 ```
 gitea doctor recreate-table user
 ```
 您可以使用以下方式让 Gitea 重新创建多个表：
 ```
 gitea doctor recreate-table table1 table2 ...
 ```
 如果您希望 Gitea 重新创建所有表，请直接调用：
 ```
 gitea doctor recreate-table
 ```
 强烈建议在运行这些命令之前备份您的数据库。
 ### doctor convert
 将现有的 MySQL 数据库从 utf8 转换为 utf8mb4，或者把 MSSQL 数据库从 varchar 转换为 nvarchar。
 ### manager
 管理运行中的服务器操作：
 - 命令:
  - `shutdown`: 优雅地关闭运行中的进程
  - `restart`: 优雅地重新启动运行中的进程（对于 Windows 服务器尚未实现）
  - `flush-queues`: 刷新运行中的进程中的队列
    - 选项:
      - `--timeout value`: 刷新过程的超时时间（默认值: 1m0s）
      - `--non-blocking`: 设置为 true，以在返回之前不等待刷新完成
  - `logging`: 调整日志命令
    - 命令:
      - `pause`: 暂停日志记录
        - 注意:
          - 如果日志级别低于此级别，日志级别将被临时提升为 INFO。
          - Gitea 将在一定程度上缓冲日志，并在超过该点后丢弃日志。
      - `resume`: 恢复日志记录
      - `release-and-reopen`: 使 Gitea 释放和重新打开用于日志记录的文件和连接（相当于向 Gitea 发送 SIGUSR1 信号）。
      - `remove name`: 删除指定的日志记录器
        - 选项:
          - `--group group`, `-g group`: 从中删除子记录器的组（默认为`default`）
      - `add`: 添加日志记录器
        - 命令:
          - `console`: 添加控制台日志记录器
            - 选项:
              - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default"
              - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式
              - `--level value`, `-l value`: 新日志记录器的日志级别
              - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别
              - `--flags value`, `-F value`: 日志记录器的标志
              - `--expression value`, `-e value`: 日志记录器的匹配表达式
              - `--prefix value`, `-p value`: 日志记录器的前缀
              - `--color`: 在日志中使用颜色
              - `--stderr`: 将控制台日志输出到 stderr - 仅适用于控制台
          - `file`: 添加文件日志记录器
            - 选项:
              - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default"
              - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式
              - `--level value`, `-l value`: 新日志记录器的日志级别
              - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别
              - `--flags value`, `-F value`: 日志记录器的标志
              - `--expression value`, `-e value`: 日志记录器的匹配表达式
              - `--prefix value`, `-p value`: 日志记录器的前缀
              - `--color`: 在日志中使用颜色
              - `--filename value`, `-f value`: 日志记录器的文件名
              - `--rotate`, `-r`: 轮转日志
              - `--max-size value`, `-s value`: 在轮转之前的最大大小（以字节为单位）
              - `--daily`, `-d`: 每天轮转日志
              - `--max-days value`, `-D value`: 保留的每日日志的最大数量
              - `--compress`, `-z`: 压缩轮转的日志
              - `--compression-level value`, `-Z value`: 使用的压缩级别
          - `conn`: 添加网络连接日志记录器
            - 选项:
              - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default"
              - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式
              - `--level value`, `-l value`: 新日志记录器的日志级别
              - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别
              - `--flags value`, `-F value`: 日志记录器的标志
              - `--expression value`, `-e value`: 日志记录器的匹配表达式
              - `--prefix value`, `-p value`: 日志记录器的前缀
              - `--color`: 在日志中使用颜色
              - `--reconnect-on-message`, `-R`: 对于每个消息重新连接主机
              - `--reconnect`, `-r`: 连接中断时重新连接主机
              - `--protocol value`, `-P value`: 设置要使用的协议：tcp、unix 或 udp（默认为 tcp）
              - `--address value`, `-a value`: 要连接到的主机地址和端口（默认为:7020）
          - `smtp`: 添加 SMTP 日志记录器
            - 选项:
              - `--group value`, `-g value`: 要添加日志记录器的组 - 默认为"default"
              - `--name value`, `-n value`: 新日志记录器的名称 - 默认为模式
              - `--level value`, `-l value`: 新日志记录器的日志级别
              - `--stacktrace-level value`, `-L value`: 堆栈跟踪日志级别
              - `--flags value`, `-F value`: 日志记录器的标志
              - `--expression value`, `-e value`: 日志记录器的匹配表达式
              - `--prefix value`, `-p value`: 日志记录器的前缀
              - `--color`: 在日志中使用颜色
              - `--username value`, `-u value`: 邮件服务器用户名
              - `--password value`, `-P value`: 邮件服务器密码
              - `--host value`, `-H value`: 邮件服务器主机（默认为: 127.0.0.1:25）
              - `--send-to value`, `-s value`: 要发送到的电子邮件地址
              - `--subject value`, `-S value`: 发送电子邮件的主题标题
  - `processes`: 显示 Gitea 进程和 Goroutine 信息
    - 选项:
      - `--flat`: 以平面表格形式显示进程，而不是树形结构
      - `--no-system`: 不显示系统进程
      - `--stacktraces`: 显示与进程关联的 Goroutine 的堆栈跟踪
      - `--json`: 输出为 JSON 格式
      - `--cancel PID`: 向具有 PID 的进程发送取消命令（仅适用于非系统进程）
 ### dump-repo
 `dump-repo` 从 Git/GitHub/Gitea/GitLab 中转储存储库数据：
 - 选项：
  - `--git_service service`：Git 服务，可以是 `git`、`github`、`gitea`、`gitlab`。如果 `clone_addr` 可以被识别，则可以忽略此选项。
  - `--repo_dir dir`，`-r dir`：存储数据的存储库目录路径。
  - `--clone_addr addr`：将被克隆的 URL，目前可以是 git/github/gitea/gitlab 的 http/https URL。例如：https://github.com/lunny/tango.git
  - `--auth_username lunny`：访问 `clone_addr` 的用户名。
  - `--auth_password <password>`：访问 `clone_addr` 的密码。
  - `--auth_token <token>`：访问 `clone_addr` 的个人令牌。
  - `--owner_name lunny`：如果非空，数据将存储在具有所有者名称的目录中。
  - `--repo_name tango`：如果非空，数据将存储在具有存储库名称的目录中。
  - `--units <units>`：要迁移的项目，一个或多个项目应以逗号分隔。允许的项目有 wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments。如果为空，则表示所有项目。
 ### restore-repo
 `restore-repo` 从磁盘目录中还原存储库数据：
 - 选项：
  - `--repo_dir dir`，`-r dir`：还原数据的存储库目录路径。
  - `--owner_name lunny`：还原目标所有者名称。
  - `--repo_name tango`：还原目标存储库名称。
  - `--units <units>`：要还原的项目，一个或多个项目应以逗号分隔。允许的项目有 wiki, issues, labels, releases, release_assets, milestones, pull_requests, comments。如果为空，则表示所有项目。
 ### actions generate-runner-token
 生成一个供 Runner 使用的新令牌，用于向服务器注册。
 - 选项：
  - `--scope {owner}[/{repo}]`，`-s {owner}[/{repo}]`：限制 Runner 的范围，没有范围表示该 Runner 可用于所有仓库，但你也可以将其限制为特定的仓库或所有者。
 要注册全局 Runner：
 ```
 gitea actions generate-runner-token
 ```
 要注册特定组织的 Runner，例如 `org`：
 ```
 gitea actions generate-runner-token -s org
 ```
 要注册特定仓库的 Runner，例如 `username/test-repo`：
 ```
 gitea actions generate-runner-token -s username/test-repo
 ```
@@ -1,547 +0,0 @@
 ---
 date: "2017-04-15T14:56:00+02:00"
 slug: "customizing-gitea"
 sidebar_position: 100
 aliases:
  - /zh-cn/customizing-gitea
 ---
 # 自定义 Gitea
 自定义 Gitea 通常通过 `CustomPath` 目录完成。默认情况下，它是工作目录（WorkPath）下的
 `custom` 目录，但如果您的[安装方式](../installation/from-binary.md)做了不同设置，也可能位于其他位置。
 这是覆盖配置项、模板等内容的核心位置。您可以通过 `gitea help` 查看 `CustomPath`，也可以在
 _站点管理_ 页面的 _Configuration_ 选项卡中找到该路径。您还可以通过设置 `GITEA_CUSTOM`
 环境变量，或在 `gitea` 二进制上使用 `--custom-path` 选项来覆盖 `CustomPath`。
 （命令行选项会覆盖环境变量。）
 如果 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)
 如果在检查 `gitea help` 后仍找不到 `CustomPath` 目录，请检查 `GITEA_CUSTOM` 环境变量；
 它可以用来将默认路径覆盖为其他位置。例如，`GITEA_CUSTOM` 可能由 init 脚本设置。
 您也可以在站点管理页面的 “Configuration” 选项卡下检查该值是否已设置。
 - [环境变量清单](../administration/environment-variables.md)
 :::note
 Gitea 必须执行完整重启后，配置更改才会生效。
 :::
 ## 提供自定义公共文件
 要让 Gitea 提供自定义公共文件（例如页面和图片），请将 `$GITEA_CUSTOM/public/`
 目录作为 webroot。Gitea 会跟随符号链接。
 当前仅提供以下文件：
 - `public/robots.txt`
 - `public/.well-known/` 目录中的文件
 - `public/assets/` 目录中的文件
 例如，存放在 `$GITEA_CUSTOM/public/assets/` 中的 `image.png` 文件，可以通过
 `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` 中：
 - `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 的浏览器回退图标
 如果源图片不是矢量格式，您可以尝试使用诸如[这个工具](https://www.aconvert.com/image/png-to-svg/)
 将光栅图像转换为矢量图。
 ## 自定义 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 以应用更改。
 ### 添加链接和页签
 如果您只是想为顶部导航栏或页脚添加额外链接，或者为仓库视图添加额外页签，
 可以将它们分别放入 `$GITEA_CUSTOM/templates/custom/` 目录中的
 `extra_links.tmpl`（添加到导航栏的链接）、`extra_links_footer.tmpl`
 （添加到页脚左侧的链接）和 `extra_tabs.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`，并且您可以使用 `{{AppSubUrl}}` 获取基础 URL：
 `<a class="item" href="{{AppSubUrl}}/assets/impressum.html">Impressum</a>`
 更多信息请参见[添加法律页面](../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` 之外，您还可以在
 `$GITEA_CUSTOM/templates/custom/` 目录中放置其他有用的模板：
 - `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 的合适位置。
 ### 使用 Gitea 变量
 您可以在自定义模板中使用各种 Gitea 变量。
 首先，_临时_ 启用开发模式：在 `app.ini` 中将 `RUN_MODE = prod` 改为 `RUN_MODE = dev`。
 然后在任意模板中添加 `{{ $ | DumpVar }}`，重启 Gitea 并刷新对应页面；
 这样会输出所有可用变量。
 找到所需数据后，使用对应变量即可；例如，如果您需要仓库名称，可以使用 `{{.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/` 目录。然后将以下内容添加到 `$GITEA_CUSTOM/templates/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;
 }
 ```
@@ -1,77 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "email-setup"
 sidebar_position: 12
 aliases:
  - /zh-cn/email-setup
 ---
 # Email 设置
 Gitea 具有邮件功能，用于发送事务性邮件（例如注册确认邮件）。它可以配置为使用 Sendmail（或兼容的 MTA，例如 Postfix 和 msmtp）或直接使用 SMTP 服务器。
 ## 使用 Sendmail
 使用 `sendmail` 命令作为邮件传输代理（mailer）。
 注意：对于在官方 Gitea Docker 镜像中使用，请使用 SMTP 版本进行配置（请参考下一节）。
 注意：对于面向互联网的网站，请查阅您的 MTA 文档以了解通过 TLS 发送邮件的说明。同时设置 SPF、DMARC 和 DKIM DNS 记录，以使发送的邮件被各个电子邮件提供商接受为合法邮件。
 ```ini title="app.ini"
 [mailer]
 ENABLED       = true
 FROM          = gitea@mydomain.com
 PROTOCOL   = sendmail
 SENDMAIL_PATH = /usr/sbin/sendmail
 SENDMAIL_ARGS = "--" ; 大多数 "sendmail" 程序都接受选项，使用 "--" 将防止电子邮件地址被解释为选项。
 ```
 ## 使用 SMTP
 直接使用 SMTP 服务器作为中继。如果您不想在实例上设置 MTA，但在电子邮件提供商那里有一个帐户，这个选项非常有用。
 ```ini title="app.ini"
 [mailer]
 ENABLED        = true
 FROM           = gitea@mydomain.com
 PROTOCOL    = smtps
 SMTP_ADDR      = mail.mydomain.com
 SMTP_PORT      = 587
 USER           = gitea@mydomain.com
 PASSWD         = `password`
 ```
 重启 Gitea 以使配置更改生效。
 要发送测试邮件以验证设置，请转到 Gitea > 站点管理 > 配置 > SMTP 邮件配置。
 有关所有选项的完整列表，请查看[配置速查表](../administration/config-cheat-sheet.md)。
 请注意：只有在使用 TLS 或 `HOST=localhost` 加密 SMTP 服务器通信时才支持身份验证。TLS 加密可以通过以下方式进行：
 - 通过端口 587 的 STARTTLS（也称为 Opportunistic TLS）。初始连接是明文的，但如果服务器支持，则可以升级为 TLS。
 - 通过默认端口 465 的 SMTPS 连接。连接到服务器从一开始就使用 TLS。
 - 使用 `PROTOCOL=smtps` 进行强制的 SMTPS 连接。（这两种方式都被称为 Implicit TLS）
  这是由于 Go 内部库对 STRIPTLS 攻击的保护机制。
 请注意，自 2018 年起，[RFC8314](https://tools.ietf.org/html/rfc8314#section-3) 推荐使用 Implicit TLS。
 ### Gmail
 以下配置应该适用于 Gmail 的 SMTP 服务器：
 ```ini title="app.ini"
 [mailer]
 ENABLED        = true
 HOST           = smtp.gmail.com:465 ; 对于 Gitea >= 1.18.0，删除此行
 SMTP_ADDR      = smtp.gmail.com
 SMTP_PORT      = 465
 FROM           = example.user@gmail.com
 USER           = example.user
 PASSWD         = `***`
 PROTOCOL    = smtps
 ```
 请注意，您需要创建并使用一个 [应用密码](https://support.google.com/accounts/answer/185833?hl=en) 并在您的 Google 帐户上启用 2FA。您将无法直接使用您的 Google 帐户密码。
@@ -1,49 +0,0 @@
 ---
 date: "2017-04-08T11:34:00+02:00"
 slug: "environment-variables"
 sidebar_position: 10
 aliases:
  - /zh-cn/environment-variables
 ---
 # 环境变量清单
 这里是用来控制 Gitea 行为表现的的环境变量清单，您需要在执行如下 Gitea 启动命令前设置它们来确保配置生效：
 ```
 GITEA_CUSTOM=/home/gitea/custom ./gitea web
 ```
 ## Go 的配置
 因为 Gitea 使用 Go 语言编写，因此它使用了一些相关的 Go 的配置参数：
 - `GOOS`
 - `GOARCH`
 - [`GOPATH`](https://go.dev/cmd/go/#hdr-GOPATH_environment_variable)
 您可以在[官方文档](https://go.dev/cmd/go/#hdr-Environment_variables)中查阅这些配置参数的详细信息。
 ## Gitea 的文件目录
 - `GITEA_WORK_DIR`：工作目录的绝对路径
 - `GITEA_CUSTOM`：默认情况下 Gitea 使用默认目录 `GITEA_WORK_DIR`/custom，您可以使用这个参数来配置 _custom_ 目录
 - `GOGS_WORK_DIR`： 已废弃，请使用 `GITEA_WORK_DIR` 替代
 - `GOGS_CUSTOM`： 已废弃，请使用 `GITEA_CUSTOM` 替代
 ## 操作系统配置
 - `USER`：Gitea 运行时使用的系统用户，它将作为一些 repository 的访问地址的一部分
 - `USERNAME`： 如果没有配置 `USER`， Gitea 将使用 `USERNAME`
 - `HOME`： 用户的 home 目录，在 Windows 中会使用 `USERPROFILE` 环境变量
 ### 仅限于 Windows 的配置
 - `USERPROFILE`： 用户的主目录，如果未配置则会使用 `HOMEDRIVE` + `HOMEPATH`
 - `HOMEDRIVE`: 用于访问 home 目录的主驱动器路径（C 盘）
 - `HOMEPATH`：在指定主驱动器下的 home 目录相对路径
 ## Miscellaneous
 - `SKIP_MINWINSVC`：如果设置为 1，在 Windows 上不会以 service 的形式运行。
@@ -1,194 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "external-renderers"
 sidebar_position: 60
 aliases:
  - /zh-cn/external-renderers
 ---
 # 外部渲染器
 Gitea 通过外部二进制文件支持自定义文件渲染（例如 Jupyter notebooks、asciidoc 等），只需要进行以下步骤：
 - 安装外部二进制文件
 - 在您的 `app.ini` 文件中添加一些配置
 - 重新启动 Gitea 实例
 此功能支持整个文件的渲染。如果您想要在 Markdown 中渲染代码块，您需要使用 JavaScript 进行一些操作。请参阅 [自定义 Gitea 配置](../administration/customizing-gitea.md) 页面上的一些示例。
 ## 安装外部二进制文件
 为了通过外部二进制文件进行文件渲染，必须安装它们的关联软件包。
 如果您正在使用 Docker 镜像，则您的 `Dockerfile` 应该包含以下内容：
 ```docker
 FROM docker.gitea.com/gitea:@dockerVersion@
 [...]
 COPY custom/app.ini /data/gitea/conf/app.ini
 [...]
 RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng libffi-dev pandoc python3-dev py3-pyzmq pipx
 # 安装其他您需要的外部渲染器的软件包
 RUN pipx install jupyter docutils --include-deps
 # 在上面添加您需要安装的任何其他 Python 软件包
 ```
 ## `app.ini` 文件配置
 在您的自定义 `app.ini` 文件中为每个外部渲染器添加一个 `[markup.XXXXX]` 部分：
 ```ini
 [markup.asciidoc]
 ENABLED = true
 FILE_EXTENSIONS = .adoc,.asciidoc
 RENDER_COMMAND = "asciidoctor -s -a showtitle --out-file=- -"
 ; 输入不是标准输入而是文件
 IS_INPUT_FILE = false
 [markup.jupyter]
 ENABLED = true
 FILE_EXTENSIONS = .ipynb
 RENDER_COMMAND = "jupyter nbconvert --stdin --stdout --to html --template basic"
 IS_INPUT_FILE = false
 [markup.restructuredtext]
 ENABLED = true
 FILE_EXTENSIONS = .rst
 RENDER_COMMAND = "timeout 30s pandoc +RTS -M512M -RTS -f rst"
 IS_INPUT_FILE = false
 ```
 如果您的外部标记语言依赖于在生成的 HTML 元素上的额外类和属性，您可能需要启用自定义的清理策略。Gitea 使用 [`bluemonday`](https://godoc.org/github.com/microcosm-cc/bluemonday) 包作为我们的 HTML 清理器。下面的示例可以用于支持从 [`pandoc`](https://pandoc.org/) 输出的服务器端 [KaTeX](https://katex.org/) 渲染结果。
 ```ini
 [markup.sanitizer.TeX]
 ; Pandoc 渲染 TeX 段落为带有 "math" 类的 <span> 元素，根据上下文可能还带有 "inline" 或 "display" 类。
 ; - 请注意，这与我们的 Markdown 解析器中内置的数学支持不同，后者使用 <code> 元素。
 ELEMENT = span
 ALLOW_ATTR = class
 REGEXP = ^\s*((math(\s+|$)|inline(\s+|$)|display(\s+|$)))+
 [markup.markdown]
 ENABLED         = true
 FILE_EXTENSIONS = .md,.markdown
 RENDER_COMMAND  = pandoc -f markdown -t html --katex
 ```
 您必须在每个部分中定义 `ELEMENT` 和 `ALLOW_ATTR`。
 要定义多个条目，请添加唯一的字母数字后缀（例如，`[markup.sanitizer.1]` 和 `[markup.sanitizer.something]`）。
 要仅为特定的外部渲染器应用清理规则，它们必须使用渲染器名称，例如 `[markup.sanitizer.asciidoc.rule-1]`、`[markup.sanitizer.<renderer>.rule-1]`。
 **注意**：如果规则在渲染器 ini 部分之前定义，或者名称与渲染器不匹配，它将应用于所有渲染器。
 完成配置更改后，请重新启动 Gitea 以使更改生效。
 **注意**：在 Gitea 1.12 之前，存在一个名为 `markup.sanitiser` 的单个部分，其中的键被重新定义为多个规则，但是，这种配置方法存在重大问题，需要通过多个部分进行配置。
 ### 示例：HTML
 直接渲染 HTML 文件：
 ```ini
 [markup.html]
 ENABLED         = true
 FILE_EXTENSIONS = .html,.htm
 RENDER_COMMAND  = cat
 ; 输入不是标准输入，而是文件
 IS_INPUT_FILE   = true
 [markup.sanitizer.html.1]
 ELEMENT = div
 ALLOW_ATTR = class
 [markup.sanitizer.html.2]
 ELEMENT = a
 ALLOW_ATTR = class
 ```
 请注意：此示例中的配置将允许渲染 HTML 文件，并使用 `cat` 命令将文件内容输出为 HTML。此外，配置中的两个清理规则将允许 `<div>` 和 `<a>` 元素使用 `class` 属性。
 在进行配置更改后，请重新启动 Gitea 以使更改生效。
 ### 示例：Office DOCX
 使用 [`pandoc`](https://pandoc.org/) 显示 Office DOCX 文件：
 ```ini
 [markup.docx]
 ENABLED = true
 FILE_EXTENSIONS = .docx
 RENDER_COMMAND = "pandoc --from docx --to html --self-contained --template /path/to/basic.html"
 [markup.sanitizer.docx.img]
 ALLOW_DATA_URI_IMAGES = true
 ```
 在此示例中，配置将允许显示 Office DOCX 文件，并使用 `pandoc` 命令将文件转换为 HTML 格式。同时，清理规则中的 `ALLOW_DATA_URI_IMAGES` 设置为 `true`，允许使用 Data URI 格式的图片。
 模板文件的内容如下：
 ```
 $body$
 ```
 ### 示例：Jupyter Notebook
 使用 [`nbconvert`](https://github.com/jupyter/nbconvert) 显示 Jupyter Notebook 文件：
 ```ini
 [markup.jupyter]
 ENABLED = true
 FILE_EXTENSIONS = .ipynb
 RENDER_COMMAND = "jupyter-nbconvert --stdin --stdout --to html --template basic"
 [markup.sanitizer.jupyter.img]
 ALLOW_DATA_URI_IMAGES = true
 ```
 在此示例中，配置将允许显示 Jupyter Notebook 文件，并使用 `nbconvert` 命令将文件转换为 HTML 格式。同样，清理规则中的 `ALLOW_DATA_URI_IMAGES` 设置为 `true`，允许使用 Data URI 格式的图片。
 在进行配置更改后，请重新启动 Gitea 以使更改生效。
 ## 自定义 CSS
 在 `.ini` 文件中，可以使用 `[markup.XXXXX]` 的格式指定外部渲染器，并且由外部渲染器生成的 HTML 将被包装在一个带有 `markup` 和 `XXXXX` 类的 `<div>` 中。`markup` 类提供了预定义的样式（如果 `XXXXX` 是 `markdown`，则使用 `markdown` 类）。否则，您可以使用这些类来针对渲染的 HTML 内容进行定制样式。
 因此，您可以编写一些 CSS 样式：
 ```css
 .markup.XXXXX html {
  font-size: 100%;
  overflow-y: scroll;
  -webkit-text-size-adjust: 100%;
  -ms-text-size-adjust: 100%;
 }
 .markup.XXXXX body {
  color: #444;
  font-family: Georgia, Palatino, "Palatino Linotype", Times, "Times New Roman",
    serif;
  font-size: 12px;
  line-height: 1.7;
  padding: 1em;
  margin: auto;
  max-width: 42em;
  background: #fefefe;
 }
 .markup.XXXXX p {
  color: orangered;
 }
 ```
 将您的样式表添加到自定义目录中，例如 `custom/public/assets/css/my-style-XXXXX.css`，并使用自定义的头文件 `custom/templates/custom/header.tmpl` 进行导入：
 ```html
 <link rel="stylesheet" href="{{AppSubUrl}}/assets/css/my-style-XXXXX.css" />
 ```
 通过以上步骤，您可以将自定义的 CSS 样式应用到特定的外部渲染器，使其具有所需的样式效果。
@@ -1,86 +0,0 @@
 ---
 date: "2022-08-01T00:00:00+00:00"
 slug: "fail2ban-setup"
 sidebar_position: 16
 aliases:
  - /zh-cn/fail2ban-setup
 ---
 # 设置 Fail2ban
 **Fail2ban 检查客户端登录日志，将多次登录失败的客户端识别为攻击者并在一段时间内阻止其访问服务。如果你的实例是公开的，这一点尤其重要。请管理员仔细设置 fail2ban，错误的配置将导致防火墙阻止你访问自己的服务器。**
 Gitea 会在日志文件 `log/gitea.log` 中记录登录失败的 CLI、SSH 或 HTTP 客户端 IP 地址，而你需要将 Gitea 的日志输出模式从默认的 `console` 更改为 `file`。这表示将日志输出到文件，使得 fail2ban 可以定期扫描日志内容。
 当用户的身份验证失败时，日志中会记录此类信息：
 ```log
 2018/04/26 18:15:54 [I] Failed authentication attempt for user from xxx.xxx.xxx.xxx
 ```
 ```log
 2020/10/15 16:08:44 [E] invalid credentials from xxx.xxx.xxx.xxx
 ```
 ## 配置规则
 添加日志过滤器规则到配置文件 `/etc/fail2ban/filter.d/gitea.conf`:
 ```ini
 [Definition]
 failregex =  .*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
 ignoreregex =
 ```
 添加监狱规则到配置文件 `/etc/fail2ban/jail.d/gitea.conf`:
 ```ini
 [gitea]
 enabled = true
 filter = gitea
 logpath = /var/lib/gitea/log/gitea.log
 maxretry = 10
 findtime = 3600
 bantime = 900
 action = iptables-allports
 ```
 如果你的 Gitea 实例运行在 Docker 容器中，并且直接将容器端口暴露到外部网络，
 你还需要添加 `chain="FORWARD"` 到监狱规则配置文件 `/etc/fail2ban/jail.d/gitea-docker.conf`
 以适应 Docker 的网络转发规则。但如果你在容器的宿主机上使用 Nginx 反向代理连接到 Gitea 则无需这样配置。
 ```ini
 [gitea-docker]
 enabled = true
 filter = gitea
 logpath = /var/lib/gitea/log/gitea.log
 maxretry = 10
 findtime = 3600
 bantime = 900
 action = iptables-allports[chain="FORWARD"]
 ```
 最后，运行 `systemctl restart fail2ban` 即可应用更改。现在，你可以使用 `systemctl status fail2ban` 检查 fail2ban 运行状态。
 上述规则规定客户端在 1 小时内，如果登录失败的次数达到 10 次，则通过 iptables 锁定该客户端 IP 地址 15 分钟。
 ## 设置反向代理
 如果你使用 Nginx 反向代理到 Gitea 实例，你还需要设置 Nginx 的 HTTP 头部值 `X-Real-IP` 将真实的客户端 IP 地址传递给 Gitea。否则 Gitea 程序会将客户端地址错误解析为反向代理服务器的地址，例如回环地址 `127.0.0.1`。
 ```
 proxy_set_header X-Real-IP $remote_addr;
 ```
 额外注意，在 Gitea 的配置文件 `app.ini` 中存在下列默认值：
 ```
 REVERSE_PROXY_LIMIT = 1
 REVERSE_PROXY_TRUSTED_PROXIES = 127.0.0.0/8,::1/128
 ```
 `REVERSE_PROXY_LIMIT` 限制反向代理服务器的层数，设置为 `0` 表示不使用这些标头。
 `REVERSE_PROXY_TRUSTED_PROXIES` 表示受信任的反向代理服务器网络地址，
 经过该网络地址转发来的流量会经过解析 `X-Real-IP` 头部得到真实客户端地址。
 （参考 [configuration cheat sheet](../administration/config-cheat-sheet.md#安全性)）
@@ -1,24 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "git-lfs-setup"
 sidebar_position: 12
 aliases:
  - /zh-cn/git-lfs-setup
 ---
 # Git LFS 设置
 要使用 Gitea 内置的 LFS 支持，您需要更新 `app.ini` 文件：
 ```ini
 [server]
 ; 启用 git-lfs 支持。true 或 false，默认为 false。
 LFS_START_SERVER = true
 [lfs]
 ; 存放 LFS 文件的路径，默认为 data/lfs。
 PATH = /home/gitea/data/lfs
 ```
 **注意**：LFS 服务器支持需要服务器上安装 Git v2.1.2 以上版本。
@@ -1,89 +0,0 @@
 ---
 date: "2023-04-09T11:00:00+02:00"
 slug: "https-setup"
 sidebar_position: 12
 ---
 # HTTPS配置
 ## 使用内置服务器
 在启用HTTPS之前，确保您拥有有效的SSL/TLS证书。
 建议在测试和评估情况下使用自签名证书，请运行 `gitea cert --host [HOST]` 以生成自签名证书
 如果您在服务器上使用阿帕奇（Apache）或Nginx，建议参考 [反向代理指南](reverse-proxies.md)。
 要使用Gitea内置HTTPS支持，您必须编辑`app.ini`文件。
 ```ini
 [server]
 PROTOCOL  = https
 ROOT_URL  = https://git.example.com:3000/
 HTTP_PORT = 3000
 CERT_FILE = cert.pem
 KEY_FILE  = key.pem
 ```
 请注意，如果您的证书由第三方证书颁发机构签名（即不是自签名的），则 cert.pem 应包含证书链。服务器证书必须是 cert.pem 中的第一个条目，后跟中介（如果有）。不必包含根证书，因为连接客户端必须已经拥有根证书才能建立信任关系。要了解有关配置值的更多信息，请查看 [配置备忘单](../administration/config-cheat-sheet#server-server)。
 对于“CERT_FILE”或“KEY_FILE”字段，当文件路径是相对路径时，文件路径相对于“GITEA_CUSTOM”环境变量。它也可以是绝对路径。
 ### 设置HTTP重定向
 Gitea服务器仅支持监听一个端口；要重定向HTTP请求致HTTPS端口，您需要启用HTTP重定向服务：
 ```ini
 [server]
 REDIRECT_OTHER_PORT = true
 ; Port the redirection service should listen on
 PORT_TO_REDIRECT = 3080
 ```
 如果您使用Docker，确保端口已配置在 `docker-compose.yml` 文件
 ## 使用 ACME (默认: Let's Encrypt)
 [ACME](https://tools.ietf.org/html/rfc8555) 是一种证书颁发机构标准协议，允许您自动请求和续订 SSL/TLS 证书。[Let`s Encrypt](https://letsencrypt.org/) 是使用此标准的免费公开信任的证书颁发机构服务器。仅实施“HTTP-01”和“TLS-ALPN-01”挑战。为了使 ACME 质询通过并验证您的域所有权，“80”端口（“HTTP-01”）或“443”端口（“TLS-ALPN-01”）上 gitea 域的外部流量必须由 gitea 实例提供服务。可能需要设置 [HTTP 重定向](#设置http重定向) 和端口转发才能正确路由外部流量。否则，到端口“80”的正常流量将自动重定向到 HTTPS。**您必须同意**ACME提供商的服务条款（默认为Let's Encrypt的 [服务条款](https://letsencrypt.org/documents/LE-SA-v1.2-2017年11月15日.pdf)。
 使用默认 Let's Encrypt 的最小配置如下：
 ```ini
 [server]
 PROTOCOL=https
 DOMAIN=git.example.com
 ENABLE_ACME=true
 ACME_ACCEPTTOS=true
 ACME_DIRECTORY=https
 ;; Email can be omitted here and provided manually at first run, after which it is cached
 ACME_EMAIL=email@example.com
 ```
 小型配置请使用 [smallstep CA](https://github.com/smallstep/certificates), 点击 [教程](https://smallstep.com/docs/tutorials/acme-challenge) 了解更多信息。
 ```ini
 [server]
 PROTOCOL=https
 DOMAIN=git.example.com
 ENABLE_ACME=true
 ACME_ACCEPTTOS=true
 ACME_URL=https://ca.example.com/acme/acme/directory
 ;; Can be omitted if using the system's trust is preferred
 ;ACME_CA_ROOT=/path/to/root_ca.crt
 ACME_DIRECTORY=https
 ACME_EMAIL=email@example.com
 ```
 要了解关于配置, 请访问 [配置备忘单](../administration/config-cheat-sheet.md#server-server)获取更多信息
 ## 使用反向代理服务器
 按照 [reverse proxy guide](reverse-proxies.md) 的规则设置你的反向代理服务器
 然后，按照下面的向导启用 HTTPS：
 - [nginx](https://nginx.org/en/docs/http/configuring_https_servers.html)
 - [apache2/httpd](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html)
 - [caddy](https://caddyserver.com/docs/tls)
 注意：仅在代理层启用 HTTPS 被称为 [TLS 终止代理](https://en.wikipedia.org/wiki/TLS_termination_proxy)。代理服务器接受传入的 TLS 连接，解密内容，然后将现在未加密的内容传递给 Gitea。只要代理和 Gitea 实例在同一台计算机上或在私有网络中的不同计算机上（代理暴露给外部网络），这通常是可以接受的。如果您的 Gitea 实例与代理隔离在公共网络上，或者如果您想要全端到端的加密，您还可以直接在 Gitea 中 [启用内置服务器的 HTTPS 支持](#使用内置服务器)，并将连接转发到 HTTPS 上。
@@ -1,263 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "logging-config"
 sidebar_position: 40
 aliases:
  - /zh-cn/logging-configuration
 ---
 # 日志配置
 Gitea 的日志配置主要由以下三种类型的组件组成：
 - `[log]` 部分用于一般配置
 - `[log.<mode-name>]` 部分用于配置不同的日志输出方式，也称为 "writer mode"，模式名称同时也作为 "writer name"
 - `[log]` 部分还可以包含遵循 `logger.<logger-name>.<CONFIG-KEY>` 模式的子日志记录器的配置
 默认情况下，已经有一个完全功能的日志输出，因此不需要重新定义。
 ## 收集日志以获取帮助
 要收集日志以获取帮助和报告问题，请参阅 [需要帮助](help/support.md)。
 ## `[log]` 部分
 在 Gitea 中，日志设施的配置在 `[log]` 部分及其子部分。
 在顶层的 `[log]` 部分，可以放置以下配置项：
 - `ROOT_PATH`：（默认值：**%(GITEA_WORK_DIR)/log**）：日志文件的基本路径。
 - `MODE`：（默认值：**console**）：要用于默认日志记录器的日志输出列表。
 - `LEVEL`：（默认值：**Info**）：要持久化的最严重的日志事件，不区分大小写。可能的值为：`Trace`、`Debug`、`Info`、`Warn`、`Error`、`Fatal`。
 - `STACKTRACE_LEVEL`：（默认值：**None**）：对于此类及更严重的事件，将在记录时打印堆栈跟踪。
 它还可以包含以下子日志记录器：
 - `logger.router.MODE`：（默认值：**,**）：用于路由器日志记录器的日志输出列表。
 - `logger.access.MODE`：（默认值：**_empty_**）：用于访问日志记录器的日志输出列表。默认情况下，访问日志记录器被禁用。
 - `logger.xorm.MODE`：（默认值：**,**）：用于 XORM 日志记录器的日志输出列表。
 将子日志记录器的模式设置为逗号（`,`）表示使用默认的全局 `MODE`。
 ## 快速示例
 ### 默认（空）配置
 空配置等同于默认配置：
 ```ini
 [log]
 ROOT_PATH = %(GITEA_WORK_DIR)/log
 MODE = console
 LEVEL = Info
 STACKTRACE_LEVEL = None
 logger.router.MODE = ,
 logger.xorm.MODE = ,
 logger.access.MODE =
 ; 这是“控制台”模式的配置选项（由上面的 MODE=console 使用）
 [log.console]
 MODE = console
 FLAGS = stdflags
 PREFIX =
 COLORIZE = true
 ```
 这等同于将所有日志发送到控制台，并将默认的 Golang 日志也发送到控制台日志中。
 这只是一个示例，默认情况下不需要将其写入配置文件中。
 ### 禁用路由日志并将一些访问日志记录到文件中
 禁用路由日志，将访问日志（>=Warn）记录到 `access.log` 中：
 ```ini
 [log]
 logger.router.MODE =
 logger.access.MODE = access-file
 [log.access-file]
 MODE = file
 LEVEL = Warn
 FILE_NAME = access.log
 ```
 ### 为不同的模式设置不同的日志级别
 将默认日志（>=Warn）记录到 `gitea.log` 中，将错误日志记录到 `file-error.log` 中：
 ```ini
 [log]
 LEVEL = Warn
 MODE = file, file-error
 ; 默认情况下，"file" 模式会将日志记录到 %(log.ROOT_PATH)/gitea.log，因此我们不需要设置它
 ; [log.file]
 [log.file-error]
 LEVEL = Error
 FILE_NAME = file-error.log
 ```
 ## 日志输出（模式和写入器）
 Gitea 提供以下日志写入器：
 - `console` - 输出日志到 `stdout`（或 `stderr`，如果已在配置中设置）
 - `file` - 输出日志到文件
 - `conn` - 输出日志到套接字（网络或 Unix 套接字）
 ### 公共配置
 某些配置适用于所有日志输出模式：
 - `MODE` 是日志输出写入器的模式。它将默认为 ini 部分的模式名称。因此，`[log.console]` 将默认为 `MODE = console`。
 - `LEVEL` 是此输出将记录的最低日志级别。
 - `STACKTRACE_LEVEL` 是此输出将打印堆栈跟踪的最低日志级别。
 - `COLORIZE` 对于 `console`，默认为 `true`，否则默认为 `false`。
 #### `EXPRESSION`
 `EXPRESSION` 表示日志事件必须匹配才能被输出写入器记录的正则表达式。
 日志消息（去除颜色）或 `longfilename:linenumber:functionname` 必须匹配其中之一。
 注意：整个消息或字符串不需要完全匹配。
 请注意，此表达式将在写入器的 goroutine 中运行，而不是在日志事件的 goroutine 中运行。
 #### `FLAGS`
 `FLAGS` 表示在每条消息之前打印的前置日志上下文信息。
 它是一个逗号分隔的字符串集。值的顺序无关紧要。
 默认值为 `stdflags`（= `date,time,medfile,shortfuncname,levelinitial`）。
 可能的值为：
 - `none` 或 `,` - 无标志。
 - `date` - 当地时区的日期：`2009/01/23`。
 - `time` - 当地时区的时间：`01:23:23`。
 - `microseconds` - 微秒精度：`01:23:23.123123`。假定有时间。
 - `longfile` - 完整的文件名和行号：`/a/b/c/d.go:23`。
 - `shortfile` - 文件名的最后一个部分和行号：`d.go:23`。
 - `funcname` - 调用者的函数名：`runtime.Caller()`。
 - `shortfuncname` - 函数名的最后一部分。覆盖 `funcname`。
 - `utc` - 如果设置了日期或时间，则使用 UTC 而不是本地时区。
 - `levelinitial` - 提供的级别的初始字符，放在方括号内，例如 `[I]` 表示 info。
 - `level` - 在方括号内的级别，例如 `[INFO]`。
 - `gopid` - 上下文的 Goroutine-PID。
 - `medfile` - 文件名的最后 20 个字符 - 相当于 `shortfile,longfile`。
 - `stdflags` - 相当于 `date,time,medfile,shortfuncname,levelinitial`。
 ### Console 模式
 在此模式下，日志记录器将将日志消息转发到 Gitea 进程附加的 stdout 和 stderr 流。
 对于 console 模式的日志记录器，如果不在 Windows 上，或者 Windows 终端可以设置为 ANSI 模式，或者是 cygwin 或 Msys 管道，则 `COLORIZE` 默认为 `true`。
 设置：
 - `STDERR`：**false**：日志记录器是否应将日志打印到 `stderr` 而不是 `stdout`。
 ### File 模式
 在此模式下，日志记录器将将日志消息保存到文件中。
 设置：
 - `FILE_NAME`：要将日志事件写入的文件，相对于 `ROOT_PATH`，默认为 `%(ROOT_PATH)/gitea.log`。异常情况：访问日志默认为 `%(ROOT_PATH)/access.log`。
 - `MAX_SIZE_SHIFT`：**28**：单个文件的最大大小位移。28 表示 256Mb。详细信息见下文。
 - `LOG_ROTATE` **true**：是否轮转日志文件。
 - `DAILY_ROTATE`：**true**：是否每天旋转日志。
 - `MAX_DAYS`：**7**：在此天数之后删除旋转的日志文件。
 - `COMPRESS`：**true**：默认情况下是否使用 gzip 压缩旧的日志文件。
 - `COMPRESSION_LEVEL`：**-1**：压缩级别。详细信息见下文。
 `MAX_SIZE_SHIFT` 通过将给定次数左移 1 (`1 << x`) 来定义文件的最大大小。
 在 v1.17.3 版本时的确切行为可以在[这里](https://github.com/go-gitea/gitea/blob/v1.17.3/modules/setting/log.go#L185)中查看。
 `COMPRESSION_LEVEL` 的有用值范围从 1 到（包括）9，其中较高的数字表示更好的压缩。
 请注意，更好的压缩可能会带来更高的资源使用。
 必须在前面加上 `-` 符号。
 ### Conn 模式
 在此模式下，日志记录器将通过网络套接字发送日志消息。
 设置：
 - `ADDR`：**:7020**：设置要连接的地址。
 - `PROTOCOL`：**tcp**：设置协议，可以是 "tcp"、"unix" 或 "udp"。
 - `RECONNECT`：**false**：在连接丢失时尝试重新连接。
 - `RECONNECT_ON_MSG`：**false**：为每条消息重新连接主机。
 ### "Router" 日志记录器
 当 Gitea 的路由处理程序工作时，Router 日志记录器记录以下消息类型：
 - `started` 消息将以 TRACE 级别记录
 - `polling`/`completed` 路由将以 INFO 级别记录。异常情况："/assets" 静态资源请求也会以 TRACE 级别记录。
 - `slow` 路由将以 WARN 级别记录
 - `failed` 路由将以 WARN 级别记录
 ### "XORM" 日志记录器
 为了使 XORM 输出 SQL 日志，还应将 `[database]` 部分中的 `LOG_SQL` 设置为 `true`。
 ### "Access" 日志记录器
 "Access" 日志记录器是自 Gitea 1.9 版本以来的新日志记录器。它提供了符合 NCSA Common Log 标准的日志格式。虽然它具有高度可配置性，但在更改其模板时应谨慎。此日志记录器的主要好处是，Gitea 现在可以使用标准日志格式记录访问日志，因此可以使用标准工具进行分析。
 您可以通过使用 `logger.access.MODE = ...` 来启用此日志记录器。
 如果需要，可以通过更改 `ACCESS_LOG_TEMPLATE` 的值来更改 "Access" 日志记录器的格式。
 请注意，访问日志记录器将以 `INFO` 级别记录，将此日志记录器的 `LEVEL` 设置为 `WARN` 或更高级别将导致不记录访问日志。
 #### ACCESS_LOG_TEMPLATE
 此值表示一个 Go 模板。其默认值为
 ```tmpl
 {{.Ctx.RemoteHost}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}" "{{.Ctx.Req.UserAgent}}"`
 ```
 模板接收以下选项：
 - `Ctx` 是 `context.Context`
 - `Identity` 是 `SignedUserName`，如果用户未登录，则为 "-"
 - `Start` 是请求的开始时间
 - `ResponseWriter` 是 `http.ResponseWriter`
 更改此模板时必须小心，因为它在标准的 panic 恢复陷阱之外运行。此模板应该尽可能简单，因为它会为每个请求运行一次。
 ## 释放和重新打开、暂停和恢复日志记录
 如果您在 Unix 上运行，您可能希望释放和重新打开日志以使用 `logrotate` 或其他工具。
 可以通过向运行中的进程发送 `SIGUSR1` 信号或运行 `gitea manager logging release-and-reopen` 命令来强制 Gitea 释放并重新打开其日志文件和连接。
 或者，您可能希望暂停和恢复日志记录 - 可以通过使用 `gitea manager logging pause` 和 `gitea manager logging resume` 命令来实现。请注意，当日志记录暂停时，低于 INFO 级别的日志事件将不会存储，并且只会存储有限数量的事件。在暂停时，日志记录可能会阻塞，尽管是暂时性的，但会大大减慢 Gitea 的运行速度，因此建议仅暂停很短的时间。
 ### 在 Gitea 运行时添加和删除日志记录
 可以使用 `gitea manager logging add` 和 `remove` 子命令在 Gitea 运行时添加和删除日志记录。
 此功能只能调整正在运行的日志系统，不能用于启动未初始化的访问或路由日志记录器。如果您希望启动这些系统，建议调整 app.ini 并（优雅地）重新启动 Gitea 服务。
 这些命令的主要目的是在运行中的系统上轻松添加临时日志记录器，以便调查问题，因为重新启动可能会导致问题消失。
 ## 使用 `logrotate` 而不是内置的日志轮转
 Gitea 包含内置的日志轮转功能，对于大多数部署来说应该已经足够了。但是，如果您想使用 `logrotate` 工具：
 - 在 `app.ini` 中将 `LOG_ROTATE` 设置为 `false`，禁用内置的日志轮转。
 - 安装 `logrotate`。
 - 根据部署要求配置 `logrotate`，有关配置语法细节，请参阅 `man 8 logrotate`。
  在 `postrotate/endscript` 块中通过 `kill -USR1` 或 `kill -10` 向 `gitea` 进程本身发送 `USR1` 信号，
  或者运行 `gitea manager logging release-and-reopen`（使用适当的环境设置）。
  确保配置适用于由 Gitea 日志记录器生成的所有文件，如上述部分所述。
 - 始终使用 `logrotate /etc/logrotate.conf --debug` 来测试您的配置。
 - 如果您正在使用 Docker 并从容器外部运行，您可以使用
  `docker exec -u $OS_USER $CONTAINER_NAME sh -c 'gitea manager logging release-and-reopen'`
  或 `docker exec $CONTAINER_NAME sh -c '/bin/s6-svc -1 /etc/s6/gitea/'`，或直接向 Gitea 进程本身发送 `USR1` 信号。
 下一个 `logrotate` 作业将包括您的配置，因此不需要重新启动。
 您还可以立即使用 `logrotate /etc/logrotate.conf --force` 重新加载 `logrotate`。
@@ -1,254 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "mail-templates"
 sidebar_position: 45
 aliases:
  - /zh-cn/mail-templates
 ---
 # 邮件模板
 为了定制特定操作的电子邮件主题和内容，可以使用模板来自定义 Gitea。这些功能的模板位于 [`custom` 目录](../administration/customizing-gitea.md) 下。
 如果没有自定义的替代方案，Gitea 将使用内部模板作为默认模板。
 自定义模板在 Gitea 启动时加载。对它们的更改在 Gitea 重新启动之前不会被识别。
 ## 支持模板的邮件通知
 目前，以下通知事件使用模板：
 | 操作名称   | 用途                                                                   |
 | ---------- | ---------------------------------------------------------------------- |
 | `new`      | 创建了新的工单或合并请求。                                             |
 | `comment`  | 在现有工单或合并请求中创建了新的评论。                                 |
 | `close`    | 关闭了工单或合并请求。                                                 |
 | `reopen`   | 重新打开了工单或合并请求。                                             |
 | `review`   | 在合并请求中进行审查的首要评论。                                       |
 | `approve`  | 对合并请求进行批准的首要评论。                                         |
 | `reject`   | 对合并请求提出更改请求的审查的首要评论。                               |
 | `code`     | 关于合并请求的代码的单个评论。                                         |
 | `assigned` | 用户被分配到工单或合并请求。                                           |
 | `default`  | 未包括在上述类别中的任何操作，或者当对应类别的模板不存在时使用的模板。 |
 特定消息类型的模板路径为：
 ```sh
 custom/templates/mail/{操作类型}/{操作名称}.tmpl
 ```
 其中 `{操作类型}` 是 `issue` 或 `pull`（针对合并请求），`{操作名称}` 是上述列出的操作名称之一。
 例如，有关合并请求中的评论的电子邮件的特定模板是：
 ```sh
 custom/templates/mail/pull/comment.tmpl
 ```
 然而，并不需要为每个操作类型/名称组合创建模板。
 使用回退系统来选择适当的模板。在此列表中，将使用 _第一个存在的_ 模板：
 - 所需**操作类型**和**操作名称**的特定模板。
 - 操作类型为 `issue` 和所需**操作名称**的模板。
 - 所需**操作类型**和操作名称为 `default` 的模板。
 - 操作类型为` issue` 和操作名称为 `default` 的模板。
 唯一必需的模板是操作类型为 `issue` 操作名称为 `default` 的模板，除非用户在 `custom` 目录中覆盖了它。
 ## 模板语法
 邮件模板是 UTF-8 编码的文本文件，需要遵循以下格式之一：
 ```
 用于主题行的文本和宏
 ------------
 用于邮件正文的文本和宏
 ```
 或者
 ```
 用于邮件正文的文本和宏
 ```
 指定 _主题_ 部分是可选的（因此也是虚线分隔符）。在使用时，_主题_ 和 _邮件正文_ 模板之间的分隔符需要至少三个虚线；分隔符行中不允许使用其他字符。
 _主题_ 和 _邮件正文_ 由 [Golang 的模板引擎](https://go.dev/pkg/text/template/) 解析，并提供了为每个通知组装的 _元数据上下文_。上下文包含以下元素：
 | 名称               | 类型             | 可用性         | 用途                                                                                                                                                                    |
 | ------------------ | ---------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `.FallbackSubject` | string           | 始终可用       | 默认主题行。参见下文。                                                                                                                                                  |
 | `.Subject`         | string           | 仅在正文中可用 | 解析后的 _主题_。                                                                                                                                                       |
 | `.Body`            | string           | 始终可用       | 工单、合并请求或评论的消息，从 Markdown 解析为 HTML 并进行了清理。请勿与 _邮件正文_ 混淆。                                                                              |
 | `.Link`            | string           | 始终可用       | 源工单、合并请求或评论的地址。                                                                                                                                          |
 | `.Issue`           | models.Issue     | 始终可用       | 产生通知的工单（或合并请求）。要获取特定于合并请求的数据（例如 `HasMerged`），可以使用 `.Issue.PullRequest`，但需要注意，如果工单 _不是_ 合并请求，则该字段将为 `nil`。 |
 | `.Comment`         | models.Comment   | 如果适用       | 如果通知是针对添加到工单或合并请求的评论，则其中包含有关评论的信息。                                                                                                    |
 | `.IsPull`          | bool             | 始终可用       | 如果邮件通知与合并请求关联（即 `.Issue.PullRequest` 不为 `nil` ），则为 `true`。                                                                                        |
 | `.Repo`            | string           | 始终可用       | 仓库的名称，包括所有者名称（例如 `mike/stuff`）                                                                                                                         |
 | `.User`            | models.User      | 始终可用       | 事件来源仓库的所有者。要获取用户名（例如 `mike`），可以使用 `.User.Name`。                                                                                              |
 | `.Doer`            | models.User      | 始终可用       | 执行触发通知事件的操作的用户。要获取用户名（例如 `rhonda`），可以使用 `.Doer.Name`。                                                                                    |
 | `.IsMention`       | bool             | 始终可用       | 如果此通知仅是因为在评论中提到了用户而生成的，并且收件人未订阅源，则为 `true`。如果收件人已订阅工单或仓库，则为 `false`。                                               |
 | `.SubjectPrefix`   | string           | 始终可用       | 如果通知是关于除工单或合并请求创建之外的其他内容，则为 `Re：`；否则为空字符串。                                                                                         |
 | `.ActionType`      | string           | 始终可用       | `"issue"` 或 `"pull"`。它将与实际的 _操作类型_ 对应，与选择的模板无关。                                                                                                 |
 | `.ActionName`      | string           | 始终可用       | 它将是上述操作类型之一（`new` ，`comment` 等），并与选择的模板对应。                                                                                                    |
 | `.ReviewComments`  | []models.Comment | 始终可用       | 审查中的代码评论列表。评论文本将在 `.RenderedContent` 中，引用的代码将在 `.Patch` 中。                                                                                  |
 所有名称区分大小写。
 ### 模板中的主题部分
 用于邮件主题的模板引擎是 Golang 的 [`text/template`](https://go.dev/pkg/text/template/)。
 有关语法的详细信息，请参阅链接的文档。
 主题构建的步骤如下：
 - 根据通知类型和可用的模板选择一个模板。
 - 解析并解析模板（例如，将 `{{.Issue.Index}}` 转换为工单或合并请求的编号）。
 - 将所有空格字符（例如 `TAB`，`LF` 等）转换为普通空格。
 - 删除所有前导、尾随和多余的空格。
 - 将字符串截断为前 256 个字母（字符）。
 如果最终结果为空字符串，**或者**没有可用的主题模板（即所选模板不包含主题部分），将使用 Gitea 的**内部默认值**。
 内部默认（回退）主题相当于：
 ```
 {{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#{{.Issue.Index}})
 ```
 例如：`Re: [mike/stuff] New color palette (#38)`
 即使存在有效的主题模板，Gitea 的默认主题也可以在模板的元数据中作为 `.FallbackSubject` 找到。
 ### 模板中的邮件正文部分
 用于邮件正文的模板引擎是 Golang 的 [`html/template`](https://go.dev/pkg/html/template/)。
 有关语法的详细信息，请参阅链接的文档。
 邮件正文在邮件主题之后进行解析，因此还有一个额外的 _元数据_ 字段，即在考虑所有情况之后实际呈现的主题。
 期望的结果是 HTML（包括结构元素，如`<html>`，`<body>`等）。可以通过 `<style>` 块、`class` 和 `style` 属性进行样式设置。但是，`html/template` 会进行一些 [自动转义](https://go.dev/pkg/html/template/#hdr-Contexts)，需要考虑这一点。
 不支持附件（例如图像或外部样式表）。但是，也可以引用其他模板，例如以集中方式提供 `<style>` 元素的内容。外部模板必须放置在 `custom/mail` 下，并相对于该目录引用。例如，可以使用 `{{template styles/base}}` 包含 `custom/mail/styles/base.tmpl`。
 邮件以 `Content-Type: multipart/alternative` 发送，因此正文以 HTML 和文本格式发送。通过剥离 HTML 标记来获取文本版本。
 ## 故障排除
 邮件的呈现方式直接取决于邮件应用程序的功能。许多邮件客户端甚至不支持 HTML，因此显示生成邮件中包含的文本版本。
 如果模板无法呈现，则只有在发送邮件时才会注意到。
 如果主题模板失败，将使用默认主题，如果从 _邮件正文_ 中成功呈现了任何内容，则将使用该内容，忽略其他内容。
 如果遇到问题，请检查 [Gitea 的日志](../administration/logging-config.md) 以获取错误消息。
 ## 示例
 `custom/templates/mail/issue/default.tmpl`:
 ```html
 [{{.Repo}}] @{{.Doer.Name}}
 {{if eq .ActionName "new"}}
    创建了
 {{else if eq .ActionName "comment"}}
    评论了
 {{else if eq .ActionName "close"}}
    关闭了
 {{else if eq .ActionName "reopen"}}
    重新打开了
 {{else}}
    更新了
 {{end}}
 {{if eq .ActionType "issue"}}
    工单
 {{else}}
    合并请求
 {{end}}
 #{{.Issue.Index}}: {{.Issue.Title}}
 ------------
 <!DOCTYPE html>
 <html>
 <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>{{.Subject}}</title>
 </head>
 <body>
    {{if .IsMention}}
    <p>
        您收到此邮件是因为 @{{.Doer.Name}} 提到了您。
    </p>
    {{end}}
    <p>
        <p>
        <a href="{{AppUrl}}/{{.Doer.LowerName}}">@{{.Doer.Name}}</a>
        {{if not (eq .Doer.FullName "")}}
            ({{.Doer.FullName}})
        {{end}}
        {{if eq .ActionName "new"}}
            创建了
        {{else if eq .ActionName "close"}}
            关闭了
        {{else if eq .ActionName "reopen"}}
            重新打开了
        {{else}}
            更新了
        {{end}}
        <a href="{{.Link}}">{{.Repo}}#{{.Issue.Index}}</a>。
        </p>
        {{if not (eq .Body "")}}
            <h3>消息内容：</h3>
            <hr>
            {{.Body}}
        {{end}}
    </p>
    <hr>
    <p>
        <a href="{{.Link}}">在 Gitea 上查看</a>。
    </p>
 </body>
 </html>
 ```
 该模板将生成以下内容：
 ### 主题
 > [mike/stuff] @rhonda 在合并请求 #38 上进行了评论：New color palette
 ### 邮件正文
 > [@rhonda](#)（Rhonda Myers）更新了 [mike/stuff#38](#)。
 >
 > #### 消息内容
 >
 > \_******\*\*******\*\*\*\*******\*\*******\_******\*\*******\*\*\*\*******\*\*******
 >
 > Mike, I think we should tone down the blues a little.
 >
 > \_******\*\*******\*\*\*\*******\*\*******\_******\*\*******\*\*\*\*******\*\*******
 >
 > [在 Gitea 上查看](#)。
 ## 高级用法
 模板系统包含一些函数，可用于进一步处理和格式化消息。以下是其中一些函数的列表：
 | 函数名           | 参数        | 可用于     | 用法                                             |
 | ---------------- | ----------- | ---------- | ------------------------------------------------ |
 | `AppUrl`         | -           | 任何地方   | Gitea 的 URL                                     |
 | `AppName`        | -           | 任何地方   | 从 `app.ini` 中设置，通常为 "Gitea"              |
 | `AppDomain`      | -           | 任何地方   | Gitea 的主机名                                   |
 | `EllipsisString` | string, int | 任何地方   | 将字符串截断为指定长度；根据需要添加省略号       |
 | `SanitizeHTML`   | string      | 仅正文部分 | 通过删除其中的危险 HTML 标签对文本进行清理       |
 | `SafeHTML`       | string      | 仅正文部分 | 将输入作为 HTML 处理；可用于输出原始的 HTML 内容 |
 这些都是 _函数_，而不是元数据，因此必须按以下方式使用：
 ```html
 像这样使用： {{SanitizeHTML "Escape<my
  >text"}} 或者这样使用： {{"Escape<my
    >text" | SanitizeHTML}} 或者这样使用： {{AppUrl}} 但不要像这样使用：
    {{.AppUrl}}</my
  ></my
 >
 ```
@@ -1,50 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "repo-indexer"
 sidebar_position: 45
 aliases:
  - /zh-cn/repo-indexer
 ---
 # 仓库索引器
 ## 设置仓库索引器
 通过在您的 [`app.ini`](../administration/config-cheat-sheet.md) 中启用此功能，Gitea 可以通过仓库的文件进行搜索：
 ```ini
 [indexer]
 ; ...
 REPO_INDEXER_ENABLED = true
 REPO_INDEXER_PATH = indexers/repos.bleve
 MAX_FILE_SIZE = 1048576
 REPO_INDEXER_INCLUDE =
 REPO_INDEXER_EXCLUDE = resources/bin/**
 ```
 请记住，索引内容可能会消耗大量系统资源，特别是在首次创建索引或全局更新索引时（例如升级 Gitea 之后）。
 ### 按大小选择要索引的文件
 `MAX_FILE_SIZE` 选项将使索引器跳过所有大于指定值的文件。
 ### 按路径选择要索引的文件
 Gitea 使用 [`gobwas/glob` 库](https://github.com/gobwas/glob) 中的 glob 模式匹配来选择要包含在索引中的文件。
 限制文件列表可以防止索引被派生或无关的文件（例如 lss、sym、map 等）污染，从而使搜索结果更相关。这还有助于减小索引的大小。
 `REPO_INDEXER_EXCLUDE_VENDORED`（默认值为 true）将排除供应商文件不包含在索引中。
 `REPO_INDEXER_INCLUDE`（默认值为空）是一个逗号分隔的 glob 模式列表，用于在索引中**包含**的文件。空列表表示“_包含所有文件_”。
 `REPO_INDEXER_EXCLUDE`（默认值为空）是一个逗号分隔的 glob 模式列表，用于从索引中**排除**的文件。与该列表匹配的文件将不会被索引。`REPO_INDEXER_EXCLUDE` 优先于 `REPO_INDEXER_INCLUDE`。
 模式匹配工作方式如下：
 - 要匹配所有带有 `.txt` 扩展名的文件，无论在哪个目录中，请使用 `**.txt`。
 - 要匹配仅在仓库的根级别中具有 `.txt` 扩展名的所有文件，请使用 `*.txt`。
 - 要匹配 `resources/bin` 目录及其子目录中的所有文件，请使用 `resources/bin/**`。
 - 要匹配位于 `resources/bin` 目录下的所有文件，请使用 `resources/bin/*`。
 - 要匹配所有名为 `Makefile` 的文件，请使用 `**Makefile`。
 - 匹配目录没有效果；模式 `resources/bin` 不会包含/排除该目录中的文件；`resources/bin/**` 会。
 - 所有文件和模式都规范化为小写，因此 `**Makefile`、`**makefile` 和 `**MAKEFILE` 是等效的。
@@ -1,454 +0,0 @@
 ---
 date: "2018-05-22T11:00:00+00:00"
 slug: "reverse-proxies"
 sidebar_position: 16
 aliases:
  - /zh-cn/reverse-proxies
 ---
 # 反向代理
 ## 通用配置
 1. 在您的 `app.ini` 文件中添加配置 `[server] ROOT_URL = https://git.example.com/`
 2. 将 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
 3. 确保反向代理不会解码 URI。`https://git.example.com/a%2Fb`的请求应该被传递给 `http://gitea:3000/a%2Fb`。
 4. 确保 `Host` 和 `X-Forwarded-Proto` 头被正确的传递给 Gitea，使 Gitea 可以看到正在访问的真实 URL。
 5. 确保 Web 服务器有完整的证书（包括所有中间证书和根证书），以便 `git clone` 和 `git pull` 正常工作。
 6. Gitea 会在 `/-/ws` 使用 WebSocket 连接，用于通知计数等实时更新。请确保反向代理使用 HTTP/1.1，并转发 `Upgrade` 和 `Connection` 头，参见下面的示例。否则 Gitea 会回退为定期轮询。
 ## 使用子路径
 通常，**不推荐**将 Gitea 放到子路径。人们很少使用此配置，并且在极少数情况下可能会出现一些问题。
 为了让 Gitea 在子路径工作（例如：`https://common.example.com/gitea/`），需要在上面的通用配置之外进行一些额外的配置：
 1. 在 `app.ini` 文件中使用配置 `[server] ROOT_URL = https://common.example.com/gitea/`。
 2. 将 `https://common.example.com/gitea/foo` 反向代理到 `http://gitea:3000/foo`。
 3. 容器映像注册表需要在根目录级别有一个固定的子路径 `v2`，您必须做下列配置：
   - 将 `https://common.example.com/v2` 反向代理到 `http://gitea:3000/v2`。
   - 确保 URI 和标头也被正确的传递（见上面的通用配置）
 ## 使用 Nginx 作为反向代理服务
 如果您想使用 Nginx 作为 Gitea 的反向代理服务，您可以参照以下 `nginx.conf` 配置中 `server` 的 `http` 部分。
 确保 `client_max_body_size` 足够大，否则在上传大文件时会出现 "client_max_body_size" 错误。
 ```nginx
 server {
    ...
    location / {
        client_max_body_size 512M;
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
 ```
 ## 使用 Nginx 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下 `nginx.conf` 配置中 `server` 的 `http` 部分，为 Gitea 添加路由规则：
 ```nginx
 server {
    ...
    location ~ ^/(gitea|v2)($|/) {
        client_max_body_size 512M;
        # 确保 nginx 使用未转义 URI， 按原样保持 "%2F"。 确保 nginx 去除 "/gitea" 子路径前缀， 按原样传递 "/v2"。
        rewrite ^ $request_uri;
        rewrite ^/(gitea($|/))?(.*) /$3 break;
        proxy_pass http://127.0.0.1:3000$uri;
        proxy_http_version 1.1;
        # 其他的常规 HTTP 表头，见上面“使用 Nginx 作为反向代理服务”小节的配置
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
 ```
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
 ## 使用 Nginx 直接提供静态资源
 我们可以通过将资源分为静态和动态两种类型来调节性能。
 CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
 Nginx 可以直接提供静态资源，并且只代理动态资源请求给 Gitea。
 Nginx 为提供静态内容进行了优化，而代理大响应可能与这一优化行为相反。
 （见[https://serverfault.com/q/587386](https://serverfault.com/q/587386)）
 将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea`。
 在此之后，在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下，我们只对 `public/` 目录感兴趣，您可以删除剩下的其他目录。
 （为了生成静态资源，您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
 取决于您的用户量的大小，您可以将流量分离到两个不同的服务器，或者为静态资源配置一个 cdn。
 ### 单服务器节点，单域名
 将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件，并配置 nginx：
 ```nginx
 server {
    listen 80;
    server_name git.example.com;
    location /_/static/assets/ {
        alias /path/to/gitea/public/;
    }
    location / {
        # 其他指令见上面「使用 Nginx 作为反向代理服务」小节
        proxy_pass http://localhost:3000;
    }
 }
 ```
 ### 双服务器节点，双域名
 将 `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` 写入您的 Gitea 配置文件，并配置 nginx：
 ```nginx
 # 运行 Gitea 的服务器
 server {
    listen 80;
    server_name git.example.com;
    location / {
        # 其他指令见上面「使用 Nginx 作为反向代理服务」小节
        proxy_pass http://localhost:3000;
    }
 }
 ```
 ```nginx
 # 提供静态资源的服务器
 server {
    listen 80;
    server_name cdn.example.com;
    location /gitea/ {
        alias /path/to/gitea/public/;
    }
    location / {
        return 404;
    }
 }
 ```
 ## Nginx Proxy Manager
 如果使用 Nginx Proxy Manager 作为 Gitea 的反向代理，配置与原生 Nginx 略有不同。
 它会[默认给自定义 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf)，因此上面 Nginx 配置里对应的指令不要再写一遍。否则会因为指令重复（尤其是 `proxy_set_header Host $host`）出现 `400 bad request`。
 创建 `/` 自定义 location 时，只需在其配置中加入：
 ```nginx
 client_max_body_size 512M;
 ```
 在代理主机上启用 `Websockets Support`，Nginx Proxy Manager 会自行加入 WebSocket 相关指令。再额外添加 `proxy_http_version` 会导致 Nginx 拒绝启动。
 ## 使用 Apache HTTPD 作为反向代理服务
 如果您想使用 Apache HTTPD 作为 Gitea 的反向代理服务，您可以为您的 Apache HTTPD 作如下配置（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
 ```apacheconf
 <VirtualHost *:80>
    ...
    ProxyPreserveHost On
    ProxyRequests off
    AllowEncodedSlashes NoDecode
    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```
 :::note
 必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。
 `upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本。更旧的版本**必须**去掉它，否则 Apache HTTPD 将无法启动。
 :::
 如果希望用 Let's Encrypt 的 webroot 验证，请在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`，避免把这些请求代理到 Gitea。
 ## 使用 Apache HTTPD 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下配置为 Gitea 添加路由规则（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
 ```apacheconf
 <VirtualHost *:80>
    ...
    <Proxy *>
         Order allow,deny
         Allow from all
    </Proxy>
    AllowEncodedSlashes NoDecode
    # 注意: 路径和 URL 后面都不要写路径符号 '/'
    ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
    ProxyPreserveHost On
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
 :::note
 必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更旧的版本请去掉它。
 :::
 ## 使用 Apache HTTPD 直接提供静态资源
 我们可以通过将资源分为静态和动态两种类型来调节性能。
 CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
 Apache HTTPD 可以直接提供静态资源，并且只代理动态资源请求给 Gitea。
 将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea/`。
 在此之后，在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下，我们只对 `public/` 目录感兴趣，您可以删除剩下的其他目录。
 （为了生成静态资源，您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
 取决于您的用户量的大小，您可以将流量分离到两个不同的服务器，或者为静态资源配置一个 cdn。
 ### 单服务器节点，单域名
 将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件：
 ```apacheconf
 <VirtualHost *:80>
    ...
    <Proxy *>
         Order allow,deny
         Allow from all
    </Proxy>
    ProxyPass /_/static/ !
    Alias /_/static/ /path/to/gitea/public/
    <Directory /path/to/gitea/public/>
        Options FollowSymlinks
 		AllowOverride None
 		Require all granted
    </Directory>
    AllowEncodedSlashes NoDecode
    # 注意: 路径和 URL 后面都不要写路径符号 '/'
    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
    ProxyPreserveHost On
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```
 :::note
 必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更旧的版本请去掉它。
 :::
 ## 使用 Caddy 作为反向代理服务
 如果您想使用 Caddy 作为 Gitea 的反向代理服务，您可以在 `Caddyfile` 中添加如下配置：
 ```
 git.example.com {
    reverse_proxy localhost:3000
 }
 ```
 ## 使用 Caddy 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以在您的 `Caddyfile` 文件中增加以下配置，为 Gitea 添加路由规则：
 ```
 git.example.com {
    route /git/* {
        uri strip_prefix /git
        reverse_proxy localhost:3000
    }
 }
 ```
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。
 ## 使用 IIS 作为反向代理服务
 如果您想使用 IIS 作为 Gitea 的反向代理服务，你需要为 IIS 设置 URL 重写来作为反向代理。
 1. 在 IIS 中设置一个空网页，比如命名为 `Gitea Proxy`。
 2. 根据[微软社区中为 IIS 设置 URL 重写的指南](https://techcommunity.microsoft.com/t5/iis-support-blog/setup-iis-with-url-rewrite-as-a-reverse-proxy-for-real-world/ba-p/846222#M343)的前两步进行配置，也就是：
 - 使用 Microsoft Web Platform Installer 5.1 (WebPI) 安装 Application Request Routing（简称 ARR），或者在 [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing) 下载这个插件。
 - 一但这个模块被安装到 IIS 上，你将会在 IIS 管理控制台看到一个叫做 URL Rewrite 的新图标。
 - 安装 Windows 功能 `WebSocket Protocol`，否则 ARR 无法代理 Gitea 的 WebSocket 端点。
 - 打开 IIS 管理控制台，在左边的列表中点击 `Gitea Proxy` 网页。在中间选中并且双击 URL Rewrite 的图标来加载 URL 重写的面板。
 - 在管理控制台的右边选择 `Add Rule` 操作，并且在 `Inbound and Outbound Rules` 分类中选择 `Reverse Proxy Rule`。
 - 在 Inbound Rules 中， 将 server name 设置为 Gitea 正在运行的主机以及对应端口。例如，如果你在 localhost 的 3000 端口上运行 Gitea，则设置为 `127.0.0.1:3000`。
 - 启用 SSL Offloading
 - 在 Outbound Rules 中，确保设置了 `Rewrite the domain names of the links in HTTP response`，并且将 `From:` 设置为上面的 server name，将 `To:` 设置为你的外部访问名称，例如：`git.example.com`
 - 关闭 Application Request Routing 的 `Server Proxy Settings` 中的 `Reverse rewrite host in response headers`（在 IIS 管理器中选择服务器节点，打开 `Application Request Routing Cache`，再打开右侧的 `Server Proxy Settings`）。若保持开启，ARR 会把 `Location` 头里的主机改回内部地址，导致登录或表单提交后的重定向把浏览器送到 `127.0.0.1:3000` 而不是 `git.example.com`。
 - 现在，根据下面的内容为您的网页编辑 `web.config`（将 `127.0.0.1:3000` 和 `git.example.com` 改为适当的值）
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <configuration>
    <system.web>
        <httpRuntime requestPathInvalidCharacters="" />
    </system.web>
    <system.webServer>
        <security>
          <requestFiltering>
            <hiddenSegments>
              <clear />
            </hiddenSegments>
            <denyUrlSequences>
              <clear />
            </denyUrlSequences>
            <fileExtensions allowUnlisted="true">
              <clear />
            </fileExtensions>
          </requestFiltering>
        </security>
        <rewrite>
            <rules useOriginalURLEncoding="false">
                <rule name="ReverseProxyInboundRule1" stopProcessing="true">
                    <match url="(.*)" />
                    <action type="Rewrite" url="http://127.0.0.1:3000{UNENCODED_URL}" />
                    <serverVariables>
                        <set name="HTTP_X_ORIGINAL_ACCEPT_ENCODING" value="HTTP_ACCEPT_ENCODING" />
                        <set name="HTTP_ACCEPT_ENCODING" value="" />
                    </serverVariables>
                </rule>
            </rules>
            <outboundRules>
                <rule name="ReverseProxyOutboundRule1" preCondition="ResponseIsHtml1">
                    <!-- set the pattern correctly here - if you only want to accept http or https -->
                    <!-- change the pattern and the action value as appropriate -->
                    <match filterByTags="A, Form, Img" pattern="^http(s)?://127.0.0.1:3000/(.*)" />
                    <action type="Rewrite" value="http{R:1}://git.example.com/{R:2}" />
                </rule>
                <rule name="RestoreAcceptEncoding" preCondition="NeedsRestoringAcceptEncoding">
                    <match serverVariable="HTTP_ACCEPT_ENCODING" pattern="^(.*)" />
                    <action type="Rewrite" value="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" />
                </rule>
                <preConditions>
                    <preCondition name="ResponseIsHtml1">
                        <add input="{RESPONSE_CONTENT_TYPE}" pattern="^text/html" />
                    </preCondition>
                    <preCondition name="NeedsRestoringAcceptEncoding">
                        <add input="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" pattern=".+" />
                    </preCondition>
                </preConditions>
            </outboundRules>
        </rewrite>
        <urlCompression doDynamicCompression="true" />
        <handlers>
          <clear />
          <add name="StaticFile" path="*" verb="*" modules="StaticFileModule,DefaultDocumentModule,DirectoryListingModule" resourceType="Either" requireAccess="Read" />
        </handlers>
        <!-- Map all extensions to the same MIME type, so all files can be
               downloaded. -->
        <staticContent>
          <clear />
          <mimeMap fileExtension="*" mimeType="application/octet-stream" />
        </staticContent>
    </system.webServer>
 </configuration>
 ```
 ## 使用 HAProxy 作为反向代理服务
 如果您想使用 HAProxy 作为 Gitea 的反向代理服务，您可以将下面的内容加入您的 HAProxy 配置。
 在 frontend 部分加入一个 acl 来将对 gitea.example.com 的请求重定向到正确的后端。
 ```
 frontend http-in
    ...
    acl acl_gitea hdr(host) -i gitea.example.com
    use_backend gitea if acl_gitea
    ...
 ```
 添加之前定义好的 backend 部分
 ```
 backend gitea
    server localhost:3000 check
 ```
 如果您将 http 内容重定向到 https，上面的配置文件也能够使用。只需要记住，在 HAProxy 和 Gitea 之间的连接将由 http 完成，所以你不需要在 Gitea 的配置文件中启用 https。
 ## 使用 HAProxy 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以在您的 HAProxy 中加入如下配置，为 Gitea 添加路由规则：
 ```
 frontend http-in
    ...
    acl acl_gitea path_beg /gitea
    use_backend gitea if acl_gitea
    ...
 ```
 在这个配置下，http://example.com/gitea/ 将被重定向到您的 Gitea 实例。
 接下来，对于 backend 部分：
 ```
 backend gitea
    http-request replace-path /gitea\/?(.*) \/\1
    server localhost:3000 check
 ```
 添加的 http-request 在需要的时候会自动加入反斜杠/，并且通过将 http://example.com/gitea 正确设置为根来在内部路径中删除 /gitea，使其能够正常工作。
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://example.com/gitea/` 的配置项。
 ## 使用 Traefik 作为反向代理服务
 如果您想使用 traefik 作为 Gitea 的反向代理服务，您可以在 `docker-compose.yaml` 中添加 label 部分（假设使用 docker 作为 traefik 的 provider）：
 ```yaml
 gitea:
  image: docker.io/gitea/gitea
  ...
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.gitea.rule=Host(`example.com`)"
    - "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
 ```
 这份配置假设您使用 traefik 来处理 HTTPS 服务，并在其和 Gitea 之间使用 HTTP 进行通信。
 ## 使用 Traefik 作为反向代理服务并将 Gitea 路由至一个子路径
 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以在您的 `docker-compose.yaml` 文件中增加以下配置，为 Gitea 添加路由规则（假设使用 docker 作为 traefik 的 provider）：
 ```yaml
 gitea:
  image: docker.io/gitea/gitea
  ...
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.gitea.rule=Host(`example.com`) && PathPrefix(`/gitea`)"
    - "traefik.http.services.gitea-websecure.loadbalancer.server.port=3000"
    - "traefik.http.middlewares.gitea-stripprefix.stripprefix.prefixes=/gitea"
    - "traefik.http.routers.gitea.middlewares=gitea-stripprefix"
 ```
 这份配置假设您使用 traefik 来处理 HTTPS 服务，并在其和 Gitea 之间使用 HTTP 进行通信。
 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://example.com/gitea/` 的配置项。
@@ -1,30 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "search-engines-indexation"
 sidebar_position: 60
 aliases:
  - /zh-cn/search-engines-indexation
 ---
 # 搜索引擎索引
 默认情况下，您的 Gitea 安装将被搜索引擎索引。
 如果您不希望您的仓库对搜索引擎可见，请进一步阅读。
 ## 使用 robots.txt 阻止搜索引擎索引
 为了使 Gitea 为顶级安装提供自定义的`robots.txt`（默认为空的 404），请在 [`custom`文件夹或`CustomPath`]（administration/customizing-gitea.md）中创建一个名为 `public/robots.txt` 的文件。
 有关如何配置 `robots.txt` 的示例，请参考 [https://moz.com/learn/seo/robotstxt](https://moz.com/learn/seo/robotstxt)。
 ```txt
 User-agent: *
 Disallow: /
 ```
 如果您将 Gitea 安装在子目录中，则需要在顶级目录中创建或编辑 `robots.txt`。
 ```txt
 User-agent: *
 Disallow: /gitea/
 ```
@@ -1,137 +0,0 @@
 ---
 date: "2023-05-23T09:00:00+08:00"
 slug: "signing"
 sidebar_position: 50
 aliases:
  - /zh-cn/signing
 ---
 # GPG 提交签名
 Gitea 将通过检查提交是否由 Gitea 数据库中的密钥签名，或者提交是否与 Git 的默认密钥匹配，来验证提供的树中的 GPG 提交签名。
 密钥不会被检查以确定它们是否已过期或撤销。密钥也不会与密钥服务器进行检查。
 如果找不到用于验证提交的密钥，提交将被标记为灰色的未锁定图标。如果提交被标记为红色的未锁定图标，则表示它使用带有 ID 的密钥签名。
 请注意：提交的签署者不必是提交的作者或提交者。
 此功能要求 Git >= 1.7.9，但要实现全部功能，需要 Git >= 2.0.0。
 ## 自动签名
 有许多地方 Gitea 会生成提交：
 - 仓库初始化
 - Wiki 更改
 - 使用编辑器或 API 进行的 CRUD 操作
 - 从合并请求进行合并
 根据配置和服务器信任，您可能希望 Gitea 对这些提交进行签名。
 ## 安装和生成 Gitea 的 GPG 密钥
 如何安装签名密钥由服务器管理员决定。Gitea 目前使用服务器的 `git` 命令生成所有提交，因此将使用服务器的 `gpg` 进行签名（如果配置了）。管理员应该审查 GPG 的最佳实践 - 特别是可能建议仅安装签名的子密钥，而不是主签名和认证的密钥。
 ## 通用配置
 Gitea 的签名配置可以在 `app.ini` 的 `[repository.signing]` 部分找到：
 ```ini
 ...
 [repository.signing]
 SIGNING_KEY = default
 SIGNING_NAME =
 SIGNING_EMAIL =
 INITIAL_COMMIT = always
 CRUD_ACTIONS = pubkey, twofa, parentsigned
 WIKI = never
 MERGES = pubkey, twofa, basesigned, commitssigned
 ...
 ```
 ### `SIGNING_KEY`
 首先讨论的选项是 `SIGNING_KEY`。有三个主要选项：
 - `none` - 这将阻止 Gitea 对任何提交进行签名
 - `default` - Gitea 将使用 `git config` 中配置的默认密钥
 - `KEYID` - Gitea 将使用具有 ID `KEYID` 的 GPG 密钥对提交进行签名。在这种情况下，您应该提供 `SIGNING_NAME` 和 `SIGNING_EMAIL`，以便显示此密钥的信息。
 `default` 选项将读取 `git config` 中的 `commit.gpgsign` 选项 - 如果设置了该选项，它将使用 `user.signingkey`、`user.name` 和 `user.email` 的结果。
 通过在 Gitea 的仓库中调整 Git 的 `config` 文件，可以使用 `SIGNING_KEY=default` 为每个仓库提供不同的签名密钥。然而，这显然不是一个理想的用户界面，因此可能会发生更改。
 :::warning
 **自 1.17 起**，Gitea 在自己的主目录 `[git].HOME_PATH`（默认为 `%(APP_DATA_PATH)/home`）中运行 git，并使用自己的配置文件 `{[git].HOME_PATH}/.gitconfig`。
 如果您有自己定制的 Gitea git 配置，您应该将这些配置设置在系统 git 配置文件中（例如 `/etc/gitconfig`）或者 Gitea 的内部 git 配置文件 `{[git].HOME_PATH}/.gitconfig` 中。
 与 git 命令相关的主目录文件（如 `.gnupg`）也应该放在 Gitea 的 git 主目录 `[git].HOME_PATH` 中。
 如果您希望将 `.gnupg` 目录放在 `{[git].HOME_PATH}/` 之外的位置，请考虑设置 `$GNUPGHOME` 环境变量为您首选的位置，否则 Gitea 将会从 `{[git].HOME_PATH}/.gnupg` 查找私钥。
 :::
 ### `INITIAL_COMMIT`
 此选项确定在创建仓库时，Gitea 是否应该对初始提交进行签名。可能的取值有：
 - `never`：从不签名
 - `pubkey`：仅在用户拥有公钥时进行签名
 - `twofa`：仅在用户使用 2FA 登录时进行签名
 - `always`：始终签名
 除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则提交将被签名。
 ### `WIKI`
 此选项确定 Gitea 是否应该对 Wiki 的提交进行签名。可能的取值有：
 - `never`：从不签名
 - `pubkey`：仅在用户拥有公钥时进行签名
 - `twofa`：仅在用户使用 2FA 登录时进行签名
 - `parentsigned`：仅在父提交已签名时进行签名。
 - `always`：始终签名
 除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则提交将被签名。
 ### `CRUD_ACTIONS`
 此选项确定 Gitea 是否应该对 Web 编辑器或 API CRUD 操作的提交进行签名。可能的取值有：
 - `never`：从不签名
 - `pubkey`：仅在用户拥有公钥时进行签名
 - `twofa`：仅在用户使用 2FA 登录时进行签名
 - `parentsigned`：仅在父提交已签名时进行签名。
 - `always`：始终签名
 除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则更改将被签名。
 ### `MERGES`
 此选项确定 Gitea 是否应该对 PR 的合并提交进行签名。可能的选项有：
 - `never`：从不签名
 - `pubkey`：仅在用户拥有公钥时进行签名
 - `twofa`：仅在用户使用 2FA 登录时进行签名
 - `basesigned`：仅在基础仓库中的父提交已签名时进行签名。
 - `headsigned`：仅在头分支中的头提交已签名时进行签名。
 - `commitssigned`：仅在头分支中的所有提交到合并点的提交都已签名时进行签名。
 - `approved`：仅对已批准的合并到受保护分支的提交进行签名。
 - `always`：始终签名
 除了 `never` 和 `always` 之外的选项可以组合为逗号分隔的列表。如果所有选择的选项都为 true，则合并将被签名。
 ## 获取签名密钥的公钥
 用于签署 Gitea 提交的公钥可以通过 API 获取：
 ```sh
 /api/v1/signing-key.gpg
 ```
 在存在特定于仓库的密钥的情况下，可以通过以下方式获取：
 ```sh
 /api/v1/repos/:username/:reponame/signing-key.gpg
 ```
@@ -1,9 +0,0 @@
 {
  "label": "贡献",
  "position": 35,
  "link": {
    "type": "generated-index",
    "slug": "/contributing",
    "title": "贡献"
  }
 }
@@ -1,110 +0,0 @@
 ---
 date: "2023-05-25T23:41:00+08:00"
 slug: "guidelines-backend"
 sidebar_position: 20
 aliases:
  - /zh-cn/guidelines-backend
 ---
 # 后端开发指南
 ## 背景
 Gitea 使用 Golang 作为后端编程语言。它使用了许多第三方包，并且自己也编写了一些包。
 例如，Gitea 使用[Chi](https://github.com/go-chi/chi)作为基本的 Web 框架。[Xorm](https://xorm.io)是一个用于与数据库交互的 ORM 框架。
 因此，管理这些包非常重要。在开始编写后端代码之前，请参考以下准则。
 ## 包设计准则
 ### 包列表
 为了保持易于理解的代码并避免循环依赖，拥有良好的代码结构是很重要的。Gitea 后端分为以下几个部分：
 - `build`：帮助构建 Gitea 的脚本。
 - `cmd`：包含所有 Gitea 的实际子命令，包括 web、doctor、serv、hooks、admin 等。`web`将启动 Web 服务。`serv`和`hooks`将被 Git 或 OpenSSH 调用。其他子命令可以帮助维护 Gitea。
 - `tests`：常用的测试函数
 - `tests/integration`：集成测试，用于测试后端回归。
 - `tests/e2e`：端到端测试，用于测试前端和后端的兼容性和视觉回归。
 - `models`：包含由 xorm 用于构建数据库表的数据结构。它还包含查询和更新数据库的函数。应避免与其他 Gitea 代码的依赖关系。在某些情况下，比如日志记录时可以例外。
  - `models/db`：基本的数据库操作。所有其他`models/xxx`包都应依赖于此包。`GetEngine`函数只能从 models/中调用。
  - `models/fixtures`：单元测试和集成测试中使用的示例数据。一个`yml`文件表示一个将在测试开始时加载到数据库中的表。
  - `models/migrations`：存储不同版本之间的数据库迁移。修改数据库结构的 PR**必须**包含一个迁移步骤。
 - `modules`：在 Gitea 中处理特定功能的不同模块。工作正在进行中：其中一些模块应该移到`services`中，特别是那些依赖于 models 的模块，因为它们依赖于数据库。
  - `modules/setting`：存储从 ini 文件中读取的所有系统配置，并在各处引用。但是在可能的情况下，应将其作为函数参数使用。
  - `modules/git`：用于与`Git`命令行或 Gogit 包交互的包。
 - `public`：编译后的前端文件（JavaScript、图像、CSS 等）
 - `routers`：处理服务器请求。由于它使用其他 Gitea 包来处理请求，因此其他包（models、modules 或 services）不能依赖于 routers。
  - `routers/api`：包含`/api/v1`相关路由，用于处理 RESTful API 请求。
  - `routers/install`：只能在系统处于安装模式（INSTALL_LOCK=false）时响应。
  - `routers/private`：仅由内部子命令调用，特别是`serv`和`hooks`。
  - `routers/web`：处理来自 Web 浏览器或 Git SMART HTTP 协议的 HTTP 请求。
 - `services`：用于常见路由操作或命令执行的支持函数。使用`models`和`modules`来处理请求。
 - `templates`：用于生成 HTML 输出的 Golang 模板。
 ### 包依赖关系
 由于 Golang 不支持导入循环，我们必须仔细决定包之间的依赖关系。这些包之间有一些级别。以下是理想的包依赖关系方向。
 `cmd` -> `routers` -> `services` -> `models` -> `modules`
 从左到右，左侧的包可以依赖于右侧的包，但右侧的包不能依赖于左侧的包。在同一级别的子包中，可以根据该级别的规则进行依赖。
 **注意事项**
 为什么我们需要在`models`之外使用数据库事务？以及如何使用？
 某些操作在数据库记录插入/更新/删除失败时应该允许回滚。
 因此，服务必须能够创建数据库事务。以下是一些示例：
 ```go
 // services/repository/repository.go
 func CreateXXXX() error {
    return db.WithTx(func(ctx context.Context) error {
        // do something, if err is returned, it will rollback automatically
        if err := issues.UpdateIssue(ctx, repoID); err != nil {
            // ...
            return err
        }
        // ...
        return nil
    })
 }
 ```
 在`services`中**不应该**直接使用`db.GetEngine(ctx)`，而是应该在`models/`下编写一个函数。
 如果该函数将在事务中使用，请将`context.Context`作为函数的第一个参数。
 ```go
 // models/issues/issue.go
 func UpdateIssue(ctx context.Context, repoID int64) error {
    e := db.GetEngine(ctx)
    // ...
 }
 ```
 ### 包名称
 对于顶层包，请使用复数作为包名，例如`services`、`models`，对于子包，请使用单数，例如`services/user`、`models/repository`。
 ### 导入别名
 由于有一些使用相同包名的包，例如`modules/user`、`models/user`和`services/user`，当这些包在一个 Go 文件中被导入时，很难知道我们使用的是哪个包以及它是变量名还是导入名。因此，我们始终建议使用导入别名。为了与常见的驼峰命名法的包变量区分开，建议使用**snake_case**作为导入别名的命名规则。
 例如：`import user_service "code.gitea.io/gitea/services/user"`
 ### 重要注意事项
 - 永远不要写成`x.Update(exemplar)`，而没有明确的`WHERE`子句：
  - 这将导致表中的所有行都被使用 exemplar 的非零值进行更新，包括 ID。
  - 通常应该写成`x.ID(id).Update(exemplar)`。
 - 如果在迁移过程中使用`x.Insert(exemplar)`向表中插入记录，而 ID 是预设的：
  - 对于 MSSQL 变体，你将需要执行`` SET IDENTITY_INSERT `table` ON ``（否则迁移将失败）
  - 对于 PostgreSQL，你还需要更新 ID 序列，否则迁移将悄无声息地通过，但后续的插入将失败：
    `` SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false) ``
 ### 未来的任务
 目前，我们正在进行一些重构，以完成以下任务：
 - 纠正不符合规则的代码。
 - `models`中的文件太多了，所以我们正在将其中的一些移动到子包`models/xxx`中。
 - 由于它们依赖于`models`，因此应将某些`modules`子包移动到`services`中。
@@ -1,149 +0,0 @@
 ---
 date: "2023-05-25T16:00:00+02:00"
 slug: "guidelines-frontend"
 sidebar_position: 20
 aliases:
  - /zh-cn/guidelines-frontend
 ---
 # 前端开发指南
 ## 背景
 Gitea 在其前端中使用[Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html)（基于[jQuery](https://api.jquery.com)）和 [Vue3](https://vuejs.org/)。
 HTML 页面由[Go HTML Template](https://pkg.go.dev/html/template)渲染。
 源文件可以在以下目录中找到：
 - **CSS 样式**： `web_src/css/`
 - **JavaScript 文件**： `web_src/js/`
 - **Vue 组件**： `web_src/js/components/`
 - **Go HTML 模板**： `templates/`
 ## 通用准则
 我们推荐使用[Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)和[Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)。
 ## Gitea 特定准则
 1. 每个功能（Fomantic-UI/jQuery 模块）应放在单独的文件/目录中。
 2. HTML 的 id 和 class 应使用 kebab-case，最好包含 2-3 个与功能相关的关键词。
 3. 在 JavaScript 中使用的 HTML 的 id 和 class 应在整个项目中是唯一的，并且应包含 2-3 个与功能相关的关键词。建议在仅在 JavaScript 中使用的 class 中使用 `js-` 前缀。
 4. 不应覆盖框架提供的 class 的 CSS 样式。始终使用具有 2-3 个与功能相关的关键词的新 class 名称来覆盖框架样式。Gitea 中的帮助 CSS 类在 `helpers.less` 中。
 5. 后端可以通过使用`ctx.PageData["myModuleData"] = map[]{}`将复杂数据传递给前端，但不要将整个模型暴露给前端，以避免泄露敏感数据。
 6. 简单页面和与 SEO 相关的页面使用 Go HTML 模板渲染生成静态的 Fomantic-UI HTML 输出。复杂页面可以使用 Vue3。
 7. 明确变量类型，优先使用`elem.disabled = true`而不是`elem.setAttribute('disabled', 'anything')`，优先使用`$el.prop('checked', var === 'yes')`而不是`$el.prop('checked', var)`。
 8. 使用语义化元素，优先使用`<button class="ui button">`而不是`<div class="ui button">`。
 9. 避免在 CSS 中使用不必要的`!important`，如果无法避免，添加注释解释为什么需要它。
 10. 避免在一个事件监听器中混合不同的事件，优先为每个事件使用独立的事件监听器。
 11. 推荐使用自定义事件名称前缀`ce-`。
 12. 建议使用 Tailwind CSS，它可以通过 `tw-` 前缀获得，例如 `tw-relative`. Gitea 自身的助手类 CSS 使用 `gt-` 前缀（`gt-ellipsis`），Gitea 自身的私有框架级 CSS 类使用 `g-` 前缀（`g-modal-confirm`）。
 13. 尽量避免内联脚本和样式，建议将 JS 代码放入 JS 文件中并使用 CSS 类。如果内联脚本和样式不可避免，请解释无法避免的原因。
 ### 可访问性 / ARIA
 在历史上，Gitea 大量使用了可访问性不友好的框架 Fomantic UI。
 Gitea 使用一些补丁使 Fomantic UI 更具可访问性（参见 `aria.md`），
 但仍然存在许多问题需要大量的工作和时间来修复。
 ### 框架使用
 不建议混合使用不同的框架，这会使代码难以维护。
 一个 JavaScript 模块应遵循一个主要框架，并遵循该框架的最佳实践。
 推荐的实现方式：
 - Vue + Vanilla JS
 - Fomantic-UI（jQuery）
 - htmx （部分页面重新加载其他静态组件）
 - Vanilla JS
 不推荐的实现方式：
 - Vue + Fomantic-UI（jQuery）
 - jQuery + Vanilla JS
 - htmx + 任何其他需要大量 JavaScript 代码或不必要的功能，如 htmx 脚本 (`hx-on`)
 为了保持界面一致，Vue 组件可以使用 Fomantic-UI 的 CSS 类。
 尽管不建议混合使用不同的框架，
 我们使用 htmx 进行简单的交互。您可以在此 [PR](https://github.com/go-gitea/gitea/pull/28908) 中查看一个简单交互的示例，其中应使用 htmx。如果您需要更高级的反应性，请不要使用 htmx，请使用其他框架（Vue/Vanilla JS）。
 但如果混合使用是必要的，并且代码设计良好且易于维护，也可以工作。
 ### `async` 函数
 只有当函数内部存在`await`调用或返回`Promise`时，才将函数标记为`async`。
 不建议使用`async`事件监听器，这可能会导致问题。
 原因是`await`后的代码在事件分发之外执行。
 参考：https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md
 如果一个事件监听器必须是`async`，应在任何`await`之前使用`e.preventDefault()`，
 建议将其放在函数的开头。
 如果我们想在非异步上下文中调用`async`函数，
 建议使用`const _promise = asyncFoo()`来告诉读者
 这是有意为之的，我们想调用异步函数并忽略 Promise。
 一些 lint 规则和 IDE 也会在未处理返回的 Promise 时发出警告。
 ### 获取数据
 要获取数据，请使用`modules/fetch.js`中的包装函数`GET`、`POST`等。他们
 接受内容的`data`选项，将自动设置 CSRF 令牌并返回
 [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)。
 ### HTML 属性和 dataset
 禁止使用`dataset`，它的驼峰命名行为使得搜索属性变得困难。
 然而，仍然存在一些特殊情况，因此当前的准则是：
 - 对于旧代码：
  - 应将`$.data()`重构为`$.attr()`。
  - 在极少数情况下，可以使用`$.data()`将一些非字符串数据绑定到元素上，但强烈不推荐使用。
 - 对于新代码：
  - 不应使用`node.dataset`，而应使用`node.getAttribute`。
  - 不要将任何用户数据绑定到 DOM 节点上，使用合适的设计模式描述节点和数据之间的关系。
 ### 显示/隐藏元素
 - 推荐在 Vue 组件中使用`v-if`和`v-show`来显示/隐藏元素。
 - Go 模板代码应使用 `.tw-hidden` 和 `showElem()/hideElem()/toggleElem()` 来显示/隐藏元素，请参阅`.tw-hidden`的注释以获取更多详细信息。
 ### Go HTML 模板中的样式和属性
 建议使用以下方式：
 ```html
 <div
  class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}"
  {{if
  .IsFoo}}data-foo{{end}}
 ></div>
 ```
 而不是：
 ```html
 <div
  class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"
  {{if
  .IsFoo}}
  data-foo{{end}}
 ></div>
 ```
 以使代码更易读。
 ### 旧代码
 许多旧代码已经存在于本文撰写之前。建议重构旧代码以遵循指南。
 ### Vue3 和 JSX
 Gitea 现在正在使用 Vue3。我们决定不引入 JSX，以保持 HTML 代码和 JavaScript 代码分离。
 ### UI 示例
 Gitea 使用一些自制的 UI 元素并自定义其他元素，以将它们更好地集成到通用 UI 方法中。当在开发模式（`RUN_MODE=dev`）下运行 Gitea 时，在 `http(s)://your-gitea-url:port/devtest` 下会提供一个包含一些标准化 UI 示例的页面。
@@ -1,40 +0,0 @@
 ---
 date: "2023-05-25T00:00:00+00:00"
 slug: "guidelines-refactoring"
 sidebar_position: 20
 aliases:
  - /zh-cn/guidelines-refactoring
 ---
 # 重构指南
 ## 背景
 自 2014 年 2 月 12 日编写了第一行代码以来，Gitea 已经发展成为一个庞大的项目。
 因此，代码库变得越来越大。代码库越大，维护就越困难。
 存在许多过时的机制，许多框架混合在一起，一些遗留代码可能会导致错误并阻碍新功能的开发。
 为了使代码库更易于维护，使 Gitea 变得更好，开发人员应牢记使用现代机制来重构旧代码。
 本文档是关于重构代码库的指南集合。
 ## 重构建议
 - 设计更多关于未来的内容，而不仅仅解决当前问题。
 - 减少模糊性，减少冲突，提高可维护性。
 - 描述重构，例如：
  - 为什么需要重构。
  - 如何解决旧问题。
  - 重构的优点/缺点是什么。
 - 只做必要的更改，尽量保留旧逻辑。
 - 引入一些中间步骤，使重构更容易审查，完整的重构计划可以在几个 PR 中完成。
 - 如果存在分歧，应该请 TOC（技术监督委员会）参与决策。
 - 添加必要的测试以确保重构的正确性。
 - 非错误重构优先在里程碑的开始时进行，这样可以更容易地在发布之前发现问题。
 ## 审查和合并建议
 - 重构的 PR 不应该长时间保持打开状态（通常为 7 天），应尽快进行审查。
 - 重构的 PR 应尽快合并，不应被其他 PR 阻塞。
 - 如果 TOC 没有异议，重构的 PR 可以在 7 天后由一名核心成员（非作者）批准后合并。
 - 如果最终结果良好，容忍一些不完美/临时的步骤。
 - 如果重构是必要的，容忍一些回归错误，并尽快修复错误。
@@ -1,25 +0,0 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "localization"
 sidebar_position: 70
 aliases:
  - /zh-cn/localization
 ---
 # 本地化
 Gitea 的本地化是通过我们的[Crowdin 项目](https://crowdin.com/project/gitea)进行的。
 对于对**英语翻译**的更改，可以发出 pull-request，来更改[英语语言环境](https://github.com/go-gitea/gitea/blob/main/options/locale/locale_en-US.ini)中合适的关键字。
 有关对**非英语**翻译的更改，请参阅上面的 Crowdin 项目。
 ## 支持的语言
 上述 Crowdin 项目中列出的任何语言一旦翻译了 25% 或更多都将得到支持。
 翻译被接受后，它将在下一次 Crowdin 同步后反映在主存储库中，这通常是在任何 PR 合并之后。
 在撰写本文时，这意味着更改后的翻译可能要到 Gitea 的下一个版本才会出现。
 如果使用开发版本，则在同步更改内容后，它应该会在更新后立即显示。
@@ -1,9 +0,0 @@
 {
  "label": "开发",
  "position": 40,
  "link": {
    "type": "generated-index",
    "slug": "/development",
    "title": "开发"
  }
 }
@@ -1,334 +0,0 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "hacking-on-gitea"
 sidebar_position: 10
 aliases:
  - /zh-cn/hacking-on-gitea
 ---
 # 玩转 Gitea
 ## 快速入门
 要获得快速工作的开发环境，您可以使用 Gitpod。
 [![在 Gitpod 中打开](/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/go-gitea/gitea)
 ## 安装 Golang
 您需要 [安装 go](https://go.dev/doc/install) 并设置您的 go 环境。
 接下来，[使用 npm 安装 Node.js](https://nodejs.org/en/download/) ，这是构建
 JavaScript 和 CSS 文件的必要工具。最低支持的 Node.js 版本是 @minNodeVersion@
 并且推荐使用最新的 LTS 版本。
 **注意** ：当执行需要外部工具的 make 任务时，比如
 `make watch-backend`，Gitea 会自动下载并构建这些必要的组件。为了能够使用这些，你必须
 将 `"$GOPATH"/bin` 目录加入到可执行路径上。如果你不把 go bin 目录添加到可执行路径你必须手动
 指定可执行程序路径。
 **注意 2** ：Go 版本 @minGoVersion@ 或更高版本是必须的。Gitea 使用 `gofmt` 来
 格式化源代码。然而，`gofmt` 的结果可能因 `go` 的版本而有差异。因此推荐安装我们持续集成使用
 的 Go 版本。截至上次更新，Go 版本应该是 @goVersion@。
 ## 安装 Make
 Gitea 大量使用 `Make` 来自动化任务和改进开发。本指南涵盖了如何安装 Make。
 ### 在 Linux 上
 使用包管理器安装。
 在 Ubuntu/Debian 上：
 ```bash
 sudo apt-get install make
 ```
 在 Fedora/RHEL/CentOS 上：
 ```bash
 sudo yum install make
 ```
 ### 在 Windows 上
 Make 的这三个发行版都可以在 Windows 上运行：
 - [单个二进制构建](http://www.equation.com/servlet/equation.cmd?fa=make)。复制到某处并添加到 `PATH`。
  - [32 位版本](http://www.equation.com/ftpdir/make/32/make.exe)
  - [64 位版本](http://www.equation.com/ftpdir/make/64/make.exe)
 - [MinGW-w64](https://www.mingw-w64.org) / [MSYS2](https://www.msys2.org/)。
  - MSYS2 是一个工具和库的集合，为您提供一个易于使用的环境来构建、安装和运行本机 Windows 软件，它包括 MinGW-w64。
  - 在 MingGW-w64 中，二进制文件称为 `mingw32-make.exe` 而不是 `make.exe`。将 `bin` 文件夹添加到 `PATH`。
  - 在 MSYS2 中，您可以直接使用 `make`。请参阅 [MSYS2 移植](https://www.msys2.org/wiki/Porting/)。
  - 要使用 CGO_ENABLED（例如：SQLite3）编译 Gitea，您可能需要使用 [tdm-gcc](https://jmeubank.github.io/tdm-gcc/) 而不是 MSYS2 gcc，因为 MSYS2 gcc 标头缺少一些 Windows -只有 CRT 函数像 \_beginthread 一样。
 - [Chocolatey 包管理器](https://chocolatey.org/packages/make)。运行`choco install make`
 **注意** ：如果您尝试在 Windows 命令提示符下使用 make 进行构建，您可能会遇到问题。建议使用上述提示（Git bash 或 MinGW），但是如果您只有命令提示符（或可能是 PowerShell），则可以使用 [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) 命令，例如 `set TAGS=bindata`。
 ## 下载并克隆 Gitea 源代码
 获取源代码的推荐方法是使用 `git clone`。
 ```bash
 git clone https://github.com/go-gitea/gitea
 ```
 （自从 go modules 出现后，不再需要构建 go 项目从 `$GOPATH` 中获取，因此不再推荐使用 `go get` 方法。）
 ## 派生 Gitea
 如上所述下载主要的 Gitea 源代码。然后，派生 [Gitea 仓库](https://github.com/go-gitea/gitea)，
 并为您的本地仓库切换 git 远程源，或添加另一个远程源：
 ```bash
 # 将原来的 Gitea origin 重命名为 upstream
 git remote rename origin upstream
 git remote add origin "git@github.com:$GITHUB_USERNAME/gitea.git"
 git fetch --all --prune
 ```
 或者：
 ```bash
 # 为我们的 fork 添加新的远程
 git remote add "$FORK_NAME" "git@github.com:$GITHUB_USERNAME/gitea.git"
 git fetch --all --prune
 ```
 为了能够创建合并请求，应将分叉存储库添加为 Gitea 本地仓库的远程，否则无法推送更改。
 ## 构建 Gitea（基本）
 看看我们的
 [说明](installation/from-source.md)
 关于如何[从源代码构建](installation/from-source.md) 。
 从源代码构建的最简单推荐方法是：
 ```bash
 TAGS="bindata sqlite sqlite_unlock_notify" make build
 ```
 `build` 目标将同时执行 `frontend` 和 `backend` 子目标。如果存在 `bindata` 标签，资源文件将被编译成二进制文件。建议在进行前端开发时省略 `bindata` 标签，以便实时反映更改。
 有关所有可用的 `make` 目标，请参阅 `make help`。另请参阅 [`.drone.yml`](https://github.com/go-gitea/gitea/blob/main/.drone.yml) 以了解我们的持续集成是如何工作的。
 ## 持续构建
 要在源文件更改时运行并持续构建：
 ```bash
 # 对于前端和后端
 make watch
 # 或者：只看前端文件（html/js/css）
 make watch-frontend
 # 或者：只看后端文件 (go)
 make watch-backend
 ```
 在 macOS 上，监视所有后端源文件可能会达到默认的打开文件限制，这可以通过当前 shell 的 `ulimit -n 12288` 或所有未来 shell 的 shell 启动文件来增加。
 ### 格式化、代码分析和拼写检查
 我们的持续集成将拒绝未通过代码检查（包括格式检查、代码分析和拼写检查）的 PR。
 你应该格式化你的代码：
 ```bash
 make fmt
 ```
 并检查源代码：
 ```bash
 # lint 前端和后端代码
 make lint
 # 仅 lint 后端代码
 make lint-backend
 ```
 **注意** ：`gofmt` 的结果取决于 `go` 的版本。您应该运行与持续集成相同的 go 版本。
 ### 处理 JS 和 CSS
 前端开发应遵循 [Guidelines for Frontend Development](contributing/guidelines-frontend.md)。
 要使用前端资源构建，请使用上面提到的“watch-frontend”目标或只构建一次：
 ```bash
 make build && ./gitea
 ```
 在提交之前，确保 linters 通过：
 ```bash
 make lint-frontend
 ```
 ### 配置本地 ElasticSearch 实例
 使用 docker 启动本地 ElasticSearch 实例：
 ```sh
 mkdir -p $(pwd) /data/elasticsearch
 sudo chown -R 1000:1000 $(pwd) /data/elasticsearch
 docker run --rm --memory= "4g" -p 127.0.0.1:9200:9200 -p 127.0.0.1:9300:9300 -e "discovery.type=single-node" -v "$(pwd)/data /elasticsearch:/usr/share/elasticsearch/data" docker.elastic.co/elasticsearch/elasticsearch:7.16.3
 ```
 配置`app.ini`：
 ```ini
 [indexer]
 ISSUE_INDEXER_TYPE = elasticsearch
 ISSUE_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
 REPO_INDEXER_ENABLED = true
 REPO_INDEXER_TYPE = elasticsearch
 REPO_INDEXER_CONN_STR = http://elastic:changeme@localhost:9200
 ```
 ### 构建和添加 SVGs
 SVG 图标是使用 `make svg` 命令构建的，该命令将图标资源编译到输出目录 `public/assets/img/svg` 中。可以在 `web_src/svg` 目录中添加自定义图标。
 ### 构建 Logo
 Gitea Logo 的 PNG 和 SVG 版本是使用 `TAGS="gitea" make generate-images` 目标从单个 SVG 源文件 assets/logo.svg 构建的。要运行它，Node.js 和 npm 必须可用。
 通过更新 `assets/logo.svg` 并运行 `make generate-images`，同样的过程也可用于从 SVG 源文件生成自定义 Logo PNG。忽略 gitea 编译选项将仅更新用户指定的 LOGO 文件。
 ### 更新 API
 创建新的 API 路由或修改现有的 API 路由时，您**必须**
 更新和/或创建 [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)
 这些使用 [go-swagger](https://goswagger.io/) 评论的文档。
 [规范](https://goswagger.io/use/spec.html#annotation-syntax)中描述了这些注释的结构。
 如果您想了解更多有关 Swagger 结构的信息，可以查看
 [Swagger 2.0 文档](https://swagger.io/docs/specification/2-0/basic-structure/)
 或与添加新 API 端点的先前 PR 进行比较，例如 [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
 您应该注意不要破坏下游用户依赖的 API。在稳定的 API 上，一般来说添加是可以接受的，但删除
 或对 API 进行根本性更改将会被拒绝。
 创建或更改 API 端点后，请用以下命令重新生成 Swagger 文档：
 ```bash
 make generate-swagger
 ```
 您应该验证生成的 Swagger 文件：
 ```bash
 make swagger-validate
 ```
 您应该提交更改后的 swagger JSON 文件。持续集成服务器将使用以下方法检查是否已完成：
 ```bash
 make swagger-check
 ```
 **注意** ：请注意，您应该使用 Swagger 2.0 文档，而不是 OpenAPI 3 文档。
 ### 创建新的配置选项
 创建新的配置选项时，将它们添加到 `modules/setting` 的对应文件。您应该将信息添加到 `custom/conf/app.ini`
 并到[配置备忘单](../administration/config-cheat-sheet.md)
 在 `docs/content/doc/advanced/config-cheat-sheet.zh-cn.md` 中找到
 ### 更改 Logo
 更改 Gitea Logo SVG 时，您将需要运行并提交结果的：
 ```bash
 make generate-images
 ```
 这将创建必要的 Gitea 图标和其他图标。
 ### 数据库迁移
 如果您对数据库中的任何数据库持久结构进行重大更改
 `models/` 目录，您将需要进行新的迁移。可以找到这些
 在 `models/migrations/` 中。您可以确保您的迁移适用于主要
 数据库类型使用：
 ```bash
 make test-sqlite-migration # 将 SQLite 切换为适当的数据库
 ```
 ## 测试
 Gitea 运行两种类型的测试：单元测试和集成测试。
 ### 单元测试
 `go test` 系统中的`*_test.go` 涵盖了单元测试。
 您可以设置环境变量 `GITEA_UNIT_TESTS_LOG_SQL=1` 以在详细模式下运行测试时显示所有 SQL 语句（即设置`GOTESTFLAGS=-v` 时）。
 ```bash
 TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
 ```
 ### 集成测试
 单元测试不会也不能完全单独测试 Gitea。因此，我们编写了集成测试；但是，这些依赖于数据库。
 ```bash
 TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
 ```
 将在 SQLite 环境中运行集成测试。集成测试需要安装 `git lfs`。其他数据库测试可用，但
 可能需要适应当地环境。
 看看 [`tests/integration/README.md`](https://github.com/go-gitea/gitea/blob/main/tests/integration/README.md) 有关更多信息以及如何运行单个测试。
 ### 测试 PR
 我们的持续集成将测试代码是否通过了单元测试，并且所有支持的数据库都将在 Docker 环境中通过集成测试。
 还将测试从几个最新版本的 Gitea 迁移。
 请在 PR 中附带提交适当的单元测试和集成测试。
 ## 网站文档
 该网站的文档位于 `docs/` 中。如果你改变了文档内容，你可以使用以下测试方法进行持续集成：
 ```bash
 make lint-md
 ```
 ## Visual Studio Code
 `contrib/ide/vscode` 中为 Visual Studio Code 提供了 `launch.json` 和 `tasks.json`。查看
 [`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/main/contrib/ide/README.md) 了解更多信息。
 ## Goland
 单击 `/main.go` 中函数 `func main()` 上的 `Run Application` 箭头
 可以快速启动一个可调试的 Gitea 实例。
 `Run/Debug Configuration` 中的 `Output Directory` 必须设置为
 gitea 项目目录（包含 `main.go` 和 `go.mod`），
 否则，启动实例的工作目录是 GoLand 的临时目录
 并防止 Gitea 在开发环境中加载动态资源（例如：模板）。
 要在 GoLand 中使用 SQLite 运行单元测试，请设置 `-tags sqlite,sqlite_unlock_notify`
 在 `运行/调试配置` 的 `Go 工具参数` 中。
 ## 提交 PR
 对更改感到满意后，将它们推送并打开拉取请求。它建议您允许 Gitea Managers 和 Owners 修改您的 PR
 分支，因为我们需要在合并之前将其更新为 main 和/或可能是能够直接帮助解决问题。
 任何 PR 都需要 Gitea 维护者的两次批准，并且需要通过持续集成。看看我们的
 [CONTRIBUTING.md](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md)
 文档。
 如果您需要更多帮助，请访问 [Discord](https://discord.gg/gitea) #Develop 频道
 并在那里聊天。
 现在，您已准备好 Hacking Gitea。
@@ -1,37 +0,0 @@
 ---
 date: "2023-05-25T17:29:00+08:00"
 slug: "integrations"
 sidebar_position: 65
 aliases:
  - /zh-cn/integrations
 ---
 # 集成
 Gitea 拥有一个出色的第三方集成社区，以及在其他各种项目中的一流支持。
 我们正在[awesome-gitea](https://gitea.com/gitea/awesome-gitea)上整理一个列表来跟踪这些集成！
 如果你正在寻找[CI/CD](https://gitea.com/gitea/awesome-gitea#user-content-devops)，
 一个[SDK](https://gitea.com/gitea/awesome-gitea#user-content-sdk)，
 甚至一些额外的[主题](https://gitea.com/gitea/awesome-gitea#user-content-themes)，
 你可以在[awesome-gitea](https://gitea.com/gitea/awesome-gitea)中找到它们的列表！
 ## 预填新文件名和内容
 如果你想打开一个具有给定名称和内容的新文件，
 你可以使用查询参数来实现：
 ```txt
 GET /{{org}}/{{repo}}/_new/{{filepath}}
    ?filename={{filename}}
    &value={{content}}
 ```
 例如：
 ```txt
 GET https://git.example.com/johndoe/bliss/_new/articles/
    ?filename=hello-world.md
    &value=Hello%2C%20World!
 ```
@@ -1,31 +0,0 @@
 ---
 date: "2023-05-25T17:29:00+08:00"
 slug: "migrations-interfaces"
 sidebar_position: 55
 aliases:
  - /zh-cn/migrations-interfaces
 ---
 # 迁移接口
 完整迁移功能在 Gitea 1.9.0 版本中引入。它定义了两个接口，用于支持从其他 Git 托管平台迁移存储库数据到 Gitea，或者在将来将 Gitea 数据迁移到其他 Git 托管平台。
 目前已实现了从 GitHub、GitLab 和其他 Gitea 实例的迁移。
 首先，Gitea 在包[modules/migration](https://github.com/go-gitea/gitea/tree/main/modules/migration)中定义了一些标准对象。它们是`Repository`、`Milestone`、`Release`、`ReleaseAsset`、`Label`、`Issue`、`Comment`、`PullRequest`、`Reaction`、`Review`、`ReviewComment`。
 ## 下载器接口
 要从新的 Git 托管平台迁移，需要进行两个步骤的更新。
 - 您应该实现一个`Downloader`，用于获取存储库信息。
 - 您应该实现一个`DownloaderFactory`，用于检测 URL 是否匹配，并创建上述的`Downloader`。
  - 您需要在`init()`中通过`RegisterDownloaderFactory`注册`DownloaderFactory`。
 您可以在[downloader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/downloader.go)中找到这些接口。
 ## 上传器接口
 目前，只实现了`GiteaLocalUploader`，因此我们只能通过此 Uploader 将下载的数据保存到本地的 Gitea 实例。目前不支持其他上传器。
 您可以在[uploader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/uploader.go)中找到这些接口。
Author	SHA1	Message	Date
Lunny Xiao	fecad73221	ci: only read the Depends on lines, and let the label be the gate	2026-09-08 12:03:59 -07:00
Lunny Xiao	83cbd0138f	ci: keep the jq expressions parsable on jq 1.6	2026-09-08 12:00:37 -07:00
Lunny Xiao	3fb4de8560	ci: run the check with the script from the pull request	2026-09-08 11:58:23 -07:00
Lunny Xiao	7d4c23de0b	ci: fail a pull request that waits for an unmerged gitea change	2026-09-08 11:50:21 -07:00