---
title: 'Configuration Cheat Sheet'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/administration/config-cheat-sheet.en-us.md'
---

This is a cheat sheet for the Forgejo configuration file. It contains most of the settings
that can be configured as well as their default values.

Any changes to the Forgejo configuration file should be made in `custom/conf/app.ini`
or any corresponding location. When installing from a distribution, this will
typically be found at `/etc/forgejo/app.ini`.

The defaults provided here are best-effort (not built automatically). They are
accurately recorded in [app.example.ini](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/custom/conf/app.example.ini)
(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. See [environment-to-ini](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/contrib/environment-to-ini) for information on how environment variables are translated to `app.ini` variables. 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 `"""`.

**Note:** A full restart is required for Forgejo configuration changes to take effect.

## Default Configuration (non-`app.ini` configuration)

These values are environment-dependent but form the basis of many values. They will be
reported as part of the default configuration when running `forgejo help` or on start-up. The order they are emitted there is slightly different, but we will list them here in the order they are set up.

- _`AppPath`_: This is the absolute path of the running forgejo binary.
- _`AppWorkPath`_: This refers to the "working path" of the `forgejo` binary. It is determined by using the first defined value in the following hierarchy:
  - The `--work-path` flag passed to the binary
  - The environment variable `$FORGEJO_WORK_DIR`
  - 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 directory of the _`AppPath`_
- _`CustomPath`_: This is the base directory for custom templates and other options.
  It is determined by using the first defined value 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
    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
    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`_.

## Overall (`DEFAULT`)

- `APP_NAME`: **Forgejo: Beyond coding. We forge.**: Application name, used in the page title.
- `APP_SLOGAN`: Application slogan, used in the page title.
- `APP_DISPLAY_NAME_FORMAT`: **{APP_NAME}: {APP_SLOGAN}**: Defines how the application full name should be presented.
  It is only used if `APP_SLOGAN` is set.
- `RUN_USER`: **_current OS username_/`$USER`/`$USERNAME` e.g. git**: The user Forgejo will run as.
  This should be a dedicated system (non-user) account. Setting this incorrectly will cause Forgejo
  to not start.
- `RUN_MODE`: **prod**: Application run mode, affects performance and debugging: `dev` or `prod`, default is `prod`. Mode `dev` makes Forgejo easier to develop and debug; values other than `dev` are treated as `prod`, which is for production use.
- `WORK_PATH`: **_the-work-path_**: The working directory, see the comment of _`AppWorkPath`_ above.

## 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**.
- `SCRIPT_TYPE`: **bash**: The script type this server supports. Usually this is `bash`,
  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 privacy setting when creating a new repository.
  \[last, private, public\]
- `DEFAULT_PUSH_CREATE_PRIVATE`: **true**: Default privacy setting 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.
- `PREFERRED_LICENSES`: **Apache-2.0, MIT"**: Preferred Licenses to place at
  the top of the list. Name must match the file name in options/license or custom/options/license.
- `DISABLE_HTTP_GIT`: **false**: Disable the ability to interact with repositories over the
  HTTP protocol.
- `USE_COMPAT_SSH_URI`: **true**: Always use `ssh://` clone URL instead of scp-style URI.
- `GO_GET_CLONE_URL_PROTOCOL`: **https**: Value for the "go get" request returns the repository URL as https or ssh.
  Default is https.
- `ACCESS_CONTROL_ALLOW_ORIGIN`: **\<empty\>**: Value for `Access-Control-Allow-Origin` header;
  by default, the header is not present. **WARNING**: This may be harmful to your website if you do not
  give it the correct 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, repo.packages, repo.actions\]
- `DEFAULT_REPO_UNITS`: **repo.code,repo.releases,repo.issues,repo.pulls,repo.wiki,repo.projects,repo.packages,repo.actions**: Comma-separated list of default new repo units. Allowed values: \[repo.code, repo.releases, repo.issues, repo.pulls, repo.wiki, repo.projects, repo.packages, repo.actions\]. 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 of whether they are 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`.
- `PREFIX_ARCHIVE_FILES`: **true**: Prefix archive files by placing them in a directory named after the repository.
- `DISABLE_MIGRATIONS`: **false**: Disable migrating feature.
- `DISABLE_STARS`: **false**: Disable stars feature.
- `DEFAULT_BRANCH`: **main**: Default branch name for all new repositories.
- `ALLOW_ADOPTION_OF_UNADOPTED_REPOSITORIES`: **false**: Allow non-admin users to adopt unadopted repositories.
- `ALLOW_DELETION_OF_UNADOPTED_REPOSITORIES`: **false**: Allow non-admin users to delete unadopted repositories.
- `DISABLE_DOWNLOAD_SOURCE_ARCHIVES`: **false**: Prevents the downloading of source archive files from the UI.
- `ALLOW_FORK_WITHOUT_MAXIMUM_LIMIT`: **true**: Allows forking repositories even if the user has reached their repository limit.

### Repository - Editor (`repository.editor`)

- `LINE_WRAP_EXTENSIONS`: **.txt,.md,.markdown,.mdown,.mkd,.livemd,**: List of file extensions for which lines should be wrapped in the Monaco editor. Separate extensions with a comma. To line wrap files without an extension, just put a comma.
- `PREVIEWABLE_FILE_MODES`: **markdown**: Valid file modes that have a preview API associated with them, such as `api/v1/markdown`. Separate the values by commas. The preview tab in edit mode won't be displayed if the file extension doesn't match.

### Repository - Pull Request (`repository.pull-request`)

- `WORK_IN_PROGRESS_PREFIXES`: **WIP:,\[WIP\]**: List of prefixes used in Pull Request
  titles 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.
- `REOPEN_KEYWORDS`: **reopen**, **reopens**, **reopened**: List of keywords used in Pull Request comments to automatically reopen
  a related issue.
- `DEFAULT_MERGE_STYLE`: **merge**: Set default merge style for repository creation; valid options: `merge`, `rebase`, `rebase-merge`, `squash`, `fast-forward-only`.
- `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`.
- `DEFAULT_MERGE_MESSAGE_ALL_AUTHORS`: **false**: In the default merge message for squash commits, walk all commits to include all authors in the `Co-authored-by` trailers; otherwise, just use those in the limited list.
- `DEFAULT_MERGE_MESSAGE_MAX_APPROVERS`: **10**: In default merge messages, limit the number of approvers listed as `Reviewed-by:`. Set to `-1` to include all.
- `DEFAULT_MERGE_MESSAGE_OFFICIAL_APPROVERS_ONLY`: **true**: In default merge messages, only include approvers who are officially allowed to review.
- `DEFAULT_UPDATE_STYLE`: **merge**: Set default PR branch update style for repository creation; valid options: `merge`, `rebase`.
- `POPULATE_SQUASH_COMMENT_WITH_COMMIT_MESSAGES`: **false**: In default squash-merge messages, include the commit message of all commits comprising the pull request.
- `ADD_CO_COMMITTER_TRAILERS`: **true**: Add `Co-authored-by` and `Co-committed-by` trailers to merge commit messages if the committer does not match the author.
- `TEST_CONFLICTING_PATCHES_WITH_GIT_APPLY`: **false**: PR patches are tested using a three-way merge method to discover if there are conflicts. If this setting is set to **true**, conflicting patches will be retested using `git apply`. This was the previous behaviour in 1.18 (and earlier) but is somewhat inefficient. Please report if you find that this setting is required.
- `RETARGET_CHILDREN_ON_MERGE`: **true**: Retarget child pull requests to the parent pull request branch target on merge of the parent pull request. It only works on merged PRs where the head and base branch target the same repo.

### Repository - Issue (`repository.issue`)

- `LOCK_REASONS`: **Too heated,Off-topic,Resolved,Spam**: A list of reasons why a Pull Request or Issue can be locked.
- `MAX_PINNED`: **3**: Maximum number of pinned Issues per Repo. Set to 0 to disable pinning Issues.

### Repository - Upload (`repository.upload`)

- `ENABLED`: **true**: Whether repository file uploads are enabled.
- `TEMP_PATH`: **data/tmp/uploads**: Path for uploads (content gets deleted on Forgejo restart).
- `ALLOWED_TYPES`: **\<empty\>**: Comma-separated list of allowed file extensions (`.zip`), MIME types (`text/plain`), or wildcard types (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types.
- `FILE_MAX_SIZE`: **50**: Maximum size of each file in megabytes.
- `MAX_FILES`: **5**: Maximum number of files per upload.

### Repository - Release (`repository.release`)

- `ALLOWED_TYPES`: **\<empty\>**: Comma-separated list of allowed file extensions (`.zip`), MIME types (`text/plain`), or wildcard types (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types.
- `DEFAULT_PAGING_NUM`: **10**: The default paging number for the releases user interface.
- For settings related to file attachments on releases, see the `attachment` section.

### Repository - Signing (`repository.signing`)

- `FORMAT`: **openpgp**: \[openpgp, ssh\]: Signing format that Forgejo should use, openpgp uses GPG and ssh uses OpenSSH.
- `SIGNING_KEY`: **default**: \[none, KEYID, default, path/to/ssh/key\]: Key to sign with. If `FORMAT` is set to **ssh** this should be set to an absolute path to an public OpenSSH key.
- `SIGNING_NAME` &amp; `SIGNING_EMAIL`: if a KEYID is provided as the `SIGNING_KEY`, use these as the Name and Email address of the signer. These should match publicized name and email address for the key.
- `INITIAL_COMMIT`: **always**: \[never, pubkey, twofa, always\]: Sign initial commit.
  - `never`: Never sign.
  - `pubkey`: Only sign if the user has a public key.
  - `twofa`: Only sign if the user is logged in with 2FA.
  - `always`: Always sign.
  - Options other than `never` and `always` can be combined as a comma-separated list.
- `DEFAULT_TRUST_MODEL`: **collaborator**: \[collaborator, committer, collaboratorcommitter\]: The default trust model used for verifying commits.
  - `collaborator`: Trust signatures signed by keys of collaborators.
  - `committer`: Trust signatures that match committers (This matches GitHub and will force Forgejo-signed commits to have Forgejo as the committer).
  - `collaboratorcommitter`: Trust signatures signed by keys of collaborators which match the committer.
- `WIKI`: **never**: \[never, pubkey, twofa, always, parentsigned\]: Sign commits to the wiki.
- `CRUD_ACTIONS`: **pubkey, twofa, parentsigned**: \[never, pubkey, twofa, parentsigned, always\]: Sign CRUD actions.
  - Options as above, with the addition of:
  - `parentsigned`: Only sign if the parent commit is signed.
- `MERGES`: **pubkey, twofa, basesigned, commitssigned**: \[never, pubkey, twofa, approved, basesigned, commitssigned, always\]: Sign merges.
  - `approved`: Only sign approved merges to a protected branch.
  - `basesigned`: Only sign if the parent commit in the base repo is signed.
  - `headsigned`: Only sign if the head commit in the head branch is signed.
  - `commitssigned`: Only sign if all the commits in the head branch to the merge point are signed.

## Repository - Local (`repository.local`)

- `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`)

Configuration to set the expected MIME type based on file extensions of downloadable files. Configuration consists of key-value pairs and file extensions starting with a leading `.`.

The following configuration sets the `Content-Type: application/vnd.android.package-archive` header when downloading files with the `.apk` file extension.

```ini
.apk=application/vnd.android.package-archive
```

## Badges (`badges`)

- `ENABLED`: **true**: Enable repository badges (via a generator like `shields.io`).
- `GENERATOR_URL_TEMPLATE`: **https://img.shields.io/badge/{{.label}}-{{.text}}-{{.color}}**: The URL template used for the badge generator service.

## CORS (`cors`)

- `ENABLED`: **false**: Enable CORS headers (disabled by default).
- `ALLOW_DOMAIN`: **\***: List of requesting origins that are allowed, e.g. "https://\*.example.com".
- `METHODS`: **GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS**: List of methods allowed to request.
- `MAX_AGE`: **10m**: Maximum time to cache the response.
- `ALLOW_CREDENTIALS`: **false**: Allow requests with credentials.
- `HEADERS`: **Content-Type,User-Agent**: Additional headers that are permitted in requests.
- `X_FRAME_OPTIONS`: **SAMEORIGIN**: Set the `X-Frame-Options` header value.

## UI (`ui`)

- `EXPLORE_PAGING_NUM`: **20**: Number of repositories shown on one explore page.
- `ISSUE_PAGING_NUM`: **20**: Number of issues shown on one page (for all pages that list issues, milestones, projects).
- `MEMBERS_PAGING_NUM`: **20**: Number of members shown in organization members list.
- `FEED_MAX_COMMIT_NUM`: **5**: Maximum number of commits shown in one activity feed.
- `FEED_PAGING_NUM`: **20**: Number of items displayed in the home feed.
- `SITEMAP_PAGING_NUM`: **20**: Number of items displayed in a single subsitemap.
- `GRAPH_MAX_COMMIT_NUM`: **100**: Maximum number of commits shown in the commit graph.
- `CODE_COMMENT_LINES`: **4**: Number of lines of code 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 installation.
- `SHOW_USER_EMAIL`: **true**: Whether the user's email should be shown on the Explore Users page.
- `THEMES`: **forgejo-auto, forgejo-light, forgejo-dark, gitea-auto, gitea-light, gitea-dark, forgejo-auto-deuteranopia-protanopia, forgejo-light-deuteranopia-protanopia, forgejo-dark-deuteranopia-protanopia, forgejo-auto-tritanopia, forgejo-light-tritanopia, forgejo-dark-tritanopia**: All available themes. **Allows** users to select personalized themes
  regardless of the value of `DEFAULT_THEME`.
- `MAX_DISPLAY_FILE_SIZE`: **8388608**: Maximum 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 aliases (:smile:) or Unicode emojis.
  For custom reactions, add a tightly cropped square image to public/assets/img/emoji/reaction_name.png.
- `REACTION_MAX_USER_NUM`: **10**: Change the number of users displayed in the reactions tooltip (triggered by mouse hover).
- `CUSTOM_EMOJIS`: **forgejo, gitea, codeberg, gitlab, git, github, gogs**: Additional Emojis not defined in the UTF-8 standard.
  By default, we support Forgejo (:forgejo:); to add more, copy them to public/assets/img/emoji/emoji_name.png and
  add them to this config.
- `DEFAULT_SHOW_FULL_NAME`: **false**: Whether the full name of 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 descriptions during repository searches on the explore page.
- `ONLY_SHOW_RELEVANT_REPOS`: **false**: Whether to only show relevant repos on the explore page when no keyword is specified, and the default sorting is used.
  A **repository** is considered irrelevant if it's a fork or if it has no metadata (no description, no icon, no topic).
- `AMBIGUOUS_UNICODE_DETECTION`: **true**: Detect ambiguous Unicode characters in files and show warnings.
- `SKIP_ESCAPE_CONTEXTS`: **\<empty\>**: \[diff, file-view, wiki\]: Comma-separated list of escape contexts where ambiguous Unicode detection should not be run. `wiki` is for content on the wiki pages, `file-view` is for (rendered) file content, and `diff` is for the diff of a commit and pull request.
- `PREFERRED_TIMESTAMP_TENSE`: **mixed**: The tense in which all timestamps should be rendered. Possible values are `absolute` time (e.g., 1970-01-01, 11:59) and `mixed`. `mixed` means most timestamps are rendered in relative time (e.g., 2 days ago).

### UI - Admin (`ui.admin`)

- `USER_PAGING_NUM`: **50**: Number of users shown on one page.
- `REPO_PAGING_NUM`: **50**: Number of repos shown on one page.
- `NOTICE_PAGING_NUM`: **25**: Number of notices shown on one page.
- `ORG_PAGING_NUM`: **50**: Number of organizations shown on one page.

### UI - User (`ui.user`)

- `REPO_PAGING_NUM`: **15**: Number of repos shown on one page.

### UI - Metadata (`ui.meta`)

- `AUTHOR`: **Forgejo - Beyond coding. We forge.**: Author meta tag for the homepage.
- `DESCRIPTION`: **Forgejo is a self-hosted lightweight software forge. Easy to install and low maintenance, it just does the job.**: Description meta tag for the homepage.
- `KEYWORDS`: **git,forge,forgejo**: Keywords meta tag for the homepage.

### UI - Notification (`ui.notification`)

- `MIN_TIMEOUT`: **10s**: These options control how often the notification endpoint is polled to update the notification count. On page load, the notification count will be checked after `MIN_TIMEOUT`. The timeout will increase to `MAX_TIMEOUT` by `TIMEOUT_STEP` if the notification count is unchanged. Set `MIN_TIMEOUT` to -1 to turn off polling.
- `MAX_TIMEOUT`: **60s**.
- `TIMEOUT_STEP`: **10s**.
- `EVENT_SOURCE_UPDATE_TIME`: **10s**: This setting determines how often the database is queried to update notification counts. If the browser client supports `EventSource` and `SharedWorker`, a `SharedWorker` will be used in preference to polling the notification endpoint. Set to **-1** to disable `EventSource`.

### 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.

### UI - CSV Files (`ui.csv`)

- `MAX_FILE_SIZE`: **524288** (512kb): Maximum allowed file size in bytes to render CSV files as tables. (Set to 0 for no limit).

## Markdown (`markdown`)

- `ENABLE_HARD_LINE_BREAK_IN_COMMENTS`: **true**: Render soft line breaks as hard line breaks in comments, which
  means a single newline character between paragraphs will cause a line break, and adding
  trailing whitespace to paragraphs is not necessary to force a line break.
- `ENABLE_HARD_LINE_BREAK_IN_DOCUMENTS`: **false**: Render soft line breaks as hard line breaks in documents, which
  means a single newline character between paragraphs will cause a line break, and adding
  trailing whitespace to paragraphs is not necessary to force a line break.
- `CUSTOM_URL_SCHEMES`: Use a comma-separated list (ftp,git,svn) to indicate additional
  URL hyperlinks to be rendered in Markdown. URLs beginning with http and https are
  always displayed. If this entry is empty, all URL schemes are allowed.
- `FILE_EXTENSIONS`: **.md,.markdown,.mdown,.mkd,.livemd**: List of file extensions that should be rendered/edited as Markdown. Separate the extensions with a comma. To render files without any extension as markdown, just put a comma.
- `ENABLE_MATH`: **true**: Enables detection of `\(...\)`, `\[...\]`, `$...$` and `$$...$$` blocks as math blocks.

## Server (`server`)

- `APP_DATA_PATH`: **_`AppWorkPath`_/data**: This is the default root path for storing data.
- `PROTOCOL`: **http**: \[http, https, fcgi, http+unix, fcgi+unix\]
  - Note: Value must be lowercase.
- `USE_PROXY_PROTOCOL`: **false**: Expect PROXY protocol headers on connections. Warning: this feature is [not working](https://codeberg.org/forgejo/forgejo/issues/633).
- `PROXY_PROTOCOL_TLS_BRIDGING`: **false**: When the protocol is https, expect PROXY protocol headers after TLS negotiation.
- `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 external URLs 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 are 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 the Forgejo server to serve the static
  assets, or copy the manually built Forgejo assets from `$FORGEJO_BUILD/public` to
  the assets location, e.g. `/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 the TCP socket
    defined by the `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 the TCP socket
    defined by the `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 the 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 the HTTP node. For different protocols, the default
  values are different. If `PROTOCOL` is `http+unix`, the default value is `http://unix/`.
  If `PROTOCOL` is `fcgi` or `fcgi+unix`, the default value is `%(PROTOCOL)s://%(HTTP_ADDR)s:%(HTTP_PORT)s/`.
  If listening on `0.0.0.0`, the default value is `%(PROTOCOL)s://localhost:%(HTTP_PORT)s/`; otherwise, the default
  value is `%(PROTOCOL)s://%(HTTP_ADDR)s:%(HTTP_PORT)s/`.
- `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.
- `PER_WRITE_TIMEOUT`: **30s**: Timeout for any write to the connection. (Set to -1 to
  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.
- `START_SSH_SERVER`: **false**: When enabled, use the built-in SSH server.
- `SSH_SERVER_USE_PROXY_PROTOCOL`: **false**: Expect PROXY protocol header on connections to the built-in SSH Server.
- `BUILTIN_SSH_SERVER_USER`: **%(RUN_USER)s**: Username to use for the built-in SSH Server.
- `SSH_USER`: **%(BUILTIN_SSH_SERVER_USER)s**: SSH username displayed in clone URLs. This is only for people who configure the SSH server themselves; in most cases, you want to leave this blank and modify `BUILTIN_SSH_SERVER_USER`.
- `SSH_DOMAIN`: **%(DOMAIN)s**: Domain name of this server, used for displayed clone URL.
- `SSH_PORT`: **22**: SSH port displayed in the 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_ROOT_PATH`: **~/.ssh**: Root path of the SSH directory.
- `SSH_CREATE_AUTHORIZED_KEYS_FILE`: **true**: Forgejo will create an `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`: **false**: Enable SSH Authorized Key Backup when rewriting all keys; default is false.
- `SSH_TRUSTED_USER_CA_KEYS`: **\<empty\>**: Specifies the public keys of certificate authorities that are trusted to sign user certificates for authentication. Multiple keys should be comma-separated. E.g. `ssh-<algorithm> <key>` or `ssh-<algorithm> <key1>, ssh-<algorithm> <key2>`. For more information, see `TrustedUserCAKeys` in the sshd config man pages. When empty, no file will be created and `SSH_AUTHORIZED_PRINCIPALS_ALLOW` will default to `off`.
- `SSH_TRUSTED_USER_CA_KEYS_FILENAME`: **`RUN_USER`/.ssh/gitea-trusted-user-ca-keys.pem**: Absolute path of the `TrustedUserCaKeys` file Forgejo will manage. If you're running your own SSH server and you want to use the Forgejo-managed file, you'll also need to modify your `sshd_config` to point to this file. The official docker image will automatically work without further configuration.
- `SSH_AUTHORIZED_PRINCIPALS_ALLOW`: **off** or **username, email**: \[off, username, email, anything\]: Specify the principals values that users are allowed to use as principal. When set to `anything`, no checks are done on the principal string. When set to `off`, authorized principals are not allowed to be set.
- `SSH_CREATE_AUTHORIZED_PRINCIPALS_FILE`: **false/true**: Forgejo will create an `authorized_principals` file by default when it is not using the internal SSH server and `SSH_AUTHORIZED_PRINCIPALS_ALLOW` is not `off`.
- `SSH_AUTHORIZED_PRINCIPALS_BACKUP`: **false/true**: Enable SSH Authorized Principals Backup when rewriting all keys; default is true if `SSH_AUTHORIZED_PRINCIPALS_ALLOW` is not `off`.
- `SSH_AUTHORIZED_KEYS_COMMAND_TEMPLATE`: **`{{.AppPath}} --config={{.CustomConf}} serv key-{{.Key.ID}}`**: Set the template for the command to be passed for authorized keys. Possible keys are: `AppPath`, `AppWorkPath`, `CustomConf`, `CustomPath`, `Key` - where `Key` is a `models/asymkey.PublicKey` and the others are strings which are shell-quoted.
- `SSH_SERVER_CIPHERS`: **chacha20-poly1305@openssh.com, aes128-ctr, aes192-ctr, aes256-ctr, aes128-gcm@openssh.com, aes256-gcm@openssh.com**: For the built-in SSH server, choose the ciphers to support for SSH connections; for system SSH, this setting has no effect.
- `SSH_SERVER_KEY_EXCHANGES`: **curve25519-sha256, ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group14-sha256, diffie-hellman-group14-sha1**: For the built-in SSH server, choose the key exchange algorithms to support for SSH connections; for system SSH, this setting has no effect.
- `SSH_SERVER_MACS`: **hmac-sha2-256-etm@openssh.com, hmac-sha2-256, hmac-sha1**: For the built-in SSH server, choose the MACs to support for SSH connections; for system SSH, this setting has no effect.
- `SSH_SERVER_HOST_KEYS`: **ssh/gitea.rsa, ssh/gogs.rsa**: For the built-in SSH server, choose the keypairs to offer as the host key. The private key should be at `SSH_SERVER_HOST_KEY` and the public key at `SSH_SERVER_HOST_KEY.pub`. Relative paths are made absolute relative to the `APP_DATA_PATH`. If no key exists, a 4096-bit RSA key will be created for you.
- `SSH_KEY_TEST_PATH`: **/tmp**: Directory to create temporary files in when testing public keys using `ssh-keygen`; default is the system temporary directory.
- `SSH_KEYGEN_PATH`: **\<empty\>**: Use `ssh-keygen` to parse public SSH keys. The value is passed to the shell. By default, Forgejo does the parsing itself.
- `SSH_EXPOSE_ANONYMOUS`: **false**: Enable exposure of SSH clone URL to anonymous visitors; default is false.
- `SSH_PER_WRITE_TIMEOUT`: **30s**: Timeout for any write to the SSH connections. (Set to
  -1 to disable all timeouts.)
- `SSH_PER_WRITE_PER_KB_TIMEOUT`: **10s**: Timeout per KB written to SSH connections.
- `MINIMUM_KEY_SIZE_CHECK`: **true**: Indicate whether to check minimum key size with corresponding type.

- `OFFLINE_MODE`: **true**: Disables use of CDNs for static files and Gravatar for profile pictures.
- `CERT_FILE`: **https/cert.pem**: Cert file path used for HTTPS. When chaining, the server certificate must come first, then intermediate CA certificates (if any). This is ignored if `ENABLE_ACME=true`. Paths are relative to _`CustomPath`_.
- `KEY_FILE`: **https/key.pem**: Key file path used for HTTPS. This is ignored if `ENABLE_ACME=true`. Paths are relative to _`CustomPath`_.
- `STATIC_ROOT_PATH`: **_`StaticRootPath`_**: Upper level of template and static files path.
- `APP_DATA_PATH`: **data** (**/data/gitea** on docker): Default path for application data. Relative paths will be made absolute against _`AppWorkPath`_.
- `STATIC_CACHE_TIME`: **6h**: Web browser cache time for static resources on `custom/`, `public/` and all uploaded avatars. Note that this cache is disabled when `RUN_MODE` is "dev".
- `ENABLE_GZIP`: **false**: Enable gzip compression for runtime-generated content; static resources excluded.
- `ENABLE_PPROF`: **false**: Application profiling (memory and CPU). For the "web" command, it listens on `localhost:6060`.
- `PPROF_DATA_PATH`: **_`AppWorkPath`_/data/tmp/pprof**: `PPROF_DATA_PATH`, use an absolute path when you start Forgejo as a service.
- `LANDING_PAGE`: **home**: Landing page for unauthenticated users \[home, explore, organizations, login, **custom**\]. Where custom would instead be any URL such as "/org/repo" or even `https://anotherwebsite.com`.
- `LFS_START_SERVER`: **false**: Enables Git LFS support.
- `LFS_CONTENT_PATH`: **%(APP_DATA_PATH)s/lfs**: Default LFS content path. (if it is on local storage.) **DEPRECATED** use settings in `[lfs]`.
- `LFS_JWT_SECRET`: **\<empty\>**: LFS authentication secret; change this to a unique string.
- `LFS_JWT_SECRET_URI`: **\<empty\>**: Instead of defining `LFS_JWT_SECRET` in the configuration, this option can be used to give Forgejo a path to a file that contains the secret (example value: `file:/etc/forgejo/lfs_jwt_secret`).
- `LFS_HTTP_AUTH_EXPIRY`: **24h**: LFS authentication validity period in `time.Duration`; pushes taking longer than this may fail.
- `LFS_MAX_FILE_SIZE`: **0**: Maximum allowed LFS file size in bytes (Set to 0 for no limit).
- `LFS_LOCKS_PAGING_NUM`: **50**: Maximum number of LFS Locks returned per page.
- `LFS_MAX_BATCH_SIZE`: **0:** When clients make LFS batch requests, reject them if there are more pointers than this number. '0' means 'unlimited'.

- `REDIRECT_OTHER_PORT`: **false**: If true and `PROTOCOL` is https, allows redirecting http requests on `PORT_TO_REDIRECT` to the https port Forgejo listens on.
- `REDIRECTOR_USE_PROXY_PROTOCOL`: **%(USE_PROXY_PROTOCOL)s**: Expect PROXY protocol header on connections to the https redirector.
- `PORT_TO_REDIRECT`: **80**: Port for the http redirection service to listen on. Used when `REDIRECT_OTHER_PORT` is true.
- `SSL_MIN_VERSION`: **TLSv1.2**: Set the minimum version of SSL/TLS support.
- `SSL_MAX_VERSION`: **\<empty\>**: Set the maximum version of SSL/TLS support.
- `SSL_CURVE_PREFERENCES`: **X25519,P256**: Set the preferred curves.
- `SSL_CIPHER_SUITES`: **ecdhe_ecdsa_with_aes_256_gcm_sha384,ecdhe_rsa_with_aes_256_gcm_sha384,ecdhe_ecdsa_with_aes_128_gcm_sha256,ecdhe_rsa_with_aes_128_gcm_sha256,ecdhe_ecdsa_with_chacha20_poly1305,ecdhe_rsa_with_chacha20_poly1305**: Set the preferred cipher suites.
  - If there is no hardware support for AES suites, by default the ChaCha suites will be preferred over the AES suites.
  - Supported suites as of Go 1.18 are:
    - TLS 1.0 - 1.2 cipher suites
      - "rsa_with_rc4_128_sha"
      - "rsa_with_3des_ede_cbc_sha"
      - "rsa_with_aes_128_cbc_sha"
      - "rsa_with_aes_256_cbc_sha"
      - "rsa_with_aes_128_cbc_sha256"
      - "rsa_with_aes_128_gcm_sha256"
      - "rsa_with_aes_256_gcm_sha384"
      - "ecdhe_ecdsa_with_rc4_128_sha"
      - "ecdhe_ecdsa_with_aes_128_cbc_sha"
      - "ecdhe_ecdsa_with_aes_256_cbc_sha"
      - "ecdhe_rsa_with_rc4_128_sha"
      - "ecdhe_rsa_with_3des_ede_cbc_sha"
      - "ecdhe_rsa_with_aes_128_cbc_sha"
      - "ecdhe_rsa_with_aes_256_cbc_sha"
      - "ecdhe_ecdsa_with_aes_128_cbc_sha256"
      - "ecdhe_rsa_with_aes_128_cbc_sha256"
      - "ecdhe_rsa_with_aes_128_gcm_sha256"
      - "ecdhe_ecdsa_with_aes_128_gcm_sha256"
      - "ecdhe_rsa_with_aes_256_gcm_sha384"
      - "ecdhe_ecdsa_with_aes_256_gcm_sha384"
      - "ecdhe_rsa_with_chacha20_poly1305_sha256"
      - "ecdhe_ecdsa_with_chacha20_poly1305_sha256"
    - TLS 1.3 cipher suites
      - "aes_128_gcm_sha256"
      - "aes_256_gcm_sha384"
      - "chacha20_poly1305_sha256"
    - Aliased names
      - "ecdhe_rsa_with_chacha20_poly1305" is an alias for "ecdhe_rsa_with_chacha20_poly1305_sha256"
      - "ecdhe_ecdsa_with_chacha20_poly1305" is an alias for "ecdhe_ecdsa_with_chacha20_poly1305_sha256"
- `ENABLE_ACME`: **false**: Flag to enable automatic certificate management via an ACME capable Certificate Authority (CA) server (default: Let's Encrypt). If enabled, `CERT_FILE` and `KEY_FILE` are ignored, and the CA must resolve `DOMAIN` to this Forgejo server. Ensure that DNS records are set and either port `80` or port `443` are accessible by the CA server (the public internet by default), and redirected to the appropriate ports `PORT_TO_REDIRECT` or `HTTP_PORT` respectively.
- `ACME_URL`: **\<empty\>**: The CA's ACME directory URL; e.g. for a self-hosted [smallstep CA server](https://github.com/smallstep/certificates), it can look like `https://ca.example.com/acme/acme/directory`. If left empty, it defaults to using Let's Encrypt's production CA (check `ACME_ACCEPTTOS` as well).
- `ACME_ACCEPTTOS`: **false**: This is an explicit check that you accept the terms of service of the ACME provider. The default is Let's Encrypt [terms of service](https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf).
- `ACME_DIRECTORY`: **https**: Directory that the certificate manager will use to cache information such as certs and private keys.
- `ACME_EMAIL`: **\<empty\>**: Email used for the ACME registration. Usually, it is to notify about problems with issued certificates.
- `ACME_CA_ROOT`: **\<empty\>**: The CA's root certificate. If left empty, it defaults to using the system's trust chain.
- `ALLOW_GRACEFUL_RESTARTS`: **true**: Perform a graceful restart on SIGHUP.
- `GRACEFUL_HAMMER_TIME`: **60s**: After a restart, the parent process will stop accepting new connections and will allow requests to finish before stopping. Shutdown will be forced if it takes longer than this time.
- `STARTUP_TIMEOUT`: **0**: Shuts down the server if startup takes longer than the provided time. Please note startup is determined by the opening of the listeners - HTTP/HTTPS/SSH. Indexers may take longer to start up and can have their own timeouts.

## Database (`database`)

- `DB_TYPE`: **sqlite3**: The database type in use \[mysql, postgres, sqlite3\].
- `HOST`: **127.0.0.1:3306**: Database host address and port or absolute path for a Unix socket \[mysql, postgres\] (e.g. /var/run/mysqld/mysqld.sock).
- `NAME`: **forgejo**: Database name.
- `USER`: **root**: Database username.
- `PASSWD`: **\<empty\>**: Database user password. Use \`your password\` or """your password""" for quoting if you use special characters in the password.
- `CHARSET_COLLATION`: **_empty_**: (MySQL only) Forgejo expects to use a case-sensitive collation for the database. Leave it empty to use the default collation.
- `SCHEMA`: **\<empty\>**: For PostgreSQL only, schema to use if different from "public". The schema must exist beforehand,
  the user must have creation privileges on it, and the user search path must be set to look into the schema first
  (e.g. `ALTER USER user SET SEARCH_PATH = schema_name,"$user",public;`).
- `SSL_MODE`: **disable**: SSL/TLS encryption mode for connecting to the database. This option is only applied for PostgreSQL and MySQL/MariaDB.
  - Valid values for MySQL/MariaDB:
    - `true`: Enable TLS with verification of the database server certificate against its root certificate. When selecting this option, make sure that the root certificate required to validate the database server certificate (e.g., the CA certificate) is on the system certificate store of both the database and Forgejo servers. See your system documentation for instructions on how to add a CA certificate to the certificate store.
    - `false`: Disable TLS.
    - `disable`: Alias for `false`, for compatibility with PostgreSQL.
    - `skip-verify`: Enable TLS without database server certificate verification. Use this option if you have a self-signed or invalid certificate on the database server.
    - `prefer`: Enable TLS with fallback to a non-TLS connection.
  - Valid values for PostgreSQL:
    - `disable`: Disable TLS.
    - `require`: Enable TLS without any verifications.
    - `verify-ca`: Enable TLS with verification of the database server certificate against its root certificate.
    - `verify-full`: Enable TLS and verify the database server name matches the given certificate in either the `Common Name` or `Subject Alternative Name` fields.
- `SQLITE_TIMEOUT`: **500**: Query timeout for SQLite3 only.
- `SQLITE_JOURNAL_MODE`: **""**: Change journal mode for SQlite3. Can be used to enable [WAL mode](https://www.sqlite.org/wal.html) when high load causes write congestion. See [SQlite3 docs](https://www.sqlite.org/pragma.html#pragma_journal_mode) for possible values. Defaults to the default for the database file, often DELETE.
- `ITERATE_BUFFER_SIZE`: **50**: Internal buffer size for iterating.
- `PATH`: **data/forgejo.db**: For SQLite3 only, the database file path.
- `LOG_SQL`: **false**: Log the executed SQL.
- `DB_RETRIES`: **10**: How many ORM init / DB connect attempts are allowed.
- `DB_RETRY_BACKOFF`: **3s**: `time.Duration` to wait before trying another ORM init / DB connect attempt, if failure occurred.
- `MAX_OPEN_CONNS` **100**: Database maximum open connections. Default is 100, which is the lowest default from PostgreSQL (MariaDB + MySQL default to 151). Setting this value higher than your database server can handle will lead to issues. If you require high concurrency, try to increase this value for both Forgejo and your database server.
- `MAX_IDLE_CONNS` **2**: Maximum idle database connections on the connection pool; default is 2 - this will be capped to `MAX_OPEN_CONNS`.
- `CONN_MAX_LIFETIME` **0 or 3s**: Sets the maximum amount of time a DB connection may be reused - default is 0, meaning there is no limit (except on MySQL/MariaDB where it is 3s - see #6804 & #7071).
- `CONN_MAX_IDLETIME` **0**: Sets the maximum amount of time a DB connection may be idle - default is 0, meaning there is no limit.
- `AUTO_MIGRATION` **true**: Whether to execute database models migrations automatically.
- `SLOW_QUERY_THRESHOLD`: **5s**: Sets the threshold for SQL queries before they are logged as slow queries in the log.

Please see #8540 & #8273 for further discussion of the appropriate values for `MAX_OPEN_CONNS`, `MAX_IDLE_CONNS` & `CONN_MAX_LIFETIME` and their
relation to port exhaustion.

## Indexer (`indexer`)

- `ISSUE_INDEXER_TYPE`: **bleve**: Issue indexer type, currently supported: `bleve`, `db`, `elasticsearch`, or `meilisearch`.
- `ISSUE_INDEXER_CONN_STR`: \*\*\*\*: Issue indexer connection string, available when `ISSUE_INDEXER_TYPE` is `elasticsearch` (e.g. http://elastic:password@localhost:9200) or `meilisearch` (e.g. http://:apikey@localhost:7700).
- `ISSUE_INDEXER_NAME`: **gitea_issues**: Issue indexer name, available when `ISSUE_INDEXER_TYPE` is `elasticsearch` or `meilisearch`.
- `ISSUE_INDEXER_PATH`: **indexers/issues.bleve**: Index file used for issue search; available when `ISSUE_INDEXER_TYPE` is `bleve`. Relative paths will be made absolute against _`AppWorkPath`_.

- `REPO_INDEXER_ENABLED`: **false**: Enables code search (uses a lot of disk space, about 6 times more than the repository size). If disabled, code search will be limited within a single repository.
- `REPO_INDEXER_REPO_TYPES`: **sources,forks,mirrors,templates**: Repo indexer units. The items to index could be `sources`, `forks`, `mirrors`, `templates`, or any combination of them separated by a comma. If empty, then it defaults to `sources` only. To disable fully, please see `REPO_INDEXER_ENABLED`.
- `REPO_INDEXER_TYPE`: **bleve**: Code search engine type, could be `bleve` or `elasticsearch`.
- `REPO_INDEXER_PATH`: **indexers/repos.bleve**: Index file used for code search.
- `REPO_INDEXER_CONN_STR`: \*\*\*\*: Code indexer connection string, available when `REPO_INDEXER_TYPE` is `elasticsearch`. i.e., http://elastic:password@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 the .txt extension. An empty list means include all files.
- `REPO_INDEXER_EXCLUDE`: **empty**: A comma-separated list of glob patterns (see https://github.com/gobwas/glob) to **exclude** from the index. Files that match this list will not be indexed, even if they match in `REPO_INDEXER_INCLUDE`.
- `REPO_INDEXER_EXCLUDE_VENDORED`: **true**: Exclude vendored files from the index.
- `MAX_FILE_SIZE`: **1048576**: Maximum size in bytes of files to be indexed.
- `STARTUP_TIMEOUT`: **30s**: If the indexer takes longer than this timeout to start - fail. (This timeout will be added to the hammer time above for child processes - as bleve will not start until the previous parent is shut down.) Set to -1 to never timeout.

## Queue (`queue` and `queue.*`)

Configuration at `[queue]` will set defaults for queues, with overrides for individual queues at `[queue.*]`. (However, see below.)

- `TYPE`: **level**: General queue type, currently supported: `level` (uses a LevelDB internally), `channel`, `redis`, `dummy`. Invalid types are treated as `level`.
- `DATADIR`: **queues/common**: Base DataDir for storing level queues. `DATADIR` for individual queues can be set in `queue.name` sections. Relative paths will be made absolute against `%(APP_DATA_PATH)s`.
- `LENGTH`: **100000**: 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. For `redis-cluster`, use `redis+cluster://127.0.0.1:6379/0`. Options can be set using query params. Similarly, LevelDB options can also be set using: **leveldb://relative/path?option=value** or **leveldb:///absolute/path?option=value**, and will override `DATADIR`.
- `QUEUE_NAME`: **\_queue**: The suffix for the 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.
- `MAX_WORKERS`: **(dynamic)**: Maximum number of worker go-routines for the queue. Default value is "CpuNum/2" clipped to between 1 and 10.

Forgejo creates the following non-unique queues:

- `code_indexer`
- `issue_indexer`
- `notification-service`
- `task`
- `mail`
- `push_update`

And the following unique queues:

- `repo_stats_update`
- `repo-archive`
- `mirror`
- `pr_patch_checker`

## Admin (`admin`)

- `DEFAULT_EMAIL_NOTIFICATIONS`: **enabled**: Default configuration for email notifications for users (user configurable). Options: enabled, onmention, disabled.
- `DISABLE_REGULAR_ORG_CREATION`: **false**: Disallow regular (non-admin) users from creating organizations.
- `USER_DISABLED_FEATURES`: **_empty_**: Disabled features for users, could be `deletion`, `manage_ssh_keys`, `manage_gpg_keys`; more features may be added in the future.
  - `deletion`: User cannot delete their own account.
  - `manage_ssh_keys`: User cannot configure SSH keys.
  - `manage_gpg_keys`: User cannot configure GPG keys.
- `EXTERNAL_USER_DISABLE_FEATURES`: **_empty_**: Comma-separated list of disabled features ONLY if the user has an external login type (e.g., LDAP, Oauth, etc.), could be `deletion`, `manage_ssh_keys`, `manage_gpg_keys`. This setting is independent from `USER_DISABLED_FEATURES` and supplements the behavior of `USER_DISABLED_FEATURES`.
  - `deletion`: User cannot delete their own account.
  - `manage_ssh_keys`: User cannot configure SSH keys.
  - `manage_gpg_keys`: User cannot configure GPG keys.
- `SEND_NOTIFICATION_EMAIL_ON_NEW_USER`: **false**: Enable email notifications to instance admins on new user sign-up. It requires `ENABLE_NOTIFY_MAIL` to be true.

## Security (`security`)

- `INSTALL_LOCK`: **false**: Controls access to the installation page. When set to "true", the installation page is not accessible.
- `SECRET_KEY`: **\<random at every install\>**: Global secret key. This key is VERY IMPORTANT; if you lose it, data encrypted by it (like 2FA secrets) can no longer be decrypted.
- `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`: **31**: Cookie lifetime, in days.
- `COOKIE_REMEMBER_NAME`: **gitea_incredible**: Name of the cookie used to store authentication
  information.
- `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: Header name for reverse proxy
  authentication.
- `REVERSE_PROXY_AUTHENTICATION_EMAIL`: **X-WEBAUTH-EMAIL**: Header name for reverse proxy
  authentication provided email.
- `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`: **X-WEBAUTH-FULLNAME**: Header name for reverse proxy
  authentication provided full name.
- `REVERSE_PROXY_LIMIT`: **1**: Interpret the `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.
- `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by commas 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 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 may be harmful to your website or your operating system.
  Setting this to true does not change existing hooks in git repos; adjust them beforehand if necessary.
- `DISABLE_WEBHOOKS`: **false**: Set to `true` to disable the webhooks feature.
- `ONLY_ALLOW_PUSH_IF_GITEA_ENVIRONMENT_SET`: **true**: Set to `false` to allow local users to push to **Forgejo** 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 paths on the server.
- `INTERNAL_TOKEN`: **\<random at every install if no uri set\>**: Secret used to validate communication within the Forgejo binary.
- `INTERNAL_TOKEN_URI`: **\<empty\>**: Instead of defining `INTERNAL_TOKEN` in the configuration, this option can be used to give Forgejo a path to a file that contains the internal token (example value: `file:/etc/forgejo/internal_token`).
- `PASSWORD_HASH_ALGO`: **pbkdf2**: The hash algorithm to use \[argon2, pbkdf2, pbkdf2_v1, pbkdf2_hi, scrypt, bcrypt\]; argon2 and scrypt require significant amounts of memory.
  - Note: The default parameters for `pbkdf2` hashing have changed - the previous settings are available as `pbkdf2_v1` but are not recommended.
  - The hash functions may be tuned by using `$` after the algorithm:
    - `argon2$<time>$<memory>$<threads>$<key-length>`
    - `bcrypt$<cost>`
    - `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`
    - `pbkdf2_v1`: `pbkdf2$10000$50`
    - `pbkdf2_v2`: `pbkdf2$50000$50`
    - `pbkdf2_hi`: `pbkdf2$320000$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 the CSRF cookie.
- `MIN_PASSWORD_LENGTH`: **8**: Minimum password length for new users.
- `PASSWORD_COMPLEXITY`: **off**: Comma-separated list of character classes required to pass minimum complexity. If left empty or no valid values are specified, checking is disabled (off):
  - 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 such 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 an LRU cache as a balance between performance and security.
- `DISABLE_QUERY_AUTH_TOKEN`: **false**: Reject API tokens sent in the URL query string (Accept Header-based API tokens only).

## Camo (`camo`)

- `ENABLED`: **false**: Enable media proxy; we support images only at the moment.
- `SERVER_URL`: **\<empty\>**: URL of the camo server; it **is required** if camo is enabled.
- `HMAC_KEY`: **\<empty\>**: Provide the HMAC key for encoding URLs; it **is required** if camo is enabled.
- `ALWAYS`: **false**: Set to true to use camo for both HTTP and HTTPS content; otherwise, only non-HTTPS URLs are proxied.

## OpenID (`openid`)

- `ENABLE_OPENID_SIGNIN`: **true**: Allow authentication via OpenID.
- `ENABLE_OPENID_SIGNUP`: **! DISABLE_REGISTRATION**: Allow registering via OpenID.
- `WHITELISTED_URIS`: **\<empty\>**: If non-empty, a list of POSIX regex patterns matching
  OpenID URIs to permit.
- `BLACKLISTED_URIS`: **\<empty\>**: If non-empty, a list of POSIX regex patterns matching
  OpenID URIs 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).
- `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:
  - `userid` - use the userid / sub attribute
  - `nickname` - use the nickname attribute
  - `email` - use the username part of the email attribute
  - Note: `nickname` and `email` options will normalize input strings using the following criteria:
    - diacritics are removed
    - the characters in the set `['´\x60]` are removed
    - the characters in the set `[\s~+]` are replaced with `-`
- `UPDATE_AVATAR`: **false**: Update avatar if available from the OAuth2 provider. Update will be performed on each login.
- `ACCOUNT_LINKING`: **login**: How to handle if an account / email already exists:
  - disabled - show an error
  - login - show an account linking login
  - auto - automatically link with the account (Please be aware that this will grant access to an existing account just because the same username or email is provided. You must make sure that this does not cause issues with your authentication providers.)

## Service (`service`)

- `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.
- `REGISTER_EMAIL_CONFIRM`: **false**: Enable this to ask for mail confirmation of registration.
  Requires `Mailer` to be enabled.
- `REGISTER_MANUAL_CONFIRM`: **false**: Enable this to manually confirm new registrations.
  Requires `REGISTER_EMAIL_CONFIRM` to be disabled.
- `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create
  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.
- `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page or to use the 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.
- `ENABLE_BASIC_AUTHENTICATION`: **true**: Disable this to disallow authentication 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. Furthermore, this only disables BASIC authentication using the
  password - not tokens or OAuth Basic.
- `ENABLE_INTERNAL_SIGNIN`: **true**: Enables the built-in authentication flow. Disable this to force users to log in through external authentication sources.
- `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable this to allow reverse proxy authentication for web requests.
- `ENABLE_REVERSE_PROXY_AUTHENTICATION_API`: **false**: Enable this to allow reverse proxy authentication for API requests; the reverse proxy is responsible for ensuring that no CSRF is possible.
- `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration
  for reverse authentication.
- `ENABLE_REVERSE_PROXY_EMAIL`: **false**: Enable this to allow auto-registration with a
  provided email rather than a generated email.
- `ENABLE_REVERSE_PROXY_FULL_NAME`: **false**: Enable this to allow auto-registration with a
  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 must also 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 must also 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.
- `RECAPTCHA_URL`: **https://www.google.com/recaptcha/**: Set the reCAPTCHA URL - allows the use of recaptcha.net.
- `HCAPTCHA_SECRET`: **""**: Sign up at https://www.hcaptcha.com/ to get a secret for hCaptcha.
- `HCAPTCHA_SITEKEY`: **""**: Sign up at https://www.hcaptcha.com/ to get a sitekey for hCaptcha.
- `MCAPTCHA_SECRET`: **""**: Go to your mCaptcha instance to get a secret for mCaptcha.
- `MCAPTCHA_SITEKEY`: **""**: Go to your mCaptcha instance to get a sitekey for mCaptcha.
- `MCAPTCHA_URL` **https://demo.mcaptcha.org/**: Set the mCaptcha URL.
- `CF_TURNSTILE_SECRET` **""**: Go to https://dash.cloudflare.com/?to=/:account/turnstile to get a secret for Cloudflare Turnstile.
- `CF_TURNSTILE_SITEKEY` **""**: Go to https://dash.cloudflare.com/?to=/:account/turnstile to get a sitekey for Cloudflare Turnstile.
- `DEFAULT_KEEP_EMAIL_PRIVATE`: **false**: By default, set users to keep their email address private.
- `DEFAULT_ALLOW_CREATE_ORGANIZATION`: **true**: Allow new users to create organizations by default.
- `DEFAULT_USER_IS_RESTRICTED`: **false**: Give new users restricted permissions by default.
- `DEFAULT_ENABLE_DEPENDENCIES`: **true**: Enable this to have dependencies enabled by default.
- `USER_LOCATION_MAP_URL`: **""**: A map service URL to show a user's location on a map. The location will be appended to the URL as an escaped query parameter. In Forgejo, [OpenStreetMap](https://openstreetmap.org) is used by default.
- `ALLOW_CROSS_REPOSITORY_DEPENDENCIES` : **true** Enable this to allow dependencies on issues from any repository where the user is granted access.
- `ENABLE_USER_HEATMAP`: **true**: Enable this to display the heatmap on users' profiles.
- `ENABLE_TIMETRACKING`: **true**: Enable the Timetracking feature.
- `DEFAULT_ENABLE_TIMETRACKING`: **true**: Allow repositories to use timetracking by default.
- `DEFAULT_ALLOW_ONLY_CONTRIBUTORS_TO_TRACK_TIME`: **true**: Only allow users with write permissions to track time.
- `EMAIL_DOMAIN_ALLOWLIST`: **\<empty\>**: If non-empty, comma-separated list of domain names that can be used to register on this instance; wildcard is supported.
- `EMAIL_DOMAIN_BLOCKLIST`: **\<empty\>**: If non-empty, comma-separated list of domain names that cannot be used to register on this instance; wildcard is supported.
- `EMAIL_DOMAIN_BLOCK_DISPOSABLE`: **false**: Enable this to append a list of known temporary/disposable email domains as compiled by [disposable-email-domains](https://github.com/disposable-email-domains/disposable-email-domains) to the block list.
- `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 organization 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.
- `DEFAULT_USER_VISIBILITY`: **public**: Set the default visibility mode for users, either "public", "limited", or "private".
- `ALLOWED_USER_VISIBILITY_MODES`: **public,limited,private**: Set which visibility modes a user can have.
- `DEFAULT_ORG_VISIBILITY`: **public**: Set the default visibility mode for organisations, either "public", "limited", or "private".
- `DEFAULT_ORG_MEMBER_VISIBLE`: **false**: True will make the membership of users visible when added to the organisation.
- `ALLOW_ONLY_INTERNAL_REGISTRATION`: **false**: Set to true to force registration only via Forgejo.
- `ALLOW_ONLY_EXTERNAL_REGISTRATION`: **false**: Set to true to force registration only using third-party services.
- `NO_REPLY_ADDRESS`: **noreply.DOMAIN**: Value for the domain part of the user's email address in the Git log if the user has set KeepEmailPrivate to true. DOMAIN resolves to the value in `server.DOMAIN`.
  The user's email will be replaced with a concatenation of the user name in lower case, "@", and `NO_REPLY_ADDRESS`.
- `USER_DELETE_WITH_COMMENTS_MAX_TIME`: **0**: Minimum amount of time a user must exist before comments are kept when the user is deleted.
- `VALID_SITE_URL_SCHEMES`: **http, https**: Valid site URL schemes for user profiles.
- `USERNAME_COOLDOWN_PERIOD`: **0**: The cooldown period in days before a username previously used by another user can be claimed by someone other than the original user. If you enter a non-positive number here, the cooldown period is deactivated, and previously used usernames can be claimed immediately.
- `MAX_USER_REDIRECTS`: **0**: The number of user redirects that a user can keep. The oldest entry is removed when a new user redirection is created. The default value is **5** if `USERNAME_COOLDOWN_PERIOD` is set to a positive value.

### Service - Explore (`service.explore`)

- `REQUIRE_SIGNIN_VIEW`: **false**: Only allow signed-in users to view the explore section.
- `DISABLE_USERS_PAGE`: **false**: Disable user listing in the explore section.
- `DISABLE_ORGANIZATIONS_PAGE`: **false**: Disable organization listing in the explore section.
- `DISABLE_CODE_PAGE`: **false**: Disable the code search page in the explore section.

## SSH Minimum Key Sizes (`ssh.minimum_key_sizes`)

Define allowed algorithms and their minimum key length (use -1 to disable a type):

- `ED25519`: **256**
- `ECDSA`: **256**
- `RSA`: **3071**: We set 3071 here because an otherwise valid 3072-bit RSA key can be reported as having a length of 3071.
- `DSA`: **-1**: DSA is now disabled by default. Set to **1024** to re-enable, but ensure you may need to reconfigure your SSHD provider.

## Webhook (`webhook`)

- `QUEUE_LENGTH`: **1000**: Hook task queue length. Use caution when editing this value.
- `DELIVER_TIMEOUT`: **5**: Delivery timeout (seconds) for shooting webhooks.
- `ALLOWED_HOST_LIST`: **external**: Webhooks can only call allowed hosts for security reasons. Comma-separated list.
  - Built-in networks:
    - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6; localhost is included.
    - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7). Also called LAN/Intranet.
    - `external`: A valid non-private unicast IP; you can access all hosts on the public internet.
    - `*`: All hosts are allowed.
  - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6.
  - Wildcard hosts: `*.example.com`, `192.168.100.*`.
- `SKIP_TLS_VERIFY`: **false**: Allow insecure certificates.
- `PAGING_NUM`: **10**: Number of webhook history events shown on one page.
- `PAYLOAD_COMMIT_LIMIT`: **15**: The maximum number of commits sent in the payload for a `push` webhook event; if there are more commits, only the most recent ones are sent.
- `PROXY_URL`: **\<empty\>**: Proxy server URL, supports http://, https://, socks5://; blank will follow environment http_proxy/https_proxy. If not given, will use the 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 the global proxy setting.

## Mailer (`mailer`)

- `ENABLED`: **false**: Enable to use a mail service.
- `PROTOCOL`: **\<empty\>**: Mail server protocol. One of "smtp", "smtps", "smtp+starttls", "smtp+unix", "sendmail", "dummy".
  - SMTP family: if your provider does not explicitly say which protocol it uses but does provide a port, you can set `SMTP_PORT` instead, and this will be inferred.
  - **sendmail**: Use the operating system's `sendmail` command instead of SMTP. This is common on Linux systems.
  - **dummy**: Send email messages to the log as a testing phase.
  - Note that enabling `sendmail` will ignore all other `mailer` settings except `ENABLED`, `FROM`, `SUBJECT_PREFIX`, and `SENDMAIL_PATH`.
  - 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 the 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
  - 465: SMTPS (SMTP Secure)
  - 587: StartTLS
- `USE_CLIENT_CERT`: **false**: Use client certificate for TLS/SSL.
- `CLIENT_CERT_FILE`: **custom/mailer/cert.pem**: Client certificate file.
- `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 the mailing user (usually the sender's e-mail address).
- `PASSWD`: **\<empty\>**: Password of the 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 the SMTP host is localhost.
- `ENABLE_HELO`: **true**: Enable HELO operation.
- `HELO_HOSTNAME`: **(retrieved from system)**: HELO hostname.
- `FROM`: **\<empty\>**: Mail from address, RFC 5322. This can be just an email address, or the "Name" \<email@example.com\> format.
- `ENVELOPE_FROM`: **\<empty\>**: Address set as the From address on the SMTP mail envelope. Set to `<>` to send an empty address.
- `SUBJECT_PREFIX`: **\<empty\>**: Prefix to be placed before e-mail subject lines.
- `SENDMAIL_PATH`: **sendmail**: The location of sendmail on the operating system (can be command or full path).
- `SENDMAIL_ARGS`: **\<empty\>**: Specify any extra sendmail arguments. (NOTE: you should be aware that email addresses can look like options - if your `sendmail` command takes options, you must set the option terminator `--`).
- `SENDMAIL_TIMEOUT`: **5m**: Default timeout for sending email through sendmail.
- `SENDMAIL_CONVERT_CRLF`: **true**: Most versions of sendmail prefer LF line endings rather than CRLF line endings. Set this to false if your version of sendmail requires CRLF line endings.
- `SEND_BUFFER_LEN`: **100**: Buffer length of the mailing queue. **DEPRECATED** use `LENGTH` in `[queue.mailer]`.
- `SEND_AS_PLAIN_TEXT`: **false**: Send mails only in plain text, without an HTML alternative.

## Incoming Email (`email.incoming`)

- `ENABLED`: **false**: Enable handling of incoming emails.
- `REPLY_TO_ADDRESS`: **\<empty\>**: The email address including the `%{token}` placeholder that will be replaced per user/action. Example: `incoming+%{token}@example.com`. The placeholder must appear in the user part of the address (before the `@`).
- `HOST`: **\<empty\>**: IMAP server host.
- `PORT`: **\<empty\>**: IMAP server port.
- `USERNAME`: **\<empty\>**: Username of the receiving account.
- `PASSWORD`: **\<empty\>**: Password of the receiving account.
- `USE_TLS`: **false**: Whether the IMAP server uses TLS.
- `SKIP_TLS_VERIFY`: **false**: If set to `true`, completely ignores server certificate validation errors. This option is unsafe.
- `MAILBOX`: **INBOX**: The mailbox name where incoming mail will end up.
- `DELETE_HANDLED_MESSAGE`: **true**: Whether handled messages should be deleted from the mailbox.
- `MAXIMUM_MESSAGE_SIZE`: **10485760**: Maximum size of a message to handle. Bigger messages are ignored. Set to 0 to allow every size.

## Cache (`cache`)

- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, `redis-cluster`, `twoqueue`, or `memcache`. (`twoqueue` represents a size-limited LRU cache.)
  - Refer to the [Recommended Settings](../recommendations/#cacheadapter) for more information about cache adapters.
- `INTERVAL`: **60**: Garbage Collection interval (sec), for `memory` and `twoqueue` cache only.
- `HOST`: **\<empty\>**: Connection string for `redis`, `redis-cluster`, and `memcache`. For `twoqueue`, sets configuration for the queue.
  - Redis: `redis://:password@127.0.0.1:6379/0?pool_size=100&idle_timeout=180s` (assuming `macaron` was a placeholder for password)
  - Redis-cluster: `redis+cluster://:password@127.0.0.1:6379/0?pool_size=100&idle_timeout=180s` (assuming `macaron` was a placeholder for password)
  - Redis-sentinel: `redis+sentinel://127.0.0.1:26379/0?mastername=mymaster`
  - Memcache: `127.0.0.1:9090;127.0.0.1:9091`
  - TwoQueue LRU cache: `{"size":50000,"recent_ratio":0.25,"ghost_ratio":0.5}` or `50000` representing the maximum number of objects stored in the cache.
- `ITEM_TTL`: **16h**: Time to keep items in cache if not used. Setting it to -1 disables caching.

## Cache - LastCommitCache settings (`cache.last_commit`)

- `ITEM_TTL`: **8760h**: Time to keep items in cache if not used. Setting it to -1 disables caching.
- `COMMITS_COUNT`: **1000**: Only enable the cache when the repository's commit count is greater than this value.

## Session (`session`)

- `PROVIDER`: **memory**: Session engine provider \[memory, file, redis, redis-cluster, db, mysql, couchbase, memcache, postgres\]. Setting `db` will reuse the configuration in `[database]`.
- `PROVIDER_CONFIG`: **data/sessions**: For `file`, the root path; for `db`, empty (database config will be used); for others, the connection string. Relative paths will be made absolute against _`AppWorkPath`_.
- `COOKIE_SECURE`:**empty**: `true` or `false`. Enable this to force using HTTPS for all session access. If not set, it defaults to `true` if the `ROOT_URL` is an HTTPS URL.
- `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.
- `SAME_SITE`: **lax** \[strict, lax, none\]: Set the SameSite setting for the cookie. Please note that setting this to `strict` can break the login via an external OAuth2 provider - this is a [known bug](https://codeberg.org/forgejo/forgejo/issues/1205).

## Picture (`picture`)

- `GRAVATAR_SOURCE`: **gravatar**: Can be `gravatar`, `duoshuo`, or anything like
  `http://cn.gravatar.com/avatar/`.
- `DISABLE_GRAVATAR`: **false**: Enable this to use local avatars only. **DEPRECATED [v1.18+]** moved to the database. Use the admin panel to configure.
- `ENABLE_FEDERATED_AVATAR`: **false**: Enable support for federated avatars.

- `AVATAR_STORAGE_TYPE`: **default**: Storage type [as explained in detail in the storage documentation](../storage/).
- `AVATAR_UPLOAD_PATH`: **data/avatars**: Path to store user avatar image files.
- `AVATAR_MAX_WIDTH`: **4096**: Maximum avatar image width in pixels.
- `AVATAR_MAX_HEIGHT`: **4096**: Maximum avatar image height in pixels.
- `AVATAR_MAX_FILE_SIZE`: **1048576** (1MiB): Maximum avatar image file size in bytes.
- `AVATAR_MAX_ORIGIN_SIZE`: **262144** (256KiB): If the uploaded file is not larger than this byte size, the image will be used as is, without resizing/converting.
- `AVATAR_RENDERED_SIZE_FACTOR`: **2**: The multiplication factor for rendered avatar images. Larger values result in finer rendering on HiDPI devices.

- `REPOSITORY_AVATAR_STORAGE_TYPE`: **default**: Storage type defined [as explained in detail in the storage documentation](../storage/).
- `REPOSITORY_AVATAR_UPLOAD_PATH`: **data/repo-avatars**: Path to store repository avatar image files.
- `REPOSITORY_AVATAR_FALLBACK`: **none**: How Forgejo deals with missing repository avatars:
  - none = no avatar will be displayed
  - random = a random avatar will be generated
  - image = the default image will be used (which is set in `REPOSITORY_AVATAR_FALLBACK_IMAGE`)
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: Image used as the default repository avatar (if `REPOSITORY_AVATAR_FALLBACK` is set to image and none was uploaded).

## Project (`project`)

Default templates for project boards:

- `PROJECT_BOARD_BASIC_KANBAN_TYPE`: **To Do, In Progress, Done**
- `PROJECT_BOARD_BUG_TRIAGE_TYPE`: **Needs Triage, High Priority, Low Priority, Closed**

## Issue and pull request attachments (`attachment`)

- `ENABLED`: **true**: Whether issue and pull request attachments are enabled.
- `ALLOWED_TYPES`: **.avif,.cpuprofile,.csv,.dmp,.docx,.fodg,.fodp,.fods,.fodt,.gif,.gz,.jpeg,.jpg,.json,.jsonc,.log,.md,.mov,.mp4,.odf,.odg,.odp,.ods,.odt,.patch,.pdf,.png,.pptx,.svg,.tgz,.txt,.webm,.webp,.xls,.xlsx,.zip**: Comma-separated list of allowed file extensions (`.zip`), MIME types (`text/plain`), or wildcard types (`image/*`, `audio/*`, `video/*`). Empty value or `*/*` allows all types.
- `MAX_SIZE`: **2048**: Maximum size (MB).
- `MAX_FILES`: **5**: Maximum number of attachments that can be uploaded at once.

Additional settings can be included in this section to specify where the data is stored, as [explained in detail in the storage documentation](../storage/).

## LFS client (`lfs_client`)

- `BATCH_SIZE`: **20**: When mirroring an upstream LFS endpoint, limit the number of pointers in each batch request to this number.
- `BATCH_OPERATION_CONCURRENCY`: **8**: Limit the number of concurrent upload/download operations within a batch.

## Log (`log`)

When configuring logging, also consult the detailed [logging documentation](../logging-documentation/).

- `ROOT_PATH`: **\<empty\>**: Root path for log files.
- `MODE`: **console**: Logging mode. For multiple modes, use a comma to separate values. You can configure each mode in per-mode log subsections `[log.writer-mode-name]`.
- `LEVEL`: **Info**: General log level. \[Trace, Debug, Info, Warn, Error, Critical, Fatal, None\]
- `STACKTRACE_LEVEL`: **None**: Default log level at which to create stack traces (rarely useful, do not set it). \[Trace, Debug, Info, Warn, Error, Critical, Fatal, None\]
- `ENABLE_SSH_LOG`: **false**: Save SSH log to the log file.
- `logger.access.MODE`: **\<empty\>**: The "access" logger.
- `logger.router.MODE`: **,**: The "router" logger; a single comma means it will use the default `MODE` above.
- `logger.xorm.MODE`: **,**: The "xorm" logger.

### Access Log (`log`)

- `ACCESS_LOG_TEMPLATE`: **`{{.Ctx.RemoteHost}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}" "{{.Ctx.Req.UserAgent}}"`**: Sets the template used to create the access log.
  - The following variables are available:
  - `Ctx`: the `context.Context` of the request.
  - `Identity`: the SignedUserName or `"-"` if not logged in.
  - `Start`: the start time of the request.
  - `ResponseWriter`: the `responseWriter` from the request.
  - `RequestID`: the value matching `REQUEST_ID_HEADERS` (default: `-`, if not matched).
  - You must be very careful to ensure that this template does not throw errors or panics, as this template runs outside the panic/recovery script.
- `REQUEST_ID_HEADERS`: **\<empty\>**: You can configure multiple values, split by commas, here. It will match in the order of configuration, and the first match will be printed in the access log.
  - e.g.,
  - In the Request Header: X-Request-ID: **test-id-123**
  - Configuration in app.ini: REQUEST_ID_HEADERS = X-Request-ID
  - Print in log: 127.0.0.1:58384 - - [14/Feb/2023:16:33:51 +0800] "**test-id-123**" ...

### Log subsections (`log.<writer-mode-name>`)

- `MODE`: **name**: Sets the mode of this log writer. Defaults to the provided subsection name. This allows you to have two different file loggers at different levels.
- `LEVEL`: **log.LEVEL**: Sets the log-level of this writer. Defaults to the `LEVEL` set in the global `[log]` section.
- `STACKTRACE_LEVEL`: **log.STACKTRACE_LEVEL**: Sets the log level at which to log stack traces.
- `EXPRESSION`: **""**: A regular expression to match either the function name, file, or message. Defaults to empty. Only log messages that match the expression will be saved in the logger.
- `FLAGS`: **stdflags**: A comma-separated string representing the log flags. Defaults to `stdflags`, which represents the prefix: `2009/01/23 01:23:23 ...a/b/c/d.go:23:runtime.Caller() [I]: message`. `none` means don't prefix log lines. See [the FLAGS section of the logging documentation](../logging-documentation/#flags) for more information.
- `PREFIX`: **""**: An additional prefix for every log line in this logger. Defaults to empty.
- `COLORIZE`: **false**: Whether to colorize the log lines.

### Console log mode (`log.console`, or `MODE=console`)

The defaults of the console change if Forgejo detects that stdout and/or stderr are connected to systemd-journald (which will happen automatically when Forgejo is running under systemd). See the [journald section in the logging documentation](../logging-documentation/#journald-mode).

- For the console logger, `COLORIZE` will default to `true` if not on Windows or if the terminal is determined to be able to display color.
- `STDERR`: **false** (journald: **true**): Use Stderr instead of Stdout.
- `FLAGS`: **stdflags** (journald: **journaldflags**): Instead of color or text annotations, machine-readable prefixes are used that can be parsed by systemd-journald.

### File log mode (`log.file`, or `MODE=file`)

- `FILE_NAME`: Set the file name for this logger. Defaults to `forgejo.log` (exception: access log defaults to `access.log`). If relative, it will be relative to the `ROOT_PATH`.
- `LOG_ROTATE`: **true**: Rotate the log files.
- `MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file; 28 represents 256MB.
- `DAILY_ROTATE`: **true**: Rotate logs daily.
- `MAX_DAYS`: **7**: Delete the log file after n days.
- `COMPRESS`: **true**: Compress old log files by default with gzip.
- `COMPRESSION_LEVEL`: **-1**: Compression level.

### Conn log mode (`log.conn`, or `MODE=conn`)

- `RECONNECT_ON_MSG`: **false**: Reconnect host for every single message.
- `RECONNECT`: **false**: Try to reconnect when the connection is lost.
- `PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix", or "udp".
- `ADDR`: **:7020**: Sets the address to connect to.

## Cron (`cron`)

- `ENABLED`: **false**: Enable to run all cron tasks periodically with default settings.
- `RUN_AT_START`: **false**: Run cron tasks at application start-up.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.

- `SCHEDULE` accepts formats:
  - Full crontab specs, e.g. `* * * * * ?`
  - Descriptors, e.g. `@midnight`, `@every 1h30m` ...
  - See more: [cron documentation](https://pkg.go.dev/github.com/gogs/cron@v0.0.0-20171120032916-9f6c956d3e14)

### Basic cron tasks - enabled by default

#### Cron - Cleanup old repository archives (`cron.archive_cleanup`)

- `ENABLED`: **true**: Enable service.
- `RUN_AT_START`: **true**: Run tasks at start-up time (if ENABLED).
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository archive cleanup, e.g., `@every 1h`.
- `OLDER_THAN`: **24h**: Archives created more than `OLDER_THAN` ago are subject to deletion, e.g., `12h`.

#### Cron - Update Mirrors (`cron.update_mirrors`)

- `SCHEDULE`: **@every 10m**: Cron syntax for scheduling update mirrors, e.g., `@every 3h`.
- `PULL_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit; 0 will result in no mirrors being queued, effectively disabling pull mirror updating).
- `PUSH_LIMIT`: **50**: Limit the number of mirrors added to the queue to this number (negative values mean no limit; 0 will result in no mirrors being queued, effectively disabling push mirror updating).

#### Cron - Repository Health Check (`cron.repo_health_check`)

- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository health check.
- `TIMEOUT`: **60s**: Time duration syntax for health check execution timeout.
- `ARGS`: **\<empty\>**: Arguments for the command `git fsck`, e.g., `--unreachable --tags`. See more on http://git-scm.com/docs/git-fsck

#### Cron - Repository Statistics Check (`cron.check_repo_stats`)

- `RUN_AT_START`: **true**: Run repository statistics check at start time.
- `SCHEDULE`: **@midnight**: Cron syntax for scheduling repository statistics check.

#### Cron - Cleanup hook_task Table (`cron.cleanup_hook_task_table`)

- `ENABLED`: **true**: Enable cleanup hook_task job.
- `RUN_AT_START`: **false**: Run cleanup hook_task at start time (if ENABLED).
- `SCHEDULE`: **@midnight**: Cron syntax for cleaning the hook_task table.
- `CLEANUP_TYPE`: **OlderThan**: `OlderThan` or `PerWebhook`. Method to clean up the hook_task table, either by age (i.e., how long ago the hook_task record was delivered) or by the number to keep per webhook (i.e., keep the most recent x deliveries per webhook).
- `OLDER_THAN`: **168h**: If `CLEANUP_TYPE` is set to `OlderThan`, then any delivered hook_task records older than this expression will be deleted.
- `NUMBER_TO_KEEP`: **10**: If `CLEANUP_TYPE` is set to `PerWebhook`, this is the number of hook_task records to keep for a webhook (i.e., keep the most recent x deliveries).

#### Cron - Cleanup expired packages (`cron.cleanup_packages`)

- `ENABLED`: **true**: Enable cleanup expired packages job.
- `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Notify every time this job runs.
- `SCHEDULE`: **@midnight**: Cron syntax for the job.
- `OLDER_THAN`: **24h**: Unreferenced package data created more than `OLDER_THAN` ago is subject to deletion.

#### Cron - Update Migration Poster ID (`cron.update_migration_poster_id`)

- `SCHEDULE`: **@midnight**: Interval as a duration between each synchronization; it will always attempt synchronization when the instance starts.

#### Cron - Sync External Users (`cron.sync_external_users`)

- `SCHEDULE`: **@midnight**: Interval as a duration between each synchronization; it will always attempt synchronization when the instance starts.
- `UPDATE_EXISTING`: **true**: Create new users, update existing user data, and disable users that are not in the external source anymore (default), or only create new users if `UPDATE_EXISTING` is set to false.

#### Cron - Cleanup Expired Actions Assets (`cron.cleanup_actions`)

- `ENABLED`: **true**: Enable cleanup expired actions assets job.
- `RUN_AT_START`: **true**: Run job at start time (if ENABLED).
- `SCHEDULE`: **@midnight**: Cron syntax for the job.

### Extended cron tasks (not enabled by default)

#### Cron - Garbage collect all repositories (`cron.git_gc_repos`)

- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start-up time (if ENABLED).
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository garbage collection, e.g., `@every 1h`.
- `TIMEOUT`: **60s**: Time duration syntax for garbage collection execution timeout.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `ARGS`: **\<empty\>**: Arguments for the command `git gc`, e.g., `--aggressive --auto`. The default value is the same as `[git]` -> `GC_ARGS`.

#### Cron - Update the '.ssh/authorized_keys' file with Forgejo SSH keys (`cron.resync_all_sshkeys`)

- `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 `.ssh/authorized_keys` synchronization, e.g., `@every 1h`.

#### Cron - Resynchronize pre-receive, update and post-receive hooks of all repositories (`cron.resync_all_hooks`)

- `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 Git hooks synchronization for all repositories, e.g. `@every 1h`.

#### Cron - Reinitialize all missing Git repositories for which records exist (`cron.reinit_missing_repos`)

- `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 initialization of repositories missing their Git files, e.g. `@every 1h`.

#### Cron - Delete all repositories missing their Git files (`cron.delete_missing_repos`)

- `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 deletion of repositories missing their Git files, e.g. `@every 1h`.

#### 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 generated repository avatars cleanup, e.g. `@every 1h`.

#### Cron - Delete all old activities from database (`cron.delete_old_actions`)

- `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 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: Any action older than this expression will be deleted from the database; suggest using `8760h` (1 year) because that's the maximum length of the heatmap.

#### 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).
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices. (Note: `NOTICE_ON_SUCCESS` is used in most other cron jobs for consistency).
- `SCHEDULE`: **@every 168h**: Cron syntax for scheduling a check, e.g. `@every 168h`.
- `HTTP_ENDPOINT`: **https://dl.gitea.com/gitea/version.json**: [DEPRECATED] The endpoint that Forgejo will check for newer versions. Not in use by the project. Might be dropped in a future version.
- `DOMAIN_ENDPOINT`: **release.forgejo.org**: The domain with a [TXT record](https://en.wikipedia.org/wiki/TXT_record) that, if specified, Forgejo will query for newer versions. This is preferred over `HTTP_ENDPOINT`.

#### 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).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices. (Note: Consider `NOTICE_ON_SUCCESS: false` for consistency).
- `SCHEDULE`: **@every 168h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **8760h**: Any system notice older than this expression will be deleted from the database.

#### 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).
- `SCHEDULE`: **@every 24h**: Cron syntax to set how often to check.
- `OLDER_THAN`: **168h**: Only attempt to garbage collect LFSMetaObjects older than this (default 7 days).
- `LAST_UPDATED_MORE_THAN_AGO`: **72h**: Only attempt to garbage collect LFSMetaObjects that have not been attempted to be garbage collected for this long (default 3 days).
- `NUMBER_TO_CHECK_PER_REPO`: **100**: Minimum number of stale LFSMetaObjects to check per repo. Set to `0` to always check all.
- `PROPORTION_TO_CHECK_PER_REPO`: **0.6**: Check at least this proportion of LFSMetaObjects per repo. (This may cause all stale LFSMetaObjects to be checked.)

#### Cron - Delete inactive account (`cron.delete_inactive_accounts`)

- `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`: **@annually**: Cron syntax to set how often to check.
- `OLDER_THAN`: **168h**: Only delete inactive accounts older than this.

## Git (`git`)

- `PATH`: **""**: The path of the Git executable. If empty, Forgejo searches through the PATH environment variable.
- `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 the Forgejo user.
- `DISABLE_DIFF_HIGHLIGHT`: **false**: Disables highlighting of added and removed changes.
- `MAX_GIT_DIFF_LINES`: **1000**: Maximum number of lines allowed for a single file in the diff view.
- `MAX_GIT_DIFF_LINE_CHARACTERS`: **5000**: Maximum character count per line highlighted in the diff view.
- `MAX_GIT_DIFF_FILES`: **100**: Maximum number of files shown in the diff view.
- `COMMITS_RANGE_SIZE`: **50**: Sets the default commits range size.
- `BRANCHES_RANGE_SIZE`: **20**: Sets the default branches range size.
- `GC_ARGS`: **\<empty\>**: Arguments for the command `git gc`, e.g., `--aggressive --auto`. See more on http://git-scm.com/docs/git-gc/
- `ENABLE_AUTO_GIT_WIRE_PROTOCOL`: **true**: Use Git wire protocol version 2 when Git version >= 2.18; default is true. Set to false if you always want Git wire protocol version 1.
  To enable this for Git over SSH when using an OpenSSH server, add `AcceptEnv GIT_PROTOCOL` to your `sshd_config` file.
- `PULL_REQUEST_PUSH_MESSAGE`: **true**: Respond to pushes to a non-default branch with a URL for creating a Pull Request (if the repository has them enabled).
- `VERBOSE_PUSH`: **true**: Print status information about pushes as they are being processed.
- `VERBOSE_PUSH_DELAY`: **5s**: Only print verbose information if the push takes longer than this delay.
- `LARGE_OBJECT_THRESHOLD`: **1048576**: (Go-Git only) Don't cache objects greater than this size in memory. (Set to 0 to disable.)
- `DISABLE_CORE_PROTECT_NTFS`: **false**: Set to true to forcibly set `core.protectNTFS` to false.
- `DISABLE_PARTIAL_CLONE`: **false**: Disable the usage of partial clones for git.

### Git - Timeout settings (`git.timeout`)

- `DEFAULT`: **360**: Git operations default timeout in seconds.
- `MIGRATE`: **600**: Migrate external repositories timeout in seconds.
- `MIRROR`: **300**: Mirror external repositories timeout in seconds.
- `CLONE`: **300**: Git clone from internal repositories timeout in seconds.
- `PULL`: **300**: Git pull from internal repositories timeout in seconds.
- `GC`: **60**: Git repository GC timeout in seconds.
- `GREP`: **2**: Git repository grep (search) timeout in seconds.

### Git - Config options (`git.config`)

The key/value pairs in this section will be used as git config.
This section only performs "set" config; a removed config key from this section won't be removed from git config automatically. The format is `some.configKey = value`.

- `diff.algorithm`: **histogram**
- `core.logAllRefUpdates`: **true**
- `gc.reflogExpire`: **90**

## Metrics (`metrics`)

- `ENABLED`: **false**: Enables the `/metrics` endpoint for Prometheus.
- `ENABLED_ISSUE_BY_LABEL`: **false**: Enable issue by label metrics with the format `gitea_issues_by_label{label="bug"} 2`.
- `ENABLED_ISSUE_BY_REPOSITORY`: **false**: Enable issue by repository metrics with the format `gitea_issues_by_repository{repository="org/repo"} 5`.
- `TOKEN`: **\<empty\>**: You need to specify the token if you want to include authorization in the metrics. The same token needs to be used in Prometheus parameters `bearer_token` or `bearer_token_file`.

## API (`api`)

- `ENABLE_SWAGGER`: **true**: Enables the API documentation endpoints (`/api/swagger`, `/api/v1/swagger`, …). True or false.
- `MAX_RESPONSE_ITEMS`: **50**: Maximum number of items in a page.
- `DEFAULT_PAGING_NUM`: **30**: Default paging number for the API.
- `DEFAULT_GIT_TREES_PER_PAGE`: **1000**: Default and maximum number of items per page for the Git trees API.
- `DEFAULT_MAX_BLOB_SIZE`: **10485760** (10MiB): Default maximum size of a blob that can be returned by the blobs API.

## OAuth2 (`oauth2`)

- `ENABLED`: **true**: Enables the OAuth2 provider.
- `ACCESS_TOKEN_EXPIRATION_TIME`: **3600**: Lifetime of an OAuth2 access token in seconds.
- `REFRESH_TOKEN_EXPIRATION_TIME`: **730**: Lifetime of an OAuth2 refresh token in hours.
- `INVALIDATE_REFRESH_TOKENS`: **true**: Check if a refresh token has already been used.
- `JWT_SIGNING_ALGORITHM`: **RS256**: Algorithm used to sign OAuth2 tokens. Valid values: \[`HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`\].
- `JWT_SECRET`: **\<empty\>**: OAuth2 authentication secret for access and refresh tokens; change this to a unique string. This setting is only needed if `JWT_SIGNING_ALGORITHM` is set to `HS256`, `HS384`, or `HS512`.
- `JWT_SECRET_URI`: **\<empty\>**: Instead of defining `JWT_SECRET` in the configuration, this option can be used to give Forgejo a path to a file that contains the secret (example value: `file:/etc/forgejo/oauth2_jwt_secret`).
- `JWT_SIGNING_PRIVATE_KEY_FILE`: **jwt/private.pem**: Private key file path used to sign OAuth2 tokens. The path is relative to **the** `APP_DATA_PATH`. This setting is only needed if `JWT_SIGNING_ALGORITHM` is set to `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, or `ES512`. The file must contain an RSA or ECDSA private key in the PKCS8 format. **If no key exists, a 4096-bit** key will be created for you.
- `MAX_TOKEN_LENGTH`: **32767**: Maximum length of token/cookie to accept from the OAuth2 provider.
- `DEFAULT_APPLICATIONS`: **git-credential-oauth, git-credential-manager**: Pre-register OAuth applications for some services on startup.

## i18n (`i18n`)

- `LANGS`: **en-US,zh-CN,zh-HK,zh-TW,da,de-DE,nds,fr-FR,nl-NL,lv-LV,ru-RU,uk-UA,ja-JP,es-ES,pt-BR,pt-PT,pl-PL,bg,it-IT,fi-FI,fil,eo,tr-TR,cs-CZ,sl,sv-SE,ko-KR,el-GR,fa-IR,hu-HU,id-ID**:
  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,简体中文,繁體中文（香港）,繁體中文（台灣）,Dansk,Deutsch,Plattdüütsch,Français,Nederlands,Latviešu,Русский,Українська,日本語,Español,Português do Brasil,Português de Portugal,Polski,Български,Italiano,Suomi,Filipino,Esperanto,Türkçe,Čeština,Slovenščina,Svenska,한국어,Ελληνικά,فارسی,Magyar nyelv,Bahasa Indonesia**: Visible names corresponding to the locales

## Markup (`markup`)

- `MERMAID_MAX_SOURCE_CHARACTERS`: **5000**: Set the maximum size of a Mermaid source. (Set to -1 to disable).
- `FILEPREVIEW_MAX_LINES`: **50**: Set the maximum number of lines allowed for a file preview. (Set to -1 to disable limits; set to 0 to disable the feature).

Forgejo can support Markup using external tools. The example below will add a markup named `asciidoc`.

```ini
[markup.asciidoc]
ENABLED = true
NEED_POSTPROCESS = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "asciidoctor --embedded --safe-mode=secure --out-file=- -"
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 etc.
- `FILE_EXTENSIONS`: **\<empty\>**: List of file extensions that should be rendered by an external
  command. Multiple extensions need a comma as a splitter.
- `RENDER_COMMAND`: External command to render all matching extensions.
- `IS_INPUT_FILE`: **false**: Input is not standard input but a file parameter following `RENDER_COMMAND`.
- `RENDER_CONTENT_MODE`: **sanitized**: How the content will be rendered.
  - `sanitized`: Sanitize the content and render it inside the current page; defaults to allowing only 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 the current page. It's **insecure** and may lead to XSS attacks if the content contains malicious code.
  - `iframe`: Render the content in a separate standalone page and embed it into the current page using an iframe. The iframe is in sandbox mode with same-origin disabled, and JS code is safely isolated from the parent page.

Two special environment variables are passed to the render command:

- `GITEA_PREFIX_SRC`, which contains the current URL prefix in the `src` path tree. To be used as a prefix for links.
- `GITEA_PREFIX_RAW`, which contains the current URL prefix in the `raw` path tree. To be used as a prefix for image paths.

If `RENDER_CONTENT_MODE` is `sanitized`, Forgejo supports customizing the sanitization policy for rendered HTML. The example below will support KaTeX output from pandoc.

```ini
[markup.sanitizer.TeX]
; Pandoc renders TeX segments as <span>s with the "math" class, optionally
; with "inline" or "display" classes depending on context.
ELEMENT = span
ALLOW_ATTR = class
REGEXP = ^\s*((math(\s+|$)|inline(\s+|$)|display(\s+|$)))+
ALLOW_DATA_URI_IMAGES = true
```

- `ELEMENT`: The element this policy applies to. Must be non-empty.
- `ALLOW_ATTR`: The attribute this policy allows. Must be non-empty.
- `REGEXP`: A regex to match the contents of the attribute against. Must be present but may be empty for unconditional allowlisting of this attribute.
- `ALLOW_DATA_URI_IMAGES`: **false**: Allow data URI images (`<img src="data:image/png;base64,..."/>`).

Multiple sanitisation rules can be defined by adding unique subsections, e.g., `[markup.sanitizer.TeX-2]`.
To apply sanitisation rules only for a specific external renderer, they must use the renderer name, e.g., `[markup.sanitizer.asciidoc.rule-1]`.
If the rule is defined above the renderer ini section or the name does not match a renderer, it is applied to every renderer.

## Highlight Mappings (`highlight.mapping`)

- `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.

## Time (`time`)

- `DEFAULT_UI_LOCATION`: **Local**: Default timezone for displaying the current time on the user interface. Takes a name corresponding to a file in the IANA Time Zone database, i.e., `Asia/Shanghai`. For UTC, an empty string or `UTC` can be given, and `Local` for the local time of the machine.

## Migrations (`migrations`)

- `MAX_ATTEMPTS`: **3**: Maximum attempts per http/https request on migrations.
- `RETRY_BACKOFF`: **3**: Backoff time per http/https request retry (seconds).
- `ALLOWED_DOMAINS`: **\<empty\>**: Domains allowlist for migrating repositories; default is blank. It means everything will be allowed. Multiple domains can be separated by commas. Wildcard is supported: `github.com, *.github.com`.
- `BLOCKED_DOMAINS`: **\<empty\>**: Domains blocklist for migrating repositories; default is blank. Multiple domains can be separated by commas. When `ALLOWED_DOMAINS` is not blank, this option has a higher priority to deny domains. Wildcard is supported.
- `ALLOW_LOCALNETWORKS`: **false**: Allow private addresses defined by RFC 1918, RFC 1122, RFC 4632, and RFC 4291. If a domain is allowed by `ALLOWED_DOMAINS`, this option will be ignored.
- `SKIP_TLS_VERIFY`: **false**: Allow skipping TLS verification.

## Federation (`federation`)

- `ENABLED`: **false**: Enable/Disable federation capabilities.
- `SHARE_USER_STATISTICS`: **true**: Enable/Disable user statistics for nodeinfo if federation is enabled.
- `MAX_SIZE`: **4**: Maximum federation request and response size in MB.
- `SIGNATURE_ENFORCED`: **true**: Enable/Disable validation of HTTP signatures. This is similar to Mastodon's `AUTHORIZED_FETCH`, also called "secure mode". This setting requires all incoming requests to be signed by the originating server. It is recommended to keep this setting enabled.

WARNING: Changing the settings below can break federation.

- `SIGNATURE_ALGORITHMS`: **rsa-sha256, rsa-sha512, ed25519**: HTTP signature algorithms.
- `DIGEST_ALGORITHM`: **SHA-256**: HTTP signature digest algorithm.
- `GET_HEADERS`: **(request-target), Date**: GET headers for federation requests.
- `POST_HEADERS`: **(request-target), Date, Digest**: POST headers for federation requests.

## Packages (`packages`)

- `ENABLED`: **true**: Enable/Disable package registry capabilities.
- `CHUNKED_UPLOAD_PATH`: **tmp/package-upload**: Path for chunked uploads. Defaults to `APP_DATA_PATH` + `tmp/package-upload`.
- `LIMIT_TOTAL_OWNER_COUNT`: **-1**: Maximum count of package versions a single owner can have (`-1` means no limits).
- `LIMIT_TOTAL_OWNER_SIZE`: **-1**: Maximum size of packages a single owner can use (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_ALPINE`: **-1**: Maximum size of an Alpine upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_CARGO`: **-1**: Maximum size of a Cargo upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_CHEF`: **-1**: Maximum size of a Chef upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_COMPOSER`: **-1**: Maximum size of a Composer upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_CONAN`: **-1**: Maximum size of a Conan upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_CONDA`: **-1**: Maximum size of a Conda upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_CONTAINER`: **-1**: Maximum size of a Container upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_CRAN`: **-1**: Maximum size of a CRAN upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_DEBIAN`: **-1**: Maximum size of a Debian upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_GENERIC`: **-1**: Maximum size of a Generic upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_GO`: **-1**: Maximum size of a Go upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_HELM`: **-1**: Maximum size of a Helm upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_MAVEN`: **-1**: Maximum size of a Maven upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_NPM`: **-1**: Maximum size of an npm upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_NUGET`: **-1**: Maximum size of a NuGet upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_PUB`: **-1**: Maximum size of a Pub upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_PYPI`: **-1**: Maximum size of a PyPI upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_RPM`: **-1**: Maximum size of an RPM upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_RUBYGEMS`: **-1**: Maximum size of a RubyGems upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_SWIFT`: **-1**: Maximum size of a Swift upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).
- `LIMIT_SIZE_VAGRANT`: **-1**: Maximum size of a Vagrant upload (`-1` means no limits, format `1000`, `1 MB`, `1 GiB`).

Additional settings can be included in this section to specify where the data is stored, as [explained in detail in the storage documentation](../storage/).

## Mirror (`mirror`)

- `ENABLED`: **true**: Enables the mirror functionality. Set to **false** to disable all mirrors. Pre-existing mirrors remain valid but won't be updated; they may be converted to regular repos.
- `DISABLE_NEW_PULL`: **false**: Disable the creation of **new** pull mirrors. Pre-existing mirrors remain valid. Will be ignored if `mirror.ENABLED` is `false`.
- `DISABLE_NEW_PUSH`: **false**: Disable the creation of **new** push mirrors. Pre-existing mirrors remain valid. Will be ignored if `mirror.ENABLED` is `false`.
- `DEFAULT_INTERVAL`: **8h**: Default interval between each check.
- `MIN_INTERVAL`: **10m**: Minimum interval for checking. (Must be >1m).

## LFS (`lfs`)

Settings can be included in this section to specify where the LFS files are stored, as [explained in detail in the storage documentation](../storage/).

## Repository Avatars (`repo-avatar`)

Settings can be included in this section to specify where the repository avatars are stored, as [explained in detail in the storage documentation](../storage/).

## Avatars (`avatar`)

Settings can be included in this section to specify where the avatars are stored, as [explained in detail in the storage documentation](../storage/).

## Actions logs (`storage.actions_log`)

Settings can be included in this section to specify where the actions logs are stored, as [explained in detail in the storage documentation](../storage/).

## Actions Artifacts (`storage.artifacts`)

Settings can be included in this section to specify where the actions artifacts are stored, as [explained in detail in the storage documentation](../storage/).

## Storage (`storage`)

| subsystem           | default base path  | app.ini sections      |
| ------------------- | ------------------ | --------------------- |
| Attachments         | attachments/       | [attachment]          |
| LFS                 | lfs/               | [lfs]                 |
| Avatars             | avatars/           | [avatar]              |
| Repository avatars  | repo-avatars/      | [repo-avatar]         |
| Repository archives | repo-archive/      | [repo-archive]        |
| Packages            | packages/          | [packages]            |
| Actions logs        | actions_log/       | [storage.actions_log] |
| Actions Artifacts   | actions_artifacts/ | [actions.artifacts]   |

The settings for all these sections are [explained in detail in the storage documentation](../storage/).

## Quota (`quota`)

Also see the [dedicated docs about the quota feature](../quota/).

- `ENABLED`: **false**: Enable the quota feature.
- `DEFAULT_GROUPS`: **\<empty\>**: Comma-separated list of groups that apply by default to users. These groups can be configured via the API.

### Default Quota (`quota.default`)

- `TOTAL`: **-1**: Size for the default quota group. `-1` means unlimited storage. Can be suffixed with units, e.g., `500M` or `2G`.

### Quota subjects (list)

The available subjects for the quota feature are:

- `size:all`: The total size of everything Forgejo tracks.
- `size:git:all`: The total size of all Git data (including all repositories, and LFS).
  - `size:git:lfs`: The size of all Git LFS data (either in private or public repos).
  - `size:repos:all`: The total size of all repositories (not including LFS).
    - **NOT YET AVAILABLE** `size:repos:public`: The total size of all public repositories (not including LFS).
    - **NOT YET AVAILABLE** `size:repos:private`: The total size of all private repositories (not including LFS).
- `size:assets:all`: The size of all assets tracked by Forgejo.
  - `size:assets:attachments:all`: The size of all kinds of attachments tracked by Forgejo.
    - `size:assets:attachments:issues`: Size of all attachments attached to issues, including issue comments.
    - `size:assets:attachments:releases`: Size of all attachments attached to releases. This does _not_ include automatically generated archives.
  - `size:assets:artifacts`: Size of all Action artifacts.
  - `size:assets:packages:all`: Size of all Packages.
- `size:wiki`: Wiki size.

## Proxy (`proxy`)

- `PROXY_ENABLED`: **false**: Enable the proxy if true; all requests to external sources via HTTP will be affected. If false, no proxy will be used, even with environment `http_proxy`/`https_proxy`.
- `PROXY_URL`: **\<empty\>**: Proxy server URL, supports http://, https://, socks5://; 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.

For example, the following configuration can be used to proxy connections to GitHub subdomains, such as api.github.com:

```ini
PROXY_ENABLED = true
PROXY_URL = socks5://127.0.0.1:1080
PROXY_HOSTS = *.github.com
```

If you intend to proxy all connections to github.com, specify its second-level domain too:

```ini
PROXY_HOSTS = github.com,*.github.com
```

Note that you may need to set the `[migrations].ALLOW_LOCALNETWORKS` option to `true` in order to allow performing migrations via proxy.

## Actions (`actions`)

- `ENABLED`: **true**: Enable/Disable Actions.
- `DEFAULT_ACTIONS_URL`: **https://data.forgejo.org**: Default address to get action plugins, e.g., the default value means downloading from "https://code.forgejo.org/actions/checkout" for "uses: actions/checkout@v3".
- `ARTIFACT_RETENTION_DAYS`: **90**: Default number of days to keep artifacts. Artifacts can have their own retention periods by setting the `retention-days` option in the `actions/upload-artifact` step.
- `ZOMBIE_TASK_TIMEOUT`: **10m**: Timeout to stop tasks which have a running status but haven't been updated for a long time.
- `ENDLESS_TASK_TIMEOUT`: **3h**: Timeout to stop tasks which have a running status and continuous updates but don't end for a long time.
- `ABANDONED_JOB_TIMEOUT`: **24h**: Timeout to cancel jobs which have a waiting status but haven't been picked up by a runner for a long time.
- `SKIP_WORKFLOW_STRINGS`: **[skip ci],[ci skip],[no ci],[skip actions],[actions skip]**: Strings committers can place inside a commit message or pull request title to skip executing the corresponding Actions workflow.

## Other (`other`)

- `SHOW_FOOTER_VERSION`: **true**: Show Forgejo and Go version information in the footer.
- `SHOW_FOOTER_TEMPLATE_LOAD_TIME`: **true**: Show the time of template execution in the footer.
- `SHOW_FOOTER_POWERED_BY`: **true**: Show the "powered by" text in the footer.
- `ENABLE_SITEMAP`: **true**: Generate sitemap.
- `ENABLE_FEED`: **true**: Enable/Disable RSS/Atom feed.
