foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-12-24 22:32:43 -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.

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

@ -1,6 +1,7 @@
---
layout: '~/layouts/Markdown.astro'
title: 'Command Line'
license: 'Apache-2.0'
---
## Usage
@ -168,11 +169,11 @@ Admin operations:
- `--allowed-domains`: Leave empty to allow all domains. Separate multiple domains with a comma (',').
- `--skip-local-2fa`: Skip 2FA to log on.
- `--active`: This Authentication Source is Activated.
Remarks:
`--force-smtps`, `--skip-verify`, `--disable-helo`, `--skip-loca-2fs` and `--active` options can be used in form:
Remarks:
`--force-smtps`, `--skip-verify`, `--disable-helo`, `--skip-loca-2fs` and `--active` options can be used in form:
- `--option`, `--option=true` to enable
- `--option=false` to disable
If those options are not specified value would not be changed in `update-smtp` or would use default `false` value in `add-smtp`
If those options are not specified value would not be changed in `update-smtp` or would use default `false` value in `add-smtp`
- Examples:
- `forgejo admin auth add-smtp --name ldap --host smtp.mydomain.org --port 587 --skip-verify --active`
- `update-smtp`:

241
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
@ -15,7 +16,7 @@ accurately recorded in [app.example.ini](https://codeberg.org/forgejo/forgejo/sr
(s/main/\<tag|release\>). Any string in the format `%(X)s` is a feature powered
by [ini](https://github.com/go-ini/ini/#recursive-values), for reading values recursively.
In the default values below, a value in the form `$XYZ` refers to an environment variable. (However, see `environment-to-ini`.) Values in the form _`XxYyZz`_ refer to values listed as part of the default configuration. These notation forms will not work in your own `app.ini` file and are only listed here as documentation.
In the default values below, a value in the form `$XYZ` refers to an environment variable. (However, see `environment-to-ini`.) Values in the form _`XxYyZz`_ refer to values listed as part of the default configuration. These notation forms will not work in your own `app.ini` file and are only listed here as documentation.
Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
@ -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`_
@ -55,40 +56,40 @@ In addition there is _`StaticRootPath`_ which can be set as a built-in at build
- `APP_NAME`: **Forgejo: Beyond coding. We forge.**: Application name, used in the page title.
- `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.
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".
## Repository (`repository`)
- `ROOT`: **%(APP_DATA_PATH)s/gitea-repositories**: Root path for storing all repository data.
A relative path is interpreted as **_`AppWorkPath`_/%(ROOT)s**.
A relative path is interpreted as **_`AppWorkPath`_/%(ROOT)s**.
- `SCRIPT_TYPE`: **bash**: The script type this server supports. Usually this is `bash`,
but some users report that only `sh` is available.
but some users report that only `sh` is available.
- `DETECTED_CHARSETS_ORDER`: **UTF-8, UTF-16BE, UTF-16LE, UTF-32BE, UTF-32LE, ISO-8859, windows-1252, ISO-8859, windows-1250, ISO-8859, ISO-8859, ISO-8859, windows-1253, ISO-8859, windows-1255, ISO-8859, windows-1251, windows-1256, KOI8-R, ISO-8859, windows-1254, Shift_JIS, GB18030, EUC-JP, EUC-KR, Big5, ISO-2022, ISO-2022, ISO-2022, IBM424_rtl, IBM424_ltr, IBM420_rtl, IBM420_ltr**: Tie-break order of detected charsets - if the detected charsets have equal confidence, charsets earlier in the list will be chosen in preference to those later. Adding `defaults` will place the unnamed charsets at that point.
- `ANSI_CHARSET`: **\<empty\>**: Default ANSI charset to override non-UTF-8 charsets to.
- `FORCE_PRIVATE`: **false**: Force every new repository to be private.
- `DEFAULT_PRIVATE`: **last**: Default private when creating a new repository.
\[last, private, public\]
\[last, private, public\]
- `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.
`-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.
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]`.
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.
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.
HTTP protocol.
- `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when
default SSH port is used.
default SSH port is used.
- `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.
- `DEFAULT_CLOSE_ISSUES_VIA_COMMITS_IN_ANY_BRANCH`: **false**: Close an issue if a commit on a non default branch marks it as closed.
- `ENABLE_PUSH_CREATE_USER`: **false**: Allow users to push local repositories to Forgejo and have them automatically created for a user.
- `ENABLE_PUSH_CREATE_ORG`: **false**: Allow users to push local repositories to Forgejo and have them automatically created for an org.
default is not to present. **WARNING**: This maybe harmful to you website if you do not
give it a right value.
- `DEFAULT_CLOSE_ISSUES_VIA_COMMITS_IN_ANY_BRANCH`: **false**: Close an issue if a commit on a non default branch marks it as closed.
- `ENABLE_PUSH_CREATE_USER`: **false**: Allow users to push local repositories to Forgejo and have them automatically created for a user.
- `ENABLE_PUSH_CREATE_ORG`: **false**: Allow users to push local repositories to Forgejo and have them automatically created for an org.
- `DISABLED_REPO_UNITS`: **_empty_**: Comma separated list of globally disabled repo units. Allowed values: \[repo.issues, repo.ext_issues, repo.pulls, repo.wiki, repo.ext_wiki, repo.projects\]
- `DEFAULT_REPO_UNITS`: **repo.code,repo.releases,repo.issues,repo.pulls,repo.wiki,repo.projects,repo.packages**: Comma separated list of default new repo units. Allowed values: \[repo.code, repo.releases, repo.issues, repo.pulls, repo.wiki, repo.projects\]. Note: Code and Releases can currently not be deactivated. If you specify default repo units you should still list them for future compatibility. External wiki and issue tracker can't be enabled by default as it requires additional settings. Disabled repo units will not be added to new repositories regardless if it is in the default list.
- `DEFAULT_FORK_REPO_UNITS`: **repo.code,repo.pulls**: Comma separated list of default forked repo units. The set of allowed values and rules is the same as `DEFAULT_REPO_UNITS`.
@ -109,11 +110,11 @@ In addition there is _`StaticRootPath`_ which can be set as a built-in at build
### Repository - Pull Request (`repository.pull-request`)
- `WORK_IN_PROGRESS_PREFIXES`: **WIP:,\[WIP\]**: List of prefixes used in Pull Request
title to mark them as Work In Progress. These are matched in a case-insensitive manner.
title to mark them as Work In Progress. These are matched in a case-insensitive manner.
- `CLOSE_KEYWORDS`: **close**, **closes**, **closed**, **fix**, **fixes**, **fixed**, **resolve**, **resolves**, **resolved**: List of
keywords used in Pull Request comments to automatically close a related issue
keywords used in Pull Request comments to automatically close a related issue
- `REOPEN_KEYWORDS`: **reopen**, **reopens**, **reopened**: List of keywords used in Pull Request comments to automatically reopen
a related issue
a related issue
- `DEFAULT_MERGE_STYLE`: **merge**: Set default merge style for repository creating, valid options: `merge`, `rebase`, `rebase-merge`, `squash`
- `DEFAULT_MERGE_MESSAGE_COMMITS_LIMIT`: **50**: In the default merge message for squash commits include at most this many commits. Set to `-1` to include all commits
- `DEFAULT_MERGE_MESSAGE_SIZE`: **5120**: In the default merge message for squash commits limit the size of the commit messages. Set to `-1` to have no limit. Only used if `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES` is `true`.
@ -170,7 +171,7 @@ In addition there is _`StaticRootPath`_ which can be set as a built-in at build
- `LOCAL_COPY_PATH`: **tmp/local-repo**: Path for temporary local repository copies. Defaults to `tmp/local-repo` (content gets deleted on Forgejo restart)
## Repository - MIME type mapping (`repository.mimetype_mapping`)
## Repository - MIME type mapping (`repository.mimetype_mapping`)
Configuration for set the expected MIME type based on file extensions of downloadable files. Configuration presents in key-value pairs and file extensions starts with leading `.`.
@ -204,16 +205,16 @@ The following configuration set `Content-Type: application/vnd.android.package-a
- `CODE_COMMENT_LINES`: **4**: Number of line of codes shown for a code comment.
- `DEFAULT_THEME`: **forgejo-auto**: \[forgejo-auto, forgejo-light, forgejo-dark, auto, gitea, arc-green\]: Set the default theme for the Forgejo install.
- `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.
- `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
- `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.
For custom reactions, add a tightly cropped square image to public/img/emoji/reaction_name.png
Values can be emoji alias (:smile:) or a unicode emoji.
For custom reactions, add a tightly cropped square image to public/img/emoji/reaction_name.png
- `CUSTOM_EMOJIS`: **forgejo, gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the utf8 standard.
By default we support Forgejo (:forgejo:), to add more copy them to public/img/emoji/emoji_name.png and
add it to this config.
By default we support Forgejo (:forgejo:), to add more copy them to public/img/emoji/emoji_name.png and
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.
@ -244,7 +245,7 @@ The following configuration set `Content-Type: application/vnd.android.package-a
### UI - SVG Images (`ui.svg`)
- `ENABLE_RENDER`: **true**: Whether to render SVG files as images. If SVG rendering is disabled, SVG files are displayed as text and cannot be embedded in markdown files as images.
- `ENABLE_RENDER`: **true**: Whether to render SVG files as images. If SVG rendering is disabled, SVG files are displayed as text and cannot be embedded in markdown files as images.
### UI - CSV Files (`ui.csv`)
@ -272,38 +273,38 @@ 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/**:
Overwrite the automatically generated public URL.
This is useful if the internal and the external URL don't match (e.g. in Docker).
- `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\>**:
Overwrite this option to request static resources from a different URL.
This includes CSS files, images, JS files and web fonts.
Avatar images are dynamic resources and still served by Forgejo.
The option can be just a different path, as in `/static`, or another domain, as in `https://cdn.example.com`.
Requests are then made as `%(ROOT_URL)s/static/assets/css/index.css` or `https://cdn.example.com/assets/css/index.css` respectively.
The static files are located in the `public/` directory of the Forgejo source repository.
You can proxy the STATIC_URL_PREFIX requests to Forgejo server to serve the static
assets, or copy the manually built Forgejo assets from `$FORGEJO_BUILD/public` to
the assets location, eg: `/var/www/assets`, make sure `$STATIC_URL_PREFIX/assets/css/index.css`
points to `/var/www/assets/css/index.css`.
Overwrite this option to request static resources from a different URL.
This includes CSS files, images, JS files and web fonts.
Avatar images are dynamic resources and still served by Forgejo.
The option can be just a different path, as in `/static`, or another domain, as in `https://cdn.example.com`.
Requests are then made as `%(ROOT_URL)s/static/assets/css/index.css` or `https://cdn.example.com/assets/css/index.css` respectively.
The static files are located in the `public/` directory of the Forgejo source repository.
You can proxy the STATIC_URL_PREFIX requests to Forgejo server to serve the static
assets, or copy the manually built Forgejo assets from `$FORGEJO_BUILD/public` to
the assets location, eg: `/var/www/assets`, make sure `$STATIC_URL_PREFIX/assets/css/index.css`
points to `/var/www/assets/css/index.css`.
- `HTTP_ADDR`: **0.0.0.0**: HTTP listen address.
- If `PROTOCOL` is set to `fcgi`, Forgejo will listen for FastCGI requests on TCP socket
defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
- If `PROTOCOL` is set to `http+unix` or `fcgi+unix`, this should be the name of the Unix socket file to use. Relative paths will be made absolute against the _`AppWorkPath`_.
- `HTTP_PORT`: **3000**: HTTP listen port.
- If `PROTOCOL` is set to `fcgi`, Forgejo will listen for FastCGI requests on TCP socket
defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
- `UNIX_SOCKET_PERMISSION`: **666**: Permissions for the Unix socket.
- `LOCAL_ROOT_URL`: **%(PROTOCOL)s://%(HTTP_ADDR)s:%(HTTP_PORT)s/**: Local
(DMZ) URL for Forgejo workers (such as SSH update) accessing web service. In
most cases you do not need to change the default value. Alter it only if
your SSH server node is not the same as HTTP node. Do not set this variable
if `PROTOCOL` is set to `http+unix`.
(DMZ) URL for Forgejo workers (such as SSH update) accessing web service. In
most cases you do not need to change the default value. Alter it only if
your SSH server node is not the same as HTTP node. Do not set this variable
if `PROTOCOL` is set to `http+unix`.
- `LOCAL_USE_PROXY_PROTOCOL`: **%(USE_PROXY_PROTOCOL)s**: When making local connections pass the PROXY protocol header.
This should be set to false if the local connection will go through the proxy.
This should be set to false if the local connection will go through the proxy.
- `PER_WRITE_TIMEOUT`: **30s**: Timeout for any write to the connection. (Set to -1 to
disable all timeouts.)
disable all timeouts.)
- `PER_WRITE_PER_KB_TIMEOUT`: **10s**: Timeout per Kb written to connections.
- `DISABLE_SSH`: **false**: Disable SSH feature when it's not available.
@ -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,9 +475,9 @@ 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
**`name`**`QUEUE_NAME`_`SET_NAME`_ but can be overridden in the specific `queue.name` section.
- `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
- `TIMEOUT`: **GRACEFUL_HAMMER_TIME + 30s**: Timeout the creation of the wrapped queue if it takes longer than this to create.
@ -529,26 +530,26 @@ 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
information.
- `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.
authentication.
- `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: Header name for reverse proxy
authentication provided email.
authentication provided email.
- `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: Header name for reverse proxy
authentication provided full name.
authentication provided full name.
- `REVERSE_PROXY_LIMIT`: **1**: Interpret X-Forwarded-For header or the X-Real-IP header and set this as the remote IP for the request.
Number of trusted proxy count. Set to zero to not use these headers.
Number of trusted proxy count. Set to zero to not use these headers.
- `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all.
- `DISABLE_GIT_HOOKS`: **true**: Set to `false` to enable users with Git Hook privilege to create custom Git Hooks.
WARNING: Custom Git Hooks can be used to perform arbitrary code execution on the host operating system.
This enables the users to access and modify this config file and the Forgejo database and interrupt the Forgejo service.
By modifying the Forgejo database, users can gain Forgejo administrator privileges.
It also enables them to access other resources available to the user on the operating system that is running the
Forgejo instance and perform arbitrary actions in the name of the Forgejo OS user.
This maybe harmful to you website or your operating system.
Setting this to true does not change existing hooks in git repos; adjust it before if necessary.
WARNING: Custom Git Hooks can be used to perform arbitrary code execution on the host operating system.
This enables the users to access and modify this config file and the Forgejo database and interrupt the Forgejo service.
By modifying the Forgejo database, users can gain Forgejo administrator privileges.
It also enables them to access other resources available to the user on the operating system that is running the
Forgejo instance and perform arbitrary actions in the name of the Forgejo OS user.
This maybe harmful to you website or your operating system.
Setting this to true does not change existing hooks in git repos; adjust it before if necessary.
- `DISABLE_WEBHOOKS`: **false**: Set to `true` to disable webhooks feature.
- `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.
@ -562,13 +563,13 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
- `pbkdf2$<iterations>$<key-length>`
- `scrypt$<n>$<r>$<p>$<key-length>`
- The defaults are:
- `argon2`: `argon2$2$65536$8$50`
- `bcrypt`: `bcrypt$10`
- `pbkdf2`: `pbkdf2$50000$50`
- `argon2`: `argon2$2$65536$8$50`
- `bcrypt`: `bcrypt$10`
- `pbkdf2`: `pbkdf2$50000$50`
- `pbkdf2_v1`: `pbkdf2$10000$50`
- `pbkdf2_v2`: `pbkdf2$50000$50`
- `pbkdf2_hi`: `pbkdf2$320000$50`
- `scrypt`: `scrypt$65536$16$2$50`
- `scrypt`: `scrypt$65536$16$2$50`
- Adjusting the algorithm parameters using this functionality is done at your own risk.
- `CSRF_COOKIE_HTTP_ONLY`: **true**: Set false to allow JavaScript to read CSRF cookie.
- `MIN_PASSWORD_LENGTH`: **6**: Minimum password length for new users.
@ -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,15 +592,15 @@ 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.
OpenID URI's to permit.
- `BLACKLISTED_URIS`: **\<empty\>**: If non-empty, list of POSIX regex patterns matching
OpenID URI's to block.
OpenID URI's to block.
## 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:
@ -616,34 +617,34 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
- `ACTIVE_CODE_LIVE_MINUTES`: **180**: Time limit (min) to confirm account/email registration.
- `RESET_PASSWD_CODE_LIVE_MINUTES`: **180**: Time limit (min) to confirm forgot password reset
process.
process.
- `REGISTER_EMAIL_CONFIRM`: **false**: Enable this to ask for mail confirmation of registration.
Requires `Mailer` to be enabled.
Requires `Mailer` to be enabled.
- `REGISTER_MANUAL_CONFIRM`: **false**: Enable this to manually confirm new registrations.
Requires `REGISTER_EMAIL_CONFIRM` to be disabled.
Requires `REGISTER_EMAIL_CONFIRM` to be disabled.
- `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create
accounts for users.
accounts for users.
- `REQUIRE_EXTERNAL_REGISTRATION_PASSWORD`: **false**: Enable this to force externally created
accounts (via GitHub, OpenID Connect, etc) to create a password. Warning: enabling this will
decrease security, so you should only enable it if you know what you're doing.
accounts (via GitHub, OpenID Connect, etc) to create a password. Warning: enabling this will
decrease security, so you should only enable it if you know what you're doing.
- `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page or to use API.
- `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when
something happens, like creating issues. Requires `Mailer` to be enabled.
something happens, like creating issues. Requires `Mailer` to be enabled.
- `ENABLE_BASIC_AUTHENTICATION`: **true**: Disable this to disallow authenticaton using HTTP
BASIC and the user's password. Please note if you disable this you will not be able to access the
tokens API endpoints using a password. Further, this only disables BASIC authentication using the
password - not tokens or OAuth Basic.
BASIC and the user's password. Please note if you disable this you will not be able to access the
tokens API endpoints using a password. Further, this only disables BASIC authentication using the
password - not tokens or OAuth Basic.
- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable this to allow reverse proxy authentication.
- `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration
for reverse authentication.
for reverse authentication.
- `ENABLE_REVERSE_PROXY_EMAIL`: **false**: Enable this to allow to auto-registration with a
provided email rather than a generated email.
provided email rather than a generated email.
- `ENABLE_REVERSE_PROXY_FULL_NAME`: **false**: Enable this to allow to auto-registration with a
provided full name for the user.
provided full name for the user.
- `ENABLE_CAPTCHA`: **false**: Enable this to use captcha validation for registration.
- `REQUIRE_CAPTCHA_FOR_LOGIN`: **false**: Enable this to require captcha validation for login. You also must enable `ENABLE_CAPTCHA`.
- `REQUIRE_EXTERNAL_REGISTRATION_CAPTCHA`: **false**: Enable this to force captcha validation
even for External Accounts (i.e. GitHub, OpenID Connect, etc). You also must enable `ENABLE_CAPTCHA`.
even for External Accounts (i.e. GitHub, OpenID Connect, etc). You also must enable `ENABLE_CAPTCHA`.
- `CAPTCHA_TYPE`: **image**: \[image, recaptcha, hcaptcha, mcaptcha, cfturnstile\]
- `RECAPTCHA_SECRET`: **""**: Go to https://www.google.com/recaptcha/admin to get a secret for recaptcha.
- `RECAPTCHA_SITEKEY`: **""**: Go to https://www.google.com/recaptcha/admin to get a sitekey for recaptcha.
@ -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`)
@ -724,7 +725,7 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
- Enabling dummy will ignore all settings except `ENABLED`, `SUBJECT_PREFIX` and `FROM`.
- `SMTP_ADDR`: **\<empty\>**: Mail server address. e.g. smtp.gmail.com. For smtp+unix, this should be a path to a unix socket instead. _Before 1.18, this was combined with `SMTP_PORT` under the name `HOST`._
- `SMTP_PORT`: **\<empty\>**: Mail server port. If no protocol is specified, it will be inferred by this setting. Common ports are listed below. _Before 1.18, this was combined with `SMTP_ADDR` under the name `HOST`._
- 25: insecure SMTP
- 25: insecure SMTP
- 465: SMTP Secure
- 587: StartTLS
- `USE_CLIENT_CERT`: **false**: Use client certificate for TLS/SSL.
@ -732,7 +733,7 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
- `CLIENT_KEY_FILE`: **custom/mailer/key.pem**: Client key file.
- `FORCE_TRUST_SERVER_CERT`: **false**: If set to `true`, completely ignores server certificate validation errors. This option is unsafe. Consider adding the certificate to the system trust store instead.
- `USER`: **\<empty\>**: Username of mailing user (usually the sender's e-mail address).
- `PASSWD`: **\<empty\>**: Password of mailing user. Use \`your password\` for quoting if you use special characters in the password.
- `PASSWD`: **\<empty\>**: Password of mailing user. Use \`your password\` for quoting if you use special characters in the password.
- Please note: authentication is only supported when the SMTP server communication is encrypted with TLS (this can be via `STARTTLS`) or SMTP host is localhost. See [Email Setup]({{< relref "doc/usage/email-setup.en-us.md" >}}) for more information.
- `ENABLE_HELO`: **true**: Enable HELO operation.
- `HELO_HOSTNAME`: **(retrieved from system)**: HELO hostname.
@ -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
@ -791,10 +792,10 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
## Picture (`picture`)
- `GRAVATAR_SOURCE`: **gravatar**: Can be `gravatar`, `duoshuo` or anything like
`http://cn.gravatar.com/avatar/`.
`http://cn.gravatar.com/avatar/`.
- `DISABLE_GRAVATAR`: **false**: Enable this to use local avatars only. **DEPRECATED [v1.18+]** moved to database. Use admin panel to configure.
- `ENABLE_FEDERATED_AVATAR`: **false**: Enable support for federated avatars (see
[http://www.libravatar.org](http://www.libravatar.org)). **DEPRECATED [v1.18+]** moved to database. Use admin panel to configure.
[http://www.libravatar.org](http://www.libravatar.org)). **DEPRECATED [v1.18+]** moved to database. Use admin panel to configure.
- `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.
@ -1004,14 +1005,14 @@ Default templates for project boards:
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
#### Cron - Delete generated repository avatars ('cron.delete_generated_repository_avatars')
#### Cron - Delete generated repository avatars ('cron.delete_generated_repository_avatars')
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
#### Cron - Delete all old actions from database ('cron.delete_old_actions')
#### Cron - Delete all old actions from database ('cron.delete_old_actions')
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
@ -1019,7 +1020,7 @@ Default templates for project boards:
- `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.
#### Cron - Check for new Forgejo versions ('cron.update_checker')
#### Cron - Check for new Forgejo versions ('cron.update_checker')
- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
@ -1028,7 +1029,7 @@ Default templates for project boards:
- `HTTP_ENDPOINT`: **https://dl.gitea.io/gitea/version.json**: the endpoint that Gitea will check for newer versions
- `DOMAIN_ENDPOINT`: **release.forgejo.org**: the domain that, if specified, Gitea will check for newer versions. This is preferred over `HTTP_ENDPOINT`.
#### Cron - Delete all old system notices from database ('cron.delete_old_system_notices')
#### Cron - Delete all old system notices from database ('cron.delete_old_system_notices')
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
@ -1036,7 +1037,7 @@ Default templates for project boards:
- `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.
#### Cron - Garbage collect LFS pointers in repositories ('cron.gc_lfs')
#### Cron - Garbage collect LFS pointers in repositories ('cron.gc_lfs')
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
@ -1050,7 +1051,7 @@ Default templates for project boards:
- `PATH`: **""**: The path of Git executable. If empty, Forgejo searches through the PATH environment.
- `HOME_PATH`: **%(APP_DATA_PATH)s/home**: The HOME directory for Git.
This directory will be used to contain the `.gitconfig` and possible `.gnupg` directories that Forgejo's git calls will use. If you can confirm Forgejo is the only application running in this environment, you can set it to the normal home directory for Forgejo user.
This directory will be used to contain the `.gitconfig` and possible `.gnupg` directories that Forgejo's git calls will use. If you can confirm Forgejo is the only application running in this environment, you can set it to the normal home directory for Forgejo user.
- `DISABLE_DIFF_HIGHLIGHT`: **false**: Disables highlight of added and removed changes.
- `MAX_GIT_DIFF_LINES`: **1000**: Max number of lines allowed of a single file in diff view.
- `MAX_GIT_DIFF_LINE_CHARACTERS`: **5000**: Max character count per line highlighted in diff view.
@ -1105,7 +1106,7 @@ Default templates for project boards:
## i18n (`i18n`)
- `LANGS`: **en-US,zh-CN,zh-HK,zh-TW,de-DE,fr-FR,nl-NL,lv-LV,ru-RU,uk-UA,ja-JP,es-ES,pt-BR,pt-PT,pl-PL,bg-BG,it-IT,fi-FI,tr-TR,cs-CZ,sv-SE,ko-KR,el-GR,fa-IR,hu-HU,id-ID,ml-IN**:
List of locales shown in language selector. The first locale will be used as the default if user browser's language doesn't match any locale in the list.
List of locales shown in language selector. The first locale will be used as the default if user browser's language doesn't match any locale in the list.
- `NAMES`: **English,简体中文,繁體中文（香港）,繁體中文（台灣）,Deutsch,Français,Nederlands,Latviešu,Русский,Українська,日本語,Español,Português do Brasil,Português de Portugal,Polski,Български,Italiano,Suomi,Türkçe,Čeština,Српски,Svenska,한국어,Ελληνικά,فارسی,Magyar nyelv,Bahasa Indonesia,മലയാളം**: Visible names corresponding to the locales
## Markup (`markup`)
@ -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
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`.
- 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_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:

13
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.
@ -44,8 +45,8 @@ index = "https://forgejo.example.com/{owner}/_cargo-index.git"
git-fetch-with-cli = true
```
| Parameter | Description |
| --------- | ----------- |
| 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.
@ -56,8 +57,8 @@ Add the credentials section to the credentials file located in the current users
token = "Bearer {token}"
```
| Parameter | Description |
| --------- | ----------- |
| Parameter | Description |
| --------- | ----------------------------------------------------------------------------------------------- |
| `token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}) |
## Publish a package
@ -78,8 +79,8 @@ To install a package from the package registry, execute the following command:
cargo add {package_name}
```
| Parameter | Description |
| -------------- | ----------- |
| Parameter | Description |
| -------------- | ----------------- |
| `package_name` | The package name. |
## Supported commands

21
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.
@ -24,8 +25,8 @@ To [configure `knife`](https://docs.chef.io/workstation/knife_setup/) to use the
knife[:supermarket_site] = 'https://forgejo.example.com/api/packages/{owner}/chef'
```
| Parameter | Description |
| --------- | ----------- |
| Parameter | Description |
| --------- | ------------------------- |
| `owner` | The owner of the package. |
## Publish a package
@ -36,8 +37,8 @@ To publish a Chef package execute the following command:
knife supermarket share {package_name}
```
| Parameter | Description |
| -------------- | ----------- |
| 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.
@ -56,9 +57,9 @@ Optional you can specify the package version:
knife supermarket install {package_name} {package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| `package_name` | The package name. |
| Parameter | Description |
| ----------------- | -------------------- |
| `package_name` | The package name. |
| `package_version` | The package version. |
## Delete a package
@ -75,7 +76,7 @@ Optional you can specify the package version:
knife supermarket unshare {package_name}/versions/{package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| `package_name` | The package name. |
| Parameter | Description |
| ----------------- | -------------------- |
| `package_name` | The package name. |
| `package_version` | The package version. |

32
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.
@ -19,9 +20,9 @@ You cannot publish a package if a package of the same name and version already e
PUT https://forgejo.example.com/api/packages/{owner}/composer
```
| Parameter | Description |
| ---------- | ----------- |
| `owner` | The owner of the package. |
| 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:
@ -49,9 +50,9 @@ 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. |
| 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. |
## Configuring the package registry
@ -60,10 +61,11 @@ 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"
}
}
]
}
```
@ -81,10 +83,10 @@ 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. |
| Parameter | Description |
| ---------- | ------------------------------------------------- |
| `owner` | The owner of the package. |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password or a personal access token. |
## Install a package
@ -101,7 +103,7 @@ Optional you can specify the package version:
composer require {package_name}:{package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| `package_name` | The package name. |
| Parameter | Description |
| ----------------- | -------------------- |
| `package_name` | The package name. |
| `package_version` | The package version. |

23
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.
@ -18,12 +19,12 @@ conan remote add {remote} https://forgejo.example.com/api/packages/{owner}/conan
conan user --remote {remote} --password {password} {username}
```
| Parameter | Description |
| -----------| ----------- |
| `remote` | The remote name. |
| `username` | Your Forgejo 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. |
| `owner` | The owner of the package. |
| `owner` | The owner of the package. |
For example:
@ -40,9 +41,9 @@ Publish a Conan package by running the following command:
conan upload --remote={remote} {recipe}
```
| Parameter | Description |
| ----------| ----------- |
| `remote` | The remote name. |
| Parameter | Description |
| --------- | --------------------- |
| `remote` | The remote name. |
| `recipe` | The recipe to upload. |
For example:
@ -61,9 +62,9 @@ To install a Conan package from the package registry, execute the following comm
conan install --remote={remote} {recipe}
```
| Parameter | Description |
| ----------| ----------- |
| `remote` | The remote name. |
| Parameter | Description |
| --------- | ----------------------- |
| `remote` | The remote name. |
| `recipe` | The recipe to download. |
For example:

25
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.
@ -21,9 +22,9 @@ default_channels:
- https://forgejo.example.com/api/packages/{owner}/conda
```
| Placeholder | Description |
| ------------ | ----------- |
| `owner` | The owner of the package. |
| 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.
@ -37,11 +38,11 @@ To publish a package, perform a HTTP PUT operation with the package content in t
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. |
| 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. |
Example request using HTTP Basic authentication:
@ -63,8 +64,8 @@ conda install {package_name}={package_version}
conda install -c {channel} {package_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| `package_name` | The package name. |
| `package_version` | The package version. |
| Parameter | Description |
| ----------------- | -------------------------------------- |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `channel` | The channel of the package. (optional) |

17
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.
@ -45,11 +46,11 @@ Push an image by executing the following command:
docker push forgejo.example.com/{owner}/{image}:{tag}
```
| Parameter | Description |
| ----------| ----------- |
| Parameter | Description |
| --------- | ----------------------- |
| `owner` | The owner of the image. |
| `image` | The name of the image. |
| `tag` | The tag of the image. |
| `image` | The name of the image. |
| `tag` | The tag of the image. |
For example:
@ -65,11 +66,11 @@ Pull an image by executing the following command:
docker pull forgejo.example.com/{owner}/{image}:{tag}
```
| Parameter | Description |
| ----------| ----------- |
| Parameter | Description |
| --------- | ----------------------- |
| `owner` | The owner of the image. |
| `image` | The name of the image. |
| `tag` | The tag of the image. |
| `image` | The name of the image. |
| `tag` | The tag of the image. |
For example:

71
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.
@ -18,12 +19,12 @@ You cannot publish a file with the same name twice to a package. You must delete
PUT https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| 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. |
| `file_name` | The filename. 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. |
| `file_name` | The filename. It can contain only lowercase letters (`a-z`), uppercase letter (`A-Z`), numbers (`0-9`), dots (`.`), hyphens (`-`), pluses (`+`), or underscores (`_`). |
Example request using HTTP Basic authentication:
@ -37,11 +38,11 @@ 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. |
| 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. |
| `409 Conflict` | A file with the same name exist already in the package. |
## Download a package
@ -51,12 +52,12 @@ To download a generic package perform a HTTP GET operation.
GET https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{file_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| Parameter | Description |
| ----------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `file_name` | The filename. |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `file_name` | The filename. |
The file content is served in the response body. The response content type is `application/octet-stream`.
@ -69,10 +70,10 @@ 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. |
| HTTP Status Code | Meaning |
| ---------------- | ---------------------------------- |
| `200 OK` | Success |
| `404 Not Found` | The package or file was not found. |
## Delete a package
@ -82,11 +83,11 @@ To delete a generic package perform a HTTP DELETE operation. This will delete al
DELETE https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{package_version}
```
| Parameter | Description |
| ----------------- | ----------- |
| Parameter | Description |
| ----------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `package_name` | The package name. |
| `package_version` | The package version. |
Example request using HTTP Basic authentication:
@ -97,10 +98,10 @@ 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. |
| HTTP Status Code | Meaning |
| ---------------- | -------------------------- |
| `204 No Content` | Success |
| `404 Not Found` | The package was not found. |
## Delete a package file
@ -110,12 +111,12 @@ To delete a file of a generic package perform a HTTP DELETE operation. This will
DELETE https://forgejo.example.com/api/packages/{owner}/generic/{package_name}/{package_version}/{filename}
```
| Parameter | Description |
| ----------------- | ----------- |
| Parameter | Description |
| ----------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `filename` | The filename. |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `filename` | The filename. |
Example request using HTTP Basic authentication:
@ -126,7 +127,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 or file was not found. |
| HTTP Status Code | Meaning |
| ---------------- | ---------------------------------- |
| `204 No Content` | Success |
| `404 Not Found` | The package or file was not found. |

27
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.
@ -24,13 +25,13 @@ helm repo add --username {username} --password {password} {repo} https://forgej
helm cm-push ./{chart_file}.tgz {repo}
```
| Parameter | Description |
| ------------ | ----------- |
| `username` | Your Forgejo username. |
| 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. |
| `chart_file` | The Helm Chart archive. |
| `owner` | The owner of the package. |
| `repo` | The name for the repository. |
| `chart_file` | The Helm Chart archive. |
| `owner` | The owner of the package. |
## Install a package
@ -42,11 +43,11 @@ helm repo update
helm install {name} {repo}/{chart}
```
| Parameter | Description |
| ---------- | ----------- |
| `username` | Your Forgejo username. |
| Parameter | Description |
| ---------- | ------------------------------------------------- |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password or a personal access token. |
| `repo` | The name for the repository. |
| `owner` | The owner of the package. |
| `name` | The local name. |
| `chart` | The name Helm Chart. |
| `repo` | The name for the repository. |
| `owner` | The owner of the package. |
| `name` | The local name. |
| `chart` | The name Helm Chart. |

13
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.
@ -53,10 +54,10 @@ Afterwards add the following sections to your project `pom.xml` file:
</distributionManagement>
```
| Parameter | Description |
| -------------- | ----------- |
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------ |
| `access_token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). |
| `owner` | The owner of the package. |
| `owner` | The owner of the package. |
## Publish a package
@ -72,9 +73,9 @@ If you want to publish a prebuild package to the registry, you can use [`mvn dep
mvn deploy:deploy-file -Durl=https://forgejo.example.com/api/packages/{owner}/maven -DrepositoryId=forgejo -Dfile=/path/to/package.jar
```
| Parameter | Description |
| -------------- | ----------- |
| `owner` | The owner of the package. |
| 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.

29
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.
@ -22,11 +23,11 @@ npm config set {scope}:registry https://forgejo.example.com/api/packages/{owner}
npm config set -- '//forgejo.example.com/api/packages/{owner}/npm/:_authToken' "{token}"
```
| 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" >}}). |
| 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" >}}). |
For example:
@ -60,9 +61,9 @@ Delete a package by running the following command:
npm unpublish {package_name}[@{package_version}]
```
| Parameter | Description |
| ----------------- | ----------- |
| `package_name` | The package name. |
| Parameter | Description |
| ----------------- | -------------------- |
| `package_name` | The package name. |
| `package_version` | The package version. |
For example:
@ -80,8 +81,8 @@ To install a package from the package registry, execute the following command:
npm install {package_name}
```
| Parameter | Description |
| -------------- | ----------- |
| Parameter | Description |
| -------------- | ----------------- |
| `package_name` | The package name. |
For example:
@ -98,11 +99,11 @@ The registry supports [version tags](https://docs.npmjs.com/adding-dist-tags-to-
npm dist-tag add {package_name}@{version} {tag}
```
| Parameter | Description |
| -------------- | ----------- |
| `package_name` | The package name. |
| Parameter | Description |
| -------------- | --------------------------- |
| `package_name` | The package name. |
| `version` | The version of the package. |
| `tag` | The tag name. |
| `tag` | The tag name. |
For example:

29
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.
@ -19,12 +20,12 @@ To register the package registry you need to configure a new NuGet feed source:
dotnet nuget add source --name {source_name} --username {username} --password {password} https://forgejo.example.com/api/packages/{owner}/nuget/index.json
```
| Parameter | Description |
| ------------- | ----------- |
| `source_name` | The desired source name. |
| `username` | Your Forgejo username. |
| 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. |
| `owner` | The owner of the package. |
| `owner` | The owner of the package. |
For example:
@ -42,9 +43,9 @@ Publish a package by running the following command:
dotnet nuget push --source {source_name} {package_file}
```
| Parameter | Description |
| -------------- | ----------- |
| `source_name` | The desired source name. |
| Parameter | Description |
| -------------- | ---------------------------------- |
| `source_name` | The desired source name. |
| `package_file` | Path to the package `.nupkg` file. |
For example:
@ -64,8 +65,8 @@ To do so, register the NuGet package registry as symbol source:
https://forgejo.example.com/api/packages/{owner}/nuget/symbols
```
| Parameter | Description |
| --------- | ----------- |
| Parameter | Description |
| --------- | ---------------------------------- |
| `owner` | The owner of the package registry. |
For example:
@ -82,11 +83,11 @@ To install a NuGet package from the package registry, execute the following comm
dotnet add package --source {source_name} --version {package_version} {package_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| Parameter | Description |
| ----------------- | ------------------------ |
| `source_name` | The desired source name. |
| `package_name` | The package name. |
| `package_version` | The package version. |
| `package_name` | The package name. |
| `package_version` | The package version. |
For example:

21
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.
@ -19,9 +20,9 @@ To register the package registry and provide credentials, execute:
dart pub token add https://forgejo.example.com/api/packages/{owner}/pub
```
| Placeholder | Description |
| ------------ | ----------- |
| `owner` | The owner of the package. |
| 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" >}}).
@ -33,9 +34,9 @@ To publish a package, edit the `pubspec.yaml` and add the following line:
publish_to: https://forgejo.example.com/api/packages/{owner}/pub
```
| Placeholder | Description |
| ------------ | ----------- |
| `owner` | The owner of the package. |
| Placeholder | Description |
| ----------- | ------------------------- |
| `owner` | The owner of the package. |
Now you can publish the package by running the following command:
@ -53,10 +54,10 @@ To install a Pub package from the package registry, execute the following comman
dart pub add {package_name} --hosted-url=https://forgejo.example.com/api/packages/{owner}/pub/
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| Parameter | Description |
| -------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
For example:

23
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.
@ -23,11 +24,11 @@ username = {username}
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. |
| 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. |
## Publish a package
@ -49,12 +50,12 @@ To install a PyPI package from the package registry, execute the following comma
pip install --index-url https://{username}:{password}@forgejo.example.com/api/packages/{owner}/pypi/simple --no-deps {package_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password or a personal access token. |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| Parameter | Description |
| -------------- | ------------------------------------------------- |
| `username` | Your Forgejo username. |
| `password` | Your Forgejo password or a personal access token. |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
For example:

31
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.
@ -18,10 +19,10 @@ To register the package registry edit the `~/.gem/credentials` file and add:
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" >}}). |
| Parameter | Description |
| --------- | ------------------------------------------------------------------------------------------------ |
| `owner` | The owner of the package. |
| `token` | Your [personal access token]({{< relref "doc/developers/api-usage.en-us.md#authentication" >}}). |
For example:
@ -38,9 +39,9 @@ Publish a package by running the following command:
gem push --host {host} {package_file}
```
| Parameter | Description |
| -------------- | ----------- |
| `host` | URL to the package registry. |
| Parameter | Description |
| -------------- | -------------------------------- |
| `host` | URL to the package registry. |
| `package_file` | Path to the package `.gem` file. |
For example:
@ -65,10 +66,10 @@ source "https://forgejo.example.com/api/packages/{owner}/rubygems" do
end
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| Parameter | Description |
| -------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
For example:
@ -92,10 +93,10 @@ Execute the following command:
gem install --host https://forgejo.example.com/api/packages/{owner}/rubygems {package_name}
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| Parameter | Description |
| -------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
For example:

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.

17
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.
@ -17,11 +18,11 @@ Publish a Vagrant box by performing a HTTP PUT request to the registry:
PUT https://forgejo.example.com/api/packages/{owner}/vagrant/{package_name}/{package_version}/{provider}.box
```
| Parameter | Description |
| ----------------- | ----------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version, semver compatible. |
| Parameter | Description |
| ----------------- | -------------------------------------------------------------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_version` | The package version, semver compatible. |
| `provider` | One of the [supported provider names](https://www.vagrantup.com/docs/providers). |
Example for uploading a Hyper-V box:
@ -42,10 +43,10 @@ To install a box from the package registry, execute the following command:
vagrant box add "https://forgejo.example.com/api/packages/{owner}/vagrant/{package_name}"
```
| Parameter | Description |
| -------------- | ----------- |
| Parameter | Description |
| -------------- | ------------------------- |
| `owner` | The owner of the package. |
| `package_name` | The package name. |
| `package_name` | The package name. |
For example:

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

105
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 |
| 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 |
| 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.* |
| 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._ |
#### 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.