docs: v1.20: sync Gitea 62ac3251fa545d32bdfc9ff824106b97ec63edbb

# Conflicts:
#	user/packages/alpine.md
#	user/packages/cran.md
#	user/packages/debian.md
#	user/packages/go.md
#	user/packages/rpm.md

admin/actions.md

@@ -163,7 +163,7 @@ Certain hosts may require specific configurations for runners to work smoothly.
 
 ### NixOS
 
-The gitea-actions-runner recipe was release in NixOS 23.05. It can be configured via `services.gitea-actions-runner`.
+The gitea-actions-runner recipe was released in NixOS 23.05. It can be configured via `services.gitea-actions-runner`.
 
 Please note that the `services.gitea-actions-runner.instances.<name>.labels` key may be set to `[]` (an empty list) to use the packaged Forgejo instance list. One of `virtualisation.docker.enable` or `virtualisation.podman.enable` will need to be set. The default Forgejo image list is populated with docker images.
 

admin/command-line.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Command Line'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/administration/command-line.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/administration/command-line.en-us.md'
 ---
 
 ## Usage
@@ -208,7 +208,7 @@ Admin operations:
         - `--synchronize-users`: Enable user synchronization.
         - `--page-size value`: Search page size.
       - Examples:
-        - `forgejo admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(uid=%s))" --email-attribute mail`
+        - `forgejo admin auth add-ldap --name ldap --security-protocol unencrypted --host mydomain.org --port 389 --user-search-base "ou=Users,dc=mydomain,dc=org" --user-filter "(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))" --email-attribute mail`
     - `update-ldap`: Update existing LDAP (via Bind DN) authentication source
       - Options:
         - `--id value`: ID of authentication source. Required.

admin/config-cheat-sheet.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Configuration Cheat Sheet'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/administration/config-cheat-sheet.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/administration/config-cheat-sheet.en-us.md'
 ---
 
 This is a cheat sheet for the Forgejo configuration file. It contains most of the settings
@@ -59,7 +59,7 @@ In addition there is _`StaticRootPath`_ which can be set as a built-in at build
 - `RUN_USER`: **_current OS username_/`$USER`/`$USERNAME` e.g. git**: The user Forgejo will run as.
   This should be a dedicated system (non-user) account. Setting this incorrectly will cause Forgejo
   to not start.
-- `RUN_MODE`: **prod**: Application run mode, affects performance and debugging. Either "dev", "prod" or "test".
+- `RUN_MODE`: **prod**: Application run mode, affects performance and debugging: `dev` or `prod`, default is `prod`. Mode `dev` makes Forgejo easier to develop and debug, values other than `dev` are treated as `prod` which is for production use.
 
 ## Repository (`repository`)
 
@@ -75,16 +75,14 @@ In addition there is _`StaticRootPath`_ which can be set as a built-in at build
 - `DEFAULT_PUSH_CREATE_PRIVATE`: **true**: Default private when creating a new repository with push-to-create.
 - `MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per user,
   `-1` means no limit.
-- `PULL_REQUEST_QUEUE_LENGTH`: **1000**: Length of pull request patch test queue, make it. **DEPRECATED** use `LENGTH` in `[queue.pr_patch_checker]`.
-  as large as possible. Use caution when editing this value.
-- `MIRROR_QUEUE_LENGTH`: **1000**: Patch test queue length, increase if pull request patch
-  testing starts hanging. **DEPRECATED** use `LENGTH` in `[queue.mirror]`.
 - `PREFERRED_LICENSES`: **Apache License 2.0,MIT License**: Preferred Licenses to place at
   the top of the list. Name must match file name in options/license or custom/options/license.
 - `DISABLE_HTTP_GIT`: **false**: Disable the ability to interact with repositories over the
   HTTP protocol.
 - `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when
   default SSH port is used.
+- `GO_GET_CLONE_URL_PROTOCOL`: **https**: Value for the "go get" request returns the repository url as https or ssh
+  default is https.
 - `ACCESS_CONTROL_ALLOW_ORIGIN`: **\<empty\>**: Value for Access-Control-Allow-Origin header,
   default is not to present. **WARNING**: This maybe harmful to you website if you do not
   give it a right value.
@@ -129,6 +127,7 @@ In addition there is _`StaticRootPath`_ which can be set as a built-in at build
 ### Repository - Issue (`repository.issue`)
 
 - `LOCK_REASONS`: **Too heated,Off-topic,Resolved,Spam**: A list of reasons why a Pull Request or Issue can be locked
+- `MAX_PINNED`: **3**: Maximum number of pinned Issues per Repo. Set to 0 to disable pinning Issues.
 
 ### Repository - Upload (`repository.upload`)
 
@@ -208,7 +207,6 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `SHOW_USER_EMAIL`: **true**: Whether the email of the user should be shown in the Explore Users page.
 - `THEMES`: **forgejo-auto,forgejo-light,forgejo-dark,auto,gitea,arc-green**: All available themes. Allow users select personalized themes.
   regardless of the value of `DEFAULT_THEME`.
-- `THEME_COLOR_META_TAG`: **#6cc644**: Value of `theme-color` meta tag, used by Android >= 5.0. An invalid color like "none" or "disable" will have the default style. More info: https://developers.google.com/web/updates/2014/11/Support-for-theme-color-in-Chrome-39-for-Android
 - `MAX_DISPLAY_FILE_SIZE`: **8388608**: Max size of files to be displayed (default is 8MiB)
 - `REACTIONS`: All available reactions users can choose on issues/prs and comments
   Values can be emoji alias (:smile:) or a unicode emoji.
@@ -218,7 +216,8 @@ The following configuration set `Content-Type: application/vnd.android.package-a
   add it to this config.
 - `DEFAULT_SHOW_FULL_NAME`: **false**: Whether the full name of the users should be shown where possible. If the full name isn't set, the username will be used.
 - `SEARCH_REPO_DESCRIPTION`: **true**: Whether to search within description at repository search on explore page.
-- `USE_SERVICE_WORKER`: **false**: Whether to enable a Service Worker to cache frontend assets.
+- `ONLY_SHOW_RELEVANT_REPOS`: **false** Whether to only show relevant repos on the explore page when no keyword is specified and default sorting is used.
+  A repo is considered irrelevant if it's a fork or if it has no metadata (no description, no icon, no topic).
 
 ### UI - Admin (`ui.admin`)
 
@@ -262,7 +261,8 @@ The following configuration set `Content-Type: application/vnd.android.package-a
   trailing whitespace to paragraphs is not necessary to force a line break.
 - `CUSTOM_URL_SCHEMES`: Use a comma separated list (ftp,git,svn) to indicate additional
   URL hyperlinks to be rendered in Markdown. URLs beginning in http and https are
-  always displayed
+  always displayed. If this entry is empty, all URL schemes are allowed.
+- `FILE_EXTENSIONS`: **.md,.markdown,.mdown,.mkd,.livemd**: List of file extensions that should be rendered/edited as Markdown. Separate the extensions with a comma. To render files without any extension as markdown, just put a comma.
 - `ENABLE_MATH`: **true**: Enables detection of `\(...\)`, `\[...\]`, `$...$` and `$$...$$` blocks as math blocks.
 
 ## Server (`server`)
@@ -351,7 +351,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
 - `LFS_START_SERVER`: **false**: Enables Git LFS support.
 - `LFS_CONTENT_PATH`: **%(APP_DATA_PATH)s/lfs**: Default LFS content path. (if it is on local storage.) **DEPRECATED** use settings in `[lfs]`.
 - `LFS_JWT_SECRET`: **\<empty\>**: LFS authentication secret, change this a unique string.
-- `LFS_HTTP_AUTH_EXPIRY`: **20m**: LFS authentication validity period in time.Duration, pushes taking longer than this may fail.
+- `LFS_HTTP_AUTH_EXPIRY`: **24h**: LFS authentication validity period in time.Duration, pushes taking longer than this may fail.
 - `LFS_MAX_FILE_SIZE`: **0**: Maximum allowed LFS file size in bytes (Set to 0 for no limit).
 - `LFS_LOCKS_PAGING_NUM`: **50**: Maximum number of LFS Locks returned per page.
 
@@ -448,13 +448,9 @@ relation to port exhaustion.
 - `ISSUE_INDEXER_CONN_STR`: \*\*\*\*: Issue indexer connection string, available when ISSUE_INDEXER_TYPE is elasticsearch. i.e. http://elastic:changeme@localhost:9200
 - `ISSUE_INDEXER_NAME`: **gitea_issues**: Issue indexer name, available when ISSUE_INDEXER_TYPE is elasticsearch
 - `ISSUE_INDEXER_PATH`: **indexers/issues.bleve**: Index file used for issue search; available when ISSUE*INDEXER_TYPE is bleve and elasticsearch. Relative paths will be made absolute against *`AppWorkPath`\_.
-- The next 4 configuration values are deprecated and should be set in `queue.issue_indexer` however are kept for backwards compatibility:
-- `ISSUE_INDEXER_QUEUE_TYPE`: **levelqueue**: Issue indexer queue, currently supports:`channel`, `levelqueue`, `redis`. **DEPRECATED** use settings in `[queue.issue_indexer]`.
-- `ISSUE_INDEXER_QUEUE_DIR`: **queues/common**: When `ISSUE_INDEXER_QUEUE_TYPE` is `levelqueue`, this will be the path where the queue will be saved. **DEPRECATED** use settings in `[queue.issue_indexer]`. Relative paths will be made absolute against `%(APP_DATA_PATH)s`.
-- `ISSUE_INDEXER_QUEUE_CONN_STR`: **addrs=127.0.0.1:6379 db=0**: When `ISSUE_INDEXER_QUEUE_TYPE` is `redis`, this will store the redis connection string. When `ISSUE_INDEXER_QUEUE_TYPE` is `levelqueue`, this is a directory or additional options of the form `leveldb://path/to/db?option=value&....`, and overrides `ISSUE_INDEXER_QUEUE_DIR`. **DEPRECATED** use settings in `[queue.issue_indexer]`.
-- `ISSUE_INDEXER_QUEUE_BATCH_NUMBER`: **20**: Batch queue number. **DEPRECATED** use settings in `[queue.issue_indexer]`.
 
 - `REPO_INDEXER_ENABLED`: **false**: Enables code search (uses a lot of disk space, about 6 times more than the repository size).
+- `REPO_INDEXER_REPO_TYPES`: **sources,forks,mirrors,templates**: Repo indexer units. The items to index could be `sources`, `forks`, `mirrors`, `templates` or any combination of them separated by a comma. If empty then it defaults to `sources` only, as if you'd like to disable fully please see `REPO_INDEXER_ENABLED`.
 - `REPO_INDEXER_TYPE`: **bleve**: Code search engine type, could be `bleve` or `elasticsearch`.
 - `REPO_INDEXER_PATH`: **indexers/repos.bleve**: Index file used for code search.
 - `REPO_INDEXER_CONN_STR`: \*\*\*\*: Code indexer connection string, available when `REPO_INDEXER_TYPE` is elasticsearch. i.e. http://elastic:changeme@localhost:9200
@@ -463,7 +459,6 @@ relation to port exhaustion.
 - `REPO_INDEXER_INCLUDE`: **empty**: A comma separated list of glob patterns (see https://github.com/gobwas/glob) to **include** in the index. Use `**.txt` to match any files with .txt extension. An empty list means include all files.
 - `REPO_INDEXER_EXCLUDE`: **empty**: A comma separated list of glob patterns (see https://github.com/gobwas/glob) to **exclude** from the index. Files that match this list will not be indexed, even if they match in `REPO_INDEXER_INCLUDE`.
 - `REPO_INDEXER_EXCLUDE_VENDORED`: **true**: Exclude vendored files from index.
-- `UPDATE_BUFFER_LEN`: **20**: Buffer length of index request. **DEPRECATED** use settings in `[queue.issue_indexer]`.
 - `MAX_FILE_SIZE`: **1048576**: Maximum size in bytes of files to be indexed.
 - `STARTUP_TIMEOUT`: **30s**: If the indexer takes longer than this timeout to start - fail. (This timeout will be added to the hammer time above for child processes - as bleve will not start until the previous parent is shutdown.) Set to -1 to never timeout.
 
@@ -471,23 +466,14 @@ relation to port exhaustion.
 
 Configuration at `[queue]` will set defaults for queues with overrides for individual queues at `[queue.*]`. (However see below.)
 
-- `TYPE`: **persistable-channel**: General queue type, currently support: `persistable-channel` (uses a LevelDB internally), `channel`, `level`, `redis`, `dummy`
+- `TYPE`: **level**: General queue type, currently support: `level` (uses a LevelDB internally), `channel`, `redis`, `dummy`. Invalid types are treated as `level`.
-- `DATADIR`: **queues/**: Base DataDir for storing persistent and level queues. `DATADIR` for individual queues can be set in `queue.name` sections but will default to `DATADIR/`**`common`**. (Previously each queue would default to `DATADIR/`**`name`**.) Relative paths will be made absolute against `%(APP_DATA_PATH)s`.
+- `DATADIR`: **queues/common**: Base DataDir for storing level queues. `DATADIR` for individual queues can be set in `queue.name` sections. Relative paths will be made absolute against `%(APP_DATA_PATH)s`.
-- `LENGTH`: **20**: Maximal queue size before channel queues block
+- `LENGTH`: **100**: Maximal queue size before channel queues block
 - `BATCH_LENGTH`: **20**: Batch data before passing to the handler
-- `CONN_STR`: **redis://127.0.0.1:6379/0**: Connection string for the redis queue type. Options can be set using query params. Similarly LevelDB options can also be set using: **leveldb://relative/path?option=value** or **leveldb:///absolute/path?option=value**, and will override `DATADIR`
+- `CONN_STR`: **redis://127.0.0.1:6379/0**: Connection string for the redis queue type. For `redis-cluster` use `redis+cluster://127.0.0.1:6379/0`. Options can be set using query params. Similarly, LevelDB options can also be set using: **leveldb://relative/path?option=value** or **leveldb:///absolute/path?option=value**, and will override `DATADIR`
 - `QUEUE_NAME`: **\_queue**: The suffix for default redis and disk queue name. Individual queues will default to **`name`**`QUEUE_NAME` but can be overridden in the specific `queue.name` section.
-- `SET_NAME`: **\_unique**: The suffix that will be added to the default redis and disk queue `set` name for unique queues. Individual queues will default to
+- `SET_NAME`: **\_unique**: The suffix that will be added to the default redis and disk queue `set` name for unique queues. Individual queues will default to **`name`**`QUEUE_NAME`_`SET_NAME`_ but can be overridden in the specific `queue.name` section.
-  **`name`**`QUEUE_NAME`_`SET_NAME`_ but can be overridden in the specific `queue.name` section.
-- `WRAP_IF_NECESSARY`: **true**: Will wrap queues with a timeoutable queue if the selected queue is not ready to be created - (Only relevant for the level queue.)
-- `MAX_ATTEMPTS`: **10**: Maximum number of attempts to create the wrapped queue
-- `TIMEOUT`: **GRACEFUL_HAMMER_TIME + 30s**: Timeout the creation of the wrapped queue if it takes longer than this to create.
-- Queues by default come with a dynamically scaling worker pool. The following settings configure this:
-- `WORKERS`: **0**: Number of initial workers for the queue.
 - `MAX_WORKERS`: **10**: Maximum number of worker go-routines for the queue.
-- `BLOCK_TIMEOUT`: **1s**: If the queue blocks for this time, boost the number of workers - the `BLOCK_TIMEOUT` will then be doubled before boosting again whilst the boost is ongoing.
-- `BOOST_TIMEOUT`: **5m**: Boost workers will timeout after this long.
-- `BOOST_WORKERS`: **1**: This many workers will be added to the worker pool if there is a boost.
 
 Forgejo creates the following non-unique queues:
 
@@ -505,21 +491,6 @@ And the following unique queues:
 - `mirror`
 - `pr_patch_checker`
 
-Certain queues have defaults that override the defaults set in `[queue]` (this occurs mostly to support older configuration):
-
-- `[queue.issue_indexer]`
-  - `TYPE` this will default to `[queue]` `TYPE` if it is set but if not it will appropriately convert `[indexer]` `ISSUE_INDEXER_QUEUE_TYPE` if that is set.
-  - `LENGTH` will default to `[indexer]` `UPDATE_BUFFER_LEN` if that is set.
-  - `BATCH_LENGTH` will default to `[indexer]` `ISSUE_INDEXER_QUEUE_BATCH_NUMBER` if that is set.
-  - `DATADIR` will default to `[indexer]` `ISSUE_INDEXER_QUEUE_DIR` if that is set.
-  - `CONN_STR` will default to `[indexer]` `ISSUE_INDEXER_QUEUE_CONN_STR` if that is set.
-- `[queue.mailer]`
-  - `LENGTH` will default to **100** or whatever `[mailer]` `SEND_BUFFER_LEN` is.
-- `[queue.pr_patch_checker]`
-  - `LENGTH` will default to **1000** or whatever `[repository]` `PULL_REQUEST_QUEUE_LENGTH` is.
-- `[queue.mirror]`
-  - `LENGTH` will default to **1000** or whatever `[repository]` `MIRROR_QUEUE_LENGTH` is.
-
 ## Admin (`admin`)
 
 - `DEFAULT_EMAIL_NOTIFICATIONS`: **enabled**: Default configuration for email notifications for users (user configurable). Options: enabled, onmention, disabled
@@ -529,7 +500,7 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
 
 - `INSTALL_LOCK`: **false**: Controls access to the installation page. When set to "true", the installation page is not accessible.
 - `SECRET_KEY`: **\<random at every install\>**: Global secret key. This key is VERY IMPORTANT, if you lost it, the data encrypted by it (like 2FA secret) can't be decrypted anymore.
-- `SECRET_KEY_URI`: **<empty>**: Instead of defining SECRET_KEY, this option can be used to use the key stored in a file (example value: `file:/etc/forgejo/secret_key`). It shouldn't be lost like SECRET_KEY.
+- `SECRET_KEY_URI`: **\<empty\>**: Instead of defining SECRET_KEY, this option can be used to use the key stored in a file (example value: `file:/etc/forgejo/secret_key`). It shouldn't be lost like SECRET_KEY.
 - `LOGIN_REMEMBER_DAYS`: **7**: Cookie lifetime, in days.
 - `COOKIE_USERNAME`: **gitea_awesome**: Name of the cookie used to store the current username.
 - `COOKIE_REMEMBER_NAME`: **gitea_incredible**: Name of cookie used to store authentication
@@ -555,7 +526,7 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
 - `ONLY_ALLOW_PUSH_IF_GITEA_ENVIRONMENT_SET`: **true**: Set to `false` to allow local users to push to gitea-repositories without setting up the Forgejo environment. This is not recommended and if you want local users to push to Forgejo repositories you should set the environment appropriately.
 - `IMPORT_LOCAL_PATHS`: **false**: Set to `false` to prevent all users (including admin) from importing local path on server.
 - `INTERNAL_TOKEN`: **\<random at every install if no uri set\>**: Secret used to validate communication within Forgejo binary.
-- `INTERNAL_TOKEN_URI`: **<empty>**: Instead of defining INTERNAL_TOKEN in the configuration, this configuration option can be used to give Forgejo a path to a file that contains the internal token (example value: `file:/etc/forgejo/internal_token`)
+- `INTERNAL_TOKEN_URI`: **\<empty\>**: Instead of defining INTERNAL_TOKEN in the configuration, this configuration option can be used to give Forgejo a path to a file that contains the internal token (example value: `file:/etc/forgejo/internal_token`)
 - `PASSWORD_HASH_ALGO`: **pbkdf2**: The hash algorithm to use \[argon2, pbkdf2, pbkdf2_v1, pbkdf2_hi, scrypt, bcrypt\], argon2 and scrypt will spend significant amounts of memory.
   - Note: The default parameters for `pbkdf2` hashing have changed - the previous settings are available as `pbkdf2_v1` but are not recommended.
   - The hash functions may be tuned by using `$` after the algorithm:
@@ -586,8 +557,8 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
 ## Camo (`camo`)
 
 - `ENABLED`: **false**: Enable media proxy, we support images only at the moment.
-- `SERVER_URL`: **<empty>**: URL of camo server, it **is required** if camo is enabled.
+- `SERVER_URL`: **\<empty\>**: URL of camo server, it **is required** if camo is enabled.
-- `HMAC_KEY`: **<empty>**: Provide the HMAC key for encoding URLs, it **is required** if camo is enabled.
+- `HMAC_KEY`: **\<empty\>**: Provide the HMAC key for encoding URLs, it **is required** if camo is enabled.
 - `ALLWAYS`: **false**: Set to true to use camo for both HTTP and HTTPS content, otherwise only non-HTTPS URLs are proxied
 
 ## OpenID (`openid`)
@@ -666,9 +637,8 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
 - `ENABLE_TIMETRACKING`: **true**: Enable Timetracking feature.
 - `DEFAULT_ENABLE_TIMETRACKING`: **true**: Allow repositories to use timetracking by default.
 - `DEFAULT_ALLOW_ONLY_CONTRIBUTORS_TO_TRACK_TIME`: **true**: Only allow users with write permissions to track time.
-- `EMAIL_DOMAIN_WHITELIST`: **\<empty\>**: If non-empty, list of domain names that can only be used to register
+- `EMAIL_DOMAIN_ALLOWLIST`: **\<empty\>**: If non-empty, comma separated list of domain names that can only be used to register on this instance, wildcard is supported.
-  on this instance.
+- `EMAIL_DOMAIN_BLOCKLIST`: **\<empty\>**: If non-empty, comma separated list of domain names that cannot be used to register on this instance, wildcard is supported.
-- `EMAIL_DOMAIN_BLOCKLIST`: **\<empty\>**: If non-empty, list of domain names that cannot be used to register on this instance
 - `SHOW_REGISTRATION_BUTTON`: **! DISABLE_REGISTRATION**: Show Registration Button
 - `SHOW_MILESTONES_DASHBOARD_PAGE`: **true** Enable this to show the milestones dashboard page - a view of all the user's milestones
 - `AUTO_WATCH_NEW_REPOS`: **true**: Enable this to let all organisation users watch new repos when they are created
@@ -765,10 +735,11 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
 ## Cache (`cache`)
 
 - `ENABLED`: **true**: Enable the cache.
-- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, `twoqueue` or `memcache`. (`twoqueue` represents a size limited LRU cache.)
+- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, `redis-cluster`, `twoqueue` or `memcache`. (`twoqueue` represents a size limited LRU cache.)
 - `INTERVAL`: **60**: Garbage Collection interval (sec), for memory and twoqueue cache only.
-- `HOST`: **\<empty\>**: Connection string for `redis` and `memcache`. For `twoqueue` sets configuration for the queue.
+- `HOST`: **\<empty\>**: Connection string for `redis`, `redis-cluster` and `memcache`. For `twoqueue` sets configuration for the queue.
   - Redis: `redis://:macaron@127.0.0.1:6379/0?pool_size=100&idle_timeout=180s`
+  - Redis-cluster `redis+cluster://:macaron@127.0.0.1:6379/0?pool_size=100&idle_timeout=180s`
   - Memcache: `127.0.0.1:9090;127.0.0.1:9091`
   - TwoQueue LRU cache: `{"size":50000,"recent_ratio":0.25,"ghost_ratio":0.5}` or `50000` representing the maximum number of objects stored in the cache.
 - `ITEM_TTL`: **16h**: Time to keep items in cache if not used, Setting it to -1 disables caching.
@@ -781,7 +752,7 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
 
 ## Session (`session`)
 
-- `PROVIDER`: **memory**: Session engine provider \[memory, file, redis, db, mysql, couchbase, memcache, postgres\]. Setting `db` will reuse the configuration in `[database]`
+- `PROVIDER`: **memory**: Session engine provider \[memory, file, redis, redis-cluster, db, mysql, couchbase, memcache, postgres\]. Setting `db` will reuse the configuration in `[database]`
 - `PROVIDER_CONFIG`: **data/sessions**: For file, the root path; for db, empty (database config will be used); for others, the connection string. Relative paths will be made absolute against _`AppWorkPath`_.
 - `COOKIE_SECURE`: **false**: Enable this to force using HTTPS for all session access.
 - `COOKIE_NAME`: **i_like_gitea**: The name of the cookie used for the session ID.
@@ -801,8 +772,9 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
 - `AVATAR_STORAGE_TYPE`: **default**: Storage type defined in `[storage.xxx]`. Default is `default` which will read `[storage]` if no section `[storage]` will be a type `local`.
 - `AVATAR_UPLOAD_PATH`: **data/avatars**: Path to store user avatar image files.
 - `AVATAR_MAX_WIDTH`: **4096**: Maximum avatar image width in pixels.
-- `AVATAR_MAX_HEIGHT`: **3072**: Maximum avatar image height in pixels.
+- `AVATAR_MAX_HEIGHT`: **4096**: Maximum avatar image height in pixels.
-- `AVATAR_MAX_FILE_SIZE`: **1048576** (1Mb): Maximum avatar image file size in bytes.
+- `AVATAR_MAX_FILE_SIZE`: **1048576** (1MiB): Maximum avatar image file size in bytes.
+- `AVATAR_MAX_ORIGIN_SIZE`: **262144** (256KiB): If the uploaded file is not larger than this byte size, the image will be used as is, without resizing/converting.
 - `AVATAR_RENDERED_SIZE_FACTOR`: **3**: The multiplication factor for rendered avatar images. Larger values result in finer rendering on HiDPI devices.
 
 - `REPOSITORY_AVATAR_STORAGE_TYPE`: **default**: Storage type defined in `[storage.xxx]`. Default is `default` which will read `[storage]` if no section `[storage]` will be a type `local`.
@@ -840,22 +812,16 @@ Default templates for project boards:
 ## Log (`log`)
 
 - `ROOT_PATH`: **\<empty\>**: Root path for log files.
-- `MODE`: **console**: Logging mode. For multiple modes, use a comma to separate values. You can configure each mode in per mode log subsections `\[log.modename\]`. By default the file mode will log to `$ROOT_PATH/gitea.log`.
+- `MODE`: **console**: Logging mode. For multiple modes, use a comma to separate values. You can configure each mode in per mode log subsections `\[log.writer-mode-name\]`.
 - `LEVEL`: **Info**: General log level. \[Trace, Debug, Info, Warn, Error, Critical, Fatal, None\]
-- `STACKTRACE_LEVEL`: **None**: Default log level at which to log create stack traces. \[Trace, Debug, Info, Warn, Error, Critical, Fatal, None\]
+- `STACKTRACE_LEVEL`: **None**: Default log level at which to log create stack traces (rarely useful, do not set it). \[Trace, Debug, Info, Warn, Error, Critical, Fatal, None\]
 - `ENABLE_SSH_LOG`: **false**: save ssh log to log file
-- `ENABLE_XORM_LOG`: **true**: Set whether to perform XORM logging. Please note SQL statement logging can be disabled by setting `LOG_SQL` to false in the `[database]` section.
+- `logger.access.MODE`: **\<empty\>**: The "access" logger
-
+- `logger.router.MODE`: **,**: The "router" logger, a single comma means it will use the default MODE above
-### Router Log (`log`)
+- `logger.xorm.MODE`: **,**: The "xorm" logger
-
-- `DISABLE_ROUTER_LOG`: **false**: Mute printing of the router log.
-- `ROUTER`: **console**: The mode or name of the log the router should log to. (If you set this to `,` it will log to default Forgejo logger.)
-  NB: You must have `DISABLE_ROUTER_LOG` set to `false` for this option to take effect. Configure each mode in per mode log subsections `\[log.modename.router\]`.
 
 ### Access Log (`log`)
 
-- `ENABLE_ACCESS_LOG`: **false**: Creates an access.log in NCSA common log format, or as per the following template
-- `ACCESS`: **file**: Logging mode for the access logger, use a comma to separate values. Configure each mode in per mode log subsections `\[log.modename.access\]`. By default the file mode will log to `$ROOT_PATH/access.log`. (If you set this to `,` it will log to the default Forgejo logger.)
 - `ACCESS_LOG_TEMPLATE`: **`{{.Ctx.RemoteAddr}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}\" \"{{.Ctx.Req.UserAgent}}"`**: Sets the template used to create the access log.
   - The following variables are available:
   - `Ctx`: the `context.Context` of the request.
@@ -863,31 +829,31 @@ Default templates for project boards:
   - `Start`: the start time of the request.
   - `ResponseWriter`: the responseWriter from the request.
   - `RequestID`: the value matching REQUEST_ID_HEADERS（default: `-`, if not matched）.
-  - You must be very careful to ensure that this template does not throw errors or panics as this template runs outside of the panic/recovery script.
+  - You must be very careful to ensure that this template does not throw errors or panics as this template runs outside the panic/recovery script.
 - `REQUEST_ID_HEADERS`: **\<empty\>**: You can configure multiple values that are splited by comma here. It will match in the order of configuration, and the first match will be finally printed in the access log.
   - e.g.
   - In the Request Header: X-Request-ID: **test-id-123**
   - Configuration in app.ini: REQUEST_ID_HEADERS = X-Request-ID
   - Print in log: 127.0.0.1:58384 - - [14/Feb/2023:16:33:51 +0800] "**test-id-123**" ...
 
-### Log subsections (`log.name`, `log.name.*`)
+### Log subsections (`log.<writer-mode-name>`)
 
-- `LEVEL`: **log.LEVEL**: Sets the log-level of this sublogger. Defaults to the `LEVEL` set in the global `[log]` section.
+- `MODE`: **name**: Sets the mode of this log writer - Defaults to the provided subsection name. This allows you to have two different file loggers at different levels.
+- `LEVEL`: **log.LEVEL**: Sets the log-level of this writer. Defaults to the `LEVEL` set in the global `[log]` section.
 - `STACKTRACE_LEVEL`: **log.STACKTRACE_LEVEL**: Sets the log level at which to log stack traces.
-- `MODE`: **name**: Sets the mode of this sublogger - Defaults to the provided subsection name. This allows you to have two different file loggers at different levels.
 - `EXPRESSION`: **""**: A regular expression to match either the function name, file or message. Defaults to empty. Only log messages that match the expression will be saved in the logger.
 - `FLAGS`: **stdflags**: A comma separated string representing the log flags. Defaults to `stdflags` which represents the prefix: `2009/01/23 01:23:23 ...a/b/c/d.go:23:runtime.Caller() [I]: message`. `none` means don't prefix log lines. See `modules/log/flags.go` for more information.
 - `PREFIX`: **""**: An additional prefix for every log line in this logger. Defaults to empty.
 - `COLORIZE`: **false**: Whether to colorize the log lines
 
-### Console log mode (`log.console`, `log.console.*`, or `MODE=console`)
+### Console log mode (`log.console`, or `MODE=console`)
 
 - For the console logger `COLORIZE` will default to `true` if not on windows or the terminal is determined to be able to color.
 - `STDERR`: **false**: Use Stderr instead of Stdout.
 
-### File log mode (`log.file`, `log.file.*` or `MODE=file`)
+### File log mode (`log.file`, or `MODE=file`)
 
-- `FILE_NAME`: Set the file name for this logger. Defaults as described above. If relative will be relative to the `ROOT_PATH`
+- `FILE_NAME`: Set the file name for this logger. Defaults to `forgejo.log` (exception: access log defaults to `access.log`). If relative will be relative to the `ROOT_PATH`
 - `LOG_ROTATE`: **true**: Rotate the log files.
 - `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file, 28 represents 256Mb.
 - `DAILY_ROTATE`: **true**: Rotate logs daily.
@@ -895,21 +861,13 @@ Default templates for project boards:
 - `COMPRESS`: **true**: Compress old log files by default with gzip
 - `COMPRESSION_LEVEL`: **-1**: Compression level
 
-### Conn log mode (`log.conn`, `log.conn.*` or `MODE=conn`)
+### Conn log mode (`log.conn`, or `MODE=conn`)
 
 - `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message.
 - `RECONNECT`: **false**: Try to reconnect when connection is lost.
 - `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp".
 - `ADDR`: **:7020**: Sets the address to connect to.
 
-### SMTP log mode (`log.smtp`, `log.smtp.*` or `MODE=smtp`)
-
-- `USER`: User email address to send from.
-- `PASSWD`: Password for the smtp server.
-- `HOST`: **127.0.0.1:25**: The SMTP host to connect to.
-- `RECEIVERS`: Email addresses to send to.
-- `SUBJECT`: **Diagnostic message from Gitea**
-
 ## Cron (`cron`)
 
 - `ENABLED`: **false**: Enable to run all cron tasks periodically with default settings.
@@ -1025,7 +983,7 @@ Default templates for project boards:
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
 - `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
 - `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
-- `OLDER_THAN`: **@every 8760h**: any action older than this expression will be deleted from database, suggest using `8760h` (1 year) because that's the max length of heatmap.
+- `OLDER_THAN`: **8760h**: any action older than this expression will be deleted from database, suggest using `8760h` (1 year) because that's the max length of heatmap.
 
 #### Cron - Check for new Forgejo versions ('cron.update_checker')
 
@@ -1042,7 +1000,7 @@ Default templates for project boards:
 - `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
 - `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
 - `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
-- `OLDER_THAN`: **@every 8760h**: any system notice older than this expression will be deleted from database.
+- `OLDER_THAN`: **8760h**: any system notice older than this expression will be deleted from database.
 
 #### Cron - Garbage collect LFS pointers in repositories ('cron.gc_lfs')
 
@@ -1075,12 +1033,7 @@ Default templates for project boards:
 - `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.
 
-## Git - Reflog settings (`git.reflog`)
+### Git - Timeout settings (`git.timeout`)
-
-- `ENABLED`: **true** Set to true to enable Git to write changes to reflogs in each repo.
-- `EXPIRATION`: **90** Reflog entry lifetime, in days. Entries are removed opportunistically by Git.
-
-## Git - Timeout settings (`git.timeout`)
 
 - `DEFAULT`: **360**: Git operations default timeout seconds.
 - `MIGRATE`: **600**: Migrate external repositories timeout seconds.
@@ -1089,6 +1042,15 @@ Default templates for project boards:
 - `PULL`: **300**: Git pull from internal repositories timeout seconds.
 - `GC`: **60**: Git repository GC timeout seconds.
 
+### Git - Config options (`git.config`)
+
+The key/value pairs in this section will be used as git config.
+This section only does "set" config, a removed config key from this section won't be removed from git config automatically. The format is `some.configKey = value`.
+
+- `diff.algorithm`: **histogram**
+- `core.logAllRefUpdates`: **true**
+- `gc.reflogExpire`: **90**
+
 ## Metrics (`metrics`)
 
 - `ENABLED`: **false**: Enables /metrics endpoint for prometheus.
@@ -1132,7 +1094,7 @@ Forgejo can support Markup using external tools. The example below will add a ma
 ENABLED = true
 NEED_POSTPROCESS = true
 FILE_EXTENSIONS = .adoc,.asciidoc
-RENDER_COMMAND = "asciidoc --out-file=- -"
+RENDER_COMMAND = "asciidoctor --embedded --safe-mode=secure --out-file=- -"
 IS_INPUT_FILE = false
 ```
 
@@ -1183,7 +1145,6 @@ If the rule is defined above the renderer ini section or the name does not match
 
 ## Time (`time`)
 
-- `FORMAT`: Time format to display on UI. i.e. RFC1123 or 2006-01-02 15:04:05
 - `DEFAULT_UI_LOCATION`: Default location of time on the UI, so that we can display correct user's time on UI. i.e. Asia/Shanghai
 
 ## Task (`task`)
@@ -1192,7 +1153,7 @@ Task queue configuration has been moved to `queue.task`. However, the below conf
 
 - `QUEUE_TYPE`: **channel**: Task queue type, could be `channel` or `redis`.
 - `QUEUE_LENGTH`: **1000**: Task queue length, available only when `QUEUE_TYPE` is `channel`.
-- `QUEUE_CONN_STR`: **redis://127.0.0.1:6379/0**: Task queue connection string, available only when `QUEUE_TYPE` is `redis`. If redis needs a password, use `redis://123@127.0.0.1:6379/0`.
+- `QUEUE_CONN_STR`: **redis://127.0.0.1:6379/0**: Task queue connection string, available only when `QUEUE_TYPE` is `redis`. If redis needs a password, use `redis://123@127.0.0.1:6379/0` or `redis+cluster://123@127.0.0.1:6379/0`.
 
 ## Migrations (`migrations`)
 
@@ -1222,19 +1183,24 @@ WARNING: Changing the settings below can break federation.
 - `CHUNKED_UPLOAD_PATH`: **tmp/package-upload**: Path for chunked uploads. Defaults to `APP_DATA_PATH` + `tmp/package-upload`
 - `LIMIT_TOTAL_OWNER_COUNT`: **-1**: Maximum count of package versions a single owner can have (`-1` means no limits)
 - `LIMIT_TOTAL_OWNER_SIZE`: **-1**: Maximum size of packages a single owner can use (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
+- `LIMIT_SIZE_ALPINE`: **-1**: Maximum size of an Alpine upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_CARGO`: **-1**: Maximum size of a Cargo upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_CHEF`: **-1**: Maximum size of a Chef upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_COMPOSER`: **-1**: Maximum size of a Composer upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_CONAN`: **-1**: Maximum size of a Conan upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_CONDA`: **-1**: Maximum size of a Conda upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_CONTAINER`: **-1**: Maximum size of a Container upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
+- `LIMIT_SIZE_CRAN`: **-1**: Maximum size of a CRAN upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
+- `LIMIT_SIZE_DEBIAN`: **-1**: Maximum size of a Debian upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_GENERIC`: **-1**: Maximum size of a Generic upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
+- `LIMIT_SIZE_GO`: **-1**: Maximum size of a Go upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_HELM`: **-1**: Maximum size of a Helm upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_MAVEN`: **-1**: Maximum size of a Maven upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_NPM`: **-1**: Maximum size of a npm upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_NUGET`: **-1**: Maximum size of a NuGet upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_PUB`: **-1**: Maximum size of a Pub upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_PYPI`: **-1**: Maximum size of a PyPI upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
+- `LIMIT_SIZE_RPM`: **-1**: Maximum size of a RPM upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_RUBYGEMS`: **-1**: Maximum size of a RubyGems upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_SWIFT`: **-1**: Maximum size of a Swift upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)
 - `LIMIT_SIZE_VAGRANT`: **-1**: Maximum size of a Vagrant upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`)

admin/database-preparation.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Database Preparation'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/installation/database-preparation.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/installation/database-preparation.en-us.md'
 ---
 
 You need a database to use Forgejo. Forgejo supports PostgreSQL (>=10), MySQL (>=5.7) or MariaDB (>=10.0), SQLite, and MSSQL (>=2008R2 SP3). This page will guide into preparing database. Only PostgreSQL and MySQL/MariaDB will be covered here since those database engines are widely-used in production. If you plan to use SQLite, you can ignore this chapter.

admin/email-setup.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Email setup'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/administration/email-setup.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/administration/email-setup.en-us.md'
 ---
 
 Forgejo has mailer functionality for sending transactional emails (such as registration confirmation). It can be configured to either use Sendmail (or compatible MTAs like Postfix and msmtp) or directly use SMTP server.

admin/incoming-email.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Incoming Email'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/incoming-email.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/incoming-email.en-us.md'
 ---
 
 Forgejo supports the execution of several actions through incoming mails. This page describes how to set this up.

admin/logging-documentation.md

@@ -2,112 +2,144 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Logging Configuration'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/administration/logging-documentation.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/administration/logging-config.en-us.md'
 ---
 
 The logging configuration of Forgejo mainly consists of 3 types of components:
 
 - The `[log]` section for general configuration
-- `[log.<sublogger>]` sections for the configuration of different log outputs
+- `[log.<mode-name>]` sections for the configuration of different log writers to output logs, aka: "writer mode", the mode name is also used as "writer name".
-- `[log.<sublogger>.<group>]` sections for output specific configuration of a log group
+- The `[log]` section can also contain sub-logger configurations following the key schema `logger.<logger-name>.<CONFIG-KEY>`
 
-As mentioned below, there is a fully functional log output by default, so it is not necessary to define one.
+There is a fully functional log output by default, so it is not necessary to define one.
 
 ## The `[log]` section
 
-Configuration of logging facilities in Forgejo happen in the `[log]` section and it's subsections.
+Configuration of logging facilities in Forgejo happen in the `[log]` section and its subsections.
 
 In the top level `[log]` section the following configurations can be placed:
 
-- `ROOT_PATH`: (Default: **%(FORGEJO_WORK_DIR)/log**): Base path for log files
+- `ROOT_PATH`: (Default: **%(GITEA_WORK_DIR)/log**): Base path for log files
 - `MODE`: (Default: **console**) List of log outputs to use for the Default logger.
-- `ROUTER`: (Default: **console**): List of log outputs to use for the Router logger.
+- `LEVEL`: (Default: **Info**) Least severe log events to persist, case-insensitive. Possible values are: `Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`.
-- `ACCESS`: List of log outputs to use for the Access logger.
-- `XORM`: (Default: **,**) List of log outputs to use for the XORM logger.
-- `ENABLE_ACCESS_LOG`: (Default: **false**): whether the Access logger is allowed to emit logs
-- `ENABLE_XORM_LOG`: (Default: **true**): whether the XORM logger is allowed to emit logs
-
-For details on the loggers check the "Log Groups" section.
-Important: log outputs won't be used if you don't enable them for the desired loggers in the corresponding list value.
-
-Lists are specified as comma separated values. This format also works in subsection.
-
-This section may be used for defining default values for subsections.
-Examples:
-
-- `LEVEL`: (Default: **Info**) Least severe log events to persist. Case insensitive. The full list of levels can be read in [app.example.ini](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/custom/conf/app.example.ini).
 - `STACKTRACE_LEVEL`: (Default: **None**) For this and more severe events the stacktrace will be printed upon getting logged.
 
-Some values are not inherited by subsections. For details see the "Non-inherited default values" section.
+And it can contain the following sub-loggers:
 
-## Log outputs
+- `logger.router.MODE`: (Default: **,**): List of log outputs to use for the Router logger.
+- `logger.access.MODE`: (Default: **\<empty\>**) List of log outputs to use for the Access logger. By default, the access logger is disabled.
+- `logger.xorm.MODE`: (Default: **,**) List of log outputs to use for the XORM logger.
 
-Log outputs are the targets to which log messages will be sent.
+Setting a comma (`,`) to sub-logger's mode means making it use the default global `MODE`.
-The content and the format of the log messages to be saved can be configured in these.
 
-Log outputs are also called subloggers.
+## Quick samples
 
-Forgejo provides 4 possible log outputs:
+### Default (empty) Configuration
 
-- `console` - Log to `os.Stdout` or `os.Stderr`
+The empty configuration is equivalent to default:
+
+```ini
+[log]
+ROOT_PATH = %(GITEA_WORK_DIR)/log
+MODE = console
+LEVEL = Info
+STACKTRACE_LEVEL = None
+logger.router.MODE = ,
+logger.xorm.MODE = ,
+logger.access.MODE =
+
+; this is the config options of "console" mode (used by MODE=console above)
+[log.console]
+MODE = console
+FLAGS = stdflags
+PREFIX =
+COLORIZE = true
+```
+
+This is equivalent to sending all logs to the console, with default Golang log being sent to the console log too.
+
+This is only a sample, and it is the default, do not need to write it into your configuration file.
+
+### Disable Router logs and record some access logs to file
+
+The Router logger is disabled, the access logs (>=Warn) goes into `access.log`:
+
+```ini
+[log]
+logger.router.MODE =
+logger.access.MODE = access-file
+
+[log.access-file]
+MODE = file
+LEVEL = Warn
+FILE_NAME = access.log
+```
+
+### Set different log levels for different modes
+
+Default logs (>=Warn) goes into `forgejo.log`, while Error logs goes into `file-error.log`:
+
+```ini
+[log]
+LEVEL = Warn
+MODE = file, file-error
+
+; by default, the "file" mode will record logs to %(log.ROOT_PATH)/forgejo.log, so we don't need to set it
+; [log.file]
+
+[log.file-error]
+LEVEL = Error
+FILE_NAME = file-error.log
+```
+
+## Log outputs (mode and writer)
+
+Forgejo provides the following log output writers:
+
+- `console` - Log to `stdout` (or `stderr` if it is set in the config)
 - `file` - Log to a file
 - `conn` - Log to a socket (network or unix)
-- `smtp` - Log via email
-
-By default, Forgejo has a `console` output configured, which is used by the loggers as seen in the section "The log section" above.
 
 ### Common configuration
 
 Certain configuration is common to all modes of log output:
 
-- `MODE` is the mode of the log output. It will default to the sublogger
+- `MODE` is the mode of the log output writer. It will default to the mode name in the ini section. Thus `[log.console]` will default to `MODE = console`.
-  name, thus `[log.console.router]` will default to `MODE = console`.
+- `LEVEL` is the lowest level that this output will log.
-  For mode specific confgurations read further.
+- `STACKTRACE_LEVEL` is the lowest level that this output will print a stacktrace.
-- `LEVEL` is the lowest level that this output will log. This value
+- `COLORIZE` will default to `true` for `console` as described, otherwise it will default to `false`.
-  is inherited from `[log]` and in the case of the non-default loggers
-  from `[log.sublogger]`.
-- `STACKTRACE_LEVEL` is the lowest level that this output will print
-  a stacktrace. This value is inherited.
-- `COLORIZE` will default to `true` for `console` as
-  described, otherwise it will default to `false`.
-
-### Non-inherited default values
-
-There are several values which are not inherited as described above but
-rather default to those specific to type of logger, these are:
-`EXPRESSION`, `FLAGS`, `PREFIX` and `FILE_NAME`.
 
 #### `EXPRESSION`
 
-`EXPRESSION` represents a regular expression that log events must match to be logged by the sublogger. Either the log message, (with colors removed), must match or the `longfilename:linenumber:functionname` must match. NB: the whole message or string doesn't need to completely match.
+`EXPRESSION` represents a regular expression that log events must match to be logged by the output writer.
+Either the log message, (with colors removed), must match or the `longfilename:linenumber:functionname` must match.
+NB: the whole message or string doesn't need to completely match.
 
-Please note this expression will be run in the sublogger's goroutine
+Please note this expression will be run in the writer's goroutine but not the logging event goroutine.
-not the logging event subroutine. Therefore it can be complicated.
 
 #### `FLAGS`
 
 `FLAGS` represents the preceding logging context information that is
 printed before each message. It is a comma-separated string set. The order of values does not matter.
 
+It defaults to `stdflags` (= `date,time,medfile,shortfuncname,levelinitial`)
+
 Possible values are:
 
 - `none` or `,` - No flags.
 - `date` - the date in the local time zone: `2009/01/23`.
 - `time` - the time in the local time zone: `01:23:23`.
-- `microseconds` - microsecond resolution: `01:23:23.123123`. Assumes
+- `microseconds` - microsecond resolution: `01:23:23.123123`. Assumes time.
-  time.
 - `longfile` - full file name and line number: `/a/b/c/d.go:23`.
 - `shortfile` - final file name element and line number: `d.go:23`.
 - `funcname` - function name of the caller: `runtime.Caller()`.
-- `shortfuncname` - last part of the function name. Overrides
+- `shortfuncname` - last part of the function name. Overrides `funcname`.
-  `funcname`.
+- `utc` - if date or time is set, use UTC rather than the local time zone.
-- `utc` - if date or time is set, use UTC rather than the local time
+- `levelinitial` - initial character of the provided level in brackets eg. `[I]` for info.
-  zone.
+- `level` - level in brackets `[INFO]`.
-- `levelinitial` - Initial character of the provided level in brackets eg. `[I]` for info.
+- `gopid` - the Goroutine-PID of the context.
-- `level` - Provided level in brackets `[INFO]`
+- `medfile` - last 20 characters of the filename - equivalent to `shortfile,longfile`.
-- `medfile` - Last 20 characters of the filename - equivalent to
+- `stdflags` - equivalent to `date,time,medfile,shortfuncname,levelinitial`.
-  `shortfile,longfile`.
-- `stdflags` - Equivalent to `date,time,medfile,shortfuncname,levelinitial`
 
 ### Console mode
 
@@ -115,7 +147,7 @@ In this mode the logger will forward log messages to the stdout and
 stderr streams attached to the Forgejo process.
 
 For loggers in console mode, `COLORIZE` will default to `true` if not
-on windows, or the windows terminal can be set into ANSI mode or is a
+on windows, or the Windows terminal can be set into ANSI mode or is a
 cygwin or Msys pipe.
 
 Settings:
@@ -128,7 +160,7 @@ In this mode the logger will save log messages to a file.
 
 Settings:
 
-- `FILE_NAME`: The file to write the log events to. For details see below.
+- `FILE_NAME`: The file to write the log events to, relative to `ROOT_PATH`, Default to `%(ROOT_PATH)/forgejo.log`. Exception: access log will default to `%(ROOT_PATH)/access.log`.
 - `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file. 28 represents 256Mb. For details see below.
 - `LOG_ROTATE` **true**: Whether to rotate the log files. TODO: if false, will it delete instead on daily rotate, or do nothing?.
 - `DAILY_ROTATE`: **true**: Whether to rotate logs daily.
@@ -136,10 +168,6 @@ Settings:
 - `COMPRESS`: **true**: Whether to compress old log files by default with gzip.
 - `COMPRESSION_LEVEL`: **-1**: Compression level. For details see below.
 
-The default value of `FILE_NAME` depends on the respective logger facility.
-If unset, their own default will be used.
-If set it will be relative to the provided `ROOT_PATH` in the master `[log]` section.
-
 `MAX_SIZE_SHIFT` defines the maximum size of a file by left shifting 1 the given number of times (`1 << x`).
 
 The useful values of `COMPRESSION_LEVEL` are from 1 to (and including) 9, where higher numbers mean better compression.
@@ -157,120 +185,28 @@ Settings:
 - `RECONNECT`: **false**: Try to reconnect when connection is lost.
 - `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message.
 
-### SMTP mode
-
-In this mode the logger will send log messages in email.
-
-It is not recommended to use this logger to send general logging
-messages. However, you could perhaps set this logger to work on `FATAL` messages only.
-
-Settings:
-
-- `HOST`: **127.0.0.1:25**: The SMTP host to connect to.
-- `USER`: User email address to send from.
-- `PASSWD`: Password for the smtp server.
-- `RECEIVERS`: Email addresses to send to.
-- `SUBJECT`: **Diagnostic message from Forgejo**. The content of the email's subject field.
-
-## Log Groups
-
-The fundamental thing to be aware of in Forgejo is that there are several
-log groups:
-
-- The "Default" logger
-- The Router logger
-- The Access logger
-- The XORM logger
-
-There is also the go log logger.
-
-### The go log logger
-
-Go provides its own extremely basic logger in the `log` package,
-however, this is not sufficient for our purposes as it does not provide
-a way of logging at multiple levels, nor does it provide a good way of
-controlling where these logs are logged except through setting of a
-writer.
-
-We have therefore redirected this logger to our Default logger, and we
-will log anything that is logged using the go logger at the INFO level.
-
-### The "Default" logger
-
-Calls to `log.Info`, `log.Debug`, `log.Error` etc. from the `code.gitea.io/gitea/modules/log` package will log to this logger.
-
-You can configure the outputs of this logger by setting the `MODE`
-value in the `[log]` section of the configuration.
-
-Each output sublogger is configured in a separate `[log.sublogger.default]`
-which inherits from the sublogger `[log.sublogger]` section and from the
-generic `[log]` section, but there are certain default values. These will
-not be inherited from the `[log]` section:
-
-- `FLAGS` is `stdflags` (Equal to
-  `date,time,medfile,shortfuncname,levelinitial`)
-- `FILE_NAME` will default to `%(ROOT_PATH)/gitea.log`
-- `EXPRESSION` will default to `""`
-- `PREFIX` will default to `""`
-
-The provider type of the sublogger can be set using the `MODE` value in
-its subsection, but will default to the name. This allows you to have
-multiple subloggers that will log to files.
-
 ### The "Router" logger
 
-The Router logger has been substantially changed in v1.17. If you are using the router logger for fail2ban or other monitoring
+The Router logger logs the following message types when Forgejo's route handlers work:
-you will need to update this configuration.
-
-You can disable Router log by setting `DISABLE_ROUTER_LOG` or by setting all of its sublogger configurations to `none`.
-
-You can configure the outputs of this
-router log by setting the `ROUTER` value in the `[log]` section of the
-configuration. `ROUTER` will default to `console` if unset and will default to same level as main logger.
-
-The Router logger logs the following:
 
 - `started` messages will be logged at TRACE level
-- `polling`/`completed` routers will be logged at INFO
+- `polling`/`completed` routers will be logged at INFO. Exception: "/assets" static resource requests are also logged at TRACE.
 - `slow` routers will be logged at WARN
 - `failed` routers will be logged at WARN
 
-The logging level for the router will default to that of the main configuration. Set `[log.<mode>.router]` `LEVEL` to change this.
+### The "XORM" logger
 
-Each output sublogger for this logger is configured in
+To make XORM outputs SQL logs, the `LOG_SQL` in `[database]` section should also be set to `true`.
-`[log.sublogger.router]` sections. There are certain default values
-which will not be inherited from the `[log]` or relevant
-`[log.sublogger]` sections:
-
-- `FILE_NAME` will default to `%(ROOT_PATH)/router.log`
-- `FLAGS` defaults to `date,time`
-- `EXPRESSION` will default to `""`
-- `PREFIX` will default to `""`
-
-NB: You can redirect the router logger to send its events to the Forgejo
-log using the value: `ROUTER = ,`
 
 ### The "Access" logger
 
-The Access logger is a new logger for version 1.9. It provides a NCSA
+The Access logger provides a NCSA
 Common Log compliant log format. It's highly configurable but caution
 should be taken when changing its template. The main benefit of this
 logger is that Forgejo can now log accesses in a standard log format so
 standard tools may be used.
 
-You can enable this logger using `ENABLE_ACCESS_LOG`. Its outputs are
+You can enable this logger using `logger.access.MODE = ...`.
-configured by setting the `ACCESS` value in the `[log]` section of the
-configuration. `ACCESS` defaults to `file` if unset.
-
-Each output sublogger for this logger is configured in
-`[log.sublogger.access]` sections. There are certain default values
-which will not be inherited from the `[log]` or relevant
-`[log.sublogger]` sections:
-
-- `FILE_NAME` will default to `%(ROOT_PATH)/access.log`
-- `FLAGS` defaults to `` or None
-- `EXPRESSION` will default to `""`
-- `PREFIX` will default to `""`
 
 If desired the format of the Access logger can be changed by changing
 the value of the `ACCESS_LOG_TEMPLATE`.
@@ -278,20 +214,18 @@ the value of the `ACCESS_LOG_TEMPLATE`.
 Please note, the access logger will log at `INFO` level, setting the
 `LEVEL` of this logger to `WARN` or above will result in no access logs.
 
-NB: You can redirect the access logger to send its events to the Forgejo
-log using the value: `ACCESS = ,`
-
 #### The ACCESS_LOG_TEMPLATE
 
-This value represent a go template. It's default value is:
+This value represents a go template. Its default value is
 
-`{{.Ctx.RemoteHost}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}" "{{.Ctx.Req.UserAgent}}"`
+```tmpl
+{{.Ctx.RemoteHost}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}" "{{.Ctx.Req.UserAgent}}"`
+```
 
 The template is passed following options:
 
 - `Ctx` is the `context.Context`
-- `Identity` is the `SignedUserName` or `"-"` if the user is not logged
+- `Identity` is the `SignedUserName` or `"-"` if the user is not logged in
-  in
 - `Start` is the start time of the request
 - `ResponseWriter` is the `http.ResponseWriter`
 
@@ -299,91 +233,6 @@ Caution must be taken when changing this template as it runs outside of
 the standard panic recovery trap. The template should also be as simple
 as it runs for every request.
 
-### The "XORM" logger
-
-The XORM logger is a long-standing logger that exists to collect XORM
-log events. It is enabled by default but can be switched off by setting
-`ENABLE_XORM_LOG` to `false` in the `[log]` section. Its outputs are
-configured by setting the `XORM` value in the `[log]` section of the
-configuration. `XORM` defaults to `,` if unset, meaning it is redirected
-to the main Forgejo log.
-
-XORM will log SQL events by default. This can be changed by setting
-the `LOG_SQL` value to `false` in the `[database]` section.
-
-Each output sublogger for this logger is configured in
-`[log.sublogger.xorm]` sections. There are certain default values
-which will not be inherited from the `[log]` or relevant
-`[log.sublogger]` sections:
-
-- `FILE_NAME` will default to `%(ROOT_PATH)/xorm.log`
-- `FLAGS` defaults to `date,time`
-- `EXPRESSION` will default to `""`
-- `PREFIX` will default to `""`
-
-## Debugging problems
-
-When submitting logs in Forgejo issues it is often helpful to submit
-merged logs obtained by either by redirecting the console log to a file or
-copying and pasting it. To that end it is recommended to set your logging to:
-
-```ini
-[database]
-LOG_SQL = false ; SQL logs are rarely helpful unless we specifically ask for them
-
-...
-
-[log]
-MODE = console
-LEVEL = debug ; please set the level to debug when we are debugging a problem
-ROUTER = console
-COLORIZE = false ; this can be true if you can strip out the ansi coloring
-ENABLE_SSH_LOG = true ; shows logs related to git over SSH.
-```
-
-Sometimes it will be helpful get some specific `TRACE` level logging restricted
-to messages that match a specific `EXPRESSION`. Adjusting the `MODE` in the
-`[log]` section to `MODE = console,traceconsole` to add a new logger output
-`traceconsole` and then adding its corresponding section would be helpful:
-
-```ini
-[log.traceconsole] ; traceconsole here is just a name
-MODE = console ; this is the output that the traceconsole writes to
-LEVEL = trace
-EXPRESSION = ; putting a string here will restrict this logger to logging only those messages that match this expression
-```
-
-(It's worth noting that log messages that match the expression at or above debug
-level will get logged twice so don't worry about that.)
-
-`STACKTRACE_LEVEL` should generally be left unconfigured (and hence kept at
-`none`). There are only very specific occasions when it useful.
-
-## Empty Configuration
-
-The empty configuration is equivalent to:
-
-```ini
-[log]
-ROOT_PATH = %(FORGEJO_WORK_DIR)/log
-MODE = console
-LEVEL = Info
-STACKTRACE_LEVEL = None
-ENABLE_ACCESS_LOG = false
-ENABLE_XORM_LOG = true
-XORM = ,
-
-[log.console]
-MODE = console
-LEVEL = %(LEVEL)
-STACKTRACE_LEVEL = %(STACKTRACE_LEVEL)
-FLAGS = stdflags
-PREFIX =
-COLORIZE = true # Or false if your windows terminal cannot color
-```
-
-This is equivalent to sending all logs to the console, with default go log being sent to the console log too.
-
 ## Releasing-and-Reopening, Pausing and Resuming logging
 
 If you are running on Unix you may wish to release-and-reopen logs in order to use `logrotate` or other tools.
@@ -406,98 +255,20 @@ the Forgejo service.
 The main intention of these commands is to easily add a temporary logger to investigate problems on running systems where a restart
 may cause the issue to disappear.
 
-## Log colorization
-
-Logs to the console will be colorized by default when not running on
-Windows. Terminal sniffing will occur on Windows and if it is
-determined that we are running on a terminal capable of color we will
-colorize.
-
-Further, on \*nix it is becoming common to have file logs that are
-colored by default. Therefore file logs will be colorised by default
-when not running on Windows.
-
-You can switch on or off colorization by using the `COLORIZE` value.
-
-From a development point of view. If you write
-`log.Info("A %s string", "formatted")` the `formatted` part of the log
-message will be Bolded on colorized logs.
-
-You can change this by either rendering the formatted string yourself.
-Or you can wrap the value in a `log.ColoredValue` struct.
-
-The `log.ColoredValue` struct contains a pointer to value, a pointer to
-string of bytes which should represent a color and second set of reset
-bytes. Pointers were chosen to prevent copying of large numbers of
-values. There are several helper methods:
-
-- `log.NewColoredValue` takes a value and 0 or more color attributes
-  that represent the color. If 0 are provided it will default to a cached
-  bold. Note, it is recommended that color bytes constructed from
-  attributes should be cached if this is a commonly used log message.
-- `log.NewColoredValuePointer` takes a pointer to a value, and
-  0 or more color attributes that represent the color.
-- `log.NewColoredValueBytes` takes a value and a pointer to an array
-  of bytes representing the color.
-
-These functions will not double wrap a `log.ColoredValue`. They will
-also set the `resetBytes` to the cached `resetBytes`.
-
-The `colorBytes` and `resetBytes` are not exported to prevent
-accidental overwriting of internal values.
-
-## ColorFormat & ColorFormatted
-
-Structs may implement the `log.ColorFormatted` interface by implementing the `ColorFormat(fmt.State)` function.
-
-If a `log.ColorFormatted` struct is logged with `%-v` format, its `ColorFormat` will be used instead of the usual `%v`. The full `fmt.State` will be passed to allow implementers to look at additional flags.
-
-In order to help implementers provide `ColorFormat` methods. There is a
-`log.ColorFprintf(...)` function in the log module that will wrap values in `log.ColoredValue` and recognise `%-v`.
-
-In general it is recommended not to make the results of this function too verbose to help increase its versatility. Usually this should simply be an `ID`:`Name`. If you wish to make a more verbose result, it is recommended to use `%-+v` as your marker.
-
-## Log Spoofing protection
-
-In order to protect the logs from being spoofed with cleverly
-constructed messages. Newlines are now prefixed with a tab and control
-characters except those used in an ANSI CSI are escaped with a
-preceding `\` and their octal value.
-
-## Creating a new named logger group
-
-Should a developer wish to create a new named logger, `NEWONE`. It is
-recommended to add an `ENABLE_NEWONE_LOG` value to the `[log]`
-section, and to add a new `NEWONE` value for the modes.
-
-A function like `func newNewOneLogService()` is recommended to manage
-construction of the named logger. e.g.
-
-```go
-func newNewoneLogService() {
-	EnableNewoneLog = Cfg.Section("log").Key("ENABLE_NEWONE_LOG").MustBool(false)
-	Cfg.Section("log").Key("NEWONE").MustString("file") // or console? or "," if you want to send this to default logger by default
-	if EnableNewoneLog {
-		options := newDefaultLogOptions()
-		options.filename = filepath.Join(LogRootPath, "newone.log")
-		options.flags = "stdflags"
-		options.bufferLength = Cfg.Section("log").Key("BUFFER_LEN").MustInt64(10000)
-		generateNamedLogger("newone", options)
-	}
-}
-```
-
-You should then add `newOneLogService` to `NewServices()` in
-`modules/setting/setting.go`
-
 ## Using `logrotate` instead of built-in log rotation
 
 Forgejo includes built-in log rotation, which should be enough for most deployments. However, if you instead want to use the `logrotate` utility:
 
 - Disable built-in log rotation by setting `LOG_ROTATE` to `false` in your `app.ini`.
 - Install `logrotate`.
-- Configure `logrotate` to match your deployment requirements, see `man 8 logrotate` for configuration syntax details. In the `postrotate/endscript` block send Forgejo a `USR1` signal via `kill -USR1` or `kill -10` to the `forgejo` process itself, or run `forgejo manager logging release-and-reopen` (with the appropriate environment). Ensure that your configurations apply to all files emitted by Forgejo loggers as described in the above sections.
+- Configure `logrotate` to match your deployment requirements, see `man 8 logrotate` for configuration syntax details.
+  In the `postrotate/endscript` block send Forgejo a `USR1` signal via `kill -USR1` or `kill -10` to the `forgejo` process itself,
+  or run `forgejo manager logging release-and-reopen` (with the appropriate environment).
+  Ensure that your configurations apply to all files emitted by Forgejo loggers as described in the above sections.
 - Always do `logrotate /etc/logrotate.conf --debug` to test your configurations.
-- If you are using docker and are running from outside of the container you can use `docker exec -u $OS_USER $CONTAINER_NAME sh -c 'forgejo manager logging release-and-reopen'` or `docker exec $CONTAINER_NAME sh -c '/bin/s6-svc -1 /etc/s6/gitea/'` or send `USR1` directly to the Forgejo process itself.
+- If you are using docker and are running from outside the container you can use
+  `docker exec -u $OS_USER $CONTAINER_NAME sh -c 'forgejo manager logging release-and-reopen'`
+  or `docker exec $CONTAINER_NAME sh -c '/bin/s6-svc -1 /etc/s6/gitea/'` or send `USR1` directly to the Forgejo process itself.
 
-The next `logrotate` jobs will include your configurations, so no restart is needed. You can also immediately reload `logrotate` with `logrotate /etc/logrotate.conf --force`.
+The next `logrotate` jobs will include your configurations, so no restart is needed.
+You can also immediately reload `logrotate` with `logrotate /etc/logrotate.conf --force`.

admin/reverse-proxy.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Reverse proxy'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/authentication.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/authentication.en-us.md'
 ---
 
 Forgejo supports Reverse Proxy Header authentication, it will read headers as a trusted login user name or user email address. This hasn't been enabled by default, you can enable it with

admin/seek-assistance.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Seek Assistance'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/help/seek-help.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/help/seek-help.en-us.md'
 ---
 
 - [Chatroom](https://matrix.to/#/#forgejo-chat:matrix.org)

admin/upgrade.md

@@ -41,7 +41,7 @@ Note: Forgejo requires [docker >= 20.10.6](https://wiki.alpinelinux.org/wiki/Rel
 
 ### Performing the upgrade
 
-- If the upgrade is from a Gitea version [lower than 1.6](https://github.com/go-gitea/gitea/blob/e82db15cfa0d1cd85ee493128960a481eb44271c/models/migrations/migrations.go#L63) and greater or equal to 1.2.0, proceed as follows:
+- If the upgrade is from a Gitea version [lower than 1.6](https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/models/migrations/migrations.go#L63) and greater or equal to 1.2.0, proceed as follows:
   - Upgrade to 1.2.3 and manually verify it runs
   - Upgrade to 1.4.3 and manually verify it runs
   - Upgrade to 1.5.3 and manually verify it runs

license.md

@@ -11,9 +11,7 @@ The copyright holders are listed in the git history.
 
 Some content is copied from https://github.com/go-gitea/gitea, published under the [Apache 2.0](https://github.com/go-gitea/gitea/blob/ffce336f1802b2f2298fc8fd27e815086702c812/docs/LICENSE) license.
 
----
+Some content is copied from https://codeberg.org/Codeberg/Documentation/
-
-Some of the content is copied from https://codeberg.org/Codeberg/Documentation/
 
 The Codeberg logos in this website are by @mray,
 licensed under [CC0 1.0](http://creativecommons.org/publicdomain/zero/1.0/).

user/agit-support.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Agit Setup'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/agit-support.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/agit-support.en-us.md'
 ---
 
 Limited support for [agit](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/).

user/api-usage.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'API Usage'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/development/api-usage.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/development/api-usage.en-us.md'
 ---
 
 ## Enabling/configuring API access

user/authentication.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Authentication'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/authentication.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/authentication.en-us.md'
 ---
 
 ## LDAP (Lightweight Directory Access Protocol)
@@ -86,9 +86,9 @@ Adds the following fields:
 
 - User Filter **(required)**
   - An LDAP filter declaring how to find the user record that is attempting to
-    authenticate. The `%s` matching parameter will be substituted with login
+    authenticate. The `%[1]s` matching parameter will be substituted with login
     name given on sign-in form.
-  - Example: `(&(objectClass=posixAccount)(uid=%s))`
+  - Example: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
   - Example for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
   - To substitute more than once, `%[1]s` should be used instead, e.g. when
     matching supplied login name against multiple attributes such as user
@@ -126,8 +126,8 @@ Adds the following fields:
   - An LDAP filter declaring when a user should be allowed to log in. The `%s`
     matching parameter will be substituted with login name given on sign-in
     form.
-  - Example: `(&(objectClass=posixAccount)(cn=%s))`
+  - Example: `(&(objectClass=posixAccount)(|(cn=%[1]s)(mail=%[1]s)))`
-  - Example: `(&(objectClass=posixAccount)(uid=%s))`
+  - Example: `(&(objectClass=posixAccount)(|(uid=%[1]s)(mail=%[1]s)))`
 
 ### Verify group membership in LDAP
 

user/issue-pull-request-templates.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Issue and Pull Request Templates'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/issue-pull-request-templates.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/issue-pull-request-templates.en-us.md'
 ---
 
 Some projects have a standard list of questions that users need to answer

user/labels.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Labels'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/labels.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/labels.en-us.md'
 ---
 
 You can use labels to classify issues and pull requests and to improve your overview over them.

user/linked-references.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Automatically Linked References in Issues, Pull Requests and Commit Messages'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/linked-references.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/linked-references.en-us.md'
 ---
 
 When an issue, pull request or comment is posted, the text description is parsed
@@ -162,28 +162,28 @@ In the examples, `User1/Repo1` refers to the repository where the reference is u
 
 | Reference in User1/Repo1    | Repo1 issues are external | RepoZ issues are external | Should render                                           |
 | --------------------------- | :-----------------------: | :-----------------------: | ------------------------------------------------------- |
-| `#1234`                     |            no             |            N/A            | A link to issue/pull 1234 in `User1/Repo1`              |
+| `#1234`                     |            no             |             -             | A link to issue/pull 1234 in `User1/Repo1`              |
-| `!1234`                     |            no             |            N/A            | A link to issue/pull 1234 in `User1/Repo1`              |
+| `!1234`                     |            no             |             -             | A link to issue/pull 1234 in `User1/Repo1`              |
-| `#1234`                     |            yes            |            N/A            | A link to _external issue_ 1234 for `User1/Repo1`       |
+| `#1234`                     |            yes            |             -             | A link to _external issue_ 1234 for `User1/Repo1`       |
-| `!1234`                     |            yes            |            N/A            | A link to _PR_ 1234 for `User1/Repo1`                   |
+| `!1234`                     |            yes            |             -             | A link to _PR_ 1234 for `User1/Repo1`                   |
-| `User1/Repo1#1234`          |            no             |            N/A            | A link to issue/pull 1234 in `User1/Repo1`              |
+| `User1/Repo1#1234`          |            no             |             -             | A link to issue/pull 1234 in `User1/Repo1`              |
-| `User1/Repo1!1234`          |            no             |            N/A            | A link to issue/pull 1234 in `User1/Repo1`              |
+| `User1/Repo1!1234`          |            no             |             -             | A link to issue/pull 1234 in `User1/Repo1`              |
-| `User1/Repo1#1234`          |            yes            |            N/A            | A link to _external issue_ 1234 for `User1/Repo1`       |
+| `User1/Repo1#1234`          |            yes            |             -             | A link to _external issue_ 1234 for `User1/Repo1`       |
-| `User1/Repo1!1234`          |            yes            |            N/A            | A link to _PR_ 1234 for `User1/Repo1`                   |
+| `User1/Repo1!1234`          |            yes            |             -             | A link to _PR_ 1234 for `User1/Repo1`                   |
-| `UserZ/RepoZ#1234`          |            N/A            |            no             | A link to issue/pull 1234 in `UserZ/RepoZ`              |
+| `UserZ/RepoZ#1234`          |             -             |            no             | A link to issue/pull 1234 in `UserZ/RepoZ`              |
-| `UserZ/RepoZ!1234`          |            N/A            |            no             | A link to issue/pull 1234 in `UserZ/RepoZ`              |
+| `UserZ/RepoZ!1234`          |             -             |            no             | A link to issue/pull 1234 in `UserZ/RepoZ`              |
-| `UserZ/RepoZ#1234`          |            N/A            |            yes            | A link to _external issue_ 1234 for `UserZ/RepoZ`       |
+| `UserZ/RepoZ#1234`          |             -             |            yes            | A link to _external issue_ 1234 for `UserZ/RepoZ`       |
-| `UserZ/RepoZ!1234`          |            N/A            |            yes            | A link to _PR_ 1234 for `UserZ/RepoZ`                   |
+| `UserZ/RepoZ!1234`          |             -             |            yes            | A link to _PR_ 1234 for `UserZ/RepoZ`                   |
 | **Alphanumeric issue IDs:** |             -             |             -             | -                                                       |
-| `AAA-1234`                  |            yes            |            N/A            | A link to _external issue_ `AAA-1234` for `User1/Repo1` |
+| `AAA-1234`                  |            yes            |             -             | A link to _external issue_ `AAA-1234` for `User1/Repo1` |
-| `!1234`                     |            yes            |            N/A            | A link to _PR_ 1234 for `User1/Repo1`                   |
+| `!1234`                     |            yes            |             -             | A link to _PR_ 1234 for `User1/Repo1`                   |
-| `User1/Repo1!1234`          |            yes            |            N/A            | A link to _PR_ 1234 for `User1/Repo1`                   |
+| `User1/Repo1!1234`          |            yes            |             -             | A link to _PR_ 1234 for `User1/Repo1`                   |
-| _Not supported_             |            N/A            |            yes            | A link to _external issue_ `AAA-1234` for `UserZ/RepoZ` |
+| _Not supported_             |             -             |            yes            | A link to _external issue_ `AAA-1234` for `UserZ/RepoZ` |
-| `UserZ/RepoZ!1234`          |            N/A            |            yes            | A link to _PR_ 1234 in `UserZ/RepoZ`                    |
+| `UserZ/RepoZ!1234`          |             -             |            yes            | A link to _PR_ 1234 in `UserZ/RepoZ`                    |
 
 _The last section is for repositories with external issue trackers that use alphanumeric format._
 
-_**N/A**: not applicable._
+_**-**: not applicable._
 
 Note: automatic references between repositories with different types of issues (external vs. internal) are not fully supported
 and may render invalid links.

user/merge-message-templates.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Merge Message templates'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/merge-message-templates.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/merge-message-templates.en-us.md'
 ---
 
 ## File names
@@ -32,3 +32,10 @@ You can use the following variables enclosed in `${}` inside these templates whi
 - PullRequestIndex: Pull request's index number
 - PullRequestReference: Pull request's reference char with index number. i.e. #1, !2
 - ClosingIssues: return a string contains all issues which will be closed by this pull request i.e. `close #1, close #2`
+
+## Rebase
+
+When rebasing without a merge commit, `REBASE_TEMPLATE.md` modifies the message of the last commit. The following additional variables are available in this template:
+
+- CommitTitle: Commit's title
+- CommitBody: Commits's body text

user/oauth2-provider.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'OAuth2 provider'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/development/oauth2-provider.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/development/oauth2-provider.en-us.md'
 ---
 
 Forgejo supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent.
@@ -24,46 +24,47 @@ At the moment Forgejo only supports the [**Authorization Code Grant**](https://t
 - [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636)
 - [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
 
-To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings.
+To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings. To test or debug you can use the web-tool https://oauthdebugger.com/.
 
 ## Scoped Tokens
 
-Forgejo supports the following scopes for tokens:
+Forgejo supports scoped access tokens, which allow users to restrict tokens to operate only on selected url routes. Scopes are grouped by high-level API routes, and further refined to the following:
 
-| Name                                     | Description                                                                                  |
+- `read`: `GET` routes
-| ---------------------------------------- | -------------------------------------------------------------------------------------------- |
+- `write`: `POST`, `PUT`, `PATCH`, and `DELETE` routes (in addition to `GET`)
-| **(no scope)**                           | Grants read-only access to public user profile and public repositories.                      |
+
-| **repo**                                 | Full control over all repositories.                                                          |
+Forgejo token scopes are as follows:
-|     **repo:status**       | Grants read/write access to commit status in all repositories.                               |
+
-|     **public_repo**       | Grants read/write access to public repositories only.                                        |
+| Name                                      | Description                                                                                                                                          |
-| **admin:repo_hook**                      | Grants access to repository hooks of all repositories. This is included in the `repo` scope. |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --- |
-|     **write:repo_hook**   | Grants read/write access to repository hooks                                                 |
+| **(no scope)**                            | Not supported. A scope is required even for public repositories.                                                                                     |
-|     **read:repo_hook**    | Grants read-only access to repository hooks                                                  |
+| **activitypub**                           | `activitypub` API routes: ActivityPub related operations.                                                                                            |
-| **admin:org**                            | Grants full access to organization settings                                                  |
+|     **read:activitypub**   | Grants read access for ActivityPub operations.                                                                                                       |
-|     **write:org**         | Grants read/write access to organization settings                                            |
+|     **write:activitypub**  | Grants read/write/delete access for ActivityPub operations.                                                                                          |
-|     **read:org**          | Grants read-only access to organization settings                                             |
+| **admin**                                 | `/admin/*` API routes: Site-wide administrative operations (hidden for non-admin accounts).                                                          |
-| **admin:public_key**                     | Grants full access for managing public keys                                                  |
+|     **read:admin**         | Grants read access for admin operations, such as getting cron jobs or registered user emails.                                                        |
-|     **write:public_key**  | Grant read/write access to public keys                                                       |
+|     **write:admin**        | Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts.                                           |     |
-|     **read:public_key**   | Grant read-only access to public keys                                                        |
+| **issue**                                 | `issues/*`, `labels/*`, `milestones/*` API routes: Issue-related operations.                                                                         |
-| **admin:org_hook**                       | Grants full access to organizational-level hooks                                             |
+|     **read:issue**         | Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones.                                         |
-| **admin:user_hook**                      | Grants full access to user-level hooks                                                       |
+|     **write:issue**        | Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones.           |
-| **notification**                         | Grants full access to notifications                                                          |
+| **misc**                                  | miscellaneous and settings top-level API routes.                                                                                                     |
-| **user**                                 | Grants full access to user profile info                                                      |
+|     **read:misc**          | Grants read access to miscellaneous operations, such as getting label and gitignore templates.                                                       |
-|     **read:user**         | Grants read access to user's profile                                                         |
+|     **write:misc**         | Grants read/write/delete access to miscellaneous operations, such as markup utility operations.                                                      |
-|     **user:email**        | Grants read access to user's email addresses                                                 |
+| **notification**                          | `notification/*` API routes: user notification operations.                                                                                           |
-|     **user:follow**       | Grants access to follow/un-follow a user                                                     |
+|     **read:notification**  | Grants read access to user notifications, such as which notifications users are subscribed to and read new notifications.                            |
-| **delete_repo**                          | Grants access to delete repositories as an admin                                             |
+|     **write:notification** | Grants read/write/delete access to user notifications, such as marking notifications as read.                                                        |
-| **package**                              | Grants full access to hosted packages                                                        |
+| **organization**                          | `orgs/*` and `teams/*` API routes: Organization and team management operations.                                                                      |
-|     **write:package**     | Grants read/write access to packages                                                         |
+|     **read:organization**  | Grants read access to org and team status, such as listing all orgs a user has visibility to, teams, and team members.                               |
-|     **read:package**      | Grants read access to packages                                                               |
+|     **write:organization** | Grants read/write/delete access to org and team status, such as creating and updating teams and updating org settings.                               |
-|     **delete:package**    | Grants delete access to packages                                                             |
+| **package**                               | `/packages/*` API routes: Packages operations                                                                                                        |
-| **admin:gpg_key**                        | Grants full access for managing GPG keys                                                     |
+|     **read:package**       | Grants read access to package operations, such as reading and downloading available packages.                                                        |
-|     **write:gpg_key**     | Grants read/write access to GPG keys                                                         |
+|     **write:package**      | Grants read/write/delete access to package operations. Currently the same as `read:package`.                                                         |
-|     **read:gpg_key**      | Grants read-only access to GPG keys                                                          |
+| **repository**                            | `/repos/*` API routes except `/repos/issues/*`: Repository file, pull-request, and release operations.                                               |
-| **admin:application**                    | Grants full access to manage applications                                                    |
+|     **read:repository**    | Grants read access to repository operations, such as getting repository files, releases, collaborators.                                              |
-|     **write:application** | Grants read/write access for managing applications                                           |
+|     **write:repository**   | Grants read/write/delete access to repository operations, such as getting updating repository files, creating pull requests, updating collaborators. |
-|     **read:application**  | Grants read access for managing applications                                                 |
+| **user**                                  | `/user/*` and `/users/*` API routes: User-related operations.                                                                                        |
-| **sudo**                                 | Allows to perform actions as the site admin.                                                 |
+|     **read:user**          | Grants read access to user operations, such as getting user repo subscriptions and user settings.                                                    |
+|     **write:user**         | Grants read/write/delete access to user operations, such as updating user repo subscriptions, followed users, and user settings.                     |
 
 ## Client types
 
@@ -71,19 +72,19 @@ Forgejo supports both confidential and public client types, [as defined by RFC 6
 
 For public clients, a redirect URI of a loopback IP address such as `http://127.0.0.1/` allows any port. Avoid using `localhost`, [as recommended by RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3).
 
-## Example
+## Examples
+
+### Confidential client
 
 **Note:** This example does not use PKCE.
 
-1. Redirect to user to the authorization endpoint in order to get their consent for accessing the resources:
+1. Redirect the user to the authorization endpoint in order to get their consent for accessing the resources:
 
    ```curl
-   https://[YOUR-FORGEJO-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
+   https://[YOUR-FORGEJO-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE
    ```
 
-   The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks.
+   The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be sent back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks.
-
-   ![Authorization Page](/authorize.png)
 
    The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example:
 
@@ -91,7 +92,7 @@ For public clients, a redirect URI of a loopback IP address such as `http://127.
    https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
    ```
 
-2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
+2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoint accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
 
    ```curl
    POST https://[YOUR-FORGEJO-URL]/login/oauth/access_token
@@ -118,8 +119,66 @@ For public clients, a redirect URI of a loopback IP address such as `http://127.
    }
    ```
 
-   The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Forgejo and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings.
+   The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Forgejo and cannot be recovered. If you lose the secret, you must regenerate the secret via the application's settings.
 
    The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request.
 
-3. Use the `access_token` to make [API requests](../api-usage) to access the user's resources.
+3. Use the `access_token` to make API requests to access the user's resources.
+
+### Public client (PKCE)
+
+PKCE (Proof Key for Code Exchange) is an extension to the OAuth flow which allows for a secure credential exchange without the requirement to provide a client secret.
+
+**Note**: Please ensure you have registered your OAuth application as a public client.
+
+To achieve this, you have to provide a `code_verifier` for every authorization request. A `code_verifier` has to be a random string with a minimum length of 43 characters and a maximum length of 128 characters. It can contain alphanumeric characters as well as the characters `-`, `.`, `_` and `~`.
+
+Using this `code_verifier` string, a new one called `code_challenge` is created by using one of two methods:
+
+- If you have the required functionality on your client, set `code_challenge` to be a URL-safe base64-encoded string of the SHA256 hash of `code_verifier`. In that case, your `code_challenge_method` becomes `S256`.
+- If you are unable to do so, you can provide your `code_verifier` as a plain string to `code_challenge`. Then you have to set your `code_challenge_method` as `plain`.
+
+After you have generated this values, you can continue with your request.
+
+1. Redirect the user to the authorization endpoint in order to get their consent for accessing the resources:
+
+   ```curl
+   https://[YOUR-FORGEJO-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&code_challenge_method=CODE_CHALLENGE_METHOD&code_challenge=CODE_CHALLENGE&state=STATE
+   ```
+
+   The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be sent back to your application after the user authorizes. The `state` parameter is optional, but should be used to prevent CSRF attacks.
+
+   ![Authorization Page](/authorize.png)
+
+   The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example:
+
+   ```curl
+   https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
+   ```
+
+2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoint accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
+
+   ```curl
+   POST https://[YOUR-FORGEJO-URL]/login/oauth/access_token
+   ```
+
+   ```json
+   {
+     "client_id": "YOUR_CLIENT_ID",
+     "code": "RETURNED_CODE",
+     "grant_type": "authorization_code",
+     "redirect_uri": "REDIRECT_URI",
+     "code_verifier": "CODE_VERIFIER"
+   }
+   ```
+
+   Response:
+
+   ```json
+   {
+     "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
+     "token_type": "bearer",
+     "expires_in": 3600,
+     "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
+   }
+   ```

user/packages/alpine.md

@@ -0,0 +1,120 @@
+---
+layout: '~/layouts/Markdown.astro'
+title: 'Alpine Packages Repository'
+license: 'Apache-2.0'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/alpine.en-us.md'
+---
+
+Publish [Alpine](https://pkgs.alpinelinux.org/) packages for your user or organization.
+
+## Requirements
+
+To work with the Alpine registry, you need to use a HTTP client like `curl` to upload and a package manager like `apk` to consume packages.
+
+The following examples use `apk`.
+
+## Configuring the package registry
+
+To register the Alpine registry add the url to the list of known apk sources (`/etc/apk/repositories`):
+
+```
+https://forgejo.example.com/api/packages/{owner}/alpine/<branch>/<repository>
+```
+
+| Placeholder  | Description                |
+| ------------ | -------------------------- |
+| `owner`      | The owner of the packages. |
+| `branch`     | The branch to use.         |
+| `repository` | The repository to use.     |
+
+If the registry is private, provide credentials in the url. You can use a password or a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}):
+
+```
+https://{username}:{your_password_or_token}@forgejo.example.com/api/packages/{owner}/alpine/<branch>/<repository>
+```
+
+The Alpine registry files are signed with a RSA key which must be known to apk. Download the public key and store it in `/etc/apk/keys/`:
+
+```shell
+curl -JO https://forgejo.example.com/api/packages/{owner}/alpine/key
+```
+
+Afterwards update the local package index:
+
+```shell
+apk update
+```
+
+## Publish a package
+
+To publish an Alpine package (`*.apk`), perform a HTTP `PUT` operation with the package content in the request body.
+
+```
+PUT https://forgejo.example.com/api/packages/{owner}/alpine/{branch}/{repository}
+```
+
+| Parameter    | Description                                                                                                               |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `owner`      | The owner of the package.                                                                                                 |
+| `branch`     | The branch may match the release version of the OS, ex: `v3.17`.                                                          |
+| `repository` | The repository can be used [to group packages](https://wiki.alpinelinux.org/wiki/Repositories) or just `main` or similar. |
+
+Example request using HTTP Basic authentication:
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/file.apk \
+     https://forgejo.example.com/api/packages/testuser/alpine/v3.17/main
+```
+
+If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password.
+You cannot publish a file with the same name twice to a package. You must delete the existing package file first.
+
+The server responds with the following HTTP Status codes.
+
+| HTTP Status Code  | Meaning                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------ |
+| `201 Created`     | The package has been published.                                                      |
+| `400 Bad Request` | The package name, version, branch, repository or architecture are invalid.           |
+| `409 Conflict`    | A package file with the same combination of parameters exist already in the package. |
+
+## Delete a package
+
+To delete an Alpine package perform a HTTP `DELETE` operation. This will delete the package version too if there is no file left.
+
+```
+DELETE https://forgejo.example.com/api/packages/{owner}/alpine/{branch}/{repository}/{architecture}/{filename}
+```
+
+| Parameter      | Description               |
+| -------------- | ------------------------- |
+| `owner`        | The owner of the package. |
+| `branch`       | The branch to use.        |
+| `repository`   | The repository to use.    |
+| `architecture` | The package architecture. |
+| `filename`     | The file to delete.       |
+
+Example request using HTTP Basic authentication:
+
+```shell
+curl --user your_username:your_token_or_password -X DELETE \
+     https://forgejo.example.com/api/packages/testuser/alpine/v3.17/main/test-package-1.0.0.apk
+```
+
+The server responds with the following HTTP Status codes.
+
+| HTTP Status Code | Meaning                            |
+| ---------------- | ---------------------------------- |
+| `204 No Content` | Success                            |
+| `404 Not Found`  | The package or file was not found. |
+
+## Install a package
+
+To install a package from the Alpine registry, execute the following commands:
+
+```shell
+# use latest version
+apk add {package_name}
+# use specific version
+apk add {package_name}={package_version}
+```

user/packages/cargo.md

@@ -1,8 +1,8 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'Cargo Packages Repository'
+title: 'Cargo Package Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/cargo.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/cargo.en-us.md'
 ---
 
 Publish [Cargo](https://doc.rust-lang.org/stable/cargo/) packages for your user or organization.
@@ -11,7 +11,7 @@ Publish [Cargo](https://doc.rust-lang.org/stable/cargo/) packages for your user
 
 To work with the Cargo package registry, you need [Rust and Cargo](https://www.rust-lang.org/tools/install).
 
-Cargo stores informations about the available packages in a package index stored in a git repository.
+Cargo stores information about the available packages in a package index stored in a git repository.
 This repository is needed to work with the registry.
 The following section describes how to create it.
 

user/packages/chef.md

@@ -1,8 +1,8 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'Chef Packages Repository'
+title: 'Chef Package Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/chef.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/chef.en-us.md'
 ---
 
 Publish [Chef](https://chef.io/) cookbooks for your user or organization.

user/packages/composer.md

@@ -1,8 +1,8 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'Composer Packages Repository'
+title: 'Composer Package Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/composer.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/composer.en-us.md'
 ---
 
 Publish [Composer](https://getcomposer.org/) packages for your user or organization.

user/packages/conan.md

@@ -1,8 +1,8 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'Conan Packages Repository'
+title: 'Conan Package Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/conan.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/conan.en-us.md'
 ---
 
 Publish [Conan](https://conan.io/) packages for your user or organization.

user/packages/conda.md

@@ -1,8 +1,8 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'Conda Packages Repository'
+title: 'Conda Package Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/conda.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/conda.en-us.md'
 ---
 
 Publish [Conda](https://docs.conda.io/en/latest/) packages for your user or organization.

user/packages/container.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Container Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/container.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/container.en-us.md'
 ---
 
 Publish [Open Container Initiative](https://opencontainers.org/) compliant images for your user or organization.

user/packages/cran.md

@@ -0,0 +1,80 @@
+---
+layout: '~/layouts/Markdown.astro'
+title: 'CRAN Package Registry'
+license: 'Apache-2.0'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/cran.en-us.md'
+---
+
+Publish [R](https://www.r-project.org/) packages to a [CRAN](https://cran.r-project.org/)-like registry for your user or organization.
+
+## Requirements
+
+To work with the CRAN package registry, you need to install [R](https://cran.r-project.org/).
+
+## Configuring the package registry
+
+To register the package registry you need to add it to `Rprofile.site`, either on the system-level, user-level (`~/.Rprofile`) or project-level:
+
+```
+options("repos" = c(getOption("repos"), c(forgejo="https://forgejo.example.com/api/packages/{owner}/cran")))
+```
+
+| Parameter | Description               |
+| --------- | ------------------------- |
+| `owner`   | The owner of the package. |
+
+If you need to provide credentials, you may embed them as part of the url (`https://user:password@forgejo.example.com/...`).
+
+## Publish a package
+
+To publish a R package, perform a HTTP `PUT` operation with the package content in the request body.
+
+Source packages:
+
+```
+PUT https://forgejo.example.com/api/packages/{owner}/cran/src
+```
+
+| Parameter | Description               |
+| --------- | ------------------------- |
+| `owner`   | The owner of the package. |
+
+Binary packages:
+
+```
+PUT https://forgejo.example.com/api/packages/{owner}/cran/bin?platform={platform}&rversion={rversion}
+```
+
+| Parameter  | Description                  |
+| ---------- | ---------------------------- |
+| `owner`    | The owner of the package.    |
+| `platform` | The name of the platform.    |
+| `rversion` | The R version of the binary. |
+
+For example:
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/package.zip \
+     https://forgejo.example.com/api/packages/testuser/cran/bin?platform=windows&rversion=4.2
+```
+
+You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
+
+## Install a package
+
+To install a R package from the package registry, execute the following command:
+
+```shell
+install.packages("{package_name}")
+```
+
+| Parameter      | Description       |
+| -------------- | ----------------- |
+| `package_name` | The package name. |
+
+For example:
+
+```shell
+install.packages("testpackage")
+```

user/packages/debian.md

@@ -0,0 +1,121 @@
+---
+layout: '~/layouts/Markdown.astro'
+title: 'Debian Package Registry'
+license: 'Apache-2.0'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/debian.en-us.md'
+---
+
+Publish [Debian](https://www.debian.org/distrib/packages) packages for your user or organization.
+
+## Requirements
+
+To work with the Debian registry, you need to use a HTTP client like `curl` to upload and a package manager like `apt` to consume packages.
+
+The following examples use `apt`.
+
+## Configuring the package registry
+
+To register the Debian registry add the url to the list of known apt sources:
+
+```shell
+echo "deb https://forgejo.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/forgejo.list
+```
+
+| Placeholder    | Description               |
+| -------------- | ------------------------- |
+| `owner`        | The owner of the package. |
+| `distribution` | The distribution to use.  |
+| `component`    | The component to use.     |
+
+If the registry is private, provide credentials in the url. You can use a password or a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}):
+
+```shell
+echo "deb https://{username}:{your_password_or_token}@forgejo.example.com/api/packages/{owner}/debian {distribution} {component}" | sudo tee -a /etc/apt/sources.list.d/forgejo.list
+```
+
+The Debian registry files are signed with a PGP key which must be known to apt:
+
+```shell
+sudo curl https://forgejo.example.com/api/packages/{owner}/debian/repository.key -o /etc/apt/trusted.gpg.d/forgejo-{owner}.asc
+```
+
+Afterwards update the local package index:
+
+```shell
+apt update
+```
+
+## Publish a package
+
+To publish a Debian package (`*.deb`), perform a HTTP `PUT` operation with the package content in the request body.
+
+```
+PUT https://forgejo.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/upload
+```
+
+| Parameter      | Description                                                            |
+| -------------- | ---------------------------------------------------------------------- |
+| `owner`        | The owner of the package.                                              |
+| `distribution` | The distribution may match the release name of the OS, ex: `bionic`.   |
+| `component`    | The component can be used to group packages or just `main` or similar. |
+
+Example request using HTTP Basic authentication:
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/file.deb \
+     https://forgejo.example.com/api/packages/testuser/debian/pool/bionic/main/upload
+```
+
+If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/development/api-usage.en-us.md#authentication" >}}) instead of the password.
+You cannot publish a file with the same name twice to a package. You must delete the existing package version first.
+
+The server responds with the following HTTP Status codes.
+
+| HTTP Status Code  | Meaning                                                                         |
+| ----------------- | ------------------------------------------------------------------------------- |
+| `201 Created`     | The package has been published.                                                 |
+| `400 Bad Request` | The package name, version, distribution, component or architecture are invalid. |
+| `409 Conflict`    | A package file with the same combination of parameters exists already.          |
+
+## Delete a package
+
+To delete a Debian package perform a HTTP `DELETE` operation. This will delete the package version too if there is no file left.
+
+```
+DELETE https://forgejo.example.com/api/packages/{owner}/debian/pool/{distribution}/{component}/{package_name}/{package_version}/{architecture}
+```
+
+| Parameter         | Description               |
+| ----------------- | ------------------------- |
+| `owner`           | The owner of the package. |
+| `package_name`    | The package name.         |
+| `package_version` | The package version.      |
+| `distribution`    | The package distribution. |
+| `component`       | The package component.    |
+| `architecture`    | The package architecture. |
+
+Example request using HTTP Basic authentication:
+
+```shell
+curl --user your_username:your_token_or_password -X DELETE \
+     https://forgejo.example.com/api/packages/testuser/debian/pools/bionic/main/test-package/1.0.0/amd64
+```
+
+The server responds with the following HTTP Status codes.
+
+| HTTP Status Code | Meaning                            |
+| ---------------- | ---------------------------------- |
+| `204 No Content` | Success                            |
+| `404 Not Found`  | The package or file was not found. |
+
+## Install a package
+
+To install a package from the Debian registry, execute the following commands:
+
+```shell
+# use latest version
+apt install {package_name}
+# use specific version
+apt install {package_name}={package_version}
+```

user/packages/generic.md

@@ -1,8 +1,8 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'Generic Packages Repository'
+title: 'Generic Package Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/generic.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/generic.en-us.md'
 ---
 
 Publish generic files, like release binaries or other output, for your user or organization.
@@ -37,7 +37,7 @@ curl --user your_username:your_password_or_token \
 
 If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) instead of the password.
 
-The server reponds with the following HTTP Status codes.
+The server responds with the following HTTP Status codes.
 
 | HTTP Status Code  | Meaning                                                       |
 | ----------------- | ------------------------------------------------------------- |
@@ -69,7 +69,7 @@ curl --user your_username:your_token_or_password \
      https://forgejo.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
 ```
 
-The server reponds with the following HTTP Status codes.
+The server responds with the following HTTP Status codes.
 
 | HTTP Status Code | Meaning                            |
 | ---------------- | ---------------------------------- |
@@ -97,7 +97,7 @@ curl --user your_username:your_token_or_password -X DELETE \
      https://forgejo.example.com/api/packages/testuser/generic/test_package/1.0.0
 ```
 
-The server reponds with the following HTTP Status codes.
+The server responds with the following HTTP Status codes.
 
 | HTTP Status Code | Meaning                    |
 | ---------------- | -------------------------- |
@@ -126,7 +126,7 @@ curl --user your_username:your_token_or_password -X DELETE \
      https://forgejo.example.com/api/packages/testuser/generic/test_package/1.0.0/file.bin
 ```
 
-The server reponds with the following HTTP Status codes.
+The server responds with the following HTTP Status codes.
 
 | HTTP Status Code | Meaning                            |
 | ---------------- | ---------------------------------- |

user/packages/go.md

@@ -0,0 +1,63 @@
+---
+layout: '~/layouts/Markdown.astro'
+title: 'Go Package Registry'
+license: 'Apache-2.0'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/go.en-us.md'
+---
+
+Publish Go packages for your user or organization.
+
+## Publish a package
+
+To publish a Go package perform a HTTP `PUT` operation with the package content in the request body.
+You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
+The package must follow the [documented structure](https://go.dev/ref/mod#zip-files).
+
+```
+PUT https://forgejo.example.com/api/packages/{owner}/go/upload
+```
+
+| Parameter | Description               |
+| --------- | ------------------------- |
+| `owner`   | The owner of the package. |
+
+To authenticate to the package registry, you need to provide custom HTTP headers or use HTTP Basic authentication:
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/file.zip \
+     https://forgejo.example.com/api/packages/testuser/go/upload
+```
+
+If you are using 2FA or OAuth use a personal access token instead of the password.
+
+The server responds with the following HTTP Status codes.
+
+| HTTP Status Code  | Meaning                                     |
+| ----------------- | ------------------------------------------- |
+| `201 Created`     | The package has been published.             |
+| `400 Bad Request` | The package is invalid.                     |
+| `409 Conflict`    | A package with the same name exist already. |
+
+## Install a package
+
+To install a Go package instruct Go to use the package registry as proxy:
+
+```shell
+# use latest version
+GOPROXY=https://forgejo.example.com/api/packages/{owner}/go go install {package_name}
+# or
+GOPROXY=https://forgejo.example.com/api/packages/{owner}/go go install {package_name}@latest
+# use specific version
+GOPROXY=https://forgejo.example.com/api/packages/{owner}/go go install {package_name}@{package_version}
+```
+
+| Parameter         | Description               |
+| ----------------- | ------------------------- |
+| `owner`           | The owner of the package. |
+| `package_name`    | The package name.         |
+| `package_version` | The package version.      |
+
+If the owner of the packages is private you need to [provide credentials](https://go.dev/ref/mod#private-module-proxy-auth).
+
+More information about the `GOPROXY` environment variable and how to protect against data leaks can be found in [the documentation](https://go.dev/ref/mod#private-modules).

user/packages/helm.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Helm Chart Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/helm.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/helm.en-us.md'
 ---
 
 Publish [Helm](https://helm.sh/) charts for your user or organization.

user/packages/index.md

@@ -9,19 +9,24 @@ The following package managers are currently supported:
 
 | Name                   | Language   | Package client             |
 | ---------------------- | ---------- | -------------------------- |
+| [Alpine](alpine)       | -          | `apk`                      |
 | [Cargo](cargo)         | Rust       | `cargo`                    |
 | [Chef](chef)           | -          | `knife`                    |
 | [Composer](composer)   | PHP        | `composer`                 |
 | [Conan](conan)         | C++        | `conan`                    |
 | [Conda](conda)         | -          | `conda`                    |
 | [Container](container) | -          | any OCI compliant client   |
+| [CRAN](cran)           | R          |                            |
+| [Debian](debian)       | -          | `apt`                      |
 | [Generic](generic)     | -          | any HTTP client            |
+| [Go](go)               | Go         | `go`                       |
 | [Helm](helm)           | -          | any HTTP client, `cm-push` |
 | [Maven](maven)         | Java       | `mvn`, `gradle`            |
 | [npm](npm)             | JavaScript | `npm`, `yarn`, `pnpm`      |
 | [NuGet](nuget)         | .NET       | `nuget`                    |
 | [Pub](pub)             | Dart       | `dart`, `flutter`          |
 | [PyPI](pypi)           | Python     | `pip`, `twine`             |
+| [RPM](rpm)             | -          | `yum`, `dnf`               |
 | [RubyGems](rubygems)   | Ruby       | `gem`, `Bundler`           |
 | [Swift](swift)         | Swift      | `swift`                    |
 | [Vagrant](vagrant)     | -          | `vagrant`                  |

user/packages/maven.md

@@ -1,8 +1,8 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'Maven Packages Repository'
+title: 'Maven Package Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/maven.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/maven.en-us.md'
 ---
 
 Publish [Maven](https://maven.apache.org) packages for your user or organization.

user/packages/npm.md

@@ -1,8 +1,8 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'npm Packages Repository'
+title: 'npm Package Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/npm.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/npm.en-us.md'
 ---
 
 Publish [npm](https://www.npmjs.com/) packages for your user or organization.

user/packages/nuget.md

@@ -1,8 +1,8 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'NuGet Packages Repository'
+title: 'NuGet Package Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/nuget.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/nuget.en-us.md'
 ---
 
 Publish [NuGet](https://www.nuget.org/) packages for your user or organization. The package registry supports the V2 and V3 API protocol and you can work with [NuGet Symbol Packages](https://docs.microsoft.com/en-us/nuget/create-packages/symbol-packages-snupkg) too.

user/packages/pub.md

@@ -1,8 +1,8 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'Pub Packages Repository'
+title: 'Pub Package Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/pub.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/pub.en-us.md'
 ---
 
 Publish [Pub](https://dart.dev/guides/packages) packages for your user or organization.

user/packages/pypi.md

@@ -1,8 +1,8 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'PyPI Packages Repository'
+title: 'PyPI Package Registry'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/pypi.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/pypi.en-us.md'
 ---
 
 Publish [PyPI](https://pypi.org/) packages for your user or organization.

user/packages/rpm.md

@@ -0,0 +1,105 @@
+---
+layout: '~/layouts/Markdown.astro'
+title: 'RPM Package Registry'
+license: 'Apache-2.0'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/rpm.en-us.md'
+---
+
+Publish [RPM](https://rpm.org/) packages for your user or organization.
+
+## Requirements
+
+To work with the RPM registry, you need to use a package manager like `yum` or `dnf` to consume packages.
+
+The following examples use `dnf`.
+
+## Configuring the package registry
+
+To register the RPM registry add the url to the list of known apt sources:
+
+```shell
+dnf config-manager --add-repo https://forgejo.example.com/api/packages/{owner}/rpm.repo
+```
+
+| Placeholder | Description               |
+| ----------- | ------------------------- |
+| `owner`     | The owner of the package. |
+
+If the registry is private, provide credentials in the url. You can use a password or a personal access token:
+
+```shell
+dnf config-manager --add-repo https://{username}:{your_password_or_token}@forgejo.example.com/api/packages/{owner}/rpm.repo
+```
+
+You have to add the credentials to the urls in the `rpm.repo` file in `/etc/yum.repos.d` too.
+
+## Publish a package
+
+To publish a RPM package (`*.rpm`), perform a HTTP PUT operation with the package content in the request body.
+
+```
+PUT https://forgejo.example.com/api/packages/{owner}/rpm/upload
+```
+
+| Parameter | Description               |
+| --------- | ------------------------- |
+| `owner`   | The owner of the package. |
+
+Example request using HTTP Basic authentication:
+
+```shell
+curl --user your_username:your_password_or_token \
+     --upload-file path/to/file.rpm \
+     https://forgejo.example.com/api/packages/testuser/rpm/upload
+```
+
+If you are using 2FA or OAuth use a personal access token instead of the password.
+You cannot publish a file with the same name twice to a package. You must delete the existing package version first.
+
+The server responds with the following HTTP Status codes.
+
+| HTTP Status Code  | Meaning                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------ |
+| `201 Created`     | The package has been published.                                                      |
+| `400 Bad Request` | The package is invalid.                                                              |
+| `409 Conflict`    | A package file with the same combination of parameters exist already in the package. |
+
+## Delete a package
+
+To delete a Debian package perform a HTTP DELETE operation. This will delete the package version too if there is no file left.
+
+```
+DELETE https://forgejo.example.com/api/packages/{owner}/rpm/{package_name}/{package_version}/{architecture}
+```
+
+| Parameter         | Description               |
+| ----------------- | ------------------------- |
+| `owner`           | The owner of the package. |
+| `package_name`    | The package name.         |
+| `package_version` | The package version.      |
+| `architecture`    | The package architecture. |
+
+Example request using HTTP Basic authentication:
+
+```shell
+curl --user your_username:your_token_or_password -X DELETE \
+     https://forgejo.example.com/api/packages/testuser/rpm/test-package/1.0.0/x86_64
+```
+
+The server responds with the following HTTP Status codes.
+
+| HTTP Status Code | Meaning                            |
+| ---------------- | ---------------------------------- |
+| `204 No Content` | Success                            |
+| `404 Not Found`  | The package or file was not found. |
+
+## Install a package
+
+To install a package from the RPM registry, execute the following commands:
+
+```shell
+# use latest version
+dnf install {package_name}
+# use specific version
+dnf install {package_name}-{package_version}.{architecture}
+```

user/packages/rubygems.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'RubyGems Packages Repository'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/rubygems.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/rubygems.en-us.md'
 ---
 
 Publish [RubyGems](https://guides.rubygems.org/) packages for your user or organization.

user/packages/storage.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Storage'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/storage.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/storage.en-us.md'
 ---
 
 This document describes the storage of the package registry and how it can be managed.

user/packages/swift.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Swift Packages Repository'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/swift.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/swift.en-us.md'
 ---
 
 # Swift Packages Repository

user/packages/vagrant.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Vagrant Packages Repository'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/packages/vagrant.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/packages/vagrant.en-us.md'
 ---
 
 Publish [Vagrant](https://www.vagrantup.com/) packages for your user or organization.

user/protection.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Branch and tag protection'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/protected-tags.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/protected-tags.en-us.md'
 ---
 
 # Protected branches

user/push-to-create.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Push Options'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/push.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/push.en-us.md'
 ---
 
 # Push To Create

user/repo-permissions.md

@@ -5,7 +5,7 @@ license: 'CC-BY-SA-4.0'
 origin_url: 'https://codeberg.org/Codeberg/Documentation/src/commit/95574213ea1b57f207f60a12557ffbfc349ee274/content/collaborating/repo-permissions.md'
 ---
 
-<!-- See also  https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/permissions.en-us.md -->
+<!-- See also  https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/permissions.en-us.md -->
 
 When you invite collaborators to join your repository or when you create teams for your organization, you have to decide what each collaborator/team is allowed to do.
 

user/webhooks.md

@@ -2,7 +2,7 @@
 layout: '~/layouts/Markdown.astro'
 title: 'Webhooks'
 license: 'Apache-2.0'
-origin_url: 'https://github.com/go-gitea/gitea/blob/ad03c6e0a36033c6f59262d8cfd6416ae3cc93d6/docs/content/doc/usage/webhooks.en-us.md'
+origin_url: 'https://github.com/go-gitea/gitea/blob/62ac3251fa545d32bdfc9ff824106b97ec63edbb/docs/content/doc/usage/webhooks.en-us.md'
 ---
 
 Forgejo supports webhooks for repository events. This can be configured in the settings