foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-28 18:42:51 -05:00
Code Issues Activity

Fix licensing problems

Browse source
This commit is contained in:
crystal 2023-03-02 23:44:11 -07:00
parent bb6b387c3c
commit 06b2ad5a16
24 changed files with 613 additions and 385 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

202
v1.19/admin/LICENSE Normal file
View file

@ -0,0 +1,202 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

1
v1.19/admin/command-line.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Command Line'
license: 'Apache-2.0'
---
## Usage

55
v1.19/admin/config-cheat-sheet.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Configuration Cheat Sheet'
license: 'Apache-2.0'
---
This is a cheat sheet for the Forgejo configuration file. It contains most of the settings
@ -33,21 +34,21 @@ reported as part of the default configuration when running `forgejo --help` or o
- A built-in value set at build time (see building from source)
- Otherwise it defaults to the directory of the _`AppPath`_
- If any of the above are relative paths then they are made absolute against the
the directory of the _`AppPath`_
the directory of the _`AppPath`_
- _`CustomPath`_: This is the base directory for custom templates and other options.
It is determined by using the first set thing in the following hierarchy:
It is determined by using the first set thing in the following hierarchy:
- The `--custom-path` flag passed to the binary
- The environment variable `$FORGEJO_CUSTOM`
- A built-in value set at build time (see building from source)
- Otherwise it defaults to _`AppWorkPath`_`/custom`
- If any of the above are relative paths then they are made absolute against the
the directory of the _`AppWorkPath`_
the directory of the _`AppWorkPath`_
- _`CustomConf`_: This is the path to the `app.ini` file.
- The `--config` flag passed to the binary
- A built-in value set at build time (see building from source)
- Otherwise it defaults to _`CustomPath`_`/conf/app.ini`
- If any of the above are relative paths then they are made absolute against the
the directory of the _`CustomPath`_
the directory of the _`CustomPath`_
In addition there is _`StaticRootPath`_ which can be set as a built-in at build time, but will otherwise default to _`AppWorkPath`_
@ -272,7 +273,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `PROXY_PROTOCOL_HEADER_TIMEOUT`: **5s**: Timeout to wait for PROXY protocol header (set to 0 to have no timeout)
- `PROXY_PROTOCOL_ACCEPT_UNKNOWN`: **false**: Accept PROXY protocol headers with Unknown type.
- `DOMAIN`: **localhost**: Domain name of this server.
- `ROOT_URL`: **%(PROTOCOL)s://%(DOMAIN)s:%(HTTP\_PORT)s/**:
- `ROOT_URL`: **%(PROTOCOL)s://%(DOMAIN)s:%(HTTP_PORT)s/**:
Overwrite the automatically generated public URL.
This is useful if the internal and the external URL don't match (e.g. in Docker).
- `STATIC_URL_PREFIX`: **\<empty\>**:
@ -314,7 +315,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `SSH_DOMAIN`: **%(DOMAIN)s**: Domain name of this server, used for displayed clone URL.
- `SSH_PORT`: **22**: SSH port displayed in clone URL.
- `SSH_LISTEN_HOST`: **0.0.0.0**: Listen address for the built-in SSH server.
- `SSH_LISTEN_PORT`: **%(SSH\_PORT)s**: Port for the built-in SSH server.
- `SSH_LISTEN_PORT`: **%(SSH_PORT)s**: Port for the built-in SSH server.
- `SSH_ROOT_PATH`: **~/.ssh**: Root path of SSH directory.
- `SSH_CREATE_AUTHORIZED_KEYS_FILE`: **true**: Forgejo will create a authorized_keys file by default when it is not using the internal ssh server. If you intend to use the AuthorizedKeysCommand functionality then you should turn this off.
- `SSH_AUTHORIZED_KEYS_BACKUP`: **true**: Enable SSH Authorized Key Backup when rewriting all keys, default is true.
@ -443,9 +444,9 @@ relation to port exhaustion.
## Indexer (`indexer`)
- `ISSUE_INDEXER_TYPE`: **bleve**: Issue indexer type, currently supported: `bleve`, `db` or `elasticsearch`.
- `ISSUE_INDEXER_CONN_STR`: ****: Issue indexer connection string, available when ISSUE_INDEXER_TYPE is elasticsearch. i.e. http://elastic:changeme@localhost:9200
- `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`_.
- `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`.
@ -455,7 +456,7 @@ relation to port exhaustion.
- `REPO_INDEXER_ENABLED`: **false**: Enables code search (uses a lot of disk space, about 6 times more than the repository size).
- `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
- `REPO_INDEXER_CONN_STR`: \*\*\*\*: Code indexer connection string, available when `REPO_INDEXER_TYPE` is elasticsearch. i.e. http://elastic:changeme@localhost:9200
- `REPO_INDEXER_NAME`: **gitea_codes**: Code indexer name, available when `REPO_INDEXER_TYPE` is elasticsearch
- `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.
@ -474,8 +475,8 @@ Configuration at `[queue]` will set defaults for queues with overrides for indiv
- `LENGTH`: **20**: 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`
- `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
- `QUEUE_NAME`: **\_queue**: The suffix for default redis and disk queue name. Individual queues will default to **`name`**`QUEUE_NAME` but can be overridden in the specific `queue.name` section.
- `SET_NAME`: **\_unique**: The suffix that will be added to the default redis and disk queue `set` name for unique queues. Individual queues will default to
**`name`**`QUEUE_NAME`_`SET_NAME`_ but can be overridden in the specific `queue.name` section.
- `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
@ -529,8 +530,8 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
- `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.
- `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
- `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
information.
- `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: Header name for reverse proxy
authentication.
@ -576,7 +577,7 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
- lower - use one or more lower latin characters
- upper - use one or more upper latin characters
- digit - use one or more digits
- spec - use one or more special characters as ``!"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~``
- spec - use one or more special characters as `` !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~ ``
- off - do not check password complexity
- `PASSWORD_CHECK_PWN`: **false**: Check [HaveIBeenPwned](https://haveibeenpwned.com/Passwords) to see if a password has been exposed.
- `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: Cache successful token hashes. API tokens are stored in the DB as pbkdf2 hashes however, this means that there is a potentially significant hashing load when there are multiple API operations. This cache will store the successfully hashed tokens in a LRU cache as a balance between performance and security.
@ -591,7 +592,7 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
## OpenID (`openid`)
- `ENABLE_OPENID_SIGNIN`: **false**: Allow authentication in via OpenID.
- `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION**: Allow registering via OpenID.
- `ENABLE_OPENID_SIGNUP`: **! DISABLE_REGISTRATION**: Allow registering via OpenID.
- `WHITELISTED_URIS`: **\<empty\>**: If non-empty, list of POSIX regex patterns matching
OpenID URI's to permit.
- `BLACKLISTED_URIS`: **\<empty\>**: If non-empty, list of POSIX regex patterns matching
@ -599,7 +600,7 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
## OAuth2 Client (`oauth2_client`)
- `REGISTER_EMAIL_CONFIRM`: _[service]_ **REGISTER\_EMAIL\_CONFIRM**: Set this to enable or disable email confirmation of OAuth2 auto-registration. (Overwrites the REGISTER\_EMAIL\_CONFIRM setting of the `[service]` section)
- `REGISTER_EMAIL_CONFIRM`: _[service]_ **REGISTER_EMAIL_CONFIRM**: Set this to enable or disable email confirmation of OAuth2 auto-registration. (Overwrites the REGISTER_EMAIL_CONFIRM setting of the `[service]` section)
- `OPENID_CONNECT_SCOPES`: **\<empty\>**: List of additional openid connect scopes. (`openid` is implicitly added)
- `ENABLE_AUTO_REGISTRATION`: **false**: Automatically create user accounts for new oauth2 users.
- `USERNAME`: **nickname**: The source of the username for new oauth2 accounts:
@ -667,7 +668,7 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
- `EMAIL_DOMAIN_WHITELIST`: **\<empty\>**: If non-empty, list of domain names that can only be used to register
on this instance.
- `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_REGISTRATION_BUTTON`: **! DISABLE_REGISTRATION**: Show Registration Button
- `SHOW_MILESTONES_DASHBOARD_PAGE`: **true** Enable this to show the milestones dashboard page - a view of all the user's milestones
- `AUTO_WATCH_NEW_REPOS`: **true**: Enable this to let all organisation users watch new repos when they are created
- `AUTO_WATCH_ON_CHANGES`: **false**: Enable this to make users watch a repository after their first commit to it
@ -711,7 +712,7 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
- `SKIP_TLS_VERIFY`: **false**: Allow insecure certification.
- `PAGING_NUM`: **10**: Number of webhook history events that are shown in one page.
- `PROXY_URL`: **\<empty\>**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting.
- `PROXY_HOSTS`: **\<empty\>`**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts. If not given, will use global proxy setting.
- `PROXY_HOSTS`: **\<empty\>`**: Comma separated list of host names requiring proxy. Glob patterns (\*) are accepted; use \*\* to match all hosts. If not given, will use global proxy setting.
## Mailer (`mailer`)
@ -782,7 +783,7 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
- `PROVIDER`: **memory**: Session engine provider \[memory, file, redis, db, mysql, couchbase, memcache, postgres\]. Setting `db` will reuse the configuration in `[database]`
- `PROVIDER_CONFIG`: **data/sessions**: For file, the root path; for db, empty (database config will be used); for others, the connection string. Relative paths will be made absolute against _`AppWorkPath`_.
- `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.
- `COOKIE_NAME`: **i_like_gitea**: The name of the cookie used for the session ID.
- `GC_INTERVAL_TIME`: **86400**: GC interval in seconds.
- `SESSION_LIFE_TIME`: **86400**: Session life time in seconds, default is 86400 (1 day)
- `DOMAIN`: **\<empty\>**: Sets the cookie Domain
@ -1124,11 +1125,11 @@ IS_INPUT_FILE = false
```
- ENABLED: **false** Enable markup support; set to **true** to enable this renderer.
- NEED\_POSTPROCESS: **true** set to **true** to replace links / sha1 and etc.
- FILE\_EXTENSIONS: **\<empty\>** List of file extensions that should be rendered by an external
- NEED_POSTPROCESS: **true** set to **true** to replace links / sha1 and etc.
- FILE_EXTENSIONS: **\<empty\>** List of file extensions that should be rendered by an external
command. Multiple extensions needs a comma as splitter.
- RENDER\_COMMAND: External command to render all matching extensions.
- IS\_INPUT\_FILE: **false** Input is not a standard input but a file param followed `RENDER_COMMAND`.
- RENDER_COMMAND: External command to render all matching extensions.
- IS_INPUT_FILE: **false** Input is not a standard input but a file param followed `RENDER_COMMAND`.
- RENDER_CONTENT_MODE: **sanitized** How the content will be rendered.
- sanitized: Sanitize the content and render it inside current page, default to only allow a few HTML tags and attributes. Customized sanitizer rules can be defined in `[markup.sanitizer.*]`.
- no-sanitizer: Disable the sanitizer and render the content inside current page. It's **insecure** and may lead to XSS attack if the content contains malicious code.
@ -1165,8 +1166,8 @@ If the rule is defined above the renderer ini section or the name does not match
- `file_extension e.g. .toml`: **language e.g. ini**. File extension to language mapping overrides.
- Forgejo will highlight files using the `linguist-language` or `gitlab-language` attribute from the `.gitattributes` file
if available. If this is not set or the language is unavailable, the file extension will be looked up
in this mapping or the filetype using heuristics.
if available. If this is not set or the language is unavailable, the file extension will be looked up
in this mapping or the filetype using heuristics.
## Time (`time`)
@ -1196,7 +1197,7 @@ Task queue configuration has been moved to `queue.task`. However, the below conf
- `SHARE_USER_STATISTICS`: **true**: Enable/Disable user statistics for nodeinfo if federation is enabled
- `MAX_SIZE`: **4**: Maximum federation request and response size (MB)
WARNING: Changing the settings below can break federation.
WARNING: Changing the settings below can break federation.
- `ALGORITHMS`: **rsa-sha256, rsa-sha512, ed25519**: HTTP signature algorithms
- `DIGEST_ALGORITHM`: **SHA-256**: HTTP signature digest algorithm
@ -1304,7 +1305,7 @@ is `data/repo-archive` and the default of `MINIO_BASE_PATH` is `repo-archive/`.
- `PROXY_ENABLED`: **false**: Enable the proxy if true, all requests to external via HTTP will be affected, if false, no proxy will be used even environment http_proxy/https_proxy
- `PROXY_URL`: **\<empty\>**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy
- `PROXY_HOSTS`: **\<empty\>**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts.
- `PROXY_HOSTS`: **\<empty\>**: Comma separated list of host names requiring proxy. Glob patterns (\*) are accepted; use \*\* to match all hosts.
i.e.

3
v1.19/admin/email-setup.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Email setup'
license: 'Apache-2.0'
---
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.
@ -49,6 +50,6 @@ Please note: authentication is only supported when the SMTP server communication
- STARTTLS (also known as Opportunistic TLS) via port 587. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
- SMTPS connection (SMTP over TLS) via the default port 465. Connection to the server use TLS from the beginning.
- Forced SMTPS connection with `IS_TLS_ENABLED=true`. (These are both known as Implicit TLS.)
This is due to protections imposed by the Go internal libraries against STRIPTLS attacks.
This is due to protections imposed by the Go internal libraries against STRIPTLS attacks.
Note that Implicit TLS is recommended by [RFC8314](https://tools.ietf.org/html/rfc8314#section-3) since 2018.

1
v1.19/admin/incoming-email.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Incoming Email'
license: 'Apache-2.0'
---
Forgejo supports the execution of several actions through incoming mails. This page describes how to set this up.

1
v1.19/admin/logging-documentation.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Logging Configuration'
license: 'Apache-2.0'
---
The logging configuration of Forgejo mainly consists of 3 types of components:

7
v1.19/admin/packages/cargo.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Cargo Packages Repository'
license: 'Apache-2.0'
---
Publish [Cargo](https://doc.rust-lang.org/stable/cargo/) packages for your user or organization.
@ -45,7 +46,7 @@ git-fetch-with-cli = true
```
| Parameter | Description |
| --------- | ----------- |
| --------- | ------------------------- |
| `owner` | The owner of the package. |
If the registry is private or you want to publish new packages, you have to configure your credentials.
@ -57,7 +58,7 @@ token = "Bearer {token}"
```
| Parameter | Description |
| --------- | ----------- |
| --------- | ----------------------------------------------------------------------------------------------- |
| `token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) |
## Publish a package
@ -79,7 +80,7 @@ cargo add {package_name}
```
| Parameter | Description |
| -------------- | ----------- |
| -------------- | ----------------- |
| `package_name` | The package name. |
## Supported commands

9
v1.19/admin/packages/chef.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Chef Packages Repository'
license: 'Apache-2.0'
---
Publish [Chef](https://chef.io/) cookbooks for your user or organization.
@ -25,7 +26,7 @@ knife[:supermarket_site] = 'https://forgejo.example.com/api/packages/{owner}/che
```
| Parameter | Description |
| --------- | ----------- |
| --------- | ------------------------- |
| `owner` | The owner of the package. |
## Publish a package
@ -37,7 +38,7 @@ knife supermarket share {package_name}
```
| Parameter | Description |
| -------------- | ----------- |
| -------------- | ----------------- |
| `package_name` | The package name. |
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.
@ -57,7 +58,7 @@ knife supermarket install {package_name} {package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| ----------------- | -------------------- |
| `package_name` | The package name. |
| `package_version` | The package version. |
@ -76,6 +77,6 @@ knife supermarket unshare {package_name}/versions/{package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| ----------------- | -------------------- |
| `package_name` | The package name. |
| `package_version` | The package version. |

12
v1.19/admin/packages/composer.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Composer Packages Repository'
license: 'Apache-2.0'
---
Publish [Composer](https://getcomposer.org/) packages for your user or organization.
@ -20,7 +21,7 @@ PUT https://forgejo.example.com/api/packages/{owner}/composer
```
| Parameter | Description |
| ---------- | ----------- |
| --------- | ------------------------- |
| `owner` | The owner of the package. |
If the `composer.json` file does not contain a `version` property, you must provide it as a query parameter:
@ -50,7 +51,7 @@ If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/deve
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 and/or version are invalid or a package with the same name and version already exist. |
@ -60,7 +61,8 @@ To register the package registry you need to add it to the Composer `config.json
```json
{
"repositories": [{
"repositories": [
{
"type": "composer",
"url": "https://forgejo.example.com/api/packages/{owner}/composer"
}
@ -82,7 +84,7 @@ To access the package registry using credentials, you must specify them in the `
```
| Parameter | Description |
| ---------- | ----------- |
| ---------- | ------------------------------------------------- |
| `owner` | The owner of the package. |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password or a personal access token. |
@ -102,6 +104,6 @@ composer require {package_name}:{package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| ----------------- | -------------------- |
| `package_name` | The package name. |
| `package_version` | The package version. |

7
v1.19/admin/packages/conan.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Conan Packages Repository'
license: 'Apache-2.0'
---
Publish [Conan](https://conan.io/) packages for your user or organization.
@ -19,7 +20,7 @@ conan user --remote {remote} --password {password} {username}
```
| Parameter | Description |
| -----------| ----------- |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `remote` | The remote name. |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password. 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. |
@ -41,7 +42,7 @@ conan upload --remote={remote} {recipe}
```
| Parameter | Description |
| ----------| ----------- |
| --------- | --------------------- |
| `remote` | The remote name. |
| `recipe` | The recipe to upload. |
@ -62,7 +63,7 @@ conan install --remote={remote} {recipe}
```
| Parameter | Description |
| ----------| ----------- |
| --------- | ----------------------- |
| `remote` | The remote name. |
| `recipe` | The recipe to download. |

7
v1.19/admin/packages/conda.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Conda Packages Repository'
license: 'Apache-2.0'
---
Publish [Conda](https://docs.conda.io/en/latest/) packages for your user or organization.
@ -22,7 +23,7 @@ default_channels:
```
| Placeholder | Description |
| ------------ | ----------- |
| ----------- | ------------------------- |
| `owner` | The owner of the package. |
See the [official documentation](https://conda.io/projects/conda/en/latest/user-guide/configuration/use-condarc.html) for explanations of the individual settings.
@ -38,7 +39,7 @@ PUT https://forgejo.example.com/api/packages/{owner}/conda/{channel}/{filename}
```
| Placeholder | Description |
| ------------ | ----------- |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `owner` | The owner of the package. |
| `channel` | The [channel](https://conda.io/projects/conda/en/latest/user-guide/concepts/channels.html) of the package. (optional) |
| `filename` | The name of the file. |
@ -64,7 +65,7 @@ conda install -c {channel} {package_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| ----------------- | -------------------------------------- |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `channel` | The channel of the package. (optional) |

5
v1.19/admin/packages/container.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Container Registry'
license: 'Apache-2.0'
---
Publish [Open Container Initiative](https://opencontainers.org/) compliant images for your user or organization.
@ -46,7 +47,7 @@ docker push forgejo.example.com/{owner}/{image}:{tag}
```
| Parameter | Description |
| ----------| ----------- |
| --------- | ----------------------- |
| `owner` | The owner of the image. |
| `image` | The name of the image. |
| `tag` | The tag of the image. |
@ -66,7 +67,7 @@ docker pull forgejo.example.com/{owner}/{image}:{tag}
```
| Parameter | Description |
| ----------| ----------- |
| --------- | ----------------------- |
| `owner` | The owner of the image. |
| `image` | The name of the image. |
| `tag` | The tag of the image. |

17
v1.19/admin/packages/generic.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Generic Packages Repository'
license: 'Apache-2.0'
---
Publish generic files, like release binaries or other output, for your user or organization.
@ -19,7 +20,7 @@ PUT https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{pac
```
| Parameter | Description |
| ----------------- | ----------- |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), pluses (`+`), or underscores (`_`). |
| `package_version` | The package version, a non-empty string without trailing or leading whitespaces. |
@ -38,7 +39,7 @@ If you are using 2FA or OAuth use a [personal access token]({{< relref "doc/deve
The server reponds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| ----------------- | ------------------------------------------------------------- |
| `201 Created` | The package has been published. |
| `400 Bad Request` | The package name and/or version and/or file name are invalid. |
| `409 Conflict` | A file with the same name exist already in the package. |
@ -52,7 +53,7 @@ GET https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{pac
```
| Parameter | Description |
| ----------------- | ----------- |
| ----------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version. |
@ -70,7 +71,7 @@ curl --user your_username:your_token_or_password \
The server reponds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| ---------------- | ---------------------------------- |
| `200 OK` | Success |
| `404 Not Found` | The package or file was not found. |
@ -83,7 +84,7 @@ DELETE https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{
```
| Parameter | Description |
| ----------------- | ----------- |
| ----------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version. |
@ -98,7 +99,7 @@ curl --user your_username:your_token_or_password -X DELETE \
The server reponds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| ---------------- | -------------------------- |
| `204 No Content` | Success |
| `404 Not Found` | The package was not found. |
@ -111,7 +112,7 @@ DELETE https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{
```
| Parameter | Description |
| ----------------- | ----------- |
| ----------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version. |
@ -127,6 +128,6 @@ curl --user your_username:your_token_or_password -X DELETE \
The server reponds with the following HTTP Status codes.
| HTTP Status Code | Meaning |
| ----------------- | ------- |
| ---------------- | ---------------------------------- |
| `204 No Content` | Success |
| `404 Not Found` | The package or file was not found. |

5
v1.19/admin/packages/helm.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Helm Chart Registry'
license: 'Apache-2.0'
---
Publish [Helm](https://helm.sh/) charts for your user or organization.
@ -25,7 +26,7 @@ helm cm-push ./{chart_file}.tgz {repo}
```
| Parameter | Description |
| ------------ | ----------- |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password. 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. |
| `repo` | The name for the repository. |
@ -43,7 +44,7 @@ helm install {name} {repo}/{chart}
```
| Parameter | Description |
| ---------- | ----------- |
| ---------- | ------------------------------------------------- |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password or a personal access token. |
| `repo` | The name for the repository. |

5
v1.19/admin/packages/maven.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Maven Packages Repository'
license: 'Apache-2.0'
---
Publish [Maven](https://maven.apache.org) packages for your user or organization.
@ -54,7 +55,7 @@ Afterwards add the following sections to your project `pom.xml` file:
```
| Parameter | Description |
| -------------- | ----------- |
| -------------- | ------------------------------------------------------------------------------------------------ |
| `access_token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). |
| `owner` | The owner of the package. |
@ -73,7 +74,7 @@ mvn deploy:deploy-file -Durl=https://forgejo.example.com/api/packages/{owner}/ma
```
| Parameter | Description |
| -------------- | ----------- |
| --------- | ------------------------- |
| `owner` | The owner of the package. |
You cannot publish a package if a package of the same name and version already exists. You must delete the existing package first.

9
v1.19/admin/packages/npm.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'npm Packages Repository'
license: 'Apache-2.0'
---
Publish [npm](https://www.npmjs.com/) packages for your user or organization.
@ -23,7 +24,7 @@ npm config set -- '//forgejo.example.com/api/packages/{owner}/npm/:_authToken' "
```
| Parameter | Description |
| ------------ | ----------- |
| --------- | ------------------------------------------------------------------------------------------------ |
| `scope` | The scope of the packages. |
| `owner` | The owner of the package. |
| `token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). |
@ -61,7 +62,7 @@ npm unpublish {package_name}[@{package_version}]
```
| Parameter | Description |
| ----------------- | ----------- |
| ----------------- | -------------------- |
| `package_name` | The package name. |
| `package_version` | The package version. |
@ -81,7 +82,7 @@ npm install {package_name}
```
| Parameter | Description |
| -------------- | ----------- |
| -------------- | ----------------- |
| `package_name` | The package name. |
For example:
@ -99,7 +100,7 @@ npm dist-tag add {package_name}@{version} {tag}
```
| Parameter | Description |
| -------------- | ----------- |
| -------------- | --------------------------- |
| `package_name` | The package name. |
| `version` | The version of the package. |
| `tag` | The tag name. |

9
v1.19/admin/packages/nuget.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'NuGet Packages Repository'
license: 'Apache-2.0'
---
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.
@ -20,7 +21,7 @@ dotnet nuget add source --name {source_name} --username {username} --password {p
```
| Parameter | Description |
| ------------- | ----------- |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `source_name` | The desired source name. |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password. 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. |
@ -43,7 +44,7 @@ dotnet nuget push --source {source_name} {package_file}
```
| Parameter | Description |
| -------------- | ----------- |
| -------------- | ---------------------------------- |
| `source_name` | The desired source name. |
| `package_file` | Path to the package `.nupkg` file. |
@ -65,7 +66,7 @@ https://forgejo.example.com/api/packages/{owner}/nuget/symbols
```
| Parameter | Description |
| --------- | ----------- |
| --------- | ---------------------------------- |
| `owner` | The owner of the package registry. |
For example:
@ -83,7 +84,7 @@ dotnet add package --source {source_name} --version {package_version} {package_n
```
| Parameter | Description |
| ----------------- | ----------- |
| ----------------- | ------------------------ |
| `source_name` | The desired source name. |
| `package_name` | The package name. |
| `package_version` | The package version. |

7
v1.19/admin/packages/pub.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Pub Packages Repository'
license: 'Apache-2.0'
---
Publish [Pub](https://dart.dev/guides/packages) packages for your user or organization.
@ -20,7 +21,7 @@ dart pub token add https://forgejo.example.com/api/packages/{owner}/pub
```
| Placeholder | Description |
| ------------ | ----------- |
| ----------- | ------------------------- |
| `owner` | The owner of the package. |
You need to provide your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}).
@ -34,7 +35,7 @@ publish_to: https://forgejo.example.com/api/packages/{owner}/pub
```
| Placeholder | Description |
| ------------ | ----------- |
| ----------- | ------------------------- |
| `owner` | The owner of the package. |
Now you can publish the package by running the following command:
@ -54,7 +55,7 @@ dart pub add {package_name} --hosted-url=https://forgejo.example.com/api/package
```
| Parameter | Description |
| ----------------- | ----------- |
| -------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |

5
v1.19/admin/packages/pypi.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'PyPI Packages Repository'
license: 'Apache-2.0'
---
Publish [PyPI](https://pypi.org/) packages for your user or organization.
@ -24,7 +25,7 @@ password = {password}
```
| Placeholder | Description |
| ------------ | ----------- |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `owner` | The owner of the package. |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password. 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. |
@ -50,7 +51,7 @@ pip install --index-url https://{username}:{password}@forgejo.example.com/api/pa
```
| Parameter | Description |
| ----------------- | ----------- |
| -------------- | ------------------------------------------------- |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password or a personal access token. |
| `owner` | The owner of the package. |

9
v1.19/admin/packages/rubygems.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'RubyGems Packages Repository'
license: 'Apache-2.0'
---
Publish [RubyGems](https://guides.rubygems.org/) packages for your user or organization.
@ -19,7 +20,7 @@ https://forgejo.example.com/api/packages/{owner}/rubygems: Bearer {token}
```
| Parameter | Description |
| ------------- | ----------- |
| --------- | ------------------------------------------------------------------------------------------------ |
| `owner` | The owner of the package. |
| `token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). |
@ -39,7 +40,7 @@ gem push --host {host} {package_file}
```
| Parameter | Description |
| -------------- | ----------- |
| -------------- | -------------------------------- |
| `host` | URL to the package registry. |
| `package_file` | Path to the package `.gem` file. |
@ -66,7 +67,7 @@ end
```
| Parameter | Description |
| ----------------- | ----------- |
| -------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
@ -93,7 +94,7 @@ gem install --host https://forgejo.example.com/api/packages/{owner}/rubygems {pa
```
| Parameter | Description |
| ----------------- | ----------- |
| -------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |

45
v1.19/admin/packages/storage.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Storage'
license: 'Apache-2.0'
---
This document describes the storage of the package registry and how it can be managed.
@ -25,15 +26,15 @@ Package registries can become large over time without cleanup.
It's recommended to delete unnecessary packages and set up cleanup rules to automatically manage the package registry usage.
Every package owner (user or organization) manages the cleanup rules which are applied to their packages.
|Setting|Description|
|-|-|
|Enabled|Turn the cleanup rule on or off.|
|Type|Every rule manages a specific package type.|
|Apply pattern to full package name|If enabled, the patterns below are applied to the full package name (`package/version`). Otherwise only the version (`version`) is used.|
|Keep the most recent|How many versions to *always* keep for each package.|
|Keep versions matching|The regex pattern that determines which versions to keep. An empty pattern keeps no version while `.+` keeps all versions. The container registry will always keep the `latest` version even if not configured.|
|Remove versions older than|Remove only versions older than the selected days.|
|Remove versions matching|The regex pattern that determines which versions to remove. An empty pattern or `.+` leads to the removal of every package if no other setting tells otherwise.|
| Setting | Description |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enabled | Turn the cleanup rule on or off. |
| Type | Every rule manages a specific package type. |
| Apply pattern to full package name | If enabled, the patterns below are applied to the full package name (`package/version`). Otherwise only the version (`version`) is used. |
| Keep the most recent | How many versions to _always_ keep for each package. |
| Keep versions matching | The regex pattern that determines which versions to keep. An empty pattern keeps no version while `.+` keeps all versions. The container registry will always keep the `latest` version even if not configured. |
| Remove versions older than | Remove only versions older than the selected days. |
| Remove versions matching | The regex pattern that determines which versions to remove. An empty pattern or `.+` leads to the removal of every package if no other setting tells otherwise. |
Every cleanup rule can show a preview of the affected packages.
This can be used to check if the cleanup rules is proper configured.
@ -44,15 +45,15 @@ Regex patterns are automatically surrounded with `\A` and `\z` anchors.
Do not include any `\A`, `\z`, `^` or `$` token in the regex patterns as they are not necessary.
The patterns are case-insensitive which matches the behaviour of the package registry in Forgejo.
|Pattern|Description|
|-|-|
|`.*`|Match every possible version.|
|`v.+`|Match versions that start with `v`.|
|`release`|Match only the version `release`.|
|`release.*`|Match versions that are either named or start with `release`.|
|`.+-temp-.+`|Match versions that contain `-temp-`.|
|`v.+\|release`|Match versions that either start with `v` or are named `release`.|
|`package/v.+\|other/release`|Match versions of the package `package` that start with `v` or the version `release` of the package `other`. This needs the setting *Apply pattern to full package name* enabled.|
| Pattern | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.*` | Match every possible version. |
| `v.+` | Match versions that start with `v`. |
| `release` | Match only the version `release`. |
| `release.*` | Match versions that are either named or start with `release`. |
| `.+-temp-.+` | Match versions that contain `-temp-`. |
| `v.+\|release` | Match versions that either start with `v` or are named `release`. |
| `package/v.+\|other/release` | Match versions of the package `package` that start with `v` or the version `release` of the package `other`. This needs the setting _Apply pattern to full package name_ enabled. |
### How the cleanup rules work
@ -62,8 +63,8 @@ The cleanup rule:
1. Collects all packages of the package type for the owners registry.
1. For every package it collects all versions.
1. Excludes from the list the # versions based on the *Keep the most recent* value.
1. Excludes from the list any versions matching the *Keep versions matching* value.
1. Excludes from the list the versions more recent than the *Remove versions older than* value.
1. Excludes from the list any versions not matching the *Remove versions matching* value.
1. Excludes from the list the # versions based on the _Keep the most recent_ value.
1. Excludes from the list any versions matching the _Keep versions matching_ value.
1. Excludes from the list the versions more recent than the _Remove versions older than_ value.
1. Excludes from the list any versions not matching the _Remove versions matching_ value.
1. Deletes the remaining versions.

5
v1.19/admin/packages/vagrant.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Vagrant Packages Repository'
license: 'Apache-2.0'
---
Publish [Vagrant](https://www.vagrantup.com/) packages for your user or organization.
@ -18,7 +19,7 @@ PUT https://forgejo.example.com/api/packages/{owner}/vagrant/{package_name}/{pac
```
| Parameter | Description |
| ----------------- | ----------- |
| ----------------- | -------------------------------------------------------------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version, semver compatible. |
@ -43,7 +44,7 @@ vagrant box add "https://forgejo.example.com/api/packages/{owner}/vagrant/{packa
```
| Parameter | Description |
| -------------- | ----------- |
| -------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |

1
v1.19/admin/reverse-proxy.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Reverse proxy'
license: 'Apache-2.0'
---
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

101
v1.19/admin/upgrade.md
View file

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: "Upgrade guide"
title: 'Upgrade guide'
license: 'Apache-2.0'
---
This guide helps Forgejo admins perform upgrades safely and provides guidance to troubleshoot problems. It covers upgrades from Gitea back to version 1.2.0.
@ -16,85 +17,87 @@ For instance, if everything (SQLite database + repositories etc.) is on a single
However, if Forgejo uses a S3 storage for attachments with a PostgresQL database, stores Git repositories on a remote file system and queues in a Redis server, the only way to ensure a consistent state is to shutdown Forgejo during the backup.
In the simplest case where everything is on a single file system and if the instance is not busy (no mirrors, no users), the backup can be done with:
* `forgejo dump` to collect everything into one zip file
* `psql/mysql/sqlite dump`. Although the zip file created by `forgejo dump` contains a copy of the database it has serious long standing open bugs that may introduce problems when re-injecting the SQL dump in a new database.
- `forgejo dump` to collect everything into one zip file
- `psql/mysql/sqlite dump`. Although the zip file created by `forgejo dump` contains a copy of the database it has serious long standing open bugs that may introduce problems when re-injecting the SQL dump in a new database.
### Verify Forgejo works
It is **critical** to verify that Forgejo works very carefully. Restoring the backup done before the upgrade is easy and does not loose any information. But if a problem is discovered days or weeks after the upgrade, it will not be an option and fixing it on a live Forgejo instance will be much more challenging.
* Run `forgejo doctor --all --log-file /tmp/doctor.log` and make sure it does not report any problem.
* Manually verify via the web interface. Making a checklist of a typical use case is a good way to not miss anything.
* If there is a problem of any kind, increase the log level and take a look at the logs. If you cannot figure out what the problem is, ask for help [in the Forgejo chatroom](https://matrix.to/#/#forgejo-chat:matrix.org) before trying to fix it.
- Run `forgejo doctor --all --log-file /tmp/doctor.log` and make sure it does not report any problem.
- Manually verify via the web interface. Making a checklist of a typical use case is a good way to not miss anything.
- If there is a problem of any kind, increase the log level and take a look at the logs. If you cannot figure out what the problem is, ask for help [in the Forgejo chatroom](https://matrix.to/#/#forgejo-chat:matrix.org) before trying to fix it.
### Preparing the Forgejo upgrade
* Manually analyze (reading the patches to the sources of the template directory) and update the customized CSS / content.
* Do not use `forgejo help` to figure out the location of `CustomPath`, look at the configuration tab of the `Site administration` panel when logged in as an admin.
* `forgejo manager flush-queues`. If it timesout, run it again with a more generous `--timeout` argument. It is important because the queues contain serialized data that is not guaranteed to be backward compatible between versions.
* Go to the `Site administration` panel and pause all queues
- Manually analyze (reading the patches to the sources of the template directory) and update the customized CSS / content.
- Do not use `forgejo help` to figure out the location of `CustomPath`, look at the configuration tab of the `Site administration` panel when logged in as an admin.
- `forgejo manager flush-queues`. If it timesout, run it again with a more generous `--timeout` argument. It is important because the queues contain serialized data that is not guaranteed to be backward compatible between versions.
- Go to the `Site administration` panel and pause all queues
Note: Forgejo requires [docker >= 20.10.6](https://wiki.alpinelinux.org/wiki/Release_Notes_for_Alpine_3.14.0) otherwise mysterious problems will happen (mysterious in the sense that the problem will about something unrelated to the Docker version").
### 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:
* 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
* Upgrade to 1.6.4 and manually verify it runs
* If the upgrade is from a Gitea version greater or equal to 1.6.4 that is not mentioned to be problematic below, upgrade directly to the latest stable Forgejo version, there is no need to upgrade to intermediate versions.
* Verify Forgejo works
- 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:
- 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
- Upgrade to 1.6.4 and manually verify it runs
- If the upgrade is from a Gitea version greater or equal to 1.6.4 that is not mentioned to be problematic below, upgrade directly to the latest stable Forgejo version, there is no need to upgrade to intermediate versions.
- Verify Forgejo works
### Troubleshooting
* Increase the log level with `forgejo manager logging add console -n traceconsole -l TRACE -e '((modules/git)|(services/mirror))'`
* If the upgrade from version x.y to version x.y+2 fails and there is a need to narrow down the problem, try upgrading to the latest minor version of each major version and verify it works. It will show which major version causes the issue and help debug the problem. For instance, if upgrading from Forgejo 1.18.2-0 to Forgejo 1.19.0-0 does not work:
* Upgrade from Forgejo 1.18.2 to Forgejo 1.18.5 (the last minor version of the 1.18 major version) and verify Forgejo works.
* Upgrade to Forgejo 1.19.0-0 (the last minor version of the 1.19 major version) and verify Forgejo works.
- Increase the log level with `forgejo manager logging add console -n traceconsole -l TRACE -e '((modules/git)|(services/mirror))'`
- If the upgrade from version x.y to version x.y+2 fails and there is a need to narrow down the problem, try upgrading to the latest minor version of each major version and verify it works. It will show which major version causes the issue and help debug the problem. For instance, if upgrading from Forgejo 1.18.2-0 to Forgejo 1.19.0-0 does not work:
- Upgrade from Forgejo 1.18.2 to Forgejo 1.18.5 (the last minor version of the 1.18 major version) and verify Forgejo works.
- Upgrade to Forgejo 1.19.0-0 (the last minor version of the 1.19 major version) and verify Forgejo works.
#### Unexpected database version
The database version is stored in the database and can be retrieved with **select * from version**. If the version found in the database does not match what is in the following table, it probably means the instance was installed from the development tree instead of a package and **the database may be in a state that has not been tested for upgrades**.
The database version is stored in the database and can be retrieved with **select \* from version**. If the version found in the database does not match what is in the following table, it probably means the instance was installed from the development tree instead of a package and **the database may be in a state that has not been tested for upgrades**.
| Forgejo version | Date | Database |
| ----------------| ---- | -------- |
|[1.18.5-0](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/RELEASE-NOTES.md#1-18-5-0) | February 2023 | v231 |
| --------------------------------------------------------------------------------------------- | ------------- | -------- |
| [1.18.5-0](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/RELEASE-NOTES.md#1-18-5-0) | February 2023 | v231 |
| Gitea version | Date | Database |
| --------------| ---- | -------- |
|[1.17.4](https://github.com/go-gitea/gitea/releases/tag/v1.17.4) | December 2022 | v224 |
|[1.16.9](https://github.com/go-gitea/gitea/releases/tag/v1.16.9) | July 2022 | v211 |
|[1.15.11](https://github.com/go-gitea/gitea/releases/tag/v1.15.11) | January 2022| v189 |
|[1.14.7](https://github.com/go-gitea/gitea/releases/tag/v1.14.7) | September 2021| v178 |
|[1.13.7](https://github.com/go-gitea/gitea/releases/tag/v1.13.7) | April 2021| v156 *Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L257) incorrectly mention it should be v155.* |
|[1.12.6](https://github.com/go-gitea/gitea/releases/tag/v1.12.6) | November 2020| v141 *Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L224) incorrectly mention it should be v140.* |
|[1.11.8](https://github.com/go-gitea/gitea/releases/tag/v1.11.8) | June 2020| v118 *Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L175) incorrectly mention it should be v117.* |
|[1.10.6](https://github.com/go-gitea/gitea/releases/tag/v1.10.6) | March 2020| v103 *Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L142) incorrectly mention it should be v102.* |
|[1.9.6](https://github.com/go-gitea/gitea/releases/tag/v1.9.6) | November 2019| v89 *Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L111) incorrectly mention it should be v88.* |
| ------------------------------------------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [1.17.4](https://github.com/go-gitea/gitea/releases/tag/v1.17.4) | December 2022 | v224 |
| [1.16.9](https://github.com/go-gitea/gitea/releases/tag/v1.16.9) | July 2022 | v211 |
| [1.15.11](https://github.com/go-gitea/gitea/releases/tag/v1.15.11) | January 2022 | v189 |
| [1.14.7](https://github.com/go-gitea/gitea/releases/tag/v1.14.7) | September 2021 | v178 |
| [1.13.7](https://github.com/go-gitea/gitea/releases/tag/v1.13.7) | April 2021 | v156 _Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L257) incorrectly mention it should be v155._ |
| [1.12.6](https://github.com/go-gitea/gitea/releases/tag/v1.12.6) | November 2020 | v141 _Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L224) incorrectly mention it should be v140._ |
| [1.11.8](https://github.com/go-gitea/gitea/releases/tag/v1.11.8) | June 2020 | v118 _Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L175) incorrectly mention it should be v117._ |
| [1.10.6](https://github.com/go-gitea/gitea/releases/tag/v1.10.6) | March 2020 | v103 _Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L142) incorrectly mention it should be v102._ |
| [1.9.6](https://github.com/go-gitea/gitea/releases/tag/v1.9.6) | November 2019 | v89 _Note that [the comment in the source](https://github.com/go-gitea/gitea/blob/63f6e6c0bd6a5314b76b7598dee77ceee1dde81a/models/migrations/migrations.go#L111) incorrectly mention it should be v88._ |
#### When upgrading from a specific version...
* Any version before [Gitea 1.17](https://github.com/go-gitea/gitea/releases/tag/v1.17.4)
* preserve a custom gitconfig: [episode 1](https://gna.org/blog/1-17-breaking-episode-1/), [episode 2](https://gna.org/blog/1-17-breaking-episode-2/)
* [Gitea 1.13.0](https://blog.gitea.io/2020/12/gitea-1.13.0-is-released/)
* The Webhook shared secret inside the webhook payload has been deprecated and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 please use the secret header that uses an hmac signature to validate the webhook payload.
* Git hooks now default to `off`! ([#13058](https://github.com/go-gitea/gitea/pull/13058))
- Any version before [Gitea 1.17](https://github.com/go-gitea/gitea/releases/tag/v1.17.4)
- preserve a custom gitconfig: [episode 1](https://gna.org/blog/1-17-breaking-episode-1/), [episode 2](https://gna.org/blog/1-17-breaking-episode-2/)
- [Gitea 1.13.0](https://blog.gitea.io/2020/12/gitea-1.13.0-is-released/)
- The Webhook shared secret inside the webhook payload has been deprecated and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 please use the secret header that uses an hmac signature to validate the webhook payload.
- Git hooks now default to `off`! ([#13058](https://github.com/go-gitea/gitea/pull/13058))
In your config, you can check the security section for `DISABLE_GIT_HOOKS`. To enable them again, you must set the setting to `false`.
### Only when upgrading to a specific version
* [1.15.2](https://blog.gitea.io/2021/09/gitea-1.15.2-is-released/)
* Unfortunately following the release of 1.15.1 it has become apparent that there is an issue with upgrading from 1.15.0 to 1.15.1 due to problem with a table constraint that was unexpectedly automatically dropped. Users who upgraded straight from 1.14.x to 1.15.1 are not affected and users who upgraded from 1.15.0 to 1.15.1 can fix the problem using `gitea doctor recreate-table issue_index` or upgrade to 1.15.2.
- [1.15.2](https://blog.gitea.io/2021/09/gitea-1.15.2-is-released/)
* Between [1.13.0](https://blog.gitea.io/2020/12/gitea-1.13.0-is-released/) [1.13.3](https://blog.gitea.io/2021/03/gitea-1.13.3-is-released/)
* Password hashing algorithm default has changed back to pbkdf2 from argon2. ([#14673](https://github.com/go-gitea/gitea/pull/14673))
- Unfortunately following the release of 1.15.1 it has become apparent that there is an issue with upgrading from 1.15.0 to 1.15.1 due to problem with a table constraint that was unexpectedly automatically dropped. Users who upgraded straight from 1.14.x to 1.15.1 are not affected and users who upgraded from 1.15.0 to 1.15.1 can fix the problem using `gitea doctor recreate-table issue_index` or upgrade to 1.15.2.
- Between [1.13.0](https://blog.gitea.io/2020/12/gitea-1.13.0-is-released/) [1.13.3](https://blog.gitea.io/2021/03/gitea-1.13.3-is-released/)
- Password hashing algorithm default has changed back to pbkdf2 from argon2. ([#14673](https://github.com/go-gitea/gitea/pull/14673))
### Unexplained upgrade failures & workarounds
* All versions
* Symptom: [blank / 500 page after login when running SQLite](https://github.com/go-gitea/gitea/issues/18650)
* Workaround: upgrade to [Forgejo 1.18.0-1 or greater](https://codeberg.org/forgejo/forgejo/commit/443675d18072d2a345bc4644d3f52dee42f58b44) and run `gitea doctor --all --fix`
- All versions
- Symptom: [blank / 500 page after login when running SQLite](https://github.com/go-gitea/gitea/issues/18650)
- Workaround: upgrade to [Forgejo 1.18.0-1 or greater](https://codeberg.org/forgejo/forgejo/commit/443675d18072d2a345bc4644d3f52dee42f58b44) and run `gitea doctor --all --fix`
### Versions with known issues
@ -102,6 +105,6 @@ Gogs from before September 2015 migrated to Forgejo v1.18 may have a [dangling `
[From the 1.11.3 release notes](https://blog.gitea.io/2020/03/gitea-1.11.3-and-1.10.6-released/):
* v1.10.0, v1.10.1, v1.10.2, v1.10.3, v1.10.4, v1.11.0, and v1.11.1 **do not use** any of these versions, as a bug in the upgrade process will delete attachments from the releases on your repositories.
* v1.11.2 (now replaced by 1.11.3) was mistakenly compiled with Go 1.14, which Gitea is not currently fully tested with and it’s known to cause [a few issues](https://github.com/go-gitea/gitea/issues/10661).
* v1.10.5 (replaced by 1.10.6 if you need to keep using the 1.10 branch) was incorrectly tagged, and was in fact a snapshot of our development branch (1.12-dev). It was also compiled with Go 1.14.
- v1.10.0, v1.10.1, v1.10.2, v1.10.3, v1.10.4, v1.11.0, and v1.11.1 **do not use** any of these versions, as a bug in the upgrade process will delete attachments from the releases on your repositories.
- v1.11.2 (now replaced by 1.11.3) was mistakenly compiled with Go 1.14, which Gitea is not currently fully tested with and it’s known to cause [a few issues](https://github.com/go-gitea/gitea/issues/10661).
- v1.10.5 (replaced by 1.10.6 if you need to keep using the 1.10 branch) was incorrectly tagged, and was in fact a snapshot of our development branch (1.12-dev). It was also compiled with Go 1.14.