On FAQ item: "Push Hook / Webhook / Actions aren't running"
The action suggested in the original answer is not enough to fix the issue when the hooks are not running. For example, when none of the hooks is running, and branches and tags are not in the database, re-running only the update/receive hooks will not have any effect.
This change adds two additional actions: sync branches and tags before running re-running the sync of update/receive hooks.
Also added a comment about filesystems mounted with `no-exec` option.
Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/130
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: vmmello <[email protected]>
Co-committed-by: vmmello <[email protected]>
#### Summary
This pull request adds detailed instructions for configuring ProtonMail's SMTP server in the `email-setup.md` documentation. The new section provides step-by-step guidance on generating SMTP tokens and configuring the `app.ini` file for ProtonMail.
#### Changes
- Added a new section under the "ProtonMail" heading in `email-setup.md`.
- Included instructions for generating SMTP tokens in ProtonMail settings.
- Provided an example configuration for the `app.ini` file to use ProtonMail's SMTP server.
Reviewed-on: https://gitea.com/gitea/docs/pulls/93
Reviewed-by: Lunny Xiao <[email protected]>
Reviewed-by: techknowlogick <[email protected]>
Co-authored-by: talltechy <[email protected]>
Co-committed-by: talltechy <[email protected]>
- Added detailed documentation for `cron.delete_repo_archives` settings.
- Documented configuration options including `ENABLED`, `RUN_AT_START`, `NOTICE_ON_SUCCESS`, and `SCHEDULE`.
- Ensured consistent formatting across cron job documentation.
This update improves clarity on how to configure periodic deletion of repository archives within Gitea.
`man 5 jail.conf`:
CONFIGURATION FILES FORMAT
*.conf files are distributed by Fail2Ban. It is recommended that *.conf files should remain unchanged to ease upgrades. If needed,
customizations should be provided in *.local files. For example, if you would like to enable the [ssh-iptables-ipset] jail specified
in jail.conf, create jail.local containing
Reviewed-on: https://gitea.com/gitea/docs/pulls/14
Reviewed-by: techknowlogick <[email protected]>
Co-authored-by: webracer999 <[email protected]>
Co-committed-by: webracer999 <[email protected]>
- Always use a relative markdown link so that we can jump even if we edit it in local env or read it in code hosting server.
Reviewed-on: https://gitea.com/gitea/docs/pulls/1
`overflow-wrap: anywhere` is a superior alternative to `word-wrap:
break-word` and we were already setting it in the class. I tested a few
cases, all look good.
This PR implemented object storages(LFS/Packages/Attachments and etc.)
for Azure Blob Storage. It depends on azure official golang SDK and can
support both the azure blob storage cloud service and azurite mock
server.
Replace #25458Fix#22527
- [x] CI Tests
- [x] integration test, MSSQL integration tests will now based on
azureblob
- [x] unit test
- [x] CLI Migrate Storage
- [x] Documentation for configuration added
------
TODO (other PRs):
- [ ] Improve performance of `blob download`.
---------
Co-authored-by: yp05327 <[email protected]>
We wanted to be able to use the IAM role provided by the EC2 instance
metadata in order to access S3 via the Minio configuration. To do this,
a new credentials chain is added that will check the following locations
for credentials when an access key is not provided. In priority order,
they are:
1. MINIO_ prefixed environment variables
2. AWS_ prefixed environment variables
3. a minio credentials file
4. an aws credentials file
5. EC2 instance metadata
This PR split the `Board` into two parts. One is the struct has been
renamed to `Column` and the second we have a `Template Type`.
But to make it easier to review, this PR will not change the database
schemas, they are just renames. The database schema changes could be in
future PRs.
---------
Co-authored-by: silverwind <[email protected]>
Co-authored-by: yp05327 <[email protected]>
Backport #31022 by @kemzeb
Syncs up docs associated to actions and deleted branch cleanup i.e. in
custom/app.example.ini and the config cheat sheet.
Co-authored-by: Kemal Zebari <[email protected]>
Backport #31003 by wxiaoguang
Fix#31002
1. Mention Make sure `Host` and `X-Fowarded-Proto` headers are correctly passed to Gitea
2. Clarify the basic requirements and move the "general configuration" to the top
3. Add a comment for the "container registry"
4. Use 1.21 behavior if the reverse proxy is not correctly configured
Co-authored-by: wxiaoguang <[email protected]>
Co-authored-by: KN4CK3R <[email protected]>
Fix#31002
1. Mention Make sure `Host` and `X-Fowarded-Proto` headers are correctly passed to Gitea
2. Clarify the basic requirements and move the "general configuration" to the top
3. Add a comment for the "container registry"
4. Use 1.21 behavior if the reverse proxy is not correctly configured
Co-authored-by: KN4CK3R <[email protected]>
Add a configuration item to enable S3 virtual-hosted style (V2) to solve
the problem caused by some S3 service providers not supporting path
style (V1).
Backport #30744 by @lunny
Documentation building has encountered a problem like below. This is
because MDX syntax doesn't allow `{customPath}`, we have to use
\`{customPath}\`
```
Error: Can't render static file for pathname "/next/administration/config-cheat-sheet"
at generateStaticFile (/workspace/gitea/gitea-docusaurus/node_modules/@docusaurus/core/lib/ssg.js:119:15)
at runNextTicks (node:internal/process/task_queues:60:5)
at process.processImmediate (node:internal/timers:449:9)
at async /workspace/gitea/gitea-docusaurus/node_modules/p-map/index.js:57:22 {
[cause]: ReferenceError: CustomPath is not defined
at _createMdxContent (server.bundle.js:4406:106)
at MDXContent (server.bundle.js:10745:8)
at Uc (server.bundle.js:264171:44)
at Xc (server.bundle.js:264173:253)
at Z (server.bundle.js:264179:89)
at Yc (server.bundle.js:264182:98)
at $c (server.bundle.js:264181:140)
at Z (server.bundle.js:264179:345)
at Xc (server.bundle.js:264177:231)
at Z (server.bundle.js:264179:89)
```
Co-authored-by: Lunny Xiao <[email protected]>
Documentation building has encountered a problem like below. This is
because MDX syntax doesn't allow `{customPath}`, we have to use
\`{customPath}\`
```
Error: Can't render static file for pathname "/next/administration/config-cheat-sheet"
at generateStaticFile (/workspace/gitea/gitea-docusaurus/node_modules/@docusaurus/core/lib/ssg.js:119:15)
at runNextTicks (node:internal/process/task_queues:60:5)
at process.processImmediate (node:internal/timers:449:9)
at async /workspace/gitea/gitea-docusaurus/node_modules/p-map/index.js:57:22 {
[cause]: ReferenceError: CustomPath is not defined
at _createMdxContent (server.bundle.js:4406:106)
at MDXContent (server.bundle.js:10745:8)
at Uc (server.bundle.js:264171:44)
at Xc (server.bundle.js:264173:253)
at Z (server.bundle.js:264179:89)
at Yc (server.bundle.js:264182:98)
at $c (server.bundle.js:264181:140)
at Z (server.bundle.js:264179:345)
at Xc (server.bundle.js:264177:231)
at Z (server.bundle.js:264179:89)
```
Misspell 0.5.0 supports passing a csv file to extend the list of
misspellings, so I added some common ones from the codebase. There is at
least one typo in a API response so we need to decided whether to revert
that and then likely remove the dict entry.
Follow #30454
And fix#24957
When using "preferred_username", if no such field,
`extractUserNameFromOAuth2` (old `getUserName`) shouldn't return an
error. All other USERNAME options do not return such error.
And fine tune some logic and error messages, make code more stable and
more friendly to end users.
Added to doc for rootless Docker installation: for SSH passthrough, the
ssh user (git) has to be able to run docker.
---------
Co-authored-by: techknowlogick <[email protected]>
Initial support for #25680
This PR only adds some simple styles from GitHub, it is big enough and
it focuses on adding the necessary framework-level supports. More styles
could be fine-tuned later.
Backport #30555 by xor-gate
Config section `[task]` has been deprecated in favor of `[queue.task]`
Co-authored-by: Jerry Jacobs <[email protected]>
Co-authored-by: wxiaoguang <[email protected]>
This allows you to hide the "Powered by" text in footer via
`SHOW_FOOTER_POWERED_BY` flag in configuration.
---------
Co-authored-by: silverwind <[email protected]>
Backport #29314 by @scribblemaniac
This fixes a minor issue in the documentation for SSH Container
Passthrough for non-rootless installs. The non-rootless Dockerfile and
docker-compose do not set `USER`/`user` instructions so `docker exec`
will run as root by default. While running as root, gitea commands will
refuse to execute, breaking these approaches. For containers built with
the rootless instructions, `docker exec` will run as git by default so
this is not necessary in that case.
This issue was already discussed in #19065, but it does not appear this
part of the issue was ever added to the documentation.
Co-authored-by: scribblemaniac <[email protected]>
This fixes a minor issue in the documentation for SSH Container
Passthrough for non-rootless installs. The non-rootless Dockerfile and
docker-compose do not set `USER`/`user` instructions so `docker exec`
will run as root by default. While running as root, gitea commands will
refuse to execute, breaking these approaches. For containers built with
the rootless instructions, `docker exec` will run as git by default so
this is not necessary in that case.
This issue was already discussed in #19065, but it does not appear this
part of the issue was ever added to the documentation.
## Changes
- Adds setting `EXTERNAL_USER_DISABLE_FEATURES` to disable any supported
user features when login type is not plain
- In general, this is necessary for SSO implementations to avoid
inconsistencies between the external account management and the linked
account
- Adds helper functions to encourage correct use
Enable us to use tailwind's
[`font-family`](https://tailwindcss.com/docs/font-family) classes as
well as remove `gt-mono` in favor of `tw-font-mono`. I also merged the
"compensation" to one selector, previously this was two different values
0.9em and 0.95em. I did not declare a `serif` font because I don't think
there will ever be a use case for those. Command ran:
```sh
perl -p -i -e 's#gt-mono#tw-font-mono#g' web_src/js/**/* templates/**/*
Previously, the default was a week.
As most instances don't set the setting, this leads to a bad user
experience by default.
## ⚠️ Breaking
If your instance requires a high level of security,
you may want to set `[security].LOGIN_REMEMBER_DAYS` so that logins are
not valid as long.
---------
Co-authored-by: Jason Song <[email protected]>
We have to define this one in helpers.css because tailwind only
generates a single class but certain things rely on this being
double-class. Command ran:
```sh
perl -p -i -e 's#gt-hidden#tw-hidden#g' web_src/js/**/* templates/**/* models/**/* web_src/css/**/*
---------
Co-authored-by: wxiaoguang <[email protected]>
- Move some scripts from `build` to new `tools` dir. Eventually i would
like to move all but let's do it step-by-step.
- Add dir to eslint and move the files into vars.
- Update docs accordingly.
- While updating docs I noticed we were incorrectly having `public/img`
path still in a few places. Replace those with the current
`public/assets/img`.
---------
Co-authored-by: Nanguan Lin <[email protected]>
Co-authored-by: Giteabot <[email protected]>
The command order of prepare-docs is incorrect.
We should prepare same version with different locale at once, otherwise the doc files for `zh-cn` in `i18n` folder will be incorrect.
Before: (files in current is as same as version 1.19)

After:

Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/92
Reviewed-by: Lunny Xiao <[email protected]>
Reviewed-by: silverwind <[email protected]>
Co-authored-by: yp05327 <[email protected]>
Co-committed-by: yp05327 <[email protected]>
* "mail/issue/default.tmpl": the body is rendered by backend
`markdown.RenderString() HTML`, it has been already sanitized
* "repo/settings/webhook/base_list.tmpl": "Description" is prepared by
backend `ctx.Tr`, it doesn't need to be sanitized
Add new option:
`visible`: witch can hide a specific field of the form or the created
content afterwards
It is a string array witch can contain `form` and `content`. If only
`form` is present, it wont show up in the created issue afterwards and
the other way around. By default it sets both except for markdown
As they are optional and github don't have any similar thing, it is non
breaking and also do not conflict with it.
With this you can:
- define "post issue creation" elements like a TODO list to track an
issue state
- make sure to have a checkbox that reminds the user to check for a
thing but dont have it in the created issue afterwards
- define markdown for the created issue (was the downside of using yaml
instead of md in the past)
- ...
## Demo
```yaml
name: New Contribution
description: External Contributor creating a pull
body:
- type: checkboxes
id: extern-todo
visible: [form]
attributes:
label: Contribution Guidelines
options:
- label: I checked there exist no similar feature to be extended
required: true
- label: I did read the CONTRIBUTION.MD
required: true
- type: checkboxes
id: intern-todo
visible: [content]
attributes:
label: Maintainer Check-List
options:
- label: Does this pull follow the KISS principe
- label: Checked if internal bord was notifyed
# ....
```
[Demo
Video](https://cloud.obermui.de/s/tm34fSAbJp9qw9z/download/vid-20240220-152751.mkv)
---
*Sponsored by Kithara Software GmbH*
---------
Co-authored-by: John Olheiser <[email protected]>
Co-authored-by: delvh <[email protected]>
Extract from #20549
This PR added a new option on app.ini `[admin]USER_DISABLED_FEATURES` to
allow the site administrator to disable users visiting deletion user
interface or allow.
This options are also potentially allowed to define more features in
future PRs.
---------
Co-authored-by: wxiaoguang <[email protected]>
- Databases are one of the most important parts of Forgejo, every
interaction uses the database in one way or another. Therefore, it is
important to maintain the database and recognize when the server is not
doing well with the database. There already is the option to log *every*
SQL query along with its execution time, but monitoring becomes
impractical for larger instances and takes up unnecessary storage in the
logs.
- Add a QoL enhancement that allows instance administrators to specify a
threshold value beyond which query execution time is logged as a warning
in the xorm logger. The default value is a conservative five seconds to
avoid this becoming a source of spam in the logs.
- The use case for this patch is that with an instance the size of
Codeberg, monitoring SQL logs is not very fruitful and most of them are
uninteresting. Recently, in the context of persistent deadlock issues
(https://codeberg.org/forgejo/forgejo/issues/220), I have noticed that
certain queries hold locks on tables like comment and issue for several
seconds. This patch helps to identify which queries these are and when
they happen.
- Added unit test.
(cherry picked from commit 9cf501f1af4cd870221cef6af489618785b71186)
---------
Co-authored-by: Gusted <[email protected]>
Co-authored-by: Giteabot <[email protected]>
Co-authored-by: 6543 <[email protected]>
For some user (as me), documentation lack of precision about where to
store issue/pr template.
I propose an enhancement about this point. With bold exergue and
precision about server itself.
I've found some user with same interrogation as :
https://forum.gitea.com/t/issue-template-directory/3328
---------
Co-authored-by: Km <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
For some user (as me), documentation lack of precision about where to
store issue/pr template.
I propose an enhancement about this point. With bold exergue and
precision about server itself.
I've found some user with same interrogation as :
https://forum.gitea.com/t/issue-template-directory/3328
---------
Co-authored-by: 6543 <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
Add more details for the docker tag when using container registry.
---------
Co-authored-by: wxiaoguang <[email protected]>
Co-authored-by: KN4CK3R <[email protected]>
With this option, it is possible to require a linear commit history with
the following benefits over the next best option `Rebase+fast-forward`:
The original commits continue existing, with the original signatures
continuing to stay valid instead of being rewritten, there is no merge
commit, and reverting commits becomes easier.
Closes#24906
Update `docs/content/administration/backup-and-restore.zh-cn.md`
`docs/content/contributing/guidelines-frontend.zh-cn.md`
`docs/content/help/support.zh-cn.md`
`docs/content/installation/database-preparation.zh-cn.md`
`docs/content/installation/windows-service.zh-cn.md`
`docs/content/usage/profile-readme.zh-cn.md` to be consistent with the
English document
- Use maintained fork https://github.com/golangci/misspell
- Rename `mispell-check` to `lint-spell`, add `lint-spell-fix`
- Run `lint-spell` in separate actions step
- Lint more files, fix discovered issues
- Remove inaccurate and outdated info in docs (we do not need GOPATH for
tools anymore)
Maybe later we can add more spellchecking tools, but I have not found
any good ones yet.
This PR adds a new `must-change-password` parameter to the
`change-password` cli command.
We already have the `must-change-password` command but it feels natural
to have this integrated into the `change-password` cli command.
---------
Co-authored-by: 6543 <[email protected]>
Renames it to `ENABLED` to be consistent with other settings and
deprecates it.
I believe this change is necessary because other setting groups such as
`attachment`, `cors`, `mailer`, etc. have an `ENABLED` setting, but
`oauth2` is the only one with an `ENABLE` setting, which could cause
confusion for users.
This is no longer a breaking change because `ENABLE` has been set as
deprecated and as an alias to `ENABLED`.
The previous variables are used by the compiler and aren't too useful
for non-developers. The newly listed variables are more likely to be of
interest.
Apologies for this drive-by PR, I probably missed instructions from the
contributors guide. The patch can be regarded as a simple way to explain
the problem and solution. Feel free to close and possibly create a new
PR that does adhere to the contributors guide.
Sometimes you need to work on a feature which depends on another (unmerged) feature.
In this case, you may create a PR based on that feature instead of the main branch.
Currently, such PRs will be closed without the possibility to reopen in case the parent feature is merged and its branch is deleted.
Automatic target branch change make life a lot easier in such cases.
Github and Bitbucket behave in such way.
Example:
$PR_1$: main <- feature1
$PR_2$: feature1 <- feature2
Currently, merging $PR_1$ and deleting its branch leads to $PR_2$ being closed without the possibility to reopen.
This is both annoying and loses the review history when you open a new PR.
With this change, $PR_2$ will change its target branch to main ($PR_2$: main <- feature2) after $PR_1$ has been merged and its branch has been deleted.
This behavior is enabled by default but can be disabled.
For security reasons, this target branch change will not be executed when merging PRs targeting another repo.
Fixes#27062Fixes#18408
---------
Co-authored-by: Denys Konovalov <[email protected]>
Co-authored-by: delvh <[email protected]>
This PR adds a section to the documentation that links to the project
[Opengist](https://github.com/thomiceli/opengist) on GitHub.
The feature was proposed in #16670 but didn't resonate well with the
maintainers.
Mainly for MySQL/MSSQL.
It is important for Gitea to use case-sensitive database charset
collation. If the database is using a case-insensitive collation, Gitea
will show startup error/warning messages, and show the errors/warnings
on the admin panel's Self-Check page.
Make `gitea doctor convert` work for MySQL to convert the collations of
database & tables & columns.
* Fix#28131
## ⚠️ BREAKING ⚠️
It is not quite breaking, but it's highly recommended to convert the
database&table&column to a consistent and case-sensitive collation.
Backport #28639 by @denyskon
According to [Debian
docs](https://wiki.debian.org/DebianRepository/UseThirdParty):
> The certificate MUST NOT be placed in /etc/apt/trusted.gpg.d or loaded
by apt-key add.
> ...
> If future updates to the certificate will be managed by an apt/dpkg
package as recommended below, then it SHOULD be downloaded into
/usr/share/keyrings using the same filename that will be provided by the
package. If it will be managed locally , it SHOULD be downloaded into
/etc/apt/keyrings instead.
> ...
> A sources.list entry SHOULD have the signed-by option set.
Co-authored-by: Denys Konovalov <[email protected]>
According to [Debian
docs](https://wiki.debian.org/DebianRepository/UseThirdParty):
> The certificate MUST NOT be placed in /etc/apt/trusted.gpg.d or loaded
by apt-key add.
> ...
> If future updates to the certificate will be managed by an apt/dpkg
package as recommended below, then it SHOULD be downloaded into
/usr/share/keyrings using the same filename that will be provided by the
package. If it will be managed locally , it SHOULD be downloaded into
/etc/apt/keyrings instead.
> ...
> A sources.list entry SHOULD have the signed-by option set.
Backport #28626 by @hakito
Make it clear that this value is just a default value and that every
artifact can have it's own value.
Co-authored-by: Gerd Katzenbeisser <[email protected]>
Backport #28587, the only conflict is the test file.
The CORS code has been unmaintained for long time, and the behavior is
not correct.
This PR tries to improve it. The key point is written as comment in
code. And add more tests.
Fix#28515Fix#27642Fix#17098
The CORS code has been unmaintained for long time, and the behavior is
not correct.
This PR tries to improve it. The key point is written as comment in
code. And add more tests.
Fix#28515Fix#27642Fix#17098
Update more actions to use nodejs20 runtime and also update the docs for
checkout action usage.
similar to:
- #27836
- #27096
---------
Signed-off-by: Rui Chen <[email protected]>
Nowadays, cache will be used on almost everywhere of Gitea and it cannot
be disabled, otherwise some features will become unaviable.
Then I think we can just remove the option for cache enable. That means
cache cannot be disabled.
But of course, we can still use cache configuration to set how should
Gitea use the cache.
Several fields in the "Verify group membership in LDAP" docs were
confusingly titled when compared to the actual fields in the
application, this change rectifies that by matching the docs to the
fields already present in gitea.
Signed-off-by: David Hulick <[email protected]>
Close#28287
## How to test it in local
convert Makefile L34 into:
```
cd .tmp/upstream-docs && git clean -f && git reset --hard && git fetch origin pull/28302/head:pr28302 && git switch pr28302
```
https://gitea.com/gitea/gitea-docusaurus/actions/runs/661/jobs/0#jobstep-9-39
I noticed that there are many warning logs in building docs.
It is causing 404 in docs.gitea.com now, so we need to fix it.
And there are also some other problems in v1.19 which can not be done in
this PR.
ps: Are there any good methods to test this in local?
Follow #28191
There are some misadded docs in #24914's backport PR #25016.
The following package registries are all supported in 1.20, so we should
not have docs in v1.19
- Alpine (#23714)
- CRAN (#22343)
- Debain (#24426)
- Go (#24687)
- RPM (#23380)
Backport #28160 by @yp05327
Since #27054, Actions are enabled by default. so we should also edit the
document. 😃
ps: I think this should be backport to 1.21.0.
Co-authored-by: yp05327 <[email protected]>
These are some things I changed to make local development easier, especially when having to update multiple versions of docs at once like the docusaurus v3 update.
i.e.
```makefile
GITEA_REMOTE := ~/code/code.gitea.io/gitea
GITEA_LATEST_BRANCH := docs-v3
GITEA_VERSION_BRANCH_PREFIX := docs-v3-
...
```
to run the Makefile against my local repo.
Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/89
Co-authored-by: jolheiser <[email protected]>
Co-committed-by: jolheiser <[email protected]>
This patchset changes the connection string builder to use net.URL and
the host/port parser to use the stdlib function for splitting host from
port. It also adds a footnote about a potentially required portnumber
for postgres UNIX sockets.
Fixes: #24552
Closes#27455
> The mechanism responsible for long-term authentication (the 'remember
me' cookie) uses a weak construction technique. It will hash the user's
hashed password and the rands value; it will then call the secure cookie
code, which will encrypt the user's name with the computed hash. If one
were able to dump the database, they could extract those two values to
rebuild that cookie and impersonate a user. That vulnerability exists
from the date the dump was obtained until a user changed their password.
>
> To fix this security issue, the cookie could be created and verified
using a different technique such as the one explained at
https://paragonie.com/blog/2015/04/secure-authentication-php-with-long-term-persistence#secure-remember-me-cookies.
The PR removes the now obsolete setting `COOKIE_USERNAME`.
Duplicate headers in a single Markdown document are problemlematic
because the auto-generated links won't be stable. Enable this rule with
no exceptions which is also the default of `markdownlint`. For example:
```md
# A
## Example
# B
## Example
```
Docasaurus will generated `example` and `example-1` links for this. If
the first heading is altered, the link `example` will unexpectedly move
to the second example heading.
Ref: https://github.com/go-gitea/gitea/pull/27461#discussion_r1347987659
Part of https://github.com/go-gitea/gitea/issues/27097:
- `gitea` theme is renamed to `gitea-light`
- `arc-green` theme is renamed to `gitea-dark`
- `auto` theme is renamed to `gitea-auto`
I put both themes in separate CSS files, removing all colors from the
base CSS. Existing users will be migrated to the new theme names. The
dark theme recolor will follow in a separate PR.
## ⚠️ BREAKING ⚠️
1. If there are existing custom themes with the names `gitea-light` or
`gitea-dark`, rename them before this upgrade and update the `theme`
column in the `user` table for each affected user.
2. The theme in `<html>` has moved from `class="theme-name"` to
`data-theme="name"`, existing customizations that depend on should be
updated.
---------
Co-authored-by: Lunny Xiao <[email protected]>
Co-authored-by: Giteabot <[email protected]>
- MySQL 5.7 support and testing is dropped
- MySQL tests now execute against 8.1, up from 5.7 and 8.0
- PostgreSQL 10 and 11 support ist dropped
- PostgreSQL tests now execute against 16, up from 15
- MSSQL 2008 support is dropped
- MSSQL tests now run against locked 2022 version
Fixes: https://github.com/go-gitea/gitea/issues/25657
Ref: https://endoflife.date/mysql
Ref: https://endoflife.date/postgresql
Ref: https://endoflife.date/mssqlserver
## ⚠️ BREAKING ⚠️
Support for MySQL 5.7, PostgreSQL 10 and 11, and MSSQL 2008 is dropped.
You are encouraged to upgrade to supported versions.
---------
Co-authored-by: techknowlogick <[email protected]>
With this PR we added the possibility to configure the Actions timeouts
values for killing tasks/jobs.
Particularly this enhancement is closely related to the `act_runner`
configuration reported below:
```
# The timeout for a job to be finished.
# Please note that the Gitea instance also has a timeout (3h by default) for the job.
# So the job could be stopped by the Gitea instance if it's timeout is shorter than this.
timeout: 3h
```
---
Setting the corresponding key in the INI configuration file, it is
possible to let jobs run for more than 3 hours.
Signed-off-by: Francesco Antognazza <[email protected]>
Previously, the production build never output sourcemaps. Now we emit
one file for `index.js` because it is the most likely one where we need
to be able to better debug reported issues like
https://github.com/go-gitea/gitea/issues/27213. This will currently
increase the binary size of gitea by around 700kB which is what the
gzipped source map file has.
Also, I fixed the CSS sourcemap generation which was broken since the
introduction of lightningcss.
Backport #27126 by @Zettat123
Related to #27039
The `ref` property in Gitea Actions is different from GitHub Actions.
This PR improves the documentation to explain the difference.
Co-authored-by: Zettat123 <[email protected]>
Backport #26999
If the AppURL(ROOT_URL) is an HTTPS URL, then the COOKIE_SECURE's
default value should be true.
And, if a user visits an "http" site with "https" AppURL, they won't be
able to login, and they should have been warned. The only problem is
that the "language" can't be set either in such case, while I think it
is not a serious problem, and it could be fixed easily if needed.
Backport #26883
This change was caused by #26271, for configuration as below:
```
[attachment]
ENABLE = true
PATH = data/attachments
MAX_SIZE = 100
MAX_FILES = 5
```
Before #26271, the resolved path is ${AppWorkPath}/${attachments.PATH}
(such as `/var/lib/gitea/data/attachments`)
After #26271, the resolved path is ${AppDataPath}/${attachments.PATH}
(such as `/var/lib/gitea/data/data/attachments`)
Fix https://github.com/go-gitea/gitea/issues/26864 Follow
https://github.com/go-gitea/gitea/pull/26271
Backport #26382 by @jolheiser
This PR adds our matrix space to the support options and alphabetizes
the list.
I also considered adding our Mastodon, however that isn't as suitable as
the other options because it's just whoever has access to the account vs
a community chat/forum.
Signed-off-by: jolheiser <[email protected]>
Co-authored-by: John Olheiser <[email protected]>
Backport #26690 by @thomas-mc-work
… because it doesn't require a separate shell, spawning a process which
cost unnecessary resources and takes time.
Co-authored-by: Thomas McWork <[email protected]>
Backport #26654 by @lunny
copy and modified from #14572
> Whilst debating enforcing MFA within our team, I realised there isn't
a lot of context to the side effects of enabling it. Most of us use Git
over HTTP and would need to add a token.
I plan to add another PR that adds a sentence to the UI about needing to
generate a token when enabling MFA if HTTP is to be used.
Co-authored-by: Lunny Xiao <[email protected]>
Co-authored-by: techknowlogick <[email protected]>
Co-authored-by: silverwind <[email protected]>
Backport #26267 by @wxiaoguang
1. Fix the wrong document (add the missing `MODE=`)
2. Add a more friendly log message to tell users to add `MODE=` in their
config
Co-authored-by: wxiaoguang <[email protected]>
Closes#30Closes#31Closes#42
Rather than partially cloning, instead we clone once and then `clean` (to remove generated files), `reset` (to reset changed files), and `checkout` branches as needed. This should allow the outdated translation check to continue to work while also reducing build times significantly.
Before:

After:

Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/52
Co-authored-by: John Olheiser <[email protected]>
Co-committed-by: John Olheiser <[email protected]>
Backport #26068 by @felixvictor
The setting `MAILER_TYPE` is deprecated.
According to the config cheat sheet, it should be `PROTOCOL`.
Co-authored-by: Felix Victor <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
Backport #26096 by @thigg
related #1635#18159
This will probably be obsolete at some point, but it should not break
anything and it may help some users
Co-authored-by: thigg <[email protected]>
Close#46
Same as those in [blog](https://gitea.com/gitea/blog/pulls/272), but for docs and api
Ejected DocPage (unsafe to eject) and ApiDoc (safe to eject) for layout changes

Screenshots

Co-authored-by: techknowlogick <[email protected]>
Co-authored-by: techknowlogick <[email protected]>
Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/47
Co-authored-by: HesterG <[email protected]>
Co-committed-by: HesterG <[email protected]>
- Do not use `target="_blank"`for gitea websites on navbar (same behavior as about.gitea.com)
- Translate "blog" on navbar for zh-cn
Before:

After:

Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/44
Co-authored-by: HesterG <[email protected]>
Co-committed-by: HesterG <[email protected]>
Backport #25648
Replace #25580Fix#19453
The problem was: when users set "GITEA__XXX__YYY" , the "install page"
doesn't respect it.
So, to make the result consistent and avoid surprising end users, now
the "install page" also writes the environment variables to the config
file.
And, to make things clear, there are enough messages on the UI to tell
users what will happen.
There are some necessary/related changes to `environment-to-ini.go`:
* The "--clear" flag is removed and it was incorrectly written there.
The "clear" operation should be done if INSTALL_LOCK=true
* The "--prefix" flag is removed because it's never used, never
documented and it only causes inconsistent behavior.
The only conflict during backport is "ui divider" in
templates/install.tmpl
Backport #25771 by @leavesster
---
according `docker/rootless/usr/local/bin/docker-setup.sh` , in rootless
docker setup, ssh port is 2222.
and mysql database case should port same as PostgreSQL port
Co-authored-by: leavesster <[email protected]>
- Used custom api dropdown for changing label dynamically. Used method discussed in [this post](https://github.com/facebook/docusaurus/pull/7231). `ComponentTypes` is ejected safely.

- Fixed dropdowns missing on chrome docs page

- Fixed `:has` selector compatibility problem on firefox. After (Screenshots from firefox):




Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/39
Co-authored-by: HesterG <[email protected]>
Co-committed-by: HesterG <[email protected]>
# Changes
- Added [redocusaurus](https://github.com/rohit-gohri/redocusaurus) package to display swagger api with reference to [woodpecker](https://github.com/woodpecker-ci/woodpecker/tree/master/docs)
- Change `sed` for swagger.json for proper version and baseurl.
- Add a dropdown for different api versions. (screenshot below)
- On API pages, only API version dropdown will show(hide locale dropdown, version dropdown for doc, and doc search)
- Allow build CSR API pages for development so it saves building time.
# Screenshots




Search:

Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/32
Co-authored-by: HesterG <[email protected]>
Co-committed-by: HesterG <[email protected]>
Backport #25581 by @wolfogre
Resolve#24789
## ⚠️ BREAKING ⚠️
Before this, `DEFAULT_ACTIONS_URL` cound be set to any custom URLs like
`https://gitea.com` or `http://your-git-server,https://gitea.com`, and
the default value was `https://gitea.com`.
But now, `DEFAULT_ACTIONS_URL` supports only
`github`(`https://github.com`) or `self`(the root url of current Gitea
instance), and the default value is `github`.
If it has configured with a URL, an error log will be displayed and it
will fallback to `github`.
Actually, what we really want to do is always make it
`https://github.com`, however, this may not be acceptable for some
instances of internal use, so there's extra support for `self`, but no
more, even `https://gitea.com`.
Please note that `uses: https://xxx/yyy/zzz` always works and it does
exactly what it is supposed to do.
Although it's breaking, I belive it should be backported to `v1.20` due
to some security issues.
Follow-up on the runner side:
- https://gitea.com/gitea/act_runner/pulls/262
- https://gitea.com/gitea/act/pulls/70
Co-authored-by: Jason Song <[email protected]>
Close#4
Right now on MacOS, sed will produce backup files, because on Mac, If do something like below using bash script
```
$SED_INPLACE '1s/---/---\nisOutdated: true/' $file
```
It will become the following on executed, and a backup file will be produced:
```
sed -i ''\'''\''' '1s/---/---\nisOutdated: true/' ./docs/content/doc/help/faq.zh-cn.md
```
The way to fix this in this PR is to change the `SED_INPLACE` to a function. [Reference](https://github.com/pingcap/tipb/blob/aa19c2d12587e66b31069f790fc371b6be565504/generate-cpp.sh#L4) (Tested on my
Mac and backup files with suffix '' will not be produced after changing to function)
Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/36
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: HesterG <[email protected]>
Co-committed-by: HesterG <[email protected]>
Backport #25256 by @thezzisu
In this pull request, the following changes are addressed:
- State user should create `config.yaml` before start container to avoid
errors.
- Provided instructions to deploy runners using docker compose.
Co-authored-by: Zisu Zhang <[email protected]>
Modified `loop_docs.sh` to take `version` and `locale` and params so do not need other `loop_docs*` scripts.
Need confirmation with version information for 1.20 and latest.
Like version in `static/20-swagger.json` and `static/latest-swagger.json`, and version used to replace `{{< version >}}`
Will wait for a stable version for 1.20

Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/28
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: HesterG <[email protected]>
Co-committed-by: HesterG <[email protected]>
Backport #23911 by @lunny
Follow up #22405Fix#20703
This PR rewrites storage configuration read sequences with some breaks
and tests. It becomes more strict than before and also fixed some
inherit problems.
- Move storage's MinioConfig struct into setting, so after the
configuration loading, the values will be stored into the struct but not
still on some section.
- All storages configurations should be stored on one section,
configuration items cannot be overrided by multiple sections. The
prioioty of configuration is `[attachment]` > `[storage.attachments]` |
`[storage.customized]` > `[storage]` > `default`
- For extra override configuration items, currently are `SERVE_DIRECT`,
`MINIO_BASE_PATH`, `MINIO_BUCKET`, which could be configured in another
section. The prioioty of the override configuration is `[attachment]` >
`[storage.attachments]` > `default`.
- Add more tests for storages configurations.
- Update the storage documentations.
Co-authored-by: Lunny Xiao <[email protected]>
Co-authored-by: wxiaoguang <[email protected]>
Close#17
mdxa is another component that is safe to eject

And right now some links are using `master` as the branch(link will be redirect to `main`), so checked for that as well.
Update:
Change `master` to `main` in upstream, so also removed check for `master`
https://github.com/go-gitea/gitea/pull/25126
# After
For example:




Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/27
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: HesterG <[email protected]>
Co-committed-by: HesterG <[email protected]>
- `git log` needs all commit history to compare latest commit of files, so changed `git clone --depth=1` to `git clone`. This will make the step take longer, so might be improved if there is a better way.
- `src/theme/MDXContent/index.js` is from [ejecting of the component](https://docusaurus.io/docs/swizzling#ejecting) inside `@docusaurus/theme-classic` plugin, and this one is safe to eject according to docusaurus


- [Outdated component style reference](https://mui.com/material-ui/react-alert/)
- Added [`Translate` component](https://docusaurus.io/docs/next/docusaurus-core#translate) to `Outdated` so it can be localized. [reference](https://docusaurus.io/docs/next/i18n/tutorial#translate-your-react-code)
- One way to check for the specific outdated documents:
search for `lastest commit timestamp` in [prepare nightly docs and prepare 1.19 docs steps](https://gitea.com/gitea/gitea-docusaurus/actions/runs/74)
# After
The Chinese documents that are outdated (latest commit is ealier than laster commit of English version):



Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/25
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: HesterG <[email protected]>
Co-committed-by: HesterG <[email protected]>
Backport #24925, partially backport #24934
(`docs/content/doc/help/faq.zh-cn.md` file)
Part of backport has already done by #24942
Also backport #24881 to avoid "deadlock"
---------
Co-authored-by: Zettat123 <[email protected]>
Backport #24979
Changes:
1. Use uniform links types relative to doc folder (start with `doc/`)
2. According to [docusaurus
links](https://docusaurus.io/docs/markdown-features/links), if `<a>` is
used, the `href` is resolved as URL location, but not file location. So
need to use `[text]({{< relref "path" >}})` instead.
# Main changes and Some notices
- Chines Docs should be put into corresponding versions' folders under `i18n/zh-cn/docusaurus-plugin-content-docs`. See [translate-markdown-files](https://docusaurus.io/docs/i18n/tutorial#translate-markdown-files) for reference. And also [srs-docs](https://github.com/ossrs/srs-docs) is a project that can be used as a reference. So changed the related paths in `loop_docs*` scripts.
- The markdown files under `docs/<version>` and `i18n/zh-cn/docusaurus-plugin-content-docs/<version>` must have the same name to be referred as translated. Files inside docs are corresponding to `current` version.
For example, `docs/administration/mail-templates.md` and `i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/mail-templates.md`. Filename of `mail-templates.md` must be the same (cannot be `mail-templates.zh-cn.md` and `mail-templates.us-en.md`)
So trim the `.en-us.md` and `.zh-cn.md` to `.md` to ensure the same names inside `loop_docs*` scripts.
- Used `npx docusaurus write-translations --locale zh-cn` to do sidebar, footer, and header translations, so no need to keep `sideBarCN` anymore. [reference](https://docusaurus.io/docs/cli#docusaurus-write-translations-sitedir)
- Local Tests for `en` and `zh-cn` are separeted, run the following on local respectly to test them
```bash
# test en version
npm run start
# test zh-cn version
npm run start -- --locale zh-cn
```
- If wants to test `en` and `zh-cn` both at the same time, run build and serve
```
npm run build
npm run serve
```
- Added some indexed page, for example:


Reviewed-on: https://gitea.com/gitea/gitea-docusaurus/pulls/13
Co-authored-by: HesterG <[email protected]>
Co-committed-by: HesterG <[email protected]>
Backport #23923 by @teauxfu
updated the example config to make the needed backticks around the
password more obvious
Co-authored-by: alex <[email protected]>
Backport #23733 by @wolfogre
I neglected that the `NameKey` of `Unit` is not only for translation,
but also configuration. So it should be `repo.actions` to maintain
consistency.
## ⚠️ BREAKING ⚠️
If users already use `actions.actions` in `DISABLED_REPO_UNITS` or
`DEFAULT_REPO_UNITS`, it will be treated as an invalid unit key.
Co-authored-by: Jason Song <[email protected]>
Follow #21962
After I eat my own dogfood, I would say that
ONLY_SHOW_RELEVANT_REPOS=false is necessary for many private/enterprise
instances, because many private repositories do not have
"description/topic", users just want to search by their names.
This PR also adds `PageIsExploreRepositories` check, to make code more
strict, because the `search` template is shared for different purpose.
And during the test, I found a bug that the "Search" button didn't
respect the "relevant" parameter, so this PR fixes the bug by the way
together.
Backport #23580 by @silverwind
Updated this default to GitHub's latest, adding the `.patch` file
extension to allowed types.
Co-authored-by: silverwind <[email protected]>
Backport #23430 by @brechtvl
* Fix scoped label left and right part breaking across lines.
* Remove slanted divider in scoped label display, make it straight.
After using this for a while, this feels more visually noisy than
helpful.
* Reduce contrast between scope and item to reduce probability of
unreadable text on background.
* Change documentation to remove mention of non-exclusive scoped labels.
Co-authored-by: Brecht Van Lommel <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
Co-authored-by: John Olheiser <[email protected]>
Backport #22451 by @philip-peterson
This PR adds support for reflogs on all repositories. It does this by
adding a global configuration entry.
Implements #14865
Signed-off-by: Philip Peterson <[email protected]>
Co-authored-by: Philip Peterson <[email protected]>
Backport #23087
Whitespace was missing from refactoring docs metadata.
backport label applied so it is included in versioned docs.
Co-authored-by: techknowlogick <[email protected]>
* Keine "Amtsdeusch"-Umschreibungen, einfach so als ob man den Nutzer direkt persönlich ansprechen würde
Genauer definiert:
* "falsch" anstatt "nicht korrekt/inkorrekt"
* Benutzerkonto oder Konto? Oder Account?
* "Wende dich an ..." anstatt "kontaktiere ..."
* In der selben Zeit übersetzen (sonst wird aus "is" "war")
* Richtige Anführungszeichen verwenden. Also `"` statt `''` oder `'` oder \` oder `´`
*`„` für beginnende Anführungszeichen, `“` für schließende Anführungszeichen
Es gelten Artikel und Worttrennungen aus dem Duden.
## Formulierungen in Modals und Buttons
Es sollten die gleichen Formulierungen auf Buttons und Modals verwendet werden.
Beispiel: Wenn der Button mit `löschen` beschriftet ist, sollte im Modal die Frage lauten `Willst du das wirklich löschen?` und nicht `Willst du das wirklich entfernen?`. Gleiches gilt für Success/Errormeldungen nach der Aktion.
Some jurisdictions (such as EU), requires certain legal pages (e.g. Privacy Policy) to be added to website. Follow these steps to add them to your Gitea instance.
## Getting Pages
Gitea source code ships with sample pages, available in `contrib/legal` directory. Copy them to `custom/public/assets/`. For example, to add Privacy Policy:
Now you need to edit the page to meet your requirements. In particular you must change the email addresses, web addresses and references to "Your Gitea Instance" to match your situation.
You absolutely must not place a general ToS or privacy statement that implies that the Gitea project is responsible for your server.
## Make it Visible
Create or append to `/path/to/custom/templates/custom/extra_links_footer.tmpl`:
- Example for Microsoft Active Directory (AD): `(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName=%s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))`
- To substitute more than once, `%[1]s` should be used instead, e.g. when
matching supplied login name against multiple attributes such as user
- Import the LDIF (change localhost to an IPA server if needed). A prompt for
Directory Manager password will be presented:
```sh
ldapmodify -h localhost -p 389 -x -D \
"cn=Directory Manager" -W -f gitea.ldif
```
- Add an IPA group for gitea_users :
```sh
ipa group-add --desc="Gitea Users" gitea_users
```
- Note: For errors about IPA credentials, run `kinit admin` and provide the
domain admin account password.
- Log in to Gitea as an Administrator and click on "Authentication" under Admin Panel.
Then click `Add New Source` and fill in the details, changing all where appropriate.
## SPNEGO with SSPI (Kerberos/NTLM, for Windows only)
Gitea supports SPNEGO single sign-on authentication (the scheme defined by RFC4559) for the web part of the server via the Security Support Provider Interface (SSPI) built in Windows. SSPI works only in Windows environments - when both the server and the clients are running Windows.
Before activating SSPI single sign-on authentication (SSO) you have to prepare your environment:
- Create a separate user account in active directory, under which the `gitea.exe` process will be running (eg. `user` under domain `domain.local`):
- Create a service principal name for the host where `gitea.exe` is running with class `HTTP`:
- Start `Command Prompt` or `PowerShell` as a privileged domain user (eg. Domain Administrator)
- Run the command below, replacing `host.domain.local` with the fully qualified domain name (FQDN) of the server where the web application will be running, and `domain\user` with the name of the account created in the previous step:
```sh
setspn -A HTTP/host.domain.local domain\user
```
- Sign in (_sign out if you were already signed in_) with the user created
- Make sure that `ROOT_URL` in the `[server]` section of `custom/conf/app.ini` is the fully qualified domain name of the server where the web application will be running - the same you used when creating the service principal name (eg. `host.domain.local`)
- Start the web server (`gitea.exe web`)
- Enable SSPI authentication by adding an `SPNEGO with SSPI` authentication source in `Site Administration -> Authentication Sources`
- Sign in to a client computer in the same domain with any domain user (client computer, different from the server running `gitea.exe`)
- If you are using Chrome or Edge, add the URL of the web app to the Local intranet sites (`Internet Options -> Security -> Local intranet -> Sites`)
- Start Chrome or Edge and navigate to the FQDN URL of Gitea (eg. `http://host.domain.local:3000`)
- Click the `Sign In` button on the dashboard and choose SSPI to be automatically logged in with the same user that is currently logged on to the computer
- If it does not work, make sure that:
- You are not running the web browser on the same server where Gitea is running. You should be running the web browser on a domain joined computer (client) that is different from the server. If both the client and server are running on the same computer NTLM will be preferred over Kerberos.
- There is only one `HTTP/...` SPN for the host
- The SPN contains only the hostname, without the port
- You have added the URL of the web app to the `Local intranet zone`
- The clocks of the server and client should not differ with more than 5 minutes (depends on group policy)
- `Integrated Windows Authentication` should be enabled in Internet Explorer (under `Advanced settings`)
## Reverse Proxy
Gitea supports Reverse Proxy Header authentication, it will read headers as a trusted login user name or user email address. This hasn't been enabled by default, you can enable it with
```ini
[service]
ENABLE_REVERSE_PROXY_AUTHENTICATION = true
```
The default login user name is in the `X-WEBAUTH-USER` header, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_USER` in app.ini. If the user doesn't exist, you can enable automatic registration with `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true`.
The default login user email is `X-WEBAUTH-EMAIL`, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_EMAIL` in app.ini, this could also be disabled with `ENABLE_REVERSE_PROXY_EMAIL`
If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`.
You can also limit the reverse proxy's IP address range with `REVERSE_PROXY_TRUSTED_PROXIES` which default value is `127.0.0.0/8,::1/128`. By `REVERSE_PROXY_LIMIT`, you can limit trusted proxies level.
You can enable the this authentication method for the API with
```ini
[service]
ENABLE_REVERSE_PROXY_AUTHENTICATION_API = true
```
:::note
When this method is enabled for the API, the reverse proxy is responsible for handling CSRF protection.
Gitea currently has a `dump` command that will save the installation to a ZIP file. This
file can be unpacked and used to restore an instance.
## Backup Consistency
To ensure the consistency of the Gitea instance, it must be shutdown during backup.
Gitea consists of a database, files and git repositories, all of which change when it is used. For instance, when a migration is in progress, a transaction is created in the database while the git repository is being copied over. If the backup happens in the middle of the migration, the git repository may be incomplete although the database claims otherwise because it was dumped afterwards. The only way to avoid such race conditions is by stopping the Gitea instance during the backups.
## Backup Command (`dump`)
Switch to the user running Gitea: `su git`. Run `./gitea dump -c /path/to/app.ini` in the Gitea installation
directory. There should be some output similar to the following:
```log
2016/12/27 22:32:09 Creating tmp work dir: /tmp/gitea-dump-417443001
2016/12/27 22:32:09 Dumping local repositories.../home/git/gitea-repositories
2016/12/27 22:32:22 Dumping database...
2016/12/27 22:32:22 Packing dump files...
2016/12/27 22:32:34 Removing tmp work dir: /tmp/gitea-dump-417443001
2016/12/27 22:32:34 Finish dumping in file gitea-dump-1482906742.zip
```
Inside the `gitea-dump-1482906742.zip` file, will be the following:
-`app.ini` - Optional copy of configuration file if originally stored outside the default `custom/` directory
-`custom/` - All config or customization files in `custom/`.
-`data/` - Data directory (APP_DATA_PATH), except sessions if you are using file session. This directory includes `attachments`, `avatars`, `lfs`, `indexers`, SQLite file if you are using SQLite.
-`repos/` - Complete copy of the repository directory.
-`gitea-db.sql` - SQL dump of database
-`log/` - Various logs. They are not needed for a recovery or migration.
Intermediate backup files are created in a temporary directory specified either with the
`--tempdir` command-line parameter or the `TMPDIR` environment variable.
## Backup the database
The SQL dump created by `gitea dump` uses XORM and Gitea admins may prefer to use the native the MySQL and PostgreSQL dump tools instead. There are still open issues when using XORM for dumping the database that may cause problems when attempting to restore it.
There are a few caveats for using the `dump` command with Docker.
The command has to be executed with the `RUN_USER = <OS_USERNAME>` specified in `gitea/conf/app.ini`; and, for the zipping of the backup folder to occur without permission error the command `docker exec` must be executed inside of the `--tempdir`.
\*Note: `--tempdir` refers to the temporary directory of the docker environment used by Gitea; if you have not specified a custom `--tempdir`, then Gitea uses `/tmp` or the `TMPDIR` environment variable of the docker container. For `--tempdir` adjust your `docker exec` command options accordingly.
The result should be a file, stored in the `--tempdir` specified, along the lines of: `gitea-dump-1482906742.zip`
## Restore Command (`restore`)
There is currently no support for a recovery command. It is a manual process that mostly
involves moving files to their correct locations and restoring a database dump.
mysql --default-character-set=utf8mb4 -u$USER -p$PASS$DATABASE <gitea-db.sql
# sqlite3
sqlite3 $DATABASE_PATH <gitea-db.sql
# postgres
psql -U $USER -d $DATABASE < gitea-db.sql
service gitea restart
```
Repository Git Hooks should be regenerated if installation method is changed (eg. binary -> Docker), or if Gitea is installed to a different directory than the previous installation.
With Gitea running, and from the directory Gitea's binary is located, execute: `./gitea admin regenerate hooks`
This ensures that application and configuration file paths in repository Git Hooks are consistent and applicable to the current installation. If these paths are not updated, repository `push` actions will fail.
If you still have issues, consider running `./gitea doctor check` to inspect possible errors (or run with `--fix`).
### Using Docker (`restore`)
There is also no support for a recovery command in a Docker-based gitea instance. The restore process contains the same steps as described in the previous section but with different paths.
The `gitea dump` command can produce a SQL file that can be read by another database type, which is useful to convert the database to another in case you did not choose the correct one during the first installation.
Note that this conversion process is not well-tested, which is why it is recommended to choose the final database type during the first installation without attempting to change it afterwards.
Stop the Gitea server, then make sure you have a full backup of your original database.
Before attempting the conversion, ensure that the original database is clean. Run `gitea doctor check --all --fix` and `gitea doctor recreate-table` to address common issues.
Use the `--database` flag to get a Gitea dump with the SQL file in the target format, in this example PostgreSQL: `gitea dump --database postgres`, then extract the file `gitea-db.sql` from the generated ZIP file.
Create the PostgreSQL Gitea user and Gitea database. Then, import the SQL file as the Gitea user into the Gitea database, using commands such as:
```sh
sudo -u postgres psql -d gitea
gitea=# SET synchronous_commit TO off
gitea=# SET on_error_stop TO on
gitea=# \i gitea-db.sql
```
Disabling `synchronous_commit` makes PostgreSQL less resilient to crashes, but makes the import a lot faster. Since we already have a backup of the original database and we can check that the import completes successfully, it should be a good trade-off.
After the import is completed, set up Gitea to use PostgreSQL and start the Gitea server again. Good luck!
If the `CustomPath` folder can't be found despite checking `gitea help`, check the `GITEA_CUSTOM`
environment variable; this can be used to override the default path to something else.
`GITEA_CUSTOM` might, for example, be set by an init script. You can check whether the value
is set under the "Configuration" tab on the site administration page.
- [List of Environment Variables](../administration/environment-variables.md)
:::note
Gitea must perform a full restart to see configuration changes.
:::
## Serving custom public files
To make Gitea serve custom public files (like pages and images), use the folder
`$GITEA_CUSTOM/public/` as the webroot. Symbolic links will be followed.
At the moment, only the following files are served:
-`public/robots.txt`
- files in the `public/.well-known/` folder
- files in the `public/assets/` folder
For example, a file `image.png` stored in `$GITEA_CUSTOM/public/assets/`, can be accessed with
the url `http://gitea.domain.tld/assets/image.png`.
## Changing the logo
To build a custom logo and/or favicon clone the Gitea source repository, replace `assets/logo.svg` and/or `assets/favicon.svg` and run
`make generate-images`. `assets/favicon.svg` is used for the favicon only. This will update below output files which you can then place in `$GITEA_CUSTOM/public/assets/img` on your server:
-`public/assets/img/logo.svg` - Used for site icon, app icon
-`public/assets/img/logo.png` - Used for Open Graph
-`public/assets/img/avatar_default.png` - Used as the default avatar image
-`public/assets/img/apple-touch-icon.png` - Used on iOS devices for bookmarks
-`public/assets/img/favicon.svg` - Used for favicon
-`public/assets/img/favicon.png` - Used as fallback for browsers that don't support SVG favicons
In case the source image is not in vector format, you can attempt to convert a raster image using tools like [this](https://www.aconvert.com/image/png-to-svg/).
## Customizing Gitea pages and resources
Gitea's executable contains all the resources required to run: templates, images, style-sheets
and translations. Any of them can be overridden by placing a replacement in a matching path
inside the `custom` directory. For example, to replace the default `.gitignore` provided
for C++ repositories, we want to replace `options/gitignore/C++`. To do this, a replacement
must be placed in `$GITEA_CUSTOM/options/gitignore/C++` (see about the location of the `CustomPath`
directory at the top of this document).
Every single page of Gitea can be changed. Dynamic content is generated using [go templates](https://pkg.go.dev/html/template),
which can be modified by placing replacements below the `$GITEA_CUSTOM/templates` directory.
To obtain any embedded file (including templates), the [`gitea embedded` tool](../administration/cmd-embedded.md) can be used. Alternatively, they can be found in the [`templates`](https://github.com/go-gitea/gitea/tree/main/templates) directory of Gitea source (Note: the example link is from the `main` branch. Make sure to use templates compatible with the release you are using).
Be aware that any statement contained inside `{{` and `}}` are Gitea's template syntax and
shouldn't be touched without fully understanding these components.
### Customizing startpage / homepage
Copy [`home.tmpl`](https://github.com/go-gitea/gitea/blob/main/templates/home.tmpl) for your version of Gitea from `templates` to `$GITEA_CUSTOM/templates`.
Edit as you wish.
Dont forget to restart your Gitea to apply the changes.
### Adding links and tabs
If all you want is to add extra links to the top navigation bar or footer, or extra tabs to the repository view, you can put them in `extra_links.tmpl` (links added to the navbar), `extra_links_footer.tmpl` (links added to the left side of footer), and `extra_tabs.tmpl` inside your `$GITEA_CUSTOM/templates/custom/` directory.
For instance, let's say you are in Germany and must add the famously legally-required "Impressum"/about page, listing who is responsible for the site's content:
just place it under your "$GITEA_CUSTOM/public/assets/" directory (for instance `$GITEA_CUSTOM/public/assets/impressum.html`) and put a link to it in either `$GITEA_CUSTOM/templates/custom/extra_links.tmpl` or `$GITEA_CUSTOM/templates/custom/extra_links_footer.tmpl`.
To match the current style, the link should have the class name "item", and you can use `{{AppSubUrl}}` to get the base URL:
For more information, see [Adding Legal Pages](../administration/adding-legal-pages.md).
You can add new tabs in the same way, putting them in `extra_tabs.tmpl`.
The exact HTML needed to match the style of other tabs is in the file
`templates/repo/header.tmpl`
([source in GitHub](https://github.com/go-gitea/gitea/blob/main/templates/repo/header.tmpl))
### Other additions to the page
Apart from `extra_links.tmpl` and `extra_tabs.tmpl`, there are other useful templates you can put in your `$GITEA_CUSTOM/templates/custom/` directory:
-`header.tmpl`, just before the end of the `<head>` tag where you can add custom CSS files for instance.
-`body_outer_pre.tmpl`, right after the start of `<body>`.
-`body_inner_pre.tmpl`, before the top navigation bar, but already inside the main container `<div class="full height">`.
-`body_inner_post.tmpl`, before the end of the main container.
-`body_outer_post.tmpl`, before the bottom `<footer>` element.
-`footer.tmpl`, right before the end of the `<body>` tag, a good place for additional JavaScript.
### Using Gitea variables
It's possible to use various Gitea variables in your custom templates.
First, _temporarily_ enable development mode: in your `app.ini` change from `RUN_MODE = prod` to `RUN_MODE = dev`. Then add `{{ $ | DumpVar }}` to any of your templates, restart Gitea and refresh that page; that will dump all available variables.
Find the data that you need, and use the corresponding variable; for example, if you need the name of the repository then you'd use `{{.Repository.Name}}`.
If you need to transform that data somehow, and aren't familiar with Go, an easy workaround is to add the data to the DOM and add a small JavaScript script block to manipulate the data.
### Example: PlantUML
You can add [PlantUML](https://plantuml.com/) support to Gitea's markdown by using a PlantUML server.
The data is encoded and sent to the PlantUML server which generates the picture. There is an online
demo server at http://www.plantuml.com/plantuml, but if you (or your users) have sensitive data you
can set up your own [PlantUML server](https://plantuml.com/server) instead. To set up PlantUML rendering,
copy JavaScript files from https://gitea.com/davidsvantesson/plantuml-code-highlight and put them in your
`$GITEA_CUSTOM/public/assets/` folder. Then add the following to `custom/footer.tmpl`:
You also need to download the content of the library [Madeleine.js](https://github.com/beige90/Madeleine.js) and place it under `$GITEA_CUSTOM/public/assets/` folder.
You should end-up with a folder structure similar to:
```
$GITEA_CUSTOM/templates
-- custom
`-- footer.tmpl
$GITEA_CUSTOM/public/assets/
-- Madeleine.js
|-- LICENSE
|-- README.md
|-- css
| |-- pygment_trac.css
| `-- stylesheet.css
|-- examples
| |-- ajax.html
| |-- index.html
| `-- upload.html
|-- images
| |-- bg_hr.png
| |-- blacktocat.png
| |-- icon_download.png
| `-- sprite_download.png
|-- models
| |-- dino2.stl
| |-- ducati.stl
| |-- gallardo.stl
| |-- lamp.stl
| |-- octocat.stl
| |-- skull.stl
| `-- treefrog.stl
`-- src
|-- Madeleine.js
|-- css
| `-- Madeleine.css
|-- icons
| |-- logo.png
| |-- madeleine.eot
| |-- madeleine.svg
| |-- madeleine.ttf
| `-- madeleine.woff
`-- lib
|-- MadeleineConverter.js
|-- MadeleineLoader.js
|-- detector.js
|-- stats.js
`-- three.min.js
```
Then restart Gitea and open a STL file on your Gitea instance.
## Customizing Gitea mails
The `$GITEA_CUSTOM/templates/mail` folder allows changing the body of every mail of Gitea.
Override by making a copy of the file under `$GITEA_CUSTOM/templates/mail` using a
full path structure matching source.
Any statement contained inside `{{` and `}}` are Gitea's template
syntax and shouldn't be touched without fully understanding these components.
## Adding Analytics to Gitea
Google Analytics, Matomo (previously Piwik), and other analytics services can be added to Gitea. To add the tracking code, refer to the `Other additions to the page` section of this document, and add the JavaScript to the `$GITEA_CUSTOM/templates/custom/header.tmpl` file.
## Customizing gitignores, labels, licenses, locales, and readmes
Place custom files in corresponding sub-folder under `custom/options`.
:::note
The files should not have a file extension, e.g. `Labels` rather than `Labels.txt`
:::
### gitignores
To add custom .gitignore, add a file with existing [.gitignore rules](https://git-scm.com/docs/gitignore) in it to `$GITEA_CUSTOM/options/gitignore`
## Customizing the git configuration
Starting with Gitea 1.20, you can customize the git configuration via the `git.config` section.
### Enabling signed git pushes
To enable signed git pushes, set these two options:
```ini
[git.config]
receive.advertisePushOptions=true
receive.certNonceSeed=<randomstring>
```
`certNonceSeed` should be set to a random string and be kept secret.
### Labels
Starting with Gitea 1.19, you can add a file that follows the [YAML label format](https://github.com/go-gitea/gitea/blob/main/options/label/Advanced.yaml) to `$GITEA_CUSTOM/options/label`:
```yaml
labels:
- name:"foo/bar"# name of the label that will appear in the dropdown
exclusive:true# whether to use the exclusive namespace for scoped labels. scoped delimiter is /
color:aabbcc# hex colour coding
description:Some label# long description of label intent
```
The [legacy file format](https://github.com/go-gitea/gitea/blob/main/options/label/Default) can still be used following the format below, however we strongly recommend using the newer YAML format instead.
`#hex-color label name ; label description`
For more information, see the [labels documentation](usage/labels.md).
### Licenses
To add a custom license, add a file with the license text to `$GITEA_CUSTOM/options/license`
### Locales
Locales are managed via our [Crowdin](https://crowdin.com/project/gitea).
You can override a locale by placing an altered locale file in `$GITEA_CUSTOM/options/locale`.
Gitea's default locale files can be found in the [`options/locale`](https://github.com/go-gitea/gitea/tree/main/options/locale) source folder and these should be used as examples for your changes.
To add a completely new locale, as well as placing the file in the above location, you will need to add the new lang and name to the `[i18n]` section in your `app.ini`. Keep in mind that Gitea will use those settings as **overrides**, so if you want to keep the other languages as well you will need to copy/paste the default values and add your own to them.
```ini title="app.ini"
[i18n]
LANGS = en-US,foo-BAR
NAMES = English,FooBar
```
The first locale will be used as the default if user browser's language doesn't match any locale in the list.
Locales may change between versions, so keeping track of your customized locales is highly encouraged.
### Readmes
To add a custom Readme, add a markdown formatted file (without an `.md` extension) to `$GITEA_CUSTOM/options/readme`
:::note
Readme templates support **variable expansion**.
currently there are `{Name}` (name of repository), `{Description}`, `{CloneURL.SSH}`, `{CloneURL.HTTPS}` and `{OwnerName}`
:::
### Reactions
To change reaction emoji's you can set allowed reactions at app.ini
A full list of supported emoji's is at [emoji list](https://gitea.com/gitea/gitea.com/issues/8)
## Customizing the look of Gitea
The built-in themes are `gitea-light`, `gitea-dark`, and `gitea-auto` (which automatically adapts to OS settings).
The default theme can be changed via `DEFAULT_THEME` in the [ui](../administration/config-cheat-sheet.md#ui-ui) section of `app.ini`.
Gitea also has support for user themes, which means every user can select which theme should be used.
The list of themes a user can choose from can be configured with the `THEMES` value in the [ui](../administration/config-cheat-sheet.md#ui-ui) section of `app.ini`.
To make a custom theme available to all users:
1. Add a CSS file to `$GITEA_CUSTOM/public/assets/css/theme-<theme-name>.css`.
The value of `$GITEA_CUSTOM` of your instance can be queried by calling `gitea help` and looking up the value of "CustomPath".
2. Add `<theme-name>` to the comma-separated list of setting `THEMES` in `app.ini`, or leave `THEMES` empty to allow all themes.
Community themes are listed in [gitea/awesome-gitea#themes](https://gitea.com/gitea/awesome-gitea#themes).
The default theme sources can be found [here](https://github.com/go-gitea/gitea/blob/main/web_src/css/themes).
If your custom theme is considered a dark theme, set the global css variable `--is-dark-theme` to `true`.
This allows Gitea to adjust the Monaco code editor's theme accordingly.
Gitea has mailer functionality for sending transactional emails (such as registration confirmation). It can be configured to either use Sendmail (or compatible MTAs like Postfix and msmtp) or directly use SMTP server.
## Using Sendmail
Use `sendmail` command as mailer.
:::note
For use in the official Gitea Docker image, please configure with the SMTP version (see the following section).
:::
:::note
For Internet-facing sites consult documentation of your MTA for instructions to send emails over TLS. Also set up SPF, DMARC, and DKIM DNS records to make emails sent be accepted as legitimate by various email providers.
Restart Gitea for the configuration changes to take effect.
To send a test email to validate the settings, go to Gitea > Site Administration > Configuration > Summary -> Mailer Configuration.
For the full list of options check the [Config Cheat Sheet](../administration/config-cheat-sheet.md)
:::note
Authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through:
:::
- STARTTLS (also known as Opportunistic TLS) via port 587. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
- SMTPS connection (SMTP over TLS) via the default port 465. Connection to the server use TLS from the beginning.
- Forced SMTPS connection with `PROTOCOL=smtps`. (These are both known as Implicit TLS.)
This is due to protections imposed by the Go internal libraries against STRIPTLS attacks.
Note that Implicit TLS is recommended by [RFC8314](https://tools.ietf.org/html/rfc8314#section-3) since 2018.
### Gmail
The following configuration should work with GMail's SMTP server:
```ini title="app.ini"
[mailer]
ENABLED = true
HOST = smtp.gmail.com:465 ; Remove this line for Gitea >= 1.18.0
Note that you'll need to create and use an [App password](https://support.google.com/accounts/answer/185833?hl=en) by enabling 2FA on your Google
account. You won't be able to use your Google account password directly.
### ProtonMail
This feature is currently only available for select Proton for Business customers and those with Visionary and Family plans with custom domain addresses. See [ProtonMail's SMTP documentation](https://proton.me/support/smtp-submission) for more information. This limitation can be circumvented by using the ProtonMail Bridge application.
Note that emails sent using SMTP are not [end-to-end encrypted](https://proton.me/support/proton-mail-encryption-explained). However, they’re still stored with zero-access encryption like any other emails in your Proton Mail inbox.
The following configuration should work with ProtonMail's SMTP server:
1. In your browser (or desktop application), sign in to your Proton Mail account and select **Settings → All settings → Proton Mail → IMAP/SMTP → SMTP tokens**.
2. Click **Generate token**.
3. Enter the following details to create a new SMTP token:
- **Token name**: Select a name for your token. This is for your reference only and does not affect the token's functionality.
- **Email address**: Select one of your active custom domain addresses to pair with your token. Copy this email address and use it for the `FROM` and `USER` configuration in `app.ini`.
4. Click **Generate**.
5. Enter your Proton Mail Account password.
Your SMTP username and SMTP token (password) will be generated. You can now enter them as the `USER` and `PASSWD` in your `app.ini` configuration.
After closing the popup, you will not be able to see this SMTP token (password) again for security reasons. You can always generate more tokens if you need to rotate passwords.
Note: Your Proton Mail login or mailbox passwords will not work with SMTP
This supports rendering of whole files. If you want to render code blocks in markdown you would need to do something with javascript. See some examples on the [Customizing Gitea](../administration/customizing-gitea.md) page.
## Installing external binaries
In order to get file rendering through external binaries, their associated packages must be installed.
If you're using a Docker image, your `Dockerfile` should contain something along this lines:
If your external markup relies on additional classes and attributes on the generated HTML elements, you might need to enable custom sanitizer policies. Gitea uses the [`bluemonday`](https://godoc.org/github.com/microcosm-cc/bluemonday) package as our HTML sanitizer. The example below could be used to support server-side [KaTeX](https://katex.org/) rendering output from [`pandoc`](https://pandoc.org/).
```ini
[markup.sanitizer.TeX]
; Pandoc renders TeX segments as <span>s with the "math" class, optionally
; with "inline" or "display" classes depending on context.
; - note this is different from the built-in math support in our markdown parser which uses <code>
You must define `ELEMENT` and `ALLOW_ATTR` in each section.
To define multiple entries, add a unique alphanumeric suffix (e.g., `[markup.sanitizer.1]` and `[markup.sanitizer.something]`).
To apply a sanitisation rules only for a specify external renderer they must use the renderer name, e.g. `[markup.sanitizer.asciidoc.rule-1]`, `[markup.sanitizer.<renderer>.rule-1]`.
**Note**: If the rule is defined above the renderer ini section or the name does not match a renderer it is applied to every renderer.
Once your configuration changes have been made, restart Gitea to have changes take effect.
**Note**: Prior to Gitea 1.12 there was a single `markup.sanitiser` section with keys that were redefined for multiple rules, however,
there were significant problems with this method of configuration necessitating configuration through multiple sections.
### Example: HTML
Render HTML files directly:
```ini
[markup.html]
ENABLED=true
FILE_EXTENSIONS=.html,.htm
RENDER_COMMAND=cat
; Input is not a standard input but a file
IS_INPUT_FILE=true
[markup.sanitizer.html.1]
ELEMENT=div
ALLOW_ATTR=class
[markup.sanitizer.html.2]
ELEMENT=a
ALLOW_ATTR=class
```
### Example: Office DOCX
Display Office DOCX files with [`pandoc`](https://pandoc.org/):
```ini
[markup.docx]
ENABLED=true
FILE_EXTENSIONS=.docx
RENDER_COMMAND="pandoc --from docx --to html --self-contained --template /path/to/basic.html"
[markup.sanitizer.docx.img]
ALLOW_DATA_URI_IMAGES=true
```
The template file has the following content:
```
$body$
```
### Example: Jupyter Notebook
Display Jupyter Notebook files with [`nbconvert`](https://github.com/jupyter/nbconvert):
```ini
[markup.jupyter]
ENABLED=true
FILE_EXTENSIONS=.ipynb
RENDER_COMMAND="jupyter-nbconvert --stdin --stdout --to html --template basic"
[markup.sanitizer.jupyter.img]
ALLOW_DATA_URI_IMAGES=true
```
## Customizing CSS
The external renderer is specified in the .ini in the format `[markup.XXXXX]` and the HTML supplied by your external renderer will be wrapped in a `<div>` with classes `markup` and `XXXXX`. The `markup` class provides out of the box styling (as does `markdown` if `XXXXX` is `markdown`). Otherwise you can use these classes to specifically target the contents of your rendered HTML.
And so you could write some CSS:
```css
.markup.XXXXXhtml{
font-size:100%;
overflow-y:scroll;
-webkit-text-size-adjust:100%;
-ms-text-size-adjust:100%;
}
.markup.XXXXXbody{
color:#444;
font-family:Georgia,Palatino,'Palatino Linotype',Times,'Times New Roman',serif;
font-size:12px;
line-height:1.7;
padding:1em;
margin:auto;
max-width:42em;
background:#fefefe;
}
.markup.XXXXXp{
color:orangered;
}
```
Add your stylesheet to your custom directory e.g `custom/public/assets/css/my-style-XXXXX.css` and import it using a custom header file `custom/templates/custom/header.tmpl`:
**Remember that fail2ban is powerful and can cause lots of issues if you do it incorrectly, so make
sure to test this before relying on it so you don't lock yourself out.**
Gitea returns an HTTP 200 for bad logins in the web logs, but if you have logging options on in
`app.ini`, then you should be able to go off of `log/gitea.log`, which gives you something like this
on a bad authentication from the web or CLI using SSH or HTTP respectively:
```log
2018/04/26 18:15:54 [I] Failed authentication attempt for user from xxx.xxx.xxx.xxx
```
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:143:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
```
(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:155:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
```
(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:198:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
```
(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:213:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
```
(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:227:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
```
(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:249:sshConnectionFailed() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
```
(From 1.15 this new message will available and doesn't have any of the false positive results that above messages from publicKeyHandler do. This will only be logged if the user has completely failed authentication.)
```log
2020/10/15 16:08:44 ...s/context/context.go:204:HandleText() [E] invalid credentials from xxx.xxx.xxx.xxx
```
Add our filter in `/etc/fail2ban/filter.d/gitea.local`:
```ini
# gitea.local
[Definition]
failregex=.*(Failed authentication attempt|invalid credentials|Attempted access of unknown user).* from <HOST>
ignoreregex=
```
Add our jail in `/etc/fail2ban/jail.d/gitea.local`:
```ini
[gitea]
enabled=true
filter=gitea
logpath=/var/lib/gitea/log/gitea.log
maxretry=10
findtime=3600
bantime=900
action=iptables-allports
```
If you're using Docker, you'll also need to add an additional jail to handle the **FORWARD**
chain in **iptables**. Configure it in `/etc/fail2ban/jail.d/gitea-docker.local`:
```ini
[gitea-docker]
enabled=true
filter=gitea
logpath=/var/lib/gitea/log/gitea.log
maxretry=10
findtime=3600
bantime=900
action=iptables-allports[chain="FORWARD"]
```
Then simply run `service fail2ban restart` to apply your changes. You can check to see if
fail2ban has accepted your configuration using `service fail2ban status`.
Make sure and read up on fail2ban and configure it to your needs, this bans someone
for **15 minutes** (from all ports) when they fail authentication 10 times in an hour.
If you run Gitea behind a reverse proxy with Nginx (for example with Docker), you need to add
this to your Nginx configuration so that IPs don't show up as 127.0.0.1:
```
proxy_set_header X-Real-IP $remote_addr;
```
The security options in `app.ini` need to be adjusted to allow the interpretation of the headers
as well as the list of IP addresses and networks that describe trusted proxy servers
(See the [configuration cheat sheet](../administration/config-cheat-sheet.md#security-security) for more information).
```
REVERSE_PROXY_LIMIT = 1
REVERSE_PROXY_TRUSTED_PROXIES = 127.0.0.1/8 ; 172.17.0.0/16 for the docker default network
Before you enable HTTPS, make sure that you have valid SSL/TLS certificates.
You could use self-generated certificates for evaluation and testing. Please run `gitea cert --host [HOST]` to generate a self signed certificate.
If you are using Apache or nginx on the server, it's recommended to check the [reverse proxy guide](./reverse-proxies.md).
To use Gitea's built-in HTTPS support, you must change your `app.ini` file:
```ini
[server]
PROTOCOL=https
ROOT_URL=https://git.example.com:3000/
HTTP_PORT=3000
CERT_FILE=cert.pem
KEY_FILE=key.pem
```
Note that if your certificate is signed by a third party certificate authority (i.e. not self-signed), then cert.pem should contain the certificate chain. The server certificate must be the first entry in cert.pem, followed by the intermediaries in order (if any). The root certificate does not have to be included because the connecting client must already have it in order to establish the trust relationship.
To learn more about the config values, please checkout the [Config Cheat Sheet](./config-cheat-sheet.md#server-server).
For the `CERT_FILE` or `KEY_FILE` field, the file path is relative to the `GITEA_CUSTOM` environment variable when it is a relative path. It can be an absolute path as well.
### Setting up HTTP redirection
The Gitea server is only able to listen to one port; to redirect HTTP requests to the HTTPS port, you will need to enable the HTTP redirection service:
```ini
[server]
REDIRECT_OTHER_PORT=true
; Port the redirection service should listen on
PORT_TO_REDIRECT=3080
```
If you are using Docker, make sure that this port is configured in your `docker-compose.yml` file.
## Using ACME (Default: Let's Encrypt)
[ACME](https://tools.ietf.org/html/rfc8555) is a Certificate Authority standard protocol that allows you to automatically request and renew SSL/TLS certificates. [Let's Encrypt](https://letsencrypt.org/) is a free publicly trusted Certificate Authority server using this standard. Only `HTTP-01` and `TLS-ALPN-01` challenges are implemented. In order for ACME challenges to pass and verify your domain ownership, external traffic to the gitea domain on port `80` (`HTTP-01`) or port `443` (`TLS-ALPN-01`) has to be served by the gitea instance. Setting up [HTTP redirection](#setting-up-http-redirection) and port-forwards might be needed for external traffic to route correctly. Normal traffic to port `80` will otherwise be automatically redirected to HTTPS. **You must consent** to the ACME provider's terms of service (default Let's Encrypt's [terms of service](https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf)).
Minimum setup using the default Let's Encrypt:
```ini
[server]
PROTOCOL=https
DOMAIN=git.example.com
ENABLE_ACME=true
ACME_ACCEPTTOS=true
ACME_DIRECTORY=https
;; Email can be omitted here and provided manually at first run, after which it is cached
Minimum setup using a [smallstep CA](https://github.com/smallstep/certificates), refer to [their tutorial](https://smallstep.com/docs/tutorials/acme-challenge) for more information.
Enabling HTTPS only at the proxy level is referred as [TLS Termination Proxy](https://en.wikipedia.org/wiki/TLS_termination_proxy). The proxy server accepts incoming TLS connections, decrypts the contents, and passes the now unencrypted contents to Gitea. This is normally fine as long as both the proxy and Gitea instances are either on the same machine, or on different machines within private network (with the proxy is exposed to outside network). If your Gitea instance is separated from your proxy over a public network, or if you want full end-to-end encryption, you can also [enable HTTPS support directly in Gitea using built-in server](#using-the-built-in-server) and forward the connections over HTTPS instead.
The logging configuration of Gitea mainly consists of 3 types of components:
- The `[log]` section for general configuration
-`[log.<mode-name>]` sections for the configuration of different log writers to output logs, aka: "writer mode", the mode name is also used as "writer name".
- The `[log]` section can also contain sub-logger configurations following the key schema `logger.<logger-name>.<CONFIG-KEY>`
There is a fully functional log output by default, so it is not necessary to define one.
## Collecting Logs for Help
To collect logs for help and issue report, see [Support Options](help/support.md).
## The `[log]` section
Configuration of logging facilities in Gitea happen in the `[log]` section and its subsections.
In the top level `[log]` section the following configurations can be placed:
-`ROOT_PATH`: (Default: **%(GITEA_WORK_DIR)/log**): Base path for log files
-`MODE`: (Default: **console**) List of log outputs to use for the Default logger.
-`LEVEL`: (Default: **Info**) Least severe log events to persist, case-insensitive. Possible values are: `Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`.
-`STACKTRACE_LEVEL`: (Default: **None**) For this and more severe events the stacktrace will be printed upon getting logged.
And it can contain the following sub-loggers:
-`logger.router.MODE`: (Default: **,**): List of log outputs to use for the Router logger.
-`logger.access.MODE`: (Default: **_empty_**) List of log outputs to use for the Access logger. By default, the access logger is disabled.
-`logger.xorm.MODE`: (Default: **,**) List of log outputs to use for the XORM logger.
Setting a comma (`,`) to sub-logger's mode means making it use the default global `MODE`.
## Quick samples
### Default (empty) Configuration
The empty configuration is equivalent to default:
```ini
[log]
ROOT_PATH=%(GITEA_WORK_DIR)/log
MODE=console
LEVEL=Info
STACKTRACE_LEVEL=None
logger.router.MODE=,
logger.xorm.MODE=,
logger.access.MODE=
; this is the config options of "console" mode (used by MODE=console above)
[log.console]
MODE=console
FLAGS=stdflags
PREFIX=
COLORIZE=true
```
This is equivalent to sending all logs to the console, with default Golang log being sent to the console log too.
This is only a sample, and it is the default, do not need to write it into your configuration file.
### Disable Router logs and record some access logs to file
The Router logger is disabled, the access logs (>=Warn) goes into `access.log`:
```ini
[log]
logger.router.MODE=
logger.access.MODE=access-file
[log.access-file]
MODE=file
LEVEL=Warn
FILE_NAME=access.log
```
### Set different log levels for different modes
Default logs (>=Warn) goes into `gitea.log`, while Error logs goes into `file-error.log`:
```ini
[log]
LEVEL=Warn
MODE=file, file-error
; by default, the "file" mode will record logs to %(log.ROOT_PATH)/gitea.log, so we don't need to set it
; [log.file]
; by default, the MODE (actually it's the output writer of this logger) is taken from the section name, so we don't need to set it either
; MODE = file
[log.file-error]
MODE=file
LEVEL=Error
FILE_NAME=file-error.log
```
## Log outputs (mode and writer)
Gitea provides the following log output writers:
-`console` - Log to `stdout` (or `stderr` if it is set in the config)
-`file` - Log to a file
-`conn` - Log to a socket (network or unix)
### Common configuration
Certain configuration is common to all modes of log output:
-`MODE` is the mode of the log output writer. It will default to the mode name in the ini section. Thus `[log.console]` will default to `MODE = console`.
-`LEVEL` is the lowest level that this output will log.
-`STACKTRACE_LEVEL` is the lowest level that this output will print a stacktrace.
-`COLORIZE` will default to `true` for `console` as described, otherwise it will default to `false`.
#### `EXPRESSION`
`EXPRESSION` represents a regular expression that log events must match to be logged by the output writer.
Either the log message, (with colors removed), must match or the `longfilename:linenumber:functionname` must match.
NB: the whole message or string doesn't need to completely match.
Please note this expression will be run in the writer's goroutine but not the logging event goroutine.
#### `FLAGS`
`FLAGS` represents the preceding logging context information that is
printed before each message. It is a comma-separated string set. The order of values does not matter.
It defaults to `stdflags` (= `date,time,medfile,shortfuncname,levelinitial`)
Possible values are:
-`none` or `,` - No flags.
-`date` - the date in the local time zone: `2009/01/23`.
-`time` - the time in the local time zone: `01:23:23`.
-`longfile` - full file name and line number: `/a/b/c/d.go:23`.
-`shortfile` - final file name element and line number: `d.go:23`.
-`funcname` - function name of the caller: `runtime.Caller()`.
-`shortfuncname` - last part of the function name. Overrides `funcname`.
-`utc` - if date or time is set, use UTC rather than the local time zone.
-`levelinitial` - initial character of the provided level in brackets eg. `[I]` for info.
-`level` - level in brackets `[INFO]`.
-`gopid` - the Goroutine-PID of the context.
-`medfile` - last 20 characters of the filename - equivalent to `shortfile,longfile`.
-`stdflags` - equivalent to `date,time,medfile,shortfuncname,levelinitial`.
### Console mode
In this mode the logger will forward log messages to the stdout and
stderr streams attached to the Gitea process.
For loggers in console mode, `COLORIZE` will default to `true` if not
on windows, or the Windows terminal can be set into ANSI mode or is a
cygwin or Msys pipe.
Settings:
-`STDERR`: **false**: Whether the logger should print to `stderr` instead of `stdout`.
### File mode
In this mode the logger will save log messages to a file.
Settings:
-`FILE_NAME`: The file to write the log events to, relative to `ROOT_PATH`, Default to `%(ROOT_PATH)/gitea.log`. Exception: access log will default to `%(ROOT_PATH)/access.log`.
-`MAX_SIZE_SHIFT`: **28**: Maximum size shift of a single file. 28 represents 256Mb. For details see below.
-`LOG_ROTATE`**true**: Whether to rotate the log files. TODO: if false, will it delete instead on daily rotate, or do nothing?.
-`DAILY_ROTATE`: **true**: Whether to rotate logs daily.
-`MAX_DAYS`: **7**: Delete rotated log files after this number of days.
-`COMPRESS`: **true**: Whether to compress old log files by default with gzip.
-`COMPRESSION_LEVEL`: **-1**: Compression level. For details see below.
`MAX_SIZE_SHIFT` defines the maximum size of a file by left shifting 1 the given number of times (`1 << x`).
The exact behavior at the time of v1.17.3 can be seen [here](https://github.com/go-gitea/gitea/blob/v1.17.3/modules/setting/log.go#L185).
The useful values of `COMPRESSION_LEVEL` are from 1 (best speed) to 9 (best compression). [DefaultCompression](https://pkg.go.dev/compress/gzip#pkg-constants) (-1) and [HuffmanOnly](https://pkg.go.dev/compress/flate#HuffmanOnly) (-2) can also be chosen.
Beware that better compression might come with higher resource usage.
### Conn mode
In this mode the logger will send log messages over a network socket.
Settings:
-`ADDR`: **:7020**: Sets the address to connect to.
-`PROTOCOL`: **tcp**: Set the protocol, either "tcp", "unix" or "udp".
-`RECONNECT`: **false**: Try to reconnect when connection is lost.
-`RECONNECT_ON_MSG`: **false**: Reconnect host for every single message.
### The "Router" logger
The Router logger logs the following message types when Gitea's route handlers work:
-`started` messages will be logged at TRACE level
-`polling`/`completed` routers will be logged at INFO. Exception: "/assets" static resource requests are also logged at TRACE.
-`slow` routers will be logged at WARN
-`failed` routers will be logged at WARN
### The "XORM" logger
To make XORM outputs SQL logs, the `LOG_SQL` in `[database]` section should also be set to `true`.
### The "Access" logger
The Access logger is a new logger since Gitea 1.9. It provides a NCSA
Common Log compliant log format. It's highly configurable but caution
should be taken when changing its template. The main benefit of this
logger is that Gitea can now log accesses in a standard log format so
standard tools may be used.
You can enable this logger using `logger.access.MODE = ...`.
If desired the format of the Access logger can be changed by changing
the value of the `ACCESS_LOG_TEMPLATE`.
Please note, the access logger will log at `INFO` level, setting the
`LEVEL` of this logger to `WARN` or above will result in no access logs.
#### The ACCESS_LOG_TEMPLATE
This value represents a go template. Its default value is
| `.FallbackSubject` | string | Always | A default subject line. See Below. |
| `.Subject` | string | Only in body | The _subject_, once resolved. |
| `.Body` | string | Always | The message of the issue, pull request or comment, parsed from Markdown into HTML and sanitized. Do not confuse with the _mail body_. |
| `.Link` | string | Always | The address of the originating issue, pull request or comment. |
| `.Issue` | models.Issue | Always | The issue (or pull request) originating the notification. To get data specific to a pull request (e.g. `HasMerged`), `.Issue.PullRequest` can be used, but care should be taken as this field will be `nil` if the issue is _not_ a pull request. |
| `.Comment` | models.Comment | If applicable | If the notification is from a comment added to an issue or pull request, this will contain the information about the comment. |
| `.IsPull` | bool | Always | `true` if the mail notification is associated with a pull request (i.e. `.Issue.PullRequest` is not `nil`). |
| `.Repo` | string | Always | Name of the repository, including owner name (e.g. `mike/stuff`) |
| `.User` | models.User | Always | Owner of the repository from which the event originated. To get the user name (e.g. `mike`),`.User.Name` can be used. |
| `.Doer` | models.User | Always | User that executed the action triggering the notification event. To get the user name (e.g. `rhonda`), `.Doer.Name` can be used. |
| `.IsMention` | bool | Always | `true` if this notification was only generated because the user was mentioned in the comment, while not being subscribed to the source. It will be `false` if the recipient was subscribed to the issue or repository. |
| `.SubjectPrefix` | string | Always | `Re: ` if the notification is about other than issue or pull request creation; otherwise an empty string. |
| `.ActionType` | string | Always | `"issue"` or `"pull"`. Will correspond to the actual _action type_ independently of which template was selected. |
| `.ActionName` | string | Always | It will be one of the action types described above (`new`, `comment`, etc.), and will correspond to the actual _action name_ independently of which template was selected. |
| `.ReviewComments` | []models.Comment | Always | List of code comments in a review. The comment text will be in `.RenderedContent` and the referenced code will be in `.Patch`. |
All names are case sensitive.
### The _subject_ part of the template
The template engine used for the mail _subject_ is golang's [`text/template`](https://go.dev/pkg/text/template/).
Please refer to the linked documentation for details about its syntax.
The _subject_ is built using the following steps:
- A template is selected according to the type of notification and to what templates are present.
- The template is parsed and resolved (e.g. `{{.Issue.Index}}` is converted to the number of the issue
or pull request).
- All space-like characters (e.g. `TAB`, `LF`, etc.) are converted to normal spaces.
- All leading, trailing and redundant spaces are removed.
- The string is truncated to its first 256 runes (characters).
If the end result is an empty string, **or** no subject template was available (i.e. the selected template
did not include a subject part), Gitea's **internal default** will be used.
The internal default (fallback) subject is the equivalent of:
Users could do repository-level code search without setting up a repository indexer.
The builtin code search is based on the `git grep` command, which is fast and efficient for small repositories.
Better code search support could be achieved by setting up the repository indexer.
## Setting up the repository indexer
Gitea can search through the files of the repositories by enabling this function in your [`app.ini`](../administration/config-cheat-sheet.md):
```ini
[indexer]
; ...
REPO_INDEXER_ENABLED = true
REPO_INDEXER_PATH = indexers/repos.bleve
MAX_FILE_SIZE = 1048576
REPO_INDEXER_INCLUDE =
REPO_INDEXER_EXCLUDE = resources/bin/**
```
Please bear in mind that indexing the contents can consume a lot of system resources, especially when the index is created for the first time or globally updated (e.g. after upgrading Gitea).
### Choosing the files for indexing by size
The `MAX_FILE_SIZE` option will make the indexer skip all files larger than the specified value.
### Choosing the files for indexing by path
Gitea applies glob pattern matching from the [`gobwas/glob` library](https://github.com/gobwas/glob) to choose which files will be included in the index.
Limiting the list of files prevents the indexes from becoming polluted with derived or irrelevant files (e.g. lss, sym, map, etc.), so the search results are more relevant. It can also help reduce the index size.
`REPO_INDEXER_EXCLUDE_VENDORED` (default: true) excludes vendored files from index.
`REPO_INDEXER_INCLUDE` (default: empty) is a comma separated list of glob patterns to **include** in the index. An empty list means "_include all files_".
`REPO_INDEXER_EXCLUDE` (default: empty) is a comma separated list of glob patterns to **exclude** from the index. Files that match this list will not be indexed. `REPO_INDEXER_EXCLUDE` takes precedence over `REPO_INDEXER_INCLUDE`.
Pattern matching works as follows:
- To match all files with a `.txt` extension no matter what directory, use `**.txt`.
- To match all files with a `.txt` extension _only at the root level of the repository_, use `*.txt`.
- To match all files inside `resources/bin` and below, use `resources/bin/**`.
- To match all files _immediately inside_`resources/bin`, use `resources/bin/*`.
- To match all files named `Makefile`, use `**Makefile`.
- Matching a directory has no effect; the pattern `resources/bin` will not include/exclude files inside that directory; `resources/bin/**` will.
- All files and patterns are normalized to lower case, so `**Makefile`, `**makefile` and `**MAKEFILE` are equivalent.
Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com/gitea/` correctly in your configuration.
## Nginx and serve static resources directly
We can tune the performance in splitting requests into categories static and dynamic.
CSS files, JavaScript files, images and web fonts are static content.
The front page, a repository view or issue list is dynamic content.
Nginx can serve static resources directly and proxy only the dynamic requests to Gitea.
Nginx is optimized for serving static content, while the proxying of large responses might be the opposite of that
(see [https://serverfault.com/q/587386](https://serverfault.com/q/587386)).
Download a snapshot of the Gitea source repository to `/path/to/gitea/`.
After this, run `make frontend` in the repository directory to generate the static resources. We are only interested in the `public/` directory for this task, so you can delete the rest.
(You will need to have [Node with npm](https://nodejs.org/en/download/) and `make` installed to generate the static resources)
Depending on the scale of your user base, you might want to split the traffic to two distinct servers,
or use a cdn for the static files.
### Single node and single domain
Set `[server] STATIC_URL_PREFIX = /_/static` in your configuration.
```nginx
server {
listen 80;
server_name git.example.com;
location /_/static/assets/ {
alias /path/to/gitea/public/;
}
location / {
proxy_pass http://localhost:3000;
}
}
```
### Two nodes and two domains
Set `[server] STATIC_URL_PREFIX = http://cdn.example.com/gitea` in your configuration.
```nginx
# application server running Gitea
server {
listen 80;
server_name git.example.com;
location / {
proxy_pass http://localhost:3000;
}
}
```
```nginx
# static content delivery server
server {
listen 80;
server_name cdn.example.com;
location /gitea/ {
alias /path/to/gitea/public/;
}
location / {
return 404;
}
}
```
## Apache HTTPD
If you want Apache HTTPD to serve your Gitea instance, you can add the following to your Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
```apacheconf
<VirtualHost *:80>
...
ProxyPreserveHost On
ProxyRequests off
AllowEncodedSlashes NoDecode
ProxyPass / http://localhost:3000/ nocanon
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
:::note
The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
:::
If you wish to use Let's Encrypt with webroot validation, add the line `ProxyPass /.well-known !` before `ProxyPass` to disable proxying these requests to Gitea.
## Apache HTTPD with a sub-path
In case you already have a site, and you want Gitea to share the domain name, you can setup Apache HTTPD to serve Gitea under a sub-path by adding the following to you Apache HTTPD configuration (usually located at `/etc/apache2/httpd.conf` in Ubuntu):
```apacheconf
<VirtualHost *:80>
...
<Proxy *>
Order allow,deny
Allow from all
</Proxy>
AllowEncodedSlashes NoDecode
# Note: no trailing slash after either /git or port
ProxyPass /git http://localhost:3000 nocanon
ProxyPreserveHost On
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
Then you **MUST** set something like `[server] ROOT_URL = http://git.example.com/git/` correctly in your configuration.
:::note
The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`.
:::
## Caddy
If you want Caddy to serve your Gitea instance, you can add the following server block to your Caddyfile:
```
git.example.com {
reverse_proxy localhost:3000
}
```
## Caddy with a sub-path
In case you already have a site, and you want Gitea to share the domain name, you can setup Caddy to serve Gitea under a sub-path by adding the following to your server block in your Caddyfile:
```
git.example.com {
route /git/* {
uri strip_prefix /git
reverse_proxy localhost:3000
}
}
```
Then set `[server] ROOT_URL = http://git.example.com/git/` in your configuration.
## IIS
If you wish to run Gitea with IIS. You will need to setup IIS with URL Rewrite as reverse proxy.
1. Setup an empty website in IIS, named let's say, `Gitea Proxy`.
2. Follow the first two steps in [Microsoft's Technical Community Guide to Setup IIS with URL Rewrite](https://techcommunity.microsoft.com/t5/iis-support-blog/setup-iis-with-url-rewrite-as-a-reverse-proxy-for-real-world/ba-p/846222#M343). That is:
- Install Application Request Routing (ARR for short) either by using the Microsoft Web Platform Installer 5.1 (WebPI) or downloading the extension from [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing)
- Once the module is installed in IIS, you will see a new Icon in the IIS Administration Console called URL Rewrite.
- Open the IIS Manager Console and click on the `Gitea Proxy` Website from the tree view on the left. Select and double click the URL Rewrite Icon from the middle pane to load the URL Rewrite interface.
- Choose the `Add Rule` action from the right pane of the management console and select the `Reverse Proxy Rule` from the `Inbound and Outbound Rules` category.
- In the Inbound Rules section, set the server name to be the host that Gitea is running on with its port. e.g. if you are running Gitea on the localhost with port 3000, the following should work: `127.0.0.1:3000`
- Enable SSL Offloading
- In the Outbound Rules, ensure `Rewrite the domain names of the links in HTTP response` is set and set the `From:` field as above and the `To:` to your external hostname, say: `git.example.com`
- Now edit the `web.config` for your website to match the following: (changing `127.0.0.1:3000` and `git.example.com` as appropriate)
If you want HAProxy to serve your Gitea instance, you can add the following to your HAProxy configuration
add an acl in the frontend section to redirect calls to gitea.example.com to the correct backend
```
frontend http-in
...
acl acl_gitea hdr(host) -i gitea.example.com
use_backend gitea if acl_gitea
...
```
add the previously defined backend section
```
backend gitea
server localhost:3000 check
```
If you redirect the http content to https, the configuration work the same way, just remember that the connection between HAProxy and Gitea will be done via http so you do not have to enable https in Gitea's configuration.
## HAProxy with a sub-path
In case you already have a site, and you want Gitea to share the domain name, you can setup HAProxy to serve Gitea under a sub-path by adding the following to you HAProxy configuration:
```
frontend http-in
...
acl acl_gitea path_beg /gitea
use_backend gitea if acl_gitea
...
```
With that configuration http://example.com/gitea/ will redirect to your Gitea instance.
then for the backend section
```
backend gitea
http-request replace-path /gitea\/?(.*) \/\1
server localhost:3000 check
```
The added http-request will automatically add a trailing slash if needed and internally remove /gitea from the path to allow it to work correctly with Gitea by setting properly http://example.com/gitea as the root.
Then you **MUST** set something like `[server] ROOT_URL = http://example.com/gitea/` correctly in your configuration.
## Traefik
If you want traefik to serve your Gitea instance, you can add the following label section to your `docker-compose.yaml` (Assuming the provider is docker).
This config assumes that you are handling HTTPS on the traefik side and using HTTP between Gitea and traefik.
## Traefik with a sub-path
In case you already have a site, and you want Gitea to share the domain name, you can setup Traefik to serve Gitea under a sub-path by adding the following to your `docker-compose.yaml` (Assuming the provider is docker) :
Gitea will verify GPG commit signatures in the provided tree by
checking if the commits are signed by a key within the Gitea database,
or if the commit matches the default key for Git.
Keys are not checked to determine if they have expired or revoked.
Keys are also not checked with keyservers.
A commit will be marked with a grey unlocked icon if no key can be
found to verify it. If a commit is marked with a red unlocked icon,
it is reported to be signed with a key with an id.
:::note
The signer of a commit does not have to be an author or
committer of a commit.
:::
## Automatic Signing
There are a number of places where Gitea will generate commits itself:
- Repository Initialisation
- Wiki Changes
- CRUD actions using the editor or the API
- Merges from Pull Requests
Depending on configuration and server trust you may want Gitea to
sign these commits.
## Installing and generating a GPG key for Gitea
It is up to a server administrator to determine how best to install
a signing key. Gitea generates all its commits using the server `git`
command at present - and therefore the server `gpg` will be used for
signing (if configured.) Administrators should review best-practices
for GPG - in particular it is probably advisable to only install a
signing secret subkey without the master signing and certifying secret
key.
## General Configuration
Gitea's configuration for signing can be found with the
`[repository.signing]` section of `app.ini`:
```ini
...
[repository.signing]
SIGNING_KEY = default
SIGNING_NAME =
SIGNING_EMAIL =
INITIAL_COMMIT = always
CRUD_ACTIONS = pubkey, twofa, parentsigned
WIKI = never
MERGES = pubkey, twofa, basesigned, commitssigned
...
```
### `SIGNING_KEY`
The first option to discuss is the `SIGNING_KEY`. There are three main
options:
- `none` - this prevents Gitea from signing any commits
- `default` - Gitea will default to the key configured within `git config`
- `KEYID` - Gitea will sign commits with the gpg key with the ID
`KEYID`. In this case you should provide a `SIGNING_NAME` and
`SIGNING_EMAIL` to be displayed for this key.
The `default` option will interrogate `git config` for
`commit.gpgsign` option - if this is set, then it will use the results
of the `user.signingkey`, `user.name` and `user.email` as appropriate.
By adjusting Git's `config` file within Gitea's
repositories, `SIGNING_KEY=default` could be used to provide different
signing keys on a per-repository basis. However, this is clearly not an
ideal UI and therefore subject to change.
:::warning
**Since 1.17**, Gitea runs git in its own home directory `[git].HOME_PATH` (default to `%(APP_DATA_PATH)/home`)
and uses its own config `{[git].HOME_PATH}/.gitconfig`.
If you have your own customized git config for Gitea, you should set these configs in system git config (aka `/etc/gitconfig`)
or the Gitea internal git config `{[git].HOME_PATH}/.gitconfig`.
Related home files for git command (like `.gnupg`) should also be put in Gitea's git home directory `[git].HOME_PATH`.
If you like to keep the `.gnupg` directory outside of `{[git].HOME_PATH}/`, consider setting the `$GNUPGHOME` environment variable to your preferred location, otherwise Gitea will use the gpg keys only under `{[git].HOME_PATH}/.gnupg`.
:::
### `INITIAL_COMMIT`
This option determines whether Gitea should sign the initial commit
when creating a repository. The possible values are:
- `never`: Never sign
- `pubkey`: Only sign if the user has a public key
- `twofa`: Only sign if the user logs in with two factor authentication
- `always`: Always sign
Options other than `never` and `always` can be combined as a comma
separated list. The commit will be signed if all selected options are true.
### `WIKI`
This options determines if Gitea should sign commits to the Wiki.
The possible values are:
- `never`: Never sign
- `pubkey`: Only sign if the user has a public key
- `twofa`: Only sign if the user logs in with two-factor authentication
- `parentsigned`: Only sign if the parent commit is signed.
- `always`: Always sign
Options other than `never` and `always` can be combined as a comma
separated list. The commit will be signed if all selected options are true.
### `CRUD_ACTIONS`
This option determines if Gitea should sign commits from the web
editor or API CRUD actions. The possible values are:
- `never`: Never sign
- `pubkey`: Only sign if the user has a public key
- `twofa`: Only sign if the user logs in with two-factor authentication
- `parentsigned`: Only sign if the parent commit is signed.
- `always`: Always sign
Options other than `never` and `always` can be combined as a comma
separated list. The change will be signed if all selected options are true.
### `MERGES`
This option determines if Gitea should sign merge commits from PRs.
The possible options are:
- `never`: Never sign
- `pubkey`: Only sign if the user has a public key
- `twofa`: Only sign if the user logs in with two-factor authentication
- `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.
- `approved`: Only sign approved merges to a protected branch.
- `always`: Always sign
Options other than `never` and `always` can be combined as a comma
separated list. The merge will be signed if all selected options are true.
## Obtaining the Public Key of the Signing Key
The public key used to sign Gitea's commits can be obtained from the API at:
```sh
/api/v1/signing-key.gpg
```
In cases where there is a repository specific key this can be obtained from:
Loaded 50 of 1295 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.