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-15 14:23:44 +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
1877 changed files with 5229 additions and 121602 deletions
@@ -19,13 +19,13 @@ jobs:
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
-      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 24
          cache: pnpm
      - name: prepare awesome list
        run: |
-          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 prepare-awesome-v28
+          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
@@ -0,0 +1,48 @@
 # The status check context of this job is "checks / depends-upstream
 # (pull_request)", which the required status check `checks / *` of the protected
 # main branch matches, so a pull request waiting for gitea cannot be merged.
 # It is a workflow of its own so that a label change does not cancel the build
 # and the preview deployment of the `checks` workflow in test.yaml.
 #
 # The check script comes from the pull request, like the workflow file itself:
 # `pull_request` runs both from the head, so taking the script from the base
 # branch would not gain anything and would leave this workflow unable to run on
 # the pull request that adds it.
 name: checks
 on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - edited
      - labeled
      - unlabeled
 concurrency:
  group: depends-upstream-${{ github.event.pull_request.number }}
  cancel-in-progress: true
 jobs:
  depends-upstream:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - name: check the upstream dependencies
        env:
          PR_NUMBER: ${{ github.event.pull_request.number }}
          # optional, only lifts the rate limit of the unauthenticated github api
          GITHUB_COM_TOKEN: ${{ secrets.GITHUB_COM_TOKEN }}
        run: |
          set -euo pipefail
          # read the description and the labels from the api instead of the
          # event context, so nothing from a pull request body is expanded into
          # this script
          api="${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY"
          curl --silent --show-error --fail --output pull.json "$api/pulls/$PR_NUMBER"
          ./scripts/check-upstream-deps.sh pull.json
@@ -16,13 +16,13 @@ jobs:
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
-      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          node-version: 24
          cache: pnpm
      - name: prepare awesome list
        run: |
-          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22 prepare-awesome-v28
+          make prepare-awesome-latest prepare-awesome\#27 prepare-awesome\#26 prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
      - name: install dependencies
        run: pnpm install --frozen-lockfile
@@ -45,7 +45,7 @@ jobs:
          # pull requests from forks do not get the secrets, the build above is
          # then the only check and the preview is silently skipped
          if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
-            echo "::notice::no Cloudflare credentials available (pull request from a fork?), skipping the preview deployment"
+            echo "no Cloudflare credentials available, skipping the preview deployment"
            exit 0
          fi
@@ -0,0 +1,29 @@
 name: unlabel merged upstream dependencies
 on:
  schedule:
    - cron: '15 */6 * * *' # every 6 hours, quarter past
  workflow_dispatch:
 jobs:
  unlabel:
    if: github.repository == 'gitea/docs'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          persist-credentials: false
      - name: drop the label from the pull requests upstream caught up with
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
          GITHUB_COM_TOKEN: ${{ secrets.GITHUB_COM_TOKEN }}
        run: |
          set -euo pipefail
          if [ -z "${DEPLOY_TOKEN:-}" ]; then
            echo "secrets.DEPLOY_TOKEN is missing, cannot remove the label"
            exit 1
          fi
          export GITEA_API="${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY"
          ./scripts/unlabel-upstream-deps.sh
@@ -2,7 +2,7 @@ name: update api spec files
 on:
  schedule:
-    - cron: '0 3 * * 1' # every Monday at 03:00
+    - cron:  '0 */12 * * *' # every 12 hours on the hour
  workflow_dispatch:
 env:
@@ -6,6 +6,7 @@ sites/*/dist
 sites/*/.astro
 sites/*/.cache
 build/
 .docusaurus/
 # Misc
 .DS_Store
@@ -12,30 +12,20 @@ create_dir:
 clone_awesome: create_dir
 	git clone --branch=$(GITEA_AWESOME_BRANCH) $(GITEA_AWESOME_REMOTE) .tmp/upstream-awesome || true
 # the contributing guide moved to the gitea repository, the readme of
 # awesome-gitea still links to it with a relative path
 AWESOME_CONTRIBUTING_URL := https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md
 FIX_AWESOME_LINKS := sed 's|](contributing.md)|]($(AWESOME_CONTRIBUTING_URL))|'
 .PHONY: prepare-awesome-latest
 prepare-awesome-latest: clone_awesome
-	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > docs/awesome.md
+	cp .tmp/upstream-awesome/README.md docs/awesome.md
 .PHONY: prepare-awesome\#%
 prepare-awesome\#%:
-	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > versioned_docs/version-1.$*/awesome.md
+	cp .tmp/upstream-awesome/README.md  versioned_docs/version-1.$*/awesome.md
 # versions numbered without the 1. prefix, like 28
 .PHONY: prepare-awesome-v%
 prepare-awesome-v%:
 	$(FIX_AWESOME_LINKS) .tmp/upstream-awesome/README.md > versioned_docs/version-$*/awesome.md
 .PHONY: install
 install:
 	pnpm install
 .PHONY: prepare-docs
-prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27 prepare-awesome-v28
+prepare-docs: install prepare-awesome-latest prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24 prepare-awesome\#25 prepare-awesome\#26 prepare-awesome\#27
 .PHONY: build
 build:
@@ -7,9 +7,9 @@ The site covers three products, all served from this repository:
 | Product | Content | Versions | Languages |
 | --- | --- | --- | --- |
-| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 28, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
+| Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
-| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 28, 1.27 … 1.22 | English |
+| API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 1.27 … 1.22 | English |
-| Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 5 … 0 | English |
+| Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 3 … 0 | English |
 The enterprise documentation is built and deployed from its own repository and
 reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere
@@ -48,11 +48,43 @@ The order of the top level sidebar groups comes from `sidebars.js` (and
 `versioned_sidebars/` for released versions), the label and order of every other
 group from the `_category_.json` of its directory.
 ### Documenting an unreleased feature
 A page that describes a gitea change which is not merged yet must wait for it,
 otherwise the site documents something no release has. Say so in the description
 of the pull request, on a line of its own, and add the `depends-on-upstream`
 label:
 ```
 Depends on: gitea#35851
 ```
 The label is what blocks the merge: the `depends-upstream` check fails while it
 is set, unless every dependency is verified as merged, and `main` requires the
 `checks` contexts. The check reads the `Depends on:` lines (`gitea#<id>` or the
 full pull request url, several lines are allowed) to find out what to wait for,
 so the label needs at least one of them. A `gitea#<id>` mentioned anywhere else
 in the description is ignored.
 Without the label, a dependency that the check finds unmerged still fails it, so
 forgetting the label does not let an unreleased feature through.
 The `unlabel merged upstream dependencies` job runs every 6 hours, removes the
 label once every referenced pull request is merged and comments on the pull
 request, which reruns the check. `scripts/check-upstream-deps.sh` is the check
 itself and can be run locally against the json of a pull request.
 The check asks the github api whether a pull request is merged, and the runners
 share the 60 requests per hour it allows without authentication. The optional
 `GITHUB_COM_TOKEN` secret (a token without scopes is enough) raises that limit;
 without it an unverifiable dependency only fails the check when the label is
 set.
 ## Cutting a version
 ```shell
 make cut-version PRODUCT=docs VERSION=1.28
-make cut-version PRODUCT=runner VERSION=6
+make cut-version PRODUCT=runner VERSION=4
 ```
 This freezes the current tree, its translations and its sidebar. The label of
@@ -79,7 +111,7 @@ make update-api-docs-latest  # refresh only the documents of gitea main
 ```
 The documents of gitea main are refreshed automatically: the `update api spec
-files` workflow runs weekly and opens a pull request whenever gitea main
+files` workflow runs every 12 hours and opens a pull request whenever gitea main
 changed. Released versions are updated by hand when a new gitea version is
 documented.
@@ -88,8 +120,8 @@ documented.
 | Version | Content | URL |
 | --- | --- | --- |
 | develop | `runner-docs/` | `/runner/develop/` |
-| current series | `runner-docs_versioned_docs/version-5/` | `/runner/` |
+| current series | `runner-docs_versioned_docs/version-3/` | `/runner/` |
-| older series | `runner-docs_versioned_docs/version-4/` | `/runner/4/` |
+| older series | `runner-docs_versioned_docs/version-2/` | `/runner/2/` |
 A version directory covers a whole release series (`version-3` documents every
 `3.x` release), so a patch release only needs a content update, not a new
@@ -101,8 +133,7 @@ Its sidebar is written by hand: `runner-sidebars.js` for develop, and
 version.
 The pages under `reference/` are generated from the runner sources — the command
-line reference from `--help`, the example configuration from `config generate`
+line reference from `--help`, the example configuration from `generate-config`:
 (`generate-config` before 3.1):
 ```shell
 make update-runner-docs           # develop docs, from the main branch of gitea/runner
@@ -2,8 +2,8 @@
 # is copied into the build output by the publish workflow, so that it is not
 # uploaded to S3/CloudFront where it would be publicly readable at /_headers.
 #
-# The build emits a single content hashed asset directory shared by every
+# Unlike the docusaurus build, astro emits a single content hashed asset
-# language, so no per locale rules are needed.
+# directory shared by every language, so no per locale rules are needed.
 # Content hashed build output (js, css, fonts). The file name changes with the
 # content, so these can be cached forever.
@@ -1,7 +1,7 @@
 # Redirects for legacy URLs and routes the site no longer serves directly.
 # The api reference and the runner docs are separate products, published in
-# english only, so they have no localized copy.
+# english only. Docusaurus served an empty localized copy of them.
 /zh-cn/api/* /api/:splat 301
 /zh-tw/api/* /api/:splat 301
 /zh-cn/runner/* /runner/:splat 301
@@ -9,9 +9,9 @@
 # The version served at the root of a product is also reachable under its
 # number, which is what the release notes and old links use.
-/api/28/* /api/:splat 301
+/api/1.27/* /api/:splat 301
 /runner/3/* /runner/:splat 301
-/28/* /:splat 301
+/1.27/* /:splat 301
 # The local search plugin had a results page of its own, algolia docsearch is a
 # modal opened from any page.
@@ -1,153 +0,0 @@
 ---
 date: "2026-09-12T00:00:00+00:00"
 slug: "audit-logging"
 sidebar_position: 41
 aliases:
  - /en-us/audit-logging
 ---
 # Audit Logging
 Gitea can record security-relevant events as structured audit records: each
 event has an `action`, `actor`, `scope`, `origin`, `message` and a JSON
 `metadata` blob. Recording is **off by default** and does not change request
 behavior when it is disabled.
 This is separate from the application, router and access logs described in
 [Logging Configuration](logging-config.md). Those logs are for operations and
 debugging. The audit log is a durable trail of who changed what.
 ## Enable recording
 Set `[audit].RECORD_OUTPUT` to `database` in `app.ini` and restart Gitea:
 ```ini
 [audit]
 RECORD_OUTPUT = database
 RETENTION_DAYS = 30
 ```
 Invalid values of `RECORD_OUTPUT` fall back to `disabled`. See the
 [configuration cheat sheet](config-cheat-sheet.md#audit-audit) for every option.
 With Docker, the same settings can be applied as
 `GITEA__audit__RECORD_OUTPUT=database` and `GITEA__audit__RETENTION_DAYS=30`
 before Gitea writes them into `app.ini`.
 ## View events
 The Audit Log pages are always available and still list any events that were
 stored earlier. When recording is disabled, the site administration page also
 shows a warning.
 | Audience | Location | Events shown |
 | --- | --- | --- |
 | Site administrators | Site administration → Monitoring → Audit Log (`/-/admin/monitor/audit_logs`) | Every event |
 | Signed-in users | User settings → Audit Log (`/user/settings/audit_logs`) | Events scoped to that user |
 | Organization owners | Organization settings → Audit Log (`/<org>/settings/audit_logs`) | Events scoped to that organization |
 | Repository administrators | Repository settings → Audit Log (`/<owner>/<repo>/settings/audit_logs`) | Events scoped to that repository |
 Each listing can be filtered by actor (username), action and origin, and sorted
 by timestamp. The actor filter does not match the
 [system actors](#actors-and-origins). Action filters accept an exact action or
 a family prefix such as `user:impersonation` or `repository:webhook`.
 Site administrators can download the current filtered result as JSONL
 (newline-delimited JSON) from **Export JSONL**. The file name is
 `gitea-audit-log-<timestamp>.jsonl`.
 ## Event shape
 A recorded event contains:
 - **Action**: a stable, colon-separated identifier such as `repository:archive`
  or `user:accesstoken:add`.
 - **Actor**: the user who performed the action. Actions taken while impersonating
  a user record both the impersonator and the impersonated user.
 - **Actor credential**: when the request authenticated with a named credential,
  the event stores its kind and id, never the secret. Typical values:
  `access-token:<id>`, `oauth2-grant:<id>`, `gitea-actions:<task id>`,
  `deploy-key:<key id>`.
 - **Scope**: the affected unit — `user`, `organization`, `repository` or
  `system` (instance-wide).
 - **Origin**: how the action was initiated — `ui`, `api`, `cli` or `system`.
 - **Message**: a human-readable sentence rendered from a per-action template.
 - **Metadata**: extra fields that fill the message template (token name, new
  visibility, and so on). Secrets and token values are not stored.
 - **IP address**: the client address of the request, when one exists. Events
  triggered by a git push record the SSH client address for SSH pushes and
  `127.0.0.1` for HTTP pushes.
 - **Timestamp**: when the event was recorded.
 An exported JSONL line looks like:
 ```json
 {"action":"repository:archive","actor":{"type":"user","id":1,"name":"alice"},"scope":{"type":"repository","id":42,"name":"org/repo"},"message":"Archived repository org/repo.","time":"2026-09-12T11:00:00Z","ip_address":"203.0.113.10","origin":"ui"}
 ```
 The `system:startup` message is kept stable across Gitea versions so operators
 can parse it: `System started [Gitea {version}]`.
 ## Actors and origins
 Most web and API requests pick up the signed-in user automatically.
 Other entry points record a system actor:
 - `gitea:cli` for `gitea admin` commands and the `system:startup` and
  `system:shutdown` events
 - `gitea:auth-source` for authentication-source syncs and for users an
  authentication source creates or updates at sign-in
 - `gitea-actions` for Gitea Actions tasks
 - `gitea:deploy-key` for pushes with a deploy key
 - `(Cron)` for scheduled cron tasks
 - `Unknown` when no actor can be resolved
 Events of the `gitea:cli` actor use origin `cli`. Cron tasks, git hooks and
 other background work use origin `system`.
 ## What is recorded
 Events cover security-relevant changes, grouped by action family:
 - **User**: create and delete, admin, restricted and active status, name,
  password and password reset requests, visibility, emails, authentication
  source, 2FA, WebAuthn, OpenID, external logins, access tokens, OAuth2
  applications and grants, SSH/GPG/principal keys, secrets, webhooks,
  impersonation, failed two-factor authentication
 - **Organization**: create and delete, name, visibility, members, teams,
  OAuth2 applications, secrets, webhooks
 - **Repository**: create, fork, archive, delete, rename, visibility, transfer,
  mirrors, signing verification, collaborators and teams, default branch,
  branch and tag protection, deploy keys, webhooks, secrets
 - **Issues and pull requests**: create, delete, comments and merges
 - **Projects and wiki pages**: create, update and delete
 - **Actions**: enable, disable and dispatch a workflow
 - **System**: startup and shutdown, instance-wide webhooks, authentication
  sources, instance-wide OAuth2 applications
 Recording never fails the request that triggered it. A write error is logged
 and the original operation continues.
 ## What is not recorded
 - Read-only access such as browsing, clone, fetch or API GET requests
 - Logins, successful or failed, other than failed two-factor authentication
  (use the [access log](logging-config.md) and
  [Fail2ban Setup](fail2ban-setup.md) for authentication traffic)
 - Edits to issues and pull requests
 - Token or secret values
 - Which SSH key a real user pushed with (deploy keys are named; ordinary SSH
  user pushes are not)
 ## Retention
 `RETENTION_DAYS` (default **30**) is the age after which recorded events are
 eligible for deletion. Set it to `0` to keep events forever.
 Cleanup is performed by the `cron.delete_old_audit_events` task (`SCHEDULE`
 defaults to `@every 24h`, `OLDER_THAN` defaults to `[audit].RETENTION_DAYS`).
 The task is registered only while `RECORD_OUTPUT` records events **and**
 `RETENTION_DAYS` is greater than `0`. Turning recording off therefore also
 stops pruning; existing rows stay until you delete them or turn recording back
 on.
@@ -337,13 +337,9 @@ The default login user email is `X-WEBAUTH-EMAIL`, you can change it via changin
 If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`.
-It applies to the web interface, Git over HTTP, Git LFS and the package registry.
+You can also limit the reverse proxy's IP address range with `REVERSE_PROXY_TRUSTED_PROXIES` which default value is `127.0.0.0/8,::1/128`. By `REVERSE_PROXY_LIMIT`, you can limit trusted proxies level.
-:::warning
+You can enable the this authentication method for the API with
 Gitea trusts these headers on every request it receives. Make sure Gitea is only reachable through your authenticating proxy, and that the proxy sets or removes these headers on every request, including on paths you exempt from authentication, for example for Git or package clients. `REVERSE_PROXY_TRUSTED_PROXIES` does not restrict them.
 :::
 To also accept them on the REST API under `/api/v1`, enable:
 ```ini
 [service]
@@ -83,7 +83,7 @@ cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/data/gitea-repositories/
+mv repos/* /var/lib/gitea/data/repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
 # mysql
@@ -130,8 +130,8 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
   HTTP protocol.
 - `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when
   default SSH port is used.
- `GO_GET_CLONE_URL_PROTOCOL`: **_empty_**: Scheme of the returned URL for the "go get" response.
+- `GO_GET_CLONE_URL_PROTOCOL`: **https**: Value for the "go get" request returns the repository url as https or ssh
-   Default is "https" if DISABLE_HTTP_GIT=false or SSH is disabled, otherwise "ssh".
+   default is https.
 - `ACCESS_CONTROL_ALLOW_ORIGIN`: **_empty_**: Value for Access-Control-Allow-Origin header,
   default is not to present.
@@ -270,10 +270,9 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `FOLDER_ICON_THEME`: **basic**: The icon theme for folders (basic/material).
 - `MAX_DISPLAY_FILE_SIZE`: **8388608**: Max size of files to be displayed (default is 8MiB)
 - `AMBIGUOUS_UNICODE_DETECTION`: **true**: Detect ambiguous unicode characters in file contents and show warnings on the UI
- `REACTIONS`: All available reactions users can choose on issues, pull requests and comments.
+- `REACTIONS`: All available reactions users can choose on issues/prs and comments
    Values can be emoji alias (:smile:) or a unicode emoji.
    For custom reactions, add a tightly cropped square image to public/assets/img/emoji/reaction_name.png
 - `RELEASE_REACTIONS`: **+1, laugh, hooray, heart, rocket, eyes**: Reactions available for releases, in the same format as `REACTIONS`.
 - `REACTION_MAX_USER_NUM`: **10**: Change the number of users that are displayed in reactions tooltip (triggered by mouse hover).
 - `CUSTOM_EMOJIS`: **gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the utf8 standard.
    By default, we support Gitea (:gitea:), to add more copy them to public/assets/img/emoji/emoji_name.png and
@@ -349,7 +348,8 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `PROXY_PROTOCOL_TLS_BRIDGING`: **false**: When protocol is https, expect PROXY protocol headers after TLS negotiation.
 - `PROXY_PROTOCOL_HEADER_TIMEOUT`: **5s**: Timeout to wait for PROXY protocol header (set to 0 to have no timeout)
 - `PROXY_PROTOCOL_ACCEPT_UNKNOWN`: **false**: Accept PROXY protocol headers with Unknown type.
- `ROOT_URL`: **`{PROTOCOL}://localhost:{HTTP_PORT}/`**:
+- `DOMAIN`: **localhost**: Domain name of this server.
 - `ROOT_URL`: **`{PROTOCOL}://{DOMAIN}:{HTTP_PORT}/`**:
   Overwrite the automatically generated public URL.
   This is useful if the internal and the external URL don't match (e.g. behind a reverse proxy).
 - `PUBLIC_URL_DETECTION`: **`auto`**: Controls how to generate the public URL. Most instances should use the "auto" behavior,
@@ -404,7 +404,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
  If it is set to `(DOER_USERNAME)`, it will use current signed-in user's username.
  This option is only for some advanced users who have configured their SSH reverse-proxy and need to use different usernames for git SSH clone.
  Most users should just leave it blank and/or modify the `BUILTIN_SSH_SERVER_USER`.
- `SSH_DOMAIN`: **_empty_**: Domain name to be exposed in clone URL, defaults to the domain part of ROOT_URL
+- `SSH_DOMAIN`: **`{DOMAIN}`**: Domain name of this server, used for displayed clone URL.
 - `SSH_PORT`: **22**: SSH port displayed in clone URL. If you need a different "SSH clone port" from the real "SSH listen port", set the SSH_LISTEN_PORT separately.
 - `SSH_LISTEN_HOST`: **0.0.0.0**: Listen address for the built-in SSH server.
 - `SSH_LISTEN_PORT`: **`{SSH_PORT}`**: Port for the built-in SSH server.
@@ -420,7 +420,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `SSH_SERVER_CIPHERS`: **`chacha20-poly1305@openssh.com`, `aes128-ctr`, `aes192-ctr`, `aes256-ctr`, `aes128-gcm@openssh.com`, `aes256-gcm@openssh.com`**: For the built-in SSH server, choose the ciphers to support for SSH connections, for system SSH this setting has no effect.
 - `SSH_SERVER_KEY_EXCHANGES`: **curve25519-sha256, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group14-sha256, diffie-hellman-group14-sha1**: For the built-in SSH server, choose the key exchange algorithms to support for SSH connections, for system SSH this setting has no effect.
 - `SSH_SERVER_MACS`: **`hmac-sha2-256-etm@openssh.com`, `hmac-sha2-256`, `hmac-sha1`**: For the built-in SSH server, choose the MACs to support for SSH connections, for system SSH this setting has no effect
- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gitea.ed25519, ssh/gitea.ecdsa, ssh/gogs.rsa**: For the built-in SSH server, choose the keypairs to offer as the host key. The private key should be at `SSH_SERVER_HOST_KEY` and the public `SSH_SERVER_HOST_KEY.pub`. Relative paths are made absolute relative to the `APP_DATA_PATH`. If none of the keys exist, a 4096 bit RSA, a 256 bit ECDSA and an ED25519 key will be created for you.
+- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gogs.rsa**: For the built-in SSH server, choose the keypairs to offer as the host key. The private key should be at `SSH_SERVER_HOST_KEY` and the public `SSH_SERVER_HOST_KEY.pub`. Relative paths are made absolute relative to the `APP_DATA_PATH`. If no key exists a 4096 bit RSA key will be created for you.
 - `SSH_KEY_TEST_PATH`: **/tmp**: Directory to create temporary files in when testing public keys using ssh-keygen, default is the system temporary directory.
 - `SSH_KEYGEN_PATH`: **_empty_**: Use `ssh-keygen` to parse public SSH keys. The value is passed to the shell. By default, Gitea does the parsing itself.
 - `SSH_EXPOSE_ANONYMOUS`: **false**: Enable exposure of SSH clone URL to anonymous visitors, default is false.
@@ -587,7 +587,8 @@ And the following unique queues:
 - `SECRET_KEY`: **\<random at every install\>**: Global secret key. This key is VERY IMPORTANT, if you lost it, the data encrypted by it (like 2FA secret) can't be decrypted anymore.
 - `SECRET_KEY_URI`: **_empty_**: Instead of defining SECRET_KEY, this option can be used to use the key stored in a file (example value: `file:/etc/gitea/secret_key`). It shouldn't be lost like SECRET_KEY.
 - `LOGIN_REMEMBER_DAYS`: **31**: How long to remember that a user is logged in before requiring relogin (in days).
- `COOKIE_REMEMBER_NAME`: **gitea\_remember**: Name of cookie used to store authentication information.
+- `COOKIE_REMEMBER_NAME`: **gitea\_incredible**: Name of cookie used to store authentication
   information.
 - `REVERSE_PROXY_LOGOUT_REDIRECT`: **_empty_**: URL or relative path to redirect users to after logout when authentication is handled by a reverse proxy or SSO. For example: `/my-sso/logout?return=/my-sso/home`.
 - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: Header name for reverse proxy
   authentication.
@@ -646,30 +647,14 @@ And the following unique queues:
 - `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: Cache successful token hashes. API tokens are stored in the DB as pbkdf2 hashes however, this means that there is a potentially significant hashing load when there are multiple API operations. This cache will store the successfully hashed tokens in a LRU cache as a balance between performance and security.
 - `DISABLE_QUERY_AUTH_TOKEN`: **false**: Reject API tokens sent in URL query string (Accept Header-based API tokens only). This setting will default to `true` in Gitea 1.23 and be deprecated in Gitea 1.24.
 - `TWO_FACTOR_AUTH`: **_empty_**: set to enforced to enforce two factor authentication. Only available in Gitea 1.24 and later.
- `EGRESS_MODE`: **lax**: Egress mode toggles between strictness of outgoing requests:
+- `ALLOWED_HOST_LIST`: **external**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list.
  - `lax` non-public targets (private, loopback, link-local, CGNAT and special-use ranges) to be allowed, it allows all public ones
  - `strict` requires an explicit allow of all addresses
 - `ALLOWED_HOST_LIST`: **_empty_**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list, eg: `192.168.1.0/24:3000`, `[2001:db8::/32]:9090`, `*.mydomain.com:[80|443]`
  - Built-in networks:
    - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6, localhost is included.
-    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), RFC 4193 (FC00::/7) and RFC 6598 CGNAT (100.64.0.0/10). Also called LAN/Intranet.
+    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7). Also called LAN/Intranet.
-  - CIDR list: `1.2.3.0/8`, `2001:db8::/32`, and with a port `[2001:db8::/32]:9090` (IPv6 addresses and CIDRs need brackets when a port is given)
+    - `external`: A valid non-private unicast IP, you can access all hosts on public internet.
-  - Host matching: `example.com` matches the host and any subdomain, dot-anchored so `notexample.com` never matches. `*.example.com` and `.example.com` match only subdomains, the apex itself is excluded. IDN names must be given as punycode.
+    - `*`: All hosts are allowed.
-  - All addresses can have ports specified. Accepted port specs:
+  - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6
-    - a single port: `192.168.1.0/24:3000`
+  - Wildcard hosts: `*.mydomain.com`, `192.168.100.*`
    - a range, both bounds inclusive: `*.mydomain.com:3000-3010`
    - a bracketed set of ports and ranges, `|` separated: `*.mydomain.com:[80|443|3000-3010]`
    - all ports: `*.mydomain.com:*`
  - A portless entry covers all ports in `lax` mode, only 80 and 443 in `strict` mode
  - Port specs apply only where the list is consulted: in `lax` mode that is non-public targets alone, public targets are allowed on every port whatever the list says. In `strict` mode every target is checked, so ports restrict public hosts too.
  - Non-public targets need an IP or built-in entry, a host name entry alone never covers them.
  - Reserved addresses (the IPv4-embedding NAT64, Teredo and 6to4 ranges, this-network, multicast and broadcast) are denied whatever the list says. To reach them configure an HTTP proxy
  - This list is enforced on direct connections only. When an HTTP proxy is configured, restricting the proxied target is the proxy server's responsibility.
 ## Audit (`audit`)
 - `RECORD_OUTPUT`: **disabled**: Where security-relevant events are recorded. `disabled` records nothing. `database` writes events to the `audit_event` table and shows them in the admin, organization, repository and user settings. Invalid values fall back to `disabled`. See [Audit Logging](audit-logging.md).
 - `RETENTION_DAYS`: **30**: Days to keep recorded events. `0` keeps them forever. Pruning is done by `cron.delete_old_audit_events`. That task is only registered while `RECORD_OUTPUT` records events and `RETENTION_DAYS` is greater than `0`.
 ## Camo (`camo`)
@@ -680,8 +665,8 @@ And the following unique queues:
 ## OpenID (`openid`)
- `ENABLE_OPENID_SIGNIN`: **false**: Allow authentication in via OpenID.
+- `ENABLE_OPENID_SIGNIN`: **true**: Allow authentication in via OpenID.
- `ENABLE_OPENID_SIGNUP`: **false**: Allow registering via OpenID.
+- `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION**: Allow registering via OpenID.
 - `WHITELISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
   OpenID URI's to permit.
 - `BLACKLISTED_URIS`: **_empty_**: If non-empty, list of POSIX regex patterns matching
@@ -716,7 +701,7 @@ And the following unique queues:
   Requires `Mailer` to be enabled.
 - `REGISTER_MANUAL_CONFIRM`: **false**: Enable this to manually confirm new registrations.
   Requires `REGISTER_EMAIL_CONFIRM` to be disabled.
- `DISABLE_REGISTRATION`: **true**: Disable registration, after which only admin can create
+- `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create
   accounts for users.
 - `REQUIRE_EXTERNAL_REGISTRATION_PASSWORD`: **false**: Enable this to force externally created
   accounts (via GitHub, OpenID Connect, etc) to create a password.
@@ -740,8 +725,8 @@ And the following unique queues:
   If you set it to false, maybe it also needs to set `ENABLE_BASIC_AUTHENTICATION` to false to
   completely disable password-based authentication.
 - `ENABLE_PASSKEY_AUTHENTICATION`: **true**: Allow users to sign-in with a passkey
- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable reverse proxy authentication for the web interface, Git over HTTP, Git LFS and the package registry. Gitea must only be reachable through the proxy, see [Reverse Proxy](authentication.md#reverse-proxy).
+- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable this to allow reverse proxy authentication for web requests
- `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`: **false**: Enable reverse proxy authentication for the REST API under `/api/v1`.
+- `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`: **false**: Enable this to allow reverse proxy authentication for API requests, the reverse proxy is responsible for ensuring that no CSRF is possible.
 - `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration
   for reverse authentication.
 - `ENABLE_REVERSE_PROXY_EMAIL`: **false**: Enable this to allow to auto-registration with a
@@ -775,7 +760,7 @@ And the following unique queues:
 - `DEFAULT_ALLOW_ONLY_CONTRIBUTORS_TO_TRACK_TIME`: **true**: Only allow users with write permissions to track time.
 - `EMAIL_DOMAIN_ALLOWLIST`: **_empty_**: If non-empty, comma separated list of domain names that can only be used to register on this instance, wildcard is supported.
 - `EMAIL_DOMAIN_BLOCKLIST`: **_empty_**: If non-empty, comma separated list of domain names that cannot be used to register on this instance, wildcard is supported.
- `SHOW_REGISTRATION_BUTTON`: **false**: Show Registration button, defaults to true only if both DISABLE_REGISTRATION and ALLOW_ONLY_EXTERNAL_REGISTRATION are false
+- `SHOW_REGISTRATION_BUTTON`: **! DISABLE\_REGISTRATION**: Show Registration Button
 - `SHOW_MILESTONES_DASHBOARD_PAGE`: **true** Enable this to show the milestones dashboard page - a view of all the user's milestones
 - `AUTO_WATCH_NEW_REPOS`: **true**: Enable this to let all organisation users watch new repos when they are created
 - `AUTO_WATCH_ON_CHANGES`: **false**: Enable this to make users watch a repository after their first commit to it
@@ -785,7 +770,8 @@ And the following unique queues:
 - `DEFAULT_ORG_MEMBER_VISIBLE`: **false** True will make the membership of the users visible when added to the organisation.
 - `ALLOW_ONLY_INTERNAL_REGISTRATION`: **false** Set to true to force registration only via Gitea.
 - `ALLOW_ONLY_EXTERNAL_REGISTRATION`: **false** Set to true to force registration only using third-party services.
- `NO_REPLY_ADDRESS`: **_empty_**: Value for the domain part of the user's email address in the git log if user has set KeepEmailPrivate to true. The user's email will be replaced with a concatenation of the user name in lower case, "@" and NO_REPLY_ADDRESS. Default value is "noreply." + the domain part of ROOT_URL
+- `NO_REPLY_ADDRESS`: **noreply.DOMAIN** Value for the domain part of the user's email address in the Git log if user has set KeepEmailPrivate to true. DOMAIN resolves to the value in server.DOMAIN.
  The user's email will be replaced with a concatenation of the user name in lower case, "@" and NO_REPLY_ADDRESS.
 - `USER_DELETE_WITH_COMMENTS_MAX_TIME`: **0** Minimum amount of time a user must exist before comments are kept when the user is deleted.
 - `VALID_SITE_URL_SCHEMES`: **http, https**: Valid site url schemes for user profiles
@@ -818,11 +804,9 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
 - `DELIVER_TIMEOUT`: **5**: Delivery timeout (sec) for shooting webhooks.
 - `SKIP_TLS_VERIFY`: **false**: Allow insecure certification.
 - `PAGING_NUM`: **10**: Number of webhook history events that are shown in one page.
- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting.
+- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting.
 - `PROXY_HOSTS`: **_empty_`**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts. If not given, will use global proxy setting.
 When a proxy is configured, Gitea does not enforce `[security]` `ALLOWED_HOST_LIST` on the proxied target, the proxy server is expected to restrict it.
 ## Mailer (`mailer`)
 :::warning
@@ -897,27 +881,27 @@ In-Reply-To =
 ## Cache (`cache`)
- `ADAPTER`: **memory**: Either `memory`, `redis`, `memcache`, or `twoqueue`.
+- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, `twoqueue` or `memcache`. (`twoqueue` represents a size limited LRU cache.)
- `INTERVAL`: **60**: For `memory` and `twoqueue`, GC interval in seconds.
+- `INTERVAL`: **60**: Garbage Collection interval (sec), for memory and twoqueue cache only.
- `HOST`: **_empty_**: For `redis` and `memcache`, connection host address. For `twoqueue` sets configuration for the queue. If left empty while `ADAPTER` is `redis`, it falls back to [redis/CONN_STR](#redis-redis) when that is set.
+- `HOST`: **_empty_**: Connection string for `redis` and `memcache`. For `twoqueue` sets configuration for the queue. If left empty while `ADAPTER` is `redis`, it falls back to [redis/CONN_STR](#redis-redis) when that is set.
  - Redis: `redis://:[email protected]:6379/0?pool_size=100&idle_timeout=180s` (See [queue/CONN_STR](#queue-queue-and-queue) for information on additional supported connection types)
    - For a Redis cluster: `redis+cluster://:[email protected]:6379/0?pool_size=100&idle_timeout=180s`
    - For a Redis sentinel: `redis+sentinel://:macaron@sentinel0:26379,sentinel1:26379,sentinel2:26379/0?pool_size=100&idle_timeout=180s&master_name=mymaster`
-  - Memcache: `127.0.0.1:11211`
+  - Memcache: `127.0.0.1:9090;127.0.0.1:9091`
  - TwoQueue LRU cache: `{"size":50000,"recent_ratio":0.25,"ghost_ratio":0.5}` or `50000` representing the maximum number of objects stored in the cache.
- `ITEM_TTL`: **16h**: Time to keep items in cache if not used. Setting it to -1 disables caching.
+- `ITEM_TTL`: **16h**: Time to keep items in cache if not used, Setting it to -1 disables caching.
 ## Cache - LastCommitCache settings (`cache.last_commit`)
- `ITEM_TTL`: **8760h**: Time to keep items in cache if not used. Setting it to -1 disables caching.
+- `ITEM_TTL`: **8760h**: Time to keep items in cache if not used, Setting it to -1 disables caching.
 - `COMMITS_COUNT`: **1000**: Only enable the cache when repository's commits count great than.
 ## Session (`session`)
- `PROVIDER`: **file**: Either "memory", "file", "redis" or "db", default is "file". "db" will reuse the configuration in `[database]`
+- `PROVIDER`: **memory**: Session engine provider \[memory, file, redis, db, mysql, couchbase, memcache, postgres\]. Setting `db` will reuse the configuration in `[database]`
 - `PROVIDER_CONFIG`: **data/sessions**: For file, the root path; for db, empty (database config will be used); for others, the connection string. Relative paths will be made absolute against _`AppWorkPath`_. For the `redis` provider, if left empty it falls back to [redis/CONN_STR](#redis-redis) when that is set.
 - `COOKIE_SECURE`:**_empty_**: `true` or `false`. Enable this to force using HTTPS for all session access. If not set, it defaults to `true` if the ROOT_URL is an HTTPS URL.
- `COOKIE_NAME`: **gitea\_session**: Session cookie name
+- `COOKIE_NAME`: **i\_like\_gitea**: The name of the cookie used for the session ID.
 - `GC_INTERVAL_TIME`: **86400**: GC interval in seconds.
 - `SESSION_LIFE_TIME`: **86400**: Session life time in seconds, default is 86400 (1 day)
 - `DOMAIN`: **_empty_**: Sets the cookie Domain
@@ -944,7 +928,7 @@ In-Reply-To =
  - none = no avatar will be displayed
  - random = random avatar will be generated
  - image = default image will be used (which is set in `REPOSITORY_AVATAR_FALLBACK_IMAGE`)
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **_empty_**: Image used as default repository avatar (if `REPOSITORY_AVATAR_FALLBACK` is set to image and none was uploaded). The value is used as-is, without prepending the sub-path of `ROOT_URL`. Empty uses Gitea's builtin repository avatar.
+- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: Image used as default repository avatar (if `REPOSITORY_AVATAR_FALLBACK` is set to image and none was uploaded)
 ## Project (`project`)
@@ -1063,7 +1047,7 @@ Release attachment has its own config options in `[repository.release]` section.
 - `ENABLED`: **true**: Enable running Update mirrors task periodically.
 - `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g. `@every 3h`.
 - `RUN_AT_START`: **false**: Run Update mirrors task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling pull mirror updating).
 - `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit, 0 will result in no mirrors being queued effectively disabling push mirror updating).
@@ -1072,7 +1056,7 @@ Release attachment has its own config options in `[repository.release]` section.
 - `ENABLED`: **true**: Enable running repository health check task periodically.
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
 - `RUN_AT_START`: **false**: Run repository health check task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
 - `ARGS`: **_empty_**: Arguments for command `git fsck`, e.g. `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck
@@ -1081,13 +1065,12 @@ Release attachment has its own config options in `[repository.release]` section.
 - `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.
 - `ENABLED`: **true**: Enable running repository statistics check task periodically.
 - `RUN_AT_START`: **true**: Run repository statistics check task when Gitea starts.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 #### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)
 - `ENABLED`: **true**: Enable cleanup hook_task job.
 - `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@midnight**: Cron syntax for cleaning hook_task table.
 - `CLEANUP_TYPE` **OlderThan** OlderThan or PerWebhook Method to cleanup hook_task, either by age (i.e. how long ago hook_task record was delivered) or by the number to keep per webhook (i.e. keep most recent x deliveries per webhook).
 - `OLDER_THAN`: **168h**: If CLEANUP_TYPE is set to OlderThan, then any delivered hook_task records older than this expression will be deleted.
@@ -1107,7 +1090,7 @@ Update migrated repositories' issues and comments' posterid, it will always atte
 - `ENABLED`: **true**: Enable update migration poster id job.
 - `RUN_AT_START`: **true**: Update migrated repositories' issues and comments' posterid when starting server
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
 #### Cron - Sync External Users (`cron.sync_external_users`)
@@ -1116,7 +1099,7 @@ Synchronize external user data (only LDAP user synchronization is supported)
 - `ENABLED`: **true**: Enable synchronize external user data job
 - `RUN_AT_START`: **false**: Synchronize external user data when starting server
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NOTICE_ON_SUCCESS`: **false**: Notice if not success
 - `SCHEDULE`: **@midnight** : Interval as a duration between each synchronization, it will always attempt synchronization when the instance starts.
 - `UPDATE_EXISTING`: **true**: Create new users, update existing user data and disable users that are not in external source anymore (default) or only create new users if UPDATE_EXISTING is set to false.
@@ -1124,14 +1107,12 @@ Synchronize external user data (only LDAP user synchronization is supported)
 - `ENABLED`: **true**: Enable cleanup expired actions assets job.
 - `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@midnight** : Cron syntax for the job.
 #### Cron - Delete Old Action Runs (`cron.cleanup_action_runs`)
 - `ENABLED`: **true**: Enable the job deleting action runs older than `RUN_RETENTION_DAYS`. Deletes nothing while that is 0.
 - `RUN_AT_START`: **false**: Run job at start time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@midnight**: Cron syntax for the job.
 #### Cron - Cleanup Deleted Branches (`cron.deleted_branches_cleanup`)
@@ -1217,21 +1198,11 @@ Synchronize external user data (only LDAP user synchronization is supported)
 - `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
 - `OLDER_THAN`: **8760h**: any action older than this expression will be deleted from database, suggest using `8760h` (1 year) because that's the max length of heatmap.
 #### Cron - Delete old audit events (`cron.delete_old_audit_events`)
 Deletes audit events older than the retention period. The task is only registered when `[audit].RECORD_OUTPUT` records events and `[audit].RETENTION_DAYS` is greater than `0`. See [Audit Logging](audit-logging.md).
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
 - `OLDER_THAN`: **720h**: any audit event older than this expression will be deleted from the database. Defaults to `[audit].RETENTION_DAYS`.
 #### Cron -  Check for new Gitea versions (`cron.update_checker`)
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
 - `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a work, e.g. `@every 168h`.
 - `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: the endpoint that Gitea will check for newer versions
@@ -1239,7 +1210,7 @@ Deletes audit events older than the retention period. The task is only registere
 - `ENABLED`: **false**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
 - `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.
@@ -1247,7 +1218,6 @@ Deletes audit events older than the retention period. The task is only registere
 - `ENABLED`: **false**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
 - `OLDER_THAN`: **168h**: Only attempt to garbage collect LFSMetaObjects older than this (default 7 days)
 - `LAST_UPDATED_MORE_THAN_AGO`: **72h**: Only attempt to garbage collect LFSMetaObjects that have not been attempted to be garbage collected for this long (default 3 days)
@@ -1260,35 +1230,35 @@ Deletes audit events older than the retention period. The task is only registere
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@annually**: Cron syntax to set how often to rebuild
 #### Cron - Stop running tasks which haven't been updated for a long time (`cron.stop_zombie_tasks`)
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@every 5m**: Cron syntax to set how often tasks to run the check
 #### Cron - Stop running tasks which have running status and continuous updates but don't end for a long time (`cron.stop_endless_tasks`)
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **true**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@every 30m**: Cron syntax to set how often to run the check.
 #### Cron - Cancel jobs which haven't been picked up for a long time (`cron.cancel_abandoned_jobs`)
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@every 6h**: Cron syntax to set how often to run the check.
 #### Cron - Start cron based actions (`cron.start_schedule_tasks`)
 - `ENABLED`: **true**: Enable service.
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
+- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@every 1m**: Cron syntax to set how often to schedule tasks
 ## Git (`git`)
@@ -1328,6 +1298,7 @@ These options are written into the gitconfig file under `[git] HOME_PATH` when G
 - `diff.algorithm`: **histogram**
 - `core.logAllRefUpdates`: **true**
 - `gc.reflogExpire`: **90**
 ## Metrics (`metrics`)
@@ -1439,13 +1410,11 @@ in this mapping or the filetype using heuristics.
 - `MAX_ATTEMPTS`: **3**: Max attempts per http/https request on migrations.
 - `RETRY_BACKOFF`: **3**: Backoff time per http/https request retry (seconds)
- `EGRESS_MODE`: **lax**: Mode toggles between strictness of scanning outgoing requests, same format as `EGRESS_MODE` in [`security`](#security-security).
+- `ALLOWED_DOMAINS`: **_empty_**: Domains allowlist for migrating repositories, default is blank. It means external hosts will be allowed. Multiple domains could be separated by commas. Wildcard is supported: `github.com, *.github.com`.
- `ALLOWED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may call, same format as `ALLOWED_HOST_LIST` in [`security`](#security-security). Private, loopback and link-local addresses need a builtin or CIDR entry. When unset, the deprecated `ALLOWED_DOMAINS` entries apply on every port with `strict` as the default mode, and the deprecated `ALLOW_LOCALNETWORKS` adds `private, loopback`.
+- `BLOCKED_DOMAINS`: **_empty_**: Domains blocklist for migrating repositories, default is blank. Multiple domains could be separated by commas. When `ALLOWED_DOMAINS` is not blank, this option has a higher priority to deny domains. Wildcard is supported.
- `BLOCKED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may never call, portless entries cover all ports.
+- `ALLOW_LOCALNETWORKS`: **false**: Allow private addresses defined by RFC 1918, RFC 1122, RFC 4632 and RFC 4291. If a domain is allowed by `ALLOWED_DOMAINS`, this option will be ignored.
 - `SKIP_TLS_VERIFY`: **false**: Allow skip tls verify
 These lists are enforced on direct connections only. When a proxy is configured (`[proxy]`, `[git.config]` `http.proxy` or the environment), restricting the proxied target is the proxy server's responsibility.
 ## Federation (`federation`)
 - `ENABLED`: **false**: Enable/Disable federation capabilities
@@ -1680,16 +1649,14 @@ is `data/repo-archive` and the default of `MINIO_BASE_PATH` is `repo-archive/`.
 ## Proxy (`proxy`)
 - `PROXY_ENABLED`: **false**: Enable the proxy if true, all requests to external via HTTP will be affected, if false, no proxy will be used even environment http_proxy/https_proxy
- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy
+- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy
 - `PROXY_HOSTS`: **_empty_**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts.
 When a proxy is configured, Gitea does not enforce the egress lists (`[security]`, `[migrations]`) on the proxied target, the proxy server is expected to restrict it.
 i.e.
 ```ini
 PROXY_ENABLED = true
-PROXY_URL = socks5://127.0.0.1:1080
+PROXY_URL = socks://127.0.0.1:1080
 PROXY_HOSTS = *.github.com
 ```
@@ -1708,7 +1675,6 @@ PROXY_HOSTS = *.github.com
 - `ARTIFACT_RETENTION_DAYS`: **90**: Days to keep artifacts. Old artifacts will be deleted after this period. 0 means keep forever.
  Changes only apply to newly uploaded artifacts, existing ones keep the expiry stored when they were uploaded.
  Artifacts could have their own retention periods by setting the `retention-days` option in `actions/upload-artifact` step.
 - `ARTIFACT_PREVIEW_MAX_SIZE`: **10485760**: Maximum total artifact size in bytes that can be browsed or previewed in the web UI. Set to `0` to disable artifact previews or `-1` for no limit. Individual files are also limited by [`MAX_DISPLAY_FILE_SIZE`](#ui-ui).
 - `RUN_RETENTION_DAYS`: **400**: Days to keep completed runs. Old runs and everything under them will be deleted after this period. 0 means keep forever.
 - `ZOMBIE_TASK_TIMEOUT`: **10m**: Timeout to stop the task which have running status, but haven't been updated for a long time
 - `ENDLESS_TASK_TIMEOUT`: **3h**: Timeout to stop the tasks which have running status and continuous updates, but don't end for a long time
@@ -1718,9 +1684,18 @@ PROXY_HOSTS = *.github.com
 - `SCOPED_WORKFLOW_DIRS`: **.gitea/scoped_workflows**: Comma-separated list of directories holding [scoped workflows](usage/actions/scoped-workflows.md) (workflows defined in a central source repository that run on other repositories). Must not overlap with `WORKFLOW_DIRS`. Leave empty so no directory is scanned for scoped workflows; none are found or run.
 - `MAX_RERUN_ATTEMPTS`: **50**: Maximum number of attempts a single workflow run can have (initial run + reruns). Defaults value is 50. Set any positive value that fits your workflow needs.
-`DEFAULT_ACTIONS_URL` sets where runners download actions without a host.
+`DEFAULT_ACTIONS_URL` indicates where the Gitea Actions runners should find the actions with relative path.
-With `github`, `uses: actions/checkout@v4` resolves to `https://github.com/actions/checkout@v4`, with `self` to `<ROOT_URL>/actions/checkout@v4`.
+For example, `uses: actions/checkout@v4` means `https://github.com/actions/checkout@v4` since the value of `DEFAULT_ACTIONS_URL` is `github`.
-`self` requires mirroring every action you use to your instance, so prefer naming the host per action instead: `uses: self:owner/repo@ref` for your instance, or a full URL like `uses: https://gitea.com/actions/checkout@v4` for any other host.
+And it can be changed to `self` to make it `root_url_of_your_gitea/actions/checkout@v4`.
 Please note that using `self` is not recommended for most cases, as it could make names globally ambiguous.
 Additionally, it requires you to mirror all the actions you need to your Gitea instance, which may not be worth it.
 Therefore, please use `self` only if you understand what you are doing.
 In earlier versions (`<= 1.19`), `DEFAULT_ACTIONS_URL` could be set to any custom URLs like `https://gitea.com` or `http://your-git-server,https://gitea.com`, and the default value was `https://gitea.com`.
 However, later updates removed those options, and now the only options are `github` and `self`, with the default value being `github`.
 However, if you want to use actions from other git server, you can use a complete URL in `uses` field, it's supported by Gitea (but not GitHub).
 Like `uses: https://gitea.com/actions/checkout@v4` or `uses: http://your-git-server/actions/checkout@v4`.
 ## Other (`other`)
@@ -86,21 +86,6 @@ PROTOCOL       = smtps
 Note that you'll need to create and use an [App password](https://support.google.com/accounts/answer/185833?hl=en) by enabling 2FA on your Google
 account. You won't be able to use your Google account password directly.
 An app password is the only option: Google
 [turned off access for apps that sign in with a password alone](https://workspaceupdates.googleblog.com/2023/09/winding-down-google-sync-and-less-secure-apps-support.html)
 in 2024 and asks applications to use OAuth instead, which Gitea's mailer does
 not implement — it authenticates with `CRAM-MD5`, `PLAIN` or `LOGIN`.
 Two things to keep in mind:
 - app passwords require 2-step verification on the account, and a Google
  Workspace administrator can switch them off for the whole domain. If they are
  not available, send through the
  [Workspace SMTP relay service](https://support.google.com/a/answer/2956491)
  or through another mail provider.
 - port `587` works as well, with `SMTP_PORT = 587` and
  `PROTOCOL = smtp+starttls`.
 ### ProtonMail
 This feature is currently only available for select Proton for Business customers and those with Visionary and Family plans with custom domain addresses. See [ProtonMail's SMTP documentation](https://proton.me/support/smtp-submission) for more information. This limitation can be circumvented by using the ProtonMail Bridge application.
@@ -41,24 +41,3 @@ client that causes SSH transfers to hang: https://github.com/git-lfs/git-lfs/pul
 This can be worked around on all the client machines by setting the git config:
 `git config --global lfs.ssh.automultiplex false`
 :::
 # Changing LFS files through the API
 The [contents API](https://docs.gitea.com/api/operations/repo-change-files/)
 works on LFS tracked files as well: send the file content as usual and Gitea
 stores it as an LFS object and commits a pointer file, as long as the path is
 matched by a `filter=lfs` rule in `.gitattributes`.
 What is easy to get wrong is the `sha` of the file being changed, which
 `PUT`/`DELETE /repos/{owner}/{repo}/contents/{filepath}` and
 `POST /repos/{owner}/{repo}/contents` require for an existing file. Gitea
 compares it with the ID of the blob the commit has at that path, and for an LFS
 tracked file that blob is the **pointer file**, not the content:
 - use the `sha` returned by
  [`GET /repos/{owner}/{repo}/contents/{filepath}`](https://docs.gitea.com/api/operations/repo-get-contents/)
 - do not use `lfs_oid` from the same response, which identifies the LFS object,
  and do not use a checksum of the file itself
 Sending anything else fails with `sha does not match`, even though the request
 looks correct.
@@ -16,8 +16,6 @@ The logging configuration of Gitea mainly consists of 3 types of components:
 There is a fully functional log output by default, so it is not necessary to define one.
 Security-relevant events (repository transfers, token changes, impersonation, and similar) are recorded separately. See [Audit Logging](audit-logging.md).
 ## Collecting Logs for Help
 To collect logs for help and issue report, see [Support Options](help/support.md).
@@ -43,7 +43,7 @@ You can try it out using [the online demo](https://demo.gitea.com).
 - **Security**
-  Gitea places a strong emphasis on security, offering features such as user permission management, access control lists, [audit logging](administration/audit-logging.md), and more to ensure the security of code and data.
+  Gitea places a strong emphasis on security, offering features such as user permission management, access control lists, and more to ensure the security of code and data.
 - **Code Review**
@@ -34,7 +34,6 @@ _Symbols used in table:_
 | Telemetry                                        | **✘**                                               | ✓         | ✓         | ✓         | ✓         | ✘            | ✘            |
 | Third-party render tool support                  | ✓                                                   | ✘         | ✘         | ✘         | ✓         | ✘            | ✘            |
 | WebAuthn (2FA)                                   | ✓                                                   | ✓         | ✓         | ✓         | ✓         | ✘            | ✓            |
 | Audit log                                        | ✓                                                   | ✓         | ⁄         | ✓         | ✓         | ?            | ?            |
 | Extensive API                                    | ✓                                                   | ✓         | ✓         | ✓         | ✓         | ✓            | ✓            |
 | Built-in Package/Container Registry              | ✓                                                   | ✓         | ✓         | ✓         | ✘         | ✘            | ✘            |
 | Sync commits to an external repo (push mirror)   | ✓                                                   | ✘         | ✓         | ✓         | ✘         | ✓            | ✓            |
@@ -23,7 +23,7 @@ version is @minNodeVersion@ and the latest LTS version is recommended.
 :::note
 Go version @minGoVersion@ or higher is required. However, it is recommended to
 obtain the same version as our continuous integration, see the advice given in
-[Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
+[Hacking on Gitea](development/hacking-on-gitea.md)
 :::
 ## Download
@@ -73,7 +73,7 @@ To build from source, the following programs must be present on the system:
 - `go` @minGoVersion@ or higher, see [here](https://go.dev/dl/)
 - `node` @minNodeVersion@ or higher with `npm`, see [here](https://nodejs.org/en/download/)
- `make`, see [here](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md#make)
+- `make`, see [here](development/hacking-on-gitea.md#installing-make)
 Various [make tasks](https://github.com/go-gitea/gitea/blob/main/Makefile)
 are provided to keep the build process as simple as possible.
@@ -0,0 +1,49 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "install-on-cloud-provider"
 sidebar_position: 90
 aliases:
  - /en-us/install-on-cloud-provider
 ---
 # Installation on Cloud Provider
 ## Cloudron
 Gitea is available as a 1-click install on [Cloudron](https://cloudron.io).
 Cloudron makes it easy to run apps like Gitea on your server and keep them up-to-date and secure.
 [![Install](/cloudron.svg)](https://cloudron.io/button.html?app=io.gitea.cloudronapp)
 The Gitea package is maintained [here](https://git.cloudron.io/cloudron/gitea-app).
 There is a [demo instance](https://my.demo.cloudron.io) (username: cloudron password: cloudron) where
 you can experiment with running Gitea.
 ## Linode
 [Linode](https://www.linode.com/) has Gitea as an app in their marketplace.
 To deploy Gitea to Linode, have a look at the [Linode Marketplace](https://www.linode.com/marketplace/apps/linode/gitea/).
 ## alwaysdata
 [alwaysdata](https://www.alwaysdata.com/) has Gitea as an app in their marketplace.
 To deploy Gitea to alwaysdata, have a look at the [alwaysdata Marketplace](https://www.alwaysdata.com/en/marketplace/gitea/).
 ## Exoscale
 [Exoscale](https://www.exoscale.com/) provides Gitea managed by [Glasskube](https://glasskube.eu/) in their marketplace.
 Exoscale is a European cloud service provider.
 The package is maintained and update via the open source [Glasskube Kubernetes Operator](https://github.com/glasskube/operator).
 To deploy Gitea to Exoscale, have a look at the [Exoscale Marketplace](https://www.exoscale.com/marketplace/listing/glasskube-gitea/).
 ## Sealos
 Gitea is available as a one-click deployment on [Sealos](https://sealos.io/products/app-store/gitea).
 The community-maintained template source is available [here](https://github.com/labring-actions/templates/tree/kb-0.9/template/gitea).
@@ -66,7 +66,7 @@ server-1  | 2026-03-11T12:57:50.796198843Z /var/lib/gitea/git is not writable
 server-1  | 2026-03-11T12:57:50.796235667Z docker setup failed
 ```
-For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:main-nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly-rootless`)
+For a stable release you could use `:latest-rootless`, `:1-rootless` or specify a certain release like `:@dockerVersion@-rootless`, but if you'd like to use the latest development version then `:nightly-rootless` would be an appropriate tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly-rootless` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly-rootless`)
 ## Named volumes
@@ -30,7 +30,7 @@ image as a service. Since there is no database available, one can be initialized
 Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
 Note that the volume should be owned by the user/group with the UID/GID specified in the config file.
 If you don't give the volume correct permissions, the container may not start.
-For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:main-nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.27-nightly`)
+For a stable release you can use `:latest`, `:1` or specify a certain release like `:@dockerVersion@`, but if you'd like to use the latest development version of Gitea then you could use the `:nightly` tag. If you'd like to run the latest commit from a release branch you can use the `:1.x-nightly` tag, where x is the minor version of Gitea. (e.g. `:1.16-nightly`)
 ```yaml
 networks:
@@ -191,7 +191,7 @@ services:
 +    networks:
 +      - gitea
 +    volumes:
-+      - ./postgres:/var/lib/postgresql
+      - ./postgres:/var/lib/postgresql/data
 ```
 ## Named volumes
@@ -1,166 +0,0 @@
 ---
 date: "2026-09-03T20:00:00+02:00"
 slug: "install-with-podman-quadlet"
 sidebar_position: 65
 aliases:
  - /en-us/install-with-podman-quadlet
 ---
 # Installation with Podman Quadlet
 Similarly to [Docker](with-docker.md), [Podman](https://podman.io/) can be used to deploy Gitea.
 This reference setup guides users through the setup based on Podman Quadlet.
 Podman Quadlet is the native integration of Podman through systemd.
 To learn more about Podman Quadlet, see [systemd units using Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html).
 This setup installs the quadlets in `~/.config/containers/systemd/`, the directory for rootless quadlets, and uses the rootless images.
 If you install them in a rootful directory such as `/etc/containers/systemd/`, use the rootful images instead.
 ## Basics
 Since Podman v6.0 a single `gitea.quadlets` file can hold multiple quadlets separated by the `---` delimiter.
 Paste the following content into a file named `gitea.quadlets`
 ```ini
 # FileName=gitea-data
 [Volume]
 VolumeName=gitea-data
 ---
 # FileName=gitea-config
 [Volume]
 VolumeName=gitea-config
 ---
 # FileName=gitea
 [Container]
 PublishPort=2222:2222
 PublishPort=3000:3000
 Image=docker.gitea.com/gitea:@dockerVersion@-rootless
 ContainerName=gitea
 Mount=type=volume,src=gitea-data.volume,destination=/var/lib/gitea
 Mount=type=volume,src=gitea-config.volume,destination=/etc/gitea
 [Service]
 Restart=always
 [Install]
 # Start with the user session
 WantedBy=default.target
 ```
 You can run the installation command
 ```sh
 $ podman quadlet install ./gitea.quadlets --application=gitea
 /home/user/.config/containers/systemd/gitea/gitea-data.volume
 /home/user/.config/containers/systemd/gitea/gitea-config.volume
 /home/user/.config/containers/systemd/gitea/gitea.container
 ```
 The `--application=gitea` flag allows us to tell podman to group the quadlets together, this can help for managing and organizing the quadlets files.
 You can validate the quadlets are properly installed by looking at the list command
 ```sh
 $ podman quadlet list
 NAME                 UNIT NAME                    PATH ON DISK                                                     STATUS         APPLICATION  POD
 gitea-config.volume  gitea-config-volume.service  /home/user/.config/containers/systemd/gitea/gitea-config.volume  active/exited  gitea
 gitea-data.volume    gitea-data-volume.service    /home/user/.config/containers/systemd/gitea/gitea-data.volume    active/exited  gitea
 gitea.container      gitea.service                /home/user/.config/containers/systemd/gitea/gitea.container      failed/failed  gitea
 ```
 You can start the application by running `systemctl --user start gitea` command.
 `WantedBy=default.target` starts the service when the user session starts.
 Rootless user services do not run without a session, so to start Gitea at boot, enable lingering for the user with `loginctl enable-linger $USER`.
 ## Databases
 ### PostgreSQL database
 To start Gitea in combination with a PostgreSQL database, apply these changes to the
 `gitea.quadlets` file created above.
 To start Gitea with a database, we need to create a network, so the database and Gitea container can communicate.
 ```diff
 # FileName=gitea-data
 [Volume]
 VolumeName=gitea-data
 ---
 # FileName=gitea-config
 [Volume]
 VolumeName=gitea-config
 ---
 + # FileName=gitea-postgres-data
 + [Volume]
 + VolumeName=gitea-postgres-data
 + ---
 + # FileName=gitea
 + [Network]
 + NetworkName=gitea
 + ---
 + # FileName=gitea-postgres
 + [Container]
 + Image=docker.io/library/postgres:18
 + ContainerName=gitea-postgres
 + Network=gitea.network
 + Mount=type=volume,src=gitea-postgres-data.volume,destination=/var/lib/postgresql
 + Environment=POSTGRES_USER=gitea
 + Environment=POSTGRES_PASSWORD=gitea
 + Environment=POSTGRES_DB=gitea
 +
 + [Service]
 + Restart=always
 +
 + [Install]
 + # Start with the user session
 + WantedBy=default.target
 + ---
 # FileName=gitea
 + [Unit]
 + Requires=gitea-postgres.service
 + After=gitea-postgres.service
 +
 [Container]
 PublishPort=2222:2222
 PublishPort=3000:3000
 Image=docker.gitea.com/gitea:@dockerVersion@-rootless
 ContainerName=gitea
 Mount=type=volume,src=gitea-data.volume,destination=/var/lib/gitea
 Mount=type=volume,src=gitea-config.volume,destination=/etc/gitea
 + Network=gitea.network
 + Environment=GITEA__database__DB_TYPE=postgres
 + Environment=GITEA__database__HOST=gitea-postgres:5432
 + Environment=GITEA__database__NAME=gitea
 + Environment=GITEA__database__USER=gitea
 + Environment=GITEA__database__PASSWD=gitea
 [Service]
 Restart=always
 [Install]
 # Start with the user session
 WantedBy=default.target
 ```
 ## Logs
 As systemd manages the container we can use `journalctl` to access the logs
 ```sh
 $ journalctl --user --follow --unit=gitea.service
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:263:runWeb() [I] Starting Gitea on PID: 2
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:115:showWebStartupMessage() [I] Gitea version: 1.27.3 built with go1.26.7-X:jsonv2 : bindata, timetzdata,
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:116:showWebStartupMessage() [I] * RunMode: prod
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:117:showWebStartupMessage() [I] * AppPath: /usr/local/bin/gitea
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:118:showWebStartupMessage() [I] * WorkPath: /var/lib/gitea
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:119:showWebStartupMessage() [I] * CustomPath: /var/lib/gitea/custom
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:120:showWebStartupMessage() [I] * ConfigFile: /etc/gitea/app.ini
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:121:showWebStartupMessage() [I] Prepare to run install page
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:329:listen() [I] Listen: http://0.0.0.0:3000
 gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:333:listen() [I] AppURL(ROOT_URL): http://localhost:3000/
 gitea[5967]: 2026/09/03 14:50:42 modules/graceful/server.go:52:NewServer() [I] Starting new Web server: tcp:0.0.0.0:3000 on PID: 2
 ```
@@ -10,13 +10,13 @@ aliases:
 # Protected branches
-Protected branches prevent unwanted changes by enforcing push, deletion, and merge policies on selected branches. The rules are enforced for every Git protocol (HTTP(S), SSH), the web editor, the API, and background jobs such as auto-merge. Only repository owners and administrators can manage the rules, and the Branches page is read-only while a repository is archived.
+Protected branches prevent unwanted changes by enforcing push and merge policies on selected branches. The rules are enforced for every Git protocol (HTTP(S), SSH), the web editor, the API, and background jobs such as auto-merge. Only repository owners and administrators can manage the rules, and the Branches page is read-only while a repository is archived.
 ## Creating or editing a rule
 1. Open the repository and select **Settings → Branches** (repository admin permission required).
 2. Select **Add new rule** or **Edit** next to an existing rule.
-3. Fill in the **Protected branch name pattern** and optional file patterns, then configure the push, deletion, merge, and review options described below.
+3. Fill in the **Protected branch name pattern** and optional file patterns, then configure the push, merge, and review options described below.
 4. Select **Save rule**.
 The rule immediately applies to all matching branches, even if the branches are created in the future.
@@ -48,9 +48,7 @@ The **Push** section controls direct pushes (including the web editor and API).
 - **Disable push** makes the branch read-only. Any attempt to push directly fails, and changes must be merged through pull requests.
 - **Enable push** allows anyone with [write access](./permissions.md) to push (force pushes are still blocked unless explicitly allowed).
- **Allowlist restricted push** requires being on the allowlist. Choose users and, for organization-owned repositories, teams.
+- **Allowlist restricted push** requires being on the allowlist. Choose users and, for organization-owned repositories, teams. Deploy keys that already have write access can also be allowlisted.
 The user allowlists for push, force-push and deletion can include the **Gitea Actions** and **Deploy Key** system users. They still require write access; **Deploy Key** also covers deploy tokens.
 When a push is blocked, the server-side hook rejects the update with an explanation.
@@ -60,17 +58,7 @@ Force pushes have their own set of options:
 - **Disable force push** completely forbids rewriting history on the branch.
 - **Enable force push** allows anyone who can push to also force push.
- **Allowlist restricted force push** limits force pushes to a separate allowlist of users or teams **and** requires regular push access.
+- **Allowlist restricted force push** limits force pushes to a separate allowlist (users, teams, and optionally deploy keys) **and** requires the person to already have regular push access.
 ## Branch deletion
 The **Branch Deletion** section controls whether matching protected branches can be deleted:
 - **Disable branch deletion** prevents deletion. This is the default.
 - **Enable branch deletion** allows anyone who can push to delete the branch.
 - **Allowlist restricted branch deletion** limits deletion to a separate allowlist of users or teams **and** requires regular push access.
 These rules apply to Git (`git push --delete`), the API, the web interface and post-merge cleanup. The default branch and configured default pull request target branch cannot be deleted.
 ## Pull request merges and approvals
@@ -1,31 +0,0 @@
 ---
 date: "2026-08-30T00:00:00+02:00"
 slug: "artifacts"
 sidebar_position: 70
 ---
 # Artifacts
 Workflow runs can store files such as test results, coverage reports, and build output as artifacts. Artifacts are uploaded by workflows, for example with [`actions/upload-artifact`](https://github.com/actions/upload-artifact), and appear on the run page after the upload completes.
 ## Previewing artifacts
 Select an artifact on the run page to open its file browser and preview in the same tab. The preview identifies the originating run and attempt, and provides links back to that run and to download the complete artifact. Selecting files in the browser updates the preview in the same tab.
 Artifact previews:
 - require sign-in and access to the Actions run to open the preview page
 - render text-based files, images (including SVG), and PDFs
 - run HTML and JavaScript content in a sandboxed frame
 Preview content is loaded through signed URLs that expire after one hour and do not require a session cookie. Reopen the preview page to obtain a fresh URL after it expires.
 The file browser lists up to 2,000 files per artifact. Larger artifacts show a notice when the list is truncated.
 Unsupported or oversized files can still be downloaded with the complete artifact.
 ## Instance configuration
 Site administrators can limit the total artifact size that can be browsed or previewed with `ARTIFACT_PREVIEW_MAX_SIZE` in the `[actions]` section of `app.ini`. The default is 10 MiB. Set it to `0` to disable previews or `-1` to allow artifacts of any size.
 The size of an individual previewed file is also limited by [`MAX_DISPLAY_FILE_SIZE`](../../administration/config-cheat-sheet.md#ui-ui) in the `[ui]` section.
@@ -6,94 +6,104 @@ sidebar_position: 120
 # Compared to GitHub Actions
-Gitea Actions is designed to be compatible with GitHub Actions, with the differences below.
+Even though Gitea Actions is designed to be compatible with GitHub Actions, there are some differences between them.
 ## Additional features
 ### Absolute action URLs
-`uses:` accepts an absolute URL to any git host, e.g. `uses: https://gitea.com/actions/checkout@v4`.
+Gitea Actions supports defining actions via absolute URL, which means that you can use actions from any git repository.
-
+Like `uses: https://github.com/actions/checkout@v4` or `uses: http://your_gitea.com/owner/repo@branch`.
 ### Action prefixes
 `uses:` accepts these prefixes:
 - `self:` references your own Gitea instance, e.g. `uses: self:owner/repo@v1` or `uses: self:owner/repo/.gitea/workflows/build.yml@v1`
 - `builtin:` runs an action built into Gitea Runner, which needs no download and no Node in the job image, e.g. `uses: builtin:checkout`
 `builtin:checkout` accepts the `repository`, `ref`, `token`, `path` and `fetch-depth` inputs of `actions/checkout` with the same defaults, and fails on any other input.
 ### Workflow-relative actions
 `$/` references the repository and commit of the workflow, or of the enclosing composite action, e.g. `uses: $/.gitea/actions/build`.
 Unlike `./`, it needs no checkout first.
 ### Actions written in Go
 Gitea Actions supports writing actions in Go.
 See [Creating Go Actions](https://blog.gitea.com/creating-go-actions/).
 ### Support the non-standard syntax @yearly, @monthly, @weekly, @daily, @hourly on schedule
-`schedule` also accepts `@yearly`, `@monthly`, `@weekly`, `@daily` and `@hourly`, which [GitHub does not](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).
+Github Actions doesn't support that. https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
 ## Unsupported workflows syntax
 ### `jobs.<job_id>.environment`
-[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment) is ignored.
+See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment).
 It's ignored by Gitea Actions now.
 ### Complex `runs-on`
-[`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) supports:
+See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
 Gitea Actions supports:
 - Static strings: `runs-on: self-hosted`
 - Arrays of labels: `runs-on: [linux, self-hosted]`
 - String expressions: `runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
 - Arrays containing expressions: `runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
 ## Missing features
 ### Package repository authorization
-`GITEA_TOKEN` cannot publish to the package registry of its repository, e.g. to push OCI images.
+The `GITEA_TOKEN` for a job running within a repository should be able to publish to the associated package repository (i.e. to upload OCI images). See the "packages" scope for the "default access" in [Automatic token authentication](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token).
-Use a personal access token instead, see [this issue](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692).
+
 This is not implemented in Gitea Actions now. A workaround for Gitea Actions is to use a Personal Access Token (PAT). See this [github issue and comment](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692) for tracking this feature.
 ### Problem Matchers
-[Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md) are ignored.
+Problem Matchers are a way to scan the output of actions for a specified regex pattern and surface that information prominently in the UI.
 See [Problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md).
 It's ignored by Gitea Actions now.
 ### Create an error annotation
-[Error annotations](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error) are ignored.
+See [Creating an annotation for an error](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)
 It's ignored by Gitea Actions now.
 ### Expressions
-[Expressions](https://docs.github.com/en/actions/learn-github-actions/expressions) support the standard GitHub functions and contexts.
+For [expressions](https://docs.github.com/en/actions/learn-github-actions/expressions), Gitea Actions supports standard GitHub functions (e.g. `success()`, `failure()`, `always()`, `cancelled()`, `format()`, `toJSON()`) and context variables (like `github`, `matrix`, `vars`, `env`).
 ## Missing UI features
 ### Pre and Post steps
-Pre and post steps have no section of their own in the job log.
+Pre and Post steps don't have their own section in the job log user interface.
 ### Services steps
-Service steps have no section of their own in the job log.
+Services steps don't have their own section in the job log user interface.
 ## Different behavior
 ### Job token permissions (`permissions`)
-`permissions` and `jobs.<job_id>.permissions` control the `GITEA_TOKEN` permissions, clamped by the repository and owner settings and further restricted for fork pull requests and cross-repository access.
+Gitea supports `permissions` and `jobs.<job_id>.permissions` to control the default `GITEA_TOKEN` permissions.
-GitHub-only scopes like `statuses`, `checks`, `deployments`, `security-events` and `pages` are not supported, while Gitea adds `code`, `releases`, `wiki` and `projects`. `id-token` works like on GitHub, see [OpenID Connect](openid-connect.md).
+
 The effective permissions are clamped by the repository/owner settings and are further restricted for fork pull requests and cross-repository access.
 GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not supported, while Gitea-specific scopes such as `code`, `releases`, `wiki`, and `projects` are available.
 See [Actions job token permissions](token-permissions.md).
 ### Downloading actions
-Actions without a host, like `uses: actions/checkout@v4`, are downloaded from `https://github.com`, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`.
+Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.
-See the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
+We have since restricted this option to only allow two values (`github` and `self`).
-For other sources, see [Absolute action URLs](#absolute-action-urls), [Action prefixes](#action-prefixes) and [Workflow-relative actions](#workflow-relative-actions).
+When set to `github`, the new default, Gitea will download non-fully-qualified actions from `https://github.com`.
 For example, if you use `uses: actions/checkout@v4`, it will download the checkout repository from `https://github.com/actions/checkout.git`.
 If you want to download an action from another git hoster, you can use an absolute URL, e.g. `uses: https://gitea.com/actions/checkout@v4`.
 If your Gitea instance is in an intranet or a restricted area, you can set the URL to `self` to only download actions from your own instance by default.
 Of course, you can still use absolute URLs in workflows.
 More details about the `[actions].DEFAULT_ACTIONS_URL` configuration can be found in the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions)。
 ### Context availability
-[Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability) is not checked, so contexts like `env` work in more places.
+Context availability is not checked, so you can use the env context on more places.
 See [Context availability](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability).
@@ -19,7 +19,7 @@ Additionally, the runner will introduce itself to Gitea and declare what kind of
 Earlier, we mentioned that `runs-on: ubuntu-latest` in a workflow file means that the job will be run on a runner with the `ubuntu-latest` label.
 But how does the runner know to run `ubuntu-latest`? The answer lies in mapping the label to an environment.
-That's why each label of a runner names an environment, like `my_custom_label:docker://centos:7`.
+That's why when you add custom labels during registration, you will need to input some complex content like `my_custom_label:docker://centos:7`.
 This means that the runner can take the job which needs to run on `my_custom_label`, and it will run it via a docker container with the image `centos:7`.
 Docker isn't the only option, though.
@@ -34,6 +34,7 @@ So,
 - `my_custom_label:docker://node:18`: Run jobs labeled with `my_custom_label` using the `node:18` Docker image.
 - `my_custom_label:host`: Run jobs labeled with `my_custom_label` directly on the host.
 - `my_custom_label`: Same as `my_custom_label:host`.
 - `my_custom_label:vm:ubuntu-latest`: (Example only, not implemented) Run jobs labeled with `my_custom_label` using a virtual machine with the `ubuntu-latest` ISO.
 ## Communication protocol
@@ -42,7 +43,7 @@ However, we did not think it was a good idea to have Gitea listen on a new port.
 Instead, we wanted to reuse the HTTP port, which means we needed a protocol that is compatible with HTTP.
 We chose to use gRPC over HTTP.
-The protocol is defined in [actions-proto-def](https://gitea.com/gitea/actions-proto-def), its Go code lives in [actionslib](https://gitea.com/gitea/actionslib).
+We use [actions-proto-def](https://gitea.com/gitea/actions-proto-def) and [actions-proto-go](https://gitea.com/gitea/actions-proto-go) to wire them up.
 More information about gRPC can be found on [its website](https://grpc.io/).
 ## Network architecture
@@ -70,8 +71,7 @@ However, if a job container tries to fetch code from localhost, it will fail bec
 ### Connection 3, runner to internet
 When you use some actions like `actions/checkout@v4`, the runner downloads the scripts, not the job containers.
-By default, it downloads them from [github.com](https://github.com/), which requires internet access.
+By default, it downloads from [github.com](http://github.com/), so it requires access to the internet. If you configure the `DEFAULT_ACTIONS_URL` to `self`, then it will download from your Gitea instance by default. Then it will not connect to internet when downloading the action itself.
 With `DEFAULT_ACTIONS_URL` set to `self`, or with `uses: self:owner/repo@ref`, it downloads them from your Gitea instance instead.
 It also downloads some docker images from Docker Hub by default, which also requires internet access.
 However, internet access is not strictly necessary.
@@ -27,24 +27,50 @@ Still, this is completely optional since both options have the same effect at th
 ## Where will the runner download scripts when using actions such as `actions/checkout@v4`?
-From `https://github.com` by default, or from your own instance when `[actions].DEFAULT_ACTIONS_URL` is `self`, see the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
+There are tens of thousands of [actions scripts](https://github.com/marketplace?type=actions) in GitHub, and when you write `uses: actions/checkout@v4`, it downloads the scripts from [github.com/actions/checkout](http://github.com/actions/checkout) by default.
 But what if you want to use actions from other places such as gitea.com instead of GitHub?
-To use an action from elsewhere, name its host:
+The good news is that you can specify the URL prefix to use actions from anywhere.
 This is an extra syntax in Gitea Actions.
 For example:
- `uses: https://gitea.com/owner/repo@ref`
+- `uses: https://gitea.com/xxx/xxx@xxx`
- `uses: http://your_gitea_instance.com/owner/repo@ref`
+- `uses: https://github.com/xxx/xxx@xxx`
- `uses: self:owner/repo@ref` for your own Gitea instance
+- `uses: http://your_gitea_instance.com/xxx@xxx`
 Be careful, the `https://` or `http://` prefix is necessary!
 This is one of the differences from GitHub Actions which supports actions scripts only from GitHub.
 But it should allow users much more flexibility in how they run Actions.
 Alternatively, if you want your runners to download actions from your own Gitea instance by default, you can configure it by setting `[actions].DEFAULT_ACTIONS_URL`.
 See [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
 ## How to limit the permission of the runners?
-Runners only connect to your Gitea instance.
+Runners have no more permissions than simply connecting to your Gitea instance.
-For each job, a runner gets a `GITEA_TOKEN` limited to the job's repository, see [Actions job token permissions](token-permissions.md).
+When any runner receives a job to run, it will temporarily gain limited permission to the repository associated with the job.
-To give a job access to more private repositories or external systems, pass it [secrets](usage/actions/secrets.md).
+If you want to give more permissions to the runner, allowing it to access more private repositories or external systems, you can pass [secrets](usage/actions/secrets.md) to it.
 Refined permission control to Actions is a complicated job.
 In the future, we will add more options to Gitea to make it more configurable, such as allowing more write access to repositories or read access to all repositories in the same organization.
 ## Which operating systems are supported by Gitea Runner?
-Official binaries are released for Linux, macOS and Windows.
+We released official binaries for Linux, macOS, and Windows.
-Other systems supported by Go and Docker work in theory.
+While other operating systems are theoretically supported if it is supported by golang and docker(docker mode enabled).
 One thing to note is that if you choose to run jobs directly on the host instead of in job containers, the environmental differences between operating systems may cause unexpected failures.
 For example, bash is not available on Windows in most cases, while act tries to use bash to run scripts by default.
 Therefore, you need to specify `powershell` as the default shell in your workflow file, see [defaults.run](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun).
 ```yaml
 defaults:
  run:
    shell: powershell
 ```
 ## How to avoid being hacked?
@@ -73,13 +99,42 @@ It is exciting to be able to reuse them.
 ## What if it runs on multiple labels, such as `runs-on: [label_a, label_b]`?
-The job runs on a runner that has all of the labels, as on [GitHub](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
+This is valid syntax.
-The runner uses the environment of the first label it has.
+It means that it should run on runners that have both the `label_a` **and** `label_b` labels, see [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on).
 Unfortunately, the runner does not work this way until v0.2.11.
 As mentioned, we map labels to environments:
 - `ubuntu` → `ubuntu:22.04`
 - `centos` → `centos:8`
 But we need to map label groups to environments instead, like so:
 - `[ubuntu]` → `ubuntu:22.04`
 - `[with-gpu]` → `linux:with-gpu`
 - `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
 We also need to re-design how tasks are assigned to runners.
 A runner with `ubuntu`, `centos`, or `with-gpu` does not necessarily indicate that it can accept jobs with `[centos, with-gpu]`.
 Therefore, the runner should inform the Gitea instance that it can only accept jobs with `[ubuntu]`, `[centos]`, `[with-gpu]`, and `[ubuntu, with-gpu]`.
 This is not a technical problem, it was just overlooked in the early design.
 See [runtime.go#L65](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65).
 Currently, the runner attempts to match everyone in the labels and uses the first match it finds.
 ## What is the difference between agent labels and custom labels for a runner?
-Gitea no longer has custom labels.
+![labels](/images/usage/actions/labels.png)
-A runner declares its labels every time it starts, from its `runner.labels` configuration or the labels given at registration, so change them there and restart the runner.
+
 Agent labels are reported to the Gitea instance by the runner during registration.
 Custom labels, on the other hand, are added manually by a Gitea administrator or owners of the organization or repository (depending on the level of the runner).
 However, the design here needs improvement, as it currently has some rough edges.
 You can add a custom label such as `centos` to a registered runner, which means the runner will receive jobs with `runs-on: centos`.
 However, the runner may not know which environment to use for this label, resulting in it using a default image or leading to a logical dead end.
 This default may not match user expectations.
 See [runtime.go#L71](https://gitea.com/gitea/runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71).
 In the meantime, we suggest that you re-register your runner if you want to change its labels.
 ## Will there be more implementations for Gitea Actions runner?
@@ -122,6 +177,3 @@ For events supported only by GitHub, see GitHub's [documentation](https://docs.g
 Go to the repository's **Settings** > **Actions** > **General** page and add collaborative owners.
 The private repositories of collaborative owners are allowed to access the actions and workflows in the current repository.
 To share within the same user or organization, add the private repositories under its **Settings** > **Actions** > **General** > **Cross-Repository Access** instead.
 See [Cross-repository access](token-permissions.md#cross-repository-access).
@@ -1,60 +0,0 @@
 ---
 date: "2026-08-23T00:00:00+00:00"
 slug: "openid-connect"
 sidebar_position: 40
 ---
 # OpenID Connect
 Jobs can request short-lived OpenID Connect (OIDC) tokens to sign in to cloud providers and other services without storing long-lived secrets. The tokens use the GitHub Actions format, so actions like `aws-actions/configure-aws-credentials`, `google-github-actions/auth` and `azure/login` work unchanged.
 ## Trusting Gitea
 Add Gitea as an OIDC identity provider in the service:
 - Issuer: `<ROOT_URL>/api/actions/oidc`
 - Audience: `<ROOT_URL>/<owner>`, unless the workflow requests another one
 Then limit which workflows can sign in with a condition on the [`sub` claim](#claims).
 Gitea signs the tokens with a key it creates at `<APP_DATA_PATH>/jwt/actions_oidc.pem`. Instances behind a load balancer must share this file.
 ## Requesting a token
 Grant the `id-token` permission to the workflow or job:
 ```yaml
 permissions:
  id-token: write
 ```
 Default permissions never include it, and jobs from fork pull requests never get it. Owners and repositories can disable it with their [maximum token permissions](token-permissions.md#maximum-token-permissions-clamping).
 Actions like the ones above request the token themselves. In a script, use `ACTIONS_ID_TOKEN_REQUEST_URL` and `ACTIONS_ID_TOKEN_REQUEST_TOKEN`:
 ```shell
 curl --fail --silent --show-error \
  --header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
  "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service"
 ```
 The token is in the `value` field of the response and expires after five minutes.
 ## Claims
 The `sub` claim names the owner and repository with their IDs, so a renamed or recreated repository cannot match an existing trust policy:
 ```text
 repo:<owner>@<owner-id>/<repo>@<repo-id>:ref:<ref>
 repo:<owner>@<owner-id>/<repo>@<repo-id>:pull_request
 ```
 The `pull_request` event uses the second form, all other events use the first, including `pull_request_target`.
 The other claims match GitHub's, like `repository`, `ref`, `sha`, `workflow_ref` and `job_workflow_ref`. The discovery document at `<ROOT_URL>/api/actions/oidc/.well-known/openid-configuration` lists them all.
 Differences from GitHub Actions:
 - There is no `environment` claim.
 - Pull request runs use `refs/pull/<index>/head` and its commit, not the merge ref and merge commit.
 - `run_number` counts runs per repository, not per workflow.
@@ -40,7 +40,7 @@ However, it is recommended to use Docker to run the jobs, because it is more sec
 Before running a runner, you should first register it to your Gitea instance using the following command:
 ```bash
-gitea-runner register --no-interactive --instance <instance> --token <token>
+./runner register --no-interactive --instance <instance> --token <token>
 ```
 There are two arguments required, `instance` and `token`.
@@ -69,7 +69,7 @@ If this file is missing or corrupted, you can simply remove it and register agai
 Finally, it's time to start the runner:
 ```bash
-gitea-runner daemon
+./runner daemon
 ```
 And you can see the new runner in the management page:
@@ -102,8 +102,8 @@ Only a workflow that runs on an event that posts a commit status (`push`, `pull_
 Scoped workflows can call reusable workflows:
- A **local** reference (`uses: ./...` or `uses: $/...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
+- A **local** reference (`uses: ./...`) resolves against the **source** repository: the repository the calling workflow's content came from, not the consuming repository.
- A **cross-repository** reference (`uses: owner/repo/...@ref` or `uses: self:owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
+- A **cross-repository** reference (`uses: owner/repo/...@ref`) is resolved with the **consuming repository's** read permission. If it points to a private repository, make sure every consuming repository can read it; otherwise the workflow will fail there.
 A reusable workflow can live under `SCOPED_WORKFLOW_DIRS` (or `WORKFLOW_DIRS`) of the source repository.
@@ -53,14 +53,13 @@ Valid access mode values for each scope are `read`, `write`, and `none`.
 - `wiki`
 - `projects`
 - `packages` (if supported by the target feature)
 - `id-token` (`write` allows requesting [OpenID Connect tokens](openid-connect.md), `read` grants nothing)
 If you specify both `contents` and a more granular scope (like `code` or `releases`), the granular scope wins for that unit.
 ### Compatibility notes
 Gitea supports a subset of GitHub Actions permission scopes.
-GitHub-only scopes such as `statuses`, `checks`, `deployments`, `security-events`, and `pages` are not currently supported by Gitea Actions.
+GitHub-only scopes such as `statuses`, `checks`, `deployments`, `id-token`, `security-events`, and `pages` are not currently supported by Gitea Actions.
 Gitea also exposes repository-unit scopes that do not exist as separate scopes in GitHub Actions:
@@ -76,18 +75,15 @@ If neither the workflow nor the job defines `permissions:`, Gitea uses the confi
 - **Permissive**: read and write permissions for most units in the job's repository (backwards-compatible default).
 - **Restricted**: read-only permissions for `code`, `releases`, and `packages` in the job's repository, and no access to other units by default.
 Neither mode includes `id-token`.
 ## Maximum token permissions (clamping)
-You can configure a maximum permission per repository unit and for `id-token`.
+You can configure a maximum permission per repository unit.
 The job's effective permissions are computed as:
 `effective = min(requested, maximum)`
 This means workflows can reduce permissions for a job, but cannot exceed your configured maximum.
 If you don't configure a maximum, the maximum defaults to `write` for all scopes.
 Maximums saved before Gitea supported `id-token` deny it until you set it to `write`.
 ## Where to configure
@@ -99,13 +95,9 @@ You can configure defaults and maximums at:
 Note: Repository-level token permission settings are only shown once **Repository Actions** are enabled.
 ## Protected branches
 Actions job tokens must have code write permission and satisfy [branch protection rules](../access-control/protected-branches.md), including any **Gitea Actions** allowlist requirements.
 ## Fork pull requests
-For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings. They also get no OpenID Connect tokens.
+For security reasons, workflows triggered by pull requests from forks are always restricted to read-only permissions for repository contents, regardless of workflow `permissions:` or settings.
 ## Cross-repository access
@@ -64,8 +64,8 @@ These are used internally by the runner and actions. They are typically not need
 | Name | Description | Example |
 |---|---|---|
 | `ACTIONS_CACHE_URL` | URL for the actions cache service. | `http://192.168.1.10:8088/` |
-| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when `id-token: write` is granted. | `***` |
+| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Token for OIDC requests. Only set when configured. | `***` |
-| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when `id-token: write` is granted. | `https://gitea.com/api/actions/oidc/token?` |
+| `ACTIONS_ID_TOKEN_REQUEST_URL` | URL to request OIDC tokens. Only set when configured. | `https://gitea.com/login/oauth/access_token` |
 | `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.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/` |
@@ -15,7 +15,7 @@ creating issues and pull requests. This will cut down on the initial back and fo
 of getting some clarifying details.
 It is currently not possible to provide generic issue/pull-request templates globally.
-Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one. See [Pre-filling Issues and Pull Requests](prefill-issues-pull-requests.md) for all parameters.
+Additionally, the New Issue page URL can be suffixed with `?title=Issue+Title&body=Issue+Text` and the form will be populated with those strings. Those strings will be used instead of the template if there is one.
 ## File names
@@ -1,42 +0,0 @@
 ---
 date: "2026-10-17T00:00:00+00:00"
 slug: "prefill-issues-pull-requests"
 sidebar_position: 14
 ---
 # Pre-filling Issues and Pull Requests
 Links to the pages for creating issues and pull requests can pre-fill the form with query parameters.
 This lets you link users from another app, a README or a project board to a form that is already categorized.
 - New issue: `/{owner}/{repo}/issues/new?…`
 - New pull request: `/{owner}/{repo}/compare/{base}...{head}?…`
 For example, this link opens a new issue with a title, two labels and an assignee:
 ```
 https://gitea.example.com/owner/repo/issues/new?title=Dashboard+crashes&label=kind/bug,area/dashboard&assignee=alice
 ```
 ## Parameters
 | Parameter     | Value                                                                       |
 | ------------- | --------------------------------------------------------------------------- |
 | `title`       | Title                                                                       |
 | `body`        | Description                                                                 |
 | `label`       | Comma-separated label IDs or names                                          |
 | `labels`      | Alias of `label`                                                            |
 | `milestone`   | Milestone ID or name                                                        |
 | `project`     | Comma-separated project IDs or titles                                       |
 | `assignee`    | Comma-separated user IDs or usernames                                       |
 | `template`    | File name of the [template](issue-pull-request-templates.md) to use         |
 | `field:<id>`  | Value of the field with this `id` in a YAML template                        |
 IDs and names can be mixed and names are matched case-insensitively. Values that don't match anything in the repository are ignored.
 Labels include the organization's labels, and closed milestones and projects can be selected too.
 Milestones and projects are only offered to users who can write to issues or pull requests, so for other users these parameters have no effect.
 The values from the link take precedence over the title, description, labels and assignees of the template.
 When there are several issue templates to choose from, the parameters are passed through to the chosen one.
 On the compare page, any of these parameters also opens the pull request form directly, as `expand=1` does.
@@ -1,64 +0,0 @@
 ---
 date: "2018-06-24:00:00+02:00"
 slug: "api-usage"
 sidebar_position: 40
 aliases:
  - /zh-cn/api-usage
 ---
 # API 使用指南
 ## 开启/配置 API 访问
 通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。
 <a id="authentication"></a>
 ## 通过 API 认证
 Gitea 支持以下几种 API 认证方式：
 - HTTP basic authentication 方式
 - 通过指定 `token=...` URL 查询参数方式
 - 通过指定 `access_token=...` URL 查询参数方式
 - 通过指定 `Authorization: token ...` HTTP header 方式
 以上提及的认证方法接受相同的 apiKey token 类型，您可以在编码时通过查阅代码更好地理解这一点。
 Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。
 您可以通过您的 gitea web 界面来创建 apiKey token：
 `Settings | Applications | Generate New Token`.
 ### 关于 `Authorization:` header
 由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 `token`，类似于如下形式：
 ```
 Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
 ```
 以 `curl` 命令为例，它会以如下形式携带在请求中：
 ```
 curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
    -H "accept: application/json" \
    -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
    -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
 ```
 正如上例所示，您也可以在 GET 请求中使用同一个 token 并以 `token=` 的查询参数形式携带 token 来进行认证。
 ## 通过 API 列出您发布的令牌
 `/users/:name/tokens` 是一个特殊的接口，需要您使用 basic authentication 进行认证，具体原因在 issue 中
 [#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及，使用方法如下所示：
 ### 使用 Basic authentication 认证
 ```
 $ curl --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
 [{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
 ```
 ## 使用 Sudo 方式请求 API
 此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。
@@ -1,218 +0,0 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "install-from-source"
 sidebar_position: 30
 aliases:
  - /zh-cn/install-from-source
 ---
 # 使用源代码安装
 你需要 [安装 Go](https://golang.google.cn/doc/install) 并正确设置 Go 环境。特别的，建议设置`$GOPATH`环境变量，并将 Go 的二进制目录或目录`${GOPATH//://bin:}/bin`添加到`$PATH`中。请参阅 Go 百科上关于 [GOPATH](https://github.com/golang/go/wiki/GOPATH) 的词条。
 接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。
 **注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md) 中给出的建议。
 ## 下载
 首先，我们需要获取源码。由于引入了 Go 模块，最简单的方法是直接使用 Git，因为我们不再需要在 GOPATH 内构建 Gitea。
 ```bash
 git clone https://github.com/go-gitea/gitea
 ```
 （之前的版本中建议使用 `go get`，但现在不再需要。）
 你可以选择编译和安装的版本，当前有多个选择。`main` 分支代表当前的开发版本。如果你想编译 `main` 版本，你可以直接跳到 [构建](#构建) 部分。
 如果你想编译带有标签的发行版本，可以使用以下命令签出：
 ```bash
 git branch -a
 git checkout @sourceBranch@
 ```
 要验证一个拉取请求（Pull Request, PR），要先启用新的分支（其中 `xyz` 是 PR 的 ID；例如，对于 [#2663](https://github.com/go-gitea/gitea/pull/2663)，ID 是 `2663 `）：
 ```bash
 git fetch origin pull/xyz/head:pr-xyz
 ```
 要以指定发行版本（如 @sourceVersion@ ）的源代码来构建 Gitea，可执行以下命令列出可用的版本并选择某个版本签出。
 使用以下命令列出可用的版本：
 ```bash
 git tag -l
 git checkout @sourceVersion@  # or git checkout pr-xyz
 ```
 ## 构建
 要从源代码进行构建，系统必须预先安装以下程序：
 - `go` @minGoVersion@ 或更高版本，请参阅 [这里](https://go.dev/dl/)
 - `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/)
 - `make`, 请参阅 [这里](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)
 为了尽可能简化编译过程，提供了各种 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。
 根据你的构建需求，以下 tags 可以使用：
 - `bindata`: 构建一个单一的整体二进制文件，包含所有资源。适用于构建生产环境版本。
 - `sqlite sqlite_unlock_notify`: 启用对 [SQLite3](https://sqlite.org/) 数据库的支持。仅建议在少数人使用时使用这个模式。
 - `pam`: 启用对 PAM（ Linux 可插拔认证模块）的支持。可用于对本地用户进行身份验证或扩展身份验证到 PAM 可用的方法。
 - `gogit`：（实验性功能）使用 go-git 变体的 Git 命令。
 将所有资源（JS/CSS/模板等）打包到二进制文件中。在生产环境部署时，使用`bindata`构建标签是必需的。在开发/测试 Gitea 或能够明确分离资源时，可以不用`bindata`。
 要包含所有资源，请使用 `bindata` 标签：
 ```bash
 TAGS="bindata" make build
 ```
 在我们的持续集成系统的默认发行版中，构建标签为：`TAGS="bindata sqlite sqlite_unlock_notify"`。因此，从源码构建的最简单、推荐方式是：
 ```bash
 TAGS="bindata sqlite sqlite_unlock_notify" make build
 ```
 `build`目标分为两个子目标：
 - `make backend` 需要 [Go @minGoVersion@](https://golang.google.cn/doc/install) 或更高版本。
 - `make frontend` 需要 [Node.js @minNodeVersion@](https://nodejs.org/zh-cn/download/) 或更高版本。
 如果存在预构建的前端文件，可以仅构建后端：
 ```bash
 TAGS="bindata" make backend
 ```
 ## 测试
 按照上述步骤完成后，工作目录中将会有一个`gitea`二进制文件。可以从该目录进行测试，或将其移动到带有测试数据的目录中。当手动从命令行启动 Gitea 时，可以通过按下`Ctrl + C`来停止程序。
 ```bash
 ./gitea web
 ```
 ## 更改默认路径
 Gitea 将从`CustomPath`中查找许多信息。默认的，这会在运行 Gitea 时当前工作目录下的`custom/`目录中（译者案：即`$PATH_TO_YOUR_GITEA$/custom/`）。它还将在`$(CustomPath)/conf/app.ini`中查找其配置文件`CustomConf`，并将当前工作目录用作一些可配置值的相对基本路径`AppWorkPath`。最后，静态文件将从默认为 `AppWorkPath`的`StaticRootPath`提供。
 尽管在开发时这些值很有用，但可能与下游用户的偏好冲突。
 一种选择是使用脚本文件来隐藏`gitea`二进制文件，并在运行 Gitea 之前创建适当的环境。然而，在构建时，可以使用`make`的`LDFLAGS`环境变量来更改这些默认值。适当的设置如下：
 - 要设置`CustomPath`，请使用`LDFLAGS="-X \"code.gitea.io/gitea/modules/setting.CustomPath=custom-path\""`
 - 对于`CustomConf`，应该使用`-X \"code.gitea.io/gitea/modules/setting.CustomConf=conf.ini\"`
 - 对于`AppWorkPath`，应该使用`-X \"code.gitea.io/gitea/modules/setting.AppWorkPath=working-path\"`
 - 对于`StaticRootPath`，应该使用`-X \"code.gitea.io/gitea/modules/setting.StaticRootPath=static-root-path\"`
 - 要更改默认的 PID 文件位置，请使用`-X \"code.gitea.io/gitea/cmd.PIDFile=/run/gitea.pid\"`
 将这些字符串与其前导的`-X`添加到`LDFLAGS`变量中，并像上面那样使用适当的`TAGS`运行`make build`。
 运行`gitea help`将允许您查看配置的`gitea`设置。
 ## 交叉编译
 `go`编译器工具链支持将代码交叉编译到不同的目标架构上。请参考[`GOOS`和`GOARCH`环境变量](https://go.dev/doc/install/source#environment) 以获取支持的目标列表。如果您想为性能较弱的系统（如树莓派）构建 Gitea，交叉编译非常有用。
 要使用构建标签（`TAGS`）进行交叉编译 Gitea，您还需要一个 C 交叉编译器，该编译器的目标架构与`GOOS`和`GOARCH`变量选择的架构相同。例如，要为 Linux ARM64（`GOOS=linux`和`GOARCH=arm64`）进行交叉编译，您需要`aarch64-unknown-linux-gnu-gcc`交叉编译器。这是因为 Gitea 构建标签使用了`cgo`的外部函数接口（FFI）。
 在没有任何标签的情况下，交叉编译的 Gitea 为 Linux ARM64 版本：
 ```
 GOOS=linux GOARCH=arm64 make build
 ```
 要交叉编译 Linux ARM64 下的 Gitea，这是推荐的构建标签：
 ```
 CC=aarch64-unknown-linux-gnu-gcc GOOS=linux GOARCH=arm64 TAGS="bindata sqlite sqlite_unlock_notify" make build
 ```
 根据您的目标架构，适当替换`CC`、`GOOS`和`GOARCH`。
 有时您需要构建一个静态编译的镜像。为此，您需要添加以下内容：
 ```
 LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo $TAGS" make build
 ```
 这可以与上述的`CC`、`GOOS`和`GOARCH`结合使用。
 ### 添加 bash/zsh 自动补全（从 1.19 版本起）
 在[`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete)中可以找到一个启用 bash 自动补全的脚本。您可以根据需要进行修改，并在您的 `.bashrc` 中使用 `source` 命令加载该脚本，或者将其复制到 `/usr/share/bash-completion/completions/gitea`。
 类似地，可以在[`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete)中找到一个用于 zsh 自动补全的脚本。您可以将其复制到 `/usr/share/zsh/_gitea`，或者在您的 `.zshrc` 中使用 `source` 命令加载该脚本。
 可能需要你根据具体情况进一步改进这些脚本。
 ## 在 Linux 上使用 Zig 进行编译或交叉编译
 请按照 [Zig 的入门指南](https://ziglang.org/learn/getting-started/#installing-zig) 安装 Zig。
 - 编译 (Linux ➝ Linux)
 ```sh
 CC="zig cc -target x86_64-linux-gnu" \
 CGO_ENABLED=1 \
 CGO_CFLAGS="-O2 -g -pthread" \
 CGO_LDFLAGS="-linkmode=external -v"
 GOOS=linux \
 GOARCH=amd64 \
 TAGS="bindata sqlite sqlite_unlock_notify" \
 make build
 ```
 - 交叉编译 (Linux ➝ Windows)
 ```sh
 CC="zig cc -target x86_64-windows-gnu" \
 CGO_ENABLED=1 \
 CGO_CFLAGS="-O2 -g -pthread" \
 GOOS=windows \
 GOARCH=amd64 \
 TAGS="bindata sqlite sqlite_unlock_notify" \
 make build
 ```
 ## 在 Windows 上使用 Zig 进行编译或交叉编译
 使用`GIT BASH`编译。
 - 编译 (Windows ➝ Windows)
 ```sh
 CC="zig cc -target x86_64-windows-gnu" \
 CGO_ENABLED=1 \
 CGO_CFLAGS="-O2 -g -pthread" \
 GOOS=windows \
 GOARCH=amd64 \
 TAGS="bindata sqlite sqlite_unlock_notify" \
 make build
 ```
 - 交叉编译 (Windows ➝ Linux)
 ```sh
 CC="zig cc -target x86_64-linux-gnu" \
 CGO_ENABLED=1 \
 CGO_CFLAGS="-O2 -g -pthread" \
 CGO_LDFLAGS="-linkmode=external -v"
 GOOS=linux \
 GOARCH=amd64 \
 TAGS="bindata sqlite sqlite_unlock_notify" \
 make build
 ```
 ## Source Map
 默认情况下，gitea 会为前端文件生成精简的 Source Map 以节省空间。 这可以通过“ENABLE_SOURCEMAP”环境变量进行控制：
 - `ENABLE_SOURCEMAP=true` 生成所有 Source Map，这是开发版本的默认设置
 - `ENABLE_SOURCEMAP=reduced` 生成有限的 Source Map，这是生产版本的默认设置
 - `ENABLE_SOURCEMAP=false` 不生成 Source Map
@@ -1,373 +0,0 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
 slug: "install-with-docker"
 sidebar_position: 70
 aliases:
  - /zh-cn/install-with-docker
 ---
 # 使用 Docker 安装
 Gitea 在其 Docker Hub 组织内提供自动更新的 Docker 镜像。可以始终使用最新的稳定标签或使用其他服务来更新 Docker 镜像。
 该参考设置指导用户完成基于 `docker-compose` 的设置，但是 `docker-compose` 的安装不在本文档的范围之内。要安装 `docker-compose` 本身，请遵循官方[安装说明](https://docs.docker.com/compose/install/)。
 ## 基本
 最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 安装的是最新的稳定版本。对于稳定的发行版，您也可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。如果您想使用最新的开发版本，则可以使用 `:main-nightly` 标签；如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly`）。
 ```yaml
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 ```
 ## 端口
 要将集成的 openSSH 守护进程和 Web 服务器绑定到其他端口，请调整端口部分。通常，只需更改主机端口，容器内的端口保持原样即可。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
 -     - "3000:3000"
 -     - "222:22"
 +     - "8080:3000"
 +     - "2221:22"
 ```
 ## 数据库
 ### MySQL 数据库
 要将 Gitea 与 MySQL 数据库结合使用，请将这些更改应用于上面创建的 `docker-compose.yml` 文件。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
 +      - GITEA__database__DB_TYPE=mysql
 +      - GITEA__database__HOST=db:3306
 +      - GITEA__database__NAME=gitea
 +      - GITEA__database__USER=gitea
 +      - GITEA__database__PASSWD=gitea
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 +    depends_on:
 +      - db
 +
 +  db:
 +    image: docker.io/library/mysql:8
 +    restart: always
 +    environment:
 +      - MYSQL_ROOT_PASSWORD=gitea
 +      - MYSQL_USER=gitea
 +      - MYSQL_PASSWORD=gitea
 +      - MYSQL_DATABASE=gitea
 +    networks:
 +      - gitea
 +    volumes:
 +      - ./mysql:/var/lib/mysql
 ```
 ### PostgreSQL 数据库
 要将 Gitea 与 PostgreSQL 数据库结合使用，请将这些更改应用于上面创建的 `docker-compose.yml` 文件。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
 +      - GITEA__database__DB_TYPE=postgres
 +      - GITEA__database__HOST=db:5432
 +      - GITEA__database__NAME=gitea
 +      - GITEA__database__USER=gitea
 +      - GITEA__database__PASSWD=gitea
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 +    depends_on:
 +      - db
 +
 +  db:
 +    image: docker.io/library/postgres:14
 +    restart: always
 +    environment:
 +      - POSTGRES_USER=gitea
 +      - POSTGRES_PASSWORD=gitea
 +      - POSTGRES_DB=gitea
 +    networks:
 +      - gitea
 +    volumes:
 +      - ./postgres:/var/lib/postgresql/data
 ```
 ## 命名卷
 要使用命名卷而不是主机卷，请在 `docker-compose.yml` 配置中定义并使用命名卷。此更改将自动创建所需的卷。您无需担心命名卷的权限；Docker 将自动处理该问题。
 ```diff
 version: "3"
 networks:
  gitea:
    external: false
 +volumes:
 +  gitea:
 +    driver: local
 +
 services:
  server:
    image: docker.gitea.com/gitea:@dockerVersion@
    container_name: gitea
    restart: always
    networks:
      - gitea
    volumes:
 -      - ./gitea:/data
 +      - gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
 ```
 MySQL 或 PostgreSQL 容器将需要分别创建。
 ## 启动
 要基于 `docker-compose` 启动此设置，请执行 `docker-compose up -d`，以在后台启动 Gitea。使用 `docker-compose ps` 将显示 Gitea 是否正确启动。可以使用 `docker-compose logs` 查看日志。
 要关闭设置，请执行 `docker-compose down`。这将停止并杀死容器。这些卷将仍然存在。
 注意：如果在 http 上使用非 3000 端口，请更改 app.ini 以匹配 `LOCAL_ROOT_URL = http://localhost:3000/`。
 ## 安装
 通过 `docker-compose` 启动 Docker 安装后，应该可以使用喜欢的浏览器访问 Gitea，以完成安装。访问 http://server-ip:3000 并遵循安装向导。如果数据库是通过上述 `docker-compose` 设置启动的，请注意，必须将 `db` 用作数据库主机名。
 ## 环境变量
 您可以通过环境变量配置 Gitea 的一些设置：
 （默认值以**粗体**显示）
 - `APP_NAME`：**“Gitea: Git with a cup of tea”**：应用程序名称，在页面标题中使用。
 - `RUN_MODE`：**prod**：应用程序运行模式，会影响性能和调试。"dev"，"prod"或"test"。
 - `DOMAIN`：**localhost**：此服务器的域名，用于 Gitea UI 中显示的 http 克隆 URL。
 - `SSH_DOMAIN`：**localhost**：该服务器的域名，用于 Gitea UI 中显示的 ssh 克隆 URL。如果启用了安装页面，则 SSH 域服务器将采用以下形式的 DOMAIN 值（保存时将覆盖此设置）。
 - `SSH_PORT`：**22**：克隆 URL 中显示的 SSH 端口。
 - `SSH_LISTEN_PORT`：**%(SSH_PORT)s**：内置 SSH 服务器的端口。
 - `DISABLE_SSH`：**false**：如果不可用，请禁用 SSH 功能。如果要禁用 SSH 功能，则在安装 Gitea 时应将 SSH 端口设置为 `0`。
 - `HTTP_PORT`：**3000**：HTTP 监听端口。
 - `ROOT_URL`：**""**：覆盖自动生成的公共 URL。如果内部 URL 和外部 URL 不匹配（例如在 Docker 中），这很有用。
 - `LFS_START_SERVER`：**false**：启用 git-lfs 支持。
 - `DB_TYPE`：**sqlite3**：正在使用的数据库类型[mysql，postgres，mssql，sqlite3]。
 - `DB_HOST`：**localhost:3306**：数据库主机地址和端口。
 - `DB_NAME`：**gitea**：数据库名称。
 - `DB_USER`：**root**：数据库用户名。
 - `DB_PASSWD`：**"_empty_"** ：数据库用户密码。如果您在密码中使用特殊字符，请使用“您的密码”进行引用。
 - `INSTALL_LOCK`：**false**：禁止访问安装页面。
 - `SECRET_KEY`：**""** ：全局密钥。这应该更改。如果它具有一个值并且 `INSTALL_LOCK` 为空，则 `INSTALL_LOCK` 将自动设置为 `true`。
 - `DISABLE_REGISTRATION`：**false**：禁用注册，之后只有管理员才能为用户创建帐户。
 - `REQUIRE_SIGNIN_VIEW`：**false**：启用此选项可强制用户登录以查看任何页面。
 - `USER_UID`：**1000**：在容器内运行 Gitea 的用户的 UID（Unix 用户 ID）。如果使用主机卷，则将其与 `/data` 卷的所有者的 UID 匹配（对于命名卷，则不需要这样做）。
 - `USER_GID`：**1000**：在容器内运行 Gitea 的用户的 GID（Unix 组 ID）。如果使用主机卷，则将其与 `/data` 卷的所有者的 GID 匹配（对于命名卷，则不需要这样做）。
 ## 自定义
 [此处](../administration/customizing-gitea.md)描述的定制文件应放在 `/data/gitea` 目录中。如果使用主机卷，则访问这些文件非常容易；对于命名卷，可以通过另一个容器或通过直接访问 `/var/lib/docker/volumes/gitea_gitea/_data` 来完成。安装后，配置文件将保存在 `/data/gitea/conf/app.ini` 中。
 ## 升级
 :::warning
 :exclamation::exclamation: **确保已将数据卷到 Docker 容器外部的某个位置** :exclamation::exclamation:
 :::
 要将安装升级到最新版本：
 ```bash
 # Edit `docker-compose.yml` to update the version, if you have one specified
 # Pull new images
 docker-compose pull
 # Start a new container, automatically removes old one
 docker-compose up -d
 ```
 ## 使用环境变量管理部署
 除了上面的环境变量之外，`app.ini` 中的任何设置都可以使用以下形式的环境变量进行设置或覆盖：`GITEA__SECTION_NAME__KEY_NAME`。 每次 docker 容器启动时都会应用这些设置。 完整信息在[这里](https://github.com/go-gitea/gitea/tree/master/contrib/environment-to-ini)。
 ```bash
 ...
 services:
  server:
    environment:
      - GITEA__mailer__ENABLED=true
      - GITEA__mailer__FROM=${GITEA__mailer__FROM:?GITEA__mailer__FROM not set}
      - GITEA__mailer__PROTOCOL=smtps
      - GITEA__mailer__HOST=${GITEA__mailer__HOST:?GITEA__mailer__HOST not set}
      - GITEA__mailer__USER=${GITEA__mailer__USER:-apikey}
      - GITEA__mailer__PASSWD="""${GITEA__mailer__PASSWD:?GITEA__mailer__PASSWD not set}"""
 ```
 Gitea 将为每次新安装自动生成新的 `SECRET_KEY` 并将它们写入 `app.ini`。 如果您想手动设置 `SECRET_KEY`，您可以使用以下 docker 命令来使用 Gitea 内置的[方法](../administration/command-line.md#generate)生成 `SECRET_KEY`。 安装后请妥善保管您的 `SECRET_KEY`，如若丢失则无法解密已加密的数据。
 以下命令将向 `stdout` 输出一个新的 `SECRET_KEY` 和 `INTERNAL_TOKEN`，然后您可以将其放入环境变量中。
 ```bash
 docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret SECRET_KEY
 docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKEN
 ```
 ```yaml
 ---
 services:
  server:
    environment:
      - GITEA__security__SECRET_KEY=[value returned by generate secret SECRET_KEY]
      - GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
 ```
 ## SSH 容器直通
 由于 SSH 在容器内运行，因此，如果需要 SSH 支持，则需要将 SSH 从主机传递到容器。一种选择是在非标准端口上运行容器 SSH（或将主机端口移至非标准端口）。另一个可能更直接的选择是将 SSH 连接从主机转发到容器。下面将说明此设置。
 本指南假定您已经在名为 `git` 的主机上创建了一个用户，该用户与容器值 `USER_UID`/`USER_GID` 共享相同的 `UID`/`GID`。这些值可以在 `docker-compose.yml` 中设置为环境变量：
 ```bash
 environment:
  - USER_UID=1000
  - USER_GID=1000
 ```
 接下来将主机的 `/home/git/.ssh` 装入容器。否则，SSH 身份验证将无法在容器内运行。
 ```bash
 volumes:
  - /home/git/.ssh/:/data/git/.ssh
 ```
 现在，需要在主机上创建 SSH 密钥对。该密钥对将用于向主机验证主机上的 `git` 用户。
 ```bash
 sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
 ```
 在下一步中，需要在主机上创建一个名为 `/usr/local/bin/gitea` 的文件（具有可执行权限）。该文件将发出从主机到容器的 SSH 转发。将以下内容添加到 `/usr/local/bin/gitea`：
 ```bash
 ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
 ```
 为了使转发正常工作，需要将容器（22）的 SSH 端口映射到 `docker-compose.yml` 中的主机端口 2222。由于此端口不需要暴露给外界，因此可以将其映射到主机的 `localhost`：
 ```bash
 ports:
  # [...]
  - "127.0.0.1:2222:22"
 ```
 另外，主机上的 `/home/git/.ssh/authorized_keys` 需要修改。它需要以与 Gitea 容器内的 `authorized_keys` 相同的方式进行操作。因此，将您在上面创建的密钥（“Gitea 主机密钥”）的公共密钥添加到 `/home/git/.ssh/authorized_keys`。这可以通过 `echo "$(cat /home/git/.ssh/id_rsa.pub)" >> /home/git/.ssh/authorized_keys` 完成。重要提示：来自 `git` 用户的公钥需要“按原样”添加，而通过 Gitea 网络界面添加的所有其他公钥将以 `command="/app [...]` 作为前缀。
 该文件应该看起来像：
 ```bash
 # SSH pubkey from git user
 ssh-rsa <Gitea Host Key>
 # other keys from users
 command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
 ```
 这是详细的说明，当发出 SSH 请求时会发生什么：
 1. 使用 `git` 用户向主机发出 SSH 请求，例如 `git clone git@domain:user/repo.git`。
 2. 在 `/home/git/.ssh/authorized_keys` 中，该命令执行 `/usr/local/bin/gitea` 脚本。
 3. `/usr/local/bin/gitea` 将 SSH 请求转发到端口 2222，该端口已映射到容器的 SSH 端口（22）。
 4. 由于 `/home/git/.ssh/authorized_keys` 中存在 `git` 用户的公钥，因此身份验证主机 → 容器成功，并且 SSH 请求转发到在 docker 容器中运行的 Gitea。
 如果在 Gitea Web 界面中添加了新的 SSH 密钥，它将以与现有密钥相同的方式附加到 `.ssh/authorized_keys` 中。
 **注意**
 SSH 容器直通仅在以下情况下有效
 - 在容器中使用 `opensshd`
 - 如果未将 `AuthorizedKeysCommand` 与 `SSH_CREATE_AUTHORIZED_KEYS_FILE = false` 结合使用以禁用授权文件密钥生成
 - `LOCAL_ROOT_URL` 不变
@@ -1,102 +0,0 @@
 ---
 date: "2023-05-24T15:00:00+08:00"
 slug: "comparison"
 sidebar_position: 15
 ---
 # 与GitHub Actions的对比
 Gitea Actions旨在与GitHub Actions兼容，差异如下。
 ## 额外功能
 <a id="absolute-action-urls"></a>
 ### Action URL绝对路径
 `uses:`支持指向任意Git托管平台的绝对URL，例如`uses: https://gitea.com/actions/checkout@v4`。
 <a id="action-prefixes"></a>
 ### Action前缀
 `uses:`支持以下前缀：
 - `self:`引用您自己的Gitea实例，例如`uses: self:owner/repo@v1`或`uses: self:owner/repo/.gitea/workflows/build.yml@v1`
 - `builtin:`运行Gitea Runner内置的Action，无需下载，Job镜像中也无需Node，例如`uses: builtin:checkout`
 `builtin:checkout`支持`actions/checkout`的`repository`、`ref`、`token`、`path`和`fetch-depth`输入，默认值相同，其他输入会使步骤失败。
 <a id="workflow-relative-actions"></a>
 ### 相对于工作流的Actions
 `$/`引用工作流所在的仓库和提交，或外层复合Action所在的仓库和提交，例如`uses: $/.gitea/actions/build`。
 与`./`不同，它无需事先检出代码。
 ### 使用Go编写Actions
 请参阅[创建Go Actions](https://blog.gitea.com/creating-go-actions/)。
 ### 支持非标准的调度语法 @yearly, @monthly, @weekly, @daily, @hourly
 `schedule`还支持`@yearly`、`@monthly`、`@weekly`、`@daily`和`@hourly`，而[GitHub不支持](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule)。
 ## 不支持的工作流语法
 ### `jobs.<job_id>.environment`
 [`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)会被忽略。
 ### 复杂的`runs-on`
 [`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)支持：
 - 静态字符串：`runs-on: self-hosted`
 - 标签数组：`runs-on: [linux, self-hosted]`
 - 字符串表达式：`runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
 - 包含表达式的数组：`runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
 ## 缺失的功能
 ### 软件包仓库授权
 `GITEA_TOKEN`无法发布到其所属仓库的软件包注册表，例如无法推送OCI镜像。
 请改用个人访问令牌，参见[此问题](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692)。
 ### 问题匹配器
 [问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)会被忽略。
 ### 为错误创建注释
 [错误注释](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)会被忽略。
 ### 表达式
 [表达式](https://docs.github.com/en/actions/learn-github-actions/expressions)支持GitHub的标准函数和上下文。
 ## 缺失的UI功能
 ### 预处理和后处理步骤
 预处理和后处理步骤在Job日志中没有单独的区块。
 ### 服务步骤
 服务步骤在Job日志中没有单独的区块。
 ## 不一样的行为
 ### `permissions`和`jobs.<job_id>.permissions`
 `permissions`和`jobs.<job_id>.permissions`控制`GITEA_TOKEN`的权限，该权限受仓库和所有者设置的限制，并在fork拉取请求和跨仓库访问时受到进一步限制。
 不支持`statuses`、`checks`、`deployments`、`security-events`和`pages`等GitHub专有的权限范围，而Gitea额外提供了`code`、`releases`、`wiki`和`projects`。`id-token`与GitHub相同，请参阅[OpenID Connect](openid-connect.md)。
 请参阅[Actions Job令牌权限](token-permissions.md)。
 ### 下载Actions
 未指定主机的Actions（如`uses: actions/checkout@v4`）会从`https://github.com`下载，当`[actions].DEFAULT_ACTIONS_URL`为`self`时则从您自己的实例下载。
 请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-actions)。
 其他来源请参阅[Action URL绝对路径](#absolute-action-urls)、[Action前缀](#action-prefixes)和[相对于工作流的Actions](#workflow-relative-actions)。
 ### 上下文可用性
 不检查[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)，因此`env`等上下文可以在更多地方使用。
@@ -1,63 +0,0 @@
 ---
 date: "2026-08-23T00:00:00+00:00"
 slug: "openid-connect"
 sidebar_position: 40
 ---
 # OpenID Connect
 Job可以请求短期有效的OpenID Connect（OIDC）令牌来登录云服务商和其他服务，无需存储长期有效的密钥。这些令牌采用GitHub Actions的格式，因此`aws-actions/configure-aws-credentials`、`google-github-actions/auth`和`azure/login`等Action无需修改即可使用。
 <a id="trusting-gitea"></a>
 ## 信任Gitea
 在服务中将Gitea添加为OIDC身份提供方：
 - Issuer：`<ROOT_URL>/api/actions/oidc`
 - Audience：`<ROOT_URL>/<owner>`，除非工作流请求了其他值
 然后通过[`sub`声明](#claims)上的条件限制哪些工作流可以登录。
 Gitea使用其在`<APP_DATA_PATH>/jwt/actions_oidc.pem`创建的密钥签名令牌。负载均衡器后的多个实例必须共享此文件。
 <a id="requesting-a-token"></a>
 ## 请求令牌
 为工作流或Job授予`id-token`权限：
 ```yaml
 permissions:
  id-token: write
 ```
 默认权限从不包含此权限，来自fork拉取请求的Job也永远无法获得。所有者和仓库可以通过[最大令牌权限](token-permissions.md#maximum-token-permissions-clamping)禁用它。
 上述Action会自行请求令牌。在脚本中，请使用`ACTIONS_ID_TOKEN_REQUEST_URL`和`ACTIONS_ID_TOKEN_REQUEST_TOKEN`：
 ```shell
 curl --fail --silent --show-error \
  --header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
  "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service"
 ```
 令牌位于响应的`value`字段中，五分钟后过期。
 <a id="claims"></a>
 ## 声明
 `sub`声明包含所有者和仓库的名称及ID，因此重命名或重新创建的仓库无法匹配已有的信任策略：
 ```text
 repo:<owner>@<owner-id>/<repo>@<repo-id>:ref:<ref>
 repo:<owner>@<owner-id>/<repo>@<repo-id>:pull_request
 ```
 `pull_request`事件使用第二种格式，其他所有事件（包括`pull_request_target`）使用第一种。
 其他声明与GitHub相同，例如`repository`、`ref`、`sha`、`workflow_ref`和`job_workflow_ref`。位于`<ROOT_URL>/api/actions/oidc/.well-known/openid-configuration`的发现文档列出了所有声明。
 与GitHub Actions的区别：
 - 没有`environment`声明。
 - 拉取请求的运行使用`refs/pull/<index>/head`及其提交，而不是合并引用和合并提交。
 - `run_number`按仓库计数，而不是按工作流计数。
@@ -1,131 +0,0 @@
 ---
 date: "2023-05-24T15:00:00+08:00"
 slug: "quickstart"
 sidebar_position: 10
 ---
 # 快速入门
 本页面将指导您使用Gitea Actions的过程。
 ## 设置Gitea
 首先，您需要一个Gitea实例。
 您可以按照[文档](installation/from-package.md) 来设置一个新实例或升级现有实例。
 无论您如何安装或运行Gitea，只要版本号是1.19.0或更高即可。
 从1.21.0开始，默认情况下，Actions是启用的。如果您正在使用1.21.0之前的版本，您需要将以下内容添加到配置文件中以启用它：
 ```ini
 [actions]
 ENABLED=true
 ```
 如果您想了解更多信息或在配置过程中遇到任何问题，请参考[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
 ### 设置Runner
 Gitea Actions需要[runner](https://gitea.com/gitea/runner) 来运行Job。
 为了避免消耗过多资源并影响Gitea实例，建议您在与Gitea实例分开的机器上启动Runner。
 您可以使用[预构建的二进制文件](http://dl.gitea.com/gitea-runner)或[容器镜像](https://hub.docker.com/r/gitea/runner/tags)来设置Runner。
 在进一步操作之前，建议您先使用预构建的二进制文件以命令行方式运行它，以确保它与您的环境兼容，尤其是如果您在本地主机上运行Runner。
 如果出现问题，这样调试起来会更容易。
 该Runner可以在隔离的Docker容器中运行Job，因此您需要确保已安装Docker并且Docker守护进程正在运行。
 虽然这不是严格必需的，因为Runner也可以直接在主机上运行Job，这取决于您的配置方式。
 然而，建议使用Docker运行Job，因为它更安全且更易于管理。
 在运行Runner之前，您需要使用以下命令将其注册到Gitea实例中：
 ```bash
 gitea-runner register --no-interactive --instance <instance> --token <token>
 ```
 需要两个必需的参数：`instance` 和 `token`。
 `instance`是您的Gitea实例的地址，如`http://192.168.8.8:3000`或`https://gitea.com`。
 Runner和Job容器（由Runner启动以执行Job）将连接到此地址。
 这意味着它可能与用于Web访问的`ROOT_URL`不同。
 使用回环地址（例如 `127.0.0.1` 或 `localhost`）是一个不好的选择。
 如果不确定使用哪个地址，通常选择局域网地址即可。
 `token` 用于身份验证和标识，例如 `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`。
 每个令牌都可用于注册多个Runner。通过重置链接替换为新令牌后，旧令牌将失效。
 您可以从以下位置获取不同级别的`token`,从而创建出相应级别的`runner`
 - 实例级别：管理员设置页面，例如 `<your_gitea.com>/-/admin/actions/runners`。
 - 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
 - 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。
 ![register runner](/images/usage/actions/register-runner.png)
 注册后，当前目录中将出现一个名为 `.runner` 的新文件，该文件存储了注册信息。
 请不要手动编辑该文件。
 如果该文件丢失或损坏，只需删除它然后重新注册即可。
 最后，是时候启动Runner了：
 ```bash
 gitea-runner daemon
 ```
 您可以在管理页面上看到新的Runner：
 ![view runner](/images/usage/actions/view-runner.png)
 您可以通过访问[Gitea Runner](runner) 获取更多信息。
 ### 使用Actions
 即使对于启用了Gitea实例的Actions，存储库仍默认禁用Actions。
 要启用它，请转到存储库的设置页面，例如`your_gitea.com/<owner>/repo/settings`，然后启用`Enable Repository Actions`。
 ![enable actions](/images/usage/actions/enable-actions.png)
 接下来的步骤可能相当复杂。
 您需要学习Actions的[工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)，并编写您想要的工作流文件。
 不过，我们可以从一个简单的演示开始：
 ```yaml
 name: Gitea Actions Demo
 run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀
 on: [push]
 jobs:
  Explore-Gitea-Actions:
    runs-on: ubuntu-latest
    steps:
      - run: echo "🎉 The job was automatically triggered by a ${{ gitea.event_name }} event."
      - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!"
      - run: echo "🔎 The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}."
      - name: Check out repository code
        uses: actions/checkout@v4
      - run: echo "💡 The ${{ gitea.repository }} repository has been cloned to the runner."
      - run: echo "🖥️ The workflow is now ready to test your code on the runner."
      - name: List files in the repository
        run: |
          ls ${{ gitea.workspace }}
      - run: echo "🍏 This job's status is ${{ job.status }}."
 ```
 您可以将上述示例上传为一个以`.yaml`扩展名的文件，放在存储库的`.gitea/workflows/`目录中，例如`.gitea/workflows/demo.yaml`。
 您可能会注意到，这与[GitHub Actions的快速入门](https://docs.github.com/en/actions/quickstart)非常相似。
 这是因为Gitea Actions在尽可能兼容GitHub Actions的基础上进行设计。
 请注意，演示文件中包含一些表情符号。
 请确保您的数据库支持它们，特别是在使用MySQL时。
 如果字符集不是`utf8mb4`，将出现错误，例如`Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`。
 有关更多信息，请参阅[数据库准备工作](../../installation/database-preparation.md#mysqlmariadb)。
 或者，您可以从演示文件中删除所有表情符号，然后再尝试一次。
 `on: [push]` 这一行表示当您向该存储库推送提交时，工作流将被触发。
 然而，当您上传 YAML 文件时，它也会推送一个提交，所以您应该在"Actions"标签中看到一个新的任务。
 ![view job](/images/usage/actions/view-job.png)
 做得好！您已成功开始使用Actions。
Author	SHA1	Message	Date
Lunny Xiao	fecad73221	ci: only read the Depends on lines, and let the label be the gate	2026-09-08 12:03:59 -07:00
Lunny Xiao	83cbd0138f	ci: keep the jq expressions parsable on jq 1.6	2026-09-08 12:00:37 -07:00
Lunny Xiao	3fb4de8560	ci: run the check with the script from the pull request	2026-09-08 11:58:23 -07:00
Lunny Xiao	7d4c23de0b	ci: fail a pull request that waits for an unmerged gitea change	2026-09-08 11:50:21 -07:00