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

ci: keep the jq expressions parsable on jq 1.6
ci: run the check with the script from the pull request
2026-11-07 10:30:32 +00:00 · 2026-09-08 12:03:59 -07:00 · 2026-09-08 12:00:37 -07:00 · 2026-09-08 11:58:23 -07:00 · 2026-09-08 11:50:21 -07:00 · 2026-09-08 18:26:25 +00:00
2080 changed files with 331375 additions and 41235 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-latest
+    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\#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"
@@ -0,0 +1,48 @@
 # The status check context of this job is "checks / depends-upstream
 # (pull_request)", which the required status check `checks / *` of the protected
 # main branch matches, so a pull request waiting for gitea cannot be merged.
 # It is a workflow of its own so that a label change does not cancel the build
 # and the preview deployment of the `checks` workflow in test.yaml.
 #
 # The check script comes from the pull request, like the workflow file itself:
 # `pull_request` runs both from the head, so taking the script from the base
 # branch would not gain anything and would leave this workflow unable to run on
 # the pull request that adds it.
 name: checks
 on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - edited
      - labeled
      - unlabeled
 concurrency:
  group: depends-upstream-${{ github.event.pull_request.number }}
  cancel-in-progress: true
 jobs:
  depends-upstream:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - name: check the upstream dependencies
        env:
          PR_NUMBER: ${{ github.event.pull_request.number }}
          # optional, only lifts the rate limit of the unauthenticated github api
          GITHUB_COM_TOKEN: ${{ secrets.GITHUB_COM_TOKEN }}
        run: |
          set -euo pipefail
          # read the description and the labels from the api instead of the
          # event context, so nothing from a pull request body is expanded into
          # this script
          api="${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY"
          curl --silent --show-error --fail --output pull.json "$api/pulls/$PR_NUMBER"
          ./scripts/check-upstream-deps.sh pull.json
@@ -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\#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
          printf '%s' "$body" | jq -Rs '{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,29 @@
 name: unlabel merged upstream dependencies
 on:
  schedule:
    - cron: '15 */6 * * *' # every 6 hours, quarter past
  workflow_dispatch:
 jobs:
  unlabel:
    if: github.repository == 'gitea/docs'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - name: drop the label from the pull requests upstream caught up with
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
          GITHUB_COM_TOKEN: ${{ secrets.GITHUB_COM_TOKEN }}
        run: |
          set -euo pipefail
          if [ -z "${DEPLOY_TOKEN:-}" ]; then
            echo "secrets.DEPLOY_TOKEN is missing, cannot remove the label"
            exit 1
          fi
          export GITEA_API="${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY"
          ./scripts/unlabel-upstream-deps.sh
@@ -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,28 +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://github.com/go-gitea/gitea/blob/main/templates/swagger/v1_json.tmpl
+          ref: main
-          sed -i "$@" 's/"version": "{{AppVer | JSEscape | Safe}}"/"version": "dev"/' static/swagger-latest.json
+          # pushing uses DEPLOY_TOKEN, keep the ephemeral job token out of .git/config
-          rm v1_json.tmpl
+          persist-credentials: false
      - name: regenerate the latest api documents
        run: make update-api-docs-latest
      - name: verify the generated file
        run: |
          set -euo pipefail
          for file in $LATEST_FILES; do
            # placeholders must have been replaced, otherwise upstream changed them again
            if grep -q -e 'GITEA-API-APP' -e '{{' "$file"; then
              echo "$file still contains template placeholders"
              exit 1
            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
-          wget https://github.com/go-gitea/gitea/blob/v1.22.4/templates/swagger/v1_json.tmpl
+          if git diff --quiet -- $LATEST_FILES; then
-          sed -i "$@" 's/"version": "{{AppVer | JSEscape | Safe}}"/"version": "1.22.6"/' static/swagger-22.json
+            echo "the api documents are already up to date"
-          rm v1_json.tmpl
+            echo "changed=false" >> "$GITHUB_OUTPUT"
            exit 0
          fi
-          if ! [[ $(git diff --shortstat) ]]; then exit 0; fi
+          if [ -z "$DEPLOY_TOKEN" ]; then
-          git config --global user.name "Gitea Bot"
+            echo "secrets.DEPLOY_TOKEN is missing, cannot push the update"
-          git config --global user.email "[email protected]"
+            exit 1
-          git remote set-url origin https://x-access-token:${{ secrets.DEPLOY_TOKEN }}@gitea.com/gitea/docs.git
+          fi
-          git add --all
+          remote="https://x-access-token:$DEPLOY_TOKEN@${GITHUB_SERVER_URL#*://}/$GITHUB_REPOSITORY.git"
-          git commit -m "[skip ci] Updated swagger files"
+
-          git push
+          # 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,29 +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-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
 .PHONY: update-api-docs
 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,158 @@
 # 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.
 ### Documenting an unreleased feature
 A page that describes a gitea change which is not merged yet must wait for it,
 otherwise the site documents something no release has. Say so in the description
 of the pull request, on a line of its own, and add the `depends-on-upstream`
 label:
 ```
 Depends on: gitea#35851
 ```
 The label is what blocks the merge: the `depends-upstream` check fails while it
 is set, unless every dependency is verified as merged, and `main` requires the
 `checks` contexts. The check reads the `Depends on:` lines (`gitea#<id>` or the
 full pull request url, several lines are allowed) to find out what to wait for,
 so the label needs at least one of them. A `gitea#<id>` mentioned anywhere else
 in the description is ignored.
 Without the label, a dependency that the check finds unmerged still fails it, so
 forgetting the label does not let an unreleased feature through.
 The `unlabel merged upstream dependencies` job runs every 6 hours, removes the
 label once every referenced pull request is merged and comments on the pull
 request, which reruns the check. `scripts/check-upstream-deps.sh` is the check
 itself and can be run locally against the json of a pull request.
 The check asks the github api whether a pull request is merged, and the runners
 share the 60 requests per hour it allows without authentication. The optional
 `GITHUB_COM_TOKEN` secret (a token without scopes is enough) raises that limit;
 without it an unverifiable dependency only fails the check when the label is
 set.
 ## Cutting a version
 ```shell
-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
@@ -325,6 +328,7 @@ in the current directory.
  - `--skip-attachment-data`: Skip dumping of attachment data. Optional.
  - `--skip-package-data`: Skip dumping of package data. Optional.
  - `--skip-log`: Skip dumping of log data. Optional.
  - `--skip-index`: Skip dumping of Bleve indexer data. Optional. Applies only for bleve.
  - `--database`, `-d`: Specify the database SQL syntax. Optional (supported arguments: sqlite3, mysql, mssql, postgres).
  - `--verbose`, `-V`: If provided, shows additional details. Optional.
  - `--type`: Set the dump output format. Optional. (formats: zip, tar, tar.sz, tar.gz, tar.xz, tar.bz2, tar.br, tar.lz4, tar.zst default: zip).
@@ -1,5 +1,5 @@
 ---
-date: "2016-12-26T16:00:00+02:00"
+date: "2025-10-26T00:00:00+00:00"
 slug: "config-cheat-sheet"
 sidebar_position: 30
 aliases:
@@ -34,13 +34,44 @@ A full restart is required for Gitea configuration changes to take effect.
 ## Use environment variables to setup Gitea
-There is [environment-to-ini](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini) to help to
+Gitea supports setting `app.ini` values via environment variables of the form `GITEA__<section>__<KEY>`. These require running `gitea config edit-ini --in-place --apply-env` before starting Gitea to write them into `app.ini`. The official Docker images do this automatically on container startup.
-generate Gitea's `app.ini` from environment variables.
+
 :::info
 If `<section>` or `<KEY>` contains a `.`, replace that with `_0X2E_`; if it contains a `-`, replace it with `_0X2C_`
 :::
 For example, to configure the database connection via environment variables:
 ```
 GITEA__database__DB_TYPE=postgres
 GITEA__database__HOST=127.0.0.1:5432
 GITEA__database__NAME=gitea
 GITEA__database__USER=gitea
 GITEA__database__PASSWD=secret
 ```
 This is equivalent to the following `app.ini` configuration:
 ```ini
 [database]
 DB_TYPE = postgres
 HOST = 127.0.0.1:5432
 NAME = gitea
 USER = gitea
 PASSWD = secret
 ```
 You can also load values from files by appending `__FILE` to the variable name. This is useful for Docker secrets:
 ```
 GITEA__database__PASSWD__FILE=/run/secrets/db_password
 ```
 ## Default Internal Variables (non-`app.ini` configuration)
 These values are environment-dependent but form the basis of a lot of values. They will be
-reported as part of the default configuration when running `gitea help` or on start-up. 
+reported as part of the default configuration when running `gitea help` or on start-up.
 The order they are emitted there is slightly different but we will list them here in the order they are set-up.
 - _`AppPath`_: This is the absolute path of the running gitea binary.
@@ -80,13 +111,19 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
   A relative path is interpreted as **`{AppWorkPath}/{ROOT}`**.
 - `SCRIPT_TYPE`: **bash**: The script type this server supports. Usually this is `bash`,
   but some users report that only `sh` is available.
 - `DEFAULT_OBJECT_FORMAT`: **sha1**: The default object format for new repositories. Valid values are `sha1` and `sha256`.
 - `DETECTED_CHARSETS_ORDER`: **UTF-8, UTF-16BE, UTF-16LE, UTF-32BE, UTF-32LE, ISO-8859, windows-1252, ISO-8859, windows-1250, ISO-8859, ISO-8859, ISO-8859, windows-1253, ISO-8859, windows-1255, ISO-8859, windows-1251, windows-1256, KOI8-R, ISO-8859, windows-1254, Shift_JIS, GB18030, EUC-JP, EUC-KR, Big5, ISO-2022, ISO-2022, ISO-2022, IBM424_rtl, IBM424_ltr, IBM420_rtl, IBM420_ltr**: Tie-break order of detected charsets - if the detected charsets have equal confidence, charsets earlier in the list will be chosen in preference to those later. Adding `defaults` will place the unnamed charsets at that point.
 - `ANSI_CHARSET`: **_empty_**: Default ANSI charset to override non-UTF-8 charsets to.
 - `FORCE_PRIVATE`: **false**: Force every new repository to be private.
 - `DEFAULT_PRIVATE`: **last**: Default private when creating a new repository: `last`, `private`, `public`
 - `DEFAULT_PUSH_CREATE_PRIVATE`: **true**: Default private when creating a new repository with push-to-create.
- `MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per user,
+- `MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per user/org,
-   `-1` means no limit.
+   `-1` means no limit. Acts as a shortcut: sets the default value for both
   `USER_MAX_CREATION_LIMIT` and `ORG_MAX_CREATION_LIMIT` when those are not configured.
 - `USER_MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per user,
   applied at creation time. `-1` means no limit. Takes precedence over `MAX_CREATION_LIMIT` when set.
 - `ORG_MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per organization,
   applied at creation time. `-1` means no limit. Takes precedence over `MAX_CREATION_LIMIT` when set.
 - `PREFERRED_LICENSES`: **Apache License 2.0,MIT License**: Preferred Licenses to place at
   the top of the list. Name must match file name in options/license or custom/options/license.
 - `DISABLE_HTTP_GIT`: **false**: Disable the ability to interact with repositories over the
@@ -99,7 +136,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
   default is not to present.
   :::warning
-   This maybe harmful to you website if you do not give it a right value.
+   This maybe harmful to your website if you do not give it a right value.
   :::
 - `DEFAULT_CLOSE_ISSUES_VIA_COMMITS_IN_ANY_BRANCH`:  **false**: Close an issue if a commit on a non default branch marks it as closed.
@@ -118,7 +155,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
 - `ALLOW_DELETION_OF_UNADOPTED_REPOSITORIES`: **false**: Allow non-admin users to delete unadopted repositories
 - `DISABLE_DOWNLOAD_SOURCE_ARCHIVES`: **false**: Don't allow download source archive files from UI
 - `ALLOW_FORK_WITHOUT_MAXIMUM_LIMIT`: **true**: Allow to fork repositories without maximum number limit
- `ALLOW_FORK_INTO_SAME_OWNER`: **false**: Allow to fork repositories into the same owner (user or organization). This feature is experimental, not fully tested, and may be changed in the future
+- `ALLOW_FORK_INTO_SAME_OWNER`: **false**: Allow to fork repositories into the same owner (user or organization).
 ### Repository - Editor (`repository.editor`)
@@ -141,8 +178,12 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
 - `DEFAULT_MERGE_MESSAGE_OFFICIAL_APPROVERS_ONLY`: **true**: In default merge messages only include approvers who are officially allowed to review.
 - `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: In default squash-merge messages include the commit message of all commits comprising the pull request.
 - `ADD_CO_COMMITTER_TRAILERS`: **true**: Add co-authored-by and co-committed-by trailers to merge commit messages if committer does not match author.
 - `TEST_CONFLICTING_PATCHES_WITH_GIT_APPLY`: **false**: PR patches are tested using a three-way merge method to discover if there are conflicts. If this setting is set to **true**, conflicting patches will be retested using `git apply` - This was the previous behaviour in 1.18 (and earlier) but is somewhat inefficient. Please report if you find that this setting is required.
 - `RETARGET_CHILDREN_ON_MERGE`: **true**: Retarget child pull requests to the parent pull request branch target on merge of parent pull request. It only works on merged PRs where the head and base branch target the same repo.
 - `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: Set the default value for "Delete pull request branch after merge by default" for new repositories.
 - `DEFAULT_TITLE_SOURCE`: **auto**: Default source for the pull request title when opening a new PR. Valid options:
  - `first-commit`: Uses the oldest commit's summary as the title. If there are multiple commits, still uses the first commit's message.
  - `auto`: Uses the commit's summary when the PR contains a single commit; when there are multiple commits, converts the branch name into a human-readable title by normalizing separators and casing.
  - `branch-name`: Always uses the PR's branch name.
 ### Repository - Issue (`repository.issue`)
@@ -159,9 +200,11 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
 ### Repository - Release (`repository.release`)
- `ALLOWED_TYPES`: **_empty_**: Comma-separated list of allowed file extensions (`.zip`), mime types (`text/plain`) or wildcard type (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types.
+- `ALLOWED_TYPES`: **_empty_**: Comma-separated list of allowed release attachment file extensions (`.zip`), mime types (`text/plain`) or wildcard type (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types.
 - `DEFAULT_PAGING_NUM`: **10**: The default paging number of releases user interface
- For settings related to file attachments on releases, see the `attachment` section.
+- `FILE_MAX_SIZE`: **2048**: Max filesize limit for release attachments (MB)
 - `MAX_FILES`: **5**: Maximum number of release attachments that can be uploaded at once for a release.
 - For other settings related to file attachments on releases, see the `attachment` section.
 ### Repository - Signing (`repository.signing`)
@@ -209,7 +252,6 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `MAX_AGE`: **10m**: max time to cache response
 - `ALLOW_CREDENTIALS`: **false**: allow request with credentials
 - `HEADERS`: **Content-Type,User-Agent**: additional headers that are permitted in requests
 - `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value.
 ## UI (`ui`)
@@ -224,6 +266,8 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `DEFAULT_THEME`: **gitea-auto**: Set the default theme for the Gitea installation, custom themes could be provided by `{CustomPath}/public/assets/css/theme-*.css`.
 - `SHOW_USER_EMAIL`: **true**: Whether the email of the user should be shown in the Explore Users page.
 - `THEMES`: **_empty_**: All available themes by `{CustomPath}/public/assets/css/theme-*.css`. Allow users select personalized themes.
 - `FILE_ICON_THEME`: **material**: The icon theme for files (basic/material).
 - `FOLDER_ICON_THEME`: **basic**: The icon theme for folders (basic/material).
 - `MAX_DISPLAY_FILE_SIZE`: **8388608**: Max size of files to be displayed (default is 8MiB)
 - `AMBIGUOUS_UNICODE_DETECTION`: **true**: Detect ambiguous unicode characters in file contents and show warnings on the UI
 - `REACTIONS`: All available reactions users can choose on issues/prs and comments
@@ -233,6 +277,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `CUSTOM_EMOJIS`: **gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the utf8 standard.
    By default, we support Gitea (:gitea:), to add more copy them to public/assets/img/emoji/emoji_name.png and
    add it to this config.
 - `ENABLED_EMOJIS`: **_empty_**: Comma separated list of enabled emojis, for example: "smile, thumbsup, thumbsdown". Leave it empty to enable all emojis.
 - `DEFAULT_SHOW_FULL_NAME`: **false**: Whether the full name of the users should be shown where possible. If the full name isn't set, the username will be used.
 - `SEARCH_REPO_DESCRIPTION`: **true**: Whether to search within description at repository search on explore page.
 - `ONLY_SHOW_RELEVANT_REPOS`: **false**: Whether to only show relevant repos on the explore page when no keyword is specified and default sorting is used.
@@ -276,17 +321,23 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 ## Markdown (`markdown`)
- `ENABLE_HARD_LINE_BREAK_IN_COMMENTS`: **true**: Render soft line breaks as hard line breaks in comments, which
+- `RENDER_OPTIONS_COMMENT`: **short-issue-pattern, new-line-hard-break**: Customize render options for different contexts.
-  means a single newline character between paragraphs will cause a line break and adding
+  Set to "none" to disable the defaults, or use comma separated list:
-  trailing whitespace to paragraphs is not necessary to force a line break.
+  - short-issue-pattern: recognized "#123" issue reference and render it as a link to the issue
- `ENABLE_HARD_LINE_BREAK_IN_DOCUMENTS`: **false**: Render soft line breaks as hard line breaks in documents, which
+  - new-line-hard-break: render soft line breaks as hard line breaks, which means a single newline character between
-  means a single newline character between paragraphs will cause a line break and adding
+    paragraphs will cause a line break and adding trailing whitespace to paragraphs is not
-  trailing whitespace to paragraphs is not necessary to force a line break.
+    necessary to force a line break.
 - `RENDER_OPTIONS_WIKI`: **short-issue-pattern**: see also RENDER_OPTIONS_COMMENT
 - `RENDER_OPTIONS_REPO_FILE`: **_empty_**: see also RENDER_OPTIONS_COMMENT
 - `CUSTOM_URL_SCHEMES`: Use a comma separated list (ftp,git,svn) to indicate additional
  URL hyperlinks to be rendered in Markdown. URLs beginning in http and https are
  always displayed. If this entry is empty, all URL schemes are allowed
- `FILE_EXTENSIONS`: **.md,.markdown,.mdown,.mkd,.livemd**: List of file extensions that should be rendered/edited as Markdown. Separate the extensions with a comma. To render files without any extension as markdown, just put a comma.
+- `FILE_EXTENSIONS`: **.md,.markdown,.mdown,.mkd,.livemd**: List of file extensions that should be rendered/edited as Markdown.
  Separate the extensions with a comma. To render files without any extension as markdown, just put a comma.
 - `ENABLE_MATH`: **true**: Enables detection of `$...$`, `$$...$$`, ``` $`...`$$ ``` blocks as math blocks.
 - `MATH_CODE_BLOCK_DETECTION`: **inline-dollar,block-dollar**: Enable delimiters for math code block detection.
  Set to "none" to disable all, or use comma separated list: inline-dollar, inline-parentheses, block-dollar, block-square-brackets.
  Default value follows GitHub.
 ## Server (`server`)
@@ -300,7 +351,12 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `DOMAIN`: **localhost**: Domain name of this server.
 - `ROOT_URL`: **`{PROTOCOL}://{DOMAIN}:{HTTP_PORT}/`**:
   Overwrite the automatically generated public URL.
-   This is useful if the internal and the external URL don't match (e.g. in Docker).
+   This is useful if the internal and the external URL don't match (e.g. behind a reverse proxy).
 - `PUBLIC_URL_DETECTION`: **`auto`**: Controls how to generate the public URL. Most instances should use the "auto" behavior,
   especially when the Gitea instance needs to be accessed in a container network.
   - "legacy": generate the public URL by "Host" header if "X-Forwarded-Proto" header exists, otherwise use "ROOT_URL".
   - "auto": always use "Host" header, and also use "X-Forwarded-Proto" header if it exists. If no "Host" header, use "ROOT_URL".
   - "never": always use "ROOT_URL", never detect from request headers.
 - `STATIC_URL_PREFIX`: **_empty_**:
   Overwrite this option to request static resources from a different URL.
   This includes CSS files, images, JS files and web fonts.
@@ -349,16 +405,16 @@ The following configuration set `Content-Type: application/vnd.android.package-a
  This option is only for some advanced users who have configured their SSH reverse-proxy and need to use different usernames for git SSH clone.
  Most users should just leave it blank and/or modify the `BUILTIN_SSH_SERVER_USER`.
 - `SSH_DOMAIN`: **`{DOMAIN}`**: Domain name of this server, used for displayed clone URL.
- `SSH_PORT`: **22**: SSH port displayed in clone URL.
+- `SSH_PORT`: **22**: SSH port displayed in clone URL. If you need a different "SSH clone port" from the real "SSH listen port", set the SSH_LISTEN_PORT separately.
 - `SSH_LISTEN_HOST`: **0.0.0.0**: Listen address for the built-in SSH server.
 - `SSH_LISTEN_PORT`: **`{SSH_PORT}`**: Port for the built-in SSH server.
- `SSH_ROOT_PATH`: **~/.ssh**: Root path of SSH directory.
+- `SSH_ROOT_PATH`: **_empty_**: Root path of SSH user directory for the system's standalone SSH server if Gitea is not using its builtin SSH server. Default is the '.ssh' directory in the run user's home directory.
- `SSH_CREATE_AUTHORIZED_KEYS_FILE`: **true**: Gitea will create a authorized_keys file by default when it is not using the internal ssh server. If you intend to use the AuthorizedKeysCommand functionality then you should turn this off.
+- `SSH_CREATE_AUTHORIZED_KEYS_FILE`: **true**: Gitea will create an authorized_keys file by default when it is not using the builtin SSH server. If you intend to use the AuthorizedKeysCommand functionality then you should turn this off.
 - `SSH_AUTHORIZED_KEYS_BACKUP`: **false**: Enable SSH Authorized Key Backup when rewriting all keys, default is false.
 - `SSH_TRUSTED_USER_CA_KEYS`: **_empty_**: Specifies the public keys of certificate authorities that are trusted to sign user certificates for authentication. Multiple keys should be comma separated. E.g.`ssh-<algorithm> <key>` or `ssh-<algorithm> <key1>, ssh-<algorithm> <key2>`. For more information see `TrustedUserCAKeys` in the sshd config man pages. When empty no file will be created and `SSH_AUTHORIZED_PRINCIPALS_ALLOW` will default to `off`.
 - `SSH_TRUSTED_USER_CA_KEYS_FILENAME`: **`RUN_USER`/.ssh/gitea-trusted-user-ca-keys.pem**: Absolute path of the `TrustedUserCaKeys` file Gitea will manage. If you're running your own ssh server and you want to use the Gitea managed file you'll also need to modify your sshd_config to point to this file. The official docker image will automatically work without further configuration.
 - `SSH_AUTHORIZED_PRINCIPALS_ALLOW`: **off** or **username, email**: \[off, username, email, anything\]: Specify the principals values that users are allowed to use as principal. When set to `anything` no checks are done on the principal string. When set to `off` authorized principal are not allowed to be set.
- `SSH_CREATE_AUTHORIZED_PRINCIPALS_FILE`: **false/true**: Gitea will create a authorized_principals file by default when it is not using the internal ssh server and `SSH_AUTHORIZED_PRINCIPALS_ALLOW` is not `off`.
+- `SSH_CREATE_AUTHORIZED_PRINCIPALS_FILE`: **false/true**: Gitea will create an authorized_principals file by default when it is not using the builtin SSH server and `SSH_AUTHORIZED_PRINCIPALS_ALLOW` is not `off`.
 - `SSH_AUTHORIZED_PRINCIPALS_BACKUP`: **false/true**: Enable SSH Authorized Principals Backup when rewriting all keys, default is true if `SSH_AUTHORIZED_PRINCIPALS_ALLOW` is not `off`.
 - `SSH_AUTHORIZED_KEYS_COMMAND_TEMPLATE`: **`{{.AppPath}} --config={{.CustomConf}} serv key-{{.Key.ID}}`**: Set the template for the command to passed on authorized keys. Possible keys are: AppPath, AppWorkPath, CustomConf, CustomPath, Key - where Key is a `models/asymkey.PublicKey` and the others are strings which are shellquoted.
 - `SSH_SERVER_CIPHERS`: **`chacha20-poly1305@openssh.com`, `aes128-ctr`, `aes192-ctr`, `aes256-ctr`, `aes128-gcm@openssh.com`, `aes256-gcm@openssh.com`**: For the built-in SSH server, choose the ciphers to support for SSH connections, for system SSH this setting has no effect.
@@ -396,46 +452,14 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `REDIRECT_OTHER_PORT`: **false**: If true and `PROTOCOL` is https, allows redirecting http requests on `PORT_TO_REDIRECT` to the https port Gitea listens on.
 - `REDIRECTOR_USE_PROXY_PROTOCOL`: **`{USE_PROXY_PROTOCOL}`**: expect PROXY protocol header on connections to https redirector.
 - `PORT_TO_REDIRECT`: **80**: Port for the http redirection service to listen on. Used when `REDIRECT_OTHER_PORT` is true.
- `SSL_MIN_VERSION`: **TLSv1.2**: Set the minimum version of ssl support.
+- `SSL_MIN_VERSION`: **_empty_**: Minimum supported TLS version, one of TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. Unset uses Go's default.
- `SSL_MAX_VERSION`: **_empty_**: Set the maximum version of ssl support.
+- `SSL_MAX_VERSION`: **_empty_**: Maximum supported TLS version, one of TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. Unset uses Go's default.
- `SSL_CURVE_PREFERENCES`: **X25519,P256**: Set the preferred curves,
+- `SSL_CURVE_PREFERENCES`: **_empty_**: Comma-separated list of SSL curve preferences. Unset uses Go's default.
- `SSL_CIPHER_SUITES`: **ecdhe_ecdsa_with_aes_256_gcm_sha384,ecdhe_rsa_with_aes_256_gcm_sha384,ecdhe_ecdsa_with_aes_128_gcm_sha256,ecdhe_rsa_with_aes_128_gcm_sha256,ecdhe_ecdsa_with_chacha20_poly1305,ecdhe_rsa_with_chacha20_poly1305**: Set the preferred cipher suites.
+- `SSL_CIPHER_SUITES`: **_empty_**: Comma-separated list of SSL cipher suites. Unset uses Go's default.
  - If there is no hardware support for AES suites, by default the ChaCha suites will be preferred over the AES suites.
  - supported suites as of Go 1.18 are:
    - TLS 1.0 - 1.2 cipher suites
      - "rsa_with_rc4_128_sha"
      - "rsa_with_3des_ede_cbc_sha"
      - "rsa_with_aes_128_cbc_sha"
      - "rsa_with_aes_256_cbc_sha"
      - "rsa_with_aes_128_cbc_sha256"
      - "rsa_with_aes_128_gcm_sha256"
      - "rsa_with_aes_256_gcm_sha384"
      - "ecdhe_ecdsa_with_rc4_128_sha"
      - "ecdhe_ecdsa_with_aes_128_cbc_sha"
      - "ecdhe_ecdsa_with_aes_256_cbc_sha"
      - "ecdhe_rsa_with_rc4_128_sha"
      - "ecdhe_rsa_with_3des_ede_cbc_sha"
      - "ecdhe_rsa_with_aes_128_cbc_sha"
      - "ecdhe_rsa_with_aes_256_cbc_sha"
      - "ecdhe_ecdsa_with_aes_128_cbc_sha256"
      - "ecdhe_rsa_with_aes_128_cbc_sha256"
      - "ecdhe_rsa_with_aes_128_gcm_sha256"
      - "ecdhe_ecdsa_with_aes_128_gcm_sha256"
      - "ecdhe_rsa_with_aes_256_gcm_sha384"
      - "ecdhe_ecdsa_with_aes_256_gcm_sha384"
      - "ecdhe_rsa_with_chacha20_poly1305_sha256"
      - "ecdhe_ecdsa_with_chacha20_poly1305_sha256"
    - TLS 1.3 cipher suites
      - "aes_128_gcm_sha256"
      - "aes_256_gcm_sha384"
      - "chacha20_poly1305_sha256"
    - Aliased names
      - "ecdhe_rsa_with_chacha20_poly1305" is an alias for "ecdhe_rsa_with_chacha20_poly1305_sha256"
      - "ecdhe_ecdsa_with_chacha20_poly1305" is alias for "ecdhe_ecdsa_with_chacha20_poly1305_sha256"
 - `ENABLE_ACME`: **false**: Flag to enable automatic certificate management via an ACME capable Certificate Authority (CA) server (default: Lets Encrypt). If enabled, `CERT_FILE` and `KEY_FILE` are ignored, and the CA must resolve `DOMAIN` to this gitea server. Ensure that DNS records are set and either port `80` or port `443` are accessible by the CA server (the public internet by default), and redirected to the appropriate ports `PORT_TO_REDIRECT` or `HTTP_PORT` respectively.
 - `ACME_URL`: **_empty_**: The CA's ACME directory URL, e.g. for a self-hosted [smallstep CA server](https://github.com/smallstep/certificates), it can look like `https://ca.example.com/acme/acme/directory`. If left empty, it defaults to using Let's Encerypt's production CA (check `LETSENCRYPT_ACCEPTTOS` as well).
 - `ACME_ACCEPTTOS`: **false**: This is an explicit check that you accept the terms of service of the ACME provider. The default is Lets Encrypt [terms of service](https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf).
- `ACME_DIRECTORY`: **https**: Directory that the certificate manager will use to cache information such as certs and private keys.
+- `ACME_DIRECTORY`: **https**: Directory that the certificate manager will use to cache information such as certs and private keys. A relative path is resolved against the working directory of the Gitea process, which is not necessarily a directory that survives a restart, see the note in [HTTPS setup](https-support.md#using-acme-default-lets-encrypt).
 - `ACME_EMAIL`: **_empty_**: Email used for the ACME registration. Usually it is to notify about problems with issued certificates.
 - `ACME_CA_ROOT`: **_empty_**: The CA's root certificate. If left empty, it defaults to using the system's trust chain.
 - `ALLOW_GRACEFUL_RESTARTS`: **true**: Perform a graceful restart on SIGHUP
@@ -465,7 +489,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
    - `require`: Enable TLS without any verifications.
    - `verify-ca`: Enable TLS with verification of the database server certificate against its root certificate.
    - `verify-full`: Enable TLS and verify the database server name matches the given certificate in either the `Common Name` or `Subject Alternative Name` fields.
- `SQLITE_TIMEOUT`: **500**: Query timeout for SQLite3 only.
+- `SQLITE_TIMEOUT`: **20000**: Query timeout in milliseconds, for SQLite3 only.
 - `SQLITE_JOURNAL_MODE`: **""**: Change journal mode for SQlite3. Can be used to enable [WAL mode](https://www.sqlite.org/wal.html) when high load causes write congestion. See [SQlite3 docs](https://www.sqlite.org/pragma.html#pragma_journal_mode) for possible values. Defaults to the default for the database file, often DELETE.
 - `ITERATE_BUFFER_SIZE`: **50**: Internal buffer size for iterating.
 - `PATH`: **data/gitea.db**: For SQLite3 only, the database file path.
@@ -485,14 +509,14 @@ relation to port exhaustion.
 ## Indexer (`indexer`)
- `ISSUE_INDEXER_TYPE`: **bleve**: Issue indexer type, currently supported: `bleve`, `db`, `elasticsearch` or `meilisearch`.
+- `ISSUE_INDEXER_TYPE`: **bleve**: Issue indexer type, currently supported: `bleve`, `db`, `elasticsearch` (also compatible with OpenSearch) or `meilisearch`.
 - `ISSUE_INDEXER_CONN_STR`: ****: Issue indexer connection string, available when ISSUE_INDEXER_TYPE is elasticsearch (e.g. `http://elastic:password@localhost:9200`) or meilisearch (e.g. `http://:apikey@localhost:7700`)
 - `ISSUE_INDEXER_NAME`: **gitea_issues**: Issue indexer name, available when ISSUE_INDEXER_TYPE is elasticsearch or meilisearch.
 - `ISSUE_INDEXER_PATH`: **indexers/issues.bleve**: Index file used for issue search; available when ISSUE_INDEXER_TYPE is bleve and elasticsearch. Relative paths will be made absolute against _`AppWorkPath`_.
 - `REPO_INDEXER_ENABLED`: **false**: Enables code search (uses a lot of disk space, about 6 times more than the repository size).
 - `REPO_INDEXER_REPO_TYPES`: **sources,forks,mirrors,templates**: Repo indexer units. The items to index could be `sources`, `forks`, `mirrors`, `templates` or any combination of them separated by a comma. If empty then it defaults to `sources` only, as if you'd like to disable fully please see `REPO_INDEXER_ENABLED`.
- `REPO_INDEXER_TYPE`: **bleve**: Code search engine type, could be `bleve` or `elasticsearch`.
+- `REPO_INDEXER_TYPE`: **bleve**: Code search engine type, could be `bleve` or `elasticsearch` (also compatible with OpenSearch).
 - `REPO_INDEXER_PATH`: **indexers/repos.bleve**: Index file used for code search.
 - `REPO_INDEXER_CONN_STR`: ****: Code indexer connection string, available when `REPO_INDEXER_TYPE` is elasticsearch. i.e. `http://elastic:password@localhost:9200`
 - `REPO_INDEXER_NAME`: **gitea_codes**: Code indexer name, available when `REPO_INDEXER_TYPE` is elasticsearch
@@ -503,6 +527,10 @@ relation to port exhaustion.
 - `MAX_FILE_SIZE`: **1048576**: Maximum size in bytes of files to be indexed.
 - `STARTUP_TIMEOUT`: **30s**: If the indexer takes longer than this timeout to start - fail. (This timeout will be added to the hammer time above for child processes - as bleve will not start until the previous parent is shutdown.) Set to -1 to never timeout.
 ## Redis (`redis`)
 - `CONN_STR`: **_empty_**: Shared default Redis connection string. When a redis-backed subsystem (`[cache]`, `[session]`, `[queue]`, `[global_lock]`) is configured to use Redis but its own connection string is empty, it falls back to this value. A subsystem's own connection string always takes precedence, so different subsystems can still use different Redis instances.
 ## Queue (`queue` and `queue.*`)
 Configuration at `[queue]` will set defaults for queues with overrides for individual queues at `[queue.*]`. (However see below.)
@@ -511,7 +539,7 @@ Configuration at `[queue]` will set defaults for queues with overrides for indiv
 - `DATADIR`: **queues/common**: Base DataDir for storing level queues. `DATADIR` for individual queues can be set in `queue.name` sections. Relative paths will be made absolute against `{APP_DATA_PATH}`.
 - `LENGTH`: **100000**: Maximal queue size before channel queues block
 - `BATCH_LENGTH`: **20**: Batch data before passing to the handler
- `CONN_STR`: **redis://127.0.0.1:6379/0**: Connection string for the redis queue type. Several redis connections schemes are supported. To see all available `uri.Scheme` types, see [here](https://github.com/go-gitea/gitea/blob/main/modules/nosql/manager_redis.go#L98-L123). For example, if you're running a Redis cluster, use `redis+cluster://127.0.0.1:6379/0`. Options can be set using query params. Similarly, LevelDB options can also be set using: **leveldb://relative/path?option=value** or **leveldb:///absolute/path?option=value**, and will override `DATADIR`
+- `CONN_STR`: **redis://127.0.0.1:6379/0**: Connection string for the redis queue type. If left empty while `TYPE` is `redis`, it falls back to [redis/CONN_STR](#redis-redis) when that is set. Several redis connections schemes are supported. To see all available `uri.Scheme` types, see [here](https://github.com/go-gitea/gitea/blob/main/modules/nosql/manager_redis.go#L98-L123). For example, if you're running a Redis cluster, use `redis+cluster://127.0.0.1:6379/0`. Options can be set using query params. Similarly, LevelDB options can also be set using: **leveldb://relative/path?option=value** or **leveldb:///absolute/path?option=value**, and will override `DATADIR`
 - `QUEUE_NAME`: **_queue**: The suffix for default redis and disk queue name. Individual queues will default to **`name`**`QUEUE_NAME` but can be overridden in the specific `queue.name` section.
 - `SET_NAME`: **_unique**: The suffix that will be added to the default redis and disk queue `set` name for unique queues. Individual queues will default to **`name`**`QUEUE_NAME`_`SET_NAME`_ but can be overridden in the specific `queue.name` section.
 - `MAX_WORKERS`: **(dynamic)**: Maximum number of worker go-routines for the queue. Default value is "CpuNum/2" clipped to between 1 and 10.
@@ -561,6 +589,7 @@ And the following unique queues:
 - `LOGIN_REMEMBER_DAYS`: **31**: How long to remember that a user is logged in before requiring relogin (in days).
 - `COOKIE_REMEMBER_NAME`: **gitea\_incredible**: Name of cookie used to store authentication
   information.
 - `REVERSE_PROXY_LOGOUT_REDIRECT`: **_empty_**: URL or relative path to redirect users to after logout when authentication is handled by a reverse proxy or SSO. For example: `/my-sso/logout?return=/my-sso/home`.
 - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: Header name for reverse proxy
   authentication.
 - `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: Header name for reverse proxy
@@ -570,6 +599,9 @@ And the following unique queues:
 - `REVERSE_PROXY_LIMIT`: **1**: Interpret X-Forwarded-For header or the X-Real-IP header and set this as the remote IP for the request.
   Number of trusted proxy count. Set to zero to not use these headers.
 - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all.
 - `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value for all HTTP responses. Set to `unset` to not send the header. Previously located in `[cors]`.
 - `X_CONTENT_TYPE_OPTIONS`: **nosniff**: Set the `X-Content-Type-Options` header value for all HTTP responses. Set to `unset` to not send the header.
 - `CONTENT_SECURITY_POLICY_GENERAL`: **_empty_**: The value of the general Content-Security-Policy for most web pages. Leave it empty to apply the default policy, or set it to "unset" to disable Content-Security-Polic.
 - `DISABLE_GIT_HOOKS`: **true**: Set to `false` to enable users with Git Hook privilege to create custom Git Hooks.
  :::warning
@@ -614,6 +646,15 @@ And the following unique queues:
 - `PASSWORD_CHECK_PWN`: **false**: Check [HaveIBeenPwned](https://haveibeenpwned.com/Passwords) to see if a password has been exposed.
 - `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: Cache successful token hashes. API tokens are stored in the DB as pbkdf2 hashes however, this means that there is a potentially significant hashing load when there are multiple API operations. This cache will store the successfully hashed tokens in a LRU cache as a balance between performance and security.
 - `DISABLE_QUERY_AUTH_TOKEN`: **false**: Reject API tokens sent in URL query string (Accept Header-based API tokens only). This setting will default to `true` in Gitea 1.23 and be deprecated in Gitea 1.24.
 - `TWO_FACTOR_AUTH`: **_empty_**: set to enforced to enforce two factor authentication. Only available in Gitea 1.24 and later.
 - `ALLOWED_HOST_LIST`: **external**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list.
  - Built-in networks:
    - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6, localhost is included.
    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7). Also called LAN/Intranet.
    - `external`: A valid non-private unicast IP, you can access all hosts on public internet.
    - `*`: All hosts are allowed.
  - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6
  - Wildcard hosts: `*.mydomain.com`, `192.168.100.*`
 ## Camo (`camo`)
@@ -670,15 +711,20 @@ And the following unique queues:
   :::
 - `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page or to use API.
   It could be set to "expensive" to block anonymous users accessing some pages which consume a lot of resources,
   for example: block anonymous AI crawlers from accessing repo code pages.
   The "expensive" mode is experimental and subject to change.
 - `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when
   something happens, like creating issues. Requires `Mailer` to be enabled.
 - `ENABLE_BASIC_AUTHENTICATION`: **true**: Disable this to disallow authentication using HTTP
   BASIC and the user's password. Please note if you disable this you will not be able to access the
   tokens API endpoints using a password. Further, this only disables BASIC authentication using the
   password - not tokens or OAuth Basic.
- `ENABLE_PASSWORD_SIGNIN_FORM`: **true**: Show the password login form (for password-based login).
+- `ENABLE_PASSWORD_SIGNIN_FORM`: **true**: Show the password login form (for password-based login),
   otherwise, only show OAuth2 or passkey login methods if they are enabled.
   If you set it to false, maybe it also needs to set `ENABLE_BASIC_AUTHENTICATION` to false to
   completely disable password-based authentication.
 - `ENABLE_PASSKEY_AUTHENTICATION`: **true**: Allow users to sign-in with a passkey
 - `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable this to allow reverse proxy authentication for web requests
 - `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`: **false**: Enable this to allow reverse proxy authentication for API requests, the reverse proxy is responsible for ensuring that no CSRF is possible.
 - `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration
@@ -736,6 +782,13 @@ And the following unique queues:
 - `DISABLE_ORGANIZATIONS_PAGE`: **false**: Disable the organizations explore page.
 - `DISABLE_CODE_PAGE`: **false**: Disable the code explore page.
 ### Request Quality of Service (`qos`)
 - `ENABLED`: **false**: Enable request quality of service and overload protection.
 - `MAX_INFLIGHT`: **(dynamic)**: The maximum number of concurrent requests that the server will process before enqueueing new requests. Default is "CpuNum * 4".
 - `MAX_WAITING`: **100**: The maximum number of requests that can be enqueued before new requests will be dropped.
 - `TARGET_WAIT_TIME`: **250ms**: Target maximum wait time a request may be enqueued for. Requests that are enqueued for less than this amount of time will not be dropped. When wait times exceed this amount, a portion of requests will be dropped until wait times have decreased below this amount.
 ## SSH Minimum Key Sizes (`ssh.minimum_key_sizes`)
 Define allowed algorithms and their minimum key length (use -1 to disable a type):
@@ -749,14 +802,6 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
 - `QUEUE_LENGTH`: **1000**: Hook task queue length. Use caution when editing this value.
 - `DELIVER_TIMEOUT`: **5**: Delivery timeout (sec) for shooting webhooks.
 - `ALLOWED_HOST_LIST`: **external**: Webhook can only call allowed hosts for security reasons. Comma separated list.
  - Built-in networks:
    - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6, localhost is included.
    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7). Also called LAN/Intranet.
    - `external`: A valid non-private unicast IP, you can access all hosts on public internet.
    - `*`: All hosts are allowed.
  - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6
  - Wildcard hosts: `*.mydomain.com`, `192.168.100.*`
 - `SKIP_TLS_VERIFY`: **false**: Allow insecure certification.
 - `PAGING_NUM`: **10**: Number of webhook history events that are shown in one page.
 - `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting.
@@ -793,7 +838,7 @@ and
  - Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or SMTP host is localhost. See [Email Setup](email-setup.md) for more information.
 - `ENABLE_HELO`: **true**: Enable HELO operation.
 - `HELO_HOSTNAME`: **(retrieved from system)**: HELO hostname.
- `FROM`: **_empty_**: Mail from address, RFC 5322. This can be just an email address, or the "Name" `\<[email protected]\>` format.
+- `FROM`: **_empty_**: Mail from address, RFC 5322. This can be just an email address, or the `"Name" <[email protected]>` format.
 - `ENVELOPE_FROM`: **_empty_**: Address set as the From address on the SMTP mail envelope. Set to `<>` to send an empty address.
 - `FROM_DISPLAY_NAME_FORMAT`: **`{{ .DisplayName }}`**: If gitea sends mails on behave of users, it will just use the name also displayed in the WebUI. If you want e.g. `Mister X (by CodeIt) <[email protected]>`, set it to `{{ .DisplayName }} (by {{ .AppName }})`. Available Variables: `.DisplayName`, `.AppName` and `.Domain`.
 - `SUBJECT_PREFIX`: **_empty_**: Prefix to be placed before e-mail subject lines.
@@ -803,6 +848,7 @@ and
 - `SENDMAIL_CONVERT_CRLF`: **true**: Most versions of sendmail prefer LF line endings rather than CRLF line endings. Set this to false if your version of sendmail requires CRLF line endings.
 - `SEND_BUFFER_LEN`: **100**: Buffer length of mailing queue. **DEPRECATED** use `LENGTH` in `[queue.mailer]`
 - `SEND_AS_PLAIN_TEXT`: **false**: Send mails only in plain text, without HTML alternative.
 - `EMBED_ATTACHMENT_IMAGES`: **false**: Embed attached images in base64 format in HTML emails. (for clients that do not load external images or disconnected vpn users still receiving emails; ATTENTION: online webclients like gmail will not show base64 embedded images)
 ## Override Email Headers (`mailer.override_header`)
@@ -837,7 +883,7 @@ In-Reply-To =
 - `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, `twoqueue` or `memcache`. (`twoqueue` represents a size limited LRU cache.)
 - `INTERVAL`: **60**: Garbage Collection interval (sec), for memory and twoqueue cache only.
- `HOST`: **_empty_**: Connection string for `redis` and `memcache`. For `twoqueue` sets configuration for the queue.
+- `HOST`: **_empty_**: Connection string for `redis` and `memcache`. For `twoqueue` sets configuration for the queue. If left empty while `ADAPTER` is `redis`, it falls back to [redis/CONN_STR](#redis-redis) when that is set.
  - Redis: `redis://:[email protected]:6379/0?pool_size=100&idle_timeout=180s` (See [queue/CONN_STR](#queue-queue-and-queue) for information on additional supported connection types)
    - For a Redis cluster: `redis+cluster://:[email protected]:6379/0?pool_size=100&idle_timeout=180s`
    - For a Redis sentinel: `redis+sentinel://:macaron@sentinel0:26379,sentinel1:26379,sentinel2:26379/0?pool_size=100&idle_timeout=180s&master_name=mymaster`
@@ -853,7 +899,7 @@ In-Reply-To =
 ## Session (`session`)
 - `PROVIDER`: **memory**: Session engine provider \[memory, file, redis, db, mysql, couchbase, memcache, postgres\]. Setting `db` will reuse the configuration in `[database]`
- `PROVIDER_CONFIG`: **data/sessions**: For file, the root path; for db, empty (database config will be used); for others, the connection string. Relative paths will be made absolute against _`AppWorkPath`_.
+- `PROVIDER_CONFIG`: **data/sessions**: For file, the root path; for db, empty (database config will be used); for others, the connection string. Relative paths will be made absolute against _`AppWorkPath`_. For the `redis` provider, if left empty it falls back to [redis/CONN_STR](#redis-redis) when that is set.
 - `COOKIE_SECURE`:**_empty_**: `true` or `false`. Enable this to force using HTTPS for all session access. If not set, it defaults to `true` if the ROOT_URL is an HTTPS URL.
 - `COOKIE_NAME`: **i\_like\_gitea**: The name of the cookie used for the session ID.
 - `GC_INTERVAL_TIME`: **86400**: GC interval in seconds.
@@ -863,8 +909,7 @@ In-Reply-To =
 ## Picture (`picture`)
- `GRAVATAR_SOURCE`: **gravatar**: Can be `gravatar`, `duoshuo` or anything like
+- `GRAVATAR_SOURCE`: **gravatar**: Can be `gravatar`, `libravatar` or any other Gravatar-compatible source, like `https://cn.gravatar.com/avatar/`.
   `http://cn.gravatar.com/avatar/`.
 - `DISABLE_GRAVATAR`: **false**: Enable this to use local avatars only. **DEPRECATED [v1.18+]** moved to database. Use admin panel to configure.
 - `ENABLE_FEDERATED_AVATAR`: **false**: Enable support for federated avatars (see
   [http://www.libravatar.org](http://www.libravatar.org)). **DEPRECATED [v1.18+]** moved to database. Use admin panel to configure.
@@ -892,12 +937,15 @@ Default templates for project board view:
 - `PROJECT_BOARD_BASIC_KANBAN_TYPE`: **To Do, In Progress, Done**
 - `PROJECT_BOARD_BUG_TRIAGE_TYPE`: **Needs Triage, High Priority, Low Priority, Closed**
-## Issue and pull request attachments (`attachment`)
+## Issue, pull-request and release attachments (`attachment`)
- `ENABLED`: **true**: Whether issue and pull request attachments are enabled.
+ALLOWED_TYPES/MAX_SIZE/MAX_FILES in this section only affect issue and pull-request attachments, not release attachments.
- `ALLOWED_TYPES`: **.avif,.cpuprofile,.csv,.dmp,.docx,.fodg,.fodp,.fods,.fodt,.gif,.gz,.jpeg,.jpg,.json,.jsonc,.log,.md,.mov,.mp4,.odf,.odg,.odp,.ods,.odt,.patch,.pdf,.png,.pptx,.svg,.tgz,.txt,.webm,.webp,.xls,.xlsx,.zip**: Comma-separated list of allowed file extensions (`.zip`), mime types (`text/plain`) or wildcard type (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types.
+Release attachment has its own config options in `[repository.release]` section.
- `MAX_SIZE`: **2048**: Maximum size (MB).
+
- `MAX_FILES`: **5**: Maximum number of attachments that can be uploaded at once.
+- `ENABLED`: **true**: Whether issue, pull-request and release attachments are enabled.
 - `ALLOWED_TYPES`: **.avif,.cpuprofile,.csv,.dmp,.docx,.fodg,.fodp,.fods,.fodt,.gif,.gz,.jpeg,.jpg,.json,.jsonc,.log,.md,.mov,.mp4,.odf,.odg,.odp,.ods,.odt,.patch,.pdf,.png,.pptx,.svg,.tgz,.txt,.webm,.webp,.xls,.xlsx,.zip**: Comma-separated list of allowed issue/pull-request attachment file extensions (`.zip`), mime types (`text/plain`) or wildcard type (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types.
 - `MAX_SIZE`: **100**: Max size of each issue/pull-request attachment file in MB.
 - `MAX_FILES`: **5**: Maximum number of issue/pull-request attachments that can be uploaded at once.
 - `STORAGE_TYPE`: **local**: Storage type for attachments, it could be `<blank>`, `local`, `minio`, `azureblob` or `xxx` which defined in another section with `[storage.xxx]`.
  For `STORAGE_TYPE = ` or there is no this configuration item, all storages will be derived from `[storage]` if configured or defult values.
@@ -906,7 +954,7 @@ Default templates for project board view:
  - `PATH`: **attachments**: Path to store attachments only available when STORAGE_TYPE is `local`, relative paths will be resolved to `{AppDataPath}/{attachment.PATH}`.
-  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#storage_minio), you can override some configurations like below.
+  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#minio-storage-configuration-storage_minio), you can override some configurations like below.
  - `MINIO_BASE_PATH`: **attachments/**: Minio base path on the bucket only available when STORAGE_TYPE is `minio`
@@ -979,7 +1027,6 @@ Default templates for project board view:
 - `ENABLED`: **false**: Enable to run all cron tasks periodically with default settings.
 - `RUN_AT_START`: **false**: Run cron tasks at application start-up.
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE` accept formats
  - Full crontab specs, e.g. `* * * * * ?`
  - Descriptors, e.g. `@midnight`, `@every 1h30m` ...
@@ -991,25 +1038,34 @@ Default templates for project board view:
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Whether to emit notice on successful execution too
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
 - `OLDER_THAN`: **24h**: Archives created more than `OLDER_THAN` ago are subject to deletion, e.g. `12h`.
 #### Cron - Update Mirrors (`cron.update_mirrors`)
 - `ENABLED`: **true**: Enable running Update mirrors task periodically.
 - `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
 - `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
 - `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
 - `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).
 #### Cron - Repository Health Check (`cron.repo_health_check`)
 - `ENABLED`: **true**: Enable running repository health check task periodically.
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
 - `RUN_AT_START`: **false**: Run repository health check task when Gitea starts.
 - `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
 - `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck
 #### Cron - Repository Statistics Check (`cron.check_repo_stats`)
 - `RUN_AT_START`: **true**: Run repository statistics check at start time.
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
 - `ENABLED`: **true**: Enable running repository statistics check task periodically.
 - `RUN_AT_START`: **true**: Run repository statistics check task when Gitea starts.
 - `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 #### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)
@@ -1030,10 +1086,20 @@ Default templates for project board view:
 #### Cron - Update Migration Poster ID (`cron.update_migration_poster_id`)
 Update migrated repositories' issues and comments' posterid, it will always attempt synchronization when the instance starts.
 - `ENABLED`: **true**: Enable update migration poster id job.
 - `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
 - `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
 #### Cron - Sync External Users (`cron.sync_external_users`)
 Synchronize external user data (only LDAP user synchronization is supported)
 - `ENABLED`: **true**: Enable synchronize external user data job
 - `RUN_AT_START`: **false**: Synchronize external user data when starting server
 - `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
 - `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.
@@ -1043,6 +1109,12 @@ Default templates for project board view:
 - `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
 - `SCHEDULE`: **@midnight** : Cron syntax for the job.
 #### Cron - Delete Old Action Runs (`cron.cleanup_action_runs`)
 - `ENABLED`: **true**: Enable the job deleting action runs older than `RUN_RETENTION_DAYS`. Deletes nothing while that is 0.
 - `RUN_AT_START`: **false**: Run job at start time (if ENABLED).
 - `SCHEDULE`: **@midnight**: Cron syntax for the job.
 #### Cron - Cleanup Deleted Branches (`cron.deleted_branches_cleanup`)
 - `ENABLED`: **true**: Enable deleted branches cleanup.
@@ -1051,6 +1123,13 @@ Default templates for project board view:
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling deleted branches cleanup.
 - `OLDER_THAN`: **24h**: Branches deleted OLDER_THAN ago will be cleaned up.
 #### Cron - Synchronize repository licenses (`cron.sync_repo_licenses`)
 - `ENABLED`: **false**: Enable deleted branches cleanup.
 - `RUN_AT_START`: **false**: Run job at start time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to log a success message.
 - `SCHEDULE`: **@annually*: Cron syntax for scheduling synchronization of repository licenses
 ### Extended cron tasks
 #### Cron - Delete all repository archives (`cron.delete_repo_archives`)
@@ -1074,7 +1153,14 @@ Default templates for project board view:
 - `ENABLED`: **false**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
+- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling synchronization of gitea ssh keys, e.g. `@every 1h`.
 #### Cron - Update the '.ssh/authorized_principals' file (`cron.resync_all_sshprincipals`)
 - `ENABLED`: **false**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 72h**: Cron syntax for scheduling update of authorized_principals, e.g. `@every 1h`.
 #### Cron - Resynchronize pre-receive, update and post-receive hooks of all repositories (`cron.resync_all_hooks`)
@@ -1138,6 +1224,43 @@ Default templates for project board view:
 - `NUMBER_TO_CHECK_PER_REPO`: **100**: Minimum number of stale LFSMetaObjects to check per repo. Set to `0` to always check all.
 - `PROPORTION_TO_CHECK_PER_REPO`: **0.6**: Check at least this proportion of LFSMetaObjects per repo. (This may cause all stale LFSMetaObjects to be checked.)
 ### Actions cron tasks
 #### Cron - Rebuild issue index (`cron.rebuild_issue_indexer`)
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
 - `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@annually**: Cron syntax to set how often to rebuild
 #### Cron - Stop running tasks which haven't been updated for a long time (`cron.stop_zombie_tasks`)
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
 - `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@every 5m**: Cron syntax to set how often tasks to run the check
 #### Cron - Stop running tasks which have running status and continuous updates but don't end for a long time (`cron.stop_endless_tasks`)
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
 - `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@every 30m**: Cron syntax to set how often to run the check.
 #### Cron - Cancel jobs which haven't been picked up for a long time (`cron.cancel_abandoned_jobs`)
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
 - `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@every 6h**: Cron syntax to set how often to run the check.
 #### Cron - Start cron based actions (`cron.start_schedule_tasks`)
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
 - `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@every 1m**: Cron syntax to set how often to schedule tasks
 ## Git (`git`)
 - `PATH`: **""**: The path of Git executable. If empty, Gitea searches through the PATH environment.
@@ -1158,20 +1281,20 @@ Default templates for project board view:
 - `LARGE_OBJECT_THRESHOLD`: **1048576**: (Go-Git only), don't cache objects greater than this in memory. (Set to 0 to disable.)
 - `DISABLE_CORE_PROTECT_NTFS`: **false** Set to true to forcibly set `core.protectNTFS` to false.
 - `DISABLE_PARTIAL_CLONE`: **false** Disable the usage of using partial clones for git.
 - `DIFF_RENAME_SIMILARITY_THRESHOLD`: **50%** Set the similarity threshold passed to git commands via `--find-renames=<threshold>`. Default is 50%, the same as git. Must be a integer percentage between 0% and 100%.
 ### Git - Timeout settings (`git.timeout`)
 - `DEFAULT`: **360**: Git operations default timeout seconds.
 - `MIGRATE`: **600**: Migrate external repositories timeout seconds.
 - `MIRROR`: **300**: Mirror external repositories timeout seconds.
 - `CLONE`: **300**: Git clone from internal repositories timeout seconds.
 - `PULL`: **300**: Git pull from internal repositories timeout seconds.
 - `GC`: **60**: Git repository GC timeout seconds.
 ### Git - Config options (`git.config`)
-The key/value pairs in this section will be used as git config.
+The key/value pairs in this section will be used as git config. The format is `some.configKey = value`.
-This section only does "set" config, a removed config key from this section won't be removed from git config automatically. The format is `some.configKey = value`.
+These options are written into the gitconfig file under `[git] HOME_PATH` when Gitea starts, and are applied **after** Gitea's built-in defaults — so values set here take precedence over the defaults listed below.
 **Note:** This section only does "set" config; a removed config key from this section won't be removed from git config automatically. Some config options might affect the behavior of git and cause Gitea's git operations to fail — make sure you know what you are doing before making changes.
 - `diff.algorithm`: **histogram**
 - `core.logAllRefUpdates`: **true**
@@ -1203,7 +1326,10 @@ This section only does "set" config, a removed config key from this section won'
 - `JWT_SECRET_URI`: **_empty_**: Instead of defining JWT_SECRET in the configuration, this configuration option can be used to give Gitea a path to a file that contains the secret (example value: `file:/etc/gitea/oauth2_jwt_secret`)
 - `JWT_SIGNING_PRIVATE_KEY_FILE`: **jwt/private.pem**: Private key file path used to sign OAuth2 tokens. The path is relative to `APP_DATA_PATH`. This setting is only needed if `JWT_SIGNING_ALGORITHM` is set to `RS256`, `RS384`, `RS512`, `ES256`, `ES384` or `ES512`. The file must contain a RSA or ECDSA private key in the PKCS8 format. If no key exists a 4096 bit key will be created for you.
 - `MAX_TOKEN_LENGTH`: **32767**: Maximum length of token/cookie to accept from OAuth2 provider
- `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, tea**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options.
+- `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, tea, gitea-app**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options.
 - `CUSTOM_SCHEMES`: **_empty_**: By default, OAuth2 applications can only use "http" and "https" as their redirect URI schemes.
  If you need to use other schemes (e.g. for desktop applications), you can specify them here as a comma-separated list.
  For example: set "my-scheme, com.example.app" to support "my-scheme://..." and "com.example.app://..." redirect URIs.
 ## i18n (`i18n`)
@@ -1213,7 +1339,9 @@ This section only does "set" config, a removed config key from this section won'
 ## Markup (`markup`)
- `MERMAID_MAX_SOURCE_CHARACTERS`: **5000**: Set the maximum size of a Mermaid source. (Set to -1 to disable)
+- `MERMAID_MAX_SOURCE_CHARACTERS`: **50000**: Set the maximum size of a Mermaid source. (Set to -1 to disable)
 ## Markup External Render (`markup.external-render-name`)
 Gitea can support Markup using external tools. The example below will add a markup named `asciidoc`.
@@ -1227,7 +1355,6 @@ IS_INPUT_FILE = false
 ```
 - ENABLED: **false** Enable markup support; set to **true** to enable this renderer.
 - NEED\_POSTPROCESS: **true** set to **true** to replace links / sha1 and etc.
 - FILE\_EXTENSIONS: **_empty_** List of file extensions that should be rendered by an external
   command. Multiple extensions needs a comma as splitter.
 - RENDER\_COMMAND: External command to render all matching extensions.
@@ -1236,6 +1363,10 @@ IS_INPUT_FILE = false
  - sanitized: Sanitize the content and render it inside current page, default to only allow a few HTML tags and attributes. Customized sanitizer rules can be defined in `[markup.sanitizer.*]`.
  - no-sanitizer: Disable the sanitizer and render the content inside current page. It's **insecure** and may lead to XSS attack if the content contains malicious code.
  - iframe: Render the content in a separate standalone page and embed it into current page by iframe. The iframe is in sandbox mode with same-origin disabled, and the JS code are safely isolated from parent page.
 - RENDER_CONTENT_SANDBOX: **_empty_** The sandbox applied to the iframe and Content-Security-Policy header when RENDER_CONTENT_MODE is `iframe`. It defaults to a safe set of "allow-*" restrictions (space separated). You can also set it by your requirements or use "disabled" to disable the sandbox completely. When set it, make sure there is no security risk:
    - PDF-only content: generally safe to use "disabled", and it needs to be "disabled" because PDF only renders with no sandbox.
    - HTML content with JS: if the "RENDER_COMMAND" can guarantee there is no XSS, then it is safe, otherwise, you need to fine tune the "allow-*" restrictions.
 - NEED_POST_PROCESS: **false** Whether post-process the rendered HTML content, including: resolve relative links and image sources, recognizing issue/commit references, escaping invisible characters, mentioning users, rendering permlink code blocks, replacing emoji shorthands, etc. By default, this is true when RENDER_CONTENT_MODE is `sanitized`, otherwise false.
 Two special environment variables are passed to the render command:
@@ -1326,6 +1457,7 @@ in this mapping or the filetype using heuristics.
 - `LIMIT_SIZE_RUBYGEMS`: **-1**: Maximum size of a RubyGems upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_SWIFT`: **-1**: Maximum size of a Swift upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_VAGRANT`: **-1**: Maximum size of a Vagrant upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_TERRAFORM_STATE``: **-1**: Maximum size of a Terraform state upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 ## Mirror (`mirror`)
@@ -1349,7 +1481,7 @@ is `data/lfs` and the default of `MINIO_BASE_PATH` is `lfs/`.
 - `PATH`: **./data/lfs**: Where to store LFS files, only available when `STORAGE_TYPE` is `local`. If not set it fall back to deprecated LFS_CONTENT_PATH value in [server] section.
-  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#storage_minio), you can also define configurations like below to override derived or default values.
+  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#minio-storage-configuration-storage_minio), you can also define configurations like below to override derived or default values.
  - `MINIO_BASE_PATH`: **attachments/**: Minio base path on the bucket only available when STORAGE_TYPE is `minio`
@@ -1500,7 +1632,7 @@ is `data/repo-archive` and the default of `MINIO_BASE_PATH` is `repo-archive/`.
  - `PATH`: **./data/repo-archive**: Where to store archive files, only available when `STORAGE_TYPE` is `local`.
-  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#storage_minio), you can override some configurations like below.
+  For `STORAGE_TYPE = minio`, the configurations can be found at [Storage Minio](#minio-storage-configuration-storage_minio), you can override some configurations like below.
  - `MINIO_BASE_PATH`: **repo-archive/**: Minio base path on the bucket only available when `STORAGE_TYPE` is `minio`
@@ -1534,17 +1666,23 @@ PROXY_HOSTS = *.github.com
 - `DEFAULT_ACTIONS_URL`: **github**: Default platform to get action plugins, `github` for `https://github.com`, `self` for the current Gitea instance.
 - `STORAGE_TYPE`: **local**: Storage type for actions logs, `local` for local disk or `minio` for s3 compatible object storage service, default is `local` or other name defined with `[storage.xxx]`
 - `MINIO_BASE_PATH`: **actions_log/**: Minio base path on the bucket only available when STORAGE_TYPE is `minio`
- `LOG_RETENTION_DAYS`: **365**: Logs retention time in days. Old logs will be deleted after this period.
+- `LOG_RETENTION_DAYS`: **365**: Days to keep logs. Old logs will be deleted after this period. 0 means keep forever.
 - `LOG_COMPRESSION`: **zstd**: Log compression type, `none` for no compression, `zstd` for zstd compression.
  Other compression types like `gzip` are NOT supported, since seekable stream is required for log view.
  It's always recommended to use compression when using local disk as log storage if CPU or memory is not a bottleneck.
  And for object storage services like S3, which is billed for requests, it would cause extra 2 times of get requests for each log view.
  But it will save storage space and network bandwidth, so it's still recommended to use compression.
- `ARTIFACT_RETENTION_DAYS`: **90**: Default number of days to keep artifacts. Artifacts could have their own retention periods by setting the `retention-days` option in `actions/upload-artifact` step.
+- `ARTIFACT_RETENTION_DAYS`: **90**: Days to keep artifacts. Old artifacts will be deleted after this period. 0 means keep forever.
  Changes only apply to newly uploaded artifacts, existing ones keep the expiry stored when they were uploaded.
  Artifacts could have their own retention periods by setting the `retention-days` option in `actions/upload-artifact` step.
 - `RUN_RETENTION_DAYS`: **400**: Days to keep completed runs. Old runs and everything under them will be deleted after this period. 0 means keep forever.
 - `ZOMBIE_TASK_TIMEOUT`: **10m**: Timeout to stop the task which have running status, but haven't been updated for a long time
 - `ENDLESS_TASK_TIMEOUT`: **3h**: Timeout to stop the tasks which have running status and continuous updates, but don't end for a long time
 - `ABANDONED_JOB_TIMEOUT`: **24h**: Timeout to cancel the jobs which have waiting status, but haven't been picked by a runner for a long time
 - `SKIP_WORKFLOW_STRINGS`: **[skip ci],[ci skip],[no ci],[skip actions],[actions skip]**: Strings committers can place inside a commit message or PR title to skip executing the corresponding actions workflow
 - `WORKFLOW_DIRS`: **.gitea/workflows,.github/workflows**: Comma-separated list of workflow directories, the first one to exist in a repo is used to find Actions workflow files.
 - `SCOPED_WORKFLOW_DIRS`: **.gitea/scoped_workflows**: Comma-separated list of directories holding [scoped workflows](usage/actions/scoped-workflows.md) (workflows defined in a central source repository that run on other repositories). Must not overlap with `WORKFLOW_DIRS`. Leave empty so no directory is scanned for scoped workflows; none are found or run.
 - `MAX_RERUN_ATTEMPTS`: **50**: Maximum number of attempts a single workflow run can have (initial run + reruns). Defaults value is 50. Set any positive value that fits your workflow needs.
 `DEFAULT_ACTIONS_URL` indicates where the Gitea Actions runners should find the actions with relative path.
 For example, `uses: actions/checkout@v4` means `https://github.com/actions/checkout@v4` since the value of `DEFAULT_ACTIONS_URL` is `github`.
@@ -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 build 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 build 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([
@@ -165,52 +167,186 @@ Alice <-- Bob: Another authentication Response
 The script will detect tags with `class="language-plantuml"`, but you can change this by providing a second argument to `parsePlantumlCodeBlocks`.
-### Example: STL Preview
+### Example: CAD Files Preview using Online 3D Viewer
-You can display STL file directly in Gitea by adding:
+You can implement CAD file preview inside your Gitea instance. This implemenation uses [`Online 3D Viewer`](https://github.com/kovacsv/Online3DViewer).
 Supports following 3D file formats:
 '3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb',
 'gltf', 'ifc', 'igs', 'iges', 'stp', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'
 (Only v2 for .gltf files)
 #### Part 1: Add template
 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}}">
-  function lS(src) {
+    function onPageChange() {
-    return new Promise(function (resolve, reject) {
+      // Supported 3D file types
-      let s = document.createElement("script");
+      const fileTypes = ['3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb', 'gltf', 'ifc', 'igs', 'iges', 'stp', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'];
      s.src = src;
      s.addEventListener("load", () => {
        resolve();
      });
      document.body.appendChild(s);
    });
  }
-  if ($('.view-raw>a[href$=".stl" i]').length) {
+      // Select matching link
-    $("body").append(
+      const links = Array.from(document.querySelectorAll('a.ui.mini.basic.button'));
-      '<link href="/assets/Madeleine.js/src/css/Madeleine.css" rel="stylesheet">'
+      const link3D = links.find(link => {
-    );
+        const href = link.href.toLowerCase();
-    Promise.all([
+        return href.includes('/raw/') && fileTypes.some(ext => href.endsWith(`.${ext}`));
      lS("/assets/Madeleine.js/src/lib/stats.js"),
      lS("/assets/Madeleine.js/src/lib/detector.js"),
      lS("/assets/Madeleine.js/src/lib/three.min.js"),
      lS("/assets/Madeleine.js/src/Madeleine.js"),
    ]).then(function () {
      $(".view-raw")
        .attr("id", "view-raw")
        .attr("style", "padding: 0;margin-bottom: -10px;");
      new Madeleine({
        target: "view-raw",
        data: $('.view-raw>a[href$=".stl" i]').attr("href"),
        path: "/assets/Madeleine.js/src",
      });
-      $('.view-raw>a[href$=".stl"]').remove();
+
 	if (link3D) {
 	  const existingScript = document.querySelector('script[src="/assets/o3dv/o3dv.min.js"]');
 	  const initializeViewer = () => {
 		const fileUrl = link3D.getAttribute('href');
                const fileView = document.querySelector('.file-view');
 		if (!fileView) return;
 		// Remove only the old viewer container if it exists
 		const oldView3D = document.getElementById('view-3d');
 		if (oldView3D) {
 		  oldView3D.remove();  // safely remove old viewer container div
 		} else {
 		  // No #view-3d, so remove all children inside .file-view
 		  while (fileView.firstChild) {
 		    fileView.removeChild(fileView.firstChild);
 		  }
 		}
 		// Create a new container for the viewer
 		const newView3D = document.createElement('div');
 		  newView3D.id = 'view-3d';
 		  newView3D.style.padding = '0';
 		  newView3D.style.margin = '0';
 		  newView3D.style.flexGrow = '1';
 		  newView3D.style.minHeight = '0';
 		  newView3D.style.width = '100%';
 		const header = document.querySelector('header');
 		const headerHeight = header ? header.offsetHeight : 0;
 		newView3D.style.height = `calc(100vh - ${headerHeight}px)`;
 		// Append the new container inside fileView
 		fileView.appendChild(newView3D);
 		const parentDiv = document.getElementById('view-3d');
 		if (parentDiv) {
 		  const viewer = new OV.EmbeddedViewer(parentDiv, {
 			backgroundColor: new OV.RGBAColor(59, 68, 76, 0),
 			defaultColor: new OV.RGBColor(200, 200, 200),
 			edgeSettings: new OV.EdgeSettings(false, new OV.RGBColor(0, 0, 0), 1),
 			environmentSettings: new OV.EnvironmentSettings([
 			  '/assets/o3dv/envmaps/fishermans_bastion/negx.jpg',
 			  '/assets/o3dv/envmaps/fishermans_bastion/posx.jpg',
 			  '/assets/o3dv/envmaps/fishermans_bastion/posy.jpg',
 			  '/assets/o3dv/envmaps/fishermans_bastion/negy.jpg',
 			  '/assets/o3dv/envmaps/fishermans_bastion/posz.jpg',
 			  '/assets/o3dv/envmaps/fishermans_bastion/negz.jpg'
 			], false)
 		  });
 		  viewer.LoadModelFromUrlList([fileUrl]);
 		}
 	  };
 	  if (typeof OV === 'undefined') {
 		if (!existingScript) {
 		  const script = document.createElement('script');
 		  script.onload = initializeViewer;
 		  script.src = '/assets/o3dv/o3dv.min.js';
 		  document.head.appendChild(script);
 		} else {
 		  // Script is loading but OV not yet ready — wait for it
 		  existingScript.addEventListener('load', initializeViewer);
 		}
 	  } else {
 		// OV already loaded
 		initializeViewer();
 	  }
 	}
    };
    // Run when the page is fully loaded
    document.addEventListener('DOMContentLoaded', onPageChange);
    const targetSelector = 'a.ui.mini.basic.button[href*="/raw/"]';
    let lastHref = null;
    let timeoutId = null;
    const checkAndRun = () => {
      const rawLink = document.querySelector(targetSelector);
      if (!rawLink) return;
      const currentHref = rawLink.getAttribute('href');
      if (currentHref !== lastHref) {
        lastHref = currentHref;
        const fileName = currentHref.split('/').pop();
        console.log('New Raw file link detected after delay:', fileName);
        onPageChange();
      }
    };
    const observer = new MutationObserver(() => {
      // Delay execution by 300ms after last mutation
      clearTimeout(timeoutId);
      timeoutId = setTimeout(checkAndRun, 300);
    });
    observer.observe(document.body, {
      childList: true,
      subtree: true,
    });
  }
 </script>
 ```
-to the file `templates/custom/footer.tmpl`
+#### Part 2: Add public files
-You also need to download the content of the library [Madeleine.js](https://github.com/beige90/Madeleine.js) and place it under `$GITEA_CUSTOM/public/assets/` folder.
+Now we need to download latest version of O3DV. Go to "$GITEA_CUSTOM/public/assets/".
 Create folder using (and cd into it):
-You should end-up with a folder structure similar to:
+```
 mkdir o3dv
 cd o3dv
 ```
 Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.18.0 as of now).
 Here use e.g. wget or curl to download the file:
 ```
 wget https://github.com/kovacsv/Online3DViewer/releases/download/0.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:
 ```
 unzip o3dv.zip
 ```
 #### Part 3: Folder permissions
 Now the last thing. Change permissions 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.
 Sanity check. You should end-up with a folder structure similar to this:
 ```
 $GITEA_CUSTOM/templates
@@ -218,49 +354,14 @@ $GITEA_CUSTOM/templates
    `-- footer.tmpl
 $GITEA_CUSTOM/public/assets/
-- Madeleine.js
+-- o3dv
-   |-- LICENSE
+   |-- o3dv.zip
-   |-- README.md
+   |-- o3dv.license.md
-   |-- css
+   |-- o3dv.min.js
-   |   |-- pygment_trac.css
+   |-- envmaps
-   |   `-- stylesheet.css
+    \...
   |-- examples
   |   |-- ajax.html
   |   |-- index.html
   |   `-- upload.html
   |-- images
   |   |-- bg_hr.png
   |   |-- blacktocat.png
   |   |-- icon_download.png
   |   `-- sprite_download.png
   |-- models
   |   |-- dino2.stl
   |   |-- ducati.stl
   |   |-- gallardo.stl
   |   |-- lamp.stl
   |   |-- octocat.stl
   |   |-- skull.stl
   |   `-- treefrog.stl
   `-- src
       |-- Madeleine.js
       |-- css
       |   `-- Madeleine.css
       |-- icons
       |   |-- logo.png
       |   |-- madeleine.eot
       |   |-- madeleine.svg
       |   |-- madeleine.ttf
       |   `-- madeleine.woff
       `-- lib
           |-- MadeleineConverter.js
           |-- MadeleineLoader.js
           |-- detector.js
           |-- stats.js
           `-- three.min.js
 ```
 Then restart Gitea and open a STL file on your Gitea instance.
 ## Customizing Gitea mails
 The `$GITEA_CUSTOM/templates/mail` folder allows changing the body of every mail of Gitea.
@@ -295,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
@@ -321,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
@@ -380,13 +482,27 @@ To make a custom theme available to all users:
  The value of `$GITEA_CUSTOM` of your instance can be queried by calling `gitea help` and looking up the value of "CustomPath".
 2. Add `<theme-name>` to the comma-separated list of setting `THEMES` in `app.ini`, or leave `THEMES` empty to allow all themes.
 A custom theme file named `theme-my-theme.css` will be displayed as `my-theme` on the user's theme selection page.
 It could add theme meta information into the custom theme CSS file to provide more information about the theme.
 If a custom theme is a dark theme, please set the global css variable `--is-dark-theme: true` in the `:root` block.
 This allows Gitea to adjust the Monaco code editor's theme accordingly.
 An "auto" theme could be implemented by using "theme-gitea-auto.css" as a reference.
 ```css
 gitea-theme-meta-info {
  --theme-display-name: "My Awesome Theme"; /* this theme will be display as "My Awesome Theme" on the UI */
 }
 :root {
  --is-dark-theme: true; /* if it is a dark theme */
  --color-primary: #112233;
  /* more custom theme variables ... */
 }
 ```
 Community themes are listed in [gitea/awesome-gitea#themes](https://gitea.com/gitea/awesome-gitea#themes).
 The default theme sources can be found [here](https://github.com/go-gitea/gitea/blob/main/web_src/css/themes).
 If your custom theme is considered a dark theme, set the global css variable `--is-dark-theme` to `true`.
 This allows Gitea to adjust the Monaco code editor's theme accordingly.
 ## Customizing fonts
 Fonts can be customized using CSS variables:
@@ -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.
@@ -23,7 +23,7 @@ In order to get file rendering through external binaries, their associated packa
 If you're using a Docker image, your `Dockerfile` should contain something along this lines:
 ```docker
-FROM docker.io/gitea/gitea:@dockerVersion@
+FROM docker.gitea.com/gitea:@dockerVersion@
 [...]
 COPY custom/app.ini /data/gitea/conf/app.ini
@@ -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,8 +54,10 @@ 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"}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
+$ curl -H "Content-Type: application/json" \
-{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
+-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"}
 ```
 The ``sha1`` (the token) is only returned once and is not stored in
@@ -48,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).
@@ -80,6 +80,7 @@ The approval page displayed to the user shows the list of scopes requested by th
 | OpenID Connect Discovery | `/.well-known/openid-configuration` |
 | Authorization Endpoint   | `/login/oauth/authorize`            |
 | Access Token Endpoint    | `/login/oauth/access_token`         |
 | Token Introspection Endpoint | `/login/oauth/introspect`           |
 | OpenID Connect UserInfo  | `/login/oauth/userinfo`             |
 | JSON Web Key Set         | `/login/oauth/keys`                 |
@@ -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.
@@ -330,9 +330,9 @@ It is highly recommended to back-up your database before running these commands.
 - Add your (bare) repositories to the correct spot for your configuration (`repository.ROOT`), ensuring they are in the correct layout `<REPO_ROOT>/[user]/[repo].git`.
  - **Note:** the directory names must be lowercase.
-  - You can also check `<ROOT_URL>/admin/config` for the repository root path.
+  - You can also check `<ROOT_URL>/-/admin/config` for the repository root path.
 - Ensure that the user/org exists that you want to adopt repositories for.
- As an admin, go to `<ROOT_URL>/admin/repos/unadopted` and search.
+- As an admin, go to `<ROOT_URL>/-/admin/repos/unadopted` and search.
  - Users can also be given similar permissions via config [`ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES`](../administration/config-cheat-sheet.md#repository-repository).
 - If the above steps are done correctly, you should be able to select repositories to adopt.
  - If no repositories are found, enable [debug logging](../administration/config-cheat-sheet.md#repository-repository) to check for any specific errors.
@@ -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"
  }
 }
@@ -24,9 +24,10 @@ All steps below requires that the database engine of your choice is installed on
 ## MySQL/MariaDB
-1. For remote database setup, you will need to make MySQL listen to your IP address. Edit `bind-address` option on `/etc/mysql/my.cnf` on database instance to:
+1. For remote database setup, you will need to make MySQL listen to your IP address. Configure the `bind-address` option in `/etc/mysql/my.cnf` on database instance by adding the following lines:
    ```ini
    [mysqld]
    bind-address = 203.0.113.3
    ```
@@ -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,19 +8,23 @@ 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
-The most simple setup just creates a volume and a network and starts the `docker.io/gitea/gitea:latest-rootless`
+The most simple setup just creates a volume and a network and starts the `docker.gitea.com/gitea:latest-rootless`
 image as a service. Since there is no database available, one can be initialized using SQLite3.
 Create a directory for `data` and `config`:
@@ -34,11 +38,9 @@ touch docker-compose.yml
 Then paste the following content into a file named `docker-compose.yml`:
 ```yaml
 version: "2"
 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
    volumes:
      - ./data:/var/lib/gitea
@@ -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.io/gitea/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.io/gitea/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.io/gitea/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
@@ -184,7 +84,7 @@ version: "2"
 +
 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
    volumes:
 -      - ./data:/var/lib/gitea
@@ -207,11 +107,9 @@ 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.io/gitea/gitea:@dockerVersion@-rootless
+    image: docker.gitea.com/gitea:@dockerVersion@-rootless
    restart: always
 +    user: 1001
    volumes:
@@ -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.io/gitea/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,13 +12,20 @@ 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
-The most simple setup just creates a volume and a network and starts the `docker.io/gitea/gitea:latest`
+The most simple setup just creates a volume and a network and starts the `docker.gitea.com/gitea:latest`
 image as a service. Since there is no database available, one can be initialized using SQLite3.
 Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
 Note that the volume should be owned by the user/group with the UID/GID specified in the config file.
@@ -26,15 +33,13 @@ 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
 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -58,15 +63,13 @@ 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
 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -93,15 +96,13 @@ 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
 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -143,16 +144,21 @@ 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
 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
@@ -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
@@ -208,7 +212,7 @@ networks:
 +
 services:
  server:
-    image: docker.io/gitea/gitea:@dockerVersion@
+    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    restart: always
    networks:
@@ -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
@@ -266,6 +264,8 @@ files; for named volumes, this is done through another container or by direct ac
 `/var/lib/docker/volumes/gitea_gitea/_data`. The configuration file will be saved at
 `/data/gitea/conf/app.ini` after the installation.
 Example: Analogous to the non-docker-installation customization linked above, you can create a `/public` folder within `/data/gitea` and place your custom `robots.txt` there which will then be served normally.
 ## Upgrading
 :::warning
@@ -277,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
@@ -316,8 +317,8 @@ Gitea will generate new secrets/tokens for every new installation automatically
 The following commands will output a new `SECRET_KEY` and `INTERNAL_TOKEN` to `stdout`, which you can then place in your environment variables.
 ```bash
-docker run -it --rm docker.io/gitea/gitea:1 gitea generate secret SECRET_KEY
+docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret SECRET_KEY
-docker run -it --rm docker.io/gitea/gitea:1 gitea generate secret INTERNAL_TOKEN
+docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKEN
 ```
 ```yaml
@@ -329,316 +330,7 @@ services:
      - GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
 ```
-## SSH Container Passthrough
+### SSH with multiple IP addresses
-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.
+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.
 ### 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.
@@ -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.
@@ -1,12 +1,10 @@
 ---
 date: "2021-05-14T00:00:00-00:00"
 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"
  }
 }
@@ -16,7 +16,7 @@ It is designed to be compatible with [GitHub Actions workflow badge](https://doc
 You can use the following URL to get the badge:
 ```
-https://your-gitea-instance.com/{owner}/{repo}/actions/workflows/{workflow_file}/badge.svg?branch={branch}&event={event}
+https://your-gitea-instance.com/{owner}/{repo}/actions/workflows/{workflow_file}/badge.svg?branch={branch}&event={event}&style={style}
 ```
 - `{owner}`: The owner of the repository.
@@ -24,3 +24,4 @@ https://your-gitea-instance.com/{owner}/{repo}/actions/workflows/{workflow_file}
 - `{workflow_file}`: The name of the workflow file.
 - `{branch}`: Optional. The branch of the workflow. Default to your repository's default branch.
 - `{event}`: Optional. The event of the workflow. Default to none.
 - `{style}`: Optional. Style of the badge, either `flat` or `flat-square`. Default to `flat`.
@@ -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,6 +55,23 @@ 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 Gitea Runner?
 We released official binaries for Linux, macOS, and Windows.
 While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
 One thing to note is that if you choose to run jobs directly on the host instead of in job containers, the environmental differences between operating systems may cause unexpected failures.
 For example, bash is not available on Windows in most cases, while act tries to use bash to run scripts by default.
 Therefore, you need to specify `powershell` as the default shell in your workflow file, see [defaults.run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun).
 ```yaml
 defaults:
  run:
    shell: powershell
 ```
 ## How to avoid being hacked?
 There are two types of possible attacks: unknown runner stealing the code or secrets from your repository, or malicious scripts controlling your runner.
@@ -72,22 +89,6 @@ Here's how we do it on [gitea.com](http://gitea.com/):
 - To run actions for fork pull requests, approval is required. See [#22803](https://github.com/go-gitea/gitea/pull/22803).
 - If someone registers their own runner for their repository or organization on [gitea.com](http://gitea.com/), we have no objections and will just not use it in our org. However, they should take care to ensure that the runner is not used by other users they do not know.
 ## Which operating systems are supported by act runner?
 It works well on Linux, macOS, and Windows.
 While other operating systems are theoretically supported, they require further testing.
 One thing to note is that if you choose to run jobs directly on the host instead of in job containers, the environmental differences between operating systems may cause unexpected failures.
 For example, bash is not available on Windows in most cases, while act tries to use bash to run scripts by default.
 Therefore, you need to specify `powershell` as the default shell in your workflow file, see [defaults.run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun).
 ```yaml
 defaults:
  run:
    shell: powershell
 ```
 ## Why choose GitHub Actions? Why not something compatible with GitLab CI/CD?
 [@lunny](https://gitea.com/lunny) has explained this in the [issue to implement actions](https://github.com/go-gitea/gitea/issues/13539).
@@ -100,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.
+Unfortunately, the runner does not work this way until v0.2.11.
 As mentioned, we map labels to environments:
 - `ubuntu` → `ubuntu:22.04`
@@ -116,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?
@@ -131,36 +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.
+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, so anyone can create a new/better implementation.
+
-We support your choice, no matter how you decide.
+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.
@@ -10,7 +10,7 @@ Starting with Gitea **1.19**, Gitea Actions are available as a built-in CI/CD so
 ## Name
-It is similar and compatible to [GitHub Actions](https://github.com/features/actions), and its name is inspired by it too.
+It is similar and mostly compatible to [GitHub Actions](https://github.com/features/actions), and its name is inspired by it too.
 To avoid confusion, we have clarified the spelling here:
 - "Gitea Actions" (with an "s", both words capitalized) is the name of the Gitea feature.
@@ -21,8 +21,8 @@ To avoid confusion, we have clarified the spelling here:
 ## Runners
 Just like other CI/CD solutions, Gitea doesn't run the jobs itself, but delegates the jobs to runners.
-The runner of Gitea Actions is called [act runner](https://gitea.com/gitea/act_runner), it is a standalone program and also written in Go.
+The runner of Gitea Actions is called [Gitea Runner](https://gitea.com/gitea/runner), it is a standalone program and also written in Go.
-It is based on a [fork](https://gitea.com/gitea/act) of [nektos/act](http://github.com/nektos/act).
+An important part of the application comes from a hard fork of [nektos/act](http://github.com/nektos/act).
 Because the runner is deployed independently, there could be potential security issues.
 To avoid them, please follow two simple rules:
@@ -35,8 +35,4 @@ However, for public Gitea instances, such as [gitea.com](https://gitea.com), the
 ## Status
-Gitea Actions is still under development, so there may be some bugs and missing features.
+Gitea Actions is stable enough for production usage and we use Gitea Actions in all the repositories in https://gitea.com/gitea.
 And breaking changes may be made before it's stable (v1.20 or later).
 If the situation changes, we will update it here.
 So please refer to the content here when you find outdated articles elsewhere.
@@ -25,12 +25,12 @@ If you want to learn more or encounter any problems while configuring it, please
 ### Set up runner
-Gitea Actions requires [act runner](https://gitea.com/gitea/act_runner) to run the jobs.
+Gitea Actions requires [Gitea Runner](https://gitea.com/gitea/runner) to run the jobs.
 In order to avoid consuming too many resources and affecting the Gitea instance, it is recommended to start runners on separate machines from the Gitea instance.
-You can use the [pre-built binaries](http://dl.gitea.com/act_runner) or the [docker images](https://hub.docker.com/r/gitea/act_runner/tags) to set up the runner.
+You can use the [pre-built binaries](http://dl.gitea.com/gitea-runner) or the [docker images](https://hub.docker.com/r/gitea/runner/tags) to set up the runner.
-Before proceeding any further, we suggest running it as a command line with pre-built binaries to ensure that it works with your environment, especially if you are running a runner on your local host.
+Before proceeding any further, we suggest running it as a command line with pre-built binaries to ensure that it works with your environment, especially if you are running a runner on your localhost.
 And it could be easier to debug if something goes wrong.
 The runner can run the jobs in isolated Docker containers, so you need to make sure that the Docker has been installed and Docker daemon is running.
@@ -40,7 +40,7 @@ However, it is recommended to use Docker to run the jobs, because it is more sec
 Before running a runner, you should first register it to your Gitea instance using the following command:
 ```bash
-./act_runner register --no-interactive --instance <instance> --token <token>
+./runner register --no-interactive --instance <instance> --token <token>
 ```
 There are two arguments required, `instance` and `token`.
@@ -55,7 +55,7 @@ If you are unsure which address to use, the LAN address is usually the right cho
 Each token can be used to create multiple runners, until it is replaced with a new token using the reset link.
 You can obtain different levels of 'tokens' from the following places to create the corresponding level of 'runners':
- Instance level: The admin settings page, like `<your_gitea.com>/admin/actions/runners`.
+- Instance level: The admin settings page, like `<your_gitea.com>/-/admin/actions/runners`.
 - Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`.
 - Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`.
@@ -69,14 +69,14 @@ If this file is missing or corrupted, you can simply remove it and register agai
 Finally, it's time to start the runner:
 ```bash
-./act_runner daemon
+./runner daemon
 ```
 And you can see the new runner in the management page:
 ![view runner](/images/usage/actions/view-runner.png)
-You can find more information by visiting [Act runner](usage/actions/act-runner.md).
+You can find more information by visiting [Gitea Runner](runner.mdx).
 ### Use Actions
@@ -115,7 +115,7 @@ jobs:
 :::warning
-Certain actions may not function correctly within SHA256 repositories. This includes [actions/checkout](https://github.com/actions/checkout/issues/1843).
+Certain actions may not function correctly within SHA256 repositories or when Gitea runs on subpath. This includes [actions/checkout](https://github.com/actions/checkout/issues/1843).
 :::
@@ -0,0 +1,53 @@
 ---
 date: "2023-04-27T15:00:00+08:00"
 slug: "runner"
 sidebar_position: 20
 ---
 # Gitea Runner
 This page will introduce the [Gitea Runner](https://gitea.com/gitea/runner), which is the runner for Gitea Actions.
 :::tip
 For detailed installation, configuration, and usage instructions, see the [Gitea Runner documentation](/runner/).
 :::
 ## Obtain a registration token
 You can register a runner at different levels. It can be:
 - Instance level: The runner will run jobs for all repositories in the instance.
 - Organization level: The runner will run jobs for all repositories in the organization.
 - Repository level: The runner will run jobs for the repository it belongs to.
 Note that the repository may still use instance-level or organization-level runners even if it has its own repository-level runners. A future release may provide an option to allow more control over this.
 Before registering the runner and running it, you need a registration token. The level of the runner determines where to obtain the registration token.
 - Instance level: The admin settings page, like `<your_gitea.com>/-/admin/actions/runners`.
 - Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`.
 - Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`.
 If you cannot see the settings page, please make sure that you have the right permissions and that Actions have been enabled.
 The format of the registration token is a random string `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`.
 A registration token can also be obtained from the Gitea [command-line interface](../../administration/command-line.md#actions-generate-runner-token):
 ```
 gitea --config /etc/gitea/app.ini actions generate-runner-token
 ```
 You can also use `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variables to set a global runner registration token when Gitea starts, for example:
 ```
 openssl rand -hex 24 > /some-dir/runner-token
 export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
 ./gitea --config ...
 ```
 The token from the environment is valid until you reset the token (re-create a new one) via the web UI or API.
 Tokens are valid for registering multiple runners, until they are revoked and replaced by a new token using the token reset link in the web interface.
 Once you have a registration token, follow the [Gitea Runner documentation](/runner/) to install, configure, and run your runner.
@@ -0,0 +1,119 @@
 ---
 date: "2026-06-26T00:00:00+00:00"
 slug: "scoped-workflows"
 sidebar_position: 60
 ---
 # Scoped Workflows
 Scoped workflows let you maintain Actions workflows in one central **source** repository and have them run automatically on many other repositories, without copying the workflow files into each one.
 A workflow file committed under a source repository's scoped-workflow directory runs on every repository that the source applies to (a "consuming" repository). Each run executes **in the consuming repository's own context**: its runners, secrets, `GITEA_TOKEN`, and branch, while the workflow **content is read from the source repository**. This is useful for mandating shared CI across an organization or instance: linting, security scans, compliance or policy checks, and similar.
 ## Levels
 A source repository can be registered at two levels:
 - **Owner level**: registered by an organization or user. The source's workflows run on every repository owned by that organization or user.
 - **Instance level**: registered by a site administrator. The source's workflows run on **every** repository on the instance.
 The same repository may be registered at both levels; it is still evaluated once per matching event.
 :::note
 Instance-level sources apply to **every** repository on the instance, and a required one cannot be opted out. Detection runs on every repository's events. Register them deliberately.
 :::
 ## Configuration
 Scoped workflows live in a directory that is separate from regular workflows. It is controlled by `SCOPED_WORKFLOW_DIRS` in the `[actions]` section of `app.ini`:
 ```ini
 [actions]
 SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
 ```
 - The default is `.gitea/scoped_workflows`.
 - It may list multiple directories (comma-separated).
 - It **must not overlap** with `WORKFLOW_DIRS` (the regular workflow directories, by default `.gitea/workflows` and `.github/workflows`).
 - Leaving it empty means no directory holds scoped workflows, so none are found or run. The settings page still appears and sources can still be registered, but no scoped workflow runs.
 Keeping scoped workflows in their own directory means a source repository's *own* Actions are unaffected: only files under `SCOPED_WORKFLOW_DIRS` are treated as scoped workflows.
 ## Providing scoped workflows from a repository
 1. In the would-be source repository, commit your workflow files under the scoped-workflow directory on its **default branch**, for example `.gitea/scoped_workflows/lint.yaml`:
   ```yaml
   name: Lint
   on: [push, pull_request]
   jobs:
     lint:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: echo "lint the consuming repository here"
   ```
 2. Register the repository as a source:
   - **Organization**: *Organization Settings -> Actions -> Scoped Workflows*
   - **User**: *User Settings -> Actions -> Scoped Workflows*
   - **Instance (admin)**: *Site Administration -> Actions -> Scoped Workflows*
   Search for and add the repository. From then on, its scoped workflows apply to the consuming repositories at that level.
 The source repository is within its own scope, so it runs these workflows on itself like any other consumer.
 ## How scoped workflows run
 - The run belongs to the **consuming** repository and uses its runners, secrets, `GITEA_TOKEN`, and ref. It behaves like a normal run there, including rerun, logs, and commit statuses.
 - The workflow **content is read from the source** repository, pinned to the source's default-branch commit at the time of the event.
 - Detection uses the consuming repository's event, so the workflow's `on:` triggers (such as `push` and `pull_request`) must match that event.
 ## Opting out
 A consuming repository can disable a scoped workflow it does not want, from its **Actions** page (the workflow appears under its source). A workflow that has been marked **required** (see below) can never be disabled or opted out by a consuming repository.
 ## Required workflows and the merge gate
 On the Scoped Workflows settings page you can mark individual workflows as **required** and give each one or more **status-check patterns** (one glob per line). A required scoped workflow:
 - Cannot be disabled by consuming repositories.
 - Gates pull-request merges: a consuming pull request can only be merged once a commit status matching **every** pattern has **passed** (must-present-and-pass). A required check that never posts a status **blocks** the merge rather than being silently skipped, so disabling Actions on the consumer cannot bypass it.
 The status-check context a scoped run posts has the form:
 ```
 <source repo full name>: <workflow display name> / <job> (<event>)
 ```
 The settings page previews these "Expected status checks" for each workflow and marks the ones your patterns match, so you can confirm a pattern is correct. A common pattern wildcards the job and event, for example `my-org/ci-repo: Lint / *`.
 Enforcement scope:
 - A required check is enforced on any target branch that has a **branch protection rule**, even one whose own status checks are disabled.
 - A target branch with **no** protection rule is not gated.
 :::warning
 Only a workflow that runs on an event that posts a commit status (`push`, `pull_request`, `pull_request_target`, `release`) can be required. A workflow that runs only on events like `workflow_dispatch`, `schedule` or `workflow_call` posts no status, so marking it required would block every consuming pull request forever. The settings page warns you in this case.
 :::
 ## Reusable workflows (`uses:`)
 Scoped workflows can call reusable workflows:
 - A **local** reference (`uses: ./...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
 - A **cross-repository** reference (`uses: owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
 A reusable workflow can live under `SCOPED_WORKFLOW_DIRS` (or `WORKFLOW_DIRS`) of the source repository.
 ## Security considerations
 A source repository's workflow content is executed in every repository it applies to, and its step scripts and their output are written to that repository's Actions logs, readable by anyone who can view the consuming repository's Actions.
 - Registering a **private** repository as a source therefore discloses its workflow logic through those logs. Only register repositories whose workflow content may be shared with every consuming repository.
 ## Limitations
 - `on: schedule` and `on: workflow_run` are currently not supported as scoped workflow triggers.
 - Scoped workflow content is read from the source's default branch; other branches of the source are not used.
@@ -0,0 +1,115 @@
 ---
 date: "2026-03-19T00:00:00+01:00"
 slug: "token-permissions"
 sidebar_position: 30
 ---
 # Actions job token permissions (`GITEA_TOKEN`)
 Every Actions job receives a built-in token (`GITEA_TOKEN`) which can be used to access Gitea (Git over HTTP(S), API requests, etc.).
 This page documents how Gitea decides what the token is allowed to do.
 In workflows, it is available as `${{ secrets.GITEA_TOKEN }}`. These settings and `permissions:` only affect `GITEA_TOKEN` (not other secrets like personal access tokens). For API calls, see [API authentication](../../development/api-usage.md#authentication).
 ## Where permissions come from
 Gitea determines the job token permissions in this order:
 1. Job-level `permissions:` (`jobs.<job_id>.permissions`)
 2. Workflow-level `permissions:` (top-level)
 3. Default permissions from settings (owner or repository)
 The result is then **clamped** by the configured maximum token permissions (see below).
 ## Supported workflow syntax
 Gitea supports the GitHub Actions-compatible `permissions:` keyword.
 ### Scalar values
 ```yaml
 permissions: read-all   # or: write-all
 ```
 ### Scoped mapping
 ```yaml
 permissions:
  contents: read
  issues: write
  pull-requests: none
 ```
 Valid access mode values for each scope are `read`, `write`, and `none`.
 ### Supported scopes
 - `contents` (applies to `code` and `releases`)
 - `code`
 - `releases`
 - `issues`
 - `pull-requests`
 - `actions`
 - `wiki`
 - `projects`
 - `packages` (if supported by the target feature)
 If you specify both `contents` and a more granular scope (like `code` or `releases`), the granular scope wins for that unit.
 ### Compatibility notes
 Gitea supports a subset of GitHub Actions permission scopes.
 GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not currently supported by Gitea Actions.
 Gitea also exposes repository-unit scopes that do not exist as separate scopes in GitHub Actions:
 - `code`
 - `releases`
 - `wiki`
 - `projects`
 ## Default permission mode
 If neither the workflow nor the job defines `permissions:`, Gitea uses the configured default mode:
 - **Permissive**: read and write permissions for most units in the job's repository (backwards-compatible default).
 - **Restricted**: read-only permissions for `code`, `releases`, and `packages` in the job's repository, and no access to other units by default.
 ## Maximum token permissions (clamping)
 You can configure a maximum permission per repository unit.
 The job's effective permissions are computed as:
 `effective = min(requested, maximum)`
 This means workflows can reduce permissions for a job, but cannot exceed your configured maximum.
 If you don't configure a maximum, the maximum defaults to `write` for all scopes.
 ## Where to configure
 You can configure defaults and maximums at:
 - **User / Organization**: `Settings` → `Actions` → `General`
 - **Repository**: `Settings` → `Actions` → `General`
  - For repositories in an organization, the repository can follow the owner-level configuration, or opt out with **Override owner-level configuration**.
 Note: Repository-level token permission settings are only shown once **Repository Actions** are enabled.
 ## Fork pull requests
 For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings.
 ## Cross-repository access
 By default, `GITEA_TOKEN` only has access to:
 - The job's repository (according to the computed permissions)
 - Public repositories (read-only)
 Access to other private repositories is denied by default.
 A user or organization can allow read-only access to selected private repositories via **Settings → Actions → General → Cross-Repository Access**.
 Private repositories can also allow selected collaborative owners via **Settings → Actions → General**.
 This allows the private repositories of those owners to read the current private repository for Actions use, such as private actions and reusable workflows.
 Fork pull request workflows never gain cross-repository access to private repositories, even if those repositories are listed.
@@ -6,11 +6,171 @@ sidebar_position: 25
 # Variables
 ## Environment variables
 These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts).
 | Name | Description | Example |
 |---|---|---|
 | `CI` | Always set to `true`. | `true` |
 | `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` |
 | `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `1.0.8` |
 | `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42_***/_data` |
 | `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
 | `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` |
 | `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
 | `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/home/runner/work/_temp/_runner_file_commands/save_state_***` |
 | `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/home/runner/work/_temp/_runner_file_commands/step_summary_***` |
 | `GITHUB_ACTIONS` | Always set to `true`. | `true` |
 | `GITHUB_ACTION` | The name of the action currently running, or the step `id`. | `__run` |
 | `GITHUB_ACTION_PATH` | The path where the action is located. | `/home/runner/work/_actions/actions/checkout/v4` |
 | `GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` |
 | `GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` |
 | `GITHUB_ACTOR` | The username of the user that triggered the workflow. | `silverwind` |
 | `GITHUB_API_URL` | The URL of the REST API. | `https://gitea.com/api/v1` |
 | `GITHUB_BASE_REF` | The target branch of a pull request. | `main` |
 | `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` |
 | `GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
 | `GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ |
 | `GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` |
 | `GITHUB_JOB` | The `job_id` of the current job. | `build` |
 | `GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
 | `GITHUB_REF_NAME` | The short ref name. | `main` |
 | `GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
 | `GITHUB_REPOSITORY` | The owner and repository name. | `gitea/docs` |
 | `GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `gitea` |
 | `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. | `90` |
 | `GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
 | `GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` |
 | `GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` |
 | `GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.com` |
 | `GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
 | `GITHUB_WORKFLOW` | The name of the workflow. | `CI` |
 | `GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/gitea/docs` |
 ### Runner environment variables
 | Name | Description | Example |
 |---|---|---|
 | `RUNNER_ARCH` | The architecture of the runner. | `X64` |
 | `RUNNER_OS` | The operating system of the runner. | `Linux` |
 | `RUNNER_TEMP` | Path to a temporary directory on the runner. | `/tmp` |
 | `RUNNER_TOOL_CACHE` | Path to the tool cache directory on the runner. | `/opt/hostedtoolcache` |
 ### Internal environment variables
 These are used internally by the runner and actions. They are typically not needed in workflows directly.
 | Name | Description | Example |
 |---|---|---|
 | `ACTIONS_CACHE_URL` | URL for the actions cache service. | `http://192.168.1.10:8088/` |
 | `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when configured. | `***` |
 | `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when configured. | `https://gitea.com/login/oauth/access_token` |
 | `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.com` |
 | `ACTIONS_RUNTIME_TOKEN` | Authentication token for the Actions pipeline API. | `***` |
 | `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.com/api/actions_pipeline/` |
 ## Context variables
 These variables are available in workflow expressions via `${{ gitea.<name> }}`. For compatibility, `${{ github.<name> }}` works as an alias.
 | Name | Description | Example |
 |---|---|---|
 | `gitea.action`<br/>`github.action` | The name of the action currently running, or the `id` of a step. | `__run` |
 | `gitea.action_path`<br/>`github.action_path` | The path where an action is located. Only supported in composite actions. | `/home/runner/work/_actions/actions/checkout/v4` |
 | `gitea.action_ref`<br/>`github.action_ref` | The ref of the action being executed. | `v4` |
 | `gitea.action_repository`<br/>`github.action_repository` | The owner and repository name of the action. | `actions/checkout` |
 | `gitea.action_status`<br/>`github.action_status` | The current result of a composite action. | `success` |
 | `gitea.actor`<br/>`github.actor` | The username of the user that triggered the initial workflow run. | `silverwind` |
 | `gitea.api_url`<br/>`github.api_url` | The URL of the REST API. | `https://gitea.com/api/v1` |
 | `gitea.base_ref`<br/>`github.base_ref` | The target branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `main` |
 | `gitea.env`<br/>`github.env` | Path on the runner to the file that sets environment variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
 | `gitea.event`<br/>`github.event` | The full event webhook payload as an object. See [Event payload](#event-payload). | `{...}` |
 | `gitea.event_name`<br/>`github.event_name` | The name of the event that triggered the workflow run. | `push` |
 | `gitea.event_path`<br/>`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
 | `gitea.head_ref`<br/>`github.head_ref` | The source branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `feature-branch` |
 | `gitea.job`<br/>`github.job` | The `job_id` of the current job. | `build` |
 | `gitea.ref`<br/>`github.ref` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
 | `gitea.ref_name`<br/>`github.ref_name` | The short ref name. | `main` |
 | `gitea.ref_protected`<br/>`github.ref_protected` | `true` if branch protections are configured for the ref that triggered the workflow run. | `true` |
 | `gitea.ref_type`<br/>`github.ref_type` | The type of ref: `branch` or `tag`. | `branch` |
 | `gitea.path`<br/>`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
 | `gitea.repository`<br/>`github.repository` | The owner and repository name. | `gitea/docs` |
 | `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `gitea` |
 | `gitea.repositoryUrl`<br/>`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.com/gitea/docs` |
 | `gitea.retention_days`<br/>`github.retention_days` | The number of days that workflow run logs and artifacts are kept. | `90` |
 | `gitea.run_id`<br/>`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` |
 | `gitea.run_number`<br/>`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` |
 | `gitea.run_attempt`<br/>`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` |
 | `gitea.secret_source`<br/>`github.secret_source` | The source of a secret used in a workflow. Always `Actions` in Gitea. | `Actions` |
 | `gitea.server_url`<br/>`github.server_url` | The URL of the Gitea instance. | `https://gitea.com` |
 | `gitea.sha`<br/>`github.sha` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
 | `gitea.token`<br/>`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `ghs_***` |
 | `gitea.triggering_actor`<br/>`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `silverwind` |
 | `gitea.workflow`<br/>`github.workflow` | The name of the workflow. If unnamed, the full path of the workflow file. | `CI` |
 | `gitea.workspace`<br/>`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/gitea/docs` |
 | `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` |
 ### Event payload
 `gitea.event` is the webhook payload of the event that triggered the run, so which fields exist depends on `gitea.event_name`.
 The same payload is written as JSON to the file at `gitea.event_path`.
 Payloads use Gitea's webhook format, which is close to GitHub's but not identical. Differences are noted below.
 Reading a field that the payload does not have returns an empty value instead of failing, so `${{ gitea.event.pull_request.number }}` is empty on a `push` run.
 These fields exist in almost every payload:
 | Name | Description | Example |
 |---|---|---|
 | `gitea.event.action` | The activity type. Only set for events that have activity types, see [supported events](faq.md#what-workflow-trigger-events-does-gitea-support). | `opened` |
 | `gitea.event.repository.full_name` | The owner and name of the repository. | `gitea/docs` |
 | `gitea.event.repository.default_branch` | The default branch of the repository. | `main` |
 | `gitea.event.repository.private` | Whether the repository is private. | `false` |
 | `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.com/gitea/docs` |
 | `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `silverwind` |
 The remaining fields are specific to one or a few events:
 | Name | Events | Description | Example |
 |---|---|---|---|
 | `gitea.event.schedule` | `schedule` | The cron expression that triggered the run. | `*/5 * * * *` |
 | `gitea.event.inputs.<name>` | `workflow_dispatch`, `workflow_call` | A raw input value. Prefer `${{ inputs.<name> }}`, which also applies the input's `default`. | `true` |
 | `gitea.event.workflow` | `workflow_dispatch` | The file name of the dispatched workflow. | `ci.yaml` |
 | `gitea.event.ref` | `push`, `create`, `delete`, `workflow_dispatch` | The ref of the event. Unlike GitHub, `create` and `delete` use the full ref instead of the short name. | `refs/heads/main` |
 | `gitea.event.ref_type` | `create`, `delete` | The type of ref: `branch` or `tag`. | `tag` |
 | `gitea.event.before`<br/>`gitea.event.after` | `push` | The commit SHA before and after the push. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
 | `gitea.event.commits` | `push` | The commits contained in the push, each with `id`, `message`, `url`, `author`, `added`, `removed` and `modified`. | `[{...}]` |
 | `gitea.event.head_commit.message` | `push` | The message of the most recent commit of the push. | `fix: broken link` |
 | `gitea.event.total_commits` | `push` | The number of commits in the push. Gitea-specific. | `3` |
 | `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.com/gitea/docs/compare/a1b2c3d...e5f6a1b` |
 | `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `silverwind` |
 | `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `silverwind/docs` |
 | `gitea.event.page` | `gollum` | The name of the wiki page. | `Home` |
 | `gitea.event.number` | `issues`, `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The index of the issue or pull request. Not set for `issue_comment`, use `gitea.event.issue.number` there. | `386` |
 | `gitea.event.issue.number`<br/>`gitea.event.issue.title`<br/>`gitea.event.issue.body`<br/>`gitea.event.issue.state`<br/>`gitea.event.issue.labels`<br/>`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Expand gitea.event in actions docs` |
 | `gitea.event.comment.body` | `issue_comment` | The body of the comment. | `LGTM` |
 | `gitea.event.is_pull` | `issue_comment` | Whether the comment was made on a pull request. Gitea-specific, GitHub sets `issue.pull_request` on the issue object instead. | `true` |
 | `gitea.event.pull_request.number`<br/>`gitea.event.pull_request.title`<br/>`gitea.event.pull_request.body`<br/>`gitea.event.pull_request.draft`<br/>`gitea.event.pull_request.merged`<br/>`gitea.event.pull_request.state`<br/>`gitea.event.pull_request.labels`<br/>`gitea.event.pull_request.user.login` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The pull request the event happened on. | `Add caching to CI` |
 | `gitea.event.pull_request.head.ref`<br/>`gitea.event.pull_request.head.sha`<br/>`gitea.event.pull_request.head.repo.full_name` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The source branch of the pull request. | `feature-branch` |
 | `gitea.event.pull_request.base.ref`<br/>`gitea.event.pull_request.base.sha` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The target branch of the pull request. | `main` |
 | `gitea.event.review.type` | `pull_request_review`, `pull_request_review_comment` | The kind of review: `pull_request_review_approved`, `pull_request_review_rejected` or `pull_request_review_comment`. GitHub uses `review.state` with the values `approved`, `changes_requested` and `commented`. | `pull_request_review_approved` |
 | `gitea.event.review.content` | `pull_request_review`, `pull_request_review_comment` | The body of the review. GitHub names this field `review.body`. | `Ship it` |
 | `gitea.event.changes.title.from`<br/>`gitea.event.changes.body.from` | `issues`, `issue_comment`, `pull_request` | The previous value. Only set when `action` is `edited`. | `Old title` |
 | `gitea.event.release.tag_name`<br/>`gitea.event.release.name`<br/>`gitea.event.release.body`<br/>`gitea.event.release.draft`<br/>`gitea.event.release.prerelease` | `release` | The release the event happened on. | `v1.2.3` |
 | `gitea.event.package.name`<br/>`gitea.event.package.type`<br/>`gitea.event.package.version` | `registry_package` | The package the event happened on. | `gitea` |
 | `gitea.event.workflow_run.id`<br/>`gitea.event.workflow_run.event`<br/>`gitea.event.workflow_run.status`<br/>`gitea.event.workflow_run.conclusion`<br/>`gitea.event.workflow_run.head_branch`<br/>`gitea.event.workflow_run.head_sha` | `workflow_run` | The workflow run that the event reports on. | `success` |
 `schedule` runs have no webhook of their own. Their payload is the payload of the push that registered the schedule, with `schedule`, `repository`, `sender` and, for organization-owned repositories, `organization` filled in.
 Only those fields are meaningful, and `sender.login` is always `gitea-actions`.
 ## User-defined variables
 You can create configuration variables on the user, organization and repository level.
 The level of the variable depends on where you created it. When creating a variable, the
 key will be converted to uppercase. You need use uppercase on the yaml file.
-## Naming conventions
+### Naming conventions
 The following rules apply to variable names:
@@ -21,12 +181,12 @@ The following rules apply to variable names:
 - Variable names must be unique at the level they are created at.
 - Variable names must not start with `CI`.
-## Using variable
+### Using variables
 After creating configuration variables, they will be automatically filled in the `vars` context.
 They can be accessed through expressions like `${{ vars.VARIABLE_NAME }}` in the workflow.
-## Precedence
+### Precedence
 If a variable with the same name exists at multiple levels, the variable at the lowest level takes precedence:
 A repository variable will always be chosen over an organization/user variable.
@@ -0,0 +1,9 @@
 {
  "label": "Issues & Pull Requests",
  "position": 20,
  "link": {
    "type": "generated-index",
    "slug": "/usage/issues-prs",
    "description": "Issues and Pull Requests workflow, templates, and collaboration features"
  }
 }
@@ -0,0 +1,52 @@
 ---
 date: "	2022-09-01T20:50:42+0000"
 slug: "agit"
 sidebar_position: 12
 aliases:
  - /en-us/agit-setup
  - /agit-setup
  - /agit
 ---
 # AGit
 In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
 :::note
 Git version 2.29 or higher is required on the server side for this to work.
 :::
 ## Creating PRs with AGit
 AGit allows to create PRs while pushing code to the remote repo.
 This can be done by pushing to a special refspec (a location identifier known to git) instead of to a branch.
 The following example illustrates this:
 ```shell
 git push origin HEAD:refs/for/main -o topic="topic_of_my_PR"
 ```
 The command has the following structure:
 ```shell
 git push <remote> <local-rev>:refs/for/<branch>[/<topic>] [-o <option>[=<value>] ...]
 ```
 - `<remote>`: The remote pointing at the target repository (not a fork!), `origin` in the example above
 - `<local-rev>`: The local branch or commit containing the changes you are proposing, `HEAD` in the example above
 - `refs/for/<branch>`: The target PR type and configuration
  - `for`: Create a normal PR with `<branch>` as the target branch. This is the only prefix supported at the moment, `refs/draft/...` and `refs/for-review/...` are reserved for future use and do not create a PR.
  - `<branch>`: The branch you want your changes to be merged into
  - `<topic>`: Optional, an alternative to `-o topic=<topic>`. The push is rejected with `topic-branch is not set` if the topic is given in neither place.
 - `-o <option>[=<value>]`: Options for the PR
  - `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review (prefixed with your user name). This is REQUIRED to trigger a pull request, unless it is already part of the refspec.
  - `title`: The PR title (optional but recommended), only used for topics not already having an associated PR.
  - `description`: The PR description (optional but recommended), only used for topics not already having an associated PR.
  - `force-push=true`: Specifies whether to force-update the target branch.
    - Note: omitting the value and using just `-o force-push` will also work.
 Here's another example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
 ```shell
 git push origin HEAD:refs/for/main -o topic="topic_of_my_PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
 ```
@@ -1,19 +1,19 @@
 ---
 date: "2018-05-10T16:00:00+02:00"
 slug: "issue-pull-request-templates"
 sidebar_position: 15
-
+aliases:
-
+  - /en-us/issue-pull-request-templates
 ---
 # Issue and Pull Request Templates
 Some projects have a standard list of questions that users need to answer
 when creating an issue or pull request. Gitea supports adding templates to the
-main branch of the repository so that they can autopopulate the form when users are
+**default branch of the repository** so that they can autopopulate the form when users are
 creating issues and pull requests. This will cut down on the initial back and forth
 of getting some clarifying details.
 It is currently not possible to provide generic issue/pull-request templates globally.
 Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one.
@@ -40,6 +40,17 @@ Possible file names for issue templates:
 - `.github/issue_template.yaml`
 - `.github/issue_template.yml`
 Possible file names for issue config:
 - `.gitea/ISSUE_TEMPLATE/config.yaml`
 - `.gitea/ISSUE_TEMPLATE/config.yml`
 - `.gitea/issue_template/config.yaml`
 - `.gitea/issue_template/config.yml`
 - `.github/ISSUE_TEMPLATE/config.yaml`
 - `.github/ISSUE_TEMPLATE/config.yml`
 - `.github/issue_template/config.yaml`
 - `.github/issue_template/config.yml`
 Possible file names for PR templates:
 - `PULL_REQUEST_TEMPLATE.md`
@@ -88,6 +99,9 @@ name: "Template Name"
 about: "This template is for testing!"
 title: "[TEST] "
 ref: "main"
 assignees: ["user1"]
 projects:
  - Example Project
 labels:
 - bug
@@ -100,7 +114,10 @@ This is the template!
 In the above example, when a user is presented with the list of issues they can submit, this would show as `Template Name` with the description
 `This template is for testing!`. When submitting an issue with the above example, the issue title would be pre-populated with
-`[TEST] ` while the issue body would be pre-populated with `This is the template!`. The issue would also be assigned two labels,
+`[TEST] ` while the issue body would be pre-populated with `This is the template!`.
 The issue would be assigned to `user1`.
 The issue would be assigned to the project `Example Project`.
 The issue would also be assigned two labels,
 `bug` and `help needed`, and the issue will have a reference to `main`.
 ## Syntax for yaml template
@@ -116,6 +133,12 @@ body:
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report!
  # some markdown that will only be visible once the issue has been created
  - type: markdown
    attributes:
      value: |
        This issue was created by an issue **template** :)
    visible: [content]
  - type: input
    id: contact
    attributes:
@@ -163,15 +186,21 @@ body:
    id: terms
    attributes:
      label: Code of Conduct
      hide_label: true
      description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
      options:
        - label: I agree to follow this project's Code of Conduct
          required: true
        - label: I have also read the CONTRIBUTION.MD
          required: true
          visible: [form]
        - label: This is a TODO only visible after issue creation
          visible: [content]
 ```
 ### Markdown
-You can use a `markdown` element to display Markdown in your form that provides extra context to the user, but is not submitted.
+You can use a `markdown` element to display Markdown in your form that provides extra context to the user, but is not submitted by default.
 Attributes:
@@ -179,19 +208,22 @@ Attributes:
 |-------|--------------------------------------------------------------|----------|--------|---------|--------------|
 | value | The text that is rendered. Markdown formatting is supported. | Required | String | -       | -            |
 visible: Default is **[form]**
 ### Textarea
 You can use a `textarea` element to add a multi-line text field to your form. Contributors can also attach files in `textarea` fields.
 Attributes:
-| Key         | Description                                                                                                                                                                   | Required | Type   | Default      | Valid values              |
+| Key         | Description                                                                                                                                                                   | Required | Type    | Default      | Valid values              |
-|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------|--------------|---------------------------|
+|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|--------------|---------------------------|
-| label       | A brief description of the expected user input, which is also displayed in the form.                                                                                          | Required | String | -            | -                         |
+| label       | A brief description of the expected user input, which is also displayed in the form.                                                                                          | Required | String  | -            | -                         |
-| description | A description of the text area to provide context or guidance, which is displayed in the form.                                                                                | Optional | String | Empty String | -                         |
+| hide_label  | If true, the label normally used as a headline is not visible.                                                                                                                | Optional | Boolean | false        | -                         |
-| placeholder | A semi-opaque placeholder that renders in the text area when empty.                                                                                                           | Optional | String | Empty String | -                         |
+| description | A description of the text area to provide context or guidance, which is displayed in the form.                                                                                | Optional | String  | Empty String | -                         |
-| value       | Text that is pre-filled in the text area.                                                                                                                                     | Optional | String | -            | -                         |
+| placeholder | A semi-opaque placeholder that renders in the text area when empty.                                                                                                           | Optional | String  | Empty String | -                         |
-| render      | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | Optional | String | -            | Languages known to Gitea. |
+| value       | Text that is pre-filled in the text area.                                                                                                                                     | Optional | String  | -            | -                         |
 | render      | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | Optional | String  | -            | Languages known to Gitea. |
 Validations:
@@ -199,18 +231,21 @@ Validations:
 |----------|------------------------------------------------------|----------|---------|---------|--------------|
 | required | Prevents form submission until element is completed. | Optional | Boolean | false   | -            |
 visible: Default is **[form, content]**
 ### Input
 You can use an `input` element to add a single-line text field to your form.
 Attributes:
-| Key         | Description                                                                                | Required | Type   | Default      | Valid values |
+| Key         | Description                                                                                | Required | Type    | Default      | Valid values |
-|-------------|--------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
+|-------------|--------------------------------------------------------------------------------------------|----------|---------|--------------|--------------|
-| label       | A brief description of the expected user input, which is also displayed in the form.       | Required | String | -            | -            |
+| label       | A brief description of the expected user input, which is also displayed in the form.       | Required | String  | -            | -            |
-| description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | -            |
+| hide_label  | If true, the label normally used as a headline is not visible.                             | Optional | Boolean | false        | -            |
-| placeholder | A semi-transparent placeholder that renders in the field when empty.                       | Optional | String | Empty String | -            |
+| description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String  | Empty String | -            |
-| value       | Text that is pre-filled in the field.                                                      | Optional | String | -            | -            |
+| placeholder | A semi-transparent placeholder that renders in the field when empty.                       | Optional | String  | Empty String | -            |
 | value       | Text that is pre-filled in the field.                                                      | Optional | String  | -            | -            |
 Validations:
@@ -220,6 +255,8 @@ Validations:
 | is_number | Prevents form submission until element is filled with a number.                                  | Optional | Boolean | false   | -                                                                        |
 | regex     | Prevents form submission until element is filled with a value that match the regular expression. | Optional | String  | -       | a [regular expression](https://en.wikipedia.org/wiki/Regular_expression) |
 visible: Default is **[form, content]**
 ### Dropdown
 You can use a `dropdown` element to add a dropdown menu in your form.
@@ -229,8 +266,10 @@ Attributes:
 | Key         | Description                                                                                         | Required | Type         | Default      | Valid values |
 |-------------|-----------------------------------------------------------------------------------------------------|----------|--------------|--------------|--------------|
 | label       | A brief description of the expected user input, which is displayed in the form.                     | Required | String       | -            | -            |
 | hide_label  | If true, the label normally used as a headline is not visible.                                      | Optional | Boolean | false        | -            |
 | description | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | Optional | String       | Empty String | -            |
 | multiple    | Determines if the user can select more than one option.                                             | Optional | Boolean      | false        | -            |
 | list        | If true, display as a list. If false, print items on one line with commas.                          | Optional | Boolean      | false        | -            |
 | options     | An array of options the user can choose from. Cannot be empty and all choices must be distinct.     | Required | String array | -            | -            |
 Validations:
@@ -239,21 +278,54 @@ Validations:
 |----------|------------------------------------------------------|----------|---------|---------|--------------|
 | required | Prevents form submission until element is completed. | Optional | Boolean | false   | -            |
 visible: Default is **[form, content]**
 ### Checkboxes
 You can use the `checkboxes` element to add a set of checkboxes to your form.
 Attributes:
-| Key         | Description                                                                                           | Required | Type   | Default      | Valid values |
+| Key         | Description                                                                                           | Required | Type    | Default      | Valid values |
-|-------------|-------------------------------------------------------------------------------------------------------|----------|--------|--------------|--------------|
+|-------------|-------------------------------------------------------------------------------------------------------|----------|---------|--------------|--------------|
-| label       | A brief description of the expected user input, which is displayed in the form.                       | Required | String | -            | -            |
+| label       | A brief description of the expected user input, which is displayed in the form.                       | Required | String  | -            | -            |
-| description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String | Empty String | -            |
+| hide_label  | If true, the label normally used as a headline is not visible.                                        | Optional | Boolean | false        | -            |
-| options     | An array of checkboxes that the user can select. For syntax, see below.                               | Required | Array  | -            | -            |
+| description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String  | Empty String | -            |
 | options     | An array of checkboxes that the user can select. For syntax, see below.                               | Required | Array   | -            | -            |
 For each value in the options array, you can set the following keys.
-| Key      | Description                                                                                                                              | Required | Type    | Default | Options |
+| Key          | Description                                                                                                                              | Required | Type         | Default | Options |
-|----------|------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|---------|---------|
+|--------------|------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------|---------|---------|
-| label    | The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks. | Required | String  | -       | -       |
+| label        | The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks. | Required | String       | -       | -       |
-| required | Prevents form submission until element is completed.                                                                                     | Optional | Boolean | false   | -       |
+| required     | Prevents form submission until element is completed.                                                                                     | Optional | Boolean      | false   | -       |
 | visible      | Whether a specific checkbox appears in the form only, in the created issue only, or both. Valid options are "form" and "content".        | Optional | String array | false   | -       |
 visible: Default is **[form, content]**
 ## Syntax for issue config
 This is a example for a issue config file
 ```yaml
 blank_issues_enabled: true
 contact_links:
  - name: Gitea
    url: https://gitea.com
    about: Visit the Gitea Website
 ```
 ### Possible Options
 | Key                  | Description                                           | Type               | Default     |
 |----------------------|-------------------------------------------------------|--------------------|-------------|
 | blank_issues_enabled | If set to false, the User is forced to use a Template | Boolean            | true        |
 | contact_links        | Custom Links to show in the Choose Box                | Contact Link Array | Empty Array |
 ### Contact Link
 | Key   | Description                      | Type   | Required |
 |-------|----------------------------------|--------|----------|
 | name  | the name of your link            | String | true     |
 | url   | The URL of your Link             | String | true     |
 | about | A short description of your Link | String | true     |
@@ -1,12 +1,9 @@
 ---
 date: "2023-03-04T19:00:00+00:00"
 slug: "labels"
 sidebar_position: 13
 aliases:
  - /en-us/labels
 ---
 # Labels
@@ -21,7 +18,7 @@ For organizations, you can define organization-wide labels that are shared with
 Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
-When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../administration/customizing-gitea/#labels). Its contained labels will all be created as well while creating the repository.
+When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
 ## Scoped Labels
@@ -85,7 +85,7 @@ Sometimes a commit or pull request may fix or bring back a problem documented
 in a particular issue. Gitea supports closing and reopening the referenced
 issues by preceding the reference with a particular _keyword_. Common keywords
 include "closes", "fixes", "reopens", etc. This list can be
-[customized](../administration/config-cheat-sheet.md) by the
+[customized](../../administration/config-cheat-sheet.md) by the
 site administrator.
 Example:
@@ -188,5 +188,7 @@ _The last section is for repositories with external issue trackers that use alph
 _**-**: not applicable._
-Note: automatic references between repositories with different types of issues (external vs. internal) are not fully supported
+:::note
 Automatic references between repositories with different types of issues (external vs. internal) are not fully supported
 and may render invalid links.
 :::
@@ -0,0 +1,47 @@
 ---
 date: "2022-08-31T17:35:40+08:00"
 slug: "merge-message-templates"
 sidebar_position: 15
 aliases:
  - /en-us/merge-message-templates
 ---
 # Merge Message templates
 ## File names
 Possible file names for PR default merge message templates:
 - `.gitea/default_merge_message/DEFAULT_TEMPLATE.md`: the default message template for all merge styles if they don't have their own templates.
 - `.gitea/default_merge_message/MERGE_TEMPLATE.md`
 - `.gitea/default_merge_message/REBASE_TEMPLATE.md`
 - `.gitea/default_merge_message/REBASE-MERGE_TEMPLATE.md`
 - `.gitea/default_merge_message/SQUASH_TEMPLATE.md`
 - `.gitea/default_merge_message/MANUALLY-MERGED_TEMPLATE.md`
 - `.gitea/default_merge_message/REBASE-UPDATE-ONLY_TEMPLATE.md`
 ## Variables
 You can use the following variables enclosed in `${}` inside these templates which follow [os.Expand](https://pkg.go.dev/os#Expand) syntax:
 - BaseRepoOwnerName: Base repository owner name of this pull request
 - BaseRepoName: Base repository name of this pull request
 - BaseBranch: Base repository target branch name of this pull request
 - HeadRepoOwnerName: Head repository owner name of this pull request
 - HeadRepoName: Head repository name of this pull request
 - HeadBranch: Head repository branch name of this pull request
 - PullRequestTitle: Pull request's title
 - PullRequestDescription: Pull request's description
 - PullRequestPosterName: Pull request's poster name
 - PullRequestIndex: Pull request's index number
 - PullRequestReference: Pull request's reference char with index number. i.e. #1, !2
 - ClosingIssues: return a string contains all issues which will be closed by this pull request i.e. `close #1, close #2`
 - ReviewedOn: Which pull request this commit belongs to. For example `Reviewed-on: https://gitea.com/foo/bar/pulls/1`
 - ReviewedBy: Who approved the pull request before the merge. For example `Reviewed-by: Jane Doe <[email protected]>`
 ## Rebase
 When rebasing without a merge commit, `REBASE_TEMPLATE.md` modifies the message of the last commit. The following additional variables are available in this template:
 - CommitTitle: Commit's title
 - CommitBody: Commits's body text
@@ -0,0 +1,76 @@
 ---
 date: "2018-06-01T19:00:00+02:00"
 slug: "pull-request"
 sidebar_position: 13
 aliases:
  - /en-us/pull-request
 ---
 # Pull Request
 A Pull Request (PR) is a way to propose changes to a repository.
 It is a request to merge one branch into another, accompanied by a description of the changes that were made.
 Pull Requests are commonly used as a way for contributors to propose changes and for maintainers to review and merge those changes.
 ## Creating a pull request
 To create a PR, you'll need to follow these steps:
 1. **Fork the repository** - If you don't have permission to make changes to the repository directly, you'll need to fork the repository to your own account.
 This creates a copy of the repository that you can make changes to.
 2. **Create a branch (optional)** - Create a new branch on your forked repository that contains the changes you want to propose.
 Give the branch a descriptive name that indicates what the changes are for.
 3. **Make your changes** - Make the changes you want, commit, and push them to your forked repository.
 4. **Create the PR** - Go to the original repository and go to the "Pull Requests" tab. Click the "New Pull Request" button and select your new branch as the source branch.
 Enter a descriptive title and description for your Pull Request and click "Create Pull Request".
 ## Reviewing a pull request
 When a PR is created, it triggers a review process. The maintainers of the repository are notified of the PR and can review the changes that were made.
 They can leave comments, request changes, or approve the changes.
 If the maintainers request changes, you'll need to make those changes in your branch and push the changes to your forked repository.
 The PR will be updated automatically with the new changes.
 If the maintainers approve the changes, they can merge the PR into the repository.
 ## Closing a pull request
 If you decide that you no longer want to merge a PR, you can close it.
 To close a PR, go to the open PR and click the "Close Pull Request" button. This will close the PR without merging it.
 ## "Work In Progress" pull requests
 Marking a pull request as being a work in progress will prevent that pull request from being accidentally merged.
 To mark a pull request as being a work in progress, you must prefix its title by `WIP:` or `[WIP]` (case insensitive).
 Those values are configurable in your `app.ini` file:
 ```ini
 [repository.pull-request]
 WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP]
 ```
 The first value of the list will be used in helpers.
 ## Default pull request title
 When opening a new pull request, Gitea pre-fills the title field. The source of that title is controlled by the `DEFAULT_TITLE_SOURCE` setting in `app.ini`:
 ```ini
 [repository.pull-request]
 DEFAULT_TITLE_SOURCE = first-commit
 ```
 Two modes are available:
 - **`first-commit`** (default): The title is taken from the summary line of the oldest commit in the branch. This applies regardless of how many commits are included in the PR.
 - **`auto`**: When the PR contains a single commit, its summary line is used as the title (same as `first-commit` for one commit). When the PR contains multiple commits, Gitea converts the branch name into a human-readable sentence: dashes, underscores, and `camelCase` word boundaries are replaced with spaces, and the first letter is capitalized.
 Example: branch name `fix-user-login-flow` with multiple commits produces the title `Fix user login flow` under `auto`, but would use the oldest commit's message under `first-commit`.
 ## Pull Request Templates
 You can find more information about pull request templates at the page [Issue and Pull Request templates](issue-pull-request-templates.md).
@@ -0,0 +1,9 @@
 {
  "label": "Packages",
  "position": 40,
  "link": {
    "type": "generated-index",
    "slug": "/usage/packages",
    "description": "Managing packages and package registries"
  }
 }
@@ -36,23 +36,24 @@ pacman-key --lsign-key {key id}
 Now add the registry configuration to `/etc/pacman.conf`.
 ```conf
-[{owner}.gitea.example.com]
+[{repository}]
 SigLevel = Required
-Server = https://gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
+Server = https://gitea.example.com/api/packages/{owner}/arch/$repo/$arch
 ```
 | Placeholder    | Description |
 | -------------- | ----------- |
 | `owner`        | The owner of the packages. |
 | `repository`   | The repository to use. |
 | `architecture` | The architecture to use. |
 Consult the owners package overview to see what `repository` and `architecture` is available.
 If the registry is private, provide credentials in the url. You can use a password or a [personal access token](development/api-usage.md#authentication):
 ```
-Server = https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
+[{repository}]
 SigLevel = Required
 Server = https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/arch/$repo/$arch
 ```
 ## Publish a package
@@ -18,7 +18,7 @@ To register the package registry you need to configure a new Conan remote:
 ```shell
 conan remote add {remote} https://gitea.example.com/api/packages/{owner}/conan
-conan user --remote {remote} --password {password} {username}
+conan remote login {remote} {username} --password {password}
 ```
 | Parameter  | Description |
@@ -32,7 +32,7 @@ For example:
 ```shell
 conan remote add gitea https://gitea.example.com/api/packages/testuser/conan
-conan user --remote gitea --password password123 testuser
+conan remote login gitea testuser --password password123
 ```
 ## Publish a package
@@ -29,7 +29,7 @@ npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{t
 | ------------ | ----------- |
 | `scope`      | The scope of the packages. |
 | `owner`      | The owner of the package. |
-| `token`      | Your [personal access token](development/api-usage.md#authentication). |
+| `token`      | Your [personal access token](development/api-usage.md#authentication). With `package` permissions. |
 For example:
@@ -35,6 +35,7 @@ The following package managers are currently supported:
 | [RPM](usage/packages/rpm.md) | - | `yum`, `dnf`, `zypper` |
 | [RubyGems](usage/packages/rubygems.md) | Ruby | `gem`, `Bundler` |
 | [Swift](usage/packages/swift.md) | Swift | `swift` |
 | [Terraform](usage/packages/terraform.md) | - | `terraform` |
 | [Vagrant](usage/packages/vagrant.md) | - | `vagrant` |
 **The following paragraphs only apply if Packages are not globally disabled!**
@@ -56,6 +57,8 @@ and shows a link to the repository on the package site (as well as a link to the
 | **read** access    | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only |
 | **write** access   | owner only | org members with admin or write access to the org |
 Please note, that your respective package manager needs to have a [personal access token](development/api-usage.md#authentication) with the permissions `package` set to either Read or Read & Write to download and publish packages respectively.
 N.B.: These access restrictions are [subject to change](https://github.com/go-gitea/gitea/issues/19270), where more finegrained control will be added via a dedicated organization team permission.
 ## Create or upload a package
@@ -0,0 +1,99 @@
 ---
 date: "2026-03-04T00:00:00+00:00"
 slug: "terraform"
 sidebar_position: 118
 ---
 # Terraform State Registry
 Publish terraform states to sync it between multiple users or CI system.
 ## Requirements
 To work with the Terraform State registry, you need to use [Terraform](https://www.terraform.io/) or [OpenTofu](https://opentofu.org/).
 ## Configuring the package registry
 To use the Gitea Terraform State registry, you need to configure the `http` backend in your Terraform configuration.
 ```hcl
 terraform {
  backend "http" {
    address        = "https://gitea.example.com/api/packages/{owner}/terraform/state/{name}"
    lock_address   = "https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/lock"
    unlock_address = "https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/lock"
    lock_method    = "POST"
    unlock_method  = "DELETE"
    username       = "{username}"
    password       = "{password_or_token}"
  }
 }
 ```
 | Placeholder | Description |
 | ----------- | ----------- |
 | `owner`     | The owner of the state (user or organization). |
 | `name`      | The name of the state. |
 | `username`  | Your Gitea username. |
 | `password`  | Your Gitea password or [personal access token](development/api-usage.md#authentication). |
 If you are using 2FA or OAuth use a [personal access token](development/api-usage.md#authentication) instead of the password.
 ## Initialize the backend
 After configuring the backend, you can initialize it with:
 ```shell
 terraform init
 ```
 Terraform will prompt you to migrate your state if you already have one locally.
 ## State Locking
 Gitea supports state locking to prevent concurrent modifications. The `lock_address` and `unlock_address` should point to the `/lock` sub-route of your state URL.
 - **Locking**: Performed via a `POST` request to `{address}/lock`.
 - **Unlocking**: Performed via a `DELETE` request to `{address}/lock`.
 Terraform handles these requests automatically when configured as shown above.
 ## Encrypted state
 The state registry supports [encrypted state](https://opentofu.org/docs/language/state/encryption/).
 ## State Versions and Management
 Gitea keeps track of your Terraform state versions. You can use the API to retrieve or delete specific versions.
 ### Fetch state
 To fetch the latest version of a state:
 ```shell
 curl --user {username}:{password_or_token} \
     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}
 ```
 To fetch a specific version by its serial number:
 ```shell
 curl --user {username}:{password_or_token} \
     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/versions/{serial}
 ```
 ### Delete state
 To delete the entire state and all its versions:
 ```shell
 curl --user {username}:{password_or_token} -X DELETE \
     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}
 ```
 To delete a specific version by its serial number:
 ```shell
 curl --user {username}:{password_or_token} -X DELETE \
     https://gitea.example.com/api/packages/{owner}/terraform/state/{name}/versions/{serial}
 ```
@@ -0,0 +1,9 @@
 {
  "label": "Repository",
  "position": 10,
  "link": {
    "type": "generated-index",
    "slug": "/usage/repository",
    "description": "Repository management, Git operations, and content features"
  }
 }
@@ -1,12 +1,10 @@
 ---
 date: "2023-08-14T00:00:00+00:00"
 slug: "blame"
 sidebar_position: 13
 aliases:
  - /en-us/blame
-
+  - /blame
 ---
 # Blame File View
@@ -1,11 +1,10 @@
 ---
 date: "2021-02-02"
 slug: "clone-filters"
 sidebar_position: 25
 aliases:
  - /en-us/clone-filters
-
+  - /clone-filters
 ---
 # Clone filters (partial clone)
@@ -0,0 +1,84 @@
 ---
 date: "2023-05-24T16:00:00+00:00"
 slug: "code-owners"
 sidebar_position: 30
 aliases:
  - /en-us/code-owners
  - /code-owners
 ---
 # Code Owners
 Gitea maintains code owner files. It looks for it in the following locations in this order:
 - `./CODEOWNERS`
 - `./docs/CODEOWNERS`
 - `./.gitea/CODEOWNERS`
 And stops at the first found file.
 File format: `<regexp rule> <@user or @org/team> [@user or @org/team]...`
 Regexp specified in golang Regex format.
 Regexp can start with `!` for negative rules - match all files except specified.
 Example file:
 ```bash
 .*\\.go @user1 @user2 # This is comment
 # Comment too
 # You can assigning code owning for users or teams
 frontend/src/.*\\.js @org1/team1 @org1/team2 @user3
 # You can use negative pattern
 !frontend/src/.* @org1/team3 @user5
 # You can use power of go regexp
 docs/(aws|google|azure)/[^/]*\\.(md|txt) @user8 @org1/team4
 !/assets/.*\\.(bin|exe|msi) @user9
 ```
 Code owners listed in this file will automatically be requested to review pull requests
 that modify files matching at least one corresponding rule.
 ### Escaping
 You can escape characters `#`, ` ` (space) and `\` with `\`, like:
 ```
 dir/with\#hashtag @user1
 path\ with\ space @user2
 path/with\\backslash @user3
 ```
 Some character (`.+*?()|[]{}^$\`) should be escaped with `\\` inside regexp, like:
 ```
 path/\\.with\\.dots
 path/with\\+plus
 ```
 ### Branch Protection Rules
 When setting up branch protection rules, you may choose to enforce code owner approval of
 modified files. This will block a PR from being merged until at least one code owner
 has given approval for every applicable rule listed in the `CODEOWNERS` file.
 For example, say you have the following `CODEOWNERS` file:
 ```bash
 .*\\.go @Bob
 .*\\.md @Sally @Chris
 migrations/.* @Alice
 ```
 This means that:
 - If your PR modifies any `.go` files, it will require approval from Bob.
 - If your PR modifies any `.md` files, it will require approval from _either_ Sally _or_ Chris.
 - If your PR modifies any file in the `migrations` directory, it will require approval from Alice.
 These rules are composable. So, for example, if your PR modifies some `.go` files, as well as
 some `.md` files, this means it will require approval from Bob, in addition to approval from
 one of either Sally or Chris.
@@ -1,11 +1,10 @@
 ---
 date: "2022-12-01T00:00:00+00:00"
 slug: "incoming-email"
-sidebar_position: 13
+sidebar_position: 130
 aliases:
  - /en-us/incoming-email
-
+  - /incoming-email
 ---
 # Incoming Email
@@ -0,0 +1,155 @@
 ---
 date: "2025-04-05T00:00:00+08:00"
 slug: "markdown"
 aliases:
  - /markdown
 sidebar_position: 4
 ---
 # Markdown
 Gitea uses MarkDown structured text in many places, you can recognise it by the `.md` file extension.
 Markdown is plain text format for writing structured documents, allowing one to write
 "plain" text files that nonetheless have _"fancy"_ **formatting**, while still keeping the plain-text version readable.
 Unfortunately, due to historical implementation differences, many subtle dialects exist.
 To avoid adding to the confusion, Gitea tries to follow "[GitHub Flavoured Markdown (GFM)](https://help.github.com/articles/github-flavored-markdown/)" as close as possible.
 "GFM" is an extension on top of the rigorously-specified [CommonMark](https://commonmark.org/) standard.
 CommonMark flavours are used by most major web platforms (e.g. Reddit, Stack Overflow, Discourse)
 and git forges (GitHub, GitLab and our very own Gitea), thus you shouldn't run into any surprises with Gitea.
 For a quick introduction to the syntax and features of GitHub Flavoured Markdown, see the GitHub documentation:
 - [Basic formatting](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
 - [Advanced formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting)
 For a deeper history about CommonMark, its spec, and its reason for existence, see [CommonMark.org](https://commonmark.org/).
 ## Rendering options
 Some Gitea's markdown rendering behaviors can be fine-tuned by global config options, see the `[markdown]` config section in the `app.example.ini`
 ## Link path resolving
 When rendering links for `<a href>`, `<img src>` and `<video src>`, Gitea resolves the link paths in the rendering context.
 - If the link is an absolute path with scheme, the link is kept as-is.
 - If the link is an URL path, it is resolved with the base path of current rendering context.
  - In a comment-like context (issues, pull-requests, commit message), the base path is current repository's home link: `/owner-name/repo-name`.
  - In a repository file context (markdown files in the repository), the base path is current git ref path.
 ### Special link tokens
 To make users easier to resolve a link to the Gitea instance's root path, Gitea has a special `/:root` path syntax.
 This will always resolve to Gitea's ROOT_URL.
 Gitea also supports GitHub's `?raw=1` query parameter.
 A request to `/owner-name/repo-name/src/branch/main/file?raw=1` will be redirected to
 `/owner-name/repo-name/raw/branch/main/file`. This makes it possible to target raw contents from relative links
 (normally, the `src/` section of the path is provided automatically by Gitea and cannot be overriden).
 ### Link handling examples
 For example, when rendering a markdown file in `/owner-name/repo-name/src/branch/main/dir`:
  1) Absolute with scheme: Link `https://example.org` will be rendered as-is.
  2) Relative from current file: Link `sub/file`is resolved to `/owner-name/repo-name/src/branch/main/dir/sub/file`
  3) Relative from repo root: Link `/sub/file` (note leading slash) is resolved to `/owner-name/repo-name/src/branch/main/sub/file`
  4) Raw media: If the link is used as `src` of an image or video, then it is resolved to `/owner-name/repo-name/raw/...`
  5) Raw relative: `sub/file?raw=1` will resolve to `/owner-name/repo-name/src/branch/main/dir/sub/file?raw=1`,
    which will redirect to `/owner-name/repo-name/raw/branch/main/dir/sub/file`.
  6) explicit root: Link `/:root/any-path` is always resolved to `$ROOT_URL/any-path` without any further processing.
 ## Issue and pull-request reference
 Using issue/pull-request numbers in a list:
 ```
 * #123
 * #456
 ```
 It will be rendered with issue titles to:
 ```
 * the issue title (#123)
 * the other issue title (#456)
 ```
 ## Theme-based image display
 Gitea supports the GitHub-like theme-based image display. Supported syntax:
 * Use Markdown image
 ```
 ![My-Light](my-light.png#gh-light-mode-only)![My-Dark](my-dark.png#gh-dark-mode-only)
 ```
 * Use `<img>` HTML tag
 ```
 <img src="my-light.png#gh-light-mode-only" height="120" width="120"/>
 <img src="my-dark.png#gh-dark-mode-only" height="120" width="120"/>
 ```
 * Use `<picture>` with `<source media>` (only works for themes with "auto" color preference)
 ```
 <picture>
  <source media="(prefers-color-scheme: dark)" srcset="my-dark.png">
  <source media="(prefers-color-scheme: light)" srcset="my-light.png">
  <img src="my-light.png">
 </picture>
 ```
 ## Math expressions
 Gitea supports GitHub-like math expression formatting.
 ### Inline expression
  - ``` $\alpha$ ```: quoted by single-dollar `$`
  - ``` $$\alpha$$ ```: quoted by double-dollar `$$`
  - ``` $`\alpha`$ ```: quoted by dollar with backquotes, the backquotes could repeat like normal code blocks.
 ### Block expression
 Using `$$`:
 ````
 $$
 \alpha
 $$
 ````
 Using code-block with language:
 ````
 ```math
 \alpha
 ```
 ````
 ## Frontmatter
 Gitea supports frontmatter and Table of Contents (TOC) rendering. By default, frontmatter rendering is enabled, and TOC rendering is disabled.
 ### Enabling TOC rendering
 To enable TOC rendering for a markdown file, add `include_toc: true` to its frontmatter section.
 ### Disabling frontmatter
 To disable frontmatter rendering for a markdown file, add `gitea: none` to its frontmatter section.
 ### Example
 ```yaml
 ---
 include_toc: true
 gitea: none
 ---
 ```
 Then, when you preview this markdown file in Gitea, the frontmatter section will not be rendered, and a Table of Contents will be generated at the top of the content.
@@ -0,0 +1,55 @@
 ---
 date: "2024-09-11T09:30:00+08:00"
 slug: "migration"
 sidebar_position: 40
 aliases:
  - /migration
 ---
 # Migration
 You can migrate repositories from other Git services to your Gitea instance.
 ## How to migrate from Gogs/GitHub/GitLab to Gitea
 To migrate from Gogs to Gitea:
 - [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
 To migrate from GitHub to Gitea, you can use Gitea's built-in migration form.
 In order to migrate items such as issues, pull requests, etc. you will need to input at least your username.
 [Example (requires login)](https://demo.gitea.com/repo/migrate)
 To migrate from GitLab to Gitea, you can use this non-affiliated tool:
 https://github.com/loganinak/MigrateGitlabToGogs
 ## How to migrate from AWS CodeCommit to Gitea
 - To use the AWS CodeCommit API, Gitea requires an access key ID and a secret access key. For security reasons, we recommend creating a new user with the minimum necessary permissions and generating an access key ID and secret access key for the migration. The minimum permissions required for this user are as follows:
  ```
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "codecommit:GetRepository",
          "codecommit:GitPull",
          "codecommit:ListPullRequests",
          "codecommit:GetPullRequest",
          "codecommit:GetCommentsForPullRequest"
        ],
        "Resource": [
          "arn:aws:codecommit:<region>:<account>:<Repo-to-Migrate>
      }
    ]
  }
  ```
  - If you do not need to migrate pull requests, you can remove the `ListPullRequests`, `GetPullRequest`, and `GetCommentsForPullRequest` actions.
  - For instructions on how to create an IAM user and assign permissions, you can refer to this [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
 - To clone this repository, Gitea requires HTTPS Git credentials. You can create HTTPS Git credentials according to this [AWS documentation](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-gc.html).
@@ -0,0 +1,18 @@
 ---
 date: "2023-03-02T21:00:00+05:00"
 slug: "profile-readme"
 sidebar_position: 42
 aliases:
  - /profile-readme
 ---
 # Profile READMEs
 To display a Markdown file in your Gitea user or organization profile page, create a repository named `.profile` and add a new file named `README.md` to it.
 Gitea will automatically display the contents of the file on your profile, in a new "Overview" above your repositories.
 Making the `.profile` repository private will hide the Profile README.
 Example of user with `.profile/README.md`:
 ![profile readme screenshot](/images/usage/profile-readme.png)
@@ -5,6 +5,7 @@ sidebar_position: 15
 aliases:
  - /en-us/push-to-create
  - /en-us/push-options
  - /push
 ---
 # Push
@@ -44,7 +45,7 @@ Push to create is a feature that allows you to push to a repository that does no
 ### Enabling Push To Create
-In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet](../administration/config-cheat-sheet.md#repository-repository).
+In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#repository-repository).
 ### Using Push To Create
@@ -4,9 +4,10 @@ slug: "repo-mirror"
 sidebar_position: 45
 aliases:
  - /en-us/repo-mirror
  - /repo-mirror
 ---
-# Repository Mirror
+# Mirror Repository
 Repository mirroring allows for the mirroring of repositories to and from external sources. You can use it to mirror branches, tags, and commits between repositories.
@@ -0,0 +1,97 @@
 ---
 date: "2019-11-28:00:00+02:00"
 slug: "template-repositories"
 sidebar_position: 44
 aliases:
  - /en-us/template-repositories
  - /template-repositories
 ---
 # Template Repository
 Since Gitea `1.11`, you can create template repositories.
 When creating a repo based on a template, you can copy most of its content, and even auto-inject variables into it.
 By default, variables will not be expanded in any file.
 Only files contained in a pattern inside the `.gitea/template` file will be checked for if they contain variables.
 When creating the template, all files are included except for this `.gitea/template` file.
 Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax.
 It closely resembles a traditional `.gitignore`, however there may be slight differences.
 ## Example `.gitea/template` file
 All paths are relative to the base of the repository
 ```gitignore
 # Expand all .go files, anywhere in the repository
 **.go
 # All text files in the text directory
 text/*.txt
 # A specific file
 a/b/c/d.json
 # Batch files in both upper or lower case can be matched
 **.[bB][aA][tT]
 ```
 Gitea also supports to use sections to exclude some files:
 ```
 [expand]
 *.md
 [exclude]
 *.log
 ```
 ## Variable Expansion
 In any file matched by the above globs, the variables below will be expanded.
 Matching filenames and paths can also be expanded, and are conservatively sanitized to support cross-platform filesystems.
 You can use variables by prefixing them with `$` or surrounding them with `${}`, so both `$VAR` and `${VAR}` insert the value of `VAR` at this location.
 To escape an expansion, use `$$`, such as `$$VAR` or `$${VAR}`.
 These are the variables Gitea currently recognizes:
 | Variable             | Expands To                                          | Transformable |
 | -------------------- | --------------------------------------------------- | ------------- |
 | YEAR                 | The year of generating the repository (i.e. `2024`) | ✘             |
 | MONTH                | The month of generating the repository (i.e. `03`)  | ✘             |
 | MONTH_ENGLISH        | The month but in English (i.e. `March`)             | ✓             |
 | DAY                  | The day of generating the repository (i.e. `02`)    | ✘             |
 | REPO_NAME            | The name of the generated repository                | ✓             |
 | TEMPLATE_NAME        | The name of the template repository                 | ✓             |
 | REPO_DESCRIPTION     | The description of the generated repository         | ✘             |
 | TEMPLATE_DESCRIPTION | The description of the template repository          | ✘             |
 | REPO_OWNER           | The owner of the generated repository               | ✓             |
 | TEMPLATE_OWNER       | The owner of the template repository                | ✓             |
 | REPO_LINK            | The URL to the generated repository                 | ✘             |
 | TEMPLATE_LINK        | The URL to the template repository                  | ✘             |
 | REPO_HTTPS_URL       | The HTTP(S) clone link for the generated repository | ✘             |
 | TEMPLATE_HTTPS_URL   | The HTTP(S) clone link for the template repository  | ✘             |
 | REPO_SSH_URL         | The SSH clone link for the generated repository     | ✘             |
 | TEMPLATE_SSH_URL     | The SSH clone link for the template repository      | ✘             |
 ## Transformers :robot:
 Since Gitea `1.12.0`, variables marked as transformable in the table above also have alternative versions where the given transformer has been applied.
 Transformed variables can be called by appending the transformer name to the variable name.
 For example, to get `REPO_NAME` in `PASCAL`-case, you should use the variable `${REPO_NAME_PASCAL}`.
 The following transformers are available (assuming `go-sdk` is the input):
 | Transformer | Effect |
 | ----------- | ------ |
 | SNAKE       | go_sdk |
 | KEBAB       | go-sdk |
 | CAMEL       | goSdk  |
 | PASCAL      | GoSdk  |
 | LOWER       | go-sdk |
 | UPPER       | GO-SDK |
 | TITLE       | Go-Sdk |
@@ -0,0 +1,732 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "webhooks"
 sidebar_position: 30
 aliases:
  - /en-us/webhooks
  - /webhooks
 ---
 # Webhooks
 Gitea can send outbound webhooks for repository activity. Repository webhooks are
 configured at `/:username/:reponame/settings/hooks` by a repository admin.
 Equivalent webhook pages also exist for organizations, users, and system
 administration.
 Webhook configuration is available at four scopes:
 - `Repository webhooks`: Trigger only for activity in one repository.
 - `Organization webhooks`: Trigger for activity in repositories owned by that
  organization.
 - `User webhooks`: Trigger for activity in repositories owned by that user.
 - `System webhooks`: Trigger for all eligible activity on the instance.
 Gitea also supports admin-defined `default webhooks`. These are not an extra
 delivery scope. Instead, they are copied into newly created repositories and
 then behave like ordinary repository webhooks.
 Gitea supports these outgoing webhook integrations:
 - Gitea
 - Gogs
 - Slack
 - Discord
 - Dingtalk
 - Telegram
 - Microsoft Teams
 - Feishu
 - Matrix
 - Wechatwork
 - Packagist
 The `Gitea` and `Gogs` webhook types send generic webhook payloads. The chat and
 service integrations listed above transform the same internal event into a
 service-specific request body.
 ## Configuration
 This section covers the webhook settings you choose when creating or editing a
 webhook.
 ### Configuring a webhook
 When creating a webhook, the main options are:
 - `Target URL`: The endpoint that receives the delivery.
 - `HTTP Method`: Usually `POST` for generic webhooks.
 - `POST Content Type`: `application/json` or
  `application/x-www-form-urlencoded` for generic webhooks.
 - `Secret`: Used to sign the raw request body with HMAC.
 - `Authorization Header`: Optional custom `Authorization` header to send with
  each request.
 - `Branch Filter`: Optional glob filter for branch and tag related events.
 - `Trigger On`: `Push Events`, `All Events`, or a custom event selection.
 - `Active`: Whether the webhook is enabled.
 :::note
 Older examples may still show a `secret` field inside the JSON payload. Current
 Gitea versions do not send the webhook secret in the payload body. Always verify
 the request by checking the signature headers instead.
 :::
 ### Branch filters
 The branch filter uses glob syntax compatible with
 [`github.com/gobwas/glob`](https://pkg.go.dev/github.com/gobwas/glob#Compile).
 - Empty, `*`, or `**` matches everything.
 - A plain branch name such as `main` matches that branch.
 - Full refs such as `refs/tags/v*` are also supported.
 - Brace expressions such as `{main,release/*}` are supported.
 - The filter only applies to events that carry a git ref, such as `create`,
  `delete`, and `push`.
 - Events without a ref, such as issues or releases, ignore the branch filter.
 Examples:
 - `main`
 - `{main,feature/*}`
 - `{refs/heads/feature/*,refs/tags/release/*}`
 ### Authorization header
 Gitea can be configured to send a custom
 [Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)
 with each webhook delivery. This is independent from the webhook secret:
 - Use the secret to verify integrity with HMAC.
 - Use the `Authorization` header when the receiving endpoint requires
  application-level authentication.
 ## Delivery
 This section describes how Gitea sends webhook deliveries and how receivers can
 identify and verify them.
 ### Delivery behavior
 - Webhooks are delivered asynchronously over HTTP.
 - Generic `Gitea` and `Gogs` webhooks support `POST` and `GET`; `POST` is the
  normal choice.
 - For `POST` requests, the payload can be sent either as JSON
  (`application/json`) or as a form field named `payload`
  (`application/x-www-form-urlencoded`).
 - Provider-specific integrations may use the HTTP method and body format
  required by that provider.
 ### Delivery headers
 Every delivery includes a unique delivery ID and event headers. For
 GitHub-compatible integrations, Gitea also sends the corresponding GitHub and
 Gogs header names.
 | Header | Description |
 | --- | --- |
 | `X-Gitea-Delivery` | Unique delivery UUID for this attempt. |
 | `X-Gitea-Event` | Normalized event name, such as `push`, `issues`, or `pull_request`. |
 | `X-Gitea-Event-Type` | More specific event type, such as `issue_assign` or `pull_request_review_comment`. |
 | `X-Gitea-Signature` | Hex-encoded HMAC-SHA256 of the raw request body, without a prefix. |
 | `X-Gitea-Hook-Installation-Target-Type` | Where the webhook is defined: typically `repository`, `organization`, `user`, or `system`. Default webhooks are copied into repositories before delivery, so they are typically delivered as `repository`. |
 | `X-Gogs-Delivery`, `X-Gogs-Event`, `X-Gogs-Event-Type`, `X-Gogs-Signature` | Compatibility headers with the same values as the Gitea variants. |
 | `X-GitHub-Delivery`, `X-GitHub-Event`, `X-GitHub-Event-Type` | GitHub-style compatibility headers. |
 | `X-GitHub-Hook-Installation-Target-Type` | GitHub-style compatibility header for the webhook scope. |
 | `X-Hub-Signature` | GitHub-compatible HMAC-SHA1 header in the form `sha1=<digest>`. |
 | `X-Hub-Signature-256` | GitHub-compatible HMAC-SHA256 header in the form `sha256=<digest>`. |
 If no secret is configured, the signature headers are still present, but their
 digest values are empty.
 #### `Event` versus `Event-Type`
 Some Gitea webhook subscriptions are grouped together under one normalized event
 name. For example, an issue assignment delivery uses the issue event group:
 ```http
 X-Gitea-Event: issues
 X-Gitea-Event-Type: issue_assign
 X-GitHub-Event: issues
 X-GitHub-Event-Type: issue_assign
 ```
 Use `X-Gitea-Event-Type` when you need the exact trigger that fired the webhook.
 #### Validating deliveries
 Gitea signs the raw request body with your webhook secret. To validate a
 delivery:
 1. Read the request body exactly as it was received.
 2. Compute the HMAC-SHA256 digest with your webhook secret.
 3. Compare the result with `X-Gitea-Signature` or with the GitHub-compatible
   `X-Hub-Signature-256` header.
 4. Use a constant-time comparison when possible.
 Important details:
 - `X-Gitea-Signature` contains only the lowercase hexadecimal SHA-256 digest.
 - `X-Hub-Signature-256` contains the same digest with a `sha256=` prefix.
 - `X-Hub-Signature` is also sent for compatibility and uses SHA-1.
 - The body must be verified before JSON parsing or any other modification.
 ##### PHP example
 The following example verifies a generic `Gitea` webhook sent as
 `application/json`.
 ```php
 <?php
 $secret = '123';
 if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit('Only POST is allowed');
 }
 $payload = file_get_contents('php://input');
 $signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
 if ($payload === false || $signature === '') {
    http_response_code(400);
    exit('Missing payload or signature');
 }
 $expected = hash_hmac('sha256', $payload, $secret);
 if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
 }
 $event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
 $eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
 $data = json_decode($payload, true);
 if (!is_array($data)) {
    http_response_code(400);
    exit('Invalid JSON payload');
 }
 http_response_code(204);
 ```
 ## Events
 This section follows the same event-by-event style used by GitHub's webhook
 documentation: each event describes when it occurs and what the top-level
 payload contains.
 The event groups match the webhook settings UI: `Repository Events`,
 `Issue Events`, `Pull Request Events`, and `Workflow Events`.
 ### Repository Events
 - `create`, `delete`, `fork`, `push`, `wiki`, `repository`, `release`, `package`, `status`
 #### `create`
 This event occurs when a branch or tag is created.
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `sha` | `string` | **Required.** The object ID of the created reference. |
 | `ref` | `string` | **Required.** The created branch or tag name. |
 | `ref_type` | `string` | **Required.** The reference type, such as `branch` or `tag`. |
 | `repository` | `object` | **Required.** The repository where the reference was created. |
 | `sender` | `object` | **Required.** The user who created the reference. |
 #### `delete`
 This event occurs when a branch or tag is deleted.
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `ref` | `string` | **Required.** The deleted branch or tag name. |
 | `ref_type` | `string` | **Required.** The reference type, such as `branch` or `tag`. |
 | `pusher_type` | `string` | **Required.** The actor type that deleted the ref. Current Gitea payloads use `user`. |
 | `repository` | `object` | **Required.** The repository where the reference was deleted. |
 | `sender` | `object` | **Required.** The user who deleted the reference. |
 #### `fork`
 This event occurs when a repository is forked.
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `forkee` | `object` | **Required.** The newly created fork repository. |
 | `repository` | `object` | **Required.** The original repository that was forked. |
 | `sender` | `object` | **Required.** The user who created the fork. |
 #### `push`
 This event occurs when commits are pushed to a branch or tag.
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `ref` | `string` | **Required.** The full pushed ref, such as `refs/heads/main`. |
 | `before` | `string` | **Required.** The commit SHA before the push. |
 | `after` | `string` | **Required.** The commit SHA after the push. |
 | `compare_url` | `string` | **Required.** URL to compare `before` and `after`. |
 | `commits` | `array` | **Required.** Commits included in the push. |
 | `total_commits` | `integer` | **Required.** Number of commits in the push. |
 | `head_commit` | `object` | The most recent commit in the push. |
 | `repository` | `object` | **Required.** The repository that received the push. |
 | `pusher` | `object` | **Required.** The user who performed the push. |
 | `sender` | `object` | **Required.** The user who triggered the webhook. |
 #### `wiki`
 This event occurs when a wiki page is created, edited, or deleted.
 **Action type:** `created`, `edited`, `deleted`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The wiki page action. |
 | `repository` | `object` | **Required.** The repository that owns the wiki. |
 | `sender` | `object` | **Required.** The user who changed the wiki page. |
 | `page` | `string` | **Required.** The wiki page name. |
 | `comment` | `string` | The wiki commit message or comment. |
 #### `repository`
 This event occurs when a repository is created or deleted.
 **Action type:** `created`, `deleted`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The repository action. |
 | `repository` | `object` | **Required.** The repository that was created or deleted. |
 | `organization` | `object` | Present when the repository belongs to an organization. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 #### `release`
 This event occurs when a release is published, updated, or deleted.
 **Action type:** `published`, `updated`, `deleted`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The release action. |
 | `release` | `object` | **Required.** The release that was acted on. |
 | `repository` | `object` | **Required.** The repository containing the release. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 #### `package`
 This event occurs when a package is created or deleted.
 **Action type:** `created`, `deleted`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The package action. |
 | `repository` | `object` | The repository associated with the package, when applicable. |
 | `package` | `object` | **Required.** The package that was acted on. |
 | `organization` | `object` | Present when the package owner is an organization. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 #### `status`
 This event occurs when a commit status is created or updated through the API.
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `commit` | `object` | The commit associated with the status. |
 | `context` | `string` | **Required.** The status context, such as `ci/build`. |
 | `created_at` | `string` | **Required.** The time the status was created. |
 | `description` | `string` | Status description text. |
 | `id` | `integer` | **Required.** The status identifier. |
 | `repository` | `object` | **Required.** The repository containing the commit. |
 | `sender` | `object` | **Required.** The user who created the status. |
 | `sha` | `string` | **Required.** The commit SHA. |
 | `state` | `string` | **Required.** The state, such as `pending`, `success`, `error`, or `failure`. |
 | `target_url` | `string` | Target URL associated with the status. |
 | `updated_at` | `string` | The time the status was last updated. |
 Unlike most other payloads, this event does not use an `action` field. The
 state transition is represented by `state`.
 ### Issue Events
 - `issues`, `issue_assign`, `issue_label`, `issue_milestone`, `issue_comment`
 #### `issues`
 This event occurs when an issue is opened, closed, reopened, edited, or deleted.
 **Action type:** `opened`, `closed`, `reopened`, `edited`, `deleted`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The issue action. |
 | `number` | `integer` | **Required.** The issue number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `issue` | `object` | **Required.** The issue that was acted on. |
 | `repository` | `object` | **Required.** The repository containing the issue. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 | `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
 #### `issue_assign`
 This event occurs when an issue is assigned or unassigned.
 **Action type:** `assigned`, `unassigned`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The assignment action. |
 | `number` | `integer` | **Required.** The issue number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `issue` | `object` | **Required.** The issue that was acted on. |
 | `repository` | `object` | **Required.** The repository containing the issue. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 | `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
 #### `issue_label`
 This event occurs when issue labels are updated or cleared.
 **Action type:** `label_updated`, `label_cleared`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The label update action. |
 | `number` | `integer` | **Required.** The issue number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `issue` | `object` | **Required.** The issue that was acted on. |
 | `repository` | `object` | **Required.** The repository containing the issue. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 | `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
 #### `issue_milestone`
 This event occurs when an issue is milestoned or demilestoned.
 **Action type:** `milestoned`, `demilestoned`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The milestone action. |
 | `number` | `integer` | **Required.** The issue number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `issue` | `object` | **Required.** The issue that was acted on. |
 | `repository` | `object` | **Required.** The repository containing the issue. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 | `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
 #### `issue_comment`
 This event occurs when a comment on an issue is created, edited, or deleted.
 **Action type:** `created`, `edited`, `deleted`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The comment action. |
 | `issue` | `object` | **Required.** The issue that the comment belongs to. |
 | `pull_request` | `object` | Present only when the comment is on a pull request timeline. |
 | `comment` | `object` | **Required.** The comment that was created, edited, or deleted. |
 | `changes` | `object` | Optional. Previous comment body when the action is `edited`. |
 | `repository` | `object` | **Required.** The repository containing the issue. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 | `is_pull` | `boolean` | **Required.** Whether the comment is on a pull request timeline. |
 ### Pull Request Events
 - `pull_request`, `pull_request_assign`, `pull_request_label`, `pull_request_milestone`, `pull_request_comment`, `pull_request_review`, `pull_request_review_approved`, `pull_request_review_rejected`, `pull_request_review_comment`, `pull_request_sync`, `pull_request_review_request`
 #### `pull_request`
 This event occurs when a pull request is opened, closed, reopened, edited, or deleted.
 **Action type:** `opened`, `closed`, `reopened`, `edited`, `deleted`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The pull request action. |
 | `number` | `integer` | **Required.** The pull request number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `pull_request` | `object` | **Required.** The pull request that was acted on. |
 | `requested_reviewer` | `object` | Present for review request events. |
 | `repository` | `object` | **Required.** The repository containing the pull request. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 | `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
 | `review` | `object` | Present for pull request review events. |
 #### `pull_request_assign`
 This event occurs when a pull request is assigned or unassigned.
 **Action type:** `assigned`, `unassigned`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The assignment action. |
 | `number` | `integer` | **Required.** The pull request number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `pull_request` | `object` | **Required.** The pull request that was acted on. |
 | `requested_reviewer` | `object` | Present for review request events. |
 | `repository` | `object` | **Required.** The repository containing the pull request. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 | `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
 | `review` | `object` | Present for pull request review events. |
 #### `pull_request_label`
 This event occurs when pull request labels are updated or cleared.
 **Action type:** `label_updated`, `label_cleared`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The label update action. |
 | `number` | `integer` | **Required.** The pull request number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `pull_request` | `object` | **Required.** The pull request that was acted on. |
 | `requested_reviewer` | `object` | Present for review request events. |
 | `repository` | `object` | **Required.** The repository containing the pull request. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 | `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
 | `review` | `object` | Present for pull request review events. |
 #### `pull_request_milestone`
 This event occurs when a pull request is milestoned or demilestoned.
 **Action type:** `milestoned`, `demilestoned`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The milestone action. |
 | `number` | `integer` | **Required.** The pull request number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `pull_request` | `object` | **Required.** The pull request that was acted on. |
 | `requested_reviewer` | `object` | Present for review request events. |
 | `repository` | `object` | **Required.** The repository containing the pull request. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 | `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
 | `review` | `object` | Present for pull request review events. |
 #### `pull_request_comment`
 This event occurs when a timeline comment on a pull request is created, edited, or deleted.
 **Action type:** `created`, `edited`, `deleted`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The comment action. |
 | `issue` | `object` | **Required.** The related issue record for the pull request. |
 | `pull_request` | `object` | **Required.** The pull request the timeline comment belongs to. |
 | `comment` | `object` | **Required.** The comment that was created, edited, or deleted. |
 | `changes` | `object` | Optional. Previous comment body when the action is `edited`. |
 | `repository` | `object` | **Required.** The repository containing the pull request. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 | `is_pull` | `boolean` | **Required.** Always `true` for this event. |
 #### `pull_request_review`
 This is a subscription-only umbrella event in the webhook settings UI.
 It does not have its own delivery payload. When selected, Gitea delivers the
 more specific events `pull_request_review_approved`,
 `pull_request_review_rejected`, and `pull_request_review_comment`.
 #### `pull_request_review_approved`
 This event occurs when a pull request review is submitted with approval.
 **Action type:** `reviewed`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** Always `reviewed`. |
 | `number` | `integer` | **Required.** The pull request number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `pull_request` | `object` | **Required.** The pull request that was reviewed. |
 | `requested_reviewer` | `object` | Present for review request events. |
 | `repository` | `object` | **Required.** The repository containing the pull request. |
 | `sender` | `object` | **Required.** The user who submitted the review. |
 | `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
 | `review` | `object` | **Required.** The review payload. For this event, `review.type` is `approved`. |
 #### `pull_request_review_rejected`
 This event occurs when a pull request review is submitted with a rejection or a
 request for changes.
 **Action type:** `reviewed`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** Always `reviewed`. |
 | `number` | `integer` | **Required.** The pull request number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `pull_request` | `object` | **Required.** The pull request that was reviewed. |
 | `requested_reviewer` | `object` | Present for review request events. |
 | `repository` | `object` | **Required.** The repository containing the pull request. |
 | `sender` | `object` | **Required.** The user who submitted the review. |
 | `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
 | `review` | `object` | **Required.** The review payload. For this event, `review.type` is `rejected`. |
 #### `pull_request_review_comment`
 This event occurs when a pull request review is submitted as a comment.
 **Action type:** `reviewed`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** Always `reviewed`. |
 | `number` | `integer` | **Required.** The pull request number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `pull_request` | `object` | **Required.** The pull request that was reviewed. |
 | `requested_reviewer` | `object` | Present for review request events. |
 | `repository` | `object` | **Required.** The repository containing the pull request. |
 | `sender` | `object` | **Required.** The user who submitted the review. |
 | `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
 | `review` | `object` | **Required.** The review payload. For this event, `review.type` is `comment`. |
 #### `pull_request_sync`
 This event occurs when a pull request is synchronized after new commits are pushed.
 **Action type:** `synchronized`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** Always `synchronized`. |
 | `number` | `integer` | **Required.** The pull request number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `pull_request` | `object` | **Required.** The pull request that was synchronized. |
 | `requested_reviewer` | `object` | Present for review request events. |
 | `repository` | `object` | **Required.** The repository containing the pull request. |
 | `sender` | `object` | **Required.** The user who performed the synchronization. |
 | `commit_id` | `string` | The commit SHA associated with the synchronization event, if applicable. |
 | `review` | `object` | Present for pull request review events. |
 #### `pull_request_review_request`
 This event occurs when a reviewer is requested or a review request is removed.
 **Action type:** `review_requested`, `review_request_removed`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The review request action. |
 | `number` | `integer` | **Required.** The pull request number. |
 | `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
 | `pull_request` | `object` | **Required.** The pull request that was acted on. |
 | `requested_reviewer` | `object` | The reviewer that was requested or removed. |
 | `repository` | `object` | **Required.** The repository containing the pull request. |
 | `sender` | `object` | **Required.** The user who performed the action. |
 | `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
 | `review` | `object` | Present for pull request review events. |
 ### Workflow Events
 - `workflow_run`, `workflow_job`
 #### `workflow_run`
 This event occurs when a Gitea Actions workflow run changes status.
 **Action type:** `queued`, `waiting`, `in_progress`, `completed`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The workflow run status transition. |
 | `workflow` | `object` | **Required.** The workflow definition. |
 | `workflow_run` | `object` | **Required.** The workflow run that was acted on. |
 | `pull_request` | `object` | Present when the workflow run is associated with a pull request. |
 | `organization` | `object` | Present when the repository owner is an organization. |
 | `repository` | `object` | **Required.** The repository containing the workflow. |
 | `sender` | `object` | **Required.** The user who triggered the workflow run update. |
 #### `workflow_job`
 This event occurs when a Gitea Actions workflow job changes status.
 **Action type:** `queued`, `waiting`, `in_progress`, `completed`
 ##### Payload parameters
 | Name | Type | Description |
 | --- | --- | --- |
 | `action` | `string` | **Required.** The workflow job status transition. |
 | `workflow_job` | `object` | **Required.** The workflow job that was acted on. |
 | `pull_request` | `object` | Present when the workflow job is associated with a pull request. |
 | `organization` | `object` | Present when the repository owner is an organization. |
 | `repository` | `object` | **Required.** The repository containing the workflow job. |
 | `sender` | `object` | **Required.** The user who triggered the workflow job update. |
 ## Testing, recent deliveries, and replay
 Each webhook page includes:
 - `Test Delivery`, which sends a synthetic `push` event for the repository.
 - `Recent Deliveries`, which shows request and response details.
 - `Redelivery`, which replays an earlier webhook delivery.
 If the repository has no commits yet, the test delivery uses a generated fake
 commit so the webhook can still be exercised.
 ## Administration notes
 Administrators can further control webhook delivery with instance settings such
 as host allow lists, delivery timeouts, and cleanup policies. See the
 [Webhook section of the configuration cheat sheet](../../administration/config-cheat-sheet.md#webhook-webhook).
@@ -0,0 +1,9 @@
 {
  "label": "User Setting",
  "position": 200,
  "link": {
    "type": "generated-index",
    "slug": "/usage/user-setting",
    "description": "Configuring user preferences and settings"
  }
 }
@@ -1,9 +1,9 @@
 ---
 date: "2023-08-22T14:21:00+08:00"
 slug: "multi-factor-authentication"
 weight: 15
-
+aliases:
  - /multi-factor-authentication
 ---
 # Multi-factor Authentication (MFA)
@@ -1,463 +0,0 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 import {themes as prismThemes} from 'prism-react-renderer';
 const lightCodeTheme = prismThemes.github;
 const darkCodeTheme = prismThemes.dracula;
 // order usage directory by type first
 function sortItemsByCategory(items) {
  // type with "category" (directory) first
  const sortedItems = items.sort(function(a, b) {
    return a.type.localeCompare(b.type);
  })
  return sortedItems;
 }
 const renderApiSSR = process.env.API_SSR !== 'false';
 const apiConfig = [
  'redocusaurus',
  {
    // Plugin Options for loading OpenAPI files
    specs: renderApiSSR ? [
      {
        spec: 'static/swagger-latest.json',
        route: '/api/next/',
      },
      {
        route: '/api/1.22/',
        spec: 'static/swagger-22.json',
      },
      {
        route: '/api/1.21/',
        spec: 'static/swagger-21.json',
      },
      {
        route: '/api/1.20/',
        spec: 'static/swagger-20.json',
      },
      {
        route: '/api/1.19/',
        spec: 'static/swagger-19.json',
      },
      {
        route: '/api/',
        spec: 'static/swagger-22.json',
      }
    ]: [],
    // Theme Options for modifying how redoc renders them
    theme: {
      // Change with your site colors
      primaryColor: '#1890ff',
    },
  },
 ]
 const pageConfig = renderApiSSR ? {
  exclude: [
    'api/**',
  ],
 }: {}
 const globalVariables = {
  current: {
    'goVersion': '1.22',
    'minGoVersion': '1.22',
    'minNodeVersion': '18',
    'version': 'main-nightly',
    'sourceVersion': 'main',
    'sourceBranch': 'main',
    'dockerVersion': 'nightly',
    'displayVersion': '1.24-dev'
  },
  '1.23': {
    'goVersion': '1.23',
    'minGoVersion': '1.22',
    'minNodeVersion': '18',
    'version': '1.23.0-rc0',
    'sourceVersion': 'v1.23.0-rc0',
    'sourceBranch': 'release/v1.23',
    'dockerVersion': '1.23.0-rc0',
    'displayVersion': '1.23.0-rc0'
  },
  '1.22': {
    'goVersion': '1.22',
    'minGoVersion': '1.22',
    'minNodeVersion': '18',
    'version': '1.22.6',
    'sourceVersion': 'v1.22.6',
    'sourceBranch': 'release/v1.22',
    'dockerVersion': '1.22.6',
    'displayVersion': '1.22.6'
  },
  '1.21': {
    'goVersion': '1.21',
    'minGoVersion': '1.21',
    'minNodeVersion': '18',
    'version': '1.21.11',
    'sourceVersion': 'v1.21.11',
    'sourceBranch': 'release/v1.21',
    'dockerVersion': '1.21.11',
    'displayVersion': '1.21.11'
  },
  '1.20': {
    'goVersion': '1.20',
    'minGoVersion': '1.20',
    'minNodeVersion': '16',
    'version': '1.20.6',
    'sourceVersion': 'v1.20.6',
    'sourceBranch': 'release/v1.20',
    'dockerVersion': '1.20.6',
    'displayVersion': '1.20.6'
  },
  '1.19': {
    'goVersion': '1.20',
    'minGoVersion': '1.19',
    'minNodeVersion': '14',
    'version': '1.19.4',
    'sourceVersion': 'v1.19.4',
    'sourceBranch': 'release/v1.19',
    'dockerVersion': '1.19.4',
    'displayVersion': '1.19.4'
  }
 }
 const versions = {
  current: {
    label: globalVariables['current'].displayVersion, // path is kept as next for dev (so users can always find "nightly" docs)
    banner: 'unreleased',
  },
  '1.23': {
    label: globalVariables['1.23'].displayVersion,
  },
  '1.22': {
    label: globalVariables['1.22'].displayVersion,
  },
  '1.21': {
    label: globalVariables['1.21'].displayVersion,
  },
  '1.20': {
    label: globalVariables['1.20'].displayVersion,
  },
  '1.19': {
    label: globalVariables['1.19'].displayVersion,
  }
 }
 /** @type {import('@docusaurus/types').Config} */
 const config = {
  title: 'Gitea Documentation',
  tagline: 'Git with a cup of tea',
  url: 'https://docs.gitea.com',
  baseUrl: '/',
  onBrokenLinks: 'warn',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.png',
  plugins: [
    [
      'docusaurus-plugin-plausible',
      {
        domain: 'docs.gitea.com',
      },
    ],
    // for runner documentations
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'runner',
        path: 'runner',
        routeBasePath: 'runner',
        //sidebarPath: './runner/sidebars.js',
        versions: {
          current: {
            label: 'main',
            banner: 'unreleased',
          },
          "0.2.11": {
            path: '0.2.11',
            label: '0.2.11',
          }
        },
        lastVersion: '0.2.11',
        editUrl: ({versionDocsDirPath, docPath, locale, version, permalink}) => {
          return `https://gitea.com/gitea/docs/src/branch/main/${version === 'current' ? 'runner': `runner_versioned_docs/version-${version}`}/${docPath}`;
        },
        async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
          const {item} = args;
          // Use the provided data to generate a custom sidebar slice
          const sidebarItems = await defaultSidebarItemsGenerator(args);
          if (item.dirName !== 'usage') {
            return sidebarItems;
          } else {
            return sortItemsByCategory(sidebarItems);
          }
        },
      },
    ],
  ],
  i18n: {
    defaultLocale: 'en-us',
    locales: ['en-us', 'zh-cn'/*,'fr-fr', 'zh-tw'*/], // temporarily disable other locales
    localeConfigs: {
      'en-us': {
        label: 'English',
      },
      'zh-cn': {
        label: '中文',
      },
    },
  },
  presets: [
    [
      '@docusaurus/preset-classic',
      //'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          routeBasePath: '/', // Serve the docs at the site's root
          editUrl: ({versionDocsDirPath, docPath, locale, version, permalink}) => {
            // Special case for awesome page
            if (docPath.includes('awesome.md')) {
              return `https://gitea.com/gitea/awesome-gitea/src/branch/main/README.md`
            }
            if (locale === 'en-us') {
              return `https://gitea.com/gitea/docs/src/branch/main/${version === 'current' ? 'docs': `versioned_docs/version-${version}`}/${docPath}`;
            }
            return `https://gitea.com/gitea/docs/src/branch/main/i18n/${locale}/docusaurus-plugin-content-docs/${version === 'current' ? 'current': `version-${version}`}/${docPath}`;
          },
          versions: versions,
          lastVersion: '1.22',
          async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
            const {item} = args;
            // Use the provided data to generate a custom sidebar slice
            const sidebarItems = await defaultSidebarItemsGenerator(args);
            if (item.dirName !== 'usage') {
              return sidebarItems;
            } else {
              return sortItemsByCategory(sidebarItems);
            }
          },
        },
        blog: false,
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
        pages: pageConfig,
        gtag: {
          trackingID: 'G-KHM0KYT506'
        },
      }),
    ],
    apiConfig,
  ],
  markdown: {
    preprocessor: ({filePath, fileContent}) => {
      var key = '';
      var found = false;
      for (key in globalVariables) {
        let folderName = (key == 'current' ? 'current' : `version-${key}`);
        if (filePath.includes(`/${folderName}/`)) {
          found = true;
          break;
        }
      }
      if (key == '' || !found) {
        key = 'current';
      }
      let content = fileContent;
      for (const variable in globalVariables[key]) {
        content = content.replaceAll('@'+variable+'@', globalVariables[key][variable]);
      }
      return content
    },
  },
  themes: [
    [
      "@easyops-cn/docusaurus-search-local",
      {
        hashed: false,
        language: ["en", "zh"],
        highlightSearchTermsOnTargetPage: true,
        explicitSearchResultPath: true,
        indexBlog: false,
        docsRouteBasePath: "/"
      }
    ]
  ],
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      metadata: [
        {name: 'keywords', content: 'gitea, git, devops, actions, packages, documentation, self-hosted, open-source, version control, gitlab, github'}
      ],
      colorMode: {
        defaultMode: 'light',
        disableSwitch: false,
        respectPrefersColorScheme: true,
      },
      announcementBar: {
        id: 'announcementBar-4', // Increment on change
        content: `<a href="https://about.gitea.com/products/cloud">Try &nbsp; Gitea Cloud &nbsp;  ☁️  &nbsp; for 30 days <span aria-hidden="true">&rarr;</span> Accelerate your Development & Deploys!</a>`,
      },
      navbar: {
        title: 'Gitea',
        logo: {
          alt: 'Gitea Logo',
          src: 'img/gitea.svg',
          href: 'https://about.gitea.com/',
          target: '_self',
        },
        items: [
          {
            type: 'doc',
            docId: 'index',
            position: 'left',
            label: 'Docs',
          },
          {
            to: '/api/1.22/',
            label: 'API',
            position: 'left',
            activeBaseRegex: 'api/(1.19|1.20|1.21|1.22|1.23|next)/',
          },
          {
            to: '/runner/0.2.11/',
            label: 'Runner',
            position: 'left',
            activeBaseRegex: 'runner/(0.2.11|next)/',
          },
          {
            position: 'left',
            label: 'Enterprise',
            href: 'https://docs.gitea.com/enterprise',
            className: 'internal-href',
            target: '_self',
          },
          {
            type: 'search',
            position: 'right',
          },
          {
            type: 'localeDropdown',
            position: 'right',
          },
          {
            type: 'docsVersionDropdown',
            position: 'right',
            dropdownActiveClassDisabled: true,
          },
          {
            type: 'custom-Dropdown',
            label: 'API Version',
            position: 'right',
            items: [
              {to: '/api/next/', label: '1.24-dev' },
              {to: '/api/1.23/', label: '1.23.0-rc0' },
              {to: '/api/1.22/', label: '1.22.6' },
              {to: '/api/1.21/', label: '1.21.11' },
              {to: '/api/1.20/', label: '1.20.6' },
              {to: '/api/1.19/', label: '1.19.4' },
            ],
            routerRgx: '\/api\/',
            classNames: 'api-dropdown',
          },
          {
            type: 'custom-Dropdown',
            label: 'Runner Version',
            position: 'right',
            items: [
              {to: '/runner/next/', label: 'development' },
              {to: '/runner/0.2.11/', label: '0.2.11' },
            ],
            routerRgx: '\/runner\/',
            classNames: 'runner-dropdown',
          },
          {
            to: 'help/support',
            position: 'right',
            label: 'Support',
            activeBaseRegex: 'help/support',
          },
          {
            href: 'https://gitea.com/user/login',
            label: 'Sign In',
            position: 'right',
            className: 'internal-href signin-button',
            target: '_self',
          },
        ],
      },
      footer: {
        style: 'dark',
        links: [
          {
            title: 'Community',
            items: [
              {
                label: 'Awesome Gitea',
                href: 'https://gitea.com/gitea/awesome-gitea',
              },
              {
                label: 'Stack Overflow',
                href: 'https://stackoverflow.com/questions/tagged/gitea',
              },
              {
                label: 'Discord',
                href: 'https://discord.gg/gitea',
              },
              {
                label: 'Matrix',
                href: 'https://matrix.to/#/#gitea-space:matrix.org',
              },
              {
                label: 'Forum',
                href: 'https://forum.gitea.com/',
              },
              {
                label: 'Twitter',
                href: 'https://twitter.com/giteaio',
              },
              {
                label: 'Mastodon',
                href: 'https://social.gitea.io/@gitea',
              },
            ],
          },
          {
            title: 'Code',
            items: [
              {
                label: 'GitHub',
                href: 'https://github.com/go-gitea/gitea',
              },
              {
                label: 'Gitea',
                href: 'https://gitea.com/gitea',
              },
              {
                label: 'Tea CLI',
                href: 'https://gitea.com/gitea/tea',
              },
            ],
          },
        ],
      },
      prism: {
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
        additionalLanguages: ['ini','diff','json','http','docker','php'],
      },
    }),
 };
 module.exports = config;
@@ -0,0 +1,8 @@
 {
  "sidebar.docs.category.actions": {
    "message": "Actions"
  },
  "sidebar.docs.category.packages": {
    "message": "Packages"
  }
 }
@@ -0,0 +1,8 @@
 {
  "sidebar.docs.category.actions": {
    "message": "Actions"
  },
  "sidebar.docs.category.packages": {
    "message": "Packages"
  }
 }
@@ -1,8 +0,0 @@
 {
  "outdated.message": {
    "message": "当前中文文档翻译不是最新版，访问英文版本查看最新内容，或"
  },
  "outdated.help": {
    "message": "帮助我们翻译"
  }
 }
@@ -0,0 +1,9 @@
 {
  "label": "运维",
  "position": 30,
  "link": {
    "type": "generated-index",
    "slug": "/administration",
    "title": "运维"
  }
 }
@@ -5,7 +5,6 @@ sidebar_position: 110
 aliases:
  - /zh-cn/adding-legal-pages
 ---
 # 添加法律页面
@@ -14,10 +13,10 @@ aliases:
 ## 获取页面
-Gitea 源代码附带了示例页面，位于 `contrib/legal` 目录中。将它们复制到 `custom/public/assets/` 目录下。例如，如果要添加隐私政策：
+Gitea 源代码附带了示例页面，位于 `contrib/service/sample-page` 目录中。将它们复制到 `custom/public/assets/` 目录下。例如，如果要添加隐私政策：
 ```
-wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/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
 ```
 现在，你需要编辑该页面以满足你的需求。特别是，你必须更改电子邮件地址、网址以及与 "Your Gitea Instance" 相关的引用，以匹配你的情况。
@@ -10,7 +10,7 @@ aliases:
 ## 轻量级目录访问协议（Lightweight Directory Access Protocol，LDAP）
-通过BindDN的LDAP和简单认证方式LDAP共享以下字段:
+通过 BindDN 的 LDAP 和简单认证方式 LDAP 共享以下字段:
 - 认证名称 **(必选)**
@@ -27,48 +27,52 @@ aliases:
  - 例如: LDAP `389`/ LDAPs `636`
 - 安全协议 (可选)
-  - 连接LDAP服务器时是否使用TLS协议。
+
  - 连接 LDAP 服务器时是否使用 TLS 协议。
 - 管理员过滤规则 (可选)
-  - 一个LDAP过滤器，用于指定哪些用户应该被赋予管理员特权。如果用户帐户符合过滤器条件，则该用户将被授予管理员权限。
+
  - 一个 LDAP 过滤器，用于指定哪些用户应该被赋予管理员特权。如果用户帐户符合过滤器条件，则该用户将被授予管理员权限。
  - 示例:`(objectClass=adminAccount)`
-  - 适用于Microsoft Active Directory（AD）的示例:`memberOf=CN=admin-group,OU=example,DC=example,DC=org`
+  - 适用于 Microsoft Active Directory（AD）的示例:`memberOf=CN=admin-group,OU=example,DC=example,DC=org`
 - 用户名属性（可选）
-  - 用户LDAP记录中包含用户名称的属性。在第一次成功登录后，将使用指定的属性值作为新的Gitea账户用户名。若留空，则使用登录表单上提供的用户名。
+  - 用户 LDAP 记录中包含用户名称的属性。在第一次成功登录后，将使用指定的属性值作为新的 Gitea 账户用户名。若留空，则使用登录表单上提供的用户名。
-  - 当提供的登录名与多个属性匹配时，这一选项非常有用，但是只有一个特定属性应该用于Gitea账户名称，请参阅"用户过滤器"。
+  - 当提供的登录名与多个属性匹配时，这一选项非常有用，但是只有一个特定属性应该用于 Gitea 账户名称，请参阅"用户过滤器"。
  - 示例:uid
-  - 适用于Microsoft Active Directory（AD）的示例:`sAMAccountName`
+  - 适用于 Microsoft Active Directory（AD）的示例:`sAMAccountName`
 - 名字属性（可选）
-  - 用户LDAP记录中包含用户名字的属性。将用于填充他们的账户信息。
+  - 用户 LDAP 记录中包含用户名字的属性。将用于填充他们的账户信息。
  - 示例:givenName
 - 姓氏属性（可选）
-  - 用户LDAP记录中包含用户姓氏的属性。将用于填充他们的账户信息。
+
  - 用户 LDAP 记录中包含用户姓氏的属性。将用于填充他们的账户信息。
  - 示例:`sn`
 - 电子邮件属性 **(必选)**
-  - 用户LDAP记录中包含用户电子邮件地址的属性。将用于填充他们的账户信息。
+  - 用户 LDAP 记录中包含用户电子邮件地址的属性。将用于填充他们的账户信息。
  - 示例:`mail`
 ### LDAP(via BindDN)
 需要额外设置以下字段:
- 绑定DN (可选)
+- 绑定 DN (可选)
-  - 搜索用户时绑定到LDAP服务器的DN。这可以留空以执行匿名搜索。
+  - 搜索用户时绑定到 LDAP 服务器的 DN。这可以留空以执行匿名搜索。
  - 示例: `cn=Search,dc=mydomain,dc=com`
 - 绑定密码 (可选)
-  - 上述指定的Bind DN（绑定区别名）的密码，如果有的话。注意：该密码在服务器上使用SECRET_KEY进行加密存储。仍然建议确保Bind DN具有尽可能少的权限。
+  - 上述指定的 Bind DN（绑定区别名）的密码，如果有的话。注意：该密码在服务器上使用 SECRET_KEY 进行加密存储。仍然建议确保 Bind DN 具有尽可能少的权限。
 - 用户搜索基准 **(必选)**
-  - 这是用于搜索用户帐户的LDAP基础路径.
+  - 这是用于搜索用户帐户的 LDAP 基础路径.
  - 示例: `ou=Users,dc=mydomain,dc=com`
 - 用户过滤规则 **(必选)**
@@ -79,19 +83,19 @@ aliases:
  - 如需多次替换，应使用 `%[1]s`，例如在将提供的登录名与多个属性（如用户标识符、电子邮件甚至电话号码）进行匹配时。
  - 示例: `(&(objectClass=Person)(|(uid=%[1]s)(mail=%[1]s)(mobile=%[1]s)))`
 - 启用用户同步
-  - 这个选项启用了一个周期性任务，用于将Gitea用户与LDAP服务器进行同步。默认的同步周期是每24小时，
+  - 这个选项启用了一个周期性任务，用于将 Gitea 用户与 LDAP 服务器进行同步。默认的同步周期是每 24 小时，
-    但您可以在app.ini文件中进行更改。
+    但您可以在 app.ini 文件中进行更改。
    有关此部分的详细说明，请参阅[sample
    app.ini](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
-    的_cron.sync_external_users_ 部分的注释。前面提到的_User Search Base_和_User Filter_
+    的*cron.sync_external_users* 部分的注释。前面提到的*User Search Base*和*User Filter*
-    设置将限制哪些用户可以使用Gitea以及哪些用户将被同步。
+    设置将限制哪些用户可以使用 Gitea 以及哪些用户将被同步。
-    在初始运行任务时，将根据给定的设置创建所有与LDAP匹配的用户，因此在使用大型企业LDAP目录时需要小心。
+    在初始运行任务时，将根据给定的设置创建所有与 LDAP 匹配的用户，因此在使用大型企业 LDAP 目录时需要小心。
 ### LDAP(simple auth)
 需要额外设置以下字段:
- 用户DN **(必选)**
+- 用户 DN **(必选)**
  - 用作用户 DN 的模板。匹配参数 `%s` 将替换为登录表单中的登录名。
  - 示例: `cn=%s,ou=Users,dc=mydomain,dc=com`
@@ -108,11 +112,12 @@ aliases:
  - 示例: `(&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))`
  - 示例: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
-### 使用LDAP验证分组成员
+### 使用 LDAP 验证分组成员
 使用以下字段:
- 群组搜索基础DN(可选)
+- 群组搜索基础 DN(可选)
  - 组使用的 LDAP DN。
  - 示例: `ou=group,dc=mydomain,dc=com`
@@ -132,43 +137,46 @@ aliases:
 ## 可插拔式认证模块(Pluggable Authentication Module,PAM)
-这个过程启用了PAM（Pluggable Authentication Modules）认证。用户仍然可以通过用户管理手动添加到系统中。
+这个过程启用了 PAM（Pluggable Authentication Modules）认证。用户仍然可以通过用户管理手动添加到系统中。
-PAM提供了一种机制，通过对用户进行PAM认证来自动将其添加到当前数据库中。为了与普通的Linux密码一起使用，
+PAM 提供了一种机制，通过对用户进行 PAM 认证来自动将其添加到当前数据库中。为了与普通的 Linux 密码一起使用，
-运行Gitea的用户还必须具有对`/etc/shadow`的读取权限，以便在使用公钥登录时检查账户的有效性。
+运行 Gitea 的用户还必须具有对`/etc/shadow`的读取权限，以便在使用公钥登录时检查账户的有效性。
-**注意**:如果用户已将SSH公钥添加到Gitea中，使用这些密钥可能会绕过登录检查系统。因此，
+**注意**:如果用户已将 SSH 公钥添加到 Gitea 中，使用这些密钥可能会绕过登录检查系统。因此，
-如果您希望禁用使用PAM进行身份验证的用户，应该在Gitea中手动禁用该账户，使用内置的用户管理功能。
+如果您希望禁用使用 PAM 进行身份验证的用户，应该在 Gitea 中手动禁用该账户，使用内置的用户管理功能。
 1. 配置和安装准备.
-    - 建议您创建一个管理用户.
+   - 建议您创建一个管理用户.
-    - 建议取消自动注册.
+   - 建议取消自动注册.
 1. 一旦数据库已初始化完成，使用新创建的管理员账户登录.
 1. 导航至用户设置（右上角的图标），然后选择
-`Site Administration` -> `Authentication Sources`, 并选择
+   `Site Administration` -> `Authentication Sources`, 并选择
-`Add Authentication Source`.
+   `Add Authentication Source`.
 1. 填写字段如下:
-    - 认证类型:`PAM`。
+   - 认证类型:`PAM`。
-    - 名称:任何有效的值都可以，如果您愿意，可以使用"System Authentication"。
+   - 名称:任何有效的值都可以，如果您愿意，可以使用"System Authentication"。
-    - PAM服务名称:从/etc/pam.d/目录下选择适用于所需认证的正确文件[^1]。
+   - PAM 服务名称:从/etc/pam.d/目录下选择适用于所需认证的正确文件[^1]。
-    - PAM电子邮件域:用户认证时要附加的电子邮件后缀。例如，如果登录系统期望一个名为gituse的用户，
+   - PAM 电子邮件域:用户认证时要附加的电子邮件后缀。例如，如果登录系统期望一个名为 gituse 的用户，
-  并且将此字段设置为mail.com，那么Gitea在验证一个GIT实例的用户时将期望user emai字段为gituser@mail.com[^2]。
+     并且将此字段设置为 mail.com，那么 Gitea 在验证一个 GIT 实例的用户时将期望 user emai 字段为gituser@mail.com[^2]。
 **Note**: PAM 支持通过[build-time flags](installation/from-source.md#build)添加,
-而官方提供的二进制文件通常不会默认启用此功能。PAM需要确保系统上有必要的libpam动态库，并且编译器可以访问必要的PAM开发头文件。
+而官方提供的二进制文件通常不会默认启用此功能。PAM 需要确保系统上有必要的 libpam 动态库，并且编译器可以访问必要的 PAM 开发头文件。
-[^1]: 例如，在Debian "Bullseye"上使用标准Linux登录，可以使用`common-session-noninteractive`。这个值对于其他版本的Debian，
+[^1]:
-包括Ubuntu和Mint，可能也是有效的，请查阅您所使用发行版的文档以确认。
+    例如，在 Debian "Bullseye"上使用标准 Linux 登录，可以使用`common-session-noninteractive`。这个值对于其他版本的 Debian，
    包括 Ubuntu 和 Mint，可能也是有效的，请查阅您所使用发行版的文档以确认。
-[^2]: **PAM的必选项** 请注意:在上面的示例中，用户将作为`gituser`而不是`[email protected]`登录到Gitea的Web界面。
+[^2]: **PAM 的必选项** 请注意:在上面的示例中，用户将作为`gituser`而不是`[email protected]`登录到 Gitea 的 Web 界面。
 ## 简单邮件传输协议(Simple Mail Transfer Protocol,SMTP)
 此选项允许 Gitea 以 Gitea 用户身份登录 SMTP 主机。请设置以下字段:
 - 身份验证名称 **(必选)**
  - 分配给新授权方法的名称
 - SMTP 验证类型 **(必选)**
  - 用于连接 SMTP 主机的验证类型，plain 或 login
 - 主机名 **(必选)**
@@ -188,7 +196,7 @@ PAM提供了一种机制，通过对用户进行PAM认证来自动将其添加
  - 示例: `gitea.com,mydomain.com,mydomain2.com`
 - 强制使用 SMTPS
-  - 默认情况下将使用SMTPS连接到端口465.如果您希望将smtp用于其他端口，自行设置
+  - 默认情况下将使用 SMTPS 连接到端口 465.如果您希望将 smtp 用于其他端口，自行设置
  - 否则，如果服务器提供' STARTTLS '扩展名，则将使用此扩展名
 - 跳过 TLS 验证
  - 禁用 TLS 验证身份.
@@ -199,7 +207,7 @@ PAM提供了一种机制，通过对用户进行PAM认证来自动将其添加
 - 要使用 FreeIPA 凭据登录 Gitea，需要为 Gitea 创建一个绑定帐户。
  创建一个绑定帐户:
- 在FreeIPA服务器上创建一个gitea.ldif文件，并将`dc=example,dc=com`替换为您的`dn`，然后提供一个适当安全的密码。
+- 在 FreeIPA 服务器上创建一个 gitea.ldif 文件，并将`dc=example,dc=com`替换为您的`dn`，然后提供一个适当安全的密码。
  ```sh
  dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
@@ -212,33 +220,33 @@ PAM提供了一种机制，通过对用户进行PAM认证来自动将其添加
  nsIdleTimeout: 0
  ```
- 导入LDIF文件（如果需要，请将localhost更改为IPA服务器）。系统会提示您输入Directory Manager的密码。:
+- 导入 LDIF 文件（如果需要，请将 localhost 更改为 IPA 服务器）。系统会提示您输入 Directory Manager 的密码。:
  ```sh
  ldapmodify -h localhost -p 389 -x -D \
  "cn=Directory Manager" -W -f gitea.ldif
  ```
- 为`gitea_users`添加IPA组:
+- 为`gitea_users`添加 IPA 组:
  ```sh
  ipa group-add --desc="Gitea Users" gitea_users
  ```
- **提示**:对于IPA凭证错误，运行' kinit admin '并提供域管理帐户密码.
+- **提示**:对于 IPA 凭证错误，运行' kinit admin '并提供域管理帐户密码.
- 以管理员身份登录Gitea，点击Admin Panel下的`Authentication`。然后单击`Add New Source`并填写详细信息，更改所有适当的地方。
+- 以管理员身份登录 Gitea，点击 Admin Panel 下的`Authentication`。然后单击`Add New Source`并填写详细信息，更改所有适当的地方。
 ## SPNEGO with SSPI (Kerberos/NTLM, for Windows only)
-Gitea支持通过Windows内置的安全支持提供程序接口（Security Support Provider Interface，SSPI）实现SPNEGO单点登录认证（由RFC4559定义的方案），用于服务器的Web部分。SSPI仅在Windows环境中工作，即当服务器和客户端都在Windows操作系统上运行时。
+Gitea 支持通过 Windows 内置的安全支持提供程序接口（Security Support Provider Interface，SSPI）实现 SPNEGO 单点登录认证（由 RFC4559 定义的方案），用于服务器的 Web 部分。SSPI 仅在 Windows 环境中工作，即当服务器和客户端都在 Windows 操作系统上运行时。
-在激活SSPI单点登录认证（SSO）之前，您需要准备您的环境:
+在激活 SSPI 单点登录认证（SSO）之前，您需要准备您的环境:
- 在Active Directory中创建一个单独的用户账户，gitea.exe 进程将在该账户下运行（例如，在domain.local域下创建一个名为user的账户:
+- 在 Active Directory 中创建一个单独的用户账户，gitea.exe 进程将在该账户下运行（例如，在 domain.local 域下创建一个名为 user 的账户:
- 为运行gitea.exe的主机创建一个服务主体名称（Service Principal Name，SPN），其类别为HTTP:
+- 为运行 gitea.exe 的主机创建一个服务主体名称（Service Principal Name，SPN），其类别为 HTTP:
  - 以特权域用户（例如域管理员）的身份启动“命令提示符”或“PowerShell”。
-  - 运行下面的命令，将host.domain.local替换为Web应用程序将运行的服务器的完全限定域名（FQDN），将domain\user替换为在前一步中创建的账户名称:
+  - 运行下面的命令，将 host.domain.local 替换为 Web 应用程序将运行的服务器的完全限定域名（FQDN），将 domain\user 替换为在前一步中创建的账户名称:
  ```sh
  setspn -A HTTP/host.domain.local domain\user
@@ -247,22 +255,22 @@ Gitea支持通过Windows内置的安全支持提供程序接口（Security Suppo
 在遵循上述步骤之前，请确保您按照以下流程进行操作:
 1. 用之前创建的用户登录（如果已经登录，请先注销）。
-2. 确保在`custom/conf/app.ini`文件的`[server]`部分中，`ROOT_URL`设置为Web应用程序将运行的服务器的完全限定域名（FQDN），与之前创建服务主体名称时使用的一致（例如，`host.domain.local`）。
+2. 确保在`custom/conf/app.ini`文件的`[server]`部分中，`ROOT_URL`设置为 Web 应用程序将运行的服务器的完全限定域名（FQDN），与之前创建服务主体名称时使用的一致（例如，`host.domain.local`）。
-3. 启动Web服务器（运行 `gitea.exe web`）。
+3. 启动 Web 服务器（运行 `gitea.exe web`）。
-4. 在 `Site Administration -> Authentication Sources` 中添加一个 `SPNEGO with SSPI` 认证源，以启用SSPI认证。
+4. 在 `Site Administration -> Authentication Sources` 中添加一个 `SPNEGO with SSPI` 认证源，以启用 SSPI 认证。
 5. 在域中的客户端计算机上，使用任何域用户登录（与运行`gitea.exe`的服务器不同）。
-6. 如果您使用Chrome或Edge浏览器，请将Web应用程序的URL添加到“本地站点”（`Internet选项 -> 安全 -> 本地站点 -> 站点`）。
+6. 如果您使用 Chrome 或 Edge 浏览器，请将 Web 应用程序的 URL 添加到“本地站点”（`Internet选项 -> 安全 -> 本地站点 -> 站点`）。
-7. 启动Chrome或Edge浏览器，导航到Gitea的FQDN URL（例如，`http://host.domain.local:3000`）。
+7. 启动 Chrome 或 Edge 浏览器，导航到 Gitea 的 FQDN URL（例如，`http://host.domain.local:3000`）。
-8. 在控制面板中点击“Sign In”按钮，然后选择SSPI，将会自动使用当前登录到计算机的用户进行登录。
+8. 在控制面板中点击“Sign In”按钮，然后选择 SSPI，将会自动使用当前登录到计算机的用户进行登录。
 9. 如果无法正常工作，请确保:
-   - 您不是在运行`gitea.exe`的同一台服务器上运行Web浏览器。应该在与服务器不同的域加入计算机（客户端）上运行Web浏览器。如果客户端和服务器都在同一台计算机上运行，则NTLM将优先于Kerberos。
+   - 您不是在运行`gitea.exe`的同一台服务器上运行 Web 浏览器。应该在与服务器不同的域加入计算机（客户端）上运行 Web 浏览器。如果客户端和服务器都在同一台计算机上运行，则 NTLM 将优先于 Kerberos。
-   - 主机上只有一个`HTTP/...`的SPN。
+   - 主机上只有一个`HTTP/...`的 SPN。
-   - SPN中只包含主机名，不包含端口号。
+   - SPN 中只包含主机名，不包含端口号。
-   - 将Web应用程序的URL添加到"本地站点"。
+   - 将 Web 应用程序的 URL 添加到"本地站点"。
-   - 服务器和客户端的时钟差异不超过5分钟（取决于组策略）。
+   - 服务器和客户端的时钟差异不超过 5 分钟（取决于组策略）。
-   - 在Internet Explorer中启用了"集成Windows身份验证"（在"高级设置"下）。
+   - 在 Internet Explorer 中启用了"集成 Windows 身份验证"（在"高级设置"下）。
-遵循这些步骤，您应该能够成功启用和使用SSPI单点登录认证（SSO）。
+遵循这些步骤，您应该能够成功启用和使用 SSPI 单点登录认证（SSO）。
 ## 反向代理认证
@@ -279,7 +287,7 @@ ENABLE_REVERSE_PROXY_AUTHENTICATION = true
 如果设置了 `ENABLE_REVERSE_PROXY_FULL_NAME=true`，则用户的全名会从 `X-WEBAUTH-FULLNAME` 读取，这样在自动创建用户时将使用这个字段作为用户全名，你也可以通过修改 `REVERSE_PROXY_AUTHENTICATION_FULL_NAME` 来变更 HTTP 头。
-你也可以通过修改 `REVERSE_PROXY_TRUSTED_PROXIES` 来设置反向代理的IP地址范围，加强安全性，默认值是 `127.0.0.0/8,::1/128`。 通过 `REVERSE_PROXY_LIMIT`， 可以设置最多信任几级反向代理。
+你也可以通过修改 `REVERSE_PROXY_TRUSTED_PROXIES` 来设置反向代理的 IP 地址范围，加强安全性，默认值是 `127.0.0.0/8,::1/128`。 通过 `REVERSE_PROXY_LIMIT`， 可以设置最多信任几级反向代理。
 你可以通过以下配置为 API 启用此认证方法：
@@ -5,12 +5,11 @@ sidebar_position: 11
 aliases:
  - /zh-cn/backup-and-restore
 ---
 # 备份与恢复
-Gitea 已经实现了 `dump` 命令可以用来备份所有需要的文件到一个zip压缩文件。该压缩文件可以被用来进行数据恢复。
+Gitea 已经实现了 `dump` 命令可以用来备份所有需要的文件到一个 zip 压缩文件。该压缩文件可以被用来进行数据恢复。
 ## 备份一致性
@@ -20,11 +19,11 @@ Gitea 包括数据库、文件和 Git 仓库，当它被使用时所有这些都
 ## 备份命令 (`dump`)
-先转到git用户的权限: `su git`. 再Gitea目录运行 `./gitea dump`。一般会显示类似如下的输出：
+先转到 git 用户的权限: `su git`. 再 Gitea 目录运行 `./gitea dump`。一般会显示类似如下的输出：
 ```
 2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:09 Dumping local repositories.../home/git/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
@@ -33,12 +32,12 @@ Gitea 包括数据库、文件和 Git 仓库，当它被使用时所有这些都
 最后生成的 `gitea-dump-1482906742.zip` 文件将会包含如下内容：
-* `app.ini` - 如果原先存储在默认的 custom/ 目录之外，则是配置文件的可选副本
+- `app.ini` - 如果原先存储在默认的 custom/ 目录之外，则是配置文件的可选副本
-* `custom/` - 所有保存在 `custom/` 目录下的配置和自定义的文件。
+- `custom/` - 所有保存在 `custom/` 目录下的配置和自定义的文件。
-* `data/` - 数据目录（APP_DATA_PATH），如果使用文件会话，则不包括会话。该目录包括 `attachments`、`avatars`、`lfs`、`indexers`、如果使用 SQLite 则包括 SQLite 文件。
+- `data/` - 数据目录（APP_DATA_PATH），如果使用文件会话，则不包括会话。该目录包括 `attachments`、`avatars`、`lfs`、`indexers`、如果使用 SQLite 则包括 SQLite 文件。
-* `repos/` - 仓库目录的完整副本。
+- `repos/` - 仓库目录的完整副本。
-* `gitea-db.sql` - 数据库dump出来的 SQL。
+- `gitea-db.sql` - 数据库 dump 出来的 SQL。
-* `log/` - Logs文件，如果用作迁移不是必须的。
+- `log/` - Logs 文件，如果用作迁移不是必须的。
 中间备份文件将会在临时目录进行创建，如果您要重新指定临时目录，可以用 `--tempdir` 参数，或者用 `TMPDIR` 环境变量。
@@ -48,12 +47,12 @@ Gitea 包括数据库、文件和 Git 仓库，当它被使用时所有这些都
 ```sh
 # mysql
-mysqldump -u$USER -p$PASS --database $DATABASE > gitea-db.sql
+mysqldump -u$USER -p$PASS --databases $DATABASE > gitea-db.sql
 # postgres
 pg_dump -U $USER $DATABASE > gitea-db.sql
 ```
-### 使用Docker （`dump`）
+### 使用 Docker （`dump`）
 在使用 Docker 时，使用 `dump` 命令有一些注意事项。
@@ -81,7 +80,7 @@ cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/gitea-repositories/
+mv repos/* /var/lib/gitea/repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
 # mysql
@@ -115,7 +114,7 @@ cd gitea-dump-1610949662
 # 恢复 Gitea 数据
 mv data/* /data/gitea
 # 恢复仓库本身
-mv repos/* /data/git/gitea-repositories/
+mv repos/* /data/git/repositories/
 # 调整文件权限
 chown -R git:git /data
 # 重新生成 Git 钩子
@@ -139,7 +138,7 @@ mv data/conf/app.ini /etc/gitea/app.ini
 # 恢复 Gitea 数据
 mv data/* /var/lib/gitea
 # 恢复仓库本身
-mv repos/* /var/lib/gitea/git/gitea-repositories
+mv repos/* /var/lib/gitea/git/repositories
 # 调整文件权限
 chown -R git:git /etc/gitea/app.ini /var/lib/gitea
 # 重新生成 Git 钩子
@@ -5,7 +5,6 @@ sidebar_position: 20
 aliases:
  - /zh-cn/cmd-embedded
 ---
 # 嵌入资源提取工具
@@ -30,7 +29,7 @@ gitea embedded list [--include-vendored] [patterns...]
 - 列出所有模板文件，无论在哪个虚拟目录下：`**.tmpl`
 - 列出所有邮件模板文件：`templates/mail/**.tmpl`
-列出 `public/assets/img` 目录下的所有文件：`public/assets/img/**`
+  列出 `public/assets/img` 目录下的所有文件：`public/assets/img/**`
 不要忘记为模式使用引号，因为空格、`*` 和其他字符可能对命令行解释器有特殊含义。