Merge branch 'main' into lunny/add_project_workflow

Reviewed-on: https://gitea.com/gitea/docs/pulls/344
Co-authored-by: Renovate Bot <renovate-bot@gitea.com>
Co-committed-by: Renovate Bot <renovate-bot@gitea.com>

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

@@ -8,36 +8,31 @@ on:
 
 jobs:
   build-docs:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
-          node-version: 20
-          cache: npm
+          node-version: 24
+          cache: pnpm
       - name: install necessary tools
         run: |
-          apt update -y && apt install -y rsync python3 python3-pip python-is-python3
-          pip install awscli
+          curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
+          unzip awscliv2.zip
+          sudo ./aws/install
       - name: prepare awesome list
         run: |
-          make prepare-awesome-latest prepare-awesome\#23 prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
-      - name: Cache ~/.npm for npm ci
-        uses: actions/cache@v4
-        with:
-          path: ~/.npm
-          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
-          restore-keys: ${{ runner.os }}-node
-
+          make prepare-awesome-latest prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       #- uses: tats-u/docuactions-cache@v1
       - name: build site
         run: |
           make build
       - name: aws credential configure
-        uses: aws-actions/configure-aws-credentials@v5
+        uses: aws-actions/configure-aws-credentials@v6
         with:
           aws-access-key-id: ${{ secrets.AWS_KEY_ID }}
           aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY}}

.gitea/workflows/test.yaml

@@ -7,23 +7,17 @@ jobs:
   build-docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v4
       - uses: actions/setup-node@v6
         with:
-          node-version: 20
-          cache: npm
+          node-version: 24
+          cache: pnpm
       - name: prepare awesome list
         run: |
-          make prepare-awesome-latest prepare-awesome\#23 prepare-awesome\#22 prepare-awesome\#21 prepare-awesome\#20 prepare-awesome\#19
-      - name: Cache ~/.npm for npm ci
-        uses: actions/cache@v4
-        with:
-          path: ~/.npm
-          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
-          restore-keys: ${{ runner.os }}-node
-
+          make prepare-awesome-latest prepare-awesome\#25 prepare-awesome\#24 prepare-awesome\#23 prepare-awesome\#22
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       #- uses: tats-u/docuactions-cache@v1
       - name: build site

.gitea/workflows/update_swagger.yaml

@@ -9,28 +9,20 @@ jobs:
   update-swagger:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - run: |
-          wget https://raw.githubusercontent.com/go-gitea/gitea/refs/heads/main/templates/swagger/v1_json.tmpl
-          sed -i "$@" 's\"version": "{{AppVer | JSEscape}}"\"version": "dev"\' v1_json.tmpl
-          sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
-          mv v1_json.tmpl static/swagger-latest.json
+          set -euo pipefail
 
-          for ver in '1.24.7' '1.23.8' '1.22.6' '1.21.11' '1.20.6' '1.19.4'; do
-            wget https://raw.githubusercontent.com/go-gitea/gitea/refs/tags/v${ver}/templates/swagger/v1_json.tmpl
-            sed -i "$@" "s|\"version\": \"{{AppVer \| JSEscape}}\"|\"version\": \"${ver}\"|" v1_json.tmpl
-            sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
-            # for version < 1.21.11
-            sed -i "$@" "s|\"version\": \"{{AppVer \| JSEscape \| Safe}}\"|\"version\": \"${ver}\"|" v1_json.tmpl
-            sed -i "$@" 's\"basePath": "{{AppSubUrl | JSEscape | Safe}}/api/v1"\"basePath": "https://gitea.com/api/v1"\' v1_json.tmpl
-            minor=$(echo "$ver" | cut -d '.' -f 2)
-            mv v1_json.tmpl static/swagger-$minor.json
-          done
+          make update-api-docs
 
-          if ! [[ $(git diff --shortstat) ]]; then exit 0; fi
           git config --global user.name "Gitea Bot"
           git config --global user.email "teabot@gitea.io"
           git remote set-url origin https://x-access-token:${{ secrets.DEPLOY_TOKEN }}@gitea.com/gitea/docs.git
-          git add --all
-          git commit -m "[skip ci] Updated swagger files"
-          git push
+
+          if git status --porcelain | grep -q .; then
+            git add --all
+            git commit -m "[skip ci] Updated swagger files"
+            git push
+          else
+            echo "No API doc changes detected; skipping commit"
+          fi

.gitignore

@@ -20,4 +20,5 @@ yarn-debug.log*
 yarn-error.log*
 
 .tmp/
+awesome/
 awesome.md

Makefile

@@ -8,7 +8,7 @@ all: build
 
 .PHONY: create_dir
 create_dir:
-	mkdir -p .tmp awesome
+	mkdir -p .tmp
 
 .PHONY: clone_awesome
 clone_awesome: create_dir
@@ -24,22 +24,22 @@ prepare-awesome\#%:
 
 .PHONY: install
 install:
-	npm install
+	pnpm install
 
 .PHONY: prepare-docs
 prepare-docs: install prepare-awesome-latest prepare-awesome\#19 prepare-awesome\#20 prepare-awesome\#21 prepare-awesome\#22 prepare-awesome\#23 prepare-awesome\#24
 
 .PHONY: build
 build:
-	npm run build
+	pnpm run build
 
 .PHONY: serve
 serve: prepare-docs
-	npm run start
+	pnpm run start
 
 .PHONY: serve-zh
 serve-zh: prepare-docs
-	npm run start -- --locale zh-cn
+	pnpm run start -- --locale zh-cn
 
 .PHONY: clean
 clean:
@@ -52,3 +52,7 @@ clean:
 	rm -rf static/swagger-22.json
 	rm -rf static/swagger-23.json
 	rm -rf static/swagger-24.json
+
+.PHONY: update-api-docs
+update-api-docs:
+	./update_api_docs.sh

README.md

@@ -19,5 +19,5 @@ make serve
 ## Test en version
 
 ```shell
-npm run start
+pnpm run start
 ```

babel.config.js

@@ -1,3 +0,0 @@
-module.exports = {
-  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
-};

docs/administration/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Administration",
+  "position": 30,
+  "link": {
+    "type": "generated-index",
+    "slug": "/administration",
+    "title": "Administration"
+  }
+}

docs/administration/backup-and-restore.md

@@ -24,7 +24,7 @@ directory. There should be some output similar to the following:
 
 ```log
 2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:09 Dumping local repositories.../home/git/gitea-repositories
+2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
 2016/12/27 22:32:22 Dumping database...
 2016/12/27 22:32:22 Packing dump files...
 2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
@@ -83,7 +83,7 @@ cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/data/gitea-repositories/
+mv repos/* /var/lib/gitea/data/repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
 
 # mysql
@@ -119,7 +119,7 @@ cd gitea-dump-1610949662
 # restore the gitea data
 mv data/* /data/gitea
 # restore the repositories itself
-mv repos/* /data/git/gitea-repositories/
+mv repos/* /data/git/repositories/
 # adjust file permissions
 chown -R git:git /data
 # Regenerate Git Hooks
@@ -143,7 +143,7 @@ mv data/conf/app.ini /etc/gitea/app.ini
 # restore the gitea data
 mv data/* /var/lib/gitea
 # restore the repositories itself
-mv repos/* /var/lib/gitea/git/gitea-repositories
+mv repos/* /var/lib/gitea/git/repositories
 # adjust file permissions
 chown -R git:git /etc/gitea/app.ini /var/lib/gitea
 # Regenerate Git Hooks
@@ -173,4 +173,4 @@ gitea=# \i gitea-db.sql
 
 Disabling `synchronous_commit` makes PostgreSQL less resilient to crashes, but makes the import a lot faster. Since we already have a backup of the original database and we can check that the import completes successfully, it should be a good trade-off.
 
-After the import is completed, set up Gitea to use PostgreSQL and start the Gitea server again. Good luck!
+After the import is completed, set up Gitea to use PostgreSQL and start the Gitea server again. Good luck!

docs/administration/config-cheat-sheet.md

@@ -34,7 +34,7 @@ A full restart is required for Gitea configuration changes to take effect.
 
 ## Use environment variables to setup Gitea
 
-There is [environment-to-ini](https://github.com/go-gitea/gitea/tree/main/contrib/environment-to-ini) to help to
+There is [environment-to-ini](https://github.com/go-gitea/gitea/blob/main/docker/root/usr/local/bin/environment-to-ini) to help to
 generate Gitea's `app.ini` from environment variables.
 
 ## Default Internal Variables (non-`app.ini` configuration)
@@ -224,7 +224,8 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `DEFAULT_THEME`: **gitea-auto**: Set the default theme for the Gitea installation, custom themes could be provided by `{CustomPath}/public/assets/css/theme-*.css`.
 - `SHOW_USER_EMAIL`: **true**: Whether the email of the user should be shown in the Explore Users page.
 - `THEMES`: **_empty_**: All available themes by `{CustomPath}/public/assets/css/theme-*.css`. Allow users select personalized themes.
-- `FILE_ICON_THEME`: **material**: The icons for file list (basic/material).
+- `FILE_ICON_THEME`: **material**: The icon theme for files (basic/material).
+- `FOLDER_ICON_THEME`: **basic**: The icon theme for folders (basic/material).
 - `MAX_DISPLAY_FILE_SIZE`: **8388608**: Max size of files to be displayed (default is 8MiB)
 - `AMBIGUOUS_UNICODE_DETECTION`: **true**: Detect ambiguous unicode characters in file contents and show warnings on the UI
 - `REACTIONS`: All available reactions users can choose on issues/prs and comments
@@ -309,7 +310,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `ROOT_URL`: **`{PROTOCOL}://{DOMAIN}:{HTTP_PORT}/`**:
    Overwrite the automatically generated public URL.
    This is useful if the internal and the external URL don't match (e.g. behind a reverse proxy).
-- `PUBLIC_URL_DETECTION`: **`legacy`**: Controls how to generate the public URL. 
+- `PUBLIC_URL_DETECTION`: **`legacy`**: Controls how to generate the public URL.
    Although it defaults to "legacy" (to avoid breaking existing users), most instances should use the "auto" behavior,
    especially when the Gitea instance needs to be accessed in a container network.
    - "legacy": generate the public URL by "Host" header if "X-Forwarded-Proto" header exists, otherwise use "ROOT_URL".
@@ -819,7 +820,7 @@ and
   - Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or SMTP host is localhost. See [Email Setup](email-setup.md) for more information.
 - `ENABLE_HELO`: **true**: Enable HELO operation.
 - `HELO_HOSTNAME`: **(retrieved from system)**: HELO hostname.
-- `FROM`: **_empty_**: Mail from address, RFC 5322. This can be just an email address, or the "Name" `\<email@example.com\>` format.
+- `FROM`: **_empty_**: Mail from address, RFC 5322. This can be just an email address, or the `"Name" <email@example.com>` format.
 - `ENVELOPE_FROM`: **_empty_**: Address set as the From address on the SMTP mail envelope. Set to `<>` to send an empty address.
 - `FROM_DISPLAY_NAME_FORMAT`: **`{{ .DisplayName }}`**: If gitea sends mails on behave of users, it will just use the name also displayed in the WebUI. If you want e.g. `Mister X (by CodeIt) <gitea@codeit.net>`, set it to `{{ .DisplayName }} (by {{ .AppName }})`. Available Variables: `.DisplayName`, `.AppName` and `.Domain`.
 - `SUBJECT_PREFIX`: **_empty_**: Prefix to be placed before e-mail subject lines.
@@ -1203,14 +1204,12 @@ Synchronize external user data (only LDAP user synchronization is supported)
 - `LARGE_OBJECT_THRESHOLD`: **1048576**: (Go-Git only), don't cache objects greater than this in memory. (Set to 0 to disable.)
 - `DISABLE_CORE_PROTECT_NTFS`: **false** Set to true to forcibly set `core.protectNTFS` to false.
 - `DISABLE_PARTIAL_CLONE`: **false** Disable the usage of using partial clones for git.
+- `DIFF_RENAME_SIMILARITY_THRESHOLD`: **50%** Set the similarity threshold passed to git commands via `--find-renames=<threshold>`. Default is 50%, the same as git. Must be a integer percentage between 0% and 100%.
 
 ### Git - Timeout settings (`git.timeout`)
 
-- `DEFAULT`: **360**: Git operations default timeout seconds.
 - `MIGRATE`: **600**: Migrate external repositories timeout seconds.
 - `MIRROR`: **300**: Mirror external repositories timeout seconds.
-- `CLONE`: **300**: Git clone from internal repositories timeout seconds.
-- `PULL`: **300**: Git pull from internal repositories timeout seconds.
 - `GC`: **60**: Git repository GC timeout seconds.
 
 ### Git - Config options (`git.config`)

docs/administration/customizing-gitea.md

@@ -9,7 +9,7 @@ aliases:
 # Customizing Gitea
 
 Customizing Gitea is typically done using the `CustomPath` folder - by default this is
-the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/installation.md) has
+the `custom` folder from the working directory (WorkPath), but may be different if your [installation](../installation/from-binary.md) has
 set this differently. This is the central place to override configuration settings,
 templates, etc. You can check the `CustomPath` using `gitea help`. You can also find
 the path on the _Configuration_ tab in the _Site Administration_ page. You can override
@@ -23,7 +23,7 @@ the Linux Filesystem Standard. Gitea will attempt to create required folders, in
 `custom/`. Distributions may provide a symlink for `custom` using `/etc/gitea/`.
 
 Application settings can be found in file `CustomConf` which is by default,
-`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/installation.md) has set this differently.
+`$GITEA_CUSTOM/conf/app.ini` but may be different if your [installation](../installation/from-binary.md) has set this differently.
 Again `gitea help` will allow you review this variable and you can override it using the
 `--config` option on the `gitea` binary.
 
@@ -317,11 +317,17 @@ mkdir o3dv
 cd o3dv
 ```
 
-Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.16.0 as of now).
-Here use e.g. wget to download the file:
+Copy latest release zip link from [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) (v0.18.0 as of now).
+Here use e.g. wget or curl to download the file:
 
 ```
-wget https://github.com/kovacsv/Online3DViewer/releases/download/0.16.0/o3dv.zip
+wget https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
+```
+
+or
+
+```
+curl -L -O https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
 ```
 
 Use e.g. unzip to unzip the archive:
@@ -347,7 +353,7 @@ $GITEA_CUSTOM/templates
 
 $GITEA_CUSTOM/public/assets/
 -- o3dv
-   |-- o3dv_0.15.0.zip
+   |-- o3dv.zip
    |-- o3dv.license.md
    |-- o3dv.min.js
    |-- envmaps
@@ -414,7 +420,7 @@ The [legacy file format](https://github.com/go-gitea/gitea/blob/main/options/lab
 
 `#hex-color label name ; label description`
 
-For more information, see the [labels documentation](usage/labels.md).
+For more information, see the [labels documentation](../usage/issues-prs/labels.md).
 
 ### Licenses
 

docs/administration/email-setup.md

@@ -45,7 +45,7 @@ ENABLED        = true
 FROM           = gitea@mydomain.com
 PROTOCOL       = smtps
 SMTP_ADDR      = mail.mydomain.com
-SMTP_PORT      = 587
+SMTP_PORT      = 465
 USER           = gitea@mydomain.com
 PASSWD         = `password`
 ```

docs/administration/mail-templates.md

@@ -257,7 +257,6 @@ the messages. Here's a list of some of them:
 | `AppDomain`      | -           | Any       | Gitea's host name                                                   |
 | `EllipsisString` | string, int | Any       | Truncates a string to the specified length; adds ellipsis as needed |
 | `SanitizeHTML`   | string      | Body only | Sanitizes text by removing any dangerous HTML tags from it          |
-| `SafeHTML`       | string      | Body only | Takes the input as HTML, can be used for outputing raw HTML content |
 
 These are _functions_, not metadata, so they have to be used:
 

docs/administration/reverse-proxies.md

@@ -210,6 +210,50 @@ Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com
 The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
 :::
 
+## Apache HTTPD and serve static resources directly
+
+We can tune the performance in splitting requests into categories static and dynamic.
+
+CSS files, JavaScript files, images and web fonts are static content.
+The front page, a repository view or issue list is dynamic content.
+
+Apache HTTPD can serve static resources directly and proxy only the dynamic requests to Gitea.
+
+Download a snapshot of the Gitea source repository to `/path/to/gitea/`.
+After this, run `make frontend` in the repository directory to generate the static resources. We are only interested in the `public/` directory for this task, so you can delete the rest.
+(You will need to have [Node with npm](https://nodejs.org/en/download/) and `make` installed to generate the static resources)
+
+Depending on the scale of your user base, you might want to split the traffic to two distinct servers,
+or use a cdn for the static files.
+
+### Single node and single domain
+
+Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration.
+
+```apacheconf
+<VirtualHost *:80>
+    ...
+    <Proxy *>
+         Order allow,deny
+         Allow from all
+    </Proxy>
+
+    ProxyPass /_/static/ !
+    Alias /_/static/ /path/to/gitea/public/
+    <Directory /path/to/gitea/public/>
+        Options FollowSymlinks
+		AllowOverride None
+		Require all granted
+    </Directory>
+
+    AllowEncodedSlashes NoDecode
+    # Note: no trailing slash after either /git or port
+    ProxyPass / http://localhost:3000/ nocanon
+    ProxyPreserveHost On
+    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+</VirtualHost>
+```
+
 ## Caddy
 
 If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile:

docs/contributing/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Contributing",
+  "position": 35,
+  "link": {
+    "type": "generated-index",
+    "slug": "/contributing",
+    "title": "Contributing"
+  }
+}

docs/contributing/contributing.md

@@ -0,0 +1,76 @@
+---
+slug: "contributing"
+sidebar_position: 1
+---
+
+# Contributing to Gitea
+
+Thank you for your interest in contributing to Gitea! This guide will help you understand how to contribute to the project effectively.
+
+## Getting Started
+
+Before you start contributing, please read our [Hacking on Gitea](../development/hacking-on-gitea.md) guide to set up your development environment.
+
+## Contribution Guidelines
+
+We have specific guidelines for different types of contributions:
+
+### Backend Development
+
+If you're working on backend code (Go), please follow our [Guidelines for Backend Development](guidelines-backend.md). This includes:
+
+- Package design and dependencies
+- Database operations and migrations
+- Testing strategies
+- Code organization
+
+### Frontend Development
+
+For frontend contributions (JavaScript, CSS, Vue), refer to our [Guidelines for Frontend Development](guidelines-frontend.md). This covers:
+
+- Framework usage (Vue3, Fomantic-UI)
+- Code style and best practices
+- Accessibility requirements
+- TypeScript usage
+
+### Refactoring
+
+When refactoring existing code, follow our [Guidelines for Refactoring](guidelines-refactoring.md) to ensure:
+
+- Clear refactoring objectives
+- Proper review process
+- Maintaining backward compatibility
+- Incremental improvements
+
+### Localization
+
+To contribute translations or localization improvements, see our [Localization Guide](localization.md) which explains:
+
+- How to contribute translations via Crowdin
+- Supported languages
+- Translation workflow
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions with the community. We are committed to providing a welcoming and inclusive environment for all contributors.
+
+## Getting Help
+
+If you need help with your contribution:
+
+- Join our [Discord](https://discord.gg/gitea) #Develop channel
+- Visit our [Forum](https://forum.gitea.com/)
+- Check existing [GitHub Issues](https://github.com/go-gitea/gitea/issues)
+
+## Submitting Your Contribution
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes following the relevant guidelines
+4. Write tests for your changes
+5. Ensure all tests pass
+6. Submit a pull request
+
+For more details, see our [CONTRIBUTING.md](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md) in the main repository.
+
+Thank you for helping make Gitea better!

docs/development/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Development",
+  "position": 40,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development",
+    "title": "Development"
+  }
+}

docs/development/api-usage.md

@@ -20,14 +20,33 @@ Gitea supports these methods of API authentication:
 - `token=...` parameter in URL query string
 - `access_token=...` parameter in URL query string
 - `Authorization: token ...` header in HTTP headers
+- HTTP signatures using an SSH public key or SSH certificate
 
 All of these methods accept the same API key token type. You can
 better understand this by looking at the code -- as of this writing,
 Gitea parses queries and headers to find the token in
 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
 
+Gitea can also authenticate API requests using an SSH key or SSH certificate via
+HTTP signatures. The SSH public key (or certificate) must be registered to the
+user account in Gitea, and the client signs requests with the corresponding
+private key. The client signs requests using the SSH private key following the
+[draft-cavage-http-signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
+specification (not RFC 9421). The signature is sent in the `Signature` header,
+and SSH certificates additionally include an `x-ssh-certificate` header. The
+official [go-sdk](https://gitea.com/gitea/go-sdk) implements this flow if you
+need a reference implementation.
+
 ## Generating and listing API tokens
 
+API tokens can be created either in the user interface or via the API. Tokens have by default limited permissions and it is important to create tokens with the correct permissions for your task.
+### User Interface
+Tokens can be created via the `Manage Access Tokens` dialog, accessed via `User Settings` / `Applications` or via the link `gitea-domain.example/user/settings/applications`. The interface allows you to create tokens and manage their permissions via the `Select permissions` sub-menu.
+
+Once created, the token is displayed in a toast message above the `Manage Access Tokens` dialog. Please note, that you can view this toast only once and it is not possible to redisplay the token for security reasons.
+
+### Token API
+
 A new token can be generated with a `POST` request to
 `/users/:name/tokens`.
 
@@ -50,6 +69,25 @@ $ curl --url https://yourusername:password@gitea.your.host/api/v1/users/<usernam
 [{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
 ```
 
+By default, this creates a token with very limited permissions. To complete your tasks, your token may require extra permissions. These permissions are created via the json variable `scopes`, which takes an array of permissions as strings. Eg.: `"scopes":["all"]`. Possible permissions, as reflected in the user interface are:
+
+- `activitypub`
+- `admin`
+- `issue`
+- `misc`
+- `notification`
+- `organization`
+- `package`
+- `repository`
+- `user`
+
+Each permission may be set to `read` or `write`. `write` implies both Read & Write. To set permissions you write the permissions string as `<read or write>:<permission name>`, eg.: `write:package` or `read:notification`. A properly formatted API call may look like:
+
+```sh
+$ curl -H "Content-Type: application/json" -d '{"name":"test", "scopes":["write:package", "read:notification"]}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
+```
+Special permissions `all` may be specified as `"scopes":["all"]`, which sets all permissions to both Read & Write.
+
 To use the API with basic authentication with two factor authentication
 enabled, you'll need to send an additional header that contains the one
 time password (6 digitrotating token).

docs/development/hacking-on-gitea.md

@@ -174,7 +174,7 @@ server as mentioned above.
 
 ### Working on JS and CSS
 
-Frontend development should follow [Guidelines for Frontend Development](contributing/guidelines-frontend.md)
+Frontend development should follow [Guidelines for Frontend Development](../contributing/guidelines-frontend.md)
 
 To build with frontend resources, either use the `watch-frontend` target mentioned above or just build once:
 

docs/help/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Help",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "slug": "/help",
+    "title": "Help"
+  }
+}

docs/installation/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Installation",
+  "position": 10,
+  "link": {
+    "type": "generated-index",
+    "slug": "/installation",
+    "title": "Installation"
+  }
+}

docs/installation/from-binary.md

@@ -139,15 +139,15 @@ export GITEA_WORK_DIR=/var/lib/gitea/
 cp gitea /usr/local/bin/gitea
 ```
 
-### Adding bash/zsh autocompletion (from 1.19)
 
-A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This can be copied to `/usr/share/bash-completion/completions/gitea`
-or sourced within your `.bashrc`.
+### Adding shell autocompletion (from 1.25)
 
-Similarly a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
-`.zshrc`.
+Shell completion can be generated directly from binary with:
+```sh
+gitea completion <shell>
+```
 
-YMMV and these scripts may need further improvement.
+Supported values for `<shell>` are `bash`, `fish`, `pwsh` and `zsh`. Details on how to load the completion for your shell can be found in the completion command help.
 
 ## Running Gitea
 

docs/installation/from-source.md

@@ -178,15 +178,14 @@ LDFLAGS="-linkmode external -extldflags '-static' $LDFLAGS" TAGS="netgo osusergo
 
 This can be combined with `CC`, `GOOS`, and `GOARCH` as above.
 
-### Adding bash/zsh autocompletion (from 1.19)
+### Adding shell autocompletion (from 1.25)
 
-A script to enable bash-completion can be found at [`contrib/autocompletion/bash_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/bash_autocomplete). This should be altered as appropriate and can be `source` in your `.bashrc`
-or copied as `/usr/share/bash-completion/completions/gitea`.
+Shell completion can be generated directly from binary with:
+```sh
+gitea completion <shell>
+```
 
-Similarly, a script for zsh-completion can be found at [`contrib/autocompletion/zsh_autocomplete`](https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/autocompletion/zsh_autocomplete). This can be copied to `/usr/share/zsh/_gitea` or sourced within your
-`.zshrc`.
-
-YMMV and these scripts may need further improvement.
+Supported values for `<shell>` are `bash`, `fish`, `pwsh` and `zsh`. Details on how to load the completion for your shell can be found in the completion command help.
 
 ## Compile or cross-compile using Linux with Zig
 

docs/installation/with-docker-rootless.md

@@ -315,51 +315,3 @@ services:
 ```
 
 To set required TOKEN and SECRET values, consider using Gitea's built-in [generate utility functions](../administration/command-line.md#generate).
-
-# SSH Container Passthrough
-
-Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is to forward SSH commands from the host to the container. This setup is explained in the following.
-
-This guide assumes that you have created a user on the host called `git` with permission to run `docker exec`, and that the Gitea container is called `gitea`. You will need to modify that user's shell to forward the commands to the `sh` executable inside the container, using `docker exec`.
-
-First, create the file `/usr/local/bin/gitea-shell` on the host, with the following contents:
-
-```bash
-#!/bin/sh
-/usr/bin/docker exec -i --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
-```
-
-Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that.
-
-You should also make sure that you’ve set the permissions of the shell wrapper correctly:
-
-```bash
-sudo chmod +x /usr/local/bin/gitea-shell
-```
-
-Once the wrapper is in place, you can make it the shell for the `git` user:
-
-```bash
-sudo usermod -s /usr/local/bin/gitea-shell git
-```
-
-Now that all the SSH commands are forwarded to the container, you need to set up the SSH authentication on the host. This is done by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea. Add the following block to `/etc/ssh/sshd_config`, on the host:
-
-```bash
-Match User git
-  AuthorizedKeysCommandUser git
-  AuthorizedKeysCommand /usr/bin/docker exec -i gitea /usr/local/bin/gitea keys -c /etc/gitea/app.ini -e git -u %u -t %t -k %k
-```
-
-(From 1.16.0 you will not need to set the `-c /etc/gitea/app.ini` option.)
-
-All that is left to do is restart the SSH server:
-
-```bash
-sudo systemctl restart sshd
-```
-
-**Notes**
-
-This isn't actually using the docker SSH - it is simply using the commands around it.
-You could theoretically not run the internal SSH server.

docs/installation/with-docker.md

@@ -331,320 +331,6 @@ services:
       - GITEA__security__INTERNAL_TOKEN=[value returned by generate secret INTERNAL_TOKEN]
 ```
 
-## SSH Container Passthrough
-
-Since SSH is running inside the container, SSH needs to be passed through from the host to the container if SSH support is desired. One option would be to run the container SSH on a non-standard port (or moving the host port to a non-standard port). Another option which might be more straightforward is for Gitea users to ssh to a Gitea user on the host which will then relay those connections to the docker. Alternatively, if the host machine has more than one IP address, the host can listen on one and Gitea on another.
-
-### Understanding SSH access to Gitea (without passthrough)
-
-To understand what needs to happen, you first need to understand what happens without passthrough. So we will try to explain this:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
-3. This entry has the public key, but also has a `command=` option. It is this command that Gitea uses to match this key to the client user and manages authentication.
-4. The client then makes an SSH request to the SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-5. The client will attempt to authenticate with the server, passing one or more public keys one at a time to the server.
-6. For each key the client provides, the SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the `git` user's `authorized_keys` file.
-7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
-8. The SSH server creates a user session for the `git` user, and using the shell for the `git` user runs the `command=`
-9. This runs `gitea serv` which takes over control of the rest of the SSH session and manages gitea authentication & authorization of the git commands.
-
-Now, for the SSH passthrough to work, we need the host SSH to match the public keys and then run the `gitea serv` on the docker. There are multiple ways of doing this. However, all of these require some information about the docker being passed to the host.
-
-### SSHing Shim (with authorized_keys)
-
-In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 9 the `gitea` command that the host runs is a shim that actually runs ssh to go into the docker and then run the real docker `gitea` itself.
-
-- To make the forwarding work, the SSH port of the container (22) needs to be mapped to the host port 2222 in `docker-compose.yml` . Since this port does not need to be exposed to the outside world, it can be mapped to the `localhost` of the host machine:
-
-  ```yaml
-  ports:
-    # [...]
-    - "127.0.0.1:2222:22"
-  ```
-
-- Next on the host create the `git` user which shares the same `UID`/ `GID` as the container values `USER_UID`/ `USER_GID`. These values can be set as environment variables in the `docker-compose.yml`:
-
-  ```yaml
-  environment:
-    - USER_UID=1000
-    - USER_GID=1000
-  ```
-
-- Mount `/home/git/.ssh` of the host into the container. This ensures that the `authorized_keys` file is shared between the host `git` user and the container `git` user otherwise the SSH authentication cannot work inside the container.
-
-  ```yaml
-  volumes:
-    - /home/git/.ssh/:/data/git/.ssh
-  ```
-
-- Now a SSH key pair needs to be created on the host. This key pair will be used to authenticate the `git` user on the host to the container. As an administrative user on the host run: (by administrative user we mean a user that can sudo to root)
-
-  ```bash
-  sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
-  ```
-
-- Please note depending on the local version of ssh you may want to consider using `-t ecdsa` here.
-
-- `/home/git/.ssh/authorized_keys` on the host now needs to be modified. It needs to act in the same way as `authorized_keys` within the Gitea container. Therefore add the public key of the key you created above ("Gitea Host Key") to `/home/git/.ssh/authorized_keys`. As an administrative user on the host run:
-
-  ```bash
-  sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
-  sudo -u git chmod 600 /home/git/.ssh/authorized_keys
-  ```
-
-  Important: The pubkey from the `git` user needs to be added "as is" while all other pubkeys added via the Gitea web interface will be prefixed with `command="/usr [...]`.
-
-  `/home/git/.ssh/authorized_keys` should then look somewhat like
-
-  ```bash
-  # SSH pubkey from git user
-  ssh-rsa <Gitea Host Key>
-
-  # other keys from users
-  command="/usr/local/bin/gitea --config=/data/gitea/conf/app.ini serv key-1",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <user pubkey>
-  ```
-
-- The next step is to create the fake host `gitea` command that will forward commands from the host to the container. The name of this file depends on your version of Gitea:
-
-  - For Gitea v1.16.0+. As an administrative user on the host run:
-
-    ```bash
-    cat <<"EOF" | sudo tee /usr/local/bin/gitea
-    #!/bin/sh
-    ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
-    EOF
-    sudo chmod +x /usr/local/bin/gitea
-    ```
-
-Here is a detailed explanation what is happening when a SSH request is made:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
-    - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
-3. This entry has the public key, but also has a `command=` option.
-    - This command matches the location of the Gitea binary on the container, but also the location of the shim on the host.
-4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
-6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
-    - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
-7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
-8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
-9. This means that the host runs the host `/usr/local/bin/gitea` shim that opens an SSH from the host to container passing the rest of the command arguments directly to `/usr/local/bin/gitea` on the container.
-10. Meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
-
-**Notes**
-
-SSH container passthrough using `authorized_keys` will work only if
-
-- `opensshd` is used in the container
-- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
-- `LOCAL_ROOT_URL` is not changed (depending on the changes)
-
-If you try to run `gitea` on the host, you will attempt to ssh to the container and thence run the `gitea` command there.
-
-Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
-
-### SSHing Shell (with authorized_keys)
-
-In this option, the idea is that the host simply uses the `authorized_keys` that gitea creates but at step 8 above we change the shell that the host runs to ssh directly into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
-
-- In this case we setup as per SSHing Shim except instead of creating `/usr/local/bin/gitea`
-we create a new shell for the git user. As an administrative user on the host run:
-
-  ```bash
-  cat <<"EOF" | sudo tee /home/git/ssh-shell
-  #!/bin/sh
-  shift
-  ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $@"
-  EOF
-  sudo chmod +x /home/git/ssh-shell
-  sudo usermod -s /home/git/ssh-shell git
-  ```
-
-  Be careful here - if you try to login as the git user in future you will ssh directly to the docker.
-
-Here is a detailed explanation what is happening when a SSH request is made:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
-    - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
-3. This entry has the public key, but also has a `command=` option.
-    - This command matches the location of the Gitea binary on the container.
-4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
-6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
-    - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
-7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
-8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
-9. The shell of the host `git` user is now our `ssh-shell` which opens an SSH connection from the host to container, (which opens a shell on the container for the container `git`).
-10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
-
-**Notes**
-
-SSH container passthrough using `authorized_keys` will work only if
-
-- `opensshd` is used in the container
-- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
-- `LOCAL_ROOT_URL` is not changed (depending on the changes)
-
-If you try to login as the `git` user on the host in future you will ssh directly to the docker.
-
-Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
-
-### Docker Shell (with authorized_keys)
-
-Similar to the above ssh shell technique we can use a shell which simply uses `docker exec`. As an administrative user on the host run:
-
-```bash
-cat <<"EOF" | sudo tee /home/git/docker-shell
-#!/bin/sh
-/usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
-EOF
-sudo chmod +x /home/git/docker-shell
-sudo usermod -s /home/git/docker-shell git
-```
-
-Here is a detailed explanation what is happening when a SSH request is made:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea in the container will add an entry for this key to the `.ssh/authorized_keys` file of its running user, `git`.
-    - However, because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key has been added to the host `git` user's `authorized_keys` file too.
-3. This entry has the public key, but also has a `command=` option.
-    - This command matches the location of the Gitea binary on the container.
-4. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-5. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
-6. For each key the client provides, the host SSH server will first check its configuration for an `AuthorizedKeysCommand` to see if the public key matches, and then the host `git` user's `authorized_keys` file.
-    - Because `/home/git/.ssh/` on the host is mounted as `/data/git/.ssh` this means that the key they added to the Gitea web will be found
-7. The first entry that matches will be selected, and assuming this is a Gitea entry, the `command=` will now be executed.
-8. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`
-9. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
-10. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
-
-Note that `gitea` in the docker command above is the name of the container. If you named yours differently, don't forget to change that. The host `git` user also has to have
-permission to run `docker exec`.
-
-**Notes**
-
-Docker shell passthrough using `authorized_keys` will work only if
-
-- `opensshd` is used in the container
-- if `AuthorizedKeysCommand` is _not used_ in combination with `SSH_CREATE_AUTHORIZED_KEYS_FILE=false` to disable authorized files key generation
-- `LOCAL_ROOT_URL` is not changed (depending on the changes)
-
-If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
-
-A Docker execing shim could be created similarly to above.
-
-### Docker Shell with AuthorizedKeysCommand
-
-The AuthorizedKeysCommand route provides another option that does not require many changes to the compose file or the `authorized_keys` - but does require changes to the host `/etc/sshd_config`.
-
-In this option, the idea is that the host SSH uses an `AuthorizedKeysCommand` instead of relying on sharing the `authorized_keys` file that gitea creates. We continue to use a special shell at step 8 above to exec into the docker and then run the shell there. This means that the `gitea` that is then run is the real docker `gitea`.
-
-- On the host create a `git` user with permission to run `docker exec`.
-- We will again assume that the Gitea container is called `gitea`.
-- Modify the `git` user's shell to forward commands to the `sh` executable inside the container using `docker exec`.  As an administrative user on the host run:
-
-  ```bash
-  cat <<"EOF" | sudo tee /home/git/docker-shell
-  #!/bin/sh
-  /usr/bin/docker exec -i -u git --env SSH_ORIGINAL_COMMAND="$SSH_ORIGINAL_COMMAND" gitea sh "$@"
-  EOF
-  sudo chmod +x /home/git/docker-shell
-  sudo usermod -s /home/git/docker-shell git
-  ```
-
-Now all attempts to login as the `git` user on the host will be forwarded to the docker - including the `SSH_ORIGINAL_COMMAND`. We now need to set-up SSH authentication on the host.
-
-We will do this by leveraging the [SSH AuthorizedKeysCommand](../administration/command-line.md#keys) to match the keys against those accepted by Gitea.
-
-Add the following block to `/etc/ssh/sshd_config`, on the host:
-
-```bash
-Match User git
-  AuthorizedKeysCommandUser git
-  AuthorizedKeysCommand /usr/bin/docker exec -i -u git gitea /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
-```
-
-(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
-
-Finally restart the SSH server. As an administrative user on the host run:
-
-```bash
-sudo systemctl restart sshd
-```
-
-Here is a detailed explanation what is happening when a SSH request is made:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea in the container will add an entry for this key to its database.
-3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
-5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
-6. The host runs the above `AuthorizedKeysCommand`, which execs in to the docker and then runs the `gitea keys` command.
-7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
-8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
-9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
-10. The shell of the host `git` user is now our `docker-shell` which uses `docker exec` to open a shell for the `git` user on the container.
-11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
-
-**Notes**
-
-Docker shell passthrough using `AuthorizedKeysCommand` will work only if
-
-- The host `git` user is allowed to run the `docker exec` command.
-
-If you try to login as the `git` user on the host in future you will `docker exec` directly to the docker.
-
-A Docker execing shim could be created similarly to above.
-
-### SSH Shell with AuthorizedKeysCommand
-
-Create a key for the host `git` user as above, add it to the docker `/data/git/.ssh/authorized_keys` then finally create and set the `ssh-shell` as above.
-
-Add the following block to `/etc/ssh/sshd_config`, on the host:
-
-```bash
-Match User git
-  AuthorizedKeysCommandUser git
-  AuthorizedKeysCommand /usr/bin/ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 /usr/local/bin/gitea keys -c /data/gitea/conf/app.ini -e git -u %u -t %t -k %k
-```
-
-(From 1.16.0 you will not need to set the `-c /data/gitea/conf/app.ini` option.)
-
-Finally restart the SSH server. As an administrative user on the host run:
-
-```bash
-sudo systemctl restart sshd
-```
-
-Here is a detailed explanation what is happening when a SSH request is made:
-
-1. The client adds their SSH public key to Gitea using the webpage.
-2. Gitea in the container will add an entry for this key to its database.
-3. The client then makes an SSH request to the host SSH server using the `git` user, e.g. `git clone git@domain:user/repo.git`.
-4. The client will attempt to authenticate with the server, passing one or more public keys in turn to the host.
-5. For each key the client provides, the host SSH server will checks its configuration for an `AuthorizedKeysCommand`.
-6. The host runs the above `AuthorizedKeysCommand`, which will SSH in to the docker and then run the `gitea keys` command.
-7. Gitea on the docker will look in it's database to see if the public key matches and will return an entry like that of an `authorized_keys` command.
-8. This entry has the public key, but also has a `command=` option which matches the location of the Gitea binary on the container.
-9. The host SSH server creates a user session for the `git` user, and using the shell for the host `git` user runs the `command=`.
-10. The shell of the host `git` user is now our `git-shell` which uses SSH to open a shell for the `git` user on the container.
-11. The container shell now runs the `command=` option meaning that the container `gitea serv` is run, taking over control of the rest of the SSH session and managing gitea authentication & authorization of the git commands.
-
-**Notes**
-
-SSH container passthrough using `AuthorizedKeysCommand` will work only if
-
-- `opensshd` is running on the container
-
-If you try to login as the `git` user on the host in future you will `ssh` directly to the docker.
-
-Never add the `Gitea Host Key` as a SSH key to a user on the Gitea interface.
-
-SSHing shims could be created similarly to above.
-
 ### SSH with multiple IP addresses
 This assumes that the host machine has more than one reachable IP address: `192.168.1.1` (host) `192.168.1.2` (gitea)
 On the host machine, configure SSHD in `/etc/ssh/sshd_config` to listen on one IP address `ListenAddress 192.168.1.1`. In the compose file the SSH port forwarding then needs to be changed to `"192.168.1.2:22:22"`. The port forwarding needs to be adjusted similarily for all other forwarded ports to avoid problems with DNS.

docs/usage/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Usage",
+  "position": 35,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage",
+    "title": "Usage"
+  }
+}

docs/usage/access-control/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Access Control",
+  "position": 100,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/access-control",
+    "description": "Permissions, security, and access control features"
+  }
+}

docs/usage/access-control/blocking-users.md

@@ -0,0 +1,47 @@
+---
+date: "2024-01-31T00:00:00+00:00"
+slug: "blocking-user"
+sidebar_position: 25
+aliases:
+  - /blocking-user
+---
+
+# Blocking a user
+
+Gitea supports blocking of users to restrict how they can interact with you and your content.
+
+You can block a user in your account settings, from the user's profile or from comments created by the user.
+The user is not directly notified about the block, but they can notice they are blocked when they attempt to interact with you.
+Organization owners can block anyone who is not a member of the organization too.
+If a blocked user has admin permissions, they can still perform all actions even if blocked.
+
+### When you block a user
+
+- the user stops following you
+- you stop following the user
+- the user's stars are removed from your repositories
+- your stars are removed from their repositories
+- the user stops watching your repositories
+- you stop watching their repositories
+- the user's issue assignments are removed from your repositories
+- your issue assignments are removed from their repositories
+- the user is removed as a collaborator on your repositories
+- you are removed as a collaborator on their repositories
+- any pending repository transfers to or from the blocked user are canceled
+
+### When you block a user, the user cannot
+
+- follow you
+- watch your repositories
+- star your repositories
+- fork your repositories
+- transfer repositories to you
+- open issues or pull requests on your repositories
+- comment on issues or pull requests you've created
+- comment on issues or pull requests on your repositories
+- react to your comments on issues or pull requests
+- react to comments on issues or pull requests on your repositories
+- assign you to issues or pull requests
+- add you as a collaborator on their repositories
+- send you notifications by @mentioning your username
+- be added as team member (if blocked by an organization)

docs/usage/access-control/permissions.md

@@ -1,11 +1,10 @@
 ---
 date: "2021-12-13:10:10+08:00"
-
 slug: "permissions"
 sidebar_position: 14
-
 aliases:
   - /en-us/permissions
+  - /permissions
 ---
 
 # Permissions
@@ -41,7 +40,7 @@ With different permissions, people could do different things with these units.
 | Wiki            | View wiki pages. Clone the wiki repository.        | Create/Edit wiki pages, push | -                         |
 | ExternalWiki    | Link to an external wiki                           | -                            | -                         |
 | ExternalTracker | Link to an external issue tracker                  | -                            | -                         |
-| Projects        | View the boards                                    | Change issues across boards  | -                         |
+| Projects        | View the columns of projects                       | Change issues across columns | -                         |
 | Packages        | View the packages                                  | Upload/Delete packages       | -                         |
 | Actions         | View the Actions logs                              | Approve / Cancel / Restart   | -                         |
 | Settings        | -                                                  | -                            | Manage the repository     |

docs/usage/access-control/protected-branches.md

@@ -0,0 +1,90 @@
+---
+date: "2025-11-20T00:00:00-07:00"
+slug: "protected-branches"
+sidebar_position: 44
+aliases:
+  - /en-us/protected-branches
+  - /en-us/protected-branch
+  - /protected-branches
+---
+
+# Protected branches
+
+Protected branches prevent unwanted changes by enforcing push and merge policies on selected branches. The rules are enforced for every Git protocol (HTTP(S), SSH), the web editor, the API, and background jobs such as auto-merge. Only repository owners and administrators can manage the rules, and the Branches page is read-only while a repository is archived.
+
+## Creating or editing a rule
+
+1. Open the repository and select **Settings → Branches** (repository admin permission required).
+2. Select **Add new rule** or **Edit** next to an existing rule.
+3. Fill in the **Protected branch name pattern** and optional file patterns, then configure the push, merge, and review options described below.
+4. Select **Save rule**.
+
+The rule immediately applies to all matching branches, even if the branches are created in the future.
+
+## Rule matching and priorities
+
+- The **Protected branch name pattern** accepts [glob](https://github.com/gobwas/glob) expressions and matches the entire branch name. Patterns are case-sensitive. Using a simple name such as `main` without glob special characters always matches that specific branch (case-insensitive).
+- If multiple rules match the same branch, only the first rule is used. Reorder the list on the **Branches** page by dragging the grab handle. The first entry (priority 1) has the highest priority, so place patterns such as `main` or `release/*` before generic fallbacks such as `*`.
+
+Example patterns:
+
+| Pattern        | Matches                         |
+| -------------- | ------------------------------- |
+| `main`         | The `main` branch only          |
+| `release/*`    | `release/v1.0`, `release/april` |
+| `hotfix/**`    | Nested branches such as `hotfix/security/CVE` |
+| `*`            | Every branch (use as a fallback) |
+
+### File-level pattern controls
+
+- **Protected file patterns** block changes to sensitive files (for example `.drone.yml` or `/docs/**/*.txt`). Patterns are case-insensitive and separated by semicolons. Commits and merge attempts that touch one of the files are rejected.
+- **Unprotected file patterns** do the opposite: if pushes are blocked, users with write access can still push commits that modify only the listed files. This is useful for letting contributors update documentation while still requiring pull requests for code.
+
+Both fields use the same `glob` syntax and match paths relative to the repository root.
+
+## Controlling direct pushes
+
+The **Push** section controls direct pushes (including the web editor and API).
+
+- **Disable push** makes the branch read-only. Any attempt to push directly fails, and changes must be merged through pull requests.
+- **Enable push** allows anyone with [write access](./permissions.md) to push (force pushes are still blocked unless explicitly allowed).
+- **Allowlist restricted push** requires being on the allowlist. Choose users and, for organization-owned repositories, teams. Deploy keys that already have write access can also be allowlisted.
+
+When a push is blocked, the server-side hook rejects the update with an explanation.
+
+### Force pushes
+
+Force pushes have their own set of options:
+
+- **Disable force push** completely forbids rewriting history on the branch.
+- **Enable force push** allows anyone who can push to also force push.
+- **Allowlist restricted force push** limits force pushes to a separate allowlist (users, teams, and optionally deploy keys) **and** requires the person to already have regular push access.
+
+## Pull request merges and approvals
+
+- **Merge allowlist**: keep the default to let anyone with write access merge pull requests, or enable the allowlist to restrict merges to selected users/teams.
+- **Required approvals**: specify how many approvals are needed before a merge is allowed. Reviews from users with write access count, unless the **Restrict approvals to allowlisted users or teams** option is enabled.
+- **Dismiss stale approvals** removes existing approvals whenever new commits that change the pull request content are pushed.
+- **Ignore stale approvals** keeps approvals but does not count reviews that were made on older commits. This option is disabled while dismissal of stale approvals is enabled.
+- **Block merge on rejected reviews** prevents merging while any official reviewer has requested changes.
+- **Block merge on official review requests** blocks merges while there are outstanding review requests (for example when CODEOWNERS requires a review).
+- **Block merge if the pull request is outdated** makes sure the head branch is up to date with the base branch before it can be merged.
+- **Administrators must follow branch protection rules** removes the ability for repository administrators to bypass the rules with the "Force merge" button.
+
+Protected file patterns apply to pull requests as well. When a pull request changes one of the protected files, the pull request banner shows the affected paths and merging stays disabled.
+
+## Status checks
+
+Enable status checks to require one or more CI jobs to succeed before merging:
+
+1. Check **Enable status check**.
+2. Enter one pattern per line in **Status check patterns**. Each pattern is a `glob` expression that matches the context name reported by Actions, Drone, Woodpecker, or another Check API client (for example `actions/test-*`).
+3. Pick contexts from the table of jobs that have reported results in the last week to verify their names.
+
+When the option is active, Gitea requires at least one context that matches each pattern to report success on the pull request head commit. An empty list is not allowed; use `*` to require the latest commit to be successful regardless of the context name.
+
+## Signed commits and other safeguards
+
+- **Require signed commits** rejects pushes that contain unsigned or unverifiable commits. The check runs inside the server hook before the push is accepted.
+- **Protected file patterns** (see above) prevent both pushes and merges that modify sensitive files.
+- **Unprotected file patterns** allow limited pushes while keeping the branch protected.

docs/usage/access-control/protected-tags.md

@@ -1,12 +1,10 @@
 ---
 date: "2021-05-14T00:00:00-00:00"
-
 slug: "protected-tags"
 sidebar_position: 45
-
 aliases:
   - /en-us/protected-tags
-
+  - /protected-tags
 ---
 
 # Protected tags

docs/usage/actions/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Actions",
+  "position": 30,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/actions",
+    "description": "Automating workflows with Actions"
+  }
+}

docs/usage/actions/act-runner.mdx

@@ -0,0 +1,459 @@
+---
+date: "2023-04-27T15:00:00+08:00"
+slug: "act-runner"
+sidebar_position: 20
+---
+
+# Act Runner
+
+This page will introduce the [act runner](https://gitea.com/gitea/act_runner) in detail, which is the runner for Gitea Actions.
+
+## Requirements
+
+Currently the runner supports three modes in which it can be run.
+1. Host: act_runner will run as an application on the host. This provides no encapsulation.
+2. Docker (recommended): Runs jobs in a [Docker](https://docker.com) container. If you choose this mode, you need to [install Docker](https://docs.docker.com/engine/install/) first and make sure that the Docker daemon is running.
+3. Docker-in-Docker (DinD): Puts the runner into rootless mode. It then runs in a Docker container with its own Docker daemon that has fewer privileges. It will spawn job containers from there. Best security but more complex setup.
+
+Other OCI container engines which are compatible with Docker's API should also work, but are untested.
+
+However, if you are sure that you want to run jobs directly on the host only, then Docker is not required.
+
+There are multiple ways to install the act runner.
+
+## Installation with binary
+
+### Download the binary
+
+You can download the binary from the [release page](https://gitea.com/gitea/act_runner/releases).
+However, if you want to use the latest nightly build, you can download it from the [download page](https://dl.gitea.com/act_runner/).
+
+When you download the binary, please make sure that you have downloaded the correct one for your platform.
+You can check it by running the following command if you are in a Unix-style OS.
+
+```bash
+chmod +x act_runner
+./act_runner --version
+```
+
+If you see the version information, it means that you have downloaded the correct binary.
+
+### Obtain a registration token
+
+You can register a runner at different levels. It can be:
+
+- Instance level: The runner will run jobs for all repositories in the instance.
+- Organization level: The runner will run jobs for all repositories in the organization.
+- Repository level: The runner will run jobs for the repository it belongs to.
+
+Note that the repository may still use instance-level or organization-level runners even if it has its own repository-level runners. A future release may provide an option to allow more control over this.
+
+
+Before registering the runner and running it, you need a registration token. The level of the runner determines where to obtain the registration token.
+
+- Instance level: The admin settings page, like `<your_gitea.com>/-/admin/actions/runners`.
+- Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`.
+- Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`.
+
+If you cannot see the settings page, please make sure that you have the right permissions and that Actions have been enabled.
+
+The format of the registration token is a random string `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`.
+
+A registration token can also be obtained from the Gitea [command-line interface](../../administration/command-line.md#actions-generate-runner-token):
+
+```
+gitea --config /etc/gitea/app.ini actions generate-runner-token
+```
+
+You can also use `GITEA_RUNNER_REGISTRATION_TOKEN`/`GITEA_RUNNER_REGISTRATION_TOKEN_FILE` environment variables to set a global runner registration token when Gitea starts, for example:
+
+```
+openssl rand -hex 24 > /some-dir/runner-token
+export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
+./gitea --config ...
+```
+
+The token from the environment is valid until you reset the token (re-create a new one) via the web UI or API.
+
+Tokens are valid for registering multiple runners, until they are revoked and replaced by a new token using the token reset link in the web interface.
+
+### Configuration
+
+Configuration is done via a configuration file. It is optional, and the default configuration will be used when no configuration file is specified. You can generate a configuration file by running the following command:
+
+```bash
+./act_runner generate-config
+```
+
+The default configuration is safe to use without any modification, so you can just use it directly.
+
+```bash
+./act_runner generate-config > config.yaml
+./act_runner --config config.yaml [command]
+```
+
+### Register the runner
+
+Registration is required before running the act runner, because the runner needs to know where to get jobs from. It is also important for the Gitea instance to identify the runner.
+
+If this has been installed using the binary package, the act runner can be registered by running the following command.
+
+```bash
+./act_runner register
+```
+
+Alternatively, you can use the `--config` option to specify the configuration file mentioned in the previous section.
+
+```bash
+./act_runner --config config.yaml register
+```
+
+You will be asked to input the registration information step by step. This includes:
+
+- The Gitea instance URL, like `https://gitea.com/` or `http://192.168.8.8:3000/`.
+- The registration token.
+- The runner name, which is optional. If you leave it blank, the hostname will be used.
+- The runner labels, which is optional. If you leave it blank, the default labels will be used.
+
+You may be confused about the runner labels, which will be explained later.
+
+If you want to register the runner in a non-interactive way, you can use arguments to do it.
+
+```bash
+./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
+```
+
+When you have registered the runner, you can find a new file named `.runner` in the current directory.
+This file stores the registration information.
+Please do not edit it manually.
+If this file is missing or corrupted, you can simply remove it and register again.
+
+If you want to store the registration information in another place, you can specify it in the configuration file,
+and don't forget to specify the `--config` option.
+
+#### Ephemeral Runners
+
+Ephemeral runners provide a security hardening mechanism for enabling organization- or instance-wide runners without requiring full user trust. Once a job is assigned within a spot VM or container, the runner's exposed credentials are automatically revoked—blocking it from polling further jobs before any untrusted code runs, while still allowing it to report progress until completion by either Gitea or the runner.
+
+act_runner **0.2.12+** is required.
+
+The updated commands for registering the runner as ephemeral are listed below. Refer to the previous section for detailed information on registering the act_runner.
+
+```bash
+./act_runner register --ephemeral
+```
+
+```bash
+./act_runner --config config.yaml register --ephemeral
+```
+
+```bash
+./act_runner register --no-interactive --ephemeral --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
+```
+
+The runner must be registered each time it is intended to receive a job. After completing the single job it is designed to execute, the runner terminates.
+
+To automate the registration and startup of new runners when a job is queued, use the `workflow_job` webhook.
+
+### Start the runner from the command line
+
+After you have registered the runner, you can run it with the following command:
+
+```shell
+./act_runner daemon
+```
+
+or
+
+```bash
+./act_runner daemon --config config.yaml
+```
+
+The runner will fetch jobs from the Gitea instance and run them automatically.
+
+### Start the runner with Systemd
+
+It is also possible to run act-runner as a [systemd](https://en.wikipedia.org/wiki/Systemd) service. Create an unprivileged `act_runner` user on your system, and create the following file in `/etc/systemd/system/act_runner.service`. The paths in `ExecStart` and `WorkingDirectory` may need to be adjusted depending on where you installed the `act_runner` binary, its configuration file, and the home directory of the `act_runner` user.
+
+```ini
+[Unit]
+Description=Gitea Actions runner
+Documentation=https://gitea.com/gitea/act_runner
+After=docker.service
+
+[Service]
+ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
+ExecReload=/bin/kill -s HUP $MAINPID
+WorkingDirectory=/var/lib/act_runner
+TimeoutSec=0
+RestartSec=10
+Restart=always
+User=act_runner
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Then:
+
+```bash
+# load the new systemd unit file
+sudo systemctl daemon-reload
+# start the service and enable it at boot
+sudo systemctl enable act_runner --now
+```
+
+If using Docker, the `act_runner` user should also be added to the `docker` group before starting the service. Keep in mind that this effectively gives `act_runner` root access to the system [[1]](https://docs.docker.com/engine/security/#docker-daemon-attack-surface).
+
+### Start the runner with LaunchDaemon (macOS)
+
+Mac uses `launchd` in place of systemd for registering daemon processes. By default, daemons run as the root user, so if desired an unprivileged `_act_runner` user can be created via the `dscl` tool. The following file should then be created in the directory `/Library/LaunchDaemon/com.gitea.act_runner.plist`. The paths for `WorkingDirectory`, `ProgramArguments`, `StandardOutPath`, `StandardErrPath`, and the `HOME` environment variable may need to be updated to reflect your installation. Also note that any executables outside of the example `PATH` shown will need to be explicitly included and will not be inherited from existing configurations.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.gitea.act_runner</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/local/bin/act_runner</string>
+        <string>daemon</string>
+        <string>--config</string>
+        <string>/etc/act_runner/config.yaml</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>WorkingDirectory</key>
+    <string>/var/lib/act_runner</string>
+    <key>StandardOutPath</key>
+    <string>/var/lib/act_runner/act_runner.log</string>
+    <key>StandardErrorPath</key>
+    <string>/var/lib/act_runner/act_runner.err</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <key>HOME</key>
+        <string>/var/lib/act_runner</string>
+    </dict>
+    <key>UserName</key>
+    <string>_act_runner</string>
+</dict>
+</plist>
+```
+
+Then:
+
+```bash
+sudo launchctl load /Library/LaunchDaemon/com.gitea.act_runner.plist
+```
+
+You can also set up a Linux or Windows service to let the runner run automatically.
+
+## Install with the docker image
+
+### Pull the image
+
+You can use the docker image from [Docker Hub](https://hub.docker.com/r/gitea/act_runner/tags).
+Just like the binary, you can use the latest nightly build by using the `nightly` tag, while the `latest` tag is the latest stable release.
+
+```bash
+docker pull docker.io/gitea/act_runner:latest # for the latest stable release
+```
+
+If you want to use the newest or experimental features, you can also use the nightly image.
+```bash
+docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
+```
+
+### Configuration
+
+Configuration is optional, but you can also generate a config file with docker:
+
+```bash
+docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner generate-config > config.yaml
+```
+
+When you are using the docker image, you can specify the configuration file by using the `CONFIG_FILE` environment variable. Make sure that the file is mounted into the container as a volume:
+
+```bash
+docker run -v $PWD/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
+```
+
+You may notice the commands above are incomplete because it is not time to run the act runner yet.
+Before running the act runner, we need to register it to your Gitea instance first.
+
+### Start the runner with docker
+
+If you are using the docker image, behavior will be slightly different. Registration and running are combined into one step in this case, so you need to specify the registration information when running the act runner.
+
+A quick start with docker run along with a minimal parameter set is shown below. You need to get the `<registration_token>` from the above step, and set a unique name for `<gitea_runner_name>` and for `<container_name>`.
+
+```bash
+docker run \
+    -e GITEA_INSTANCE_URL=<instance_url> \
+    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
+    -e GITEA_RUNNER_NAME=<gitea_runner_name> \
+    --name <container_name> \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -d docker.io/gitea/act_runner:latest
+```
+
+You can add more parameters to use a custom config, add a `data` directory for non-volatile file storage, etc.
+
+```bash
+docker run \
+    -v $PWD/config.yaml:/config.yaml \
+    -v $PWD/data:/data \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -e CONFIG_FILE=/config.yaml \
+    -e GITEA_INSTANCE_URL=<instance_url> \
+    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
+    -e GITEA_RUNNER_NAME=<gitea_runner_name> \
+    -e GITEA_RUNNER_LABELS=<runner_labels> \
+    --name <container_name> \
+    -d docker.io/gitea/act_runner:latest
+```
+
+You may notice that we have mounted `/var/run/docker.sock` into the container.
+This is because with this setup, act runner will execute jobs in temporary Docker containers, so it needs to communicate with the Docker daemon.
+As mentioned, you can remove it if you want to run jobs on the host directly.
+To be clear, the "host" actually means the container that is running the act runner now, instead of the host machine.
+
+---
+
+To enable ephemeral runners, set the environment variable `GITEA_RUNNER_EPHEMERAL=1` in the runner image. This setup doesn't use a `/data` volume because the credentials are single-use and not intended to be reused. You can find more details about this mode under [Ephemeral runners](#ephemeral-runners).
+
+```bash
+docker run \
+    -e GITEA_INSTANCE_URL=<instance_url> \
+    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
+    -e GITEA_RUNNER_EPHEMERAL=1 \
+    -e GITEA_RUNNER_NAME=<runner_name> \
+    --name my_runner \
+    -d docker.io/gitea/act_runner:nightly
+```
+
+```bash
+docker run \
+    -v $PWD/config.yaml:/config.yaml \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -e CONFIG_FILE=/config.yaml \
+    -e GITEA_INSTANCE_URL=<instance_url> \
+    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
+    -e GITEA_RUNNER_EPHEMERAL=1 \
+    -e GITEA_RUNNER_NAME=<runner_name> \
+    -e GITEA_RUNNER_LABELS=<runner_labels> \
+    --name my_runner \
+    -d docker.io/gitea/act_runner:nightly
+```
+
+Mounting the host's Docker socket using `/var/run/docker.sock:/var/run/docker.sock` introduces a potential security vulnerability. If a job can access this socket, the reusable `GITEA_RUNNER_REGISTRATION_TOKEN` could be exposed through Docker inspect data.
+
+### Start the runner using docker compose
+
+You could also set up the runner using the following `docker-compose.yml`:
+
+```yml
+version: "3.8"
+services:
+  runner:
+    image: docker.io/gitea/act_runner:nightly
+    environment:
+      CONFIG_FILE: /config.yaml
+      GITEA_INSTANCE_URL: "${INSTANCE_URL}"
+      GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
+      GITEA_RUNNER_NAME: "${RUNNER_NAME}"
+      GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
+    volumes:
+      - ./config.yaml:/config.yaml
+      - ./data:/data
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+When using docker, there is no requirement to enter the container and manually run `./act_runner daemon` command as shown below. Once the container has been started successfully, it will show up as an active runner in your Gitea instance.
+
+---
+
+To enable ephemeral runners, set the environment variable `GITEA_RUNNER_EPHEMERAL=1` in the runner image. This setup doesn't use a `/data` volume because the credentials are single-use and not intended to be reused. You can find more details about this mode under [Ephemeral runners](#ephemeral-runners).
+
+```yml
+version: "3.8"
+services:
+  runner:
+    image: docker.io/gitea/act_runner:nightly
+    environment:
+      CONFIG_FILE: /config.yaml
+      GITEA_INSTANCE_URL: "${INSTANCE_URL}"
+      GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
+      GITEA_RUNNER_NAME: "${RUNNER_NAME}"
+      GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
+      GITEA_RUNNER_EPHEMERAL: "1"
+    volumes:
+      - ./config.yaml:/config.yaml
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+Mounting the host's Docker socket using `/var/run/docker.sock:/var/run/docker.sock` introduces a potential security vulnerability. If a job can access this socket, the reusable `GITEA_RUNNER_REGISTRATION_TOKEN` could be exposed through Docker inspect data.
+
+### More start examples
+A couple more usage examples can be found in the [act_runner](https://gitea.com/gitea/act_runner/src/branch/main/examples) repository.
+
+## Advanced Configurations
+
+### Configuring cache when starting a runner using the docker image
+
+If you do not intend to use `actions/cache` in your workflow, you can ignore this section.
+
+If you use `actions/cache` without any additional configuration, it will return the following error:
+> Failed to restore: getCacheEntry failed: connect ETIMEDOUT IP:PORT
+
+The error occurs because the runner container and job container are on different networks, so the job container cannot access the runner container.
+
+Therefore, it is essential to configure the cache action to ensure its proper functioning. Follow these steps:
+
+- 1. Obtain the LAN IP address of the host machine where the runner container is running.
+- 2. Find an available port number on the host machine where the runner container is running.
+- 3. Configure the following settings in the configuration file:
+
+```yaml
+cache:
+  enabled: true
+  dir: ""
+  # Use the LAN IP obtained in step 1
+  host: "192.168.8.17"
+  # Use the port number obtained in step 2
+  port: 8088
+```
+
+- 4. When starting the container, map the cache port to the host machine:
+
+```bash
+docker run \
+  --name gitea-docker-runner \
+  -p 8088:8088 \
+  -d docker.io/gitea/act_runner:nightly
+```
+
+### Labels
+
+The labels of a runner are used to determine which jobs the runner can run, and how to run them.
+
+The default labels are `ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`.
+It is a comma-separated list, and each item is a label.
+
+Let's take `ubuntu-22.04:docker://node:16-bullseye` as an example.
+It means that the runner can run jobs with `runs-on: ubuntu-22.04`, and the job will be run in a docker container with the image `node:16-bullseye`.
+
+If the default image is insufficient for your needs, and you have enough disk space to use a better and bigger one, you can change it to `ubuntu-22.04:docker://<the image you like>`.
+You can find more useful images on [act images](https://github.com/nektos/act/blob/master/IMAGES.md).
+
+If you want to run jobs on the host directly, you can change it to `ubuntu-22.04:host` or just `ubuntu-22.04`; `:host` is optional.
+However, we suggest you use a special name like `linux_amd64:host` or `windows:host` to avoid misusing it.
+
+Starting with Gitea 1.21, you can change labels by modifying `runners.labels` in the runner configuration file (if you don't have a configuration file, please refer to [configuration tutorials](#configuration)).
+The runner will use these new labels as soon as you restart it, i.e., by calling `./act_runner daemon --config config.yaml`.

docs/usage/actions/comparison.md

@@ -33,13 +33,6 @@ See [Using concurrency](https://docs.github.com/en/actions/using-jobs/using-conc
 
 It's ignored by Gitea Actions now.
 
-### `run-name`
-
-The name for workflow runs generated from the workflow.
-See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#run-name).
-
-It's ignored by Gitea Actions now.
-
 ### `permissions` and `jobs.<job_id>.permissions`
 
 See [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions).
@@ -107,6 +100,14 @@ Services steps don't have their own section in the job log user interface.
 
 ## Different behavior
 
+### Concurrency
+
+As of v1.21.0, gitea behaves as if `concurrency.cancel-in-progress` is set to `true`.
+
+This means that newly-triggered workflows will pre-empt runs already in progress for previous triggers.
+
+See [PR #25716](https://github.com/go-gitea/gitea/pull/25716) for additional details.
+
 ### Downloading actions
 
 Previously (Pre 1.21.0), `[actions].DEFAULT_ACTIONS_URL` defaulted to `https://gitea.com`.

docs/usage/actions/faq.md

@@ -168,3 +168,8 @@ For events supported only by GitHub, see GitHub's [documentation](https://docs.g
 
 > For `pull_request` events, in [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request), the `ref` is `refs/pull/:prNumber/merge`, which is a reference to the merge commit preview. However, Gitea has no such reference.
 > Therefore, the `ref` in Gitea Actions is `refs/pull/:prNumber/head`, which points to the head of pull request rather than the preview of the merge commit.
+
+## How to share actions and reusable workflows from private repositories?
+
+Go to the repository's **Settings** > **Actions** > **General** page and add collaborative owners.
+The private repositories of collaborative owners are allowed to access the actions and workflows in the current repository.

docs/usage/actions/quickstart.md

@@ -76,7 +76,7 @@ And you can see the new runner in the management page:
 
 ![view runner](/images/usage/actions/view-runner.png)
 
-You can find more information by visiting [Act runner](usage/actions/act-runner.md).
+You can find more information by visiting [Act runner](act-runner.mdxc).
 
 ### Use Actions
 

docs/usage/issues-prs/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Issues & Pull Requests",
+  "position": 20,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/issues-prs",
+    "description": "Issues and Pull Requests workflow, templates, and collaboration features"
+  }
+}

docs/usage/issues-prs/agit.md

@@ -4,9 +4,11 @@ slug: "agit"
 sidebar_position: 12
 aliases:
   - /en-us/agit-setup
+  - /agit-setup
+  - /agit
 ---
 
-# AGit Setup
+# AGit
 
 In Gitea `1.13`, support for [AGit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/) was added. AGit enables users to create pull requests directly, even without write permissions of the repository, eliminating the need to fork it. This helps reduce the number of duplicated repositories and minimizes unnecessary disk usage.
 
@@ -27,19 +29,21 @@ git push origin HEAD:refs/for/main
 The command has the following structure:
 
 - `HEAD`: The target branch
-- `refs/<for|draft|for-review>/<branch>`: The target PR type
+- `origin`: The target repository (not a fork!)
+- `HEAD`: The local branch containing the changes you are proposing
+- `refs/<for|draft|for-review>/<branch>`: The target PR type and configuration
   - `for`: Create a normal PR with `<branch>` as the target branch
-  - `draft`/ `for-review`: Currently ignored silently
-- `<branch>/<session>`: The target branch to open the PR
+  - `draft`/`for-review`: Currently ignored silently
+  - `<branch>/`: The branch you want your changes to be merged into
 - `-o <topic|title|description>`: Options for the PR
-  - `title`: The PR title
-  - `topic`: The branch name the PR should be opened for
-  - `description`: The PR description
+  - `topic`: The topic of this change. It will become the name of the branch holding the changes waiting for review.  This is REQUIRED to trigger a pull request.
+  - `title`: The PR title (optional but recommended), only used for topics not already having an associated PR.
+  - `description`: The PR description (optional but recommended), only used for topics not already having an associated PR.
   - `force-push=true`: Specifies whether to force-update the target branch.
-    - Note: omitting the value and using just `-o force-push` will not work.
+    - Note: omitting the value and using just `-o force-push` will also work.
 
 Here's another advanced example for creating a new PR targeting `main` with `topic`, `title`, and `description`:
 
 ```shell
-git push origin HEAD:refs/for/main -o topic="Topic of my PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
+git push origin HEAD:refs/for/main -o topic="topic_of_my_PR" -o title="Title of the PR" -o description="# The PR Description\nThis can be **any** markdown content.\n- [x] Ok"
 ```

docs/usage/issues-prs/labels.md

@@ -1,12 +1,9 @@
 ---
 date: "2023-03-04T19:00:00+00:00"
-
 slug: "labels"
 sidebar_position: 13
-
 aliases:
   - /en-us/labels
-
 ---
 
 # Labels
@@ -21,7 +18,7 @@ For organizations, you can define organization-wide labels that are shared with
 
 Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
 
-When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../administration/customizing-gitea/#labels). Its contained labels will all be created as well while creating the repository.
+When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
 
 ## Scoped Labels
 

docs/usage/issues-prs/linked-references.md

@@ -85,7 +85,7 @@ Sometimes a commit or pull request may fix or bring back a problem documented
 in a particular issue. Gitea supports closing and reopening the referenced
 issues by preceding the reference with a particular _keyword_. Common keywords
 include "closes", "fixes", "reopens", etc. This list can be
-[customized](../administration/config-cheat-sheet.md) by the
+[customized](../../administration/config-cheat-sheet.md) by the
 site administrator.
 
 Example:

docs/usage/issues-prs/pull-request.md

@@ -57,4 +57,4 @@ The first value of the list will be used in helpers.
 
 ## Pull Request Templates
 
-You can find more information about pull request templates at the page [Issue and Pull Request templates](usage/issue-pull-request-templates.md).
+You can find more information about pull request templates at the page [Issue and Pull Request templates](issue-pull-request-templates.md).

docs/usage/labels.md

@@ -1,33 +0,0 @@
----
-date: "2023-03-04T19:00:00+00:00"
-slug: "labels"
-sidebar_position: 13
-aliases:
-  - /en-us/labels
----
-
-# Labels
-
-You can use labels to classify issues and pull requests and to improve your overview over them.
-
-## Creating Labels
-
-For repositories, labels can be created by going to `Issues` and clicking on `Labels`.
-
-For organizations, you can define organization-wide labels that are shared with all organization repositories, including both already-existing repositories as well as newly created ones. Organization-wide labels can be created in the organization `Settings`.
-
-Labels have a mandatory name, a mandatory color, an optional description, and must either be exclusive or not (see `Scoped Labels` below).
-
-When you create a repository, you can ensure certain labels exist by using the `Issue Labels` option. This option lists a number of available label sets that are [configured globally on your instance](../administration/customizing-gitea.md#labels). Its contained labels will all be created as well while creating the repository.
-
-## Scoped Labels
-
-Scoped labels are used to ensure at most a single label with the same scope is assigned to an issue or pull request. For example, if labels `kind/bug` and `kind/enhancement` have the Exclusive option set, an issue can only be classified as a bug or an enhancement.
-
-A scoped label must contain `/` in its name (not at either end of the name). The scope of a label is determined based on the **last** `/`, so for example the scope of label `scope/subscope/item` is `scope/subscope`.
-
-## Filtering by Label
-
-Issue and pull request lists can be filtered by label. Selecting multiple labels shows issues and pull requests that have all selected labels assigned.
-
-By holding alt to click the label, issues and pull requests with the chosen label are excluded from the list.

docs/usage/packages/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Packages",
+  "position": 40,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/packages",
+    "description": "Managing packages and package registries"
+  }
+}

docs/usage/packages/arch.md

@@ -36,23 +36,24 @@ pacman-key --lsign-key {key id}
 
 Now add the registry configuration to `/etc/pacman.conf`.
 ```conf
-[{owner}.gitea.example.com]
+[{repository}]
 SigLevel = Required
-Server = https://gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
+Server = https://gitea.example.com/api/packages/{owner}/arch/$repo/$arch
 ```
 
 | Placeholder    | Description |
 | -------------- | ----------- |
 | `owner`        | The owner of the packages. |
 | `repository`   | The repository to use. |
-| `architecture` | The architecture to use. |
 
 Consult the owners package overview to see what `repository` and `architecture` is available.
 
 If the registry is private, provide credentials in the url. You can use a password or a [personal access token](development/api-usage.md#authentication):
 
 ```
-Server = https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/arch/{repository}/{architecture}
+[{repository}]
+SigLevel = Required
+Server = https://{username}:{your_password_or_token}@gitea.example.com/api/packages/{owner}/arch/$repo/$arch
 ```
 
 ## Publish a package

docs/usage/packages/npm.md

@@ -29,7 +29,7 @@ npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{t
 | ------------ | ----------- |
 | `scope`      | The scope of the packages. |
 | `owner`      | The owner of the package. |
-| `token`      | Your [personal access token](development/api-usage.md#authentication). |
+| `token`      | Your [personal access token](development/api-usage.md#authentication). With `package` permissions. |
 
 For example:
 

docs/usage/packages/overview.md

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

docs/usage/projects/_category_.json

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

docs/usage/projects/project-workflows.md

@@ -0,0 +1,92 @@
+---
+date: "2025-11-25T18:58:22Z"
+slug: "project-workflows"
+sidebar_position: 1
+description: "Automate tasks on repository projects by reacting to events with filters and actions."
+---
+
+# Project Workflows
+
+Project workflows let you automate what happens on a repository project board whenever an issue or pull request triggers a supported event. The feature runs entirely inside Gitea, so no external runners or webhooks are required.
+
+Users who can edit the project (repository owners, maintainers, and project managers) may create, edit, clone, enable, or disable workflows from the project UI.
+
+## Open the workflow editor
+
+1. Navigate to the repository → **Projects** and open the board you want to automate.
+2. Select the **Workflows** tab that appears next to the project columns.
+3. Click left sidbar to edit an event definition.
+4. Choose the event, add any filters, chain the actions you need, and save.
+
+Every workflow lives inside the project it belongs to. If you need similar logic for another project, recreate or clone the workflow in that project.
+
+## Concepts
+
+Every workflow is composed of `event`, `filters`, and `actions`.
+
+- **Event** - An Event defines when a workflow should be triggered. It represents specific activities such as an issue being opened, a pull request being merged, or a project column being changed.
+- **Filter** - A Filter refines when an event should take effect. It allows users to specify conditions like issue type, labels, or project columns to ensure actions only run in targeted scenarios.
+- **Action** - An Action defines what happens when the event and filters match. It performs operations such as adding labels, moving issues between columns, or changing the issue or pull request state.
+
+## Supported events
+
+| Event | Fires when |
+| --- | --- |
+| Issues/PRs opened | A new issue or pull request is created. |
+| Issues/PRs closed | The issue or pull request is closed. |
+| Issues/PRs reopened | A previously closed issue or pull request is reopened. |
+| Added to project | An issue or pull request is added to the project. |
+| Removed from project | An issue or pull request is removed from the project. |
+| Column changed | A card moves from one column to another. |
+| Code changes requested | A reviewer requests changes on a pull request connected to the project. |
+| Code review approved | A reviewer approves the pull request. |
+| Pull request merged | The pull request is merged. |
+
+Each event can have multiple workflows so you can handle the same trigger differently for separate sets of cards.
+
+## Filters
+
+Filters refine when an event should run. If none are configured, the workflow runs on every occurrence of the event.
+
+- **Apply to** - Specify the target type: `issues only`, `pull requests only`, or `issues and pull requests`.
+- **Labels** - Trigger the event only if the issue or pull request contains one or more specified labels.
+- **Move from column** - Filter events based on the original project column.
+- **Move to column** - Filter events based on the destination project column.
+
+You can combine filters to require multiple conditions (for example, PRs with the `needs-review` label moving into the "Review" column).
+
+## Actions
+
+Workflows execute their actions in the order you add them. Available actions are:
+
+- **Add labels** - Automatically add one or more labels to the issue or pull request.
+- **Remove labels** - Remove one or more specified labels.
+- **Move to column** - Move the issue or pull request to a designated project column.
+- **Issue state** - Change the state by closing or reopening the issue or pull request.
+
+Combine actions to build more complex automations (for example, move the card and apply labels in a single workflow).
+
+## Managing workflows
+
+### Enable or disable
+
+Each workflow has its own toggle. Disable a workflow to pause it temporarily without losing its configuration. Disabled workflows are ignored even if the event fires.
+
+### Clone an event workflow
+
+Use **Clone** to duplicate the current workflow (event, filters, and actions). This is useful when you need several variations of the same trigger—adjust the copied filters/actions and save under a new name.
+
+## Example: triage incoming bug reports
+
+The following workflow keeps bug reports organized automatically:
+
+1. **Event:** Issues/PRs opened.
+2. **Filters:** Apply to `issues only`; Labels include `bug`.
+3. **Actions:**
+   - Add labels → `needs-triage`.
+   - Move to column → "Needs Triage".
+   - Issue state → leave open (no change) but could optionally reopen to ensure visibility.
+
+With this configuration every new bug issue when added to this project immediately lands in the right column with the correct label, so maintainers always know what still needs triage.
+
+Start small, test the workflow on a single project, and expand the automation set as your team discovers repetitive tasks you can offload to workflows.

docs/usage/repository/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Repository",
+  "position": 10,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/repository",
+    "description": "Repository management, Git operations, and content features"
+  }
+}

docs/usage/repository/blame.md

@@ -1,12 +1,10 @@
 ---
 date: "2023-08-14T00:00:00+00:00"
-
 slug: "blame"
 sidebar_position: 13
-
 aliases:
   - /en-us/blame
-
+  - /blame
 ---
 
 # Blame File View

docs/usage/repository/clone-filter.md

@@ -1,11 +1,10 @@
 ---
 date: "2021-02-02"
-
 slug: "clone-filters"
 sidebar_position: 25
 aliases:
   - /en-us/clone-filters
-
+  - /clone-filters
 ---
 
 # Clone filters (partial clone)

docs/usage/repository/code-owners.md

@@ -1,12 +1,10 @@
 ---
 date: "2023-05-24T16:00:00+00:00"
-
 slug: "code-owners"
 sidebar_position: 30
-
 aliases:
   - /en-us/code-owners
-
+  - /code-owners
 ---
 
 # Code Owners

docs/usage/repository/incoming-email.md

@@ -1,11 +1,10 @@
 ---
 date: "2022-12-01T00:00:00+00:00"
-
 slug: "incoming-email"
-sidebar_position: 13
+sidebar_position: 130
 aliases:
   - /en-us/incoming-email
-
+  - /incoming-email
 ---
 
 # Incoming Email

docs/usage/repository/markdown.md

@@ -0,0 +1,128 @@
+---
+date: "2025-04-05T00:00:00+08:00"
+slug: "markdown"
+aliases:
+  - /markdown
+sidebar_position: 4
+---
+
+# Markdown
+
+Gitea uses MarkDown structured text in many places, you can recognise it by the `.md` file extension.
+Markdown is plain text format for writing structured documents, allowing one to write
+"plain" text files that nonetheless have _"fancy"_ **formatting**, while still keeping the plain-text version readable.
+
+Unfortunately, due to historical implementation differences, many subtle dialects exist.
+To avoid adding to the confusion, Gitea tries to follow "[GitHub Flavoured Markdown (GFM)](https://help.github.com/articles/github-flavored-markdown/)" as close as possible.
+"GFM" is an extension on top of the rigorously-specified [CommonMark](https://commonmark.org/) standard.
+CommonMark flavours are used by most major web platforms (e.g. Reddit, Stack Overflow, Discourse)
+and git forges (GitHub, GitLab and our very own Gitea), thus you shouldn't run into any surprises with Gitea.
+
+For a quick introduction to the syntax and features of GitHub Flavoured Markdown, see the GitHub documentation:
+- [Basic formatting](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
+- [Advanced formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting)
+
+For a deeper history about CommonMark, its spec, and its reason for existence, see [CommonMark.org](https://commonmark.org/).
+
+## Rendering options
+
+Some Gitea's markdown rendering behaviors can be fine-tuned by global config options, see the `[markdown]` config section in the `app.example.ini`
+
+
+## Link path resolving
+
+When rendering links for `<a href>`, `<img src>` and `<video src>`, Gitea resolves the link paths in the rendering context.
+
+- If the link is an absolute path with scheme, the link is kept as-is.
+- If the link is an URL path, it is resolved with the base path of current rendering context.
+  - In a comment-like context (issues, pull-requests, commit message), the base path is current repository's home link: `/owner-name/repo-name`.
+  - In a repository file context (markdown files in the repository), the base path is current git ref path.
+
+### Special link tokens
+
+To make users easier to resolve a link to the Gitea instance's root path, Gitea has a special `/:root` path syntax.
+This will always resolve to Gitea's ROOT_URL.
+
+Gitea also supports GitHub's `?raw=1` query parameter.
+A request to `/owner-name/repo-name/src/branch/main/file?raw=1` will be redirected to
+`/owner-name/repo-name/raw/branch/main/file`. This makes it possible to target raw contents from relative links
+(normally, the `src/` section of the path is provided automatically by Gitea and cannot be overriden).
+
+### Link handling examples
+
+For example, when rendering a markdown file in `/owner-name/repo-name/src/branch/main/dir`:
+  1) Absolute with scheme: Link `https://example.org` will be rendered as-is.
+  2) Relative from current file: Link `sub/file`is resolved to `/owner-name/repo-name/src/branch/main/dir/sub/file`
+  3) Relative from repo root: Link `/sub/file` (note leading slash) is resolved to `/owner-name/repo-name/src/branch/main/sub/file`
+  4) Raw media: If the link is used as `src` of an image or video, then it is resolved to `/owner-name/repo-name/raw/...`
+  5) Raw relative: `sub/file?raw=1` will resolve to `/owner-name/repo-name/src/branch/main/dir/sub/file?raw=1`,
+    which will redirect to `/owner-name/repo-name/raw/branch/main/dir/sub/file`.
+  6) explicit root: Link `/:root/any-path` is always resolved to `$ROOT_URL/any-path` without any further processing.
+
+
+## Issue and pull-request reference
+
+Using issue/pull-request numbers in a list:
+
+```
+* #123
+* #456
+```
+
+It will be rendered with issue titles to:
+
+```
+* the issue title (#123)
+* the other issue title (#456)
+```
+
+## Math expressions
+
+Gitea supports GitHub-like math expression formatting.
+
+### Inline expression
+
+  - ``` $\alpha$ ```: quoted by single-dollar `$`
+  - ``` $$\alpha$$ ```: quoted by double-dollar `$$`
+  - ``` $`\alpha`$ ```: quoted by dollar with backquotes, the backquotes could repeat like normal code blocks.
+
+### Block expression
+
+Using `$$`:
+
+````
+$$
+\alpha
+$$
+````
+
+Using code-block with language:
+
+````
+```math
+\alpha
+```
+````
+
+## Frontmatter
+
+Gitea supports frontmatter and Table of Contents (TOC) rendering. By default, frontmatter rendering is enabled, and TOC rendering is disabled.
+
+### Enabling TOC rendering
+
+To enable TOC rendering for a markdown file, add `include_toc: true` to its frontmatter section.
+
+### Disabling frontmatter
+
+To disable frontmatter rendering for a markdown file, add `gitea: none` to its frontmatter section.
+
+### Example
+
+```yaml
+---
+include_toc: true
+gitea: none
+---
+```
+
+Then, when you preview this markdown file in Gitea, the frontmatter section will not be rendered, and a Table of Contents will be generated at the top of the content.

docs/usage/repository/migration.md

@@ -0,0 +1,55 @@
+---
+date: "2024-09-11T09:30:00+08:00"
+slug: "migration"
+sidebar_position: 40
+aliases:
+  - /migration
+---
+
+# Migration
+
+You can migrate repositories from other Git services to your Gitea instance.
+
+## How to migrate from Gogs/GitHub/GitLab to Gitea
+
+To migrate from Gogs to Gitea:
+
+- [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
+
+To migrate from GitHub to Gitea, you can use Gitea's built-in migration form.
+
+In order to migrate items such as issues, pull requests, etc. you will need to input at least your username.
+
+[Example (requires login)](https://demo.gitea.com/repo/migrate)
+
+To migrate from GitLab to Gitea, you can use this non-affiliated tool:
+
+https://github.com/loganinak/MigrateGitlabToGogs
+
+## How to migrate from AWS CodeCommit to Gitea
+
+- To use the AWS CodeCommit API, Gitea requires an access key ID and a secret access key. For security reasons, we recommend creating a new user with the minimum necessary permissions and generating an access key ID and secret access key for the migration. The minimum permissions required for this user are as follows:
+  ```
+  {
+    "Version": "2012-10-17",
+    "Statement": [
+      {
+        "Effect": "Allow",
+        "Action": [
+          "codecommit:GetRepository",
+          "codecommit:GitPull",
+          "codecommit:ListPullRequests",
+          "codecommit:GetPullRequest",
+          "codecommit:GetCommentsForPullRequest"
+        ],
+        "Resource": [
+          "arn:aws:codecommit:<region>:<account>:<Repo-to-Migrate>
+      }
+    ]
+  }
+  ```
+  - If you do not need to migrate pull requests, you can remove the `ListPullRequests`, `GetPullRequest`, and `GetCommentsForPullRequest` actions.
+
+  - For instructions on how to create an IAM user and assign permissions, you can refer to this [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html).
+
+- To clone this repository, Gitea requires HTTPS Git credentials. You can create HTTPS Git credentials according to this [AWS documentation](https://docs.aws.amazon.com/codecommit/latest/userguide/setting-up-gc.html).

docs/usage/repository/profile-readme.md

@@ -1,7 +1,9 @@
 ---
 date: "2023-03-02T21:00:00+05:00"
 slug: "profile-readme"
-sidebar_position: 12
+sidebar_position: 42
+aliases:
+  - /profile-readme
 ---
 
 # Profile READMEs

docs/usage/repository/push.md

@@ -5,6 +5,7 @@ sidebar_position: 15
 aliases:
   - /en-us/push-to-create
   - /en-us/push-options
+  - /push
 ---
 
 # Push
@@ -44,7 +45,7 @@ Push to create is a feature that allows you to push to a repository that does no
 
 ### Enabling Push To Create
 
-In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet](../administration/config-cheat-sheet.md#repository-repository).
+In the `app.ini` file, set `ENABLE_PUSH_CREATE_USER` to `true` and `ENABLE_PUSH_CREATE_ORG` to `true` if you want to allow users to create repositories in their own user account and in organizations they are a member of respectively. Restart Gitea for the changes to take effect. You can read more about these two options in the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#repository-repository).
 
 ### Using Push To Create
 

docs/usage/repository/repo-mirror.md

@@ -1,14 +1,13 @@
 ---
 date: "2021-05-13T00:00:00-00:00"
-
 slug: "repo-mirror"
 sidebar_position: 45
-
 aliases:
   - /en-us/repo-mirror
+  - /repo-mirror
 ---
 
-# Repository Mirror
+# Mirror Repository
 
 Repository mirroring allows for the mirroring of repositories to and from external sources. You can use it to mirror branches, tags, and commits between repositories.
 
@@ -55,7 +54,7 @@ The repository now gets mirrored periodically to the remote repository. You can
 
 To set up a mirror from Gitea to GitHub, you need to follow these steps:
 
-1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the *public_repo* box checked.
+1. Create a [GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) with the *public_repo* box checked. Also check the **workflow** checkbox in case your repo uses GitHub Actions for continuous integration.
 2. Create a repository with that name on GitHub. Unlike Gitea, GitHub does not support creating repositories by pushing to the remote. You can also use an existing remote repo if it has the same commit history as your Gitea repo.
 3. In the settings of your Gitea repo, fill in the **Git Remote Repository URL**: `https://github.com/<your_github_group>/<your_github_project>.git`.
 4. Fill in the **Authorization** fields with your GitHub username and the personal access token as **Password**.
@@ -88,10 +87,10 @@ The repository pushes shortly thereafter. To force a push, select the **Synchron
 
 ### Mirror an existing ssh repository
 
-Currently gitea supports no ssh push mirrors. You can work around this by adding a `post-receive` hook to your gitea repository that pushes manually.
+Currently Gitea supports no ssh push mirrors. You can work around this by adding a `post-receive` hook to your Gitea repository that pushes manually.
 
-1. Make sure the user running gitea has access to the git repo you are trying to mirror to from shell.
-2. On the Webinterface at the repository settings > git hooks add a post-receive hook for the mirror. I.e.
+1. Make sure the user running Gitea has access to the git repo you are trying to mirror to from shell.
+2. On the web interface at the repository settings > git hooks add a post-receive hook for the mirror. I.e.
 
 ```
 #!/usr/bin/env bash

docs/usage/repository/template-repositories.md

@@ -1,27 +1,30 @@
 ---
 date: "2019-11-28:00:00+02:00"
-
 slug: "template-repositories"
-sidebar_position: 14
-
+sidebar_position: 44
 aliases:
   - /en-us/template-repositories
+  - /template-repositories
 ---
 
-# Template Repositories
+# Template Repository
 
-Gitea `1.11.0` and above includes template repositories, and one feature implemented with them is auto-expansion of specific variables within your template files.
+Since Gitea `1.11`, you can create template repositories.
+When creating a repo based on a template, you can copy most of its content, and even auto-inject variables into it.
 
-To tell Gitea which files to expand, you must include a `template` file inside the `.gitea` directory of the template repository.
+By default, variables will not be expanded in any file.
+Only files contained in a pattern inside the `.gitea/template` file will be checked for if they contain variables.
+When creating the template, all files are included except for this `.gitea/template` file.
 
-Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax. It closely resembles a traditional `.gitignore`, however there may be slight differences.
+Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax.
+It closely resembles a traditional `.gitignore`, however there may be slight differences.
 
 ## Example `.gitea/template` file
 
 All paths are relative to the base of the repository
 
 ```gitignore
-# All .go files, anywhere in the repository
+# Expand all .go files, anywhere in the repository
 **.go
 
 # All text files in the text directory
@@ -34,20 +37,23 @@ a/b/c/d.json
 **.[bB][aA][tT]
 ```
 
-:::note
-The `template` file will be removed from the `.gitea` directory when a repository is generated from the template.
-:::
-
 ## Variable Expansion
 
-In any file matched by the above globs, certain variables will be expanded.
+In any file matched by the above globs, the variables below will be expanded.
 
 Matching filenames and paths can also be expanded, and are conservatively sanitized to support cross-platform filesystems.
 
-All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, use a double `$$`, such as `$$VAR` or `$${VAR}`
+You can use variables by prefixing them with `$` or surrounding them with `${}`, so both `$VAR` and `${VAR}` insert the value of `VAR` at this location.
+To escape an expansion, use `$$`, such as `$$VAR` or `$${VAR}`.
+
+These are the variables Gitea currently recognizes:
 
 | Variable             | Expands To                                          | Transformable |
 | -------------------- | --------------------------------------------------- | ------------- |
+| YEAR                 | The year of generating the repository (i.e. `2024`) | ✘             |
+| MONTH                | The month of generating the repository (i.e. `03`)  | ✘             |
+| MONTH_ENGLISH        | The month but in English (i.e. `March`)             | ✓             |
+| DAY                  | The day of generating the repository (i.e. `02`)    | ✘             |
 | REPO_NAME            | The name of the generated repository                | ✓             |
 | TEMPLATE_NAME        | The name of the template repository                 | ✓             |
 | REPO_DESCRIPTION     | The description of the generated repository         | ✘             |
@@ -63,11 +69,12 @@ All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, us
 
 ## Transformers :robot:
 
-Gitea `1.12.0` adds a few transformers to some of the applicable variables above.
+Since Gitea `1.12.0`, variables marked as transformable in the table above also have alternative versions where the given transformer has been applied.
 
-For example, to get `REPO_NAME` in `PASCAL`-case, your template would use `${REPO_NAME_PASCAL}`
+Transformed variables can be called by appending the transformer name to the variable name.
+For example, to get `REPO_NAME` in `PASCAL`-case, you should use the variable `${REPO_NAME_PASCAL}`.
 
-Feeding `go-sdk` to the available transformers yields...
+The following transformers are available (assuming `go-sdk` is the input):
 
 | Transformer | Effect |
 | ----------- | ------ |

docs/usage/repository/webhooks.md

@@ -1,12 +1,10 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
-
 slug: "webhooks"
 sidebar_position: 30
-
 aliases:
   - /en-us/webhooks
-
+  - /webhooks
 ---
 
 # Webhooks

docs/usage/user-setting/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "User Setting",
+  "position": 200,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/user-setting",
+    "description": "Configuring user preferences and settings"
+  }
+}

docs/usage/user-setting/multi-factor-authentication.md

@@ -1,9 +1,9 @@
 ---
 date: "2023-08-22T14:21:00+08:00"
-
 slug: "multi-factor-authentication"
 weight: 15
-
+aliases:
+  - /multi-factor-authentication
 ---
 
 # Multi-factor Authentication (MFA)

docusaurus.config.js

@@ -29,7 +29,11 @@ const apiConfig = [
           },
           {
             route: "/api/",
-            spec: "static/swagger-24.json",
+            spec: "static/swagger-25.json",
+          },
+          {
+            route: "/api/1.25/",
+            spec: "static/swagger-25.json",
           },
           {
             route: "/api/1.24/",
@@ -43,18 +47,6 @@ const apiConfig = [
             route: "/api/1.22/",
             spec: "static/swagger-22.json",
           },
-          {
-            route: "/api/1.21/",
-            spec: "static/swagger-21.json",
-          },
-          {
-            route: "/api/1.20/",
-            spec: "static/swagger-20.json",
-          },
-          {
-            route: "/api/1.19/",
-            spec: "static/swagger-19.json",
-          },
         ]
       : [],
     // Theme Options for modifying how redoc renders them
@@ -72,17 +64,27 @@ const pageConfig = renderApiSSR
   : {};
 
 const globalVariables = {
-  current: {
-    goVersion: "1.24",
-    minGoVersion: "1.24",
+  "current": {
+    goVersion: "1.25",
+    minGoVersion: "1.25",
     minNodeVersion: "22",
     version: "main-nightly",
     sourceVersion: "main",
     sourceBranch: "main",
     dockerVersion: "nightly",
-    displayVersion: "1.25-dev",
+    displayVersion: "1.26-dev",
   },
-  1.24: {
+  "1.25": {
+    goVersion: "1.25",
+    minGoVersion: "1.25",
+    minNodeVersion: "22",
+    version: "1.25.4",
+    sourceVersion: "v1.25.0",
+    sourceBranch: "release/v1.25",
+    dockerVersion: "1.25.4",
+    displayVersion: "1.25.4",
+  },
+  "1.24": {
     goVersion: "1.24",
     minGoVersion: "1.24",
     minNodeVersion: "22",
@@ -92,7 +94,7 @@ const globalVariables = {
     dockerVersion: "1.24.7",
     displayVersion: "1.24.7",
   },
-  1.23: {
+  "1.23": {
     goVersion: "1.23",
     minGoVersion: "1.22",
     minNodeVersion: "18",
@@ -102,7 +104,7 @@ const globalVariables = {
     dockerVersion: "1.23.8",
     displayVersion: "1.23.8",
   },
-  1.22: {
+  "1.22": {
     goVersion: "1.22",
     minGoVersion: "1.22",
     minNodeVersion: "18",
@@ -112,61 +114,25 @@ const globalVariables = {
     dockerVersion: "1.22.6",
     displayVersion: "1.22.6",
   },
-  1.21: {
-    goVersion: "1.21",
-    minGoVersion: "1.21",
-    minNodeVersion: "18",
-    version: "1.21.11",
-    sourceVersion: "v1.21.11",
-    sourceBranch: "release/v1.21",
-    dockerVersion: "1.21.11",
-    displayVersion: "1.21.11",
-  },
-  "1.20": {
-    goVersion: "1.20",
-    minGoVersion: "1.20",
-    minNodeVersion: "16",
-    version: "1.20.6",
-    sourceVersion: "v1.20.6",
-    sourceBranch: "release/v1.20",
-    dockerVersion: "1.20.6",
-    displayVersion: "1.20.6",
-  },
-  1.19: {
-    goVersion: "1.20",
-    minGoVersion: "1.19",
-    minNodeVersion: "14",
-    version: "1.19.4",
-    sourceVersion: "v1.19.4",
-    sourceBranch: "release/v1.19",
-    dockerVersion: "1.19.4",
-    displayVersion: "1.19.4",
-  },
 };
 
 const versions = {
-  current: {
+  "current": {
     label: globalVariables["current"].displayVersion, // path is kept as next for dev (so users can always find "nightly" docs)
     banner: "unreleased",
   },
-  1.24: {
+  "1.25": {
+    label: globalVariables["1.25"].displayVersion,
+  },
+  "1.24": {
     label: globalVariables["1.24"].displayVersion,
   },
-  1.23: {
+  "1.23": {
     label: globalVariables["1.23"].displayVersion,
   },
-  1.22: {
+  "1.22": {
     label: globalVariables["1.22"].displayVersion,
   },
-  1.21: {
-    label: globalVariables["1.21"].displayVersion,
-  },
-  "1.20": {
-    label: globalVariables["1.20"].displayVersion,
-  },
-  1.19: {
-    label: globalVariables["1.19"].displayVersion,
-  },
 };
 
 /** @type {import('@docusaurus/types').Config} */
@@ -176,7 +142,6 @@ const config = {
   url: "https://docs.gitea.com",
   baseUrl: "/",
   onBrokenLinks: "warn",
-  onBrokenMarkdownLinks: "warn",
   favicon: "img/favicon.png",
   future: {
     experimental_faster: true,
@@ -194,8 +159,8 @@ const config = {
     [
       "@docusaurus/plugin-content-docs",
       {
-        id: "runner",
-        path: "runner",
+        id: "runner-docs",
+        path: "runner-docs",
         routeBasePath: "runner",
         //sidebarPath: './runner/sidebars.js',
         versions: {
@@ -218,8 +183,8 @@ const config = {
         }) => {
           return `https://gitea.com/gitea/docs/src/branch/main/${
             version === "current"
-              ? "runner"
-              : `runner_versioned_docs/version-${version}`
+              ? "runner-docs"
+              : `runner-docs_versioned_docs/version-${version}`
           }/${docPath}`;
         },
         async sidebarItemsGenerator({ defaultSidebarItemsGenerator, ...args }) {
@@ -284,7 +249,7 @@ const config = {
             }/${docPath}`;
           },
           versions: versions,
-          lastVersion: "1.24",
+          lastVersion: "1.25",
           async sidebarItemsGenerator({
             defaultSidebarItemsGenerator,
             ...args
@@ -312,6 +277,9 @@ const config = {
     apiConfig,
   ],
   markdown: {
+    hooks: {
+      onBrokenMarkdownLinks: "warn",
+    },
     preprocessor: ({ filePath, fileContent }) => {
       var key = "";
       var found = false;
@@ -391,10 +359,10 @@ const config = {
             label: "Docs",
           },
           {
-            to: "/api/1.24/",
+            to: "/api/1.25/",
             label: "API",
             position: "left",
-            activeBaseRegex: "api/(1.19|1.20|1.21|1.22|1.23|1.24|next)/",
+            activeBaseRegex: "api/(1.22|1.23|1.24|1.25|next)/",
           },
           {
             to: "/runner/0.2.11/",
@@ -427,13 +395,11 @@ const config = {
             label: "API Version",
             position: "right",
             items: [
-              { to: "/api/next/", label: "1.25-dev" },
+              { to: "/api/next/", label: "1.26-dev" },
+              { to: "/api/1.25/", label: "1.25.4" },
               { to: "/api/1.24/", label: "1.24.7" },
               { to: "/api/1.23/", label: "1.23.8" },
               { to: "/api/1.22/", label: "1.22.6" },
-              { to: "/api/1.21/", label: "1.21.11" },
-              { to: "/api/1.20/", label: "1.20.6" },
-              { to: "/api/1.19/", label: "1.19.4" },
             ],
             routerRgx: "/api/",
             classNames: "api-dropdown",

i18n/en-us/docusaurus-plugin-content-docs/version-1.23.json

@@ -0,0 +1,8 @@
+{
+  "sidebar.docs.category.actions": {
+    "message": "Actions"
+  },
+  "sidebar.docs.category.packages": {
+    "message": "Packages"
+  }
+}

i18n/en-us/docusaurus-plugin-content-docs/version-1.24.json

@@ -0,0 +1,8 @@
+{
+  "sidebar.docs.category.actions": {
+    "message": "Actions"
+  },
+  "sidebar.docs.category.packages": {
+    "message": "Packages"
+  }
+}

i18n/en-us/docusaurus-plugin-content-docs/version-1.25.json

@@ -0,0 +1,8 @@
+{
+  "sidebar.docs.category.actions": {
+    "message": "Actions"
+  },
+  "sidebar.docs.category.packages": {
+    "message": "Packages"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/administration.md

@@ -1,12 +0,0 @@
----
-date: "2016-12-01T16:00:00+02:00"
-title: "运维"
-slug: "administration"
-sidebar_position: 30
-
-menu:
-  sidebar:
-    name: "运维"
-    sidebar_position: 20
-    identifier: "administration"
----

i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "运维",
+  "position": 30,
+  "link": {
+    "type": "generated-index",
+    "slug": "/administration",
+    "title": "运维"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/backup-and-restore.md

@@ -23,7 +23,7 @@ Gitea 包括数据库、文件和 Git 仓库，当它被使用时所有这些都
 
 ```
 2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
-2016/12/27 22:32:09 Dumping local repositories.../home/git/gitea-repositories
+2016/12/27 22:32:09 Dumping local repositories.../home/git/repositories
 2016/12/27 22:32:22 Dumping database...
 2016/12/27 22:32:22 Packing dump files...
 2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
@@ -80,7 +80,7 @@ cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/gitea-repositories/
+mv repos/* /var/lib/gitea/repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea
 
 # mysql
@@ -114,7 +114,7 @@ cd gitea-dump-1610949662
 # 恢复 Gitea 数据
 mv data/* /data/gitea
 # 恢复仓库本身
-mv repos/* /data/git/gitea-repositories/
+mv repos/* /data/git/repositories/
 # 调整文件权限
 chown -R git:git /data
 # 重新生成 Git 钩子
@@ -138,7 +138,7 @@ mv data/conf/app.ini /etc/gitea/app.ini
 # 恢复 Gitea 数据
 mv data/* /var/lib/gitea
 # 恢复仓库本身
-mv repos/* /var/lib/gitea/git/gitea-repositories
+mv repos/* /var/lib/gitea/git/repositories
 # 调整文件权限
 chown -R git:git /etc/gitea/app.ini /var/lib/gitea
 # 重新生成 Git 钩子

i18n/zh-cn/docusaurus-plugin-content-docs/current/contributing/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "贡献",
+  "position": 35,
+  "link": {
+    "type": "generated-index",
+    "slug": "/contributing",
+    "title": "贡献"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/development.md

@@ -1,12 +0,0 @@
----
-date: "2016-12-01T16:00:00+02:00"
-title: "开发"
-slug: "development"
-sidebar_position: 40
-
-menu:
-  sidebar:
-    name: "开发"
-    sidebar_position: 40
-    identifier: "development"
----

i18n/zh-cn/docusaurus-plugin-content-docs/current/development/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "开发",
+  "position": 40,
+  "link": {
+    "type": "generated-index",
+    "slug": "/development",
+    "title": "开发"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/help.md

@@ -1,12 +0,0 @@
----
-date: "2017-01-20T15:00:00+08:00"
-title: "帮助"
-slug: "help"
-sidebar_position: 5
-
-menu:
-  sidebar:
-    name: "帮助"
-    sidebar_position: 100
-    identifier: "help"
----

i18n/zh-cn/docusaurus-plugin-content-docs/current/help/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "帮助",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "slug": "/help",
+    "title": "帮助"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/installation.md

@@ -1,12 +0,0 @@
----
-date: "2016-12-01T16:00:00+02:00"
-title: "安装"
-slug: "installation"
-sidebar_position: 10
-
-menu:
-  sidebar:
-    name: "安装"
-    sidebar_position: 10
-    identifier: "installation"
----

i18n/zh-cn/docusaurus-plugin-content-docs/current/installation/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "安装",
+  "position": 10,
+  "link": {
+    "type": "generated-index",
+    "slug": "/installation",
+    "title": "安装"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage.md

@@ -1,12 +0,0 @@
----
-date: "2016-12-27T16:00:00+02:00"
-title: "使用指南"
-slug: "usage"
-sidebar_position: 35
-
-menu:
-  sidebar:
-    name: "使用指南"
-    sidebar_position: 30
-    identifier: "usage"
----

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "使用指南",
+  "position": 35,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage",
+    "title": "使用指南"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/access-control/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "权限控制",
+  "position": 100,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/access-control",
+    "description": "权限，安全，和访问控制功能"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "工作流",
+  "position": 30,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/actions",
+    "description": "自动化工作流，CI/CD 和操作功能"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/actions/act-runner.md

@@ -236,6 +236,15 @@ docker run \
 
 ### 标签
 
+```mermaid
+flowchart TD
+    A[Workflow: runs-on: ubuntu-22.04] --> B[Act Runner 收到 Job 请求]
+    B --> C[匹配标签: ubuntu-22.04:docker://node:16-bullseye]
+    C --> D[启动 Docker 容器: node:16-bullseye]
+    D --> E[在容器中运行 Job 步骤]
+    E --> F[返回执行结果给 Gitea]
+```
+
 Runner的标签用于确定Runner可以运行哪些Job以及如何运行它们。
 
 默认标签为`ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`。

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/issues-prs/_category.json

@@ -0,0 +1,9 @@
+{
+  "label": "工单 和 合并请求",
+  "position": 20,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/issues-prs",
+    "description": "工单 和 合并请求 工作流，模板，和协作功能"
+  }
+}

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/packages/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "软件包",
+  "position": 40,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/packages",
+    "description": "软件包管理，依赖关系，和分发功能"
+  }
+}

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

@@ -0,0 +1,9 @@
+{
+  "label": "项目",
+  "position": 60,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/projects",
+    "description": "规划、跟踪并自动化仓库项目"
+  }
+}

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

@@ -0,0 +1,90 @@
+---
+date: "2025-11-25T18:58:22Z"
+slug: "project-workflows"
+sidebar_position: 1
+description: "在仓库项目上使用事件、过滤器和动作组合来自动化重复操作。"
+---
+
+# 项目工作流
+
+项目工作流可以在仓库项目看板上根据问题或拉取请求触发的事件自动执行操作。该功能无需外部 Runner 或 Webhook，完全在 Gitea 内部运行。
+
+具备项目编辑权限的成员（仓库所有者、维护者和项目管理员）都可以在项目界面中创建、编辑、克隆、启用或禁用工作流。
+
+## 打开工作流编辑器
+
+1. 进入仓库并打开需要自动化的 **Projects** 看板。
+2. 在列列表旁选择 **Workflows** 选项卡。
+3. 点击事件定义，或选中已有工作流进行编辑。
+4. 选择事件、追加过滤器、按顺序添加需要的动作并保存。
+
+每个工作流都存放在所属的项目下。如果另一个项目需要类似逻辑，请在目标项目中重新创建或克隆工作流。
+
+## 基本概念
+
+- **事件（Event）**：定义何时评估工作流，例如创建问题或卡片在列间移动。
+- **过滤器（Filter）**：可选条件，只有满足条件才会执行动作，例如标签或列的变化。
+- **动作（Action）**：当事件与过滤器匹配时 Gitea 要执行的操作，例如添加标签或移动卡片。
+
+## 支持的事件
+
+| 事件 | 触发时机 |
+| --- | --- |
+| 新建问题/拉取请求 | 创建新的问题或拉取请求。 |
+| 关闭问题/拉取请求 | 该问题或拉取请求被关闭。 |
+| 重新打开问题/拉取请求 | 已关闭的条目被重新打开。 |
+| 加入项目 | 问题或拉取请求被添加到该项目。 |
+| 从项目移除 | 条目被从项目中移出。 |
+| 列发生变化 | 卡片从一个列移动到另一个列。 |
+| 被请求修改 | 与项目关联的拉取请求收到修改请求。 |
+| 审查通过 | 审查者批准了该拉取请求。 |
+| 拉取请求已合并 | 该拉取请求被合并。 |
+
+每个事件都可以配置多个工作流，以便在不同场景下对同一触发器执行不同操作。
+
+## 过滤器
+
+过滤器用于进一步限定事件是否需执行。如果未配置过滤器，事件发生时工作流始终运行。
+
+- **适用对象（Apply to）**：限定仅匹配 `issues only`、`pull requests only` 或同时匹配。
+- **标签（Labels）**：仅当卡片已包含指定标签之一时运行。
+- **来源列（Move from column）**：仅当卡片原本位于所选列之一时运行，常与“列发生变化”事件组合。
+- **目标列（Move to column）**：仅当卡片移动到指定列时运行。
+
+可以组合多个过滤器以同时满足多种条件，例如“带有 `needs-review` 标签的拉取请求移动到 “Review” 列”。
+
+## 动作
+
+动作会按照添加顺序依次执行，可用的动作包括：
+
+- **添加标签（Add labels）**：为问题或拉取请求附加一个或多个标签。
+- **移除标签（Remove labels）**：删除不再需要的标签。
+- **移动到列（Move to column）**：将卡片移动到同一项目看板中的另一列。
+- **问题状态（Issue state）**：关闭或重新打开关联的问题或拉取请求。
+
+通过组合多个动作，可在单个工作流中完成移动卡片、更新标签等多重操作。
+
+## 管理工作流
+
+### 启用或禁用
+
+每个工作流都带有独立的开关。禁用后即使事件触发也会被忽略，适合临时暂停自动化而保留配置。
+
+### 克隆事件工作流
+
+点击 **Clone** 可以复制当前工作流（事件、过滤器与动作都会被复制）。在需要针对同一触发器设置不同条件时，复制并微调即可快速得到新的工作流。
+
+## 示例：自动分流新的缺陷报告
+
+以下工作流可以让缺陷报告自动进入待处理区：
+
+1. **事件：** Issues/PRs opened。
+2. **过滤器：** 仅适用于 `issues only`；标签包含 `bug`。
+3. **动作：**
+   - 添加标签 → `needs-triage`。
+   - 移动到列 → “Needs Triage”。
+   - 问题状态 → 保持打开（如有需要也可以强制重新打开以确保可见）。
+
+配置完成后，每当新的缺陷问题创建时都会立即拥有正确的标签并出现在指定列中，维护者可以第一时间看到需要分流的条目。
+
+从简单规则开始，在单个项目中验证效果，再根据团队的重复性任务逐步扩展自动化逻辑。

i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/repository/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "仓库",
+  "position": 10,
+  "link": {
+    "type": "generated-index",
+    "slug": "/usage/repository",
+    "description": "仓库管理，Git操作和内容功能"
+  }
+}