add artifact preview

update to 1.27.3 (#532 )
Preview: https://pr-532.docs-gitea-com.pages.dev Reviewed-on: https://gitea.com/gitea/docs/pulls/532 Reviewed-by: bircni <[email protected]> Co-authored-by: Lunny Xiao <[email protected]>
2026-11-12 12:54:12 +00:00 · 2026-08-30 14:23:03 +02:00 · 2026-08-29 19:59:27 +00:00 · 2026-08-27 05:11:05 +00:00 · 2026-08-25 17:33:20 +00:00 · 2026-08-24 17:16:30 +00:00
2042 changed files with 211011 additions and 86555 deletions
@@ -1,5 +1,5 @@
 name: Build and Publish Docs site
-run-name: docusaurus build docs site
+run-name: astro build docs site
 on:
  push:
@@ -8,41 +8,41 @@ on:
 jobs:
  build-docs:
-    runs-on: ubuntu-22.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
      # to pagefind otherwise
      PUBLIC_DOCSEARCH_APP_ID: ${{ secrets.DOCSEARCH_APP_ID }}
      PUBLIC_DOCSEARCH_API_KEY: ${{ secrets.DOCSEARCH_API_KEY }}
      PUBLIC_DOCSEARCH_INDEX_NAME: ${{ secrets.DOCSEARCH_INDEX_NAME }}
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-node@v4
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
-          node-version: 20
+          node-version: 24
-          cache: npm
+          cache: pnpm
      - name: install necessary tools
        run: |
          apt update -y && apt install -y rsync python3 python3-pip python-is-python3
          pip install awscli
      - name: prepare awesome list
        run: |
-          make prepare-awesome-latest prepare-awesome\#23 prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
+          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
      - name: Cache ~/.npm for npm ci
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: ${{ runner.os }}-node
      - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
      #- uses: tats-u/docuactions-cache@v1
      - name: build site
        run: make build
      - name: Copy files to Cloudflare Pages
        env:
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
-          make build
+          # cloudflare/_headers and cloudflare/_redirects are only meaningful for
-      - name: aws credential configure
+          # the Cloudflare Pages deployment, so they are copied into the build
-        uses: aws-actions/configure-aws-credentials@v4
+          # right before the deploy.
-        with:
+          cp cloudflare/_headers sites/docs/dist/_headers
-          aws-access-key-id: ${{ secrets.AWS_KEY_ID }}
+          cp cloudflare/_redirects sites/docs/dist/_redirects
-          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}
+          test -f sites/docs/dist/_headers -a -f sites/docs/dist/_redirects || exit 1
-          aws-region: ${{ secrets.AWS_REGION}}
+          pnpm dlx wrangler@4 pages deploy sites/docs/dist \
-      - name: Copy files to the production website with the AWS CLI
+            --project-name docs-gitea-com \
-        run: |
+            --branch main
          aws s3 sync build/ s3://docs-gitea-com
          aws cloudfront create-invalidation --distribution-id ${{ secrets.AWS_DISTRIBUTION}} --paths '/*'
@@ -0,0 +1,68 @@
 name: cleanup preview
 on:
  pull_request:
    types:
      - closed
 # make sure two closing events for the same pull request do not delete the same
 # deployment twice
 concurrency:
  group: cleanup-preview-${{ github.event.pull_request.number }}
 jobs:
  cleanup-preview:
    runs-on: ubuntu-latest
    steps:
      - name: delete the Cloudflare Pages preview deployments
        env:
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          set -euo pipefail
          # pull requests from forks do not get the secrets, nothing was
          # deployed for them either
          if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
            echo "no Cloudflare credentials available, skipping the preview cleanup"
            exit 0
          fi
          project=docs-gitea-com
          branch="pr-$PR_NUMBER"
          api="https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/pages/projects/$project/deployments"
          page=1
          ids=""
          while true; do
            curl --silent --show-error --fail --output deployments.json \
              -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
              "$api?per_page=100&page=$page"
            found="$(jq -r --arg branch "$branch" \
              '.result[] | select(.deployment_trigger.metadata.branch == $branch) | .id' deployments.json)"
            if [ -n "$found" ]; then
              ids="$ids$found"$'\n'
            fi
            # the API returns an empty result once the last page is passed
            [ "$(jq -r '.result | length' deployments.json)" -eq 100 ] || break
            page=$((page + 1))
          done
          if [ -z "$(printf '%s' "$ids" | tr -d '[:space:]')" ]; then
            echo "no preview deployment found for $branch"
            exit 0
          fi
          # force=true also removes the deployment the branch alias points at
          printf '%s' "$ids" | while read -r id; do
            [ -n "$id" ] || continue
            echo "deleting the deployment $id of $branch"
            curl --silent --show-error --fail --output /dev/null \
              -X DELETE "$api/$id?force=true" \
              -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
          done
          echo "the preview of $branch is gone"
@@ -3,29 +3,101 @@ name: checks
 on:
  - pull_request
 # a new push to the same pull request replaces the running preview build
 concurrency:
  group: checks-${{ github.event.pull_request.number }}
  cancel-in-progress: true
 jobs:
  build-docs:
    runs-on: ubuntu-latest
    env:
      NODE_OPTIONS: --max-old-space-size=8192
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-node@v4
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
-          node-version: 20
+          node-version: 24
-          cache: npm
+          cache: pnpm
      - name: prepare awesome list
        run: |
-          make prepare-awesome-latest prepare-awesome\#23 prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
+          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
      - name: Cache ~/.npm for npm ci
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: ${{ runner.os }}-node
-      - name: Install dependencies
+      - name: install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
      #- uses: tats-u/docuactions-cache@v1
      - name: build site
        run: make build
      - name: type check
        run: make check
      - name: deploy the preview to Cloudflare Pages
        id: preview
        env:
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
-          make build
+          set -euo pipefail
          # pull requests from forks do not get the secrets, the build above is
          # then the only check and the preview is silently skipped
          if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
            echo "no Cloudflare credentials available, skipping the preview deployment"
            exit 0
          fi
          # same as the production deployment: _headers and _redirects only
          # belong to the Cloudflare Pages output, so they are copied in right
          # before uploading
          cp cloudflare/_headers sites/docs/dist/_headers
          cp cloudflare/_redirects sites/docs/dist/_redirects
          pnpm dlx wrangler@4 pages deploy sites/docs/dist \
            --project-name docs-gitea-com \
            --branch "pr-$PR_NUMBER" | tee wrangler.log
          url="$(grep -Eo 'https://[A-Za-z0-9.-]+\.pages\.dev' wrangler.log | tail -n 1)"
          if [ -z "$url" ]; then
            echo "could not read the preview URL from the wrangler output"
            exit 1
          fi
          echo "url=$url" >> "$GITHUB_OUTPUT"
      - name: update the pull request with the preview URL
        if: steps.preview.outputs.url != ''
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
          PREVIEW_URL: ${{ steps.preview.outputs.url }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          set -euo pipefail
          if [ -z "${DEPLOY_TOKEN:-}" ]; then
            echo "secrets.DEPLOY_TOKEN is missing, the preview is at $PREVIEW_URL"
            exit 0
          fi
          api="${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER"
          curl --silent --show-error --fail --output pull.json \
            -H "Authorization: token $DEPLOY_TOKEN" "$api"
          marker='<!-- cloudflare-preview -->'
          # drop the line written by an earlier run, so the URL is updated in
          # place instead of piling up at the end of the description
          body="$(jq -r '.body // ""' pull.json | grep -vF "$marker" || true)"
          body="$(printf '%s\n' "$body" | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}')"
          if [ -n "$body" ]; then
            body="$(printf '%s\n\n%s Preview: %s\n' "$body" "$marker" "$PREVIEW_URL")"
          else
            body="$(printf '%s Preview: %s\n' "$marker" "$PREVIEW_URL")"
          fi
          jq -n --arg body "$body" '{body: $body}' > patch.json
          curl --silent --show-error --fail --output /dev/null \
            -X PATCH "$api" \
            -H "Authorization: token $DEPLOY_TOKEN" \
            -H 'Content-Type: application/json' \
            --data @patch.json
          echo "the pull request now points at $PREVIEW_URL"
@@ -0,0 +1,109 @@
 name: update runner reference
 on:
  schedule:
    - cron: '30 3 * * 1' # every Monday at 03:30
  workflow_dispatch:
 env:
  # main is protected, so the update is proposed as a pull request from this branch
  BOT_BRANCH: bot/update-runner-reference
  BASE_BRANCH: main
  # the develop runner docs follow the main branch of gitea/runner, every
  # documented release series follows its newest stable tag. The value is used
  # unquoted, so the glob is expanded by the shell of each step.
  TARGET_DIRS: runner-docs/reference runner-docs_versioned_docs/version-*/reference
 jobs:
  update-runner-reference:
    if: github.repository == 'gitea/docs'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          ref: main
          # pushing uses DEPLOY_TOKEN, keep the ephemeral job token out of .git/config
          persist-credentials: false
      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
        with:
          go-version: 'stable'
          cache: false
      - name: regenerate the runner reference pages
        run: |
          set -euo pipefail
          ./update_runner_docs.sh main runner-docs/reference
          ./update_runner_docs.sh --released
      - name: verify the generated files
        run: |
          set -euo pipefail
          # the pages are built from `--help` and `generate-config`, so a truncated
          # build would silently produce an almost empty page
          for dir in $TARGET_DIRS; do
            echo "checking $dir"
            grep -q 'gitea-runner \[command\]' "$dir/cli.md"
            grep -q 'gitea-runner exec \[flags\]' "$dir/cli.md"
            grep -q '^runner:' "$dir/config-example.md"
          done
      - name: push bot branch
        id: bot_branch
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          set -euo pipefail
          if git diff --quiet -- $TARGET_DIRS; then
            echo "the runner reference is already up to date"
            echo "changed=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          if [ -z "$DEPLOY_TOKEN" ]; then
            echo "secrets.DEPLOY_TOKEN is missing, cannot push the update"
            exit 1
          fi
          remote="https://x-access-token:$DEPLOY_TOKEN@${GITHUB_SERVER_URL#*://}/$GITHUB_REPOSITORY.git"
          # skip if an open bot branch already carries exactly these files
          if git fetch --quiet --depth=1 "$remote" "refs/heads/$BOT_BRANCH" 2>/dev/null; then
            if git diff --quiet FETCH_HEAD -- $TARGET_DIRS; then
              echo "$BOT_BRANCH already proposes this runner reference"
              echo "changed=false" >> "$GITHUB_OUTPUT"
              exit 0
            fi
          fi
          git config user.name "Gitea Bot"
          git config user.email "[email protected]"
          git switch --create "$BOT_BRANCH"
          git add $TARGET_DIRS
          git commit -m "Update the runner reference pages"
          # force push: the branch is always rebuilt on top of the current main
          git push --force "$remote" "HEAD:refs/heads/$BOT_BRANCH"
          echo "changed=true" >> "$GITHUB_OUTPUT"
      - name: create pull request
        if: steps.bot_branch.outputs.changed == 'true'
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          set -euo pipefail
          cat > pull.json <<EOF
          {
            "base": "$BASE_BRANCH",
            "head": "$BOT_BRANCH",
            "title": "Update the runner reference pages",
            "body": "Automated update of the generated runner reference pages from gitea/runner (main for the develop docs, the newest stable tag for every documented series), opened by the \"update runner reference\" scheduled workflow."
          }
          EOF
          code="$(curl --silent --show-error --output pull-response.json --write-out '%{http_code}' \
            -X POST "${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY/pulls" \
            -H "Authorization: token $DEPLOY_TOKEN" \
            -H 'Content-Type: application/json' \
            --data @pull.json)"
          case "$code" in
            201) echo "pull request created" ;;
            409) echo "an open pull request for $BOT_BRANCH already exists, it now points at the new commit" ;;
            *) echo "unexpected response $code:"; cat pull-response.json; exit 1 ;;
          esac
@@ -1,36 +1,110 @@
-name: update swagger files
+name: update api spec files
 on:
  schedule:
    - cron:  '0 */12 * * *' # every 12 hours on the hour
  workflow_dispatch:
 env:
  # main is protected, so the update is proposed as a pull request from this branch
  BOT_BRANCH: bot/update-swagger-latest
  BASE_BRANCH: main
  # the documents of the gitea main branch, refreshed by this job
  LATEST_FILES: static/swagger-latest.json static/openapi3-latest.json
 jobs:
  update-swagger:
    if: github.repository == 'gitea/docs'
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - run: |
+        with:
-          wget https://raw.githubusercontent.com/go-gitea/gitea/refs/heads/main/templates/swagger/v1_json.tmpl
+          ref: main
-          sed -i "$@" 's\"version": "{{AppVer | JSEscape}}"\"version": "dev"\' v1_json.tmpl
+          # pushing uses DEPLOY_TOKEN, keep the ephemeral job token out of .git/config
-          sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
+          persist-credentials: false
-          mv v1_json.tmpl static/swagger-latest.json
+      - name: regenerate the latest api documents
-
+        run: make update-api-docs-latest
-          for ver in '1.24.0-rc0' '1.23.8' '1.22.6' '1.21.11' '1.20.6' '1.19.4'; do
+      - name: verify the generated file
-            wget https://raw.githubusercontent.com/go-gitea/gitea/refs/tags/v${ver}/templates/swagger/v1_json.tmpl
+        run: |
-            sed -i "$@" "s|\"version\": \"{{AppVer \| JSEscape}}\"|\"version\": \"${ver}\"|" v1_json.tmpl
+          set -euo pipefail
-            sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
+          for file in $LATEST_FILES; do
-            # for version < 1.21.11
+            # placeholders must have been replaced, otherwise upstream changed them again
-            sed -i "$@" "s|\"version\": \"{{AppVer \| JSEscape \| Safe}}\"|\"version\": \"${ver}\"|" v1_json.tmpl
+            if grep -q -e 'GITEA-API-APP' -e '{{' "$file"; then
-            sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape | Safe}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
+              echo "$file still contains template placeholders"
-            minor=$(echo "$ver" | cut -d '.' -f 2)
+              exit 1
-            mv v1_json.tmpl static/swagger-$minor.json
+            fi
            if command -v python3 >/dev/null 2>&1; then
              python3 -c "import json,sys; json.load(open(sys.argv[1]))" "$file"
            fi
          done
      - name: push bot branch
        id: bot_branch
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          set -euo pipefail
-          if ! [[ $(git diff --shortstat) ]]; then exit 0; fi
+          if git diff --quiet -- $LATEST_FILES; then
-          git config --global user.name "Gitea Bot"
+            echo "the api documents are already up to date"
-          git config --global user.email "[email protected]"
+            echo "changed=false" >> "$GITHUB_OUTPUT"
-          git remote set-url origin https://x-access-token:${{ secrets.DEPLOY_TOKEN }}@gitea.com/gitea/docs.git
+            exit 0
-          git add --all
+          fi
-          git commit -m "[skip ci] Updated swagger files"
+
-          git push
+          if [ -z "$DEPLOY_TOKEN" ]; then
            echo "secrets.DEPLOY_TOKEN is missing, cannot push the update"
            exit 1
          fi
          remote="https://x-access-token:$DEPLOY_TOKEN@${GITHUB_SERVER_URL#*://}/$GITHUB_REPOSITORY.git"
          # skip if an open bot branch already carries exactly this file
          if git fetch --quiet --depth=1 "$remote" "refs/heads/$BOT_BRANCH" 2>/dev/null; then
            same=true
            for file in $LATEST_FILES; do
              old_blob="$(git rev-parse --quiet --verify "FETCH_HEAD:$file" || true)"
              if [ "$old_blob" != "$(git hash-object "$file")" ]; then
                same=false
                break
              fi
            done
            if [ "$same" = true ]; then
              echo "$BOT_BRANCH already proposes these api documents"
              echo "changed=false" >> "$GITHUB_OUTPUT"
              exit 0
            fi
          fi
          git config user.name "Gitea Bot"
          git config user.email "[email protected]"
          git switch --create "$BOT_BRANCH"
          git add $LATEST_FILES
          git commit -m "Update the latest api documents"
          # force push: the branch is always rebuilt on top of the current main
          git push --force "$remote" "HEAD:refs/heads/$BOT_BRANCH"
          echo "changed=true" >> "$GITHUB_OUTPUT"
      - name: create pull request
        if: steps.bot_branch.outputs.changed == 'true'
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
        run: |
          set -euo pipefail
          cat > pull.json <<EOF
          {
            "base": "$BASE_BRANCH",
            "head": "$BOT_BRANCH",
            "title": "Update the latest api documents",
            "body": "Automated update of static/swagger-latest.json and static/openapi3-latest.json from the gitea main branch, opened by the \"update api spec files\" scheduled workflow."
          }
          EOF
          code="$(curl --silent --show-error --output pull-response.json --write-out '%{http_code}' \
            -X POST "${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY/pulls" \
            -H "Authorization: token $DEPLOY_TOKEN" \
            -H 'Content-Type: application/json' \
            --data @pull.json)"
          case "$code" in
            201) echo "pull request created" ;;
            409) echo "an open pull request for $BOT_BRANCH already exists, it now points at the new commit" ;;
            *) echo "unexpected response $code:"; cat pull-response.json; exit 1 ;;
          esac
@@ -1,12 +1,12 @@
 # Dependencies
-/node_modules
+node_modules
-# Production
+# Build output
-/build
+sites/*/dist
-
+sites/*/.astro
-# Generated files
+sites/*/.cache
-.docusaurus
+build/
-.cache-loader
+.docusaurus/
 # Misc
 .DS_Store
@@ -20,4 +20,5 @@ yarn-debug.log*
 yarn-error.log*
 .tmp/
 awesome/
 awesome.md
@@ -1,5 +0,0 @@
 audit=false
 fund=false
 update-notifier=false
 package-lock=true
 lockfile-version=3
@@ -1,5 +1,3 @@
 export NODE_OPTIONS := "--max-old-space-size=8192"
 GITEA_AWESOME_REMOTE := https://gitea.com/gitea/awesome-gitea.git
 GITEA_AWESOME_BRANCH := main
@@ -8,7 +6,7 @@ all: build
 .PHONY: create_dir
 create_dir:
-	mkdir -p .tmp awesome
+	mkdir -p .tmp
 .PHONY: clone_awesome
 clone_awesome: create_dir
@@ -24,31 +22,69 @@ prepare-awesome\#%:
 .PHONY: install
 install:
-	npm install
+	pnpm install
 .PHONY: prepare-docs
-prepare-docs: install prepare-awesome-latest prepare-awesome\#19 prepare-awesome\#20 prepare-awesome\#21 prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24
+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:
-	npm run build
+	pnpm run build
 # type checks the astro site and its components
 .PHONY: check
 check:
 	pnpm run check
 .PHONY: serve
 serve: prepare-docs
-	npm run start
+	pnpm run dev
-.PHONY: serve-zh
+# only the english docs of the version served at the root, plus the runner:
-serve-zh: prepare-docs
+# starts in a few seconds instead of loading the whole matrix
-	npm run start -- --locale zh-cn
+.PHONY: serve-fast
 serve-fast:
 	pnpm run dev:en-latest
 # search is built by pagefind at build time, so it is only available on the
 # built site; this serves it locally
 .PHONY: serve-built
 serve-built: build
 	pnpm run preview
 .PHONY: clean
 clean:
 	rm -rf .tmp
-	rm -rf static/_*
+	rm -rf sites/docs/dist
-	rm -rf static/swagger-latest.json
+	rm -rf sites/docs/.cache
-	rm -rf static/swagger-19.json
+	rm -rf sites/docs/node_modules/.astro
-	rm -rf static/swagger-20.json
+
-	rm -rf static/swagger-21.json
+# static/swagger-*.json and static/openapi3-*.json are committed files, use
-	rm -rf static/swagger-22.json
+# update-api-docs to refresh them
-	rm -rf static/swagger-23.json
+.PHONY: update-api-docs
-	rm -rf static/swagger-24.json
+update-api-docs:
 	./update_api_docs.sh
 # only refresh the documents of the gitea main branch (used by the cron job)
 .PHONY: update-api-docs-latest
 update-api-docs-latest:
 	./update_api_docs.sh --latest-only
 # regenerate the generated runner reference pages of the develop docs from the
 # main branch of gitea/runner (used by the update runner reference cron job)
 .PHONY: update-runner-docs
 update-runner-docs:
 	./update_runner_docs.sh main runner-docs/reference
 # same, for every documented release series: the tags are looked up through the
 # Gitea API, so a runner release needs no change here
 .PHONY: update-runner-docs-released
 update-runner-docs-released:
 	./update_runner_docs.sh --released
 # freezes the current docs or runner tree as a new version, see
 # scripts/cut-version.mjs
 .PHONY: cut-version
 cut-version:
 	@test -n "$(PRODUCT)" -a -n "$(VERSION)" || { echo 'usage: make cut-version PRODUCT=docs VERSION=1.28'; exit 1; }
 	node scripts/cut-version.mjs $(PRODUCT) $(VERSION)
@@ -1,23 +1,126 @@
 # Gitea Docs ![badge](https://gitea.com/gitea/docs/actions/workflows/build-and-publish.yaml/badge.svg)
-## How to build
+The sources of [docs.gitea.com](https://docs.gitea.com), built with
 [Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
-```shell
+The site covers three products, all served from this repository:
-make clean
+
-make prepare-docs
+| Product | Content | Versions | Languages |
-make build
+| --- | --- | --- | --- |
-```
+| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 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, 3 … 0 | English |
 The enterprise documentation is built and deployed from its own repository and
 reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere
 routes to that deployment.
 ## Development
 ```shell
-make clean
+make install       # pnpm install
-make prepare-docs
+make serve-fast    # english, the version served at the root, starts in seconds
-make serve
+make serve         # the whole matrix, every version and language
 make build         # production build into sites/docs/dist
 make check         # type checks the site and its components
 ```
-## Test en version
+Search is built by Pagefind while the site is built, so it only answers on the
 built site: use `make serve-built` to try it. With the Algolia credentials
 (`PUBLIC_DOCSEARCH_APP_ID`, `PUBLIC_DOCSEARCH_API_KEY`) set, DocSearch is used
 instead and works in `make serve` too.
 `GITEA_DOCS_PRODUCTS`, `GITEA_DOCS_VERSIONS` and `GITEA_DOCS_LOCALES` (comma
 separated) restrict what is built, which is what `make serve-fast` uses.
 `GITEA_DOCS_STRICT_LINKS=true` turns the warnings about unresolved relative
 markdown links into a build error.
 `sites/docs/README.md` documents how the sources are mapped onto the site.
 ## Writing
 Pages are plain markdown with the same frontmatter and admonitions as before:
 frontmatter `slug`, `sidebar_position` and `sidebar_label` keep working, and so
 do the `:::note` style admonitions and the `@version@` style release variables.
 Relative `*.md` links are rewritten to urls while the site is built.
 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.
 ## Cutting a version
 ```shell
-npm run start
+make cut-version PRODUCT=docs VERSION=1.28
 make cut-version PRODUCT=runner VERSION=4
 ```
 This freezes the current tree, its translations and its sidebar. The label of
 the version, its release variables (`@version@`, `@dockerVersion@`, ...) and
 which version is served at the root live in
 `packages/content-loader/src/products.ts` and are edited by hand afterwards.
 That file is the single source of truth for the product, version and language
 matrix.
 ## API docs
 The definitions rendered under `/api/` live in `static/`:
 `swagger-latest.json` (gitea main) and `swagger-<minor>.json` (released
 versions) hold the swagger 2.0 document every gitea version ships,
 `openapi3-latest.json` and `openapi3-<minor>.json` the openapi 3.0 document
 gitea generates since 1.27. The openapi 3.0 document is what gets rendered
 where it exists, and both are offered for download on the overview page of the
 version, since code generators cannot read the rendered pages (and several of
 them reject swagger 2.0).
 ```shell
 make update-api-docs         # refresh latest + every released version
 make update-api-docs-latest  # refresh only the documents of gitea main
 ```
 The documents of gitea main are refreshed automatically: the `update api spec
 files` workflow runs every 12 hours and opens a pull request whenever gitea main
 changed. Released versions are updated by hand when a new gitea version is
 documented.
 ## Runner docs
 | Version | Content | URL |
 | --- | --- | --- |
 | develop | `runner-docs/` | `/runner/develop/` |
 | current series | `runner-docs_versioned_docs/version-3/` | `/runner/` |
 | 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
 folder. Use floating image tags (`gitea/runner:3`) and links to the runner's
 `main` branch in those pages to keep them valid across patch releases.
 Its sidebar is written by hand: `runner-sidebars.js` for develop, and
 `runner-docs_versioned_sidebars/version-<version>-sidebars.json` per documented
 version.
 The pages under `reference/` are generated from the runner sources — the command
 line reference from `--help`, the example configuration from `generate-config`:
 ```shell
 make update-runner-docs           # develop docs, from the main branch of gitea/runner
 make update-runner-docs-released  # every series, from its newest stable tag
 ./update_runner_docs.sh v3.0.2 runner-docs_versioned_docs/version-3/reference
 ```
 These are refreshed automatically as well: the `update runner reference`
 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.
 ## Deployment
 `main` is built and published by the `Build and Publish Docs site` workflow, to
 S3/CloudFront and to Cloudflare Pages. `cloudflare/_headers` sets the cache
 policy and `cloudflare/_redirects` keeps the urls the site used to serve; both
 are copied next to the build output by that workflow.
 `cloudflare/docsearch-crawler.json` is the Algolia crawler configuration.
 `/enterprise/` is served by another deployment and routed to it by a Cloudflare
 worker that lives outside this repository.
@@ -1,3 +0,0 @@
 module.exports = {
  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
 };
@@ -0,0 +1,24 @@
 # Cloudflare Pages reads this file from the root of the deployed directory. It
 # is copied into the build output by the publish workflow, so that it is not
 # uploaded to S3/CloudFront where it would be publicly readable at /_headers.
 #
 # Unlike the docusaurus build, astro emits a single content hashed asset
 # 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.
 /_astro/*
  Cache-Control: public, max-age=31536000, immutable
 # Files under public/img and public/images keep stable names and are replaced in
 # place, so they get a short, conservative max-age instead.
 /img/*
  Cache-Control: public, max-age=86400
 /images/*
  Cache-Control: public, max-age=86400
 # The pagefind index, only present when the site is built without algolia
 # docsearch. Content hashed as well.
 /pagefind/*
  Cache-Control: public, max-age=31536000, immutable
@@ -0,0 +1,458 @@
 # Redirects for legacy URLs and routes the site no longer serves directly.
 # The api reference and the runner docs are separate products, published in
 # english only. Docusaurus served an empty localized copy of them.
 /zh-cn/api/* /api/:splat 301
 /zh-tw/api/* /api/:splat 301
 /zh-cn/runner/* /runner/:splat 301
 /zh-tw/runner/* /runner/: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/1.27/* /api/:splat 301
 /runner/3/* /runner/: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.
 /search /  301
 /zh-cn/search /zh-cn/ 301
 /zh-tw/search /zh-tw/ 301
 # Pages that moved when the docs were reorganized: the flat `/usage/webhooks`,
 # `/advanced/...` and `/developers/...` layout of 1.19 and 1.20, and
 # `/help/seek-help`. Those urls kept working until the site moved to Cloudflare
 # because it was published with `aws s3 sync` without `--delete`, so the pages
 # built before the move were never removed from the bucket. Only what the build
 # emits is served now, and gitea itself and blog.gitea.com still link to some of
 # them, so they are redirected here.
 /actions                                          /usage/actions/ 301
 /actions/                                         /usage/actions/ 301
 /administration                                   /category/administration/ 301
 /administration/                                  /category/administration/ 301
 /administration/logging-configuration             /administration/logging-config/ 301
 /advanced/adding-legal-pages                      /administration/adding-legal-pages/ 301
 /advanced/clone-filters                           /usage/repository/clone-filters/ 301
 /advanced/cmd-embedded                            /administration/cmd-embedded/ 301
 /advanced/config-cheat-sheet                      /administration/config-cheat-sheet/ 301
 /advanced/customizing-gitea                       /administration/customizing-gitea/ 301
 /advanced/environment-variables                   /administration/environment-variables/ 301
 /advanced/external-renderers                      /administration/external-renderers/ 301
 /advanced/logging-configuration                   /administration/logging-config/ 301
 /advanced/mail-templates                          /administration/mail-templates/ 301
 /advanced/protected-tags                          /usage/access-control/protected-tags/ 301
 /advanced/repo-indexer                            /administration/repo-indexer/ 301
 /advanced/repo-mirror                             /usage/repository/repo-mirror/ 301
 /advanced/search-engines-indexation               /administration/search-engines-indexation/ 301
 /advanced/signing                                 /administration/signing/ 301
 /developers/api-usage                             /development/api-usage/ 301
 /developers/integrations                          /development/integrations/ 301
 /developers/migrations-interfaces                 /development/migrations-interfaces/ 301
 /developers/oauth2-provider                       /development/oauth2-provider/ 301
 /development                                      /category/development/ 301
 /development/                                     /category/development/ 301
 /features/authentication                          /administration/authentication/ 301
 /features/comparison                              /installation/comparison/ 301
 /features/webhooks                                /usage/repository/webhooks/ 301
 /help                                             /category/help/ 301
 /help/                                            /category/help/ 301
 /help/seek-help                                   /help/support/ 301
 /installation                                     /category/installation/ 301
 /installation/                                    /category/installation/ 301
 /installation/upgrade-from-gogs                   /category/installation/ 301
 /upgrade/upgrade-from-gitea                       /installation/upgrade-from-gitea/ 301
 /upgrade/upgrade-from-gogs                        /category/installation/ 301
 /usage                                            /category/usage/ 301
 /usage/                                           /category/usage/ 301
 /usage/actions/act-runner                         /runner/ 301
 /usage/agit                                       /usage/issues-prs/agit/ 301
 /usage/agit-setup                                 /usage/issues-prs/agit/ 301
 /usage/authentication                             /administration/authentication/ 301
 /usage/automatically-linked-references            /usage/issues-prs/automatically-linked-references/ 301
 /usage/badge                                      /usage/actions/badge/ 301
 /usage/blame                                      /usage/repository/blame/ 301
 /usage/blocking-user                              /usage/access-control/blocking-user/ 301
 /usage/clone-filters                              /usage/repository/clone-filters/ 301
 /usage/code-owners                                /usage/repository/code-owners/ 301
 /usage/command-line                               /administration/command-line/ 301
 /usage/email-setup                                /administration/email-setup/ 301
 /usage/git-lfs-setup                              /administration/git-lfs-setup/ 301
 /usage/https-setup                                /administration/https-setup/ 301
 /usage/incoming-email                             /usage/repository/incoming-email/ 301
 /usage/issue-pull-request-templates               /usage/issues-prs/issue-pull-request-templates/ 301
 /usage/labels                                     /usage/issues-prs/labels/ 301
 /usage/markdown                                   /usage/repository/markdown/ 301
 /usage/merge-message-templates                    /usage/issues-prs/merge-message-templates/ 301
 /usage/migration                                  /usage/repository/migration/ 301
 /usage/multi-factor-authentication                /usage/user-setting/multi-factor-authentication/ 301
 /usage/permissions                                /usage/access-control/permissions/ 301
 /usage/profile-readme                             /usage/repository/profile-readme/ 301
 /usage/protected-tags                             /usage/access-control/protected-tags/ 301
 /usage/pull-request                               /usage/issues-prs/pull-request/ 301
 /usage/push                                       /usage/repository/push/ 301
 /usage/push-options                               /usage/repository/push/ 301
 /usage/push-to-create                             /usage/repository/push/ 301
 /usage/repo-mirror                                /usage/repository/repo-mirror/ 301
 /usage/secrets                                    /usage/actions/secrets/ 301
 /usage/template-repositories                      /usage/repository/template-repositories/ 301
 /usage/webhooks                                   /usage/repository/webhooks/ 301
 # ... and under simplified chinese.
 /zh-cn/actions                                    /zh-cn/usage/actions/ 301
 /zh-cn/actions/                                   /zh-cn/usage/actions/ 301
 /zh-cn/administration                             /zh-cn/category/administration/ 301
 /zh-cn/administration/                            /zh-cn/category/administration/ 301
 /zh-cn/administration/logging-configuration       /zh-cn/administration/logging-config/ 301
 /zh-cn/advanced/adding-legal-pages                /zh-cn/administration/adding-legal-pages/ 301
 /zh-cn/advanced/clone-filters                     /zh-cn/usage/repository/clone-filters/ 301
 /zh-cn/advanced/cmd-embedded                      /zh-cn/administration/cmd-embedded/ 301
 /zh-cn/advanced/config-cheat-sheet                /zh-cn/administration/config-cheat-sheet/ 301
 /zh-cn/advanced/customizing-gitea                 /zh-cn/administration/customizing-gitea/ 301
 /zh-cn/advanced/environment-variables             /zh-cn/administration/environment-variables/ 301
 /zh-cn/advanced/external-renderers                /zh-cn/administration/external-renderers/ 301
 /zh-cn/advanced/logging-configuration             /zh-cn/administration/logging-config/ 301
 /zh-cn/advanced/mail-templates                    /zh-cn/administration/mail-templates/ 301
 /zh-cn/advanced/protected-tags                    /zh-cn/usage/access-control/protected-tags/ 301
 /zh-cn/advanced/repo-indexer                      /zh-cn/administration/repo-indexer/ 301
 /zh-cn/advanced/repo-mirror                       /zh-cn/usage/repository/repo-mirror/ 301
 /zh-cn/advanced/search-engines-indexation         /zh-cn/administration/search-engines-indexation/ 301
 /zh-cn/advanced/signing                           /zh-cn/administration/signing/ 301
 /zh-cn/developers/api-usage                       /zh-cn/development/api-usage/ 301
 /zh-cn/developers/integrations                    /zh-cn/development/integrations/ 301
 /zh-cn/developers/migrations-interfaces           /zh-cn/development/migrations-interfaces/ 301
 /zh-cn/developers/oauth2-provider                 /zh-cn/development/oauth2-provider/ 301
 /zh-cn/development                                /zh-cn/category/development/ 301
 /zh-cn/development/                               /zh-cn/category/development/ 301
 /zh-cn/features/authentication                    /zh-cn/administration/authentication/ 301
 /zh-cn/features/comparison                        /zh-cn/installation/comparison/ 301
 /zh-cn/features/webhooks                          /zh-cn/usage/repository/webhooks/ 301
 /zh-cn/help                                       /zh-cn/category/help/ 301
 /zh-cn/help/                                      /zh-cn/category/help/ 301
 /zh-cn/help/seek-help                             /zh-cn/help/support/ 301
 /zh-cn/installation                               /zh-cn/category/installation/ 301
 /zh-cn/installation/                              /zh-cn/category/installation/ 301
 /zh-cn/installation/upgrade-from-gogs             /zh-cn/category/installation/ 301
 /zh-cn/upgrade/upgrade-from-gitea                 /zh-cn/installation/upgrade-from-gitea/ 301
 /zh-cn/upgrade/upgrade-from-gogs                  /zh-cn/category/installation/ 301
 /zh-cn/usage                                      /zh-cn/category/usage/ 301
 /zh-cn/usage/                                     /zh-cn/category/usage/ 301
 /zh-cn/usage/actions/act-runner                   /runner/ 301
 /zh-cn/usage/agit-setup                           /zh-cn/usage/issues-prs/agit/ 301
 /zh-cn/usage/authentication                       /zh-cn/administration/authentication/ 301
 /zh-cn/usage/automatically-linked-references      /zh-cn/usage/issues-prs/automatically-linked-references/ 301
 /zh-cn/usage/badge                                /zh-cn/usage/actions/badge/ 301
 /zh-cn/usage/blame                                /zh-cn/usage/repository/blame/ 301
 /zh-cn/usage/blocking-user                        /zh-cn/usage/access-control/blocking-user/ 301
 /zh-cn/usage/clone-filters                        /zh-cn/usage/repository/clone-filters/ 301
 /zh-cn/usage/code-owners                          /zh-cn/usage/repository/code-owners/ 301
 /zh-cn/usage/command-line                         /zh-cn/administration/command-line/ 301
 /zh-cn/usage/email-setup                          /zh-cn/administration/email-setup/ 301
 /zh-cn/usage/git-lfs-setup                        /zh-cn/administration/git-lfs-setup/ 301
 /zh-cn/usage/https-setup                          /zh-cn/administration/https-setup/ 301
 /zh-cn/usage/incoming-email                       /zh-cn/usage/repository/incoming-email/ 301
 /zh-cn/usage/issue-pull-request-templates         /zh-cn/usage/issues-prs/issue-pull-request-templates/ 301
 /zh-cn/usage/labels                               /zh-cn/usage/issues-prs/labels/ 301
 /zh-cn/usage/markdown                             /zh-cn/usage/repository/markdown/ 301
 /zh-cn/usage/merge-message-templates              /zh-cn/usage/issues-prs/merge-message-templates/ 301
 /zh-cn/usage/migration                            /zh-cn/usage/repository/migration/ 301
 /zh-cn/usage/multi-factor-authentication          /zh-cn/usage/user-setting/multi-factor-authentication/ 301
 /zh-cn/usage/permissions                          /zh-cn/usage/access-control/permissions/ 301
 /zh-cn/usage/profile-readme                       /zh-cn/usage/repository/profile-readme/ 301
 /zh-cn/usage/protected-tags                       /zh-cn/usage/access-control/protected-tags/ 301
 /zh-cn/usage/pull-request                         /zh-cn/usage/issues-prs/pull-request/ 301
 /zh-cn/usage/push                                 /zh-cn/usage/repository/push/ 301
 /zh-cn/usage/push-options                         /zh-cn/usage/repository/push/ 301
 /zh-cn/usage/push-to-create                       /zh-cn/usage/repository/push/ 301
 /zh-cn/usage/repo-mirror                          /zh-cn/usage/repository/repo-mirror/ 301
 /zh-cn/usage/secrets                              /zh-cn/usage/actions/secrets/ 301
 /zh-cn/usage/template-repositories                /zh-cn/usage/repository/template-repositories/ 301
 /zh-cn/usage/webhooks                             /zh-cn/usage/repository/webhooks/ 301
 # ... and under traditional chinese.
 /zh-tw/actions                                    /zh-tw/usage/actions/ 301
 /zh-tw/actions/                                   /zh-tw/usage/actions/ 301
 /zh-tw/administration                             /zh-tw/category/administration/ 301
 /zh-tw/administration/                            /zh-tw/category/administration/ 301
 /zh-tw/administration/logging-configuration       /zh-tw/administration/logging-config/ 301
 /zh-tw/advanced/adding-legal-pages                /zh-tw/administration/adding-legal-pages/ 301
 /zh-tw/advanced/clone-filters                     /zh-tw/usage/repository/clone-filters/ 301
 /zh-tw/advanced/cmd-embedded                      /zh-tw/administration/cmd-embedded/ 301
 /zh-tw/advanced/config-cheat-sheet                /zh-tw/administration/config-cheat-sheet/ 301
 /zh-tw/advanced/customizing-gitea                 /zh-tw/administration/customizing-gitea/ 301
 /zh-tw/advanced/environment-variables             /zh-tw/administration/environment-variables/ 301
 /zh-tw/advanced/external-renderers                /zh-tw/administration/external-renderers/ 301
 /zh-tw/advanced/logging-configuration             /zh-tw/administration/logging-config/ 301
 /zh-tw/advanced/mail-templates                    /zh-tw/administration/mail-templates/ 301
 /zh-tw/advanced/protected-tags                    /zh-tw/usage/access-control/protected-tags/ 301
 /zh-tw/advanced/repo-indexer                      /zh-tw/administration/repo-indexer/ 301
 /zh-tw/advanced/repo-mirror                       /zh-tw/usage/repository/repo-mirror/ 301
 /zh-tw/advanced/search-engines-indexation         /zh-tw/administration/search-engines-indexation/ 301
 /zh-tw/advanced/signing                           /zh-tw/administration/signing/ 301
 /zh-tw/developers/api-usage                       /zh-tw/development/api-usage/ 301
 /zh-tw/developers/integrations                    /zh-tw/development/integrations/ 301
 /zh-tw/developers/migrations-interfaces           /zh-tw/development/migrations-interfaces/ 301
 /zh-tw/developers/oauth2-provider                 /zh-tw/development/oauth2-provider/ 301
 /zh-tw/development                                /zh-tw/category/development/ 301
 /zh-tw/development/                               /zh-tw/category/development/ 301
 /zh-tw/features/authentication                    /zh-tw/administration/authentication/ 301
 /zh-tw/features/comparison                        /zh-tw/installation/comparison/ 301
 /zh-tw/features/webhooks                          /zh-tw/usage/repository/webhooks/ 301
 /zh-tw/help                                       /zh-tw/category/help/ 301
 /zh-tw/help/                                      /zh-tw/category/help/ 301
 /zh-tw/help/seek-help                             /zh-tw/help/support/ 301
 /zh-tw/installation                               /zh-tw/category/installation/ 301
 /zh-tw/installation/                              /zh-tw/category/installation/ 301
 /zh-tw/installation/upgrade-from-gogs             /zh-tw/category/installation/ 301
 /zh-tw/upgrade/upgrade-from-gitea                 /zh-tw/installation/upgrade-from-gitea/ 301
 /zh-tw/upgrade/upgrade-from-gogs                  /zh-tw/category/installation/ 301
 /zh-tw/usage                                      /zh-tw/category/usage/ 301
 /zh-tw/usage/                                     /zh-tw/category/usage/ 301
 /zh-tw/usage/actions/act-runner                   /runner/ 301
 /zh-tw/usage/agit-setup                           /zh-tw/usage/issues-prs/agit/ 301
 /zh-tw/usage/authentication                       /zh-tw/administration/authentication/ 301
 /zh-tw/usage/automatically-linked-references      /zh-tw/usage/issues-prs/automatically-linked-references/ 301
 /zh-tw/usage/badge                                /zh-tw/usage/actions/badge/ 301
 /zh-tw/usage/blame                                /zh-tw/usage/repository/blame/ 301
 /zh-tw/usage/blocking-user                        /zh-tw/usage/access-control/blocking-user/ 301
 /zh-tw/usage/clone-filters                        /zh-tw/usage/repository/clone-filters/ 301
 /zh-tw/usage/code-owners                          /zh-tw/usage/repository/code-owners/ 301
 /zh-tw/usage/command-line                         /zh-tw/administration/command-line/ 301
 /zh-tw/usage/email-setup                          /zh-tw/administration/email-setup/ 301
 /zh-tw/usage/git-lfs-setup                        /zh-tw/administration/git-lfs-setup/ 301
 /zh-tw/usage/https-setup                          /zh-tw/administration/https-setup/ 301
 /zh-tw/usage/incoming-email                       /zh-tw/usage/repository/incoming-email/ 301
 /zh-tw/usage/issue-pull-request-templates         /zh-tw/usage/issues-prs/issue-pull-request-templates/ 301
 /zh-tw/usage/labels                               /zh-tw/usage/issues-prs/labels/ 301
 /zh-tw/usage/markdown                             /zh-tw/usage/repository/markdown/ 301
 /zh-tw/usage/merge-message-templates              /zh-tw/usage/issues-prs/merge-message-templates/ 301
 /zh-tw/usage/migration                            /zh-tw/usage/repository/migration/ 301
 /zh-tw/usage/multi-factor-authentication          /zh-tw/usage/user-setting/multi-factor-authentication/ 301
 /zh-tw/usage/permissions                          /zh-tw/usage/access-control/permissions/ 301
 /zh-tw/usage/protected-tags                       /zh-tw/usage/access-control/protected-tags/ 301
 /zh-tw/usage/pull-request                         /zh-tw/usage/issues-prs/pull-request/ 301
 /zh-tw/usage/push                                 /zh-tw/usage/repository/push/ 301
 /zh-tw/usage/push-options                         /zh-tw/usage/repository/push/ 301
 /zh-tw/usage/push-to-create                       /zh-tw/usage/repository/push/ 301
 /zh-tw/usage/repo-mirror                          /zh-tw/usage/repository/repo-mirror/ 301
 /zh-tw/usage/secrets                              /zh-tw/usage/actions/secrets/ 301
 /zh-tw/usage/template-repositories                /zh-tw/usage/repository/template-repositories/ 301
 /zh-tw/usage/webhooks                             /zh-tw/usage/repository/webhooks/ 301
 # ... and under the develop version.
 /next/actions                                     /next/usage/actions/ 301
 /next/actions/                                    /next/usage/actions/ 301
 /next/administration                              /next/category/administration/ 301
 /next/administration/                             /next/category/administration/ 301
 /next/administration/logging-configuration        /next/administration/logging-config/ 301
 /next/advanced/adding-legal-pages                 /next/administration/adding-legal-pages/ 301
 /next/advanced/clone-filters                      /next/usage/repository/clone-filters/ 301
 /next/advanced/cmd-embedded                       /next/administration/cmd-embedded/ 301
 /next/advanced/config-cheat-sheet                 /next/administration/config-cheat-sheet/ 301
 /next/advanced/customizing-gitea                  /next/administration/customizing-gitea/ 301
 /next/advanced/environment-variables              /next/administration/environment-variables/ 301
 /next/advanced/external-renderers                 /next/administration/external-renderers/ 301
 /next/advanced/logging-configuration              /next/administration/logging-config/ 301
 /next/advanced/mail-templates                     /next/administration/mail-templates/ 301
 /next/advanced/protected-tags                     /next/usage/access-control/protected-tags/ 301
 /next/advanced/repo-indexer                       /next/administration/repo-indexer/ 301
 /next/advanced/repo-mirror                        /next/usage/repository/repo-mirror/ 301
 /next/advanced/search-engines-indexation          /next/administration/search-engines-indexation/ 301
 /next/advanced/signing                            /next/administration/signing/ 301
 /next/developers/api-usage                        /next/development/api-usage/ 301
 /next/developers/integrations                     /next/development/integrations/ 301
 /next/developers/migrations-interfaces            /next/development/migrations-interfaces/ 301
 /next/developers/oauth2-provider                  /next/development/oauth2-provider/ 301
 /next/development                                 /next/category/development/ 301
 /next/development/                                /next/category/development/ 301
 /next/features/authentication                     /next/administration/authentication/ 301
 /next/features/comparison                         /next/installation/comparison/ 301
 /next/features/webhooks                           /next/usage/repository/webhooks/ 301
 /next/help                                        /next/category/help/ 301
 /next/help/                                       /next/category/help/ 301
 /next/help/seek-help                              /next/help/support/ 301
 /next/installation                                /next/category/installation/ 301
 /next/installation/                               /next/category/installation/ 301
 /next/installation/upgrade-from-gogs              /next/category/installation/ 301
 /next/upgrade/upgrade-from-gitea                  /next/installation/upgrade-from-gitea/ 301
 /next/upgrade/upgrade-from-gogs                   /next/category/installation/ 301
 /next/usage                                       /next/category/usage/ 301
 /next/usage/                                      /next/category/usage/ 301
 /next/usage/actions/act-runner                    /runner/ 301
 /next/usage/agit                                  /next/usage/issues-prs/agit/ 301
 /next/usage/agit-setup                            /next/usage/issues-prs/agit/ 301
 /next/usage/authentication                        /next/administration/authentication/ 301
 /next/usage/automatically-linked-references       /next/usage/issues-prs/automatically-linked-references/ 301
 /next/usage/badge                                 /next/usage/actions/badge/ 301
 /next/usage/blame                                 /next/usage/repository/blame/ 301
 /next/usage/blocking-user                         /next/usage/access-control/blocking-user/ 301
 /next/usage/clone-filters                         /next/usage/repository/clone-filters/ 301
 /next/usage/code-owners                           /next/usage/repository/code-owners/ 301
 /next/usage/command-line                          /next/administration/command-line/ 301
 /next/usage/email-setup                           /next/administration/email-setup/ 301
 /next/usage/git-lfs-setup                         /next/administration/git-lfs-setup/ 301
 /next/usage/https-setup                           /next/administration/https-setup/ 301
 /next/usage/incoming-email                        /next/usage/repository/incoming-email/ 301
 /next/usage/issue-pull-request-templates          /next/usage/issues-prs/issue-pull-request-templates/ 301
 /next/usage/labels                                /next/usage/issues-prs/labels/ 301
 /next/usage/markdown                              /next/usage/repository/markdown/ 301
 /next/usage/merge-message-templates               /next/usage/issues-prs/merge-message-templates/ 301
 /next/usage/migration                             /next/usage/repository/migration/ 301
 /next/usage/multi-factor-authentication           /next/usage/user-setting/multi-factor-authentication/ 301
 /next/usage/permissions                           /next/usage/access-control/permissions/ 301
 /next/usage/profile-readme                        /next/usage/repository/profile-readme/ 301
 /next/usage/protected-tags                        /next/usage/access-control/protected-tags/ 301
 /next/usage/pull-request                          /next/usage/issues-prs/pull-request/ 301
 /next/usage/push                                  /next/usage/repository/push/ 301
 /next/usage/push-options                          /next/usage/repository/push/ 301
 /next/usage/push-to-create                        /next/usage/repository/push/ 301
 /next/usage/repo-mirror                           /next/usage/repository/repo-mirror/ 301
 /next/usage/secrets                               /next/usage/actions/secrets/ 301
 /next/usage/template-repositories                 /next/usage/repository/template-repositories/ 301
 /next/usage/webhooks                              /next/usage/repository/webhooks/ 301
 # ... and under simplified chinese, develop.
 /zh-cn/next/actions                               /zh-cn/next/usage/actions/ 301
 /zh-cn/next/actions/                              /zh-cn/next/usage/actions/ 301
 /zh-cn/next/administration                        /zh-cn/next/category/administration/ 301
 /zh-cn/next/administration/                       /zh-cn/next/category/administration/ 301
 /zh-cn/next/administration/logging-configuration  /zh-cn/next/administration/logging-config/ 301
 /zh-cn/next/advanced/adding-legal-pages           /zh-cn/next/administration/adding-legal-pages/ 301
 /zh-cn/next/advanced/clone-filters                /zh-cn/next/usage/repository/clone-filters/ 301
 /zh-cn/next/advanced/cmd-embedded                 /zh-cn/next/administration/cmd-embedded/ 301
 /zh-cn/next/advanced/config-cheat-sheet           /zh-cn/next/administration/config-cheat-sheet/ 301
 /zh-cn/next/advanced/customizing-gitea            /zh-cn/next/administration/customizing-gitea/ 301
 /zh-cn/next/advanced/environment-variables        /zh-cn/next/administration/environment-variables/ 301
 /zh-cn/next/advanced/external-renderers           /zh-cn/next/administration/external-renderers/ 301
 /zh-cn/next/advanced/logging-configuration        /zh-cn/next/administration/logging-config/ 301
 /zh-cn/next/advanced/mail-templates               /zh-cn/next/administration/mail-templates/ 301
 /zh-cn/next/advanced/protected-tags               /zh-cn/next/usage/access-control/protected-tags/ 301
 /zh-cn/next/advanced/repo-indexer                 /zh-cn/next/administration/repo-indexer/ 301
 /zh-cn/next/advanced/repo-mirror                  /zh-cn/next/usage/repository/repo-mirror/ 301
 /zh-cn/next/advanced/search-engines-indexation    /zh-cn/next/administration/search-engines-indexation/ 301
 /zh-cn/next/advanced/signing                      /zh-cn/next/administration/signing/ 301
 /zh-cn/next/developers/api-usage                  /zh-cn/next/development/api-usage/ 301
 /zh-cn/next/developers/integrations               /zh-cn/next/development/integrations/ 301
 /zh-cn/next/developers/migrations-interfaces      /zh-cn/next/development/migrations-interfaces/ 301
 /zh-cn/next/developers/oauth2-provider            /zh-cn/next/development/oauth2-provider/ 301
 /zh-cn/next/development                           /zh-cn/next/category/development/ 301
 /zh-cn/next/development/                          /zh-cn/next/category/development/ 301
 /zh-cn/next/features/authentication               /zh-cn/next/administration/authentication/ 301
 /zh-cn/next/features/comparison                   /zh-cn/next/installation/comparison/ 301
 /zh-cn/next/features/webhooks                     /zh-cn/next/usage/repository/webhooks/ 301
 /zh-cn/next/help                                  /zh-cn/next/category/help/ 301
 /zh-cn/next/help/                                 /zh-cn/next/category/help/ 301
 /zh-cn/next/help/seek-help                        /zh-cn/next/help/support/ 301
 /zh-cn/next/installation                          /zh-cn/next/category/installation/ 301
 /zh-cn/next/installation/                         /zh-cn/next/category/installation/ 301
 /zh-cn/next/installation/upgrade-from-gogs        /zh-cn/next/category/installation/ 301
 /zh-cn/next/upgrade/upgrade-from-gitea            /zh-cn/next/installation/upgrade-from-gitea/ 301
 /zh-cn/next/upgrade/upgrade-from-gogs             /zh-cn/next/category/installation/ 301
 /zh-cn/next/usage                                 /zh-cn/next/category/usage/ 301
 /zh-cn/next/usage/                                /zh-cn/next/category/usage/ 301
 /zh-cn/next/usage/actions/act-runner              /runner/ 301
 /zh-cn/next/usage/agit-setup                      /zh-cn/next/usage/issues-prs/agit/ 301
 /zh-cn/next/usage/authentication                  /zh-cn/next/administration/authentication/ 301
 /zh-cn/next/usage/automatically-linked-references /zh-cn/next/usage/issues-prs/automatically-linked-references/ 301
 /zh-cn/next/usage/badge                           /zh-cn/next/usage/actions/badge/ 301
 /zh-cn/next/usage/blame                           /zh-cn/next/usage/repository/blame/ 301
 /zh-cn/next/usage/blocking-user                   /zh-cn/next/usage/access-control/blocking-user/ 301
 /zh-cn/next/usage/clone-filters                   /zh-cn/next/usage/repository/clone-filters/ 301
 /zh-cn/next/usage/code-owners                     /zh-cn/next/usage/repository/code-owners/ 301
 /zh-cn/next/usage/command-line                    /zh-cn/next/administration/command-line/ 301
 /zh-cn/next/usage/email-setup                     /zh-cn/next/administration/email-setup/ 301
 /zh-cn/next/usage/git-lfs-setup                   /zh-cn/next/administration/git-lfs-setup/ 301
 /zh-cn/next/usage/https-setup                     /zh-cn/next/administration/https-setup/ 301
 /zh-cn/next/usage/incoming-email                  /zh-cn/next/usage/repository/incoming-email/ 301
 /zh-cn/next/usage/issue-pull-request-templates    /zh-cn/next/usage/issues-prs/issue-pull-request-templates/ 301
 /zh-cn/next/usage/labels                          /zh-cn/next/usage/issues-prs/labels/ 301
 /zh-cn/next/usage/markdown                        /zh-cn/next/usage/repository/markdown/ 301
 /zh-cn/next/usage/merge-message-templates         /zh-cn/next/usage/issues-prs/merge-message-templates/ 301
 /zh-cn/next/usage/migration                       /zh-cn/next/usage/repository/migration/ 301
 /zh-cn/next/usage/multi-factor-authentication     /zh-cn/next/usage/user-setting/multi-factor-authentication/ 301
 /zh-cn/next/usage/permissions                     /zh-cn/next/usage/access-control/permissions/ 301
 /zh-cn/next/usage/profile-readme                  /zh-cn/next/usage/repository/profile-readme/ 301
 /zh-cn/next/usage/protected-tags                  /zh-cn/next/usage/access-control/protected-tags/ 301
 /zh-cn/next/usage/pull-request                    /zh-cn/next/usage/issues-prs/pull-request/ 301
 /zh-cn/next/usage/push                            /zh-cn/next/usage/repository/push/ 301
 /zh-cn/next/usage/push-options                    /zh-cn/next/usage/repository/push/ 301
 /zh-cn/next/usage/push-to-create                  /zh-cn/next/usage/repository/push/ 301
 /zh-cn/next/usage/repo-mirror                     /zh-cn/next/usage/repository/repo-mirror/ 301
 /zh-cn/next/usage/secrets                         /zh-cn/next/usage/actions/secrets/ 301
 /zh-cn/next/usage/template-repositories           /zh-cn/next/usage/repository/template-repositories/ 301
 /zh-cn/next/usage/webhooks                        /zh-cn/next/usage/repository/webhooks/ 301
 # ... and under traditional chinese, develop.
 /zh-tw/next/actions                               /zh-tw/next/usage/actions/ 301
 /zh-tw/next/actions/                              /zh-tw/next/usage/actions/ 301
 /zh-tw/next/administration                        /zh-tw/next/category/administration/ 301
 /zh-tw/next/administration/                       /zh-tw/next/category/administration/ 301
 /zh-tw/next/administration/logging-configuration  /zh-tw/next/administration/logging-config/ 301
 /zh-tw/next/advanced/adding-legal-pages           /zh-tw/next/administration/adding-legal-pages/ 301
 /zh-tw/next/advanced/clone-filters                /zh-tw/next/usage/repository/clone-filters/ 301
 /zh-tw/next/advanced/cmd-embedded                 /zh-tw/next/administration/cmd-embedded/ 301
 /zh-tw/next/advanced/config-cheat-sheet           /zh-tw/next/administration/config-cheat-sheet/ 301
 /zh-tw/next/advanced/customizing-gitea            /zh-tw/next/administration/customizing-gitea/ 301
 /zh-tw/next/advanced/environment-variables        /zh-tw/next/administration/environment-variables/ 301
 /zh-tw/next/advanced/external-renderers           /zh-tw/next/administration/external-renderers/ 301
 /zh-tw/next/advanced/logging-configuration        /zh-tw/next/administration/logging-config/ 301
 /zh-tw/next/advanced/mail-templates               /zh-tw/next/administration/mail-templates/ 301
 /zh-tw/next/advanced/protected-tags               /zh-tw/next/usage/access-control/protected-tags/ 301
 /zh-tw/next/advanced/repo-indexer                 /zh-tw/next/administration/repo-indexer/ 301
 /zh-tw/next/advanced/repo-mirror                  /zh-tw/next/usage/repository/repo-mirror/ 301
 /zh-tw/next/advanced/search-engines-indexation    /zh-tw/next/administration/search-engines-indexation/ 301
 /zh-tw/next/advanced/signing                      /zh-tw/next/administration/signing/ 301
 /zh-tw/next/developers/api-usage                  /zh-tw/next/development/api-usage/ 301
 /zh-tw/next/developers/integrations               /zh-tw/next/development/integrations/ 301
 /zh-tw/next/developers/migrations-interfaces      /zh-tw/next/development/migrations-interfaces/ 301
 /zh-tw/next/developers/oauth2-provider            /zh-tw/next/development/oauth2-provider/ 301
 /zh-tw/next/development                           /zh-tw/next/category/development/ 301
 /zh-tw/next/development/                          /zh-tw/next/category/development/ 301
 /zh-tw/next/features/authentication               /zh-tw/next/administration/authentication/ 301
 /zh-tw/next/features/comparison                   /zh-tw/next/installation/comparison/ 301
 /zh-tw/next/features/webhooks                     /zh-tw/next/usage/repository/webhooks/ 301
 /zh-tw/next/help                                  /zh-tw/next/category/help/ 301
 /zh-tw/next/help/                                 /zh-tw/next/category/help/ 301
 /zh-tw/next/help/seek-help                        /zh-tw/next/help/support/ 301
 /zh-tw/next/installation                          /zh-tw/next/category/installation/ 301
 /zh-tw/next/installation/                         /zh-tw/next/category/installation/ 301
 /zh-tw/next/installation/upgrade-from-gogs        /zh-tw/next/category/installation/ 301
 /zh-tw/next/upgrade/upgrade-from-gitea            /zh-tw/next/installation/upgrade-from-gitea/ 301
 /zh-tw/next/upgrade/upgrade-from-gogs             /zh-tw/next/category/installation/ 301
 /zh-tw/next/usage                                 /zh-tw/next/category/usage/ 301
 /zh-tw/next/usage/                                /zh-tw/next/category/usage/ 301
 /zh-tw/next/usage/actions/act-runner              /runner/ 301
 /zh-tw/next/usage/agit-setup                      /zh-tw/next/usage/issues-prs/agit/ 301
 /zh-tw/next/usage/authentication                  /zh-tw/next/administration/authentication/ 301
 /zh-tw/next/usage/automatically-linked-references /zh-tw/next/usage/issues-prs/automatically-linked-references/ 301
 /zh-tw/next/usage/badge                           /zh-tw/next/usage/actions/badge/ 301
 /zh-tw/next/usage/blame                           /zh-tw/next/usage/repository/blame/ 301
 /zh-tw/next/usage/blocking-user                   /zh-tw/next/usage/access-control/blocking-user/ 301
 /zh-tw/next/usage/clone-filters                   /zh-tw/next/usage/repository/clone-filters/ 301
 /zh-tw/next/usage/code-owners                     /zh-tw/next/usage/repository/code-owners/ 301
 /zh-tw/next/usage/command-line                    /zh-tw/next/administration/command-line/ 301
 /zh-tw/next/usage/email-setup                     /zh-tw/next/administration/email-setup/ 301
 /zh-tw/next/usage/git-lfs-setup                   /zh-tw/next/administration/git-lfs-setup/ 301
 /zh-tw/next/usage/https-setup                     /zh-tw/next/administration/https-setup/ 301
 /zh-tw/next/usage/incoming-email                  /zh-tw/next/usage/repository/incoming-email/ 301
 /zh-tw/next/usage/issue-pull-request-templates    /zh-tw/next/usage/issues-prs/issue-pull-request-templates/ 301
 /zh-tw/next/usage/labels                          /zh-tw/next/usage/issues-prs/labels/ 301
 /zh-tw/next/usage/markdown                        /zh-tw/next/usage/repository/markdown/ 301
 /zh-tw/next/usage/merge-message-templates         /zh-tw/next/usage/issues-prs/merge-message-templates/ 301
 /zh-tw/next/usage/migration                       /zh-tw/next/usage/repository/migration/ 301
 /zh-tw/next/usage/multi-factor-authentication     /zh-tw/next/usage/user-setting/multi-factor-authentication/ 301
 /zh-tw/next/usage/permissions                     /zh-tw/next/usage/access-control/permissions/ 301
 /zh-tw/next/usage/protected-tags                  /zh-tw/next/usage/access-control/protected-tags/ 301
 /zh-tw/next/usage/pull-request                    /zh-tw/next/usage/issues-prs/pull-request/ 301
 /zh-tw/next/usage/push                            /zh-tw/next/usage/repository/push/ 301
 /zh-tw/next/usage/push-options                    /zh-tw/next/usage/repository/push/ 301
 /zh-tw/next/usage/push-to-create                  /zh-tw/next/usage/repository/push/ 301
 /zh-tw/next/usage/repo-mirror                     /zh-tw/next/usage/repository/repo-mirror/ 301
 /zh-tw/next/usage/secrets                         /zh-tw/next/usage/actions/secrets/ 301
 /zh-tw/next/usage/template-repositories           /zh-tw/next/usage/repository/template-repositories/ 301
 /zh-tw/next/usage/webhooks                        /zh-tw/next/usage/repository/webhooks/ 301
 # Runner versions that were published under their full number, and the develop
 # runner docs, which used to be `next`.
 /runner/0.2.11/* /runner/0/:splat 301
 /runner/1.0.8/* /runner/1/:splat 301
 /runner/next/* /runner/develop/:splat 301
@@ -0,0 +1,32 @@
 {
  "_comment": "Algolia DocSearch crawler configuration. The three facets come from the docsearch:* meta tags every page carries; only the versions people read are indexed, the older ones stay reachable through the version picker.",
  "index_name": "gitea",
  "start_urls": [
    "https://docs.gitea.com/",
    "https://docs.gitea.com/next/",
    "https://docs.gitea.com/zh-cn/",
    "https://docs.gitea.com/zh-tw/",
    "https://docs.gitea.com/runner/",
    "https://docs.gitea.com/api/",
    "https://docs.gitea.com/enterprise/"
  ],
  "sitemap_urls": ["https://docs.gitea.com/sitemap-index.xml"],
  "exclusion_patterns": [
    "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]/**"
  ],
  "selectors": {
    "lvl0": { "selector": "//nav[contains(@aria-labelledby,'starlight__sidebar')]//a[@aria-current='page']/ancestor::details//summary//span", "type": "xpath", "global": true, "default_value": "Documentation" },
    "lvl1": ".sl-markdown-content h1, h1",
    "lvl2": ".sl-markdown-content h2",
    "lvl3": ".sl-markdown-content h3",
    "lvl4": ".sl-markdown-content h4",
    "text": ".sl-markdown-content p, .sl-markdown-content li, .sl-markdown-content td"
  },
  "custom_settings": {
    "attributesForFaceting": ["product", "version", "language"]
  },
  "conversation_id": []
 }
@@ -0,0 +1,9 @@
 {
  "label": "Administration",
  "position": 30,
  "link": {
    "type": "generated-index",
    "slug": "/administration",
    "title": "Administration"
  }
 }
@@ -12,10 +12,10 @@ Some jurisdictions (such as EU), requires certain legal pages (e.g. Privacy Poli
 ## Getting Pages
-Gitea source code ships with sample pages, available in `contrib/legal` directory. Copy them to `custom/public/assets/`. For example, to add Privacy Policy:
+Gitea source code ships with sample pages, available in `contrib/service/sample-page` directory. Copy them to `custom/public/assets/`. For example, to add Privacy Policy:
 ```bash
-wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/legal/privacy.html.sample
+wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/service/sample-page/privacy.html.sample
 ```
 Now you need to edit the page to meet your requirements. In particular you must change the email addresses, web addresses and references to "Your Gitea Instance" to match your situation.
@@ -349,3 +349,86 @@ ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true
 :::note
 When this method is enabled for the API, the reverse proxy is responsible for handling CSRF protection.
 :::
 ## OAuth2 and OpenID Connect
 Gitea can delegate the login to an external OAuth2 or OpenID Connect provider,
 which is what "Sign in with ..." on the login page uses. This is the client side
 of the protocol; for the other direction, using a Gitea instance as the provider
 for another application, see
 [Gitea as an OAuth2 provider](../development/oauth2-provider.md).
 A source is added under `Site Administration -> Identity & Access ->
 Authentication Sources -> Add Authentication Source`, with `OAuth2` as the
 authentication type, or on the command line with
 `gitea admin auth add-oauth`. The fields are:
 - **Authentication Name (required)**
  - The name of the source. It is part of the callback URL, so it cannot be
    changed later without registering a new callback URL at the provider.
 - **OAuth2 Provider (required)**
  - `OpenID Connect` for any provider that implements OpenID Connect discovery
    (Keycloak, Authentik, Authelia, Entra ID, Okta, Zitadel and others), or one
    of the providers Gitea knows about directly: Gitea, GitHub, GitLab, Google,
    Discord, Bitbucket, Dropbox, Facebook, Mastodon, Nextcloud, Twitter, Yandex
    and Azure AD v2.
 - **Client ID (Key)** and **Client Secret (required)**
  - The credentials of the application registered at the provider.
 - **OpenID Connect Auto Discovery URL**
  - Only for the `OpenID Connect` provider: the discovery document of the
    provider, usually `https://provider.example.com/.well-known/openid-configuration`.
    Gitea reads the endpoints from it.
 - **Additional Scopes**
  - Scopes to request on top of the ones the provider needs by default. For
    OpenID Connect, `openid` is always added, and the scopes are taken from
    `OPENID_CONNECT_SCOPES` in `app.ini` when it is set.
 - **Required Claim Name** and **Required Claim Value**
  - Restrict the login to accounts whose token carries this claim, optionally
    with this exact value.
 - **Claim name providing group names**, **Group Claim value for administrator
  users**, **Group Claim value for restricted users** and **Map claimed groups
  to Organization teams**
  - Grant the administrator or the restricted flag, and organization team
    membership, from the groups the provider reports. They all need the claim
    name to be set.
 - **Icon URL**
  - Image shown next to the button on the login page.
 Register `{ROOT_URL}/user/oauth2/{Authentication Name}/callback` as the
 redirect URI at the provider, for example
 `https://gitea.example.com/user/oauth2/keycloak/callback` for a source named
 `keycloak`. A wrong redirect URI is the most common reason for the login to
 fail at the provider.
 What happens to accounts that log in this way is configured in `app.ini`, see
 [OAuth2 Client](config-cheat-sheet.md#oauth2-client-oauth2_client):
 ```ini title="app.ini"
 [oauth2_client]
 ; create an account for a user who logs in for the first time
 ENABLE_AUTO_REGISTRATION = true
 ; where the username of a new account comes from
 USERNAME = nickname
 ; what to do when the username or email is already taken
 ACCOUNT_LINKING = login
 ```
 :::note
 This is unrelated to `ENABLE_OPENID_SIGNIN` and the `[openid]` section, which
 configure the older OpenID 2.0 sign-in.
 :::
@@ -24,7 +24,7 @@ directory. There should be some output similar to the following:
 ```log
 2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:09 Dumping local repositories.../home/git/gitea-repositories
+2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
 2016/12/27 22:32:22 Dumping database...
 2016/12/27 22:32:22 Packing dump files...
 2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
@@ -83,7 +83,7 @@ cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/data/gitea-repositories/
+mv repos/* /var/lib/gitea/data/repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
 # mysql
@@ -119,7 +119,7 @@ cd gitea-dump-1610949662
 # restore the gitea data
 mv data/* /data/gitea
 # restore the repositories itself
-mv repos/* /data/git/gitea-repositories/
+mv repos/* /data/git/repositories/
 # adjust file permissions
 chown -R git:git /data
 # Regenerate Git Hooks
@@ -143,7 +143,7 @@ mv data/conf/app.ini /etc/gitea/app.ini
 # restore the gitea data
 mv data/* /var/lib/gitea
 # restore the repositories itself
-mv repos/* /var/lib/gitea/git/gitea-repositories
+mv repos/* /var/lib/gitea/git/repositories
 # adjust file permissions
 chown -R git:git /etc/gitea/app.ini /var/lib/gitea
 # Regenerate Git Hooks
@@ -173,4 +173,4 @@ gitea=# \i gitea-db.sql
 Disabling `synchronous_commit` makes PostgreSQL less resilient to crashes, but makes the import a lot faster. Since we already have a backup of the original database and we can check that the import completes successfully, it should be a good trade-off.
-After the import is completed, set up Gitea to use PostgreSQL and start the Gitea server again. Good luck!
+After the import is completed, set up Gitea to use PostgreSQL and start the Gitea server again. Good luck!
@@ -45,6 +45,9 @@ Starts the server:
  - Gitea should not be run as root. To bind to a port below 1024, you can use setcap on
    Linux: `sudo setcap 'cap_net_bind_service=+ep' /path/to/gitea`. This will need to be
    redone every time you update Gitea.
    A systemd unit can grant the capability to the process instead, which survives an
    upgrade and works with SELinux in enforcing mode, see
    [running Gitea with SELinux](../installation/selinux.md).
 ### admin
@@ -9,7 +9,7 @@ aliases:
 # Customizing Gitea
 Customizing Gitea is typically done using the `CustomPath` folder - by default this is
-the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/installation.md) has
+the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/from-binary.md) has
 set this differently. This is the central place to override configuration settings,
 templates, etc. You can check the `CustomPath` using `gitea help`. You can also find
 the path on the _Configuration_ tab in the _Site Administration_ page. You can override
@@ -23,7 +23,7 @@ the Linux Filesystem Standard. Gitea will attempt to create required folders, in
 `custom/`. Distributions may provide a symlink for `custom` using `/etc/gitea/`.
 Application settings can be found in file `CustomConf` which is by default,
-`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/installation.md) has set this differently.
+`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/from-binary.md) has set this differently.
 Again `gitea help` will allow you review this variable and you can override it using the
 `--config` option on the `gitea` binary.
@@ -85,6 +85,8 @@ To obtain any embedded file (including templates), the [`gitea embedded` tool](.
 Be aware that any statement contained inside `{{` and `}}` are Gitea's template syntax and
 shouldn't be touched without fully understanding these components.
 Gitea pages are protected by Content-Security-Policy, use `<script nonce="{{ctx.CspScriptNonce}}">...</script>` for script tags.
 ### Customizing startpage / homepage
 Copy [`home.tmpl`](https://github.com/go-gitea/gitea/blob/main/templates/home.tmpl) for your version of Gitea from `templates` to `$GITEA_CUSTOM/templates`.
@@ -136,10 +138,10 @@ The data is encoded and sent to the PlantUML server which generates the picture.
 demo server at http://www.plantuml.com/plantuml, but if you (or your users) have sensitive data you
 can set up your own [PlantUML server](https://plantuml.com/server) instead. To set up PlantUML rendering,
 copy JavaScript files from https://gitea.com/davidsvantesson/plantuml-code-highlight and put them in your
-`$GITEA_CUSTOM/public/assets/` folder. Then add the following to `custom/footer.tmpl`:
+`$GITEA_CUSTOM/public/assets/` folder. Then add the following to `$GITEA_CUSTOM/templates/custom/footer.tmpl`:
 ```html
-<script>
+<script nonce="{{ctx.CspScriptNonce}}">
  $(async () => {
    if (!$('.language-plantuml').length) return;
    await Promise.all([
@@ -180,60 +182,129 @@ In $GITEA_CUSTOM we need to add our template.
 This template needs to be saved in "$GITEA_CUSTOM/templates/custom/".
 Here create file "footer.tmpl" and add following text into it:
 ```
 nano $GITEA_CUSTOM/templates/custom/footer.tmpl
 ```
 ```html
-<script>
+<script nonce="{{ctx.CspScriptNonce}}">
-    document.addEventListener('DOMContentLoaded', () => {
+    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) {
+	if (link3D) {
-        const script = document.createElement('script');
+	  const existingScript = document.querySelector('script[src="/assets/o3dv/o3dv.min.js"]');
-        script.onload = () => {
+
-          const fileUrl = link3D.getAttribute('href');
+	  const initializeViewer = () => {
-  
+		const fileUrl = link3D.getAttribute('href');
-          // Prepare the container for the viewer
+
-          const fileView = document.querySelector('.file-view');
+                const fileView = document.querySelector('.file-view');
-          if (fileView) {
+
-            fileView.setAttribute('id', 'view-3d');
+		if (!fileView) return;
-            fileView.style.padding = '0';
+
-            fileView.style.margin = '0';
+		// Remove only the old viewer container if it exists
-            fileView.style.height = '400px';
+		const oldView3D = document.getElementById('view-3d');
-            fileView.style.width = '100%';
+		if (oldView3D) {
-            fileView.innerHTML = '';
+		  oldView3D.remove();  // safely remove old viewer container div
-          }
+		} else {
-  
+		  // No #view-3d, so remove all children inside .file-view
-          // Initialize viewer
+		  while (fileView.firstChild) {
-          const parentDiv = document.getElementById('view-3d');
+		    fileView.removeChild(fileView.firstChild);
-          if (parentDiv) {
+		  }
-            const viewer = new OV.EmbeddedViewer(parentDiv, {
+		}
-              backgroundColor: new OV.RGBAColor(59, 68, 76, 0), // Transparent
+
-              defaultColor: new OV.RGBColor(200, 200, 200),
+		// Create a new container for the viewer
-              edgeSettings: new OV.EdgeSettings(false, new OV.RGBColor(0, 0, 0), 1),
+		const newView3D = document.createElement('div');
-              environmentSettings: new OV.EnvironmentSettings([
+		  newView3D.id = 'view-3d';
-                '/assets/o3dv/envmaps/fishermans_bastion/negx.jpg',
+		  newView3D.style.padding = '0';
-                '/assets/o3dv/envmaps/fishermans_bastion/posx.jpg',
+		  newView3D.style.margin = '0';
-                '/assets/o3dv/envmaps/fishermans_bastion/posy.jpg',
+		  newView3D.style.flexGrow = '1';
-                '/assets/o3dv/envmaps/fishermans_bastion/negy.jpg',
+		  newView3D.style.minHeight = '0';
-                '/assets/o3dv/envmaps/fishermans_bastion/posz.jpg',
+		  newView3D.style.width = '100%';
-                '/assets/o3dv/envmaps/fishermans_bastion/negz.jpg'
+
-              ], false)
+		const header = document.querySelector('header');
-            });
+		const headerHeight = header ? header.offsetHeight : 0;
-  
+
-            // Load the model
+		newView3D.style.height = `calc(100vh - ${headerHeight}px)`;
-            viewer.LoadModelFromUrlList([fileUrl]);
+
-          }
+		// Append the new container inside fileView
-        };
+		fileView.appendChild(newView3D);
-  
+
-        script.src = '/assets/o3dv/o3dv.min.js';
+		const parentDiv = document.getElementById('view-3d');
-        document.head.appendChild(script);
+		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>
 ```
@@ -248,11 +319,17 @@ mkdir o3dv
 cd o3dv
 ```
-Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.15.0 as of now).
+Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.18.0 as of now).
-Here use e.g. wget to download the file:
+Here use e.g. wget or curl to download the file:
 ```
-wget https://github.com/kovacsv/Online3DViewer/releases/download/0.15.0/o3dv.zip
+wget https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
 ```
 or
 ```
 curl -L -O https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
 ```
 Use e.g. unzip to unzip the archive:
@@ -262,20 +339,14 @@ unzip o3dv.zip
 #### Part 3: Folder permissions
-Now the last thing. Change permissions on the "footer.tmpl":
+Now the last thing. Change permissions on the public folder:
 ```
 chown git:git $GITEA_CUSTOM/templates/custom/footer.tmpl
 chmod 770 $GITEA_CUSTOM/templates/custom/footer.tmpl
 ```
 And on the public folder:
 ```
 chown -R git:git $GITEA_CUSTOM/public
 ```
 Now we have everything ready! Restart your gitea instance to apply these changes and test it in your browser.
-You should end-up with a folder structure similar to this:
+Sanity check. You should end-up with a folder structure similar to this:
 ```
 $GITEA_CUSTOM/templates
@@ -284,7 +355,7 @@ $GITEA_CUSTOM/templates
 $GITEA_CUSTOM/public/assets/
 -- o3dv
-   |-- o3dv_0.15.0.zip
+   |-- o3dv.zip
   |-- o3dv.license.md
   |-- o3dv.min.js
   |-- envmaps
@@ -325,15 +396,16 @@ Starting with Gitea 1.20, you can customize the git configuration via the `git.c
 ### Enabling signed git pushes
-To enable signed git pushes, set these two options:
+[Signed pushes](https://git-scm.com/docs/git-push#Documentation/git-push.txt---signedtruefalseif-asked) allow clients to cryptographically sign the push operation itself (not just individual commits). To enable signed pushes, add the following to `app.ini`:
 ```ini
 [git.config]
 receive.advertisePushOptions = true
 receive.certNonceSeed = <randomstring>
 ```
-`certNonceSeed` should be set to a random string and be kept secret.
+`certNonceSeed` should be set to a random string and be kept secret. It is used to generate anti-replay nonces. Gitea already sets `receive.advertisePushOptions = true` by default, so no additional configuration is needed. Note that Gitea does not read `/etc/gitconfig`, so this option must be set via `app.ini` as shown above.
 On the client side, pushes can be signed via `git push --signed` or enabled permanently using `git config --global push.gpgSign if-asked`.
 ### Labels
@@ -351,7 +423,7 @@ The [legacy file format](https://github.com/go-gitea/gitea/blob/main/options/lab
 `#hex-color label name ; label description`
-For more information, see the [labels documentation](usage/labels.md).
+For more information, see the [labels documentation](../usage/issues-prs/labels.md).
 ### Licenses
@@ -10,6 +10,10 @@ aliases:
 Gitea has mailer functionality for sending transactional emails (such as registration confirmation). It can be configured to either use Sendmail (or compatible MTAs like Postfix and msmtp) or directly use SMTP server.
 :::note
 Be sure to set ENABLE_NOTIFY_MAIL=true to allow Gitea to send email notifications. Check the [Config Cheat Sheet](../administration/config-cheat-sheet.md#service-service) for details.
 :::
 ## Using Sendmail
 Use `sendmail` command as mailer.
@@ -41,7 +45,7 @@ ENABLED        = true
 FROM           = [email protected]
 PROTOCOL       = smtps
 SMTP_ADDR      = mail.mydomain.com
-SMTP_PORT      = 587
+SMTP_PORT      = 465
 USER           = [email protected]
 PASSWD         = `password`
 ```
@@ -56,7 +60,7 @@ For the full list of options check the [Config Cheat Sheet](../administration/co
 Authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through:
 :::
- STARTTLS (also known as Opportunistic TLS) via port 587. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
+- STARTTLS (also known as Opportunistic TLS) via port 587 with `PROTOCOL=smtp+starttls`. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
 - SMTPS connection (SMTP over TLS) via the default port 465. Connection to the server use TLS from the beginning.
 - Forced SMTPS connection with `PROTOCOL=smtps`. (These are both known as Implicit TLS.)
 This is due to protections imposed by the Go internal libraries against STRIPTLS attacks.
@@ -78,6 +78,28 @@ [email protected]
 To learn more about the config values, please checkout the [Config Cheat Sheet](./config-cheat-sheet.md#server-server).
 :::warning
 `ACME_DIRECTORY` is where the account key and the issued certificates are
 cached, and the default `https` is a relative path, resolved against the working
 directory of the Gitea process. In the official Docker image that working
 directory is `/app/gitea`, which is part of the container and not of the `/data`
 volume, so every recreated container starts without an account and without
 certificates and asks the CA for new ones. Let's Encrypt allows
 [5 certificates per week](https://letsencrypt.org/docs/rate-limits/) for the
 same set of domains, after which the instance is left without a working
 certificate until the limit expires.
 Point the setting at a path inside the volume when running in a container:
 ```ini title="app.ini"
 [server]
 ACME_DIRECTORY=/data/gitea/https
 ```
 The rootless image keeps its working directory (`/var/lib/gitea`) in a volume,
 so it is only affected when that volume is not persisted.
 :::
 ## Using a reverse proxy
 Setup up your reverse proxy as shown in the [reverse proxy guide](../administration/reverse-proxies.md).
@@ -257,7 +257,6 @@ the messages. Here's a list of some of them:
 | `AppDomain`      | -           | Any       | Gitea's host name                                                   |
 | `EllipsisString` | string, int | Any       | Truncates a string to the specified length; adds ellipsis as needed |
 | `SanitizeHTML`   | string      | Body only | Sanitizes text by removing any dangerous HTML tags from it          |
 | `SafeHTML`       | string      | Body only | Takes the input as HTML, can be used for outputing raw HTML content |
 These are _functions_, not metadata, so they have to be used:
@@ -32,7 +32,7 @@ Please bear in mind that indexing the contents can consume a lot of system resou
 ### Choosing the files for indexing by size
-The `MAX_FILE_SIZE` option will make the indexer skip all files larger than the specified value.
+The `MAX_FILE_SIZE` option will make the indexer skip all files larger than the specified value in bytes.
 ### Choosing the files for indexing by path
@@ -13,7 +13,9 @@ aliases:
 1. Set `[server] ROOT_URL = https://git.example.com/` in your `app.ini` file.
 2. Make the reverse-proxy pass `https://git.example.com/foo` to `http://gitea:3000/foo`.
 3. Make sure the reverse-proxy does not decode the URI. The request `https://git.example.com/a%2Fb` should be passed as `http://gitea:3000/a%2Fb`.
-4. Make sure `Host` and `X-Fowarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
+4. Make sure `Host` and `X-Forwarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
 5. Make sure your webserver has a certificate, including all intermediate and RootCA certificates, for `git clone` and `git pull` to work.
 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.
 ### Use a sub-path
@@ -40,6 +42,7 @@ server {
    location / {
        client_max_body_size 512M;
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
@@ -66,6 +69,7 @@ server {
        rewrite ^ $request_uri;
        rewrite ^/(gitea($|/))?(.*) /$3 break;
        proxy_pass http://127.0.0.1:3000$uri;
        proxy_http_version 1.1;
        # other common HTTP headers, see the "Nginx" config section above
        proxy_set_header Connection $http_connection;
@@ -112,6 +116,7 @@ server {
    }
    location / {
        # other directives, see the "Nginx" config section above
        proxy_pass http://localhost:3000;
    }
 }
@@ -128,6 +133,7 @@ server {
    server_name git.example.com;
    location / {
        # other directives, see the "Nginx" config section above
        proxy_pass http://localhost:3000;
    }
 }
@@ -149,6 +155,20 @@ server {
 }
 ```
 ## Nginx Proxy Manager
 If you are using Nginx Proxy Manager to serve your Gitea instance it differs slighly from the raw Nginx.
 It is [adding some directives](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf) for a custom location by default, so you have to skip these from the above mentioned Nginx config. Otherwise Nginx will produce `400 bad request` error due to duplicated directives (`proxy_set_header Host $host` is the particularly problematic one).
 So while creating the `/` Custom location, just add the following line to it's configuration:
 ```nginx
 client_max_body_size 512M;
 ```
 Enable `Websockets Support` on the proxy host, Nginx Proxy Manager then adds the WebSocket directives itself. Adding `proxy_http_version` on top of that makes Nginx refuse to start.
 ## Apache HTTPD
 If you want Apache HTTPD to serve your Gitea instance, you can add the following to your Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
@@ -159,13 +179,15 @@ If you want Apache HTTPD to serve your Gitea instance, you can add the following
    ProxyPreserveHost On
    ProxyRequests off
    AllowEncodedSlashes NoDecode
-    ProxyPass / http://localhost:3000/ nocanon
+    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```
 :::note
 The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
 `upgrade=websocket` requires Apache HTTPD 2.4.48 or later. On older versions you **MUST** remove it, otherwise Apache HTTPD will not start.
 :::
 If you wish to use Let's Encrypt with webroot validation, add the line `ProxyPass /.well-known !` before `ProxyPass` to disable proxying these requests to Gitea.
@@ -183,7 +205,7 @@ In case you already have a site, and you want Gitea to share the domain name, yo
    </Proxy>
    AllowEncodedSlashes NoDecode
    # Note: no trailing slash after either /git or port
-    ProxyPass /git http://localhost:3000 nocanon
+    ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
    ProxyPreserveHost On
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
@@ -192,7 +214,55 @@ In case you already have a site, and you want Gitea to share the domain name, yo
 Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com/git/` correctly in your configuration.
 :::note
-The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
+The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`. `upgrade=websocket` requires Apache HTTPD 2.4.48 or later, remove it on older versions.
 :::
 ## Apache HTTPD and serve static resources directly
 We can tune the performance in splitting requests into categories static and dynamic.
 CSS files, JavaScript files, images and web fonts are static content.
 The front page, a repository view or issue list is dynamic content.
 Apache HTTPD can serve static resources directly and proxy only the dynamic requests to Gitea.
 Download a snapshot of the Gitea source repository to `/path/to/gitea/`.
 After this, run `make frontend` in the repository directory to generate the static resources. We are only interested in the `public/` directory for this task, so you can delete the rest.
 (You will need to have [Node with npm](https://nodejs.org/en/download/) and `make` installed to generate the static resources)
 Depending on the scale of your user base, you might want to split the traffic to two distinct servers,
 or use a cdn for the static files.
 ### Single node and single domain
 Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration.
 ```apacheconf
 <VirtualHost *:80>
    ...
    <Proxy *>
         Order allow,deny
         Allow from all
    </Proxy>
    ProxyPass /_/static/ !
    Alias /_/static/ /path/to/gitea/public/
    <Directory /path/to/gitea/public/>
        Options FollowSymlinks
 		AllowOverride None
 		Require all granted
    </Directory>
    AllowEncodedSlashes NoDecode
    # Note: no trailing slash after either /git or port
    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
    ProxyPreserveHost On
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```
 :::note
 The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`. `upgrade=websocket` requires Apache HTTPD 2.4.48 or later, remove it on older versions.
 :::
 ## Caddy
@@ -229,11 +299,13 @@ If you wish to run Gitea with IIS. You will need to setup IIS with URL Rewrite a
 - Install Application Request Routing (ARR for short) either by using the Microsoft Web Platform Installer 5.1 (WebPI) or downloading the extension from [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing)
 - Once the module is installed in IIS, you will see a new Icon in the IIS Administration Console called URL Rewrite.
 - Install the `WebSocket Protocol` Windows feature, otherwise ARR cannot proxy Gitea's WebSocket endpoint.
 - Open the IIS Manager Console and click on the `Gitea Proxy` Website from the tree view on the left. Select and double click the URL Rewrite Icon from the middle pane to load the URL Rewrite interface.
 - Choose the `Add Rule` action from the right pane of the management console and select the `Reverse Proxy Rule` from the `Inbound and Outbound Rules` category.
 - In the Inbound Rules section, set the server name to be the host that Gitea is running on with its port. e.g. if you are running Gitea on the localhost with port 3000, the following should work: `127.0.0.1:3000`
 - Enable SSL Offloading
 - In the Outbound Rules, ensure `Rewrite the domain names of the links in HTTP response` is set and set the `From:` field as above and the `To:` to your external hostname, say: `git.example.com`
 - Turn `Reverse rewrite host in response headers` off, in the `Server Proxy Settings` of Application Request Routing (select the server node in the IIS Manager, open `Application Request Routing Cache`, then `Server Proxy Settings` in the right pane). While it is on, ARR rewrites the host of the `Location` header back to the internal one, so the redirects Gitea sends after a sign-in or a form submission send the browser to `127.0.0.1:3000` instead of `git.example.com`.
 - Now edit the `web.config` for your website to match the following: (changing `127.0.0.1:3000` and `git.example.com` as appropriate)
 ```xml
@@ -6,12 +6,14 @@ aliases:
  - /en-us/signing
 ---
-# GPG Commit Signatures
+# GPG/SSH Commit Signatures
-Gitea will verify GPG commit signatures in the provided tree by
+Gitea will verify gpg/ssh commit signatures in the provided tree by
 checking if the commits are signed by a key within the Gitea database,
 or if the commit matches the default key for Git.
 Additionally Gitea will verify commits signed by ssh keys, which public keys are part of [`TRUSTED_SSH_KEYS`](#general-configuration).
 Keys are not checked to determine if they have expired or revoked.
 Keys are also not checked with keyservers.
@@ -46,6 +48,11 @@ for GPG - in particular it is probably advisable to only install a
 signing secret subkey without the master signing and certifying secret
 key.
 ## Installing and generating a SSH key for Gitea
 You can run `ssh-keygen -t ed25519 -f gitea-signing-key` to generate the private/public keypair for commit signing without any password. Usually you would store the key next to the gitea configuration, then point `SIGNING_KEY` to the generated public key `/path/to/gitea-signing-key.pub`. Gitea generates all its commits using the server `git` command at present - and therefore the server `ssh-keygen` will be used for
 signing (if configured.)
 ## General Configuration
 Gitea's configuration for signing can be found with the
@@ -65,16 +72,41 @@ MERGES = pubkey, twofa, basesigned, commitssigned
 ...
 ```
 ---
 For SSH commit signing, you need to specify the `SIGNING_FORMAT` to `ssh` instead of the default `openpgp`. `SIGNING_NAME` and `SIGNING_EMAIL` are required for verifing the signatures.
 This looks like this:
 ```ini
 ...
 [repository.signing]
 SIGNING_KEY = /path/to/gitea-signing-key.pub
 SIGNING_NAME =
 SIGNING_EMAIL =
 SIGNING_FORMAT = ssh
 INITIAL_COMMIT = always
 CRUD_ACTIONS = pubkey, twofa, parentsigned
 WIKI = never
 MERGES = pubkey, twofa, basesigned, commitssigned
 ...
 ```
 - `/path/to/gitea-signing-key` is expected to be the private key for `/path/to/gitea-signing-key.pub` [see here how to generate a new ssh keypair](#installing-and-generating-a-ssh-key-for-gitea).
 - `TRUSTED_SSH_KEYS = ssh-<algorithm> <key>` or `TRUSTED_SSH_KEYS = ssh-<algorithm> <key1>, ssh-<algorithm> <key2>` can be used for rotating the global ssh signing key to continue verifying commits signed by the previous keys.
 ### `SIGNING_KEY`
 The first option to discuss is the `SIGNING_KEY`. There are three main
 options:
 - `none` - this prevents Gitea from signing any commits
- `default` - Gitea will default to the key configured within `git config`
+- `default` - Gitea will default to the gpg key configured within `git config`
 - `KEYID` - Gitea will sign commits with the gpg key with the ID
  `KEYID`. In this case you should provide a `SIGNING_NAME` and
  `SIGNING_EMAIL` to be displayed for this key.
 - `/path/to/gitea-signing-key.pub` - Gitea will sign commits with the ssh key without the `.pub` suffix `/path/to/gitea-signing-key`. In this case you should provide a `SIGNING_NAME` and
  `SIGNING_EMAIL` to be displayed for this key and set `SIGNING_FORMAT` to `ssh`.
 The `default` option will interrogate `git config` for
 `commit.gpgsign` option - if this is set, then it will use the results
@@ -97,6 +129,10 @@ Related home files for git command (like `.gnupg`) should also be put in Gitea's
 If you like to keep the `.gnupg` directory outside of `{[git].HOME_PATH}/`, consider setting the `$GNUPGHOME` environment variable to your preferred location, otherwise Gitea will use the gpg keys only under `{[git].HOME_PATH}/.gnupg`.
 :::
 :::warning
 The default option and repository specific signing keys are not supported for ssh keys
 :::
 ### `INITIAL_COMMIT`
 This option determines whether Gitea should sign the initial commit
@@ -168,3 +204,9 @@ In cases where there is a repository specific key this can be obtained from:
 ```sh
 /api/v1/repos/:username/:reponame/signing-key.gpg
 ```
 For ssh commit signing the default ssh public key can be obtained via the API at:
 ```sh
 /api/v1/signing-key.pub
 ```
@@ -0,0 +1,9 @@
 {
  "label": "Development",
  "position": 40,
  "link": {
    "type": "generated-index",
    "slug": "/development",
    "title": "Development"
  }
 }
@@ -20,14 +20,33 @@ Gitea supports these methods of API authentication:
 - `token=...` parameter in URL query string
 - `access_token=...` parameter in URL query string
 - `Authorization: token ...` header in HTTP headers
 - HTTP signatures using an SSH public key or SSH certificate
 All of these methods accept the same API key token type. You can
 better understand this by looking at the code -- as of this writing,
 Gitea parses queries and headers to find the token in
 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
 Gitea can also authenticate API requests using an SSH key or SSH certificate via
 HTTP signatures. The SSH public key (or certificate) must be registered to the
 user account in Gitea, and the client signs requests with the corresponding
 private key. The client signs requests using the SSH private key following the
 [draft-cavage-http-signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
 specification (not RFC 9421). The signature is sent in the `Signature` header,
 and SSH certificates additionally include an `x-ssh-certificate` header. The
 official [go-sdk](https://gitea.com/gitea/go-sdk) implements this flow if you
 need a reference implementation.
 ## Generating and listing API tokens
 API tokens can be created either in the user interface or via the API. Tokens have by default limited permissions and it is important to create tokens with the correct permissions for your task.
 ### User Interface
 Tokens can be created via the `Manage Access Tokens` dialog, accessed via `User Settings` / `Applications` or via the link `gitea-domain.example/user/settings/applications`. The interface allows you to create tokens and manage their permissions via the `Select permissions` sub-menu.
 Once created, the token is displayed in a toast message above the `Manage Access Tokens` dialog. Please note, that you can view this toast only once and it is not possible to redisplay the token for security reasons.
 ### Token API
 A new token can be generated with a `POST` request to
 `/users/:name/tokens`.
@@ -35,7 +54,8 @@ Note that `/users/:name/tokens` is a special endpoint and requires you
 to authenticate using `BasicAuth` and a password, as follows:
 ```sh
-$ curl -H "Content-Type: application/json" -d '{"name":test_token","scopes":["read:activitypub","read:issue", "write:misc", "read:notification", "read:organization", "read:package", "read:repository", "read:user"]}'
+$ curl -H "Content-Type: application/json" \
 -d '{"name":"test_token","scopes":["read:activitypub","read:issue", "write:misc", "read:notification", "read:organization", "read:package", "read:repository", "read:user"]}' \
 -u 'username:password' "https://gitea.your.host/api/v1/users/{username}/tokens"
 {"id":1,"name":"test_token","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
 ```
@@ -49,6 +69,25 @@ $ curl --url https://yourusername:[email protected]/api/v1/users/<usernam
 [{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
 ```
 By default, this creates a token with very limited permissions. To complete your tasks, your token may require extra permissions. These permissions are created via the json variable `scopes`, which takes an array of permissions as strings. Eg.: `"scopes":["all"]`. Possible permissions, as reflected in the user interface are:
 - `activitypub`
 - `admin`
 - `issue`
 - `misc`
 - `notification`
 - `organization`
 - `package`
 - `repository`
 - `user`
 Each permission may be set to `read` or `write`. `write` implies both Read & Write. To set permissions you write the permissions string as `<read or write>:<permission name>`, eg.: `write:package` or `read:notification`. A properly formatted API call may look like:
 ```sh
 $ curl -H "Content-Type: application/json" -d '{"name":"test", "scopes":["write:package", "read:notification"]}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
 ```
 Special permissions `all` may be specified as `"scopes":["all"]`, which sets all permissions to both Read & Write.
 To use the API with basic authentication with two factor authentication
 enabled, you'll need to send an additional header that contains the one
 time password (6 digitrotating token).
@@ -0,0 +1,9 @@
 {
  "label": "Help",
  "position": 5,
  "link": {
    "type": "generated-index",
    "slug": "/help",
    "title": "Help"
  }
 }
@@ -33,7 +33,7 @@ then the config file (app.ini) should exists in the "custom/conf" directory of y
 Some package vendors might use "/etc/gitea" to store the config file, while some others don't.
 You could manually find the config file (app.ini) by checking Gitea's startup logs
-or reading the Gitea Web's Site Administrator -> Confugiraton Summary.
+or reading the Gitea Web's Site Administrator -> Configuration Summary.
 If you are using some isolated enviroments like container (docker),
 the path you see usually is not what it is in the host's filesystem.
@@ -13,7 +13,7 @@ Gitea was originally forked from [Gogs](https://gogs.io) and almost all the code
 :::warning
-Gitea does not sent or cherry-picked commits from upstream, so there is no guarantee it will work if you upgrade from Gogs to Gitea. The recommended method is to migrate repositories from Gogs to Gitea.
+Gitea does not send commits to upstream or cherry-pick commits from it, so there is no guarantee it will work if you upgrade from Gogs to Gitea. The recommended method is to migrate repositories from Gogs to Gitea.
 :::
@@ -31,11 +31,11 @@ You can try it out using [the online demo](https://demo.gitea.com).
 - **Code Hosting**
-  Gitea supports creating and managing repositories, browsing commit history and code files, reviewing and merging code submissions, managing collaborators, handling branches, and more. It also supports many common Git features such as tags, Cherry-pick, hooks, integrated collaboration tools, and more.
+  Gitea supports creating and managing repositories, browsing commit history and code files, reviewing and merging code submissions, managing collaborators, handling branches, and more. It also supports many common Git features such as tags, cherry-picking, hooks, integrated collaboration tools, and more.
 - **Lightweight and Fast**
-  One of Gitea's design goals is to be lightweight and fast in response. Unlike some large code hosting platforms, it remains lean, performs well in terms of speed, and is suitable for resource-limited server environments. Due to its lightweight design, Gitea has relatively low resource consumption and performs well in resource-constrained environments.
+  One of Gitea's design goals is to be lightweight and fast in response. Unlike some large code hosting platforms, it remains lean, performs well in terms of speed, and is suitable for resource-limited server environments.
 - **Easy Deployment and Maintenance**
@@ -105,6 +105,6 @@ For more detailed information, please refer to: https://docs.gitea.com/installat
  - [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
  - [github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb)
-## Integrated support
+## Integrated Support
 Please visit [Awesome Gitea](https://gitea.com/gitea/awesome-gitea/) to get more third-party integrated support
@@ -0,0 +1,9 @@
 {
  "label": "Installation",
  "position": 10,
  "link": {
    "type": "generated-index",
    "slug": "/installation",
    "title": "Installation"
  }
 }
@@ -40,19 +40,37 @@ chmod +x gitea
 Note that the above command will download Gitea @version@ for 64-bit Linux.
-## Verify GPG signature
+## Verify signature
 ### Sigstore
 Starting with v1.27 Gitea signs all binaries using [sigstore](https://sigstore.dev/) to prevent against unwanted modification of binaries.
 To validate the binary, download the bundle file which ends in `sigstore.json` for the binary you downloaded and use the [cosign](https://docs.sigstore.dev/cosign/system_config/installation/) command line tool.
 ```sh
 cosign verify-blob gitea-@version@-linux-amd64 --bundle gitea-@version@-linux-amd64.sigstore.json --certificate-oidc-issuer=https://token.actions.githubusercontent.com --certificate-identity-regexp="https://github.com/go-gitea/gitea/.github/workflows/release-.*"
 ```
 If the command outputs `Verified OK`, binary was not modified.
 :::note
 The above command will match any release workflow. You may choose to restrict the identity further by requiring a specific branch or workflow to be matched. For example this url will match only nightly builds made on main branch: `https://github.com/go-gitea/gitea/.github/workflows/release-nightly.yml@refs/heads/main`
 :::
 ### GPG
 Gitea signs all binaries with a [GPG key](https://keys.openpgp.org/search?q=teabot%40gitea.io) to prevent against unwanted modification of binaries.
 To validate the binary, download the signature file which ends in `.asc` for the binary you downloaded and use the GPG command line tool.
 ```sh
-gpg --keyserver keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
+gpg --keyserver hkps://keys.openpgp.org --recv 7C9E68152594688862D62AF62D9AE806EC1592E2
 gpg --verify gitea-@version@-linux-amd64.asc gitea-@version@-linux-amd64
 ```
 Look for the text `Good signature from "Teabot <[email protected]>"` to assert a good binary,
 despite warnings like `This key is not certified with a trusted signature!`.
 ## Recommended server configuration
 :::note
@@ -139,20 +157,27 @@ export GITEA_WORK_DIR=/var/lib/gitea/
 cp gitea /usr/local/bin/gitea
 ```
 ### Adding bash/zsh autocompletion (from 1.19)
-A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This can be copied to `/usr/share/bash-completion/completions/gitea`
+### Adding shell autocompletion (from 1.25)
 or sourced within your `.bashrc`.
-Similarly a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
+Shell completion can be generated directly from binary with:
-`.zshrc`.
+```sh
 gitea completion <shell>
 ```
-YMMV and these scripts may need further improvement.
+Supported values for `<shell>` are `bash`, `fish`, `pwsh` and `zsh`. Details on how to load the completion for your shell can be found in the completion command help.
 ## Running Gitea
 After you complete the above steps, you can run Gitea two ways:
 :::note
 On a distribution with SELinux in enforcing mode (Fedora, RHEL, CentOS Stream,
 Rocky Linux, AlmaLinux and others), the binary and the data directory need
 labels the default policy does not give them, and binding to a port below 1024
 takes an extra step. See [running Gitea with SELinux](selinux.md).
 :::
 ### 1. Creating a service file to start Gitea automatically (recommended)
 See how to create [Linux service](installation/run-as-service-in-ubuntu.md)
@@ -214,9 +239,7 @@ As of v1.8, there is a problem with the arm7 version of Gitea, and it doesn't ru
 It is recommended to switch to the arm6 version, which has been tested and shown to work on Raspberry Pis and similar devices.
-<!---
+{/* please remove after fixing the arm7 bug */}
 please remove after fixing the arm7 bug
 --->
 ### Git error after updating to a new version of Gitea
 If during the update, the binary file name has been changed to a new version of Gitea,
@@ -6,6 +6,8 @@ aliases:
  - /en-us/install-from-source
 ---
 :::warning This document is outdated, pleaes refer to [build-source.md](https://github.com/go-gitea/gitea/tree/main/docs/build-source.md):::
 # Installation from source
 You should [install go](https://go.dev/doc/install) and set up your go
@@ -125,6 +127,12 @@ launched manually from command line, it can be killed by pressing `Ctrl + C`.
 ./gitea web
 ```
 :::note
 A binary built this way carries no SELinux label of its own. On a distribution
 with SELinux in enforcing mode, see
 [running Gitea with SELinux](selinux.md) before installing it as a service.
 :::
 ## Changing default paths
 Gitea will search for a number of things from the _`CustomPath`_. By default this is
@@ -178,15 +186,14 @@ LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo
 This can be combined with `CC`, `GOOS`, and `GOARCH` as above.
-### Adding bash/zsh autocompletion (from 1.19)
+### Adding shell autocompletion (from 1.25)
-A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This should be altered as appropriate and can be `source` in your `.bashrc`
+Shell completion can be generated directly from binary with:
-or copied as `/usr/share/bash-completion/completions/gitea`.
+```sh
 gitea completion <shell>
 ```
-Similarly, a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
+Supported values for `<shell>` are `bash`, `fish`, `pwsh` and `zsh`. Details on how to load the completion for your shell can be found in the completion command help.
 `.zshrc`.
 YMMV and these scripts may need further improvement.
 ## Compile or cross-compile using Linux with Zig
@@ -41,3 +41,9 @@ 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).
@@ -12,7 +12,7 @@ You can run Gitea as a Linux service, using either systemd or supervisor. The st
 ## Using systemd
-Copy the sample [gitea.service](https://github.com/go-gitea/gitea/blob/main/contrib/systemd/gitea.service) to `/etc/systemd/system/gitea.service`, then edit the file with your favorite editor.
+Copy the sample [gitea.service](https://github.com/go-gitea/gitea/blob/main/contrib/service/systemd/gitea.service) to `/etc/systemd/system/gitea.service`, then edit the file with your favorite editor.
 Uncomment any service that needs to be enabled on this host, such as MySQL.
@@ -48,7 +48,7 @@ mkdir /home/git/gitea/log/supervisor
 ```
 Append the configuration from the sample
-[supervisord config](https://github.com/go-gitea/gitea/blob/main/contrib/supervisor/gitea) to `/etc/supervisor/supervisord.conf`.
+[supervisord config](https://github.com/go-gitea/gitea/blob/main/contrib/service/supervisor/gitea) to `/etc/supervisor/supervisord.conf`.
 Using your favorite editor, change the user (`git`) and home
 (`/home/git`) settings to match the deployment environment. Change the PORT
@@ -0,0 +1,109 @@
 ---
 date: "2026-08-13T00:00:00+00:00"
 slug: "selinux"
 sidebar_position: 45
 ---
 # Running Gitea with SELinux
 Distributions such as Fedora, RHEL, CentOS Stream, Rocky Linux and AlmaLinux
 ship SELinux in enforcing mode. Packages from a distribution repository come
 with a policy that fits them, but an installation
 [from binary](from-binary.md) or [from source](from-source.md) puts the binary
 and the data in paths the policy knows nothing about, so the labels have to be
 set by hand. The same applies to any other distribution where SELinux is
 enabled.
 Do not turn SELinux off to work around the problems below. `setenforce 0` is
 useful to confirm that a failure really comes from SELinux, but switch it back
 on with `setenforce 1` afterwards.
 ## Binding to a port below 1024
 Gitea should not run as root, and an unprivileged process may not bind to a
 port below 1024. Granting the capability to the binary with
 `setcap 'cap_net_bind_service=+ep' /usr/local/bin/gitea` is often suggested,
 but it is the least robust option:
 - file capabilities are stored in an extended attribute of the binary, so they
  are lost every time the binary is replaced, which happens on every upgrade.
 - the SELinux policy has to allow the capability for the label of the binary,
  and a binary in a path such as `/opt` usually does not carry a label that
  allows it.
 Let systemd grant the capability to the process instead. It works with SELinux
 in enforcing mode and survives upgrades, the sample unit file has the two lines
 commented out:
 ```ini title="/etc/systemd/system/gitea.service"
 [Service]
 CapabilityBoundingSet=CAP_NET_BIND_SERVICE
 AmbientCapabilities=CAP_NET_BIND_SERVICE
 ```
 Reload and restart the service afterwards:
 ```sh
 sudo systemctl daemon-reload
 sudo systemctl restart gitea
 ```
 If the capability still does not reach the process, add `PrivateUsers=false` to
 the unit: the sandboxing runs the service in a user namespace where the
 capability does not apply to the host.
 Two alternatives avoid the privileged port altogether, and are what most
 installations end up doing:
 - put a [reverse proxy](../administration/reverse-proxies.md) in front of Gitea
  and let it own ports `80` and `443`.
 - redirect the port in the firewall, for example with
  `firewall-cmd --permanent --add-forward-port=port=80:proto=tcp:toport=3000`.
 ## Labelling the binary and the data directory
 If Gitea starts but cannot read its own files, or fails in ways that are not
 explained by the file permissions, the labels are usually wrong. The tools come
 from the `policycoreutils-python-utils` package.
 Label the binary as an executable and the data directory as application state:
 ```sh
 sudo semanage fcontext -a -t bin_t '/usr/local/bin/gitea'
 sudo restorecon -v /usr/local/bin/gitea
 sudo semanage fcontext -a -t var_lib_t '/var/lib/gitea(/.*)?'
 sudo restorecon -Rv /var/lib/gitea
 ```
 `semanage fcontext` records the rule, `restorecon` applies it to the files that
 are already there. Use the two together rather than `chcon`, whose labels are
 reverted by the next relabel of the file system.
 Adjust the paths if the installation does not follow
 [installation from binary](from-binary.md); the configuration in `/etc/gitea`
 is read with the label distributions give to `/etc`, so it normally needs
 nothing.
 ## Finding out what was denied
 SELinux denials are written to the audit log, not to the Gitea log, so a
 failure often looks like a permission problem without any further explanation:
 ```sh
 sudo ausearch -m AVC -c gitea --start recent
 ```
 If a denial shows up that the rules above do not cover, turn it into a local
 policy module. Read what it allows before installing it, `audit2allow` writes
 down whatever was denied, including the things that were denied for a good
 reason:
 ```sh
 sudo ausearch -c gitea --raw | audit2allow -M gitea-local
 cat gitea-local.te
 sudo semodule -i gitea-local.pp
 ```
 If the denials point at a path Gitea should not be using at all, fix the path
 instead of allowing the access.
@@ -8,15 +8,19 @@ aliases:
 # Installation with Docker (rootless)
-Gitea provides automatically updated Docker images within its Docker Hub organization. It is
+## Relation to rootful image
 possible to always use the latest stable tag or to use another service that handles updating
 Docker images.
-The rootless image uses Gitea internal SSH to provide Git protocol and doesn't support OpenSSH.
+* Rootless image doesn't require "root" privilege on the host, while it may have stricter UID/GID requirement.
 * Rootless image must use its bulitin SSH server, while the rootful one must its managed standalone OpenSSH server.
 * The volume mapping and directory layout is different between them.
-This reference setup guides users through the setup based on `docker-compose`, but the installation
+Except the differences above, the rootless image shares the same mechanism with rootful image,
-of `docker-compose` is out of scope of this documentation. To install `docker-compose` itself, follow
+including: port mapping, custimzation, upgrading, environment variables, etc.
-the official [install instructions](https://docs.docker.com/compose/install/).
+Read more in "[Installation with Docker (rootful)](./with-docker.md)"
 ATTENTION: the rootful/rootless images are not compatible with the other.
 If you have chosen one, you should always use the same one,
 don't switch to the other one by changing the compose file's `image` value.
 ## Basics
@@ -34,8 +38,6 @@ touch docker-compose.yml
 Then paste the following content into a file named `docker-compose.yml`:
 ```yaml
 version: "2"
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@-rootless
@@ -56,116 +58,16 @@ Note that the volume should be owned by the user/group with the UID/GID specifie
 sudo chown 1000:1000 config/ data/
 ```
-> If you don't give the volume correct permissions, the container may not start.
+> If you don't give the volume correct permissions, the container may present the following errors in the logs:
 ```sh
 server-1  | 2026-03-11T12:57:50.794102045Z mkdir: can't create directory '/var/lib/gitea/git': Permission denied
 server-1  | 2026-03-11T12:57:50.796198843Z /var/lib/gitea/git is not writable
 server-1  | 2026-03-11T12:57:50.796235667Z docker setup failed
 ```
 For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly-rootless`)
 ## Custom port
 To bind the integrated ssh and the webserver on a different port, adjust
 the port section. It's common to just change the host port and keep the ports within
 the container like they are.
 ```diff
 version: "2"
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
    volumes:
      - ./data:/var/lib/gitea
      - ./config:/etc/gitea
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
 -      - "3000:3000"
 -      - "2222:2222"
 +      - "80:3000"
 +      - "22:2222"
 ```
 ## MySQL database
 To start Gitea in combination with a MySQL database, apply these changes to the
 `docker-compose.yml` file created above.
 ```diff
 version: "2"
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@-rootless
 +    environment:
 +      - GITEA__database__DB_TYPE=mysql
 +      - GITEA__database__HOST=db:3306
 +      - GITEA__database__NAME=gitea
 +      - GITEA__database__USER=gitea
 +      - GITEA__database__PASSWD=gitea
    restart: always
    volumes:
      - ./data:/var/lib/gitea
      - ./config:/etc/gitea
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:2222"
 +    depends_on:
 +      - db
 +
 +  db:
 +    image: docker.io/library/mysql:8
 +    restart: always
 +    environment:
 +      - MYSQL_ROOT_PASSWORD=gitea
 +      - MYSQL_USER=gitea
 +      - MYSQL_PASSWORD=gitea
 +      - MYSQL_DATABASE=gitea
 +    volumes:
 +      - ./mysql:/var/lib/mysql
 ```
 ## PostgreSQL database
 To start Gitea in combination with a PostgreSQL database, apply these changes to
 the `docker-compose.yml` file created above.
 ```diff
 version: "2"
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    environment:
 +      - GITEA__database__DB_TYPE=postgres
 +      - GITEA__database__HOST=db:5432
 +      - GITEA__database__NAME=gitea
 +      - GITEA__database__USER=gitea
 +      - GITEA__database__PASSWD=gitea
    restart: always
    volumes:
      - ./data:/var/lib/gitea
      - ./config:/etc/gitea
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:2222"
 +    depends_on:
 +      - db
 +
 +  db:
 +    image: docker.io/library/postgres:14
 +    restart: always
 +    environment:
 +      - POSTGRES_USER=gitea
 +      - POSTGRES_PASSWORD=gitea
 +      - POSTGRES_DB=gitea
 +    volumes:
 +      - ./postgres:/var/lib/postgresql/data
 ```
 ## Named volumes
 To use named volumes instead of host volumes, define and use the named volume
@@ -174,8 +76,6 @@ create the required volume. You don't need to worry about permissions with
 named volumes; Docker will deal with that automatically.
 ```diff
 version: "2"
 +volumes:
 +  gitea-data:
 +    driver: local
@@ -207,8 +107,6 @@ As an example to clone the host user `git` definition use the command `id -u git
 Please make sure that the mounted folders are writable by the user.
 ```diff
 version: "2"
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@-rootless
@@ -223,143 +121,3 @@ services:
      - "3000:3000"
      - "2222:2222"
 ```
 ## Startup
 :::note
 From July 2023 Compose V1 stopped receiving updates. It's also no longer available in new releases of Docker Desktop.
 Compose V2 is included with all currently supported versions of Docker Desktop. Please use V2 to do below operations.
 :::
 To start this setup based on `docker-compose`, execute `docker-compose up -d`,
 to launch Gitea in the background. Using `docker-compose ps` will show if Gitea
 started properly. Logs can be viewed with `docker-compose logs`.
 To shut down the setup, execute `docker-compose down`. This will stop
 and kill the containers. The volumes will still exist.
 :::note
 If using a non-3000 port on http, change app.ini to match
 `LOCAL_ROOT_URL = http://localhost:3000/`.
 :::
 ## Install
 After starting the Docker setup via `docker-compose`, Gitea should be available using a
 favorite browser to finalize the installation. Visit http://server-ip:3000 and follow the
 installation wizard. If the database was started with the `docker-compose` setup as
 documented above, please note that `db` must be used as the database hostname.
 ## Customization
 Customization files described [here](../administration/customizing-gitea.md) should
 be placed in `/var/lib/gitea/custom` directory. If using host volumes, it's quite easy to access these
 files; for named volumes, this is done through another container or by direct access at
 `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea`. The configuration file will be saved at
 `/etc/gitea/app.ini` after the installation.
 ## Upgrading
 :::warning
 :exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation:
 :::
 To upgrade your installation to the latest release:
 ```bash
 # Edit `docker-compose.yml` to update the version, if you have one specified
 # Pull new images
 docker-compose pull
 # Start a new container, automatically removes old one
 docker-compose up -d
 ```
 ## Upgrading from standard image
 - Backup your setup
 - Change volume mountpoint from /data to /var/lib/gitea
 - If you used a custom app.ini move it to a new volume mounted to /etc/gitea
 - Rename folder (inside volume) gitea to custom
 - Edit app.ini if needed
  - Set START_SSH_SERVER = true
 - Use image docker.gitea.com/gitea:@dockerVersion@-rootless
 ## Managing Deployments With Environment Variables
 In addition to the environment variables above, any settings in `app.ini` can be set
 or overridden with an environment variable of the form: `GITEA__SECTION_NAME__KEY_NAME`.
 These settings are applied each time the docker container starts, and won't be passed into Gitea's sub-processes.
 Full information [here](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini).
 These environment variables can be passed to the docker container in `docker-compose.yml`.
 The following example will enable a smtp mail server if the required env variables
 `GITEA__mailer__FROM`, `GITEA__mailer__HOST`, `GITEA__mailer__PASSWD` are set on the host
 or in a `.env` file in the same directory as `docker-compose.yml`.
 The settings can be also set or overridden with the content of a file by defining an environment variable of the form:
 `GITEA__section_name__KEY_NAME__FILE` that points to a file.
 ```bash
 ...
 services:
  server:
    environment:
      - GITEA__mailer__ENABLED=true
      - GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
      - GITEA__mailer__PROTOCOL=smtp
      - GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
      - GITEA__mailer__IS_TLS_ENABLED=true
      - GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
      - GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
 ```
 To set required TOKEN and SECRET values, consider using Gitea's built-in [generate utility functions](../administration/command-line.md#generate).
 # SSH Container Passthrough
 Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is to forward SSH commands from the host to the container. This setup is explained in the following.
 This guide assumes that you have created a user on the host called `git` with permission to run `docker exec`, and that the Gitea container is called `gitea`. You will need to modify that user's shell to forward the commands to the `sh` executable inside the container, using `docker exec`.
 First, create the file `/usr/local/bin/gitea-shell` on the host, with the following contents:
 ```bash
 #!/bin/sh
 /usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
 ```
 Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that.
 You should also make sure that you’ve set the permissions of the shell wrapper correctly:
 ```bash
 sudo chmod +x /usr/local/bin/gitea-shell
 ```
 Once the wrapper is in place, you can make it the shell for the `git` user:
 ```bash
 sudo usermod -s /usr/local/bin/gitea-shell git
 ```
 Now that all the SSH commands are forwarded to the container, you need to set up the SSH authentication on the host. This is done by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea. Add the following block to `/etc/ssh/sshd_config`, on the host:
 ```bash
 Match User git
  AuthorizedKeysCommandUser git
  AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
 ```
 (From 1.16.0 you will not need to set the `-c /etc/gitea/app.ini` option.)
 All that is left to do is restart the SSH server:
 ```bash
 sudo systemctl restart sshd
 ```
 **Notes**
 This isn't actually using the docker SSH - it is simply using the commands around it.
 You could theoretically not run the internal SSH server.
@@ -12,9 +12,16 @@ Gitea provides automatically updated Docker images within its Docker Hub organiz
 possible to always use the latest stable tag or to use another service that handles updating
 Docker images.
-This reference setup guides users through the setup based on `docker-compose`, but the installation
+This reference setup guides users through the setup based on `docker compose`.
-of `docker-compose` is out of scope of this documentation. To install `docker-compose` itself, follow
+Docker compose has been included in the Docker Engine since the shift to Compose v2.
-the official [install instructions](https://docs.docker.com/compose/install/).
+If, for some reason, compose is not available on your system, follow the official [install instructions](https://docs.docker.com/compose/install/).
 This document targets for the default rootful image. For the rootless image,
 see "[Installation with Docker (rootless)](./with-docker-rootless.md)"
 ATTENTION: the rootful/rootless images are not compatible with the other.
 If you have chosen one, you should always use the same one,
 don't switch to the other one by changing the compose file's `image` value.
 ## Basics
@@ -26,8 +33,6 @@ If you don't give the volume correct permissions, the container may not start.
 For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly`)
 ```yaml
 version: "3"
 networks:
  gitea:
    external: false
@@ -58,8 +63,6 @@ the port section. It's common to just change the host port and keep the ports wi
 the container like they are.
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
@@ -93,8 +96,6 @@ To start Gitea in combination with a MySQL database, apply these changes to the
 `docker-compose.yml` file created above.
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
@@ -143,9 +144,14 @@ services:
 To start Gitea in combination with a PostgreSQL database, apply these changes to
 the `docker-compose.yml` file created above.
-```diff
+:::note
-version: "3"
+The example pins a major version on purpose: PostgreSQL does not upgrade its data
 directory on its own, moving to a newer major version later requires `pg_upgrade`
 or a dump and restore. Start a new instance on the newest version Gitea supports,
 see [database preparation](database-preparation.md) for the supported versions.
 :::
 ```diff
 networks:
  gitea:
    external: false
@@ -176,7 +182,7 @@ services:
 +      - db
 +
 +  db:
-+    image: docker.io/library/postgres:14
+    image: docker.io/library/postgres:18
 +    restart: always
 +    environment:
 +      - POSTGRES_USER=gitea
@@ -196,8 +202,6 @@ create the required volume. You don't need to worry about permissions with
 named volumes; Docker will deal with that automatically.
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
@@ -227,17 +231,11 @@ MySQL or PostgreSQL containers will need to be created separately.
 ## Startup
-:::note
+To start this setup based on `docker compose`, execute `docker compose up -d`,
-From July 2023 Compose V1 stopped receiving updates. It's also no longer available in new releases of Docker Desktop.
+to launch Gitea in the background. Using `docker compose ps` will show if Gitea
 started properly. Logs can be viewed with `docker compose logs`.
-Compose V2 is included with all currently supported versions of Docker Desktop. Please use V2 to do below operations.
+To shut down the setup, execute `docker compose down`. This will stop
 :::
 To start this setup based on `docker-compose`, execute `docker-compose up -d`,
 to launch Gitea in the background. Using `docker-compose ps` will show if Gitea
 started properly. Logs can be viewed with `docker-compose logs`.
 To shut down the setup, execute `docker-compose down`. This will stop
 and kill the containers. The volumes will still exist.
 :::note
@@ -247,9 +245,9 @@ If using a non-3000 port on http, change app.ini to match
 ## Installation
-After starting the Docker setup via `docker-compose`, Gitea should be available using a
+After starting the Docker setup via `docker compose`, Gitea should be available using a
 favorite browser to finalize the installation. Visit http://server-ip:3000 and follow the
-installation wizard. If the database was started with the `docker-compose` setup as
+installation wizard. If the database was started with the `docker compose` setup as
 documented above, please note that `db` must be used as the database hostname.
 ## Configure the user inside Gitea using environment variables
@@ -279,17 +277,18 @@ To upgrade your installation to the latest release:
 ```bash
 # Edit `docker-compose.yml` to update the version, if you have one specified
 # Pull new images
-docker-compose pull
+docker compose pull
 # Start a new container, automatically removes old one
-docker-compose up -d
+docker compose up -d
 ```
 ## Managing Deployments With Environment Variables
 In addition to the environment variables above, any settings in `app.ini` can be set
-or overridden with an environment variable of the form: `GITEA__SECTION_NAME__KEY_NAME`.
+or overridden with an environment variable of the form: `GITEA__section_name__KEY_NAME=value`.
-These settings are applied each time the docker container starts, and won't be passed into Gitea's sub-processes.
+These settings are applied each time the docker container starts by `environment-to-ini` command
-Full information [here](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini).
+(a warpper of `gitea config edit-ini`), and won't be passed into Gitea's sub-processes.
 See `./gitea config edit-ini --help` for more details.
 These environment variables can be passed to the docker container in `docker-compose.yml`.
 The following example will enable an smtp mail server if the required env variables
@@ -331,320 +330,7 @@ services:
      - GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
 ```
 ## SSH Container Passthrough
 Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker. Alternatively, if the host machine has more than one IP address, the host can listen on one and Gitea on another.
 ### Understanding SSH access to Gitea (without passthrough)
 To understand what needs to happen, you first need to understand what happens without passthrough. So we will try to explain this:
 1. The client adds their SSH public key to Gitea using the webpage.
 2. Gitea will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
 3. This entry has the public key, but also has a `command=` option. It is this command that Gitea uses to match this key to the client user and manages authentication.
 4. The client then makes an SSH request to the SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
 5. The client will attempt to authenticate with the server, passing one or more public keys one at a time to the server.
 6. For each key the client provides, the SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the `git` user's `authorized_keys` file.
 7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
 8. The SSH server creates a user session for the `git` user, and using the shell for the `git` user runs the `command=`
 9. This runs `gitea serv` which takes over control of the rest of the SSH session and manages gitea authentication & authorization of the git commands.
 Now, for the SSH passthrough to work, we need the host SSH to match the public keys and then run the `gitea serv` on the docker. There are multiple ways of doing this. However, all of these require some information about the docker being passed to the host.
 ### SSHing Shim (with authorized_keys)
 In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 9 the `gitea` command that the host runs is a shim that actually runs ssh to go into the docker and then run the real docker `gitea` itself.
 - To make the forwarding work, the SSH port of the container (22) needs to be mapped to the host port 2222 in `docker-compose.yml` . Since this port does not need to be exposed to the outside world, it can be mapped to the `localhost` of the host machine:
  ```yaml
  ports:
    # [...]
    - "127.0.0.1:2222:22"
  ```
 - Next on the host create the `git` user which shares the same `UID`/ `GID` as the container values `USER_UID`/ `USER_GID`. These values can be set as environment variables in the `docker-compose.yml`:
  ```yaml
  environment:
    - USER_UID=1000
    - USER_GID=1000
  ```
 - Mount `/home/git/.ssh` of the host into the container. This ensures that the `authorized_keys` file is shared between the host `git` user and the container `git` user otherwise the SSH authentication cannot work inside the container.
  ```yaml
  volumes:
    - /home/git/.ssh/:/data/git/.ssh
  ```
 - Now a SSH key pair needs to be created on the host. This key pair will be used to authenticate the `git` user on the host to the container. As an administrative user on the host run: (by administrative user we mean a user that can sudo to root)
  ```bash
  sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
  ```
 - Please note depending on the local version of ssh you may want to consider using `-t ecdsa` here.
 - `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `~/git/.ssh/authorized_keys`. As an administrative user on the host run:
  ```bash
  sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
  sudo -u git chmod 600 /home/git/.ssh/authorized_keys
  ```
  Important: The pubkey from the `git` user needs to be added "as is" while all other pubkeys added via the Gitea web interface will be prefixed with `command="/usr [...]`.
  `/home/git/.ssh/authorized_keys` should then look somewhat like
  ```bash
  # SSH pubkey from git user
  ssh-rsa <Gitea Host Key>
  # other keys from users
  command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
  ```
 - The next step is to create the fake host `gitea` command that will forward commands from the host to the container. The name of this file depends on your version of Gitea:
  - For Gitea v1.16.0+. As an administrative user on the host run:
    ```bash
    cat <<"EOF" | sudo tee /usr/local/bin/gitea
    #!/bin/sh
    ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
    EOF
    sudo chmod +x /usr/local/bin/gitea
    ```
 Here is a detailed explanation what is happening when a SSH request is made:
 1. The client adds their SSH public key to Gitea using the webpage.
 2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
    - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
 3. This entry has the public key, but also has a `command=` option.
    - This command matches the location of the Gitea binary on the container, but also the location of the shim on the host.
 4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
 5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
 6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
    - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
 7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
 8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
 9. This means that the host runs the host `/usr/local/bin/gitea` shim that opens an SSH from the host to container passing the rest of the command arguments directly to `/usr/local/bin/gitea` on the container.
 10. Meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
 **Notes**
 SSH container passthrough using `authorized_keys` will work only if
 - `opensshd` is used in the container
 - if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
 - `LOCAL_ROOT_URL` is not changed (depending on the changes)
 If you try to run `gitea` on the host, you will attempt to ssh to the container and thence run the `gitea` command there.
 Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
 ### SSHing Shell (with authorized_keys)
 In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 8 above we change the shell that the host runs to ssh directly into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
 - In this case we setup as per SSHing Shim except instead of creating `/usr/local/bin/gitea`
 we create a new shell for the git user. As an administrative user on the host run:
  ```bash
  cat <<"EOF" | sudo tee /home/git/ssh-shell
  #!/bin/sh
  shift
  ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $@"
  EOF
  sudo chmod +x /home/git/ssh-shell
  sudo usermod -s /home/git/ssh-shell git
  ```
  Be careful here - if you try to login as the git user in future you will ssh directly to the docker.
 Here is a detailed explanation what is happening when a SSH request is made:
 1. The client adds their SSH public key to Gitea using the webpage.
 2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
    - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
 3. This entry has the public key, but also has a `command=` option.
    - This command matches the location of the Gitea binary on the container.
 4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
 5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
 6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
    - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
 7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
 8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
 9. The shell of the host `git` user is now our `ssh-shell` which opens an SSH connection from the host to container, (which opens a shell on the container for the container `git`).
 10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
 **Notes**
 SSH container passthrough using `authorized_keys` will work only if
 - `opensshd` is used in the container
 - if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
 - `LOCAL_ROOT_URL` is not changed (depending on the changes)
 If you try to login as the `git` user on the host in future you will ssh directly to the docker.
 Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
 ### Docker Shell (with authorized_keys)
 Similar to the above ssh shell technique we can use a shell which simply uses `docker exec`. As an administrative user on the host run:
 ```bash
 cat <<"EOF" | sudo tee /home/git/docker-shell
 #!/bin/sh
 /usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
 EOF
 sudo chmod +x /home/git/docker-shell
 sudo usermod -s /home/git/docker-shell git
 ```
 Here is a detailed explanation what is happening when a SSH request is made:
 1. The client adds their SSH public key to Gitea using the webpage.
 2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
    - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
 3. This entry has the public key, but also has a `command=` option.
    - This command matches the location of the Gitea binary on the container.
 4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
 5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
 6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
    - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
 7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
 8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
 9. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
 10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
 Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that. The host `git` user also has to have
 permission to run `docker exec`.
 **Notes**
 Docker shell passthrough using `authorized_keys` will work only if
 - `opensshd` is used in the container
 - if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
 - `LOCAL_ROOT_URL` is not changed (depending on the changes)
 If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
 A Docker execing shim could be created similarly to above.
 ### Docker Shell with AuthorizedKeysCommand
 The AuthorizedKeysCommand route provides another option that does not require many changes to the compose file or the `authorized_keys` - but does require changes to the host `/etc/sshd_config`.
 In this option, the idea is that the host SSH uses an `AuthorizedKeysCommand` instead of relying on sharing the `authorized_keys` file that gitea creates. We continue to use a special shell at step 8 above to exec into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
 - On the host create a `git` user with permission to run `docker exec`.
 - We will again assume that the Gitea container is called `gitea`.
 - Modify the `git` user's shell to forward commands to the `sh` executable inside the container using `docker exec`.  As an administrative user on the host run:
  ```bash
  cat <<"EOF" | sudo tee /home/git/docker-shell
  #!/bin/sh
  /usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
  EOF
  sudo chmod +x /home/git/docker-shell
  sudo usermod -s /home/git/docker-shell git
  ```
 Now all attempts to login as the `git` user on the host will be forwarded to the docker - including the `SSH_ORIGINAL_COMMAND`. We now need to set-up SSH authentication on the host.
 We will do this by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea.
 Add the following block to `/etc/ssh/sshd_config`, on the host:
 ```bash
 Match User git
  AuthorizedKeysCommandUser git
  AuthorizedKeysCommand /usr/bin/docker exec -i -u git gitea /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
 ```
 (From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
 Finally restart the SSH server. As an administrative user on the host run:
 ```bash
 sudo systemctl restart sshd
 ```
 Here is a detailed explanation what is happening when a SSH request is made:
 1. The client adds their SSH public key to Gitea using the webpage.
 2. Gitea in the container will add an entry for this key to its database.
 3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
 4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
 5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
 6. The host runs the above `AuthorizedKeysCommand`, which execs in to the docker and then runs the `gitea keys` command.
 7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
 8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
 9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
 10. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
 11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
 **Notes**
 Docker shell passthrough using `AuthorizedKeysCommand` will work only if
 - The host `git` user is allowed to run the `docker exec` command.
 If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
 A Docker execing shim could be created similarly to above.
 ### SSH Shell with AuthorizedKeysCommand
 Create a key for the host `git` user as above, add it to the docker `/data/git/.ssh/authorized_keys` then finally create and set the `ssh-shell` as above.
 Add the following block to `/etc/ssh/sshd_config`, on the host:
 ```bash
 Match User git
  AuthorizedKeysCommandUser git
  AuthorizedKeysCommand /usr/bin/ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
 ```
 (From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
 Finally restart the SSH server. As an administrative user on the host run:
 ```bash
 sudo systemctl restart sshd
 ```
 Here is a detailed explanation what is happening when a SSH request is made:
 1. The client adds their SSH public key to Gitea using the webpage.
 2. Gitea in the container will add an entry for this key to its database.
 3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
 4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
 5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
 6. The host runs the above `AuthorizedKeysCommand`, which will SSH in to the docker and then run the `gitea keys` command.
 7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
 8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
 9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
 10. The shell of the host `git` user is now our `git-shell` which uses SSH to open a shell for the `git` user on the container.
 11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
 **Notes**
 SSH container passthrough using `AuthorizedKeysCommand` will work only if
 - `opensshd` is running on the container
 If you try to login as the `git` user on the host in future you will `ssh` directly to the docker.
 Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
 SSHing shims could be created similarly to above.
 ### SSH with multiple IP addresses
 This assumes that the host machine has more than one reachable IP address: `192.168.1.1` (host) `192.168.1.2` (gitea)
 On the host machine, configure SSHD in `/etc/ssh/sshd_config` to listen on one IP address `ListenAddress 192.168.1.1`. In the compose file the SSH port forwarding then needs to be changed to `"192.168.1.2:22:22"`. The port forwarding needs to be adjusted similarily for all other forwarded ports to avoid problems with DNS.
@@ -0,0 +1,9 @@
 {
  "label": "Usage",
  "position": 35,
  "link": {
    "type": "generated-index",
    "slug": "/usage",
    "title": "Usage"
  }
 }
@@ -0,0 +1,9 @@
 {
  "label": "Access Control",
  "position": 100,
  "link": {
    "type": "generated-index",
    "slug": "/usage/access-control",
    "description": "Permissions, security, and access control features"
  }
 }
@@ -0,0 +1,47 @@
 ---
 date: "2024-01-31T00:00:00+00:00"
 slug: "blocking-user"
 sidebar_position: 25
 aliases:
  - /blocking-user
 ---
 # Blocking a user
 Gitea supports blocking of users to restrict how they can interact with you and your content.
 You can block a user in your account settings, from the user's profile or from comments created by the user.
 The user is not directly notified about the block, but they can notice they are blocked when they attempt to interact with you.
 Organization owners can block anyone who is not a member of the organization too.
 If a blocked user has admin permissions, they can still perform all actions even if blocked.
 ### When you block a user
 - the user stops following you
 - you stop following the user
 - the user's stars are removed from your repositories
 - your stars are removed from their repositories
 - the user stops watching your repositories
 - you stop watching their repositories
 - the user's issue assignments are removed from your repositories
 - your issue assignments are removed from their repositories
 - the user is removed as a collaborator on your repositories
 - you are removed as a collaborator on their repositories
 - any pending repository transfers to or from the blocked user are canceled
 ### When you block a user, the user cannot
 - follow you
 - watch your repositories
 - star your repositories
 - fork your repositories
 - transfer repositories to you
 - open issues or pull requests on your repositories
 - comment on issues or pull requests you've created
 - comment on issues or pull requests on your repositories
 - react to your comments on issues or pull requests
 - react to comments on issues or pull requests on your repositories
 - assign you to issues or pull requests
 - add you as a collaborator on their repositories
 - send you notifications by @mentioning your username
 - be added as team member (if blocked by an organization)
@@ -1,11 +1,10 @@
 ---
 date: "2021-12-13:10:10+08:00"
 slug: "permissions"
 sidebar_position: 14
 aliases:
  - /en-us/permissions
  - /permissions
 ---
 # Permissions
@@ -41,7 +40,7 @@ With different permissions, people could do different things with these units.
 | Wiki            | View wiki pages. Clone the wiki repository.        | Create/Edit wiki pages, push | -                         |
 | ExternalWiki    | Link to an external wiki                           | -                            | -                         |
 | ExternalTracker | Link to an external issue tracker                  | -                            | -                         |
-| Projects        | View the boards                                    | Change issues across boards  | -                         |
+| Projects        | View the columns of projects                       | Change issues across columns | -                         |
 | Packages        | View the packages                                  | Upload/Delete packages       | -                         |
 | Actions         | View the Actions logs                              | Approve / Cancel / Restart   | -                         |
 | Settings        | -                                                  | -                            | Manage the repository     |
@@ -0,0 +1,90 @@
 ---
 date: "2025-11-20T00:00:00-07:00"
 slug: "protected-branches"
 sidebar_position: 44
 aliases:
  - /en-us/protected-branches
  - /en-us/protected-branch
  - /protected-branches
 ---
 # Protected branches
 Protected branches prevent unwanted changes by enforcing push and merge policies on selected branches. The rules are enforced for every Git protocol (HTTP(S), SSH), the web editor, the API, and background jobs such as auto-merge. Only repository owners and administrators can manage the rules, and the Branches page is read-only while a repository is archived.
 ## Creating or editing a rule
 1. Open the repository and select **Settings → Branches** (repository admin permission required).
 2. Select **Add new rule** or **Edit** next to an existing rule.
 3. Fill in the **Protected branch name pattern** and optional file patterns, then configure the push, merge, and review options described below.
 4. Select **Save rule**.
 The rule immediately applies to all matching branches, even if the branches are created in the future.
 ## Rule matching and priorities
 - The **Protected branch name pattern** accepts [glob](https://github.com/gobwas/glob) expressions and matches the entire branch name. Patterns are case-sensitive. Using a simple name such as `main` without glob special characters always matches that specific branch (case-insensitive).
 - If multiple rules match the same branch, only the first rule is used. Reorder the list on the **Branches** page by dragging the grab handle. The first entry (priority 1) has the highest priority, so place patterns such as `main` or `release/*` before generic fallbacks such as `*`.
 Example patterns:
 | Pattern        | Matches                         |
 | -------------- | ------------------------------- |
 | `main`         | The `main` branch only          |
 | `release/*`    | `release/v1.0`, `release/april` |
 | `hotfix/**`    | Nested branches such as `hotfix/security/CVE` |
 | `*`            | Every branch (use as a fallback) |
 ### File-level pattern controls
 - **Protected file patterns** block changes to sensitive files (for example `.drone.yml` or `/docs/**/*.txt`). Patterns are case-insensitive and separated by semicolons. Commits and merge attempts that touch one of the files are rejected.
 - **Unprotected file patterns** do the opposite: if pushes are blocked, users with write access can still push commits that modify only the listed files. This is useful for letting contributors update documentation while still requiring pull requests for code.
 Both fields use the same `glob` syntax and match paths relative to the repository root.
 ## Controlling direct pushes
 The **Push** section controls direct pushes (including the web editor and API).
 - **Disable push** makes the branch read-only. Any attempt to push directly fails, and changes must be merged through pull requests.
 - **Enable push** allows anyone with [write access](./permissions.md) to push (force pushes are still blocked unless explicitly allowed).
 - **Allowlist restricted push** requires being on the allowlist. Choose users and, for organization-owned repositories, teams. Deploy keys that already have write access can also be allowlisted.
 When a push is blocked, the server-side hook rejects the update with an explanation.
 ### Force pushes
 Force pushes have their own set of options:
 - **Disable force push** completely forbids rewriting history on the branch.
 - **Enable force push** allows anyone who can push to also force push.
 - **Allowlist restricted force push** limits force pushes to a separate allowlist (users, teams, and optionally deploy keys) **and** requires the person to already have regular push access.
 ## Pull request merges and approvals
 - **Merge allowlist**: keep the default to let anyone with write access merge pull requests, or enable the allowlist to restrict merges to selected users/teams.
 - **Required approvals**: specify how many approvals are needed before a merge is allowed. Reviews from users with write access count, unless the **Restrict approvals to allowlisted users or teams** option is enabled.
 - **Dismiss stale approvals** removes existing approvals whenever new commits that change the pull request content are pushed.
 - **Ignore stale approvals** keeps approvals but does not count reviews that were made on older commits. This option is disabled while dismissal of stale approvals is enabled.
 - **Block merge on rejected reviews** prevents merging while any official reviewer has requested changes.
 - **Block merge on official review requests** blocks merges while there are outstanding review requests (for example when CODEOWNERS requires a review).
 - **Block merge if the pull request is outdated** makes sure the head branch is up to date with the base branch before it can be merged.
 - **Administrators must follow branch protection rules** removes the ability for repository administrators to bypass the rules with the "Force merge" button.
 Protected file patterns apply to pull requests as well. When a pull request changes one of the protected files, the pull request banner shows the affected paths and merging stays disabled.
 ## Status checks
 Enable status checks to require one or more CI jobs to succeed before merging:
 1. Check **Enable status check**.
 2. Enter one pattern per line in **Status check patterns**. Each pattern is a `glob` expression that matches the context name reported by Actions, Drone, Woodpecker, or another Check API client (for example `actions/test-*`).
 3. Pick contexts from the table of jobs that have reported results in the last week to verify their names.
 When the option is active, Gitea requires at least one context that matches each pattern to report success on the pull request head commit. An empty list is not allowed; use `*` to require the latest commit to be successful regardless of the context name.
 ## Signed commits and other safeguards
 - **Require signed commits** rejects pushes that contain unsigned or unverifiable commits. The check runs inside the server hook before the push is accepted.
 - **Protected file patterns** (see above) prevent both pushes and merges that modify sensitive files.
 - **Unprotected file patterns** allow limited pushes while keeping the branch protected.
@@ -4,6 +4,7 @@ slug: "protected-tags"
 sidebar_position: 45
 aliases:
  - /en-us/protected-tags
  - /protected-tags
 ---
 # Protected tags
@@ -0,0 +1,9 @@
 {
  "label": "Actions",
  "position": 30,
  "link": {
    "type": "generated-index",
    "slug": "/usage/actions",
    "description": "Automating workflows with Actions"
  }
 }
@@ -0,0 +1,28 @@
 ---
 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 a new 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:
 - are available only to signed-in users who can access the Actions run;
 - render text-based files and PDFs;
 - run HTML and JavaScript content in a sandboxed frame; and
 - label the rendered content as automatically generated by Gitea Actions.
 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.
@@ -26,38 +26,6 @@ Github Actions doesn't support that. https://docs.github.com/en/actions/using-wo
 ## Unsupported workflows syntax
 ### `concurrency`
 It's used to run a single job at a time.
 See [Using concurrency](https://docs.github.com/en/actions/using-jobs/using-concurrency).
 It's ignored by Gitea Actions now.
 ### `run-name`
 The name for workflow runs generated from the workflow.
 See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#run-name).
 It's ignored by Gitea Actions now.
 ### `permissions` and `jobs.<job_id>.permissions`
 See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions).
 It's ignored by Gitea Actions now.
 ### `jobs.<job_id>.timeout-minutes`
 See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes).
 It's ignored by Gitea Actions now.
 ### `jobs.<job_id>.continue-on-error`
 See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error).
 It's ignored by Gitea Actions now.
 ### `jobs.<job_id>.environment`
 See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment).
@@ -68,7 +36,12 @@ It's ignored by Gitea Actions now.
 See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
-Gitea Actions only supports `runs-on: xyz` or `runs-on: [xyz]` now.
+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
@@ -93,7 +66,7 @@ It's ignored by Gitea Actions now.
 ### Expressions
-For [expressions](https://docs.github.com/en/actions/learn-github-actions/expressions), only [`always()`](https://docs.github.com/en/actions/learn-github-actions/expressions#always) is supported.
+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
@@ -107,6 +80,15 @@ Services steps don't have their own section in the job log user interface.
 ## Different behavior
 ### Job token permissions (`permissions`)
 Gitea supports `permissions` and `jobs.<job_id>.permissions` to control the default `GITEA_TOKEN` permissions.
 The effective permissions are clamped by the repository/owner settings and are further restricted for fork pull requests and cross-repository access.
 GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not supported, while Gitea-specific scopes such as `code`, `releases`, `wiki`, and `projects` are available.
 See [Actions job token permissions](token-permissions.md).
 ### Downloading actions
 Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.
@@ -8,33 +8,9 @@ sidebar_position: 140
 Gitea Actions has multiple components. This document describes them individually.
-## Act
+## Gitea Runner
-The [nektos/act](https://github.com/nektos/act) project is an excellent tool that allows you to run your GitHub Actions locally.
+Gitea Runner is based on a hard fork of [nektos/act](https://github.com/nektos/act).
 We were inspired by this and wondered if it would be possible to run actions for Gitea.
 However, while [nektos/act](https://github.com/nektos/act) is designed as a command line tool, what we actually needed was a Go library with modifications specifically for Gitea.
 So we forked it as [gitea/act](https://gitea.com/gitea/act).
 This is a soft fork that will periodically follow the upstream.
 Although some custom commits have been added, we will try our best to avoid changing too much of the original code.
 The forked act is just a shim or adapter for Gitea's specific usage.
 There are some additional commits that have been made, such as:
 - Outputting execution logs to logger hook so they can be reported to Gitea
 - Disabling the GraphQL URL, since Gitea doesn't support it
 - Starting a new container for every job instead of reusing to ensure isolation.
 These modifications have no reason to be merged into the upstream.
 They don't make sense if the user just wants to run trusted actions locally.
 However, there may be overlaps in the future, such as a required bug fix or new feature needed by both projects.
 In these cases, we will contribute the changes back to the upstream repository.
 ## Act runner
 Gitea's runner is called act runner because it's based on act.
 Like other CI runners, we designed it as an external part of Gitea, which means it should run on a different server than Gitea.
@@ -47,7 +23,7 @@ That's why when you add custom labels during registration, you will need to inpu
 This means that the runner can take the job which needs to run on `my_custom_label`, and it will run it via a docker container with the image `centos:7`.
 Docker isn't the only option, though.
-The act also supports running jobs directly on the host.
+The runner also supports running jobs directly on the host.
 This is achieved through labels like `linux_arm:host`.
 This label indicates that the runner can take a job that needs to run on `linux_arm` and run it directly on the host.
@@ -62,7 +38,7 @@ So,
 ## Communication protocol
-As act runner is an independent part of Gitea, we needed a protocol for runners to communicate with the Gitea instance.
+As the runner is an independent part of Gitea, we needed a protocol for runners to communicate with the Gitea instance.
 However, we did not think it was a good idea to have Gitea listen on a new port.
 Instead, we wanted to reuse the HTTP port, which means we needed a protocol that is compatible with HTTP.
 We chose to use gRPC over HTTP.
@@ -79,9 +55,9 @@ This will help you troubleshoot some problems and explain why it's a bad idea to
 There are four network connections marked in the picture, and the direction of the arrows indicates the direction of establishing the connections.
-### Connection 1, act runner to Gitea instance
+### Connection 1, runner to Gitea instance
-The act runner must be able to connect to Gitea to receive tasks and send back the execution results.
+The runner must be able to connect to Gitea to receive tasks and send back the execution results.
 ### Connection 2, job containers to Gitea instance
@@ -92,9 +68,9 @@ Fetching code is not always necessary to run some jobs, but it is required in mo
 If you use a loopback address to register a runner, the runner can connect to Gitea when it is on the same machine.
 However, if a job container tries to fetch code from localhost, it will fail because Gitea is not in the same container.
-### Connection 3, act runner to internet
+### Connection 3, runner to internet
-When you use some actions like `actions/checkout@v4`, the act runner downloads the scripts, not the job containers.
+When you use some actions like `actions/checkout@v4`, the runner downloads the scripts, not the job containers.
 By default, it downloads from [github.com](http://github.com/), so it requires access to the internet. If you configure the `DEFAULT_ACTIONS_URL` to `self`, then it will download from your Gitea instance by default. Then it will not connect to internet when downloading the action itself.
 It also downloads some docker images from Docker Hub by default, which also requires internet access.
@@ -55,7 +55,7 @@ If you want to give more permissions to the runner, allowing it to access more p
 Refined permission control to Actions is a complicated job.
 In the future, we will add more options to Gitea to make it more configurable, such as allowing more write access to repositories or read access to all repositories in the same organization.
-## Which operating systems are supported by act runner?
+## Which operating systems are supported by Gitea Runner?
 We released official binaries for Linux, macOS, and Windows.
 While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
@@ -101,7 +101,7 @@ It is exciting to be able to reuse them.
 This is valid syntax.
 It means that it should run on runners that have both the `label_a` **and** `label_b` labels, see [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
-Unfortunately, act runner does not work this way until v0.2.11.
+Unfortunately, the runner does not work this way until v0.2.11.
 As mentioned, we map labels to environments:
 - `ubuntu` → `ubuntu:22.04`
@@ -117,9 +117,9 @@ We also need to re-design how tasks are assigned to runners.
 A runner with `ubuntu`, `centos`, or `with-gpu` does not necessarily indicate that it can accept jobs with `[centos, with-gpu]`.
 Therefore, the runner should inform the Gitea instance that it can only accept jobs with `[ubuntu]`, `[centos]`, `[with-gpu]`, and `[ubuntu, with-gpu]`.
 This is not a technical problem, it was just overlooked in the early design.
-See [runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
+See [runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
-Currently, the act runner attempts to match everyone in the labels and uses the first match it finds.
+Currently, the runner attempts to match everyone in the labels and uses the first match it finds.
 ## What is the difference between agent labels and custom labels for a runner?
@@ -132,37 +132,48 @@ However, the design here needs improvement, as it currently has some rough edges
 You can add a custom label such as `centos` to a registered runner, which means the runner will receive jobs with `runs-on: centos`.
 However, the runner may not know which environment to use for this label, resulting in it using a default image or leading to a logical dead end.
 This default may not match user expectations.
-See [runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71).
+See [runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71).
 In the meantime, we suggest that you re-register your runner if you want to change its labels.
 ## Will there be more implementations for Gitea Actions runner?
-Although we would like to provide more options, our limited manpower means that act runner will be the only officially supported runner at the moment.
+Although we would like to provide more options, our limited manpower means that Gitea Runner will be the only officially supported runner at the moment.
-However, both Gitea and act runner are completely open source under MIT License, so anyone can modify the code to satisfy their requirements.
+However, both Gitea and Gitea Runner are completely open source under MIT License, so anyone can modify the code to satisfy their requirements.
-In case you fork act runner to create your own version: Please contribute the changes back if you can and if you think your changes will help others as well.
+In case you fork Gitea Runner to create your own version: Please contribute the changes back if you can and if you think your changes will help others as well.
 ## What workflow trigger events does Gitea support?
 All events listed in this table are supported events and are compatible with GitHub.
 For events supported only by GitHub, see GitHub's [documentation](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows).
-| trigger event               | activity types                                                                                                           |
+| trigger event                                | activity types                                                                                                                                                             |
-|-----------------------------|--------------------------------------------------------------------------------------------------------------------------|
+|----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| create                      | not applicable                                                                                                           |
+| create                                       | not applicable                                                                                                                                                             |
-| delete                      | not applicable                                                                                                           |
+| delete                                       | not applicable                                                                                                                                                             |
-| fork                        | not applicable                                                                                                           |
+| fork                                         | not applicable                                                                                                                                                             |
-| gollum                      | not applicable                                                                                                           |
+| gollum                                       | not applicable                                                                                                                                                             |
-| push                        | not applicable                                                                                                           |
+| push                                         | not applicable                                                                                                                                                             |
-| issues                      | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
+| schedule                                     | not applicable                                                                                                                                                             |
-| issue_comment               | `created`, `edited`, `deleted`                                                                                           |
+| workflow_dispatch                            | not applicable                                                                                                                                                             |
-| pull_request                | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled`                |
+| workflow_call                                | not applicable                                                                                                                                                             |
-| pull_request_review         | `submitted`, `edited`                                                                                                    |
+| issues                                       | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled`                                                    |
-| pull_request_review_comment | `created`, `edited`                                                                                                      |
+| issue_comment                                | `created`, `edited`, `deleted`                                                                                                                                             |
-| release                     | `published`, `edited`                                                                                                    |
+| pull_request<br/>pull_request_target         | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled`, `milestoned`, `demilestoned`, `review_requested`, `review_request_removed` |
-| registry_package            | `published`                                                                                                              |
+| pull_request_review                          | `submitted`, `edited`                                                                                                                                                      |
 | pull_request_review_comment                  | `created`, `edited`                                                                                                                                                        |
 | release                                      | `published`, `edited`                                                                                                                                                      |
 | registry_package                             | `published`                                                                                                                                                                |
 | workflow_run                                 | `requested`, `in_progress`, `completed`                                                                                                                                    |
 > Without an explicit `types:` filter, `pull_request` and `pull_request_target` only run on `opened`, `reopened` and `synchronize`, matching GitHub. All other events run on every activity type they support.
 > For `pull_request` events, in [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request), the `ref` is `refs/pull/:prNumber/merge`, which is a reference to the merge commit preview. However, Gitea has no such reference.
 > Therefore, the `ref` in Gitea Actions is `refs/pull/:prNumber/head`, which points to the head of pull request rather than the preview of the merge commit.
 ## How to share actions and reusable workflows from private repositories?
 Go to the repository's **Settings** > **Actions** > **General** page and add collaborative owners.
 The private repositories of collaborative owners are allowed to access the actions and workflows in the current repository.