docs(packages): document terraform module registry (#433)

Ref: https://github.com/go-gitea/gitea/pull/38040

Adds docs/usage/packages/terraform-module.md describing the v1 scope,
naming rules, authentication, service discovery, HTTP API surface and
[packages] settings for the new private Terraform Module Registry.

---------

Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/433
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Michael Lopez <[email protected]>

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

@@ -8,7 +8,7 @@ on:
 
 jobs:
   build-docs:
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-26.04
     env:
       NODE_OPTIONS: --max-old-space-size=8192
       # search only appears once the credentials are set, the build falls back
@@ -21,7 +21,7 @@ jobs:
       - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
       - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
         with:
-          node-version: 24
+          node-version: 26
           cache: pnpm
       - name: prepare awesome list
         run: |

.gitea/workflows/test.yaml

@@ -18,7 +18,7 @@ jobs:
       - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
       - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
         with:
-          node-version: 24
+          node-version: 26
           cache: pnpm
       - name: prepare awesome list
         run: |

Makefile

@@ -92,7 +92,7 @@ update-runner-docs:
 update-runner-docs-released:
 	./update_runner_docs.sh --released
 
-# freezes the current docs or runner tree as a new version, see
+# freezes the current docs, runner or cli tree as a new version, see
 # scripts/cut-version.mjs
 .PHONY: cut-version
 cut-version:

README.md

@@ -3,13 +3,14 @@
 The sources of [docs.gitea.com](https://docs.gitea.com), built with
 [Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
 
-The site covers three products, all served from this repository:
+The site covers four products, all served from this repository:
 
 | Product | Content | Versions | Languages |
 | --- | --- | --- | --- |
 | Docs | `docs/`, `versioned_docs/`, `i18n/` | next, 28, 1.27 … 1.22 | English, 简体中文, 繁體中文 |
 | API | `static/swagger-*.json`, `static/openapi3-*.json` | next, 28, 1.27 … 1.22 | English |
 | Runner | `runner-docs/`, `runner-docs_versioned_docs/` | develop, 5 … 0 | English |
+| CLI | `cli-docs/`, `cli-docs_versioned_docs/` | develop | English |
 
 The enterprise documentation is built and deployed from its own repository and
 reached through `/enterprise/`, which a Cloudflare worker maintained elsewhere
@@ -53,6 +54,7 @@ group from the `_category_.json` of its directory.
 ```shell
 make cut-version PRODUCT=docs VERSION=1.28
 make cut-version PRODUCT=runner VERSION=6
+make cut-version PRODUCT=cli VERSION=0.1
 ```
 
 This freezes the current tree, its translations and its sidebar. The label of
@@ -115,6 +117,16 @@ workflow runs weekly and opens a pull request whenever the runner's CLI or
 example configuration changed. Generating them needs Go, since the script builds
 the runner binary.
 
+## CLI docs
+
+The documentation of `gt`, the Gitea CLI from
+[gitea/cli](https://gitea.com/gitea/cli), is laid out like the runner docs, with
+its sidebar in `cli-sidebars.js`. No series is documented yet, so `cli-docs/` is
+served at `/cli/`. Once a release exists, cut its series and list it in
+`cliSeries` in `packages/content-loader/src/products.ts`, which moves the develop
+docs to `/cli/develop/`. The guides leave the flags of each command to
+`gt <command> --help`.
+
 ## Deployment
 
 `main` is built and published by the `Build and Publish Docs site` workflow, to

cli-docs/authentication.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 3
+---
+
+# Logging in
+
+On a terminal, `gt auth login` asks for the instance and how to log in. gt never asks for
+your password.
+
+## OAuth in a browser
+
+```bash
+gt auth login --host https://gitea.example.com --oauth
+```
+
+gt opens the instance's authorization page, so single sign-on and two-factor
+authentication work as on the web. The browser has to run on the same machine as gt.
+`--scopes` limits the token to fewer [scopes](/development/oauth2-provider#scopes); gt
+refreshes OAuth tokens on its own.
+
+## Access token
+
+Create a token under **Settings > Applications** on the instance and pass it on stdin:
+
+```bash
+gt auth login --host https://gitea.example.com --with-token < token.txt
+```
+
+The token needs `read:user`, and the scopes of what you do with gt, such as
+`write:repository` and `write:issue` for working on pull requests.
+
+## SSH key
+
+gt can sign its requests with an SSH key registered for your account instead of using a
+token:
+
+```bash
+gt auth login --host https://gitea.example.com --ssh-key ~/.ssh/id_ed25519
+```
+
+## Accounts
+
+Tokens go to the system keyring, or with `--credential-store file` to gt's configuration
+directory on machines without one. Run `gt auth login` once per instance and account.
+gt picks the instance from the repository's remote or `--host`, and the account with
+`gt auth switch` or `--user`. `gt auth status` lists your accounts and `gt auth logout`
+removes one.
+
+For instances behind an access proxy, `--header` and `--client-cert` add headers and a
+client certificate.
+
+## Git over HTTPS
+
+`gt auth setup-git` lets `git push` and `git fetch` over HTTPS use gt's login. gt's own
+clone and checkout commands need no setup.

cli-docs/ci.md

@@ -0,0 +1,40 @@
+---
+sidebar_position: 4
+---
+
+# Using gt in CI
+
+Give gt a token and an instance through the environment, and turn prompts off:
+
+| Variable | Description |
+| --- | --- |
+| `GITEA_TOKEN` | Access token; gt never stores it |
+| `GITEA_CLI_HOST` or `GITEA_INSTANCE_URL` | URL of the instance |
+| `GITEA_CLI_REPO` | Repository, like `--repo` |
+
+`--no-input` makes a command fail instead of prompting, and `--yes` confirms changes in
+advance.
+
+## Gitea Actions
+
+Gitea does not allow secret names that start with `GITEA_`, so store the token as, for
+example, `GT_TOKEN`:
+
+```yaml
+on:
+  push:
+    branches: [main]
+
+jobs:
+  staging:
+    runs-on: ubuntu-latest
+    env:
+      GITEA_TOKEN: ${{ secrets.GT_TOKEN }}
+      GITEA_CLI_HOST: ${{ gitea.server_url }}
+      GITEA_CLI_REPO: ${{ gitea.repository }}
+    steps:
+      - run: curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
+      - run: gt workflow run deploy.yml --ref main --field env=staging --no-input
+```
+
+`gt run watch` and `gt pr checks --watch` wait for runs and checks and fail when one fails.

cli-docs/index.md

@@ -0,0 +1,38 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# Gitea CLI
+
+[gt](https://gitea.com/gitea/cli) is the official command line client for Gitea. It works
+with repositories, issues, pull requests, releases, Actions and the other resources of a
+Gitea instance, from a terminal or a script.
+
+:::info Development version
+These pages describe builds from the `main` branch, published as `nightly` binaries and images.
+:::
+
+gt needs Gitea 28 or later, and Git for the commands that clone, check out or push.
+
+## Getting started
+
+1. [Install gt](installation.md).
+2. [Log in](authentication.md):
+
+   ```bash
+   gt auth login
+   ```
+
+3. Run commands in a clone of a repository on that instance, or select one with `--repo`:
+
+   ```bash
+   gt issue list --label bug
+   gt pr checkout 13
+   gt issue view 42 --repo gitea.com/gitea/cli
+   ```
+
+`gt doctor` checks your setup and suggests a fix for each problem it finds.
+
+`gt <command> --help` lists the flags of a command, and `gt help environment` the global
+flags and environment variables.

cli-docs/installation.md

@@ -0,0 +1,37 @@
+---
+sidebar_position: 2
+---
+
+# Installation
+
+gt is a single binary for Linux, macOS, Windows and FreeBSD.
+
+## Install script
+
+The install script downloads gt from [dl.gitea.com](https://dl.gitea.com/gitea-cli/),
+verifies its checksum and installs it.
+
+```bash
+# Linux, macOS, FreeBSD
+curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
+```
+
+```powershell
+# Windows
+irm https://gitea.com/gitea/cli/raw/branch/main/scripts/install.ps1 | iex
+```
+
+Set `GITEA_CLI_VERSION` to install a specific version, or `nightly` for the latest build
+of `main`.
+
+## Other ways
+
+- **Binaries:** download them from [dl.gitea.com/gitea-cli](https://dl.gitea.com/gitea-cli/).
+- **Docker:** the [`gitea/gitea-cli`](https://hub.docker.com/r/gitea/gitea-cli) image runs
+  `gt` as its entry point.
+- **Go:** `go install gitea.dev/cli/cmd/gt@latest`
+
+## Shell completion and man pages
+
+`gt completion <shell>` prints the completion script for bash, zsh, fish or PowerShell;
+`gt completion <shell> --help` shows how to load it. `gt man` prints the manual.

cli-docs/scripting.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 5
+---
+
+# Output and scripting
+
+Scripts should read JSON: the text output is meant for people and may change.
+
+```bash
+gt pr view 123 --json number,title,state
+gt issue list --json number,title --jq '.[] | "\(.number)\t\(.title)"'
+```
+
+`--json` prints all fields or the ones you list; the **JSON FIELDS** section of a command's
+`--help` names them. `--jq` filters the result without needing jq installed. Piped lists
+print as tab-separated values.
+
+gt exits with 0 on success, 1 when a command fails, 2 on a usage error and 4 when
+authentication is missing or rejected; `gt help exit-codes` lists all codes.
+
+`gt api` calls any API endpoint with gt's login, and `gt alias set` defines shortcuts for
+commands you use often.

cli-docs_versions.json

@@ -0,0 +1 @@
+[]

cli-sidebars.js

@@ -0,0 +1,16 @@
+// Sidebar of the gt (Gitea CLI) documentation (develop version).
+// Released versions carry their own copy in
+// cli-docs_versioned_sidebars/version-<version>-sidebars.json.
+module.exports = {
+  cli: [
+    {
+      type: 'doc',
+      id: 'index',
+      label: 'What is gt?',
+    },
+    'installation',
+    'authentication',
+    'ci',
+    'scripting',
+  ],
+};

cloudflare/_redirects

@@ -1,11 +1,13 @@
 # Redirects for legacy URLs and routes the site no longer serves directly.
 
-# The api reference and the runner docs are separate products, published in
+# The api reference, the runner and the cli docs are separate products,
-# english only, so they have no localized copy.
+# published in english only, so they have no localized copy.
 /zh-cn/api/* /api/:splat 301
 /zh-tw/api/* /api/:splat 301
 /zh-cn/runner/* /runner/:splat 301
 /zh-tw/runner/* /runner/:splat 301
+/zh-cn/cli/* /cli/:splat 301
+/zh-tw/cli/* /cli/:splat 301
 
 # The version served at the root of a product is also reachable under its
 # number, which is what the release notes and old links use.

cloudflare/docsearch-crawler.json

@@ -7,6 +7,7 @@
     "https://docs.gitea.com/zh-cn/",
     "https://docs.gitea.com/zh-tw/",
     "https://docs.gitea.com/runner/",
+    "https://docs.gitea.com/cli/",
     "https://docs.gitea.com/api/",
     "https://docs.gitea.com/enterprise/"
   ],
@@ -15,7 +16,8 @@
     "https://docs.gitea.com/1.2*/**",
     "https://docs.gitea.com/*/1.2*/**",
     "https://docs.gitea.com/api/1.2*/**",
-    "https://docs.gitea.com/runner/[0-9]/**"
+    "https://docs.gitea.com/runner/[0-9]/**",
+    "https://docs.gitea.com/cli/[0-9]*/**"
   ],
   "selectors": {
     "lvl0": { "selector": "//nav[contains(@aria-labelledby,'starlight__sidebar')]//a[@aria-current='page']/ancestor::details//summary//span", "type": "xpath", "global": true, "default_value": "Documentation" },

docs/administration/config-cheat-sheet.md

@@ -179,7 +179,7 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build
 - `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: In default squash-merge messages include the commit message of all commits comprising the pull request.
 - `ADD_CO_COMMITTER_TRAILERS`: **true**: Add co-authored-by and co-committed-by trailers to merge commit messages if committer does not match author.
 - `RETARGET_CHILDREN_ON_MERGE`: **true**: Retarget child pull requests to the parent pull request branch target on merge of parent pull request. It only works on merged PRs where the head and base branch target the same repo.
-- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: Set the default value for "Delete pull request branch after merge by default" for new repositories.
+- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **true**: Set the default value for "Delete pull request branch after merge by default" for new repositories.
 - `DEFAULT_TITLE_SOURCE`: **auto**: Default source for the pull request title when opening a new PR. Valid options:
   - `first-commit`: Uses the oldest commit's summary as the title. If there are multiple commits, still uses the first commit's message.
   - `auto`: Uses the commit's summary when the PR contains a single commit; when there are multiple commits, converts the branch name into a human-readable title by normalizing separators and casing.
@@ -595,7 +595,8 @@ And the following unique queues:
    authentication provided email.
 - `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: Header name for reverse proxy
    authentication provided full name.
-- `REVERSE_PROXY_LIMIT`: **1**: Interpret X-Forwarded-For header or the X-Real-IP header and set this as the remote IP for the request.
+- `REVERSE_PROXY_LIMIT`: **1**: Interpret the X-Real-IP, X-Forwarded-For or Forwarded header, in that order, and set this as the remote IP for the request.
+   The client port is taken from the header value or, with X-Real-IP, from X-Real-Port.
    Number of trusted proxy count. Set to zero to not use these headers.
 - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all.
 - `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value for all HTTP responses. Set to `unset` to not send the header. Previously located in `[cors]`.
@@ -1355,7 +1356,7 @@ These options are written into the gitconfig file under `[git] HOME_PATH` when G
 - `JWT_SECRET_URI`: **_empty_**: Instead of defining JWT_SECRET in the configuration, this configuration option can be used to give Gitea a path to a file that contains the secret (example value: `file:/etc/gitea/oauth2_jwt_secret`)
 - `JWT_SIGNING_PRIVATE_KEY_FILE`: **jwt/private.pem**: Private key file path used to sign OAuth2 tokens. The path is relative to `APP_DATA_PATH`. This setting is only needed if `JWT_SIGNING_ALGORITHM` is set to `RS256`, `RS384`, `RS512`, `ES256`, `ES384` or `ES512`. The file must contain a RSA or ECDSA private key in the PKCS8 format. If no key exists a 4096 bit key will be created for you.
 - `MAX_TOKEN_LENGTH`: **32767**: Maximum length of token/cookie to accept from OAuth2 provider
-- `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, tea, gitea-app**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options.
+- `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager, gitea-cli, gitea-app, gitea-vscode**: Pre-register OAuth applications for some services on startup. See the [OAuth2 documentation](/development/oauth2-provider.md) for the list of available options. `tea` is accepted as an alias of `gitea-cli`.
 - `CUSTOM_SCHEMES`: **_empty_**: By default, OAuth2 applications can only use "http" and "https" as their redirect URI schemes.
   If you need to use other schemes (e.g. for desktop applications), you can specify them here as a comma-separated list.
   For example: set "my-scheme, com.example.app" to support "my-scheme://..." and "com.example.app://..." redirect URIs.
@@ -1487,8 +1488,9 @@ These lists are enforced on direct connections only. When a proxy is configured
 - `LIMIT_SIZE_RPM`: **-1**: Maximum size of a RPM upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_RUBYGEMS`: **-1**: Maximum size of a RubyGems upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_SWIFT`: **-1**: Maximum size of a Swift upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
+- `LIMIT_SIZE_TERRAFORM_MODULE`: **-1**: Maximum size of a Terraform module archive upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`). Archives are additionally capped at 32 MiB decompressed.
+- `LIMIT_SIZE_TERRAFORM_STATE`: **-1**: Maximum size of a Terraform state upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_VAGRANT`: **-1**: Maximum size of a Vagrant upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
-- `LIMIT_SIZE_TERRAFORM_STATE``: **-1**: Maximum size of a Terraform state upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 
 ## Mirror (`mirror`)
 
@@ -1707,7 +1709,7 @@ PROXY_HOSTS = *.github.com
   But it will save storage space and network bandwidth, so it's still recommended to use compression.
 - `ARTIFACT_RETENTION_DAYS`: **90**: Days to keep artifacts. Old artifacts will be deleted after this period. 0 means keep forever.
   Changes only apply to newly uploaded artifacts, existing ones keep the expiry stored when they were uploaded.
-  Artifacts could have their own retention periods by setting the `retention-days` option in `actions/upload-artifact` step.
+  Workflows can request a shorter retention period, down to 1 day.
 - `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

docs/administration/reverse-proxies.md

@@ -16,6 +16,7 @@ aliases:
 4. Make sure `Host` and `X-Forwarded-Proto` headers are correctly passed to Gitea to make Gitea see the real URL being visited.
 5. Make sure your webserver has a certificate, including all intermediate and RootCA certificates, for `git clone` and `git pull` to work.
 6. Gitea uses a WebSocket connection at `/-/ws` for real-time updates like the notification counter. Make sure the reverse-proxy talks HTTP/1.1 and forwards the `Upgrade` and `Connection` headers, see the examples below. Without it, Gitea falls back to periodic polling.
+7. Make sure the reverse-proxy sets the `X-Real-IP` header, otherwise Gitea uses a client-sent value. For example `header_up X-Real-IP {remote_host}` in Caddy's `reverse_proxy`, `RequestHeader set X-Real-IP "expr=%{REMOTE_ADDR}"` in Apache or `http-request set-header X-Real-IP %[src]` in HAProxy. To log the client port, also set `X-Real-Port`, for example `proxy_set_header X-Real-Port $remote_port;` in nginx.
 
 ### Use a sub-path
 

docs/development/api-usage.md

@@ -73,6 +73,7 @@ By default, this creates a token with very limited permissions. To complete your
 
 - `activitypub`
 - `admin`
+- `commitstatus` (included in `repository`)
 - `issue`
 - `misc`
 - `notification`

docs/development/oauth2-provider.md

@@ -111,6 +111,9 @@ Gitea token scopes are as follows:
 | **admin** | `/admin/*` API routes: Site-wide administrative operations (hidden for non-admin accounts).                                                          |
 |     **read:admin** | Grants read access for admin operations, such as getting cron jobs or registered user emails.                                                        |
 |     **write:admin** | Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts.                                           |
+| **commitstatus** | `/repos/{owner}/{repo}/statuses/{sha}` and `/repos/{owner}/{repo}/commits/{ref}/status(es)` API routes: Commit status operations.                        |
+|     **read:commitstatus** | Grants read access to commit statuses. Included in `read:repository`.                                                                                |
+|     **write:commitstatus** | Grants read/write access to commit statuses, such as reporting CI results. Included in `write:repository`.                                           |
 | **issue** | `issues/*`, `labels/*`, `milestones/*` API routes: Issue-related operations.                                                                         |
 |     **read:issue** | Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones.                                         |
 |     **write:issue** | Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones.           |
@@ -141,7 +144,9 @@ Gitea creates OAuth applications for the following services by default on startu
 |-----------|-----------|---------|
 |[git-credential-oauth](https://github.com/hickford/git-credential-oauth)|Git credential helper|`a4792ccc-144e-407e-86c9-5e7d8d9c3269`|
 |[Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager)|Git credential helper|`e90ee53c-94e2-48ac-9358-a874fb9e0662`|
-|[tea](https://gitea.com/gitea/tea)|tea|`d57cb8c4-630c-4168-8324-ec79935e18d4`|
+|[Gitea CLI](https://gitea.com/gitea/cli)|Gitea CLI|`d57cb8c4-630c-4168-8324-ec79935e18d4`|
+|Gitea App|Official Gitea mobile app|`b757811a-05c8-4c76-8d74-a5ee3d2073f2`|
+|[gitea-vscode](https://gitea.com/gitea/gitea-vscode)|VS Code extension|`75a9ec3e-42b5-40cb-9144-9ea96ecd56a6`|
 
 To prevent unexpected behavior, they are being displayed as locked in the UI and their creation can instead be controlled by the `DEFAULT_APPLICATIONS` parameter in `app.ini`.
 

docs/installation/database-preparation.md

@@ -8,7 +8,7 @@ aliases:
 
 # Database Preparation
 
-You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. Only PostgreSQL and MySQL will be covered here since those database engines are widely-used in production. If you plan to use SQLite, you can ignore this chapter.
+You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. PostgreSQL, MySQL and MSSQL are covered here. If you plan to use SQLite, you can ignore this chapter.
 
 :::warning
 Converting one database type to another is not a well-tested process and you may experience issues. It is better to choose the final database type at the type of the first installation. Be aware that SQLite does not scale; if you expect your instance to grow at a later time, you should choose another database type.
@@ -177,6 +177,28 @@ All steps below requires that the database engine of your choice is installed on
 
     You should be prompted to enter password for the database user, and connected to the database.
 
+## MSSQL
+
+1. As an administrator, create the login, a database with case-sensitive collation, and its user. Replace the password `'gitea'` with a secure one:
+
+    ```sql
+    CREATE LOGIN gitea WITH PASSWORD = 'gitea';
+    CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
+    GO
+    USE giteadb;
+    CREATE USER gitea FOR LOGIN gitea;
+    ALTER ROLE db_owner ADD MEMBER gitea;
+    GO
+    ```
+
+    Upgrades change the database schema, so the user needs `db_owner`, or `db_ddladmin`, `db_datareader` and `db_datawriter`. With the latter, also run `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;` as administrator.
+
+2. On your Gitea server, test the connection to the database:
+
+    ```sh
+    sqlcmd -S 203.0.113.3 -U gitea -d giteadb
+    ```
+
 ## Database Connection over TLS
 
 If the communication between Gitea and your database instance is performed through a private network, or if Gitea and the database are running on the same server, this section can be omitted since the security between Gitea and the database instance is not critically exposed. If instead the database instance is on a public network, use TLS to encrypt the connection to the database, as it is possible for third-parties to intercept the traffic data.

docs/usage/actions/comparison.md

@@ -19,14 +19,7 @@ Gitea Actions is designed to be compatible with GitHub Actions, with the differe
 `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:` runs an action built into Gitea Runner, which needs no download and does not depend on Node.js, 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
 
@@ -92,7 +85,7 @@ See [Actions job token permissions](token-permissions.md).
 
 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`.
 See the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
-For other sources, see [Absolute action URLs](#absolute-action-urls), [Action prefixes](#action-prefixes) and [Workflow-relative actions](#workflow-relative-actions).
+For other sources, see [Absolute action URLs](#absolute-action-urls) and [Action prefixes](#action-prefixes).
 
 ### Context availability
 

docs/usage/actions/variables.md

@@ -9,53 +9,67 @@ sidebar_position: 25
 ## Environment variables
 
 These environment variables are set automatically in every workflow run and can be accessed directly (e.g. `$CI` in shell scripts).
+A `GITEA_*` name listed with a `GITHUB_*` name holds the same value.
 
 | Name | Description | Example |
 |---|---|---|
+| `ACT` | Always set to `true`, unless the runner is configured with `runner.set_act_env: false`. | `true` |
 | `CI` | Always set to `true`. | `true` |
-| `GITEA_ACTIONS` | Always set to `true`. Useful to distinguish Gitea Actions from other CI systems. | `true` |
+| `GITEA_ACTION`<br/>`GITHUB_ACTION` | The `id` of the current step, or its index when it has none. | `0` |
-| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `1.0.8` |
+| `GITEA_ACTION_PATH`<br/>`GITHUB_ACTION_PATH` | The path where the action is located. Only set in composite actions. | `/var/run/act/actions/***` |
-| `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42_***/_data` |
+| `GITEA_ACTION_REF`<br/>`GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` |
-| `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
+| `GITEA_ACTION_REPOSITORY`<br/>`GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` |
-| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/home/runner/work/_temp/_runner_file_commands/set_output_***` |
+| `GITEA_ACTIONS`<br/>`GITHUB_ACTIONS` | Always set to `true`. `GITEA_ACTIONS` is useful to distinguish Gitea Actions from other CI systems. | `true` |
-| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
+| `GITEA_ACTIONS_RUNNER_VERSION` | The version of the runner executing the workflow. | `v5.2.4` |
-| `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/home/runner/work/_temp/_runner_file_commands/save_state_***` |
+| `GITEA_ACTOR`<br/>`GITHUB_ACTOR` | The username of the user that triggered the workflow. | `alice` |
-| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/home/runner/work/_temp/_runner_file_commands/step_summary_***` |
+| `GITEA_ACTOR_ID`<br/>`GITHUB_ACTOR_ID` | The ID of the user that triggered the workflow. | `1` |
-| `GITHUB_ACTIONS` | Always set to `true`. | `true` |
+| `GITEA_API_URL`<br/>`GITHUB_API_URL` | The URL of the REST API. | `https://gitea.example.com/api/v1` |
-| `GITHUB_ACTION` | The name of the action currently running, or the step `id`. | `__run` |
+| `GITEA_BASE_REF`<br/>`GITHUB_BASE_REF` | The target branch of a pull request. | `main` |
-| `GITHUB_ACTION_PATH` | The path where the action is located. | `/home/runner/work/_actions/actions/checkout/v4` |
+| `GITEA_DOCKER_WORKSPACE` | The workspace path as the Docker daemon sees it, for bind mounts into containers a job starts, e.g. `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data` in a compose file. Only set for jobs running in a container. | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` |
-| `GITHUB_ACTION_REF` | The ref of the action being executed. | `v4` |
+| `GITEA_ENV`<br/>`GITHUB_ENV` | Path to the file that sets environment variables for subsequent steps. | `/var/run/act/workflow/envs.txt` |
-| `GITHUB_ACTION_REPOSITORY` | The owner and repository of the action. | `actions/checkout` |
+| `GITEA_EVENT_NAME`<br/>`GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` |
-| `GITHUB_ACTOR` | The username of the user that triggered the workflow. | `silverwind` |
+| `GITEA_EVENT_PATH`<br/>`GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/var/run/act/workflow/event.json` |
-| `GITHUB_API_URL` | The URL of the REST API. | `https://gitea.com/api/v1` |
+| `GITEA_GRAPHQL_URL`<br/>`GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ |
-| `GITHUB_BASE_REF` | The target branch of a pull request. | `main` |
+| `GITEA_HEAD_REF`<br/>`GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` |
-| `GITHUB_EVENT_NAME` | The name of the event that triggered the workflow. | `push` |
+| `GITEA_JOB`<br/>`GITHUB_JOB` | The `job_id` of the current job. | `build` |
-| `GITHUB_EVENT_PATH` | Path to the file containing the event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
+| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | Path to the file that sets step output parameters. | `/var/run/act/workflow/outputcmd.txt` |
-| `GITHUB_GRAPHQL_URL` | Empty in Gitea (GraphQL is not supported). | _(empty)_ |
+| `GITEA_PATH`<br/>`GITHUB_PATH` | Path to the file that adds system `PATH` entries for subsequent steps. | `/var/run/act/workflow/pathcmd.txt` |
-| `GITHUB_HEAD_REF` | The source branch of a pull request. | `feature-branch` |
+| `GITEA_REF`<br/>`GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
-| `GITHUB_JOB` | The `job_id` of the current job. | `build` |
+| `GITEA_REF_NAME`<br/>`GITHUB_REF_NAME` | The short ref name. | `main` |
-| `GITHUB_REF` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
+| `GITEA_REF_PROTECTED`<br/>`GITHUB_REF_PROTECTED` | `true` if branch protections are configured for the ref that triggered the workflow. | `true` |
-| `GITHUB_REF_NAME` | The short ref name. | `main` |
+| `GITEA_REF_TYPE`<br/>`GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
-| `GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
+| `GITEA_REPOSITORY`<br/>`GITHUB_REPOSITORY` | The owner and repository name. | `owner/repo` |
-| `GITHUB_REPOSITORY` | The owner and repository name. | `gitea/docs` |
+| `GITEA_REPOSITORY_ID`<br/>`GITHUB_REPOSITORY_ID` | The ID of the repository. | `123` |
-| `GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `gitea` |
+| `GITEA_REPOSITORY_OWNER`<br/>`GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `owner` |
-| `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. | `90` |
+| `GITEA_REPOSITORY_OWNER_ID`<br/>`GITHUB_REPOSITORY_OWNER_ID` | The ID of the repository owner. | `45` |
-| `GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
+| `GITEA_RETENTION_DAYS`<br/>`GITHUB_RETENTION_DAYS` | The number of days that artifacts are kept, empty when kept forever. | `90` |
-| `GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` |
+| `GITEA_RUN_ATTEMPT`<br/>`GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
-| `GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` |
+| `GITEA_RUN_ID`<br/>`GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` |
-| `GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.com` |
+| `GITEA_RUN_NUMBER`<br/>`GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` |
-| `GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `GITEA_SERVER_URL`<br/>`GITHUB_SERVER_URL` | The URL of the Gitea instance. | `https://gitea.example.com` |
-| `GITHUB_WORKFLOW` | The name of the workflow. | `CI` |
+| `GITEA_SHA`<br/>`GITHUB_SHA` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
-| `GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/gitea/docs` |
+| `GITEA_STATE`<br/>`GITHUB_STATE` | Path to the file that sets step state variables. | `/var/run/act/workflow/statecmd.txt` |
+| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | Path to the file for writing job summaries. | `/var/run/act/workflow/step-summary-0.md` |
+| `GITEA_TRIGGERING_ACTOR`<br/>`GITHUB_TRIGGERING_ACTOR` | The username of the user that initiated the workflow run. May differ from `GITEA_ACTOR` on re-runs. | `alice` |
+| `GITEA_WORKFLOW`<br/>`GITHUB_WORKFLOW` | The name of the workflow. | `CI` |
+| `GITEA_WORKFLOW_SHA`<br/>`GITHUB_WORKFLOW_SHA` | The commit SHA of the workflow file. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `GITEA_WORKSPACE`<br/>`GITHUB_WORKSPACE` | The default working directory on the runner. | `/workspace/owner/repo` |
+| `TRACEPARENT` | The W3C trace context of the job's span, so instrumented tools can add spans to the job's trace. Only set when the runner exports traces, see [Monitoring](/runner/monitoring/#opentelemetry). | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` |
+| `TRACESTATE` | Vendor-specific trace data that accompanies `TRACEPARENT`. Only set when the trace carries any. | `rojo=00f067aa0ba902b7` |
 
 ### Runner environment variables
 
 | Name | Description | Example |
 |---|---|---|
+| `ImageOS` | The OS and release of the job's image, read by `setup-*` actions. | `ubuntu24` |
 | `RUNNER_ARCH` | The architecture of the runner. | `X64` |
+| `RUNNER_DEBUG` | Set to `1` when the `ACTIONS_STEP_DEBUG` secret is `true`, unset otherwise. | `1` |
+| `RUNNER_ENVIRONMENT` | Always set to `self-hosted`. | `self-hosted` |
+| `RUNNER_NAME` | The name of the runner executing the job. | `my-runner` |
 | `RUNNER_OS` | The operating system of the runner. | `Linux` |
 | `RUNNER_TEMP` | Path to a temporary directory on the runner. | `/tmp` |
 | `RUNNER_TOOL_CACHE` | Path to the tool cache directory on the runner. | `/opt/hostedtoolcache` |
+| `RUNNER_WORKSPACE` | The parent directory of `GITEA_WORKSPACE`. | `/workspace/owner` |
 
 ### Internal environment variables
 
@@ -65,10 +79,10 @@ These are used internally by the runner and actions. They are typically not need
 |---|---|---|
 | `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_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 `id-token: write` is granted. | `https://gitea.example.com/api/actions/oidc/token?` |
-| `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.com` |
+| `ACTIONS_RESULTS_URL` | URL for storing artifacts. | `https://gitea.example.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/` |
+| `ACTIONS_RUNTIME_URL` | URL for the Gitea Actions pipeline API. | `https://gitea.example.com/api/actions_pipeline/` |
 
 ## Context variables
 
@@ -76,39 +90,39 @@ These variables are available in workflow expressions via `${{ gitea.<name> }}`.
 
 | Name | Description | Example |
 |---|---|---|
-| `gitea.action`<br/>`github.action` | The name of the action currently running, or the `id` of a step. | `__run` |
+| `gitea.action`<br/>`github.action` | The `id` of the current step, or its index when it has none. | `0` |
-| `gitea.action_path`<br/>`github.action_path` | The path where an action is located. Only supported in composite actions. | `/home/runner/work/_actions/actions/checkout/v4` |
+| `gitea.action_path`<br/>`github.action_path` | The path where an action is located. Only supported in composite actions. | `/var/run/act/actions/***` |
 | `gitea.action_ref`<br/>`github.action_ref` | The ref of the action being executed. | `v4` |
 | `gitea.action_repository`<br/>`github.action_repository` | The owner and repository name of the action. | `actions/checkout` |
 | `gitea.action_status`<br/>`github.action_status` | The current result of a composite action. | `success` |
-| `gitea.actor`<br/>`github.actor` | The username of the user that triggered the initial workflow run. | `silverwind` |
+| `gitea.actor`<br/>`github.actor` | The username of the user that triggered the initial workflow run. | `alice` |
-| `gitea.api_url`<br/>`github.api_url` | The URL of the REST API. | `https://gitea.com/api/v1` |
+| `gitea.api_url`<br/>`github.api_url` | The URL of the REST API. | `https://gitea.example.com/api/v1` |
 | `gitea.base_ref`<br/>`github.base_ref` | The target branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `main` |
-| `gitea.env`<br/>`github.env` | Path on the runner to the file that sets environment variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/set_env_***` |
+| `gitea.env`<br/>`github.env` | Path on the runner to the file that sets environment variables from workflow commands. | `/var/run/act/workflow/envs.txt` |
 | `gitea.event`<br/>`github.event` | The full event webhook payload as an object. See [Event payload](#event-payload). | `{...}` |
 | `gitea.event_name`<br/>`github.event_name` | The name of the event that triggered the workflow run. | `push` |
-| `gitea.event_path`<br/>`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/home/runner/work/_temp/_github_workflow/event.json` |
+| `gitea.event_path`<br/>`github.event_path` | Path on the runner to the file containing the full event webhook payload. | `/var/run/act/workflow/event.json` |
 | `gitea.head_ref`<br/>`github.head_ref` | The source branch of a pull request. Only set for `pull_request` and `pull_request_target` events. | `feature-branch` |
 | `gitea.job`<br/>`github.job` | The `job_id` of the current job. | `build` |
 | `gitea.ref`<br/>`github.ref` | The fully-formed ref that triggered the workflow. | `refs/heads/main` |
 | `gitea.ref_name`<br/>`github.ref_name` | The short ref name. | `main` |
 | `gitea.ref_protected`<br/>`github.ref_protected` | `true` if branch protections are configured for the ref that triggered the workflow run. | `true` |
 | `gitea.ref_type`<br/>`github.ref_type` | The type of ref: `branch` or `tag`. | `branch` |
-| `gitea.path`<br/>`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. Unique to each step. | `/home/runner/work/_temp/_runner_file_commands/add_path_***` |
+| `gitea.path`<br/>`github.path` | Path on the runner to the file that sets system `PATH` variables from workflow commands. | `/var/run/act/workflow/pathcmd.txt` |
-| `gitea.repository`<br/>`github.repository` | The owner and repository name. | `gitea/docs` |
+| `gitea.repository`<br/>`github.repository` | The owner and repository name. | `owner/repo` |
-| `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `gitea` |
+| `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `owner` |
-| `gitea.repositoryUrl`<br/>`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.com/gitea/docs` |
+| `gitea.repositoryUrl`<br/>`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.example.com/owner/repo` |
-| `gitea.retention_days`<br/>`github.retention_days` | The number of days that workflow run logs and artifacts are kept. | `90` |
+| `gitea.retention_days`<br/>`github.retention_days` | The number of days that artifacts are kept, empty when kept forever. | `90` |
 | `gitea.run_id`<br/>`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` |
 | `gitea.run_number`<br/>`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` |
 | `gitea.run_attempt`<br/>`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` |
 | `gitea.secret_source`<br/>`github.secret_source` | The source of a secret used in a workflow. Always `Actions` in Gitea. | `Actions` |
-| `gitea.server_url`<br/>`github.server_url` | The URL of the Gitea instance. | `https://gitea.com` |
+| `gitea.server_url`<br/>`github.server_url` | The URL of the Gitea instance. | `https://gitea.example.com` |
 | `gitea.sha`<br/>`github.sha` | The commit SHA that triggered the workflow. | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
-| `gitea.token`<br/>`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `ghs_***` |
+| `gitea.token`<br/>`github.token` | A token to authenticate on behalf of the Gitea App installed on the repository. See [Token permissions](token-permissions.md). | `***` |
-| `gitea.triggering_actor`<br/>`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `silverwind` |
+| `gitea.triggering_actor`<br/>`github.triggering_actor` | The username of the user that initiated the workflow run. May differ from `actor` on re-runs. | `alice` |
 | `gitea.workflow`<br/>`github.workflow` | The name of the workflow. If unnamed, the full path of the workflow file. | `CI` |
-| `gitea.workspace`<br/>`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/gitea/docs` |
+| `gitea.workspace`<br/>`github.workspace` | The default working directory on the runner and the default location of your repository when using the `checkout` action. | `/workspace/owner/repo` |
 | `gitea.gitea_default_actions_url` | The default URL for downloading actions. Gitea-specific. | `https://github.com` |
 
 ### Event payload
@@ -124,11 +138,11 @@ These fields exist in almost every payload:
 | Name | Description | Example |
 |---|---|---|
 | `gitea.event.action` | The activity type. Only set for events that have activity types, see [supported events](faq.md#what-workflow-trigger-events-does-gitea-support). | `opened` |
-| `gitea.event.repository.full_name` | The owner and name of the repository. | `gitea/docs` |
+| `gitea.event.repository.full_name` | The owner and name of the repository. | `owner/repo` |
 | `gitea.event.repository.default_branch` | The default branch of the repository. | `main` |
 | `gitea.event.repository.private` | Whether the repository is private. | `false` |
-| `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.com/gitea/docs` |
+| `gitea.event.repository.html_url` | The HTML URL of the repository. | `https://gitea.example.com/owner/repo` |
-| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `silverwind` |
+| `gitea.event.sender.login` | The username of the user that triggered the event. Also available as `sender.username`. | `alice` |
 
 The remaining fields are specific to one or a few events:
 
@@ -143,12 +157,12 @@ The remaining fields are specific to one or a few events:
 | `gitea.event.commits` | `push` | The commits contained in the push, each with `id`, `message`, `url`, `author`, `added`, `removed` and `modified`. | `[{...}]` |
 | `gitea.event.head_commit.message` | `push` | The message of the most recent commit of the push. | `fix: broken link` |
 | `gitea.event.total_commits` | `push` | The number of commits in the push. Gitea-specific. | `3` |
-| `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.com/gitea/docs/compare/a1b2c3d...e5f6a1b` |
+| `gitea.event.compare_url` | `push` | The URL comparing `before` with `after`. GitHub names this field `compare`. | `https://gitea.example.com/owner/repo/compare/a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2...f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5` |
-| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `silverwind` |
+| `gitea.event.pusher.login` | `push` | The username of the user that pushed. | `alice` |
-| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `silverwind/docs` |
+| `gitea.event.forkee.full_name` | `fork` | The owner and name of the new fork. | `alice/repo` |
 | `gitea.event.page` | `gollum` | The name of the wiki page. | `Home` |
 | `gitea.event.number` | `issues`, `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The index of the issue or pull request. Not set for `issue_comment`, use `gitea.event.issue.number` there. | `386` |
-| `gitea.event.issue.number`<br/>`gitea.event.issue.title`<br/>`gitea.event.issue.body`<br/>`gitea.event.issue.state`<br/>`gitea.event.issue.labels`<br/>`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Expand gitea.event in actions docs` |
+| `gitea.event.issue.number`<br/>`gitea.event.issue.title`<br/>`gitea.event.issue.body`<br/>`gitea.event.issue.state`<br/>`gitea.event.issue.labels`<br/>`gitea.event.issue.user.login` | `issues`, `issue_comment` | The issue the event happened on. | `Fix typo in README` |
 | `gitea.event.comment.body` | `issue_comment` | The body of the comment. | `LGTM` |
 | `gitea.event.is_pull` | `issue_comment` | Whether the comment was made on a pull request. Gitea-specific, GitHub sets `issue.pull_request` on the issue object instead. | `true` |
 | `gitea.event.pull_request.number`<br/>`gitea.event.pull_request.title`<br/>`gitea.event.pull_request.body`<br/>`gitea.event.pull_request.draft`<br/>`gitea.event.pull_request.merged`<br/>`gitea.event.pull_request.state`<br/>`gitea.event.pull_request.labels`<br/>`gitea.event.pull_request.user.login` | `pull_request`, `pull_request_target`, `pull_request_review`, `pull_request_review_comment` | The pull request the event happened on. | `Add caching to CI` |

docs/usage/packages/overview.md

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

docs/usage/packages/terraform-module.md

@@ -0,0 +1,170 @@
+---
+date: "2026-06-09T00:00:00+00:00"
+slug: "terraform-module"
+sidebar_position: 119
+---
+
+# Terraform Module Registry
+
+Publish [Terraform](https://www.terraform.io/) modules for your user or organization and use them
+from Terraform or Terragrunt. The registry implements the
+[HashiCorp module registry protocol](https://developer.hashicorp.com/terraform/internals/module-registry-protocol),
+so modules are referenced with the usual `HOST/NAMESPACE/NAME/PROVIDER` address.
+
+## Requirements
+
+- The [Terraform CLI](https://developer.hashicorp.com/terraform/install) or
+  [Terragrunt](https://terragrunt.gruntwork.io/).
+- **Your Gitea instance must be served over HTTPS with a valid certificate.**
+  Terraform and Terragrunt only perform module registry discovery over HTTPS and reject
+  plain HTTP — including `http://localhost`. This is a requirement of the protocol, not of Gitea.
+
+A module is addressed by three segments:
+
+| Segment     | Meaning                                                        |
+| ----------- | ------------------------------------------------------------- |
+| `namespace` | The owner of the module: a Gitea user or organization name. It must follow the same rules as `name`, so owners with a `.` in their name cannot publish modules. |
+| `name`      | The module name. Letters, digits, `-` and `_`, starting and ending with a letter or digit, up to 64 characters. |
+| `provider`  | The main provider the module targets, e.g. `aws`. Lowercase letters and digits, up to 64 characters. |
+
+Versions follow [semantic versioning](https://semver.org/) and are stored in canonical form: a
+leading `v` is dropped and missing segments are padded, so `v1.2.3` and `1.2.3` address the same
+version, and `1.2` becomes `1.2.0`.
+
+## Packaging a module
+
+A module is published as a single `.tar.gz` archive, stored and served exactly as uploaded. The
+module's `.tf` files must therefore be at the **archive root**. A source tarball downloaded from a Git
+host wraps everything in a `repository-version/` directory and is rejected — repackage the module
+directory's contents instead:
+
+```shell
+tar -czf vpc-1.0.0.tar.gz -C path/to/module .
+```
+
+The root module's inputs, outputs, providers and `README` are shown on the package page. Each
+submodule found under `modules/<name>` is listed with its source address and links to its own page,
+which shows the install snippet for that submodule along with its inputs, outputs, providers and
+`README`. Only one level is indexed, so `modules/<name>/<nested>` is not listed. Anything else,
+including `examples/`, is kept in the archive but is not indexed. A module that is only a collection of
+submodules, with no root module, is also accepted. Files in JSON syntax (`.tf.json`) are accepted too,
+but only `.tf` files are indexed.
+
+## Authentication
+
+Create a [personal access token](development/api-usage.md#authentication) with the `read:package` scope to download
+private modules, and `write:package` to publish or delete them. Add it to your Terraform CLI
+configuration file (`~/.terraformrc` or `%APPDATA%/terraform.rc`):
+
+```hcl
+credentials "gitea.example.com" {
+  token = "<your token>"
+}
+```
+
+Modules owned by a public user or organization can be downloaded without a token.
+
+## Publishing a module
+
+Upload an archive with a `PUT` request, sending the file as the raw request body. Use
+`curl --upload-file` rather than `--data-binary`: the latter sends a form content type that
+the registry will not accept as an archive.
+
+```shell
+curl --user "your_username:your_token" \
+  --upload-file vpc-1.0.0.tar.gz \
+  https://gitea.example.com/api/packages/-/terraform/modules/{namespace}/{name}/{provider}/{version}
+```
+
+| Parameter   | Description                            |
+| ----------- | -------------------------------------- |
+| `namespace` | The owner (user or organization).      |
+| `name`      | The module name.                       |
+| `provider`  | The provider the module targets.       |
+| `version`   | The module version (semver).           |
+
+For example, to publish version `1.0.0` of the `vpc` module for the `aws` provider under the `acme`
+organization:
+
+```shell
+curl --user "your_username:your_token" \
+  --upload-file vpc-1.0.0.tar.gz \
+  https://gitea.example.com/api/packages/-/terraform/modules/acme/vpc/aws/1.0.0
+```
+
+A successful upload returns `201 Created`. Published versions are immutable: uploading a version that
+already exists returns `409 Conflict`. To replace a version, delete it first.
+
+## Linking a module to a repository
+
+A module always lives in a user or organization's package space — its namespace is that user or
+organization, never a repository, because the registry address (`HOST/NAMESPACE/NAME/PROVIDER`) has no
+repository segment. You cannot publish "into" a repository. Instead, a repository link is a display
+association that surfaces the module on a repository's **Packages** tab. The workflow is:
+
+1. **Publish** the module to the user or organization namespace, exactly as shown in
+   [Publishing a module](#publishing-a-module).
+2. **Link** the package to a repository owned by that same user or organization: open the package,
+   go to its **Settings**, and select the repository (or use the
+   `POST /api/v1/packages/{owner}/terraform-module/{name}%2F{provider}/-/link/{repo}` API).
+
+The link applies to the whole module — all of its versions, including ones published later — and can
+be changed or removed at any time. It only affects where the module is listed in the UI; the address
+used to consume it is unchanged (still `HOST/NAMESPACE/NAME/PROVIDER`, with no repository in it).
+
+## Consuming a module
+
+Reference the module by its registry address. With Terraform:
+
+```hcl
+module "vpc" {
+  source  = "gitea.example.com/acme/vpc/aws"
+  version = "~> 1.0"
+}
+```
+
+To use a submodule, append its path with the standard `//` separator:
+
+```hcl
+module "network" {
+  source  = "gitea.example.com/acme/infra/google//modules/network"
+  version = "~> 1.0"
+}
+```
+
+With Terragrunt, use the `tfr://` scheme and pass the version as a query parameter:
+
+```hcl
+terraform {
+  source = "tfr://gitea.example.com/acme/vpc/aws?version=1.0.0"
+}
+```
+
+`terraform init` (or `terragrunt init`) resolves the address through the service discovery document
+at `https://gitea.example.com/.well-known/terraform.json` and downloads the matching version.
+
+## Deleting a version
+
+```shell
+curl --user "your_username:your_token" \
+  --request DELETE \
+  https://gitea.example.com/api/packages/-/terraform/modules/acme/vpc/aws/1.0.0
+```
+
+A successful delete returns `204 No Content`. This requires the `write:package` scope. There is no
+separate deprecation flow — deleting a version removes it from the registry.
+
+## Limits
+
+The stored archive is bounded by the instance-wide package limits (`LIMIT_SIZE_TERRAFORM_MODULE` and
+`LIMIT_TOTAL_OWNER_SIZE`) set by your Gitea administrator; see the
+[configuration cheat sheet](../../administration/config-cheat-sheet.md#packages-packages).
+
+Independently of those settings, an archive may not exceed **32 MiB decompressed**. The registry
+reads the whole archive to index it, and stops with `413 Request Entity Too Large` past that ceiling,
+so raising `LIMIT_SIZE_TERRAFORM_MODULE` above 32 MiB does not allow larger modules. Real modules are
+kilobyte-scale, so this only affects archives carrying unrelated payloads.
+
+A `README` larger than **1 MiB**, of the root module or of a submodule, is not shown on the package
+page. The module is still accepted and the file stays in the archive.
+

docs/usage/projects/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Projects",
+  "position": 60,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/projects",
+    "description": "Plan and track work with project boards"
+  }
+}

docs/usage/projects/project-workflows.md

@@ -0,0 +1,82 @@
+---
+date: "2025-11-25T18:58:22Z"
+slug: "project-workflows"
+sidebar_position: 1
+description: "Automate project boards with event-driven filters and actions."
+---
+
+# Project Workflows
+
+Project workflows automate a project board. When an issue or pull request in the project triggers an event, each enabled workflow for that event checks its filters and applies its actions. Workflows run in Gitea and need no runner.
+
+## Edit workflows
+
+1. Open a project and select **Workflows**.
+2. Select an event in the sidebar.
+3. Set filters and actions, then select **Save**. To change an existing workflow, select **Edit** first.
+
+An event can have several workflows. **Clone** copies the selected workflow so you can adapt it to other items. **Disable** pauses a workflow and keeps its configuration. **Remove** deletes it.
+
+## Events
+
+| Event | Runs when | Filters | Actions |
+| --- | --- | --- | --- |
+| Item added to project | An item is added to the project or created in it | Apply to, labels | Move to column, labels, issue state |
+| Item removed from project | An item is removed from the project | Apply to, labels | Labels, issue state |
+| Item reopened | An item is reopened | Apply to, labels | Move to column, labels |
+| Item closed | An item is closed | Apply to, labels | Move to column, labels |
+| Item column changed | An item moves to another column | Apply to, columns, labels | Labels, issue state |
+| Code changes requested | An official reviewer requests changes on a pull request | Labels | Move to column, labels |
+| Code review approved | An official reviewer approves a pull request | Labels | Move to column, labels |
+| Pull request merged | A pull request is merged | Labels | Move to column, labels |
+
+## Filters
+
+A workflow without filters runs for every item.
+
+- **Apply to**: issues, pull requests, or both.
+- **When moved from column**, **When moved to column**: the column the item left or entered.
+- **Only if it has labels**: the item must have all selected labels.
+
+## Actions
+
+A workflow needs at least one action. Actions run in this order:
+
+1. **Move to column**: moves the item to a column.
+2. **Add labels**, **Remove labels**: changes the item's labels.
+3. **Issue state**: closes or reopens the item. Workflows never reopen pull requests.
+
+Workflow changes appear in the timeline as "Project workflow" followed by the event, and don't trigger other workflows. Workflows don't run in closed projects or for items in archived repositories.
+
+## Permissions
+
+Anyone who can read a project can view its workflows. Managing them requires write access to the project and:
+
+- Repository project: write access to the repository's issues and pull requests.
+- Organization project: organization owner or site administrator.
+- User project: the project's owner.
+
+Access tokens limited to public repositories can't manage workflows for organization or user projects. Workflows apply their actions regardless of who triggered the event.
+
+## API
+
+Manage workflows under the project routes of a repository (`/repos/{owner}/{repo}/projects/{id}`), an organization (`/orgs/{org}/projects/{id}`) or the authenticated user (`/user/projects/{id}`):
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `.../workflows` | List workflows |
+| `GET` | `.../workflows/{workflow_id}` | Get a workflow |
+| `POST` | `.../workflows` | Create a workflow |
+| `PATCH` | `.../workflows/{workflow_id}` | Edit a workflow, omitted fields stay unchanged |
+| `DELETE` | `.../workflows/{workflow_id}` | Delete a workflow |
+
+A workflow has an `event` (`item_added_to_project`, `item_removed_from_project`, `item_reopened`, `item_closed`, `item_column_changed`, `code_changes_requested`, `code_review_approved` or `pull_request_merged`), an `enabled` flag, `filters` (`issue_type`, `source_column_id`, `target_column_id`, `label_ids`) and `actions` (`column_id`, `add_label_ids`, `remove_label_ids`, `issue_state`). Each event accepts only the filters and actions listed in [Events](#events).
+
+## Example
+
+To route new bug reports to triage, create a workflow for **Item added to project**:
+
+- **Apply to**: Issues only
+- **Only if it has labels**: `bug`
+- **Move to column**: Triage
+- **Add labels**: `needs-triage`

docs/usage/repository/code-owners.md

@@ -9,25 +9,36 @@ aliases:
 
 # Code Owners
 
-Gitea maintains code owner files. It looks for it in the following locations in this order:
+Gitea reads the first CODEOWNERS file found at these locations, in order:
 
 - `./CODEOWNERS`
 - `./docs/CODEOWNERS`
 - `./.gitea/CODEOWNERS`
 
-And stops at the first found file.
+Pull requests use the base branch's rules. File views show owners from the commit
+being viewed, including when browsing a branch, tag, or historical commit.
 
-File format: `<regexp rule> <@user or @org/team> [@user or @org/team]...`
+## Patterns and owners
 
-Regexp specified in golang Regex format.
+Each rule contains a pattern followed by users or organization teams.
-Regexp can start with `!` for negative rules - match all files except specified.
+
+Patterns starting with `*` or containing `/*` are parsed as glob expressions.
+General patterns are parsed as regular expressions.
+A leading `!` inverts a match.
+
+Special rule characters like space, backslash and `#` must be escaped with a backslash.
+When using regexp, since backslash needs to be escaped in rule level, literal dot should be written as  `\\.`
 
 Example file:
 
-```bash
+```text
-.*\\.go @user1 @user2 # This is comment
+*.js @alice @bob       # This is an inline comment
+doc/*.md @charles      # Patterns starting with "*" or containing "/*" are parsed as glob
+src/**/db*.py @david   # Use "**" to match any-level sub directories
+
+.*\\.go @user1 @user2   # General patterns are parsed as regexp
+test\\..*\\.js @user3   # !!! Do remeber: NOT "test.*.js", only regexp can be used for such cases
 
-# Comment too
 # You can assigning code owning for users or teams
 frontend/src/.*\\.js @org1/team1 @org1/team2 @user3
 
@@ -42,24 +53,69 @@ docs/(aws|google|azure)/[^/]*\\.(md|txt) @user8 @org1/team4
 Code owners listed in this file will automatically be requested to review pull requests
 that modify files matching at least one corresponding rule.
 
-### Escaping
+## Sections
 
-You can escape characters `#`, ` ` (space) and `\` with `\`, like:
+A section heading can supply default owners for the rules that follow it:
 
+```text
+[Documentation] @org1/team-doc
+*.md
+README.md @alice
+
+[Frontend] @bob
+*.js
 ```
+
+Owners on a rule replace the section's default owners. Section names are
+case-insensitive; repeated headings belong to the same section. For each file, the
+last matching rule in each named section applies. Matching rules outside named
+sections retain Gitea's existing behavior: they all apply.
+
+## Review request annotations
+
+Use `## review-request=true` or `## review-request=false` to control automatic
+review requests. A line annotation overrides a section annotation, which overrides
+the global value. When none is set, individual code owners receive automatic review
+requests only if they watch the repository and include pull requests in their watch
+preferences. Team-level requests are enabled by default. An explicit `true` requests
+a review regardless of the individual owner's watch preferences; `false` disables
+automatic requests for the rule.
+
+```text
+## review-request=false # global default for following rules
+
+*.js @alice ## review-request=true # only this rule
+
+[Documentation] @org1/team-doc ## review-request=true
+*.md
+private/* @bob ## review-request=false
+```
+
+A standalone annotation changes the global default for subsequent rules.
+Annotations on section headings apply until the next heading. Ordinary comments
+start with `#`, including comments after annotations.
+
+Disabling review requests keeps code owners visible when viewing a file and
+does not waive approvals required by branch protection.
+
+## Escaping
+
+You need to escape characters `#`, ` ` (space) and `\` with backslash `\`, e.g.:
+
+```text
 dir/with\#hashtag @user1
 path\ with\ space @user2
 path/with\\backslash @user3
 ```
 
-Some character (`.+*?()|[]{}^$\`) should be escaped with `\\` inside regexp, like:
+Some regexp characters (`.+*?()|[]{}^$\`) should be escaped with `\\`, e.g.:
 
 ```
 path/\\.with\\.dots
 path/with\\+plus
 ```
 
-### Branch Protection Rules
+## Branch Protection Rules
 
 When setting up branch protection rules, you may choose to enforce code owner approval of
 modified files. This will block a PR from being merged until at least one code owner
@@ -67,7 +123,7 @@ has given approval for every applicable rule listed in the `CODEOWNERS` file.
 
 For example, say you have the following `CODEOWNERS` file:
 
-```bash
+```text
 .*\\.go @Bob
 .*\\.md @Sally @Chris
 migrations/.* @Alice

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

@@ -141,7 +141,7 @@ aliases:
 - `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: 在默认的 squash 合并消息中，包括构成拉取请求的所有提交的提交消息。
 - `ADD_CO_COMMITTER_TRAILERS`: **true**: 如果提交者与作者不匹配，在合并提交消息中添加`co-authored-by`和`co-committed-by`标记。
 - `RETARGET_CHILDREN_ON_MERGE`: **true**: 当父合并请求被合并时，将子合并请求重新定向到父合并请求的目标分支。仅适用于头分支和基分支指向同一仓库的已合并合并请求。
-- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: 为新仓库设置"合并后默认删除合并请求分支"的默认值。
+- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **true**: 为新仓库设置"合并后默认删除合并请求分支"的默认值。
 
 ### 仓库 - 工单 (`repository.issue`)
 
@@ -524,7 +524,8 @@ Gitea 创建以下非唯一队列：
 - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: 反向代理认证的 HTTP 头部名称，用于提供用户信息。
 - `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: 反向代理认证的 HTTP 头部名称，用于提供邮箱信息。
 - `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: 反向代理认证的 HTTP 头部名称，用于提供全名信息。
-- `REVERSE_PROXY_LIMIT`: **1**: 解释 X-Forwarded-For 标头或 X-Real-IP 标头，并将其设置为请求的远程 IP。
+- `REVERSE_PROXY_LIMIT`: **1**: 按顺序解释 X-Real-IP、X-Forwarded-For 或 Forwarded 标头，并将其设置为请求的远程 IP。
+  客户端端口取自标头值，或在使用 X-Real-IP 时取自 X-Real-Port。
   可信代理计数。设置为零以不使用这些标头。
 - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: 逗号分隔的受信任代理服务器的 IP 地址和网络列表。使用 `*` 来信任全部。
 - `DISABLE_GIT_HOOKS`: **true**: 设置为 `false` 以允许具有 Git 钩子权限的用户创建自定义 Git 钩子。
@@ -1195,7 +1196,7 @@ In-Reply-To =
 - `JWT_SECRET_URI`：**_empty_**: 可以使用此配置选项，而不是在配置中定义`JWT_SECRET`，以向 Gitea 提供包含密钥的文件的路径（示例值：`file:/etc/gitea/oauth2_jwt_secret`）。
 - `JWT_SIGNING_PRIVATE_KEY_FILE`：**jwt/private.pem**: 用于签署 OAuth2 令牌的私钥文件路径。路径相对于`APP_DATA_PATH`。仅当`JWT_SIGNING_ALGORITHM`设置为`RS256`，`RS384`，`RS512`，`ES256`，`ES384`或`ES512`时才需要此设置。文件必须包含 PKCS8 格式的 RSA 或 ECDSA 私钥。如果不存在密钥，则将为您创建一个 4096 位密钥。
 - `MAX_TOKEN_LENGTH`：**32767**: 从 OAuth2 提供者接受的令牌/cookie 的最大长度。
-- `DEFAULT_APPLICATIONS`：**git-credential-oauth，git-credential-manager, tea**: 在启动时预注册用于某些服务的 OAuth 应用程序。有关可用选项列表，请参阅[OAuth2 文档](/development/oauth2-provider.md)。
+- `DEFAULT_APPLICATIONS`：**git-credential-oauth, git-credential-manager, gitea-cli, gitea-app, gitea-vscode**: 在启动时预注册用于某些服务的 OAuth 应用程序。有关可用选项列表，请参阅[OAuth2 文档](/development/oauth2-provider.md)。
 
 ## i18n (`i18n`)
 

i18n/zh-cn/docs/current/installation/database-preparation.md

@@ -8,7 +8,7 @@ aliases:
 
 # 数据库准备
 
-在使用 Gitea 前，您需要准备一个数据库。Gitea 支持 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（内置） 和 MSSQL（>= 2012 SP4）这几种数据库。本页将指导您准备数据库。由于 PostgreSQL 和 MySQL 在生产环境中被广泛使用，因此本文档将仅涵盖这两种数据库。如果您计划使用 SQLite，则可以忽略本章内容。
+在使用 Gitea 前，您需要准备一个数据库。Gitea 支持 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（内置） 和 MSSQL（>= 2012 SP4）这几种数据库。本页将指导您准备数据库。本文档涵盖 PostgreSQL、MySQL 和 MSSQL。如果您计划使用 SQLite，则可以忽略本章内容。
 
 如果您使用不受支持的数据库版本，请通过 [联系我们](/help/support) 以获取有关我们的扩展支持的信息。我们可以为旧数据库提供测试和支持，并将这些修复集成到 Gitea 代码库中。
 
@@ -168,6 +168,28 @@ aliases:
 
    您应该会被提示输入数据库用户的密码，并连接到数据库。
 
+## MSSQL
+
+1. 以管理员身份创建登录名、使用大小写敏感排序规则的数据库及其用户。请将密码 `'gitea'` 替换为安全的密码：
+
+   ```sql
+   CREATE LOGIN gitea WITH PASSWORD = 'gitea';
+   CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
+   GO
+   USE giteadb;
+   CREATE USER gitea FOR LOGIN gitea;
+   ALTER ROLE db_owner ADD MEMBER gitea;
+   GO
+   ```
+
+   升级会更改数据库结构，因此该用户需要 `db_owner`，或者 `db_ddladmin`、`db_datareader` 和 `db_datawriter`。使用后者时，还需以管理员身份执行 `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;`。
+
+2. 在您的 Gitea 服务器上，测试与数据库的连接：
+
+   ```sh
+   sqlcmd -S 203.0.113.3 -U gitea -d giteadb
+   ```
+
 ## 使用 TLS 进行数据库连接
 
 如果 Gitea 和您的数据库实例之间的通信是通过私有网络进行的，或者如果 Gitea 和数据库运行在同一台服务器上，那么可以省略本节，因为 Gitea 和数据库实例之间的安全性不会受到严重威胁。但是，如果数据库实例位于公共网络上，请使用 TLS 对数据库连接进行加密，以防止第三方拦截流量数据。

i18n/zh-cn/docs/current/usage/actions/comparison.md

@@ -21,15 +21,7 @@ Gitea Actions旨在与GitHub Actions兼容，差异如下。
 `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:`运行Gitea Runner内置的Action，无需下载，也不依赖Node.js，例如`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
 
@@ -95,7 +87,7 @@ Gitea Actions旨在与GitHub 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)。
+其他来源请参阅[Action URL绝对路径](#absolute-action-urls)和[Action前缀](#action-prefixes)。
 
 ### 上下文可用性
 

i18n/zh-cn/docs/current/usage/actions/variables.md

@@ -6,10 +6,90 @@ sidebar_position: 25
 
 # 变量
 
+## 环境变量
+
+以下环境变量会在每次工作流运行时自动设置，可以直接访问（例如在 shell 脚本中使用 `$CI`）。
+同时列出 `GITEA_*` 和 `GITHUB_*` 名称的变量值相同。
+
+| 名称 | 描述 | 示例 |
+|---|---|---|
+| `ACT` | 始终为 `true`，除非 Runner 配置了 `runner.set_act_env: false`。 | `true` |
+| `CI` | 始终为 `true`。 | `true` |
+| `GITEA_ACTION`<br/>`GITHUB_ACTION` | 当前步骤的 `id`，未设置时为步骤的序号。 | `0` |
+| `GITEA_ACTION_PATH`<br/>`GITHUB_ACTION_PATH` | Action 所在的路径。仅在复合 Action 中设置。 | `/var/run/act/actions/***` |
+| `GITEA_ACTION_REF`<br/>`GITHUB_ACTION_REF` | 正在执行的 Action 的 ref。 | `v4` |
+| `GITEA_ACTION_REPOSITORY`<br/>`GITHUB_ACTION_REPOSITORY` | Action 的所有者和仓库名称。 | `actions/checkout` |
+| `GITEA_ACTIONS`<br/>`GITHUB_ACTIONS` | 始终为 `true`。`GITEA_ACTIONS` 可用于区分 Gitea Actions 和其他 CI 系统。 | `true` |
+| `GITEA_ACTIONS_RUNNER_VERSION` | 执行工作流的 Runner 的版本。 | `v5.2.4` |
+| `GITEA_ACTOR`<br/>`GITHUB_ACTOR` | 触发工作流的用户的用户名。 | `alice` |
+| `GITEA_ACTOR_ID`<br/>`GITHUB_ACTOR_ID` | 触发工作流的用户的 ID。 | `1` |
+| `GITEA_API_URL`<br/>`GITHUB_API_URL` | REST API 的 URL。 | `https://gitea.example.com/api/v1` |
+| `GITEA_BASE_REF`<br/>`GITHUB_BASE_REF` | 拉取请求的目标分支。 | `main` |
+| `GITEA_DOCKER_WORKSPACE` | Docker 守护进程所见的工作区路径，用于绑定挂载到 Job 启动的容器中，例如在 compose 文件中使用 `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data`。仅在 Job 运行于容器中时设置。 | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` |
+| `GITEA_ENV`<br/>`GITHUB_ENV` | 为后续步骤设置环境变量的文件路径。 | `/var/run/act/workflow/envs.txt` |
+| `GITEA_EVENT_NAME`<br/>`GITHUB_EVENT_NAME` | 触发工作流的事件名称。 | `push` |
+| `GITEA_EVENT_PATH`<br/>`GITHUB_EVENT_PATH` | 包含事件 Webhook 负载的文件路径。 | `/var/run/act/workflow/event.json` |
+| `GITEA_GRAPHQL_URL`<br/>`GITHUB_GRAPHQL_URL` | 在 Gitea 中为空（不支持 GraphQL）。 | _（空）_ |
+| `GITEA_HEAD_REF`<br/>`GITHUB_HEAD_REF` | 拉取请求的源分支。 | `feature-branch` |
+| `GITEA_JOB`<br/>`GITHUB_JOB` | 当前 Job 的 `job_id`。 | `build` |
+| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | 设置步骤输出参数的文件路径。 | `/var/run/act/workflow/outputcmd.txt` |
+| `GITEA_PATH`<br/>`GITHUB_PATH` | 为后续步骤添加系统 `PATH` 条目的文件路径。 | `/var/run/act/workflow/pathcmd.txt` |
+| `GITEA_REF`<br/>`GITHUB_REF` | 触发工作流的完整 ref。 | `refs/heads/main` |
+| `GITEA_REF_NAME`<br/>`GITHUB_REF_NAME` | ref 的短名称。 | `main` |
+| `GITEA_REF_PROTECTED`<br/>`GITHUB_REF_PROTECTED` | 如果触发工作流的 ref 配置了分支保护，则为 `true`。 | `true` |
+| `GITEA_REF_TYPE`<br/>`GITHUB_REF_TYPE` | ref 的类型：`branch` 或 `tag`。 | `branch` |
+| `GITEA_REPOSITORY`<br/>`GITHUB_REPOSITORY` | 所有者和仓库名称。 | `owner/repo` |
+| `GITEA_REPOSITORY_ID`<br/>`GITHUB_REPOSITORY_ID` | 仓库的 ID。 | `123` |
+| `GITEA_REPOSITORY_OWNER`<br/>`GITHUB_REPOSITORY_OWNER` | 仓库所有者的用户名。 | `owner` |
+| `GITEA_REPOSITORY_OWNER_ID`<br/>`GITHUB_REPOSITORY_OWNER_ID` | 仓库所有者的 ID。 | `45` |
+| `GITEA_RETENTION_DAYS`<br/>`GITHUB_RETENTION_DAYS` | Artifact 的保留天数，永久保留时为空。 | `90` |
+| `GITEA_RUN_ATTEMPT`<br/>`GITHUB_RUN_ATTEMPT` | 工作流运行的尝试次数。 | `1` |
+| `GITEA_RUN_ID`<br/>`GITHUB_RUN_ID` | 每次工作流运行的唯一编号。 | `1234` |
+| `GITEA_RUN_NUMBER`<br/>`GITHUB_RUN_NUMBER` | 特定工作流每次运行的唯一编号。 | `42` |
+| `GITEA_SERVER_URL`<br/>`GITHUB_SERVER_URL` | Gitea 实例的 URL。 | `https://gitea.example.com` |
+| `GITEA_SHA`<br/>`GITHUB_SHA` | 触发工作流的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `GITEA_STATE`<br/>`GITHUB_STATE` | 设置步骤状态变量的文件路径。 | `/var/run/act/workflow/statecmd.txt` |
+| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | 写入 Job 摘要的文件路径。 | `/var/run/act/workflow/step-summary-0.md` |
+| `GITEA_TRIGGERING_ACTOR`<br/>`GITHUB_TRIGGERING_ACTOR` | 发起工作流运行的用户的用户名。重新运行时可能与 `GITEA_ACTOR` 不同。 | `alice` |
+| `GITEA_WORKFLOW`<br/>`GITHUB_WORKFLOW` | 工作流的名称。 | `CI` |
+| `GITEA_WORKFLOW_SHA`<br/>`GITHUB_WORKFLOW_SHA` | 工作流文件的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `GITEA_WORKSPACE`<br/>`GITHUB_WORKSPACE` | Runner 上的默认工作目录。 | `/workspace/owner/repo` |
+| `TRACEPARENT` | Job span 的 W3C 追踪上下文，供已接入追踪的工具将 span 添加到 Job 的追踪中。仅在 Runner 导出追踪数据时设置，参见[监控](/runner/monitoring/#opentelemetry)。 | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` |
+| `TRACESTATE` | 随 `TRACEPARENT` 附带的厂商特定追踪数据。仅在追踪包含此类数据时设置。 | `rojo=00f067aa0ba902b7` |
+
+### Runner 环境变量
+
+| 名称 | 描述 | 示例 |
+|---|---|---|
+| `ImageOS` | Job 镜像的操作系统和版本，供 `setup-*` Action 读取。 | `ubuntu24` |
+| `RUNNER_ARCH` | Runner 的架构。 | `X64` |
+| `RUNNER_DEBUG` | 当 `ACTIONS_STEP_DEBUG` 密钥为 `true` 时设置为 `1`，否则不设置。 | `1` |
+| `RUNNER_ENVIRONMENT` | 始终为 `self-hosted`。 | `self-hosted` |
+| `RUNNER_NAME` | 执行 Job 的 Runner 的名称。 | `my-runner` |
+| `RUNNER_OS` | Runner 的操作系统。 | `Linux` |
+| `RUNNER_TEMP` | Runner 上临时目录的路径。 | `/tmp` |
+| `RUNNER_TOOL_CACHE` | Runner 上工具缓存目录的路径。 | `/opt/hostedtoolcache` |
+| `RUNNER_WORKSPACE` | `GITEA_WORKSPACE` 的父目录。 | `/workspace/owner` |
+
+### 内部环境变量
+
+这些变量供 Runner 和 Action 内部使用，工作流中通常不需要直接使用。
+
+| 名称 | 描述 | 示例 |
+|---|---|---|
+| `ACTIONS_CACHE_URL` | Actions 缓存服务的 URL。 | `http://192.168.1.10:8088/` |
+| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | 用于 OIDC 请求的令牌。仅在授予 `id-token: write` 时设置。 | `***` |
+| `ACTIONS_ID_TOKEN_REQUEST_URL` | 请求 OIDC 令牌的 URL。仅在授予 `id-token: write` 时设置。 | `https://gitea.example.com/api/actions/oidc/token?` |
+| `ACTIONS_RESULTS_URL` | 存储 Artifact 的 URL。 | `https://gitea.example.com` |
+| `ACTIONS_RUNTIME_TOKEN` | Actions 流水线 API 的认证令牌。 | `***` |
+| `ACTIONS_RUNTIME_URL` | Gitea Actions 流水线 API 的 URL。 | `https://gitea.example.com/api/actions_pipeline/` |
+
+## 用户定义的变量
+
 您可以创建用户、组织和仓库级别的变量。变量的级别取决于创建它的位置。当创建变量时，变量的名称会被
 转换为大写，在yaml文件中引用时需要使用大写。
 
-## 命名规则
+### 命名规则
 
 以下规则适用于变量名：
 
@@ -20,11 +100,11 @@ sidebar_position: 25
 - 变量名称在创建它们的级别上必须是唯一的。
 - 变量名称不能为 `CI`。
 
-## 使用
+### 使用
 
 创建配置变量后，它们将自动填充到 `vars` 上下文中。您可以在工作流中使用类似 `${{ vars.VARIABLE_NAME }}` 这样的表达式来使用它们。
 
-## 优先级
+### 优先级
 
 如果同名变量存在于多个级别，则级别最低的变量优先。
 仓库级别的变量总是比组织或者用户级别的变量优先被选中。

i18n/zh-cn/docs/current/usage/projects/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "项目",
+  "position": 60,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/projects",
+    "description": "使用项目看板规划和跟踪工作"
+  }
+}

i18n/zh-cn/docs/current/usage/projects/project-workflows.md

@@ -0,0 +1,82 @@
+---
+date: "2025-11-25T18:58:22Z"
+slug: "project-workflows"
+sidebar_position: 1
+description: "通过事件驱动的过滤器和动作自动化项目看板。"
+---
+
+# 项目工作流
+
+项目工作流可自动化项目看板。当项目中的问题或合并请求触发事件时，该事件下每个已启用的工作流都会检查其过滤条件并执行相应动作。工作流在 Gitea 中运行，无需运行器。
+
+## 编辑工作流
+
+1. 打开项目并选择 **Workflows**。
+2. 在侧边栏中选择事件。
+3. 设置过滤器和动作，然后选择 **Save**。要修改现有工作流，请先选择 **Edit**。
+
+一个事件可以有多个工作流。**Clone** 会复制选中的工作流，便于调整后用于其他条目。**Disable** 会暂停工作流并保留其配置。**Remove** 会删除工作流。
+
+## 事件
+
+| 事件 | 触发时机 | 过滤器 | 动作 |
+| --- | --- | --- | --- |
+| Item added to project | 条目被添加到项目或在项目中创建时 | Apply to、标签 | Move to column、标签、问题状态 |
+| Item removed from project | 条目被移出项目时 | Apply to、标签 | 标签、问题状态 |
+| Item reopened | 条目被重新打开时 | Apply to、标签 | Move to column、标签 |
+| Item closed | 条目被关闭时 | Apply to、标签 | Move to column、标签 |
+| Item column changed | 条目移至另一列时 | Apply to、列、标签 | 标签、问题状态 |
+| Code changes requested | 正式审查者要求修改合并请求时 | 标签 | Move to column、标签 |
+| Code review approved | 正式审查者批准合并请求时 | 标签 | Move to column、标签 |
+| Pull request merged | 合并请求被合并时 | 标签 | Move to column、标签 |
+
+## 过滤器
+
+未设置过滤器的工作流会对每个条目运行。
+
+- **Apply to**：问题、合并请求或两者。
+- **When moved from column**、**When moved to column**：条目离开或进入的列。
+- **Only if it has labels**：条目必须包含所有选中的标签。
+
+## 动作
+
+工作流至少需要一个动作。动作按以下顺序执行：
+
+1. **Move to column**：将条目移至某一列。
+2. **Add labels**、**Remove labels**：更改条目的标签。
+3. **Issue state**：关闭或重新打开条目。工作流不会重新打开合并请求。
+
+工作流所做的更改在时间线中显示为“Project workflow”及其后的事件名称，且不会触发其他工作流。工作流不会在已关闭的项目中运行，也不会处理已归档仓库中的条目。
+
+## 权限
+
+任何拥有项目读取权限的人都可以查看其工作流。管理工作流需要项目的写入权限，并满足以下条件：
+
+- 仓库项目：拥有该仓库的问题和合并请求的写入权限。
+- 组织项目：是组织所有者或站点管理员。
+- 用户项目：是项目所有者。
+
+仅限公开仓库的访问令牌无法管理组织或用户项目的工作流。无论谁触发事件，工作流都会执行其动作。
+
+## API
+
+可通过仓库（`/repos/{owner}/{repo}/projects/{id}`）、组织（`/orgs/{org}/projects/{id}`）或已认证用户（`/user/projects/{id}`）的项目路由管理工作流：
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| `GET` | `.../workflows` | 列出工作流 |
+| `GET` | `.../workflows/{workflow_id}` | 获取工作流 |
+| `POST` | `.../workflows` | 创建工作流 |
+| `PATCH` | `.../workflows/{workflow_id}` | 编辑工作流，未提供的字段保持不变 |
+| `DELETE` | `.../workflows/{workflow_id}` | 删除工作流 |
+
+工作流包含 `event`（`item_added_to_project`、`item_removed_from_project`、`item_reopened`、`item_closed`、`item_column_changed`、`code_changes_requested`、`code_review_approved` 或 `pull_request_merged`）、`enabled` 标志、`filters`（`issue_type`、`source_column_id`、`target_column_id`、`label_ids`）以及 `actions`（`column_id`、`add_label_ids`、`remove_label_ids`、`issue_state`）。每个事件仅接受[事件](#事件)表中列出的过滤器和动作。
+
+## 示例
+
+要将新的缺陷报告分流至待分类列，请为 **Item added to project** 创建工作流：
+
+- **Apply to**：Issues only
+- **Only if it has labels**：`bug`
+- **Move to column**：Triage
+- **Add labels**：`needs-triage`

i18n/zh-cn/docs/version-28/installation/database-preparation.md

@@ -8,7 +8,7 @@ aliases:
 
 # 数据库准备
 
-在使用 Gitea 前，您需要准备一个数据库。Gitea 支持 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（内置） 和 MSSQL（>= 2012 SP4）这几种数据库。本页将指导您准备数据库。由于 PostgreSQL 和 MySQL 在生产环境中被广泛使用，因此本文档将仅涵盖这两种数据库。如果您计划使用 SQLite，则可以忽略本章内容。
+在使用 Gitea 前，您需要准备一个数据库。Gitea 支持 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（内置） 和 MSSQL（>= 2012 SP4）这几种数据库。本页将指导您准备数据库。本文档涵盖 PostgreSQL、MySQL 和 MSSQL。如果您计划使用 SQLite，则可以忽略本章内容。
 
 如果您使用不受支持的数据库版本，请通过 [联系我们](/help/support) 以获取有关我们的扩展支持的信息。我们可以为旧数据库提供测试和支持，并将这些修复集成到 Gitea 代码库中。
 
@@ -168,6 +168,28 @@ aliases:
 
    您应该会被提示输入数据库用户的密码，并连接到数据库。
 
+## MSSQL
+
+1. 以管理员身份创建登录名、使用大小写敏感排序规则的数据库及其用户。请将密码 `'gitea'` 替换为安全的密码：
+
+   ```sql
+   CREATE LOGIN gitea WITH PASSWORD = 'gitea';
+   CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
+   GO
+   USE giteadb;
+   CREATE USER gitea FOR LOGIN gitea;
+   ALTER ROLE db_owner ADD MEMBER gitea;
+   GO
+   ```
+
+   升级会更改数据库结构，因此该用户需要 `db_owner`，或者 `db_ddladmin`、`db_datareader` 和 `db_datawriter`。使用后者时，还需以管理员身份执行 `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;`。
+
+2. 在您的 Gitea 服务器上，测试与数据库的连接：
+
+   ```sh
+   sqlcmd -S 203.0.113.3 -U gitea -d giteadb
+   ```
+
 ## 使用 TLS 进行数据库连接
 
 如果 Gitea 和您的数据库实例之间的通信是通过私有网络进行的，或者如果 Gitea 和数据库运行在同一台服务器上，那么可以省略本节，因为 Gitea 和数据库实例之间的安全性不会受到严重威胁。但是，如果数据库实例位于公共网络上，请使用 TLS 对数据库连接进行加密，以防止第三方拦截流量数据。

i18n/zh-cn/docs/version-28/usage/actions/comparison.md

@@ -21,15 +21,7 @@ Gitea Actions旨在与GitHub Actions兼容，差异如下。
 `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:`运行Gitea Runner内置的Action，无需下载，也不依赖Node.js，例如`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
 
@@ -95,7 +87,7 @@ Gitea Actions旨在与GitHub 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)。
+其他来源请参阅[Action URL绝对路径](#absolute-action-urls)和[Action前缀](#action-prefixes)。
 
 ### 上下文可用性
 

i18n/zh-tw/docs/current/administration/config-cheat-sheet.md

@@ -142,7 +142,7 @@ aliases:
 - `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: 在預設的 squash 合併消息中，包括構成拉取請求的所有提交的提交消息。
 - `ADD_CO_COMMITTER_TRAILERS`: **true**: 如果提交者與作者不匹配，在合併提交消息中添加`co-authored-by`和`co-committed-by`標記。
 - `RETARGET_CHILDREN_ON_MERGE`: **true**: 當父合併請求被合併時，將子合併請求重新定向到父合併請求的目標分支。僅適用於頭分支和基分支指向同一儲存庫的已合併合併請求。
-- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **false**: 為新儲存庫設定"合併後預設刪除合併請求分支"的預設值。
+- `DEFAULT_DELETE_BRANCH_AFTER_MERGE`: **true**: 為新儲存庫設定"合併後預設刪除合併請求分支"的預設值。
 
 ### 儲存庫 - 工單 (`repository.issue`)
 
@@ -529,7 +529,8 @@ Gitea 建立以下非唯一隊列：
 - `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: 反向代理認證的 HTTP 頭部名稱，用於提供使用者資訊。
 - `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: 反向代理認證的 HTTP 頭部名稱，用於提供郵箱資訊。
 - `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: 反向代理認證的 HTTP 頭部名稱，用於提供全名資訊。
-- `REVERSE_PROXY_LIMIT`: **1**: 解釋 X-Forwarded-For 標頭或 X-Real-IP 標頭，並將其設定為請求的遠程 IP。
+- `REVERSE_PROXY_LIMIT`: **1**: 依序解釋 X-Real-IP、X-Forwarded-For 或 Forwarded 標頭，並將其設定為請求的遠程 IP。
+  客戶端連接埠取自標頭值，或在使用 X-Real-IP 時取自 X-Real-Port。
   可信代理計數。設定為零以不使用這些標頭。
 - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: 逗號分隔的受信任代理伺服器的 IP 地址和網路列表。使用 `*` 來信任全部。
 - `DISABLE_GIT_HOOKS`: **true**: 設定為 `false` 以允許具有 Git 鉤子權限的使用者建立自訂 Git 鉤子。
@@ -1201,7 +1202,7 @@ In-Reply-To =
 - `JWT_SECRET_URI`：**_empty_**: 可以使用此設定選項，而不是在設定中定義`JWT_SECRET`，以向 Gitea 提供包含密鑰的文件的路徑（範例值：`file:/etc/gitea/oauth2_jwt_secret`）。
 - `JWT_SIGNING_PRIVATE_KEY_FILE`：**jwt/private.pem**: 用於簽署 OAuth2 令牌的私鑰文件路徑。路徑相對於`APP_DATA_PATH`。僅當`JWT_SIGNING_ALGORITHM`設定為`RS256`，`RS384`，`RS512`，`ES256`，`ES384`或`ES512`時才需要此設定。文件必須包含 PKCS8 格式的 RSA 或 ECDSA 私鑰。如果不存在密鑰，則將為您建立一個 4096 位密鑰。
 - `MAX_TOKEN_LENGTH`：**32767**: 從 OAuth2 提供者接受的令牌/cookie 的最大長度。
-- `DEFAULT_APPLICATIONS`：**git-credential-oauth，git-credential-manager, tea**: 在啟動時預註冊用於某些服務的 OAuth 應用程式。有關可用選項列表，請參閱[OAuth2 文件](/development/oauth2-provider.md)。
+- `DEFAULT_APPLICATIONS`：**git-credential-oauth, git-credential-manager, gitea-cli, gitea-app, gitea-vscode**: 在啟動時預註冊用於某些服務的 OAuth 應用程式。有關可用選項列表，請參閱[OAuth2 文件](/development/oauth2-provider.md)。
 
 ## i18n (`i18n`)
 

i18n/zh-tw/docs/current/installation/database-preparation.md

@@ -8,7 +8,7 @@ aliases:
 
 # 資料庫準備
 
-在使用 Gitea 前，您需要準備一個資料庫。Gitea 支援 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（內置） 和 MSSQL（>= 2012 SP4）這幾種資料庫。本頁將指導您準備資料庫。由於 PostgreSQL 和 MySQL 在生產環境中被廣泛使用，因此本文件將僅涵蓋這兩種資料庫。如果您計劃使用 SQLite，則可以忽略本章內容。
+在使用 Gitea 前，您需要準備一個資料庫。Gitea 支援 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（內置） 和 MSSQL（>= 2012 SP4）這幾種資料庫。本頁將指導您準備資料庫。本文件涵蓋 PostgreSQL、MySQL 和 MSSQL。如果您計劃使用 SQLite，則可以忽略本章內容。
 
 如果您使用不受支援的資料庫版本，請通過 [聯繫我們](/help/support) 以獲取有關我們的擴展支援的資訊。我們可以為舊資料庫提供測試和支援，並將這些修復整合到 Gitea 程式碼庫中。
 
@@ -168,6 +168,28 @@ aliases:
 
    您應該會被提示輸入資料庫使用者的密碼，並連接到資料庫。
 
+## MSSQL
+
+1. 以管理員身份建立登入名稱、使用大小寫敏感排序規則的資料庫及其使用者。請將密碼 `'gitea'` 替換為安全的密碼：
+
+   ```sql
+   CREATE LOGIN gitea WITH PASSWORD = 'gitea';
+   CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
+   GO
+   USE giteadb;
+   CREATE USER gitea FOR LOGIN gitea;
+   ALTER ROLE db_owner ADD MEMBER gitea;
+   GO
+   ```
+
+   升級會更改資料庫結構，因此該使用者需要 `db_owner`，或者 `db_ddladmin`、`db_datareader` 和 `db_datawriter`。使用後者時，還需以管理員身份執行 `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;`。
+
+2. 在您的 Gitea 伺服器上，測試與資料庫的連接：
+
+   ```sh
+   sqlcmd -S 203.0.113.3 -U gitea -d giteadb
+   ```
+
 ## 使用 TLS 進行資料庫連接
 
 如果 Gitea 和您的資料庫實例之間的通信是通過私有網路進行的，或者如果 Gitea 和資料庫運行在同一臺伺服器上，那麼可以省略本節，因為 Gitea 和資料庫實例之間的安全性不會受到嚴重威脅。但是，如果資料庫實例位於公共網路上，請使用 TLS 對資料庫連接進行加密，以防止第三方攔截流量資料。

i18n/zh-tw/docs/current/usage/actions/comparison.md

@@ -21,15 +21,7 @@ Gitea Actions 旨在與 GitHub Actions 相容，差異如下。
 `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:` 執行 Gitea Runner 內建的 Action，無需下載，也不依賴 Node.js，例如 `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
 
@@ -95,7 +87,7 @@ Gitea Actions 旨在與 GitHub 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)。
+其他來源請參閱 [Action URL絕對路徑](#absolute-action-urls)和[Action 前綴](#action-prefixes)。
 
 ### 上下文可用性
 

i18n/zh-tw/docs/current/usage/actions/variables.md

@@ -6,10 +6,90 @@ sidebar_position: 25
 
 # 變量
 
+## 環境變量
+
+以下環境變量會在每次工作流執行時自動設定，可以直接存取（例如在 shell 腳本中使用 `$CI`）。
+同時列出 `GITEA_*` 和 `GITHUB_*` 名稱的變量值相同。
+
+| 名稱 | 描述 | 範例 |
+|---|---|---|
+| `ACT` | 始終為 `true`，除非 Runner 設定了 `runner.set_act_env: false`。 | `true` |
+| `CI` | 始終為 `true`。 | `true` |
+| `GITEA_ACTION`<br/>`GITHUB_ACTION` | 目前步驟的 `id`，未設定時為步驟的序號。 | `0` |
+| `GITEA_ACTION_PATH`<br/>`GITHUB_ACTION_PATH` | Action 所在的路徑。僅在複合 Action 中設定。 | `/var/run/act/actions/***` |
+| `GITEA_ACTION_REF`<br/>`GITHUB_ACTION_REF` | 正在執行的 Action 的 ref。 | `v4` |
+| `GITEA_ACTION_REPOSITORY`<br/>`GITHUB_ACTION_REPOSITORY` | Action 的所有者和儲存庫名稱。 | `actions/checkout` |
+| `GITEA_ACTIONS`<br/>`GITHUB_ACTIONS` | 始終為 `true`。`GITEA_ACTIONS` 可用於區分 Gitea Actions 和其他 CI 系統。 | `true` |
+| `GITEA_ACTIONS_RUNNER_VERSION` | 執行工作流的 Runner 的版本。 | `v5.2.4` |
+| `GITEA_ACTOR`<br/>`GITHUB_ACTOR` | 觸發工作流的使用者的使用者名稱。 | `alice` |
+| `GITEA_ACTOR_ID`<br/>`GITHUB_ACTOR_ID` | 觸發工作流的使用者的 ID。 | `1` |
+| `GITEA_API_URL`<br/>`GITHUB_API_URL` | REST API 的 URL。 | `https://gitea.example.com/api/v1` |
+| `GITEA_BASE_REF`<br/>`GITHUB_BASE_REF` | 拉取請求的目標分支。 | `main` |
+| `GITEA_DOCKER_WORKSPACE` | Docker 守護程式所見的工作區路徑，用於綁定掛載到 Job 啟動的容器中，例如在 compose 檔案中使用 `${GITEA_DOCKER_WORKSPACE:-.}/data:/app/data`。僅在 Job 於容器中執行時設定。 | `/var/lib/docker/volumes/GITEA-ACTIONS-TASK-42-***/_data` |
+| `GITEA_ENV`<br/>`GITHUB_ENV` | 為後續步驟設定環境變量的檔案路徑。 | `/var/run/act/workflow/envs.txt` |
+| `GITEA_EVENT_NAME`<br/>`GITHUB_EVENT_NAME` | 觸發工作流的事件名稱。 | `push` |
+| `GITEA_EVENT_PATH`<br/>`GITHUB_EVENT_PATH` | 包含事件 Webhook 負載的檔案路徑。 | `/var/run/act/workflow/event.json` |
+| `GITEA_GRAPHQL_URL`<br/>`GITHUB_GRAPHQL_URL` | 在 Gitea 中為空（不支援 GraphQL）。 | _（空）_ |
+| `GITEA_HEAD_REF`<br/>`GITHUB_HEAD_REF` | 拉取請求的來源分支。 | `feature-branch` |
+| `GITEA_JOB`<br/>`GITHUB_JOB` | 目前 Job 的 `job_id`。 | `build` |
+| `GITEA_OUTPUT`<br/>`GITHUB_OUTPUT` | 設定步驟輸出參數的檔案路徑。 | `/var/run/act/workflow/outputcmd.txt` |
+| `GITEA_PATH`<br/>`GITHUB_PATH` | 為後續步驟新增系統 `PATH` 項目的檔案路徑。 | `/var/run/act/workflow/pathcmd.txt` |
+| `GITEA_REF`<br/>`GITHUB_REF` | 觸發工作流的完整 ref。 | `refs/heads/main` |
+| `GITEA_REF_NAME`<br/>`GITHUB_REF_NAME` | ref 的短名稱。 | `main` |
+| `GITEA_REF_PROTECTED`<br/>`GITHUB_REF_PROTECTED` | 如果觸發工作流的 ref 設定了分支保護，則為 `true`。 | `true` |
+| `GITEA_REF_TYPE`<br/>`GITHUB_REF_TYPE` | ref 的類型：`branch` 或 `tag`。 | `branch` |
+| `GITEA_REPOSITORY`<br/>`GITHUB_REPOSITORY` | 所有者和儲存庫名稱。 | `owner/repo` |
+| `GITEA_REPOSITORY_ID`<br/>`GITHUB_REPOSITORY_ID` | 儲存庫的 ID。 | `123` |
+| `GITEA_REPOSITORY_OWNER`<br/>`GITHUB_REPOSITORY_OWNER` | 儲存庫所有者的使用者名稱。 | `owner` |
+| `GITEA_REPOSITORY_OWNER_ID`<br/>`GITHUB_REPOSITORY_OWNER_ID` | 儲存庫所有者的 ID。 | `45` |
+| `GITEA_RETENTION_DAYS`<br/>`GITHUB_RETENTION_DAYS` | Artifact 的保留天數，永久保留時為空。 | `90` |
+| `GITEA_RUN_ATTEMPT`<br/>`GITHUB_RUN_ATTEMPT` | 工作流執行的嘗試次數。 | `1` |
+| `GITEA_RUN_ID`<br/>`GITHUB_RUN_ID` | 每次工作流執行的唯一編號。 | `1234` |
+| `GITEA_RUN_NUMBER`<br/>`GITHUB_RUN_NUMBER` | 特定工作流每次執行的唯一編號。 | `42` |
+| `GITEA_SERVER_URL`<br/>`GITHUB_SERVER_URL` | Gitea 實例的 URL。 | `https://gitea.example.com` |
+| `GITEA_SHA`<br/>`GITHUB_SHA` | 觸發工作流的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `GITEA_STATE`<br/>`GITHUB_STATE` | 設定步驟狀態變量的檔案路徑。 | `/var/run/act/workflow/statecmd.txt` |
+| `GITEA_STEP_SUMMARY`<br/>`GITHUB_STEP_SUMMARY` | 寫入 Job 摘要的檔案路徑。 | `/var/run/act/workflow/step-summary-0.md` |
+| `GITEA_TRIGGERING_ACTOR`<br/>`GITHUB_TRIGGERING_ACTOR` | 發起工作流執行的使用者的使用者名稱。重新執行時可能與 `GITEA_ACTOR` 不同。 | `alice` |
+| `GITEA_WORKFLOW`<br/>`GITHUB_WORKFLOW` | 工作流的名稱。 | `CI` |
+| `GITEA_WORKFLOW_SHA`<br/>`GITHUB_WORKFLOW_SHA` | 工作流檔案的提交 SHA。 | `a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2` |
+| `GITEA_WORKSPACE`<br/>`GITHUB_WORKSPACE` | Runner 上的預設工作目錄。 | `/workspace/owner/repo` |
+| `TRACEPARENT` | Job span 的 W3C 追蹤上下文，供已接入追蹤的工具將 span 新增到 Job 的追蹤中。僅在 Runner 匯出追蹤資料時設定，參見[監控](/runner/monitoring/#opentelemetry)。 | `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` |
+| `TRACESTATE` | 隨 `TRACEPARENT` 附帶的廠商特定追蹤資料。僅在追蹤包含此類資料時設定。 | `rojo=00f067aa0ba902b7` |
+
+### Runner 環境變量
+
+| 名稱 | 描述 | 範例 |
+|---|---|---|
+| `ImageOS` | Job 映像的作業系統和版本，供 `setup-*` Action 讀取。 | `ubuntu24` |
+| `RUNNER_ARCH` | Runner 的架構。 | `X64` |
+| `RUNNER_DEBUG` | 當 `ACTIONS_STEP_DEBUG` 密鑰為 `true` 時設定為 `1`，否則不設定。 | `1` |
+| `RUNNER_ENVIRONMENT` | 始終為 `self-hosted`。 | `self-hosted` |
+| `RUNNER_NAME` | 執行 Job 的 Runner 的名稱。 | `my-runner` |
+| `RUNNER_OS` | Runner 的作業系統。 | `Linux` |
+| `RUNNER_TEMP` | Runner 上暫存目錄的路徑。 | `/tmp` |
+| `RUNNER_TOOL_CACHE` | Runner 上工具快取目錄的路徑。 | `/opt/hostedtoolcache` |
+| `RUNNER_WORKSPACE` | `GITEA_WORKSPACE` 的上層目錄。 | `/workspace/owner` |
+
+### 內部環境變量
+
+這些變量供 Runner 和 Action 內部使用，工作流中通常不需要直接使用。
+
+| 名稱 | 描述 | 範例 |
+|---|---|---|
+| `ACTIONS_CACHE_URL` | Actions 快取服務的 URL。 | `http://192.168.1.10:8088/` |
+| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | 用於 OIDC 請求的令牌。僅在授予 `id-token: write` 時設定。 | `***` |
+| `ACTIONS_ID_TOKEN_REQUEST_URL` | 請求 OIDC 令牌的 URL。僅在授予 `id-token: write` 時設定。 | `https://gitea.example.com/api/actions/oidc/token?` |
+| `ACTIONS_RESULTS_URL` | 儲存 Artifact 的 URL。 | `https://gitea.example.com` |
+| `ACTIONS_RUNTIME_TOKEN` | Actions 管線 API 的驗證令牌。 | `***` |
+| `ACTIONS_RUNTIME_URL` | Gitea Actions 管線 API 的 URL。 | `https://gitea.example.com/api/actions_pipeline/` |
+
+## 使用者定義的變量
+
 您可以建立使用者、組織和儲存庫級別的變量。變量的級別取決於建立它的位置。當建立變量時，變量的名稱會被
 轉換為大寫，在yaml文件中引用時需要使用大寫。
 
-## 命名規則
+### 命名規則
 
 以下規則適用於變量名：
 
@@ -20,11 +100,11 @@ sidebar_position: 25
 - 變量名稱在建立它們的級別上必須是唯一的。
 - 變量名稱不能為 `CI`。
 
-## 使用
+### 使用
 
 建立設定變量後，它們將自動填充到 `vars` 上下文中。您可以在工作流中使用類似 `${{ vars.VARIABLE_NAME }}` 這樣的表達式來使用它們。
 
-## 優先級
+### 優先級
 
 如果同名變量存在於多個級別，則級別最低的變量優先。
 儲存庫級別的變量總是比組織或者使用者級別的變量優先被選中。

i18n/zh-tw/docs/current/usage/projects/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "專案",
+  "position": 60,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/projects",
+    "description": "使用專案看板規劃與追蹤工作"
+  }
+}

i18n/zh-tw/docs/current/usage/projects/project-workflows.md

@@ -0,0 +1,82 @@
+---
+date: "2025-11-25T18:58:22Z"
+slug: "project-workflows"
+sidebar_position: 1
+description: "透過事件驅動的篩選條件與動作，讓專案看板自動化。"
+---
+
+# 專案工作流程
+
+專案工作流程可讓專案看板自動化。當專案中的問題或合併請求觸發事件時，該事件的每個已啟用工作流程都會檢查篩選條件並執行動作。工作流程在 Gitea 中執行，不需要 runner。
+
+## 編輯工作流程
+
+1. 開啟專案並選取 **Workflows**。
+2. 在側邊欄選取事件。
+3. 設定篩選條件與動作，然後選取 **Save**。若要變更現有工作流程，請先選取 **Edit**。
+
+一個事件可以有多個工作流程。**Clone** 會複製選取的工作流程，方便您調整後用於其他項目。**Disable** 會暫停工作流程並保留設定。**Remove** 會刪除工作流程。
+
+## 事件
+
+| 事件 | 執行時機 | 篩選條件 | 動作 |
+| --- | --- | --- | --- |
+| Item added to project | 項目加入專案或在專案中建立時 | Apply to、標籤 | Move to column、標籤、問題狀態 |
+| Item removed from project | 項目從專案移除時 | Apply to、標籤 | 標籤、問題狀態 |
+| Item reopened | 項目重新開啟時 | Apply to、標籤 | Move to column、標籤 |
+| Item closed | 項目關閉時 | Apply to、標籤 | Move to column、標籤 |
+| Item column changed | 項目移至另一欄時 | Apply to、欄、標籤 | 標籤、問題狀態 |
+| Code changes requested | 正式審查者要求修改合併請求時 | 標籤 | Move to column、標籤 |
+| Code review approved | 正式審查者核准合併請求時 | 標籤 | Move to column、標籤 |
+| Pull request merged | 合併請求合併時 | 標籤 | Move to column、標籤 |
+
+## 篩選條件
+
+未設定篩選條件的工作流程會對所有項目執行。
+
+- **Apply to**：問題、合併請求或兩者。
+- **When moved from column**、**When moved to column**：項目離開或進入的欄。
+- **Only if it has labels**：項目必須具有所有選取的標籤。
+
+## 動作
+
+工作流程至少需要一個動作。動作依下列順序執行：
+
+1. **Move to column**：將項目移至某一欄。
+2. **Add labels**、**Remove labels**：變更項目的標籤。
+3. **Issue state**：關閉或重新開啟項目。工作流程不會重新開啟合併請求。
+
+工作流程所做的變更會在時間軸中顯示為「Project workflow」加上事件名稱，且不會觸發其他工作流程。專案已關閉或項目位於已封存的儲存庫時，工作流程不會執行。
+
+## 權限
+
+任何具有專案讀取權限的使用者都能檢視其工作流程。管理工作流程需要專案的寫入權限，以及：
+
+- 儲存庫專案：該儲存庫的問題與合併請求的寫入權限。
+- 組織專案：組織擁有者或網站管理員身分。
+- 使用者專案：專案擁有者身分。
+
+僅限公開儲存庫的存取權杖無法管理組織或使用者專案的工作流程。無論誰觸發事件，工作流程都會執行其動作。
+
+## API
+
+透過儲存庫（`/repos/{owner}/{repo}/projects/{id}`）、組織（`/orgs/{org}/projects/{id}`）或已驗證使用者（`/user/projects/{id}`）的專案路由管理工作流程：
+
+| 方法 | 路徑 | 用途 |
+| --- | --- | --- |
+| `GET` | `.../workflows` | 列出工作流程 |
+| `GET` | `.../workflows/{workflow_id}` | 取得工作流程 |
+| `POST` | `.../workflows` | 建立工作流程 |
+| `PATCH` | `.../workflows/{workflow_id}` | 編輯工作流程，未提供的欄位保持不變 |
+| `DELETE` | `.../workflows/{workflow_id}` | 刪除工作流程 |
+
+工作流程包含 `event`（`item_added_to_project`、`item_removed_from_project`、`item_reopened`、`item_closed`、`item_column_changed`、`code_changes_requested`、`code_review_approved` 或 `pull_request_merged`）、`enabled` 旗標、`filters`（`issue_type`、`source_column_id`、`target_column_id`、`label_ids`）與 `actions`（`column_id`、`add_label_ids`、`remove_label_ids`、`issue_state`）。每個事件僅接受[事件](#事件)中列出的篩選條件與動作。
+
+## 範例
+
+若要將新的錯誤回報送往分類處理，請為 **Item added to project** 建立工作流程：
+
+- **Apply to**：Issues only
+- **Only if it has labels**：`bug`
+- **Move to column**：Triage
+- **Add labels**：`needs-triage`

i18n/zh-tw/docs/version-28/installation/database-preparation.md

@@ -8,7 +8,7 @@ aliases:
 
 # 資料庫準備
 
-在使用 Gitea 前，您需要準備一個資料庫。Gitea 支援 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（內置） 和 MSSQL（>= 2012 SP4）這幾種資料庫。本頁將指導您準備資料庫。由於 PostgreSQL 和 MySQL 在生產環境中被廣泛使用，因此本文件將僅涵蓋這兩種資料庫。如果您計劃使用 SQLite，則可以忽略本章內容。
+在使用 Gitea 前，您需要準備一個資料庫。Gitea 支援 PostgreSQL（>= 12）、MySQL（>= 8.0）、MariaDB（>= 10.4）、SQLite（內置） 和 MSSQL（>= 2012 SP4）這幾種資料庫。本頁將指導您準備資料庫。本文件涵蓋 PostgreSQL、MySQL 和 MSSQL。如果您計劃使用 SQLite，則可以忽略本章內容。
 
 如果您使用不受支援的資料庫版本，請通過 [聯繫我們](/help/support) 以獲取有關我們的擴展支援的資訊。我們可以為舊資料庫提供測試和支援，並將這些修復整合到 Gitea 程式碼庫中。
 
@@ -168,6 +168,28 @@ aliases:
 
    您應該會被提示輸入資料庫使用者的密碼，並連接到資料庫。
 
+## MSSQL
+
+1. 以管理員身份建立登入名稱、使用大小寫敏感排序規則的資料庫及其使用者。請將密碼 `'gitea'` 替換為安全的密碼：
+
+   ```sql
+   CREATE LOGIN gitea WITH PASSWORD = 'gitea';
+   CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
+   GO
+   USE giteadb;
+   CREATE USER gitea FOR LOGIN gitea;
+   ALTER ROLE db_owner ADD MEMBER gitea;
+   GO
+   ```
+
+   升級會更改資料庫結構，因此該使用者需要 `db_owner`，或者 `db_ddladmin`、`db_datareader` 和 `db_datawriter`。使用後者時，還需以管理員身份執行 `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;`。
+
+2. 在您的 Gitea 伺服器上，測試與資料庫的連接：
+
+   ```sh
+   sqlcmd -S 203.0.113.3 -U gitea -d giteadb
+   ```
+
 ## 使用 TLS 進行資料庫連接
 
 如果 Gitea 和您的資料庫實例之間的通信是通過私有網路進行的，或者如果 Gitea 和資料庫運行在同一臺伺服器上，那麼可以省略本節，因為 Gitea 和資料庫實例之間的安全性不會受到嚴重威脅。但是，如果資料庫實例位於公共網路上，請使用 TLS 對資料庫連接進行加密，以防止第三方攔截流量資料。

i18n/zh-tw/docs/version-28/usage/actions/comparison.md

@@ -21,15 +21,7 @@ Gitea Actions 旨在與 GitHub Actions 相容，差異如下。
 `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:` 執行 Gitea Runner 內建的 Action，無需下載，也不依賴 Node.js，例如 `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
 
@@ -95,7 +87,7 @@ Gitea Actions 旨在與 GitHub 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)。
+其他來源請參閱 [Action URL絕對路徑](#absolute-action-urls)和[Action 前綴](#action-prefixes)。
 
 ### 上下文可用性
 

package.json

@@ -13,5 +13,5 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "[email protected]3.0"
+  "packageManager": "[email protected]6.1"
 }

packages/content-loader/src/products.ts

@@ -8,7 +8,7 @@
 
 export type LocaleId = 'en-us' | 'zh-cn' | 'zh-tw';
 
-export type ProductId = 'docs' | 'api' | 'runner' | 'enterprise';
+export type ProductId = 'docs' | 'api' | 'runner' | 'cli' | 'enterprise';
 
 /** Values substituted for `@name@` placeholders in the markdown sources. */
 export interface VersionVariables {
@@ -89,11 +89,11 @@ const variables: Record<string, VersionVariables> = {
     goVersion: '1.27',
     minGoVersion: '1.27',
     minNodeVersion: '22',
-    version: '28.2.0',
+    version: '28.3.0',
-    sourceVersion: 'v28.2.0',
+    sourceVersion: 'v28.3.0',
     sourceBranch: 'release/v28',
-    dockerVersion: '28.2.0',
+    dockerVersion: '28.3.0',
-    displayVersion: '28.2.0',
+    displayVersion: '28.3.0',
   },
   '1.27': {
     goVersion: '1.26',
@@ -246,6 +246,40 @@ const runnerProduct: ProductDef = {
   ],
 };
 
+/**
+ * gt, the Gitea CLI: laid out like the runner. Until the first series is listed
+ * here the develop docs are served at the product root, without the unreleased
+ * banner, since there is no release to point to. Listing a series moves them to
+ * `/cli/develop/`.
+ */
+const cliSeries: { id: string; latestRelease: string }[] = [];
+
+const cliProduct: ProductDef = {
+  id: 'cli',
+  label: 'CLI',
+  base: 'cli',
+  locales: ['en-us'],
+  versions: [
+    {
+      id: 'develop',
+      label: 'develop',
+      sources: { 'en-us': 'cli-docs' },
+      ...(cliSeries.length > 0
+        ? { path: 'develop', banner: 'unreleased' as const }
+        : { path: '', latest: true }),
+    },
+    ...cliSeries.map(
+      ({ id, latestRelease }, index): VersionDef => ({
+        id,
+        label: latestRelease,
+        path: index === 0 ? '' : id,
+        latest: index === 0,
+        sources: { 'en-us': `cli-docs_versioned_docs/version-${id}` },
+      }),
+    ),
+  ],
+};
+
 /** API reference, rendered from the swagger documents by starlight-openapi. */
 const apiProduct: ProductDef = {
   id: 'api',
@@ -301,7 +335,13 @@ const enterpriseProduct: ProductDef = {
   externalBaseUrl: 'https://docs.gitea.com/enterprise',
 };
 
-export const products: ProductDef[] = [docsProduct, apiProduct, runnerProduct, enterpriseProduct];
+export const products: ProductDef[] = [
+  docsProduct,
+  apiProduct,
+  runnerProduct,
+  cliProduct,
+  enterpriseProduct,
+];
 
 export function getProduct(id: ProductId): ProductDef {
   const product = products.find((candidate) => candidate.id === id);

packages/content-loader/src/sidebar.ts

@@ -1,7 +1,7 @@
 /**
  * Builds one sidebar per (product, version, language) out of the loaded pages,
  * deriving it from `_category_.json` and from the
- * handwritten sidebar files of the runner docs.
+ * handwritten sidebar files of the runner and the cli docs.
  */
 
 import { defaultLocale } from './products';
@@ -44,7 +44,7 @@ export interface SidebarGroup {
 
 export type SidebarEntry = SidebarLink | SidebarGroup;
 
-/** A hand written sidebar file, as used by the runner docs. */
+/** A hand written sidebar file, as used by the runner and the cli docs. */
 export type SidebarSourceItem =
   | string
   | { type: 'doc'; id: string; label?: string }
@@ -148,7 +148,7 @@ function treeOf(pages: SidebarPage[]): Tree {
   return { build, label };
 }
 
-/** Sidebar described by a hand written sidebar file, used by the runner docs. */
+/** Sidebar described by a hand written sidebar file, used by the runner and the cli docs. */
 function fromSidebarSource(
   items: SidebarSourceItem[],
   pages: SidebarPage[],

runner-docs/hooks/job-hooks.md

@@ -31,7 +31,7 @@ The shell options of `run:` steps do not apply to hooks. Set `pipefail` and othe
 
 ## Environment and output
 
-A hook receives the job's environment, including `runner.envs`, the workflow's `env:` and the `GITHUB_*` variables. The runner includes hook output in the job log and masks secrets as it does for step output.
+A hook receives the job's environment, including `runner.envs`, the workflow's `env:` and the `GITHUB_*` and `GITEA_*` variables. The runner includes hook output in the job log and masks secrets as it does for step output.
 
 Use `$GITHUB_ENV` and `$GITHUB_PATH` to pass environment variables and paths to later steps. Mask values with `::add-mask::`:
 

runner-docs/reference/cli.md

@@ -20,13 +20,13 @@ Usage:
   gitea-runner [command]
 
 Available Commands:
-  bug-report      Print information useful when filing a bug report
+  bug-report          Print information useful when filing a bug report
-  cache-server    Start a cache server for the cache action
+  cache-server        Start a cache server for the cache action
-  config          Generate, read and edit config files
+  config              Generate, read and edit config files
-  daemon          Run as a runner daemon
+  daemon              Run as a runner daemon
-  exec            Run workflow locally.
+  exec                Run workflow locally.
-  help            Help about any command
+  help                Help about any command
-  register        Register a runner to the server
+  register            Register a runner to the server
 
 Flags:
   -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable
@@ -91,8 +91,8 @@ Usage:
 
 Flags:
       --artifact-server-addr string      Defines the address where the artifact server listens
-      --artifact-server-path string      Defines the path where the artifact server stores uploads and retrieves downloads from. If not specified the artifact server will not start. (default ".")
+      --artifact-server-path string      Defines the path where the artifact server stores uploads and retrieves downloads from, outside the workspace that jobs copy. Defaults to a temporary directory removed on exit.
-      --artifact-server-port string      Defines the port where the artifact server listens (will only bind to localhost). (default "34567")
+      --artifact-server-port string      Defines the port where the artifact server listens (default "34567")
       --container-architecture string    Architecture which should be used to run containers, e.g.: linux/amd64. If not specified, will use host default architecture. Requires Docker server API Version 1.41+. Ignored on earlier Docker server platforms.
       --container-cap-add stringArray    kernel capabilities to add to the workflow containers (e.g. --container-cap-add SYS_PTRACE)
       --container-cap-drop stringArray   kernel capabilities to remove from the workflow containers (e.g. --container-cap-drop SYS_PTRACE)

runner-docs/reference/config-example.md

@@ -207,7 +207,8 @@ cache:
   #  secret_key_file: "/run/secrets/cache-s3-secret-key"
   # When true, reuse a cached action instead of fetching from the remote on every job.
   # A moved tag (e.g. a re-tagged "v6") or an updated branch stays at the cached commit
-  # until its cache entry expires or is manually removed.
+  # until its cache entry expires or is manually removed. A cached action whose files changed size
+  # since it was downloaded is still fetched again, unless an older runner cached it without sizes.
   #offline_mode: false
   # Serve the actions cache service v2 API. The actions that use it fall back to v1 on any host
   # they do not take for GitHub, so reaching it means editing that check out of their own bundle,
@@ -318,6 +319,18 @@ kubernetes:
   #pod_template: {}
   # Pod templates merged over pod_template, in runs-on order, for jobs whose runs-on has the label they are keyed by.
   #pod_templates: {}
+  # Have job pods fetch directories, such as actions, and copies of 64 KiB or more gzipped from the runner over the pod network,
+  # instead of the runner streaming them through the API server. An init container copies gitea-runner from image into each job pod.
+  # api: through the API server (default). auto: over the pod network, through the API server for a job pod that
+  # cannot reach the runner. direct: over the pod network only, so a broken setup fails jobs instead of quietly
+  # costing API server traffic again.
+  #transfer:
+  #  mode: api
+  #  # Address and port the runner listens on and job pods reach it at, the outbound IP and a free port when empty.
+  #  host: ""
+  #  port: 0
+  #  # Image with gitea-runner on its PATH, the runner pod's image when it has a single container and runs in namespace.
+  #  image: ""
 
 # Optional local task-admission checks. Disabled by default. When enabled, low
 # disk space or a failing script pauses new task fetching; existing jobs continue.

runner-docs_versioned_docs/version-5/reference/cli.md

@@ -91,8 +91,8 @@ Usage:
 
 Flags:
       --artifact-server-addr string      Defines the address where the artifact server listens
-      --artifact-server-path string      Defines the path where the artifact server stores uploads and retrieves downloads from. If not specified the artifact server will not start. (default ".")
+      --artifact-server-path string      Defines the path where the artifact server stores uploads and retrieves downloads from, outside the workspace that jobs copy. Defaults to a temporary directory removed on exit.
-      --artifact-server-port string      Defines the port where the artifact server listens (will only bind to localhost). (default "34567")
+      --artifact-server-port string      Defines the port where the artifact server listens (default "34567")
       --container-architecture string    Architecture which should be used to run containers, e.g.: linux/amd64. If not specified, will use host default architecture. Requires Docker server API Version 1.41+. Ignored on earlier Docker server platforms.
       --container-cap-add stringArray    kernel capabilities to add to the workflow containers (e.g. --container-cap-add SYS_PTRACE)
       --container-cap-drop stringArray   kernel capabilities to remove from the workflow containers (e.g. --container-cap-drop SYS_PTRACE)

runner-docs_versioned_docs/version-5/reference/config-example.md

@@ -207,7 +207,8 @@ cache:
   #  secret_key_file: "/run/secrets/cache-s3-secret-key"
   # When true, reuse a cached action instead of fetching from the remote on every job.
   # A moved tag (e.g. a re-tagged "v6") or an updated branch stays at the cached commit
-  # until its cache entry expires or is manually removed.
+  # until its cache entry expires or is manually removed. A cached action whose files changed size
+  # since it was downloaded is still fetched again, unless an older runner cached it without sizes.
   #offline_mode: false
   # Serve the actions cache service v2 API. The actions that use it fall back to v1 on any host
   # they do not take for GitHub, so reaching it means editing that check out of their own bundle,

scripts/cut-version.mjs

@@ -4,10 +4,11 @@
  *
  *   node scripts/cut-version.mjs docs 1.28     # freezes docs/ as 1.28
  *   node scripts/cut-version.mjs runner 4      # freezes runner-docs/ as 4
+ *   node scripts/cut-version.mjs cli 0.1       # freezes cli-docs/ as 0.1
  *
  * For the docs it copies the english tree, every translation and the sidebar
- * file; for the runner the english tree and its sidebar. The version list
+ * file; for the runner and the cli the english tree and its sidebar. The
- * (`versions.json`, `runner-docs_versions.json`) is updated too.
+ * version list (`versions.json`, `<product>-docs_versions.json`) is updated too.
  *
  * The label, the release variables (`@version@`, `@dockerVersion@`, ...) and
  * which version is served at the root live in
@@ -21,8 +22,8 @@ import process from 'node:process';
 
 const [product, version] = process.argv.slice(2);
 
-if (!product || !version || !['docs', 'runner'].includes(product)) {
+if (!product || !version || !['docs', 'runner', 'cli'].includes(product)) {
-  console.error('usage: node scripts/cut-version.mjs <docs|runner> <version>');
+  console.error('usage: node scripts/cut-version.mjs <docs|runner|cli> <version>');
   process.exit(1);
 }
 
@@ -52,6 +53,7 @@ async function freeze(from, to) {
 async function freezeSidebar(from, to) {
   if (await exists(to)) throw new Error(`${to} already exists`);
   const sidebar = require(path.join(root, from));
+  await mkdir(path.join(root, path.dirname(to)), { recursive: true });
   await writeFile(path.join(root, to), `${JSON.stringify(sidebar, null, 2)}\n`);
   console.log(`  ${from} -> ${to}`);
 }
@@ -80,12 +82,12 @@ if (product === 'docs') {
 
   await addToVersions('versions.json');
 } else {
-  await freeze('runner-docs', `runner-docs_versioned_docs/version-${version}`);
+  await freeze(`${product}-docs`, `${product}-docs_versioned_docs/version-${version}`);
   await freezeSidebar(
-    'runner-sidebars.js',
+    `${product}-sidebars.js`,
-    `runner-docs_versioned_sidebars/version-${version}-sidebars.json`,
+    `${product}-docs_versioned_sidebars/version-${version}-sidebars.json`,
   );
-  await addToVersions('runner-docs_versions.json');
+  await addToVersions(`${product}-docs_versions.json`);
 }
 
 console.log(

sites/docs/README.md

@@ -1,14 +1,15 @@
 # Astro + Starlight site
 
 Renders the gitea documentation with [Starlight](https://starlight.astro.build):
-the docs (6 versions x 3 languages), the runner docs (4 series) and the api
+the docs (6 versions x 3 languages), the runner docs (4 series), the cli docs
-reference (7 swagger documents). The enterprise docs stay in their own
+and the api reference (7 swagger documents). The enterprise docs stay in their
-deployment and are linked from the header.
+own deployment and are linked from the header.
 
 The content directories are the ones the site has always used — `docs/`,
 `versioned_docs/`, `i18n/`, `runner-docs/`, `runner-docs_versioned_docs/` and
 `static/swagger-*.json` (plus `static/openapi3-*.json` since gitea 1.27) — so
-the release scripts and the translation workflow stay unchanged.
+the release scripts and the translation workflow stay unchanged. The cli docs
+in `cli-docs/` follow the layout of the runner docs.
 
 ## Running it
 
@@ -40,6 +41,7 @@ pickers, the version banner, the search facets and the api schemas.
 | `i18n/zh-cn/docs/version-1.27/` | `/zh-cn/` |
 | `runner-docs_versioned_docs/version-3/` | `/runner/` |
 | `runner-docs/` | `/runner/develop/` |
+| `cli-docs/` | `/cli/`, until a cli series is released |
 | `static/openapi3-27.json` | `/api/` |
 | `static/openapi3-latest.json` | `/api/next/` |
 | `static/swagger-26.json` | `/api/1.26/` |
@@ -60,8 +62,9 @@ of every file, the second normalizes and renders it:
 
 Sidebars are built per (product, version, language) from `_category_.json` and
 from the sidebar files (`sidebars.js`, `versioned_sidebars/`,
-`runner-sidebars.js`, `runner-docs_versioned_sidebars/`), and selected in
+`runner-sidebars.js`, `runner-docs_versioned_sidebars/`, `cli-sidebars.js`),
-`src/routeData.ts`, since starlight only supports a single static sidebar.
+and selected in `src/routeData.ts`, since starlight only supports a single
+static sidebar.
 
 Set `GITEA_DOCS_STRICT_LINKS=true` to fail the build on a broken internal link
 instead of warning.
@@ -69,12 +72,12 @@ instead of warning.
 ## Products and languages
 
 The docs are the site itself, so their language comes first: `/zh-cn/1.26/`.
-The runner and the api are separate products and keep their language inside the
+The runner, the cli and the api are separate products and keep their language
-product, `/runner/zh-cn/3/`, which is reserved: both are published in english
+inside the product, `/runner/zh-cn/3/`, which is reserved: all are published in
-only today. Starlight builds a fallback page in every configured language for
+english only today. Starlight builds a fallback page in every configured
-every english page, so `/zh-cn/runner/` would exist; the post build integration
+language for every english page, so `/zh-cn/runner/` would exist; the post build
-removes those directories and `cloudflare/_redirects` sends them to the
+integration removes those directories and `cloudflare/_redirects` sends them to
-english page.
+the english page.
 
 The version served at the root of a product has no number in its url: docs 1.27
 is `/`, runner 3 is `/runner/` and api 1.27 is `/api/`. `/1.27/`, `/runner/3/`

sites/docs/package.json

@@ -11,16 +11,16 @@
     "check": "astro check"
   },
   "dependencies": {
-    "@astrojs/starlight": "0.42.6",
+    "@astrojs/starlight": "0.42.7",
     "@astrojs/starlight-docsearch": "0.8.0",
     "@gitea-docs/content-loader": "workspace:*",
     "@pagefind/default-ui": "1.5.2",
-    "astro": "7.3.8",
+    "astro": "7.4.2",
     "sharp": "0.35.5",
     "starlight-openapi": "0.27.0"
   },
   "devDependencies": {
-    "@astrojs/check": "0.9.10",
+    "@astrojs/check": "0.9.12",
     "typescript": "6.0.3"
   }
 }

sites/docs/src/config/strings.ts

@@ -23,7 +23,7 @@ type Strings = {
 const en: Strings = {
   versionLabel: 'Version',
   languageLabel: 'Language',
-  products: { docs: 'Docs', api: 'API', runner: 'Runner', enterprise: 'Enterprise' },
+  products: { docs: 'Docs', api: 'API', runner: 'Runner', cli: 'CLI', enterprise: 'Enterprise' },
   footer: { Community: 'Community', Code: 'Code', More: 'More' },
   signIn: 'Sign In',
   translationNotice: 'This translation may be behind the english original.',
@@ -41,7 +41,7 @@ const strings: Record<string, Strings> = {
   'zh-cn': {
     versionLabel: '版本',
     languageLabel: '语言',
-    products: { docs: '文档', api: 'API', runner: 'Runner', enterprise: '企业版' },
+    products: { docs: '文档', api: 'API', runner: 'Runner', cli: 'CLI', enterprise: '企业版' },
     footer: { Community: '社区', Code: '开源代码', More: '更多' },
     signIn: '登录',
     translationNotice: '当前中文文档翻译不是最新版，访问英文版本查看最新内容，或',
@@ -56,7 +56,7 @@ const strings: Record<string, Strings> = {
   'zh-tw': {
     versionLabel: '版本',
     languageLabel: '語言',
-    products: { docs: '文件', api: 'API', runner: 'Runner', enterprise: '企業版' },
+    products: { docs: '文件', api: 'API', runner: 'Runner', cli: 'CLI', enterprise: '企業版' },
     footer: { Community: '社區', Code: '開源程式碼', More: '更多' },
     signIn: '登入',
     translationNotice: '當前中文文檔翻譯不是最新版，訪問英文版本查看最新內容，或',

sites/docs/src/integrations/postbuild.ts

@@ -11,9 +11,9 @@ import { defaultLocale, locales, products, type LocaleId } from '@gitea-docs/con
  *   generated as `/api/126/`. The directories are renamed and the links inside
  *   the build are rewritten.
  * - starlight builds a fallback page in every configured language for every
- *   english page. That is what we want for the docs, but the runner and the api
+ *   english page. That is what we want for the docs, but the other products
- *   are separate products with their own language list, so `/zh-cn/runner/` has
+ *   have their own language list, so `/zh-cn/runner/` has to go;
- *   to go; `cloudflare/_redirects` sends it to the english page.
+ *   `cloudflare/_redirects` sends it to the english page.
  */
 export function giteaPostBuild(): AstroIntegration {
   return {

sites/docs/src/lib/pagefind-ui.ts

@@ -90,7 +90,7 @@ function addScopeToggle(root: HTMLElement, onChange: (allVersions: boolean) => v
 
 /**
  * While all versions are searched the same page shows up once per version, so
- * the version (and the product, for the api and the runner) is appended to the
+ * the version (and the product, for every product but the docs) is appended to the
  * title of a result.
  */
 function labelResult(result: PagefindResult): void {

sites/docs/src/lib/sidebars.ts

@@ -12,9 +12,9 @@ import { getCollection } from 'astro:content';
 import { repoRoot } from '../config/paths';
 
 /**
- * Sidebar files: the top level order of the docs and the
+ * Sidebar files: the top level order of the docs and the handwritten sidebars
- * handwritten sidebars of the runner, one per version. Read as is, so cutting a
+ * of the runner and the cli, one per version. Read as is, so cutting a version
- * version keeps needing no change here.
+ * keeps needing no change here.
  */
 function sidebarSources(): Map<string, SidebarSourceItem[]> {
   const sidebars = new Map<string, SidebarSourceItem[]>();
@@ -42,11 +42,11 @@ function sidebarSources(): Map<string, SidebarSourceItem[]> {
           version.id === 'next'
             ? 'sidebars.js'
             : `versioned_sidebars/version-${version.id}-sidebars.json`;
-      } else if (product.id === 'runner') {
+      } else if (product.id === 'runner' || product.id === 'cli') {
-        files[`runner@${version.id}`] =
+        files[`${product.id}@${version.id}`] =
           version.id === 'develop'
-            ? 'runner-sidebars.js'
+            ? `${product.id}-sidebars.js`
-            : `runner-docs_versioned_sidebars/version-${version.id}-sidebars.json`;
+            : `${product.id}-docs_versioned_sidebars/version-${version.id}-sidebars.json`;
       }
     }
   }

sites/docs/src/schema.ts

@@ -7,7 +7,7 @@ import { z } from 'astro:content';
  * per version sidebars, the version and language pickers and the search facets.
  */
 export const giteaMeta = z.object({
-  product: z.enum(['docs', 'api', 'runner', 'enterprise']),
+  product: z.enum(['docs', 'api', 'runner', 'cli', 'enterprise']),
   version: z.string(),
   locale: z.string(),
   prefix: z.string(),

static/openapi3-28.json

@@ -5686,7 +5686,7 @@
             "x-go-name": "Description"
           },
           "due_on": {
-            "description": "Deadline is the updated due date for the milestone",
+            "description": "Deadline is the due date for the milestone, use null or empty string to remove the deadline",
             "format": "date-time",
             "type": "string",
             "x-go-name": "Deadline"
@@ -7416,7 +7416,7 @@
         "description": "IssueLabelsOption a collection of labels",
         "properties": {
           "labels": {
-            "description": "Labels can be a list of integers representing label IDs\nor a list of strings representing label names",
+            "description": "Labels can be a list of integers representing label IDs\nor a list of strings representing label names.\nIf a repository label and an organization label share a name,\nthe repository label is used.",
             "items": {},
             "type": "array",
             "x-go-name": "Labels"
@@ -11119,7 +11119,7 @@
       "url": "http://opensource.org/licenses/MIT"
     },
     "title": "Gitea API",
-    "version": "28.2.0"
+    "version": "28.3.0"
   },
   "openapi": "3.0.3",
   "paths": {

static/swagger-28.json

@@ -17,7 +17,7 @@
       "name": "MIT",
       "url": "http://opensource.org/licenses/MIT"
     },
-    "version": "28.2.0"
+    "version": "28.3.0"
   },
   "basePath": "https://gitea.com/api/v1",
   "paths": {
@@ -28779,7 +28779,7 @@
           "x-go-name": "Description"
         },
         "due_on": {
-          "description": "Deadline is the updated due date for the milestone",
+          "description": "Deadline is the due date for the milestone, use null or empty string to remove the deadline",
           "type": "string",
           "format": "date-time",
           "x-go-name": "Deadline"
@@ -30525,7 +30525,7 @@
       "type": "object",
       "properties": {
         "labels": {
-          "description": "Labels can be a list of integers representing label IDs\nor a list of strings representing label names",
+          "description": "Labels can be a list of integers representing label IDs\nor a list of strings representing label names.\nIf a repository label and an organization label share a name,\nthe repository label is used.",
           "type": "array",
           "items": {},
           "x-go-name": "Labels"

update_api_docs.sh

@@ -127,7 +127,7 @@ if [ "$LATEST_ONLY" -eq 1 ]; then
   exit 0
 fi
 
-for ver in '28.2.0' '1.27.3' '1.26.4' '1.25.5' '1.24.7' '1.23.8' '1.22.6'; do
+for ver in '28.3.0' '1.27.3' '1.26.4' '1.25.5' '1.24.7' '1.23.8' '1.22.6'; do
   # 1.x releases are suffixed with the minor (1.27.3 -> 27), the versions
   # without the 1. prefix with the major (28.0.0 -> 28)
   case "$ver" in

versioned_docs/version-1.27/usage/packages/overview.md

@@ -55,11 +55,11 @@ and shows a link to the repository on the package site (as well as a link to the
 | Package owner type | User | Organization |
 |--------------------|------|--------------|
 | **read** access    | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only |
-| **write** access   | owner only | org members with admin or write access to the org |
+| **write** access   | owner only | members of a team with write access to packages |
 
 Please note, that your respective package manager needs to have a [personal access token](development/api-usage.md#authentication) with the permissions `package` set to either Read or Read & Write to download and publish packages respectively.
 
-N.B.: These access restrictions are [subject to change](https://github.com/go-gitea/gitea/issues/19270), where more finegrained control will be added via a dedicated organization team permission.
+The packages permission of an organization team applies to all packages of the organization, regardless of the repositories assigned to the team.
 
 ## Create or upload a package
 

versioned_docs/version-28/administration/config-cheat-sheet.md

@@ -1706,7 +1706,7 @@ PROXY_HOSTS = *.github.com
   But it will save storage space and network bandwidth, so it's still recommended to use compression.
 - `ARTIFACT_RETENTION_DAYS`: **90**: Days to keep artifacts. Old artifacts will be deleted after this period. 0 means keep forever.
   Changes only apply to newly uploaded artifacts, existing ones keep the expiry stored when they were uploaded.
-  Artifacts could have their own retention periods by setting the `retention-days` option in `actions/upload-artifact` step.
+  Workflows can request a shorter retention period, down to 1 day.
 - `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

versioned_docs/version-28/installation/database-preparation.md

@@ -8,7 +8,7 @@ aliases:
 
 # Database Preparation
 
-You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. Only PostgreSQL and MySQL will be covered here since those database engines are widely-used in production. If you plan to use SQLite, you can ignore this chapter.
+You need a database to use Gitea. Gitea supports PostgreSQL (>= 12), MySQL (>= 8.0), MariaDB (>= 10.4), SQLite (builtin), and MSSQL (>= 2012 SP4). This page will guide into preparing database. PostgreSQL, MySQL and MSSQL are covered here. If you plan to use SQLite, you can ignore this chapter.
 
 :::warning
 Converting one database type to another is not a well-tested process and you may experience issues. It is better to choose the final database type at the type of the first installation. Be aware that SQLite does not scale; if you expect your instance to grow at a later time, you should choose another database type.
@@ -177,6 +177,28 @@ All steps below requires that the database engine of your choice is installed on
 
     You should be prompted to enter password for the database user, and connected to the database.
 
+## MSSQL
+
+1. As an administrator, create the login, a database with case-sensitive collation, and its user. Replace the password `'gitea'` with a secure one:
+
+    ```sql
+    CREATE LOGIN gitea WITH PASSWORD = 'gitea';
+    CREATE DATABASE giteadb COLLATE Latin1_General_CS_AS;
+    GO
+    USE giteadb;
+    CREATE USER gitea FOR LOGIN gitea;
+    ALTER ROLE db_owner ADD MEMBER gitea;
+    GO
+    ```
+
+    Upgrades change the database schema, so the user needs `db_owner`, or `db_ddladmin`, `db_datareader` and `db_datawriter`. With the latter, also run `ALTER DATABASE giteadb SET READ_COMMITTED_SNAPSHOT ON;` as administrator.
+
+2. On your Gitea server, test the connection to the database:
+
+    ```sh
+    sqlcmd -S 203.0.113.3 -U gitea -d giteadb
+    ```
+
 ## Database Connection over TLS
 
 If the communication between Gitea and your database instance is performed through a private network, or if Gitea and the database are running on the same server, this section can be omitted since the security between Gitea and the database instance is not critically exposed. If instead the database instance is on a public network, use TLS to encrypt the connection to the database, as it is possible for third-parties to intercept the traffic data.

versioned_docs/version-28/usage/actions/comparison.md

@@ -19,14 +19,7 @@ Gitea Actions is designed to be compatible with GitHub Actions, with the differe
 `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:` runs an action built into Gitea Runner, which needs no download and does not depend on Node.js, 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
 
@@ -92,7 +85,7 @@ See [Actions job token permissions](token-permissions.md).
 
 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`.
 See the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
-For other sources, see [Absolute action URLs](#absolute-action-urls), [Action prefixes](#action-prefixes) and [Workflow-relative actions](#workflow-relative-actions).
+For other sources, see [Absolute action URLs](#absolute-action-urls) and [Action prefixes](#action-prefixes).
 
 ### Context availability
 

versioned_docs/version-28/usage/actions/variables.md

@@ -39,7 +39,7 @@ These environment variables are set automatically in every workflow run and can
 | `GITHUB_REF_TYPE` | The type of ref: `branch` or `tag`. | `branch` |
 | `GITHUB_REPOSITORY` | The owner and repository name. | `gitea/docs` |
 | `GITHUB_REPOSITORY_OWNER` | The repository owner's username. | `gitea` |
-| `GITHUB_RETENTION_DAYS` | The number of days that workflow run logs and artifacts are kept. | `90` |
+| `GITHUB_RETENTION_DAYS` | The number of days that artifacts are kept, empty when kept forever. | `90` |
 | `GITHUB_RUN_ATTEMPT` | The attempt number of the workflow run. | `1` |
 | `GITHUB_RUN_ID` | A unique number for each workflow run. | `1234` |
 | `GITHUB_RUN_NUMBER` | A unique number for each run of a particular workflow. | `42` |
@@ -98,7 +98,7 @@ These variables are available in workflow expressions via `${{ gitea.<name> }}`.
 | `gitea.repository`<br/>`github.repository` | The owner and repository name. | `gitea/docs` |
 | `gitea.repository_owner`<br/>`github.repository_owner` | The repository owner's username. | `gitea` |
 | `gitea.repositoryUrl`<br/>`github.repositoryUrl` | The HTML URL to the repository. | `https://gitea.com/gitea/docs` |
-| `gitea.retention_days`<br/>`github.retention_days` | The number of days that workflow run logs and artifacts are kept. | `90` |
+| `gitea.retention_days`<br/>`github.retention_days` | The number of days that artifacts are kept, empty when kept forever. | `90` |
 | `gitea.run_id`<br/>`github.run_id` | A unique number for each workflow run within a repository. Does not change on re-run. | `1234` |
 | `gitea.run_number`<br/>`github.run_number` | A unique number for each run of a particular workflow. Starts at 1 and increments with each new run. | `42` |
 | `gitea.run_attempt`<br/>`github.run_attempt` | A unique number for each re-run attempt. Starts at 1 and increments with each re-run. | `1` |

versioned_docs/version-28/usage/packages/helm.md

@@ -37,7 +37,7 @@ helm cm-push ./{chart_file}.tgz {repo}
 
 ## Install a package
 
-To install a Helm char from the registry, execute the following command:
+To install a Helm chart from the registry, execute the following command:
 
 ```shell
 helm repo add  --username {username} --password {password} {repo} https://gitea.example.com/api/packages/{owner}/helm

versioned_docs/version-28/usage/packages/overview.md

@@ -55,11 +55,11 @@ and shows a link to the repository on the package site (as well as a link to the
 | Package owner type | User | Organization |
 |--------------------|------|--------------|
 | **read** access    | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only |
-| **write** access   | owner only | org members with admin or write access to the org |
+| **write** access   | owner only | members of a team with write access to packages |
 
 Please note, that your respective package manager needs to have a [personal access token](development/api-usage.md#authentication) with the permissions `package` set to either Read or Read & Write to download and publish packages respectively.
 
-N.B.: These access restrictions are [subject to change](https://github.com/go-gitea/gitea/issues/19270), where more finegrained control will be added via a dedicated organization team permission.
+The packages permission of an organization team applies to all packages of the organization, regardless of the repositories assigned to the team.
 
 ## Create or upload a package