The "Issues/PRs opened" event was folded into "Added to project", pull
requests can only be closed by workflows, closed projects don't run
workflows, and actions run in a fixed order. The new Permissions
section defines who can manage workflows and that they then act
without further permission checks. Also fix the editor steps, a typo
and the zh-tw page's nonexistent "New Workflow" button.
Assisted-by: Claude Code:claude-opus-5-5
Fix act runner doc typos and errors and simplify some grammar.
Co-authored-by: Peter Ryszkiewicz <[email protected]>
Co-committed-by: Peter Ryszkiewicz <[email protected]>
Original Gitea's repository no longer contains "Environment to INI" document referenced in "Managing Deployments With Environment Variables" section.
This commit fixes the reference by pointing the link to the last commit where needed doc was still present.
Reviewed-on: https://gitea.com/gitea/docs/pulls/315
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: andriibratanin <[email protected]>
Co-committed-by: andriibratanin <[email protected]>
This adds explanations, that were missing regarding Token scopes and the packages feature requiring a token with said scope. Also added a missing explanation, that tokens can be created in the user interface, not just the API. The reason this PR is created was due to misunderstandings around the package feature, that arose during the discussion in https://github.com/go-gitea/gitea/issues/32048 .
This PR aims to clarify the misunderstood points around tokens, scopes and the package feature.
During the creation of this PR bug https://github.com/go-gitea/gitea/issues/32078 was found, the scopes are always reported as `null` during the response of the initial `POST` to create the token.
Co-authored-by: Wladislav ヴラド Artsimovich <[email protected]>
Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/72
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: FrostKiwi <[email protected]>
Co-committed-by: FrostKiwi <[email protected]>
The SMTPS protocol uses port 465, not 587. Port 587 is instead used for STARTTLS.
Helps getting administrators stuck in cryptic errors such as:
Failed to send a testing email to "[email protected]": could not initiate SMTP session: tls: first record does not look like a TLS handshake
Reviewed-on: https://gitea.com/gitea/docs/pulls/295
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: kairosys-dev <[email protected]>
Co-committed-by: kairosys-dev <[email protected]>
Fix JSON syntax error in token creation request
The previous JSON was malformed:
{"name":test_token","scopes":[...]}
The value of "name" was missing opening quotes, causing the error:
invalid character 't' looking for beginning of value
Fixed by enclosing the string in double quotes:
{"name":"test_token","scopes":[...]}
Reviewed-on: https://gitea.com/gitea/docs/pulls/269
Reviewed-by: techknowlogick <[email protected]>
Co-authored-by: desysoft <[email protected]>
Co-committed-by: desysoft <[email protected]>
Added instructions on how to download the signature file using wget, and fixed a typo in the wget commands that would have caused the command to fail when copied/pasted.
Reviewed-on: https://gitea.com/gitea/docs/pulls/262
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: kmanwar89 <[email protected]>
Co-committed-by: kmanwar89 <[email protected]>
Documentation for my changes to ssh commit signing in <https://github.com/go-gitea/gitea/pull/34341>.
* Renames "GPG Commit Signatures" to "GPG/SSH Commit Signatures", since the url is called just signing and creating a new page would duplicate a lot
* _"The default option and repository specific signing keys are not supported for ssh keys"_
* the original draft implementation did support this for ssh keys
* this warning should avoid people expecting this gitconfig style things to work for ssh keys, since verifying is disabled in this case (e.g. pre 1.25 undocumented behavior preserved).
Co-authored-by: Lunny Xiao <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/241
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: Christopher Homberger <[email protected]>
Co-committed-by: Christopher Homberger <[email protected]>
## Description
Fix step 1 of the [Database Preparation](https://docs.gitea.com/installation/database-prep) docs.
## Changes
When a user modifies the */etc/mysql/my.cnf* config file as instructed in step 1 of the database preparation guide, they get an error message from MySQL when trying to log in as the root user after saving changes.
```shell
mysql: [ERROR] Found option without preceding group in config file /etc/mysql/my.cnf at line 37.
mysql: [ERROR] Fatal error in defaults handling. Program aborted!
```
The solution is to include precede `bind-address` with a group like this.
```ini
[mysqld]
bind-address = 203.0.113.3
```
Reviewed-on: https://gitea.com/gitea/docs/pulls/173
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: b-nagaj <[email protected]>
Co-committed-by: b-nagaj <[email protected]>
I can not understand the old logic:
- download the web page (not the raw data) from GitHub
- replace `AppVer`
- remove the file???
It does nothing.
The correct logic:
- download the raw file from GitHub
- replace `AppVer` and `AppSubUrl`
- move the file to the correct place
As the script is not correct for a long time, added the support for all version since 1.19.
Fix#142
Reviewed-on: https://gitea.com/gitea/docs/pulls/150
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: yp05327 <[email protected]>
Co-committed-by: yp05327 <[email protected]>
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]>
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]>
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]>
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]>
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]>
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]>
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]>
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]>
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]>
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
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]>
Backport #27946 by @lng2020
As title. Some attachments and file sizes can easily be larger than
these limits
Co-authored-by: Nanguan Lin <[email protected]>
Backport #27723 by @mpldr
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
Co-authored-by: Moritz Poldrack <[email protected]>
Backport #27844 by @nodiscc
This documents running `act-runner` as a systemd service under a
dedicated user account.
Co-authored-by: nodiscc <[email protected]>
Backport #27555 by @wolfogre
It should be OK to increase the default queue length since the default
type is "level".
IMO, the old default length (100) is a little too small. See
https://github.com/go-gitea/gitea/issues/27540#issuecomment-1754269491
IIRC, a larger length could lead to more memory usage only when the type
is "channel," but it's an obscure case. Otherwise, it's just a limit
(for "level" or "redis").
Co-authored-by: Jason Song <[email protected]>
Backport #27500 by @silverwind
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
Co-authored-by: silverwind <[email protected]>
Backport #27400 by @fantognazza
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]>
Backport #27291 by @silverwind
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.
The chinese docs are machine-translated, please correct accordingly.
Co-authored-by: silverwind <[email protected]>
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`:
@@ -236,7 +227,7 @@ configure this, set the fields below:
- Restrict what domains can log in if using a public SMTP host or SMTP host
- Restrict what domains can log in if using a public SMTP host or SMTP host
with multiple domains.
with multiple domains.
- Example: `gitea.io,mydomain.com,mydomain2.com`
- Example: `gitea.com,mydomain.com,mydomain2.com`
- Force SMTPS
- Force SMTPS
@@ -348,4 +339,13 @@ If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WE
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 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.
Notice: Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests.
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/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!
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.
:::note
Be sure to set ENABLE_NOTIFY_MAIL=true to allow Gitea to send email notifications. Check the [Config Cheat Sheet](../administration/config-cheat-sheet.md#service-service) for details.
:::
## 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 with `PROTOCOL=smtp+starttls`. 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.
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
## Installing external binaries
@@ -32,18 +23,16 @@ In order to get file rendering through external binaries, their associated packa
If you're using a Docker image, your `Dockerfile` should contain something along this lines:
If you're using a Docker image, your `Dockerfile` should contain something along this lines:
**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:
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{
listen80;
server_namegit.example.com;
location/_/static/assets/{
alias/path/to/gitea/public/;
}
location/{
proxy_passhttp://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{
listen80;
server_namegit.example.com;
location/{
proxy_passhttp://localhost:3000;
}
}
```
```nginx
# static content delivery server
server{
listen80;
server_namecdn.example.com;
location/gitea/{
alias/path/to/gitea/public/;
}
location/{
return404;
}
}
```
## Nginx Proxy Manager
If you are using Nginx Proxy Manager to serve your Gitea instance it differs slighly from the raw Nginx.
It is [adding some directives](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf) for a custom location by default, so you have to skip these from the above mentioned Nginx config. Otherwise Nginx will produce `400 bad request` error due to duplicated directives (`proxy_set_header Host $host` is the particularly problematic one).
So while creating the `/` Custom location, just add the following lines to it's configuration:
```nginx
client_max_body_size512M;
proxy_set_headerConnection$http_connection;
proxy_set_headerUpgrade$http_upgrade;
```
## 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>
...
ProxyPreserveHostOn
ProxyRequestsoff
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
ProxyPreserveHostOn
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`.
:::
## Apache HTTPD 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.
Apache HTTPD can serve static resources directly and proxy only the dynamic requests to Gitea.
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.
```apacheconf
<VirtualHost*:80>
...
<Proxy*>
Order allow,deny
Allow from all
</Proxy>
ProxyPass /_/static/ !
Alias /_/static/ /path/to/gitea/public/
<Directory/path/to/gitea/public/>
Options FollowSymlinks
AllowOverrideNone
Requireall granted
</Directory>
AllowEncodedSlashes NoDecode
# Note: no trailing slash after either /git or port
ProxyPass / http://localhost:3000/ nocanon
ProxyPreserveHostOn
RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
</VirtualHost>
```
## 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/ssh 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.
Additionally Gitea will verify commits signed by ssh keys, which public keys are part of [`TRUSTED_SSH_KEYS`](#general-configuration).
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.
## Installing and generating a SSH key for Gitea
You can run `ssh-keygen -t ed25519 -f gitea-signing-key` to generate the private/public keypair for commit signing without any password. Usually you would store the key next to the gitea configuration, then point `SIGNING_KEY` to the generated public key `/path/to/gitea-signing-key.pub`. Gitea generates all its commits using the server `git` command at present - and therefore the server `ssh-keygen` will be used for
signing (if configured.)
## 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
...
```
---
For SSH commit signing, you need to specify the `SIGNING_FORMAT` to `ssh` instead of the default `openpgp`. `SIGNING_NAME` and `SIGNING_EMAIL` are required for verifing the signatures.
This looks like this:
```ini
...
[repository.signing]
SIGNING_KEY=/path/to/gitea-signing-key.pub
SIGNING_NAME=
SIGNING_EMAIL=
SIGNING_FORMAT=ssh
INITIAL_COMMIT=always
CRUD_ACTIONS=pubkey, twofa, parentsigned
WIKI=never
MERGES=pubkey, twofa, basesigned, commitssigned
...
```
-`/path/to/gitea-signing-key` is expected to be the private key for `/path/to/gitea-signing-key.pub` [see here how to generate a new ssh keypair](#installing-and-generating-a-ssh-key-for-gitea).
-`TRUSTED_SSH_KEYS = ssh-<algorithm> <key>` or `TRUSTED_SSH_KEYS = ssh-<algorithm> <key1>, ssh-<algorithm> <key2>` can be used for rotating the global ssh signing key to continue verifying commits signed by the previous keys.
### `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 gpg 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.
-`/path/to/gitea-signing-key.pub` - Gitea will sign commits with the ssh key without the `.pub` suffix `/path/to/gitea-signing-key`. In this case you should provide a `SIGNING_NAME` and
`SIGNING_EMAIL` to be displayed for this key and set `SIGNING_FORMAT` to `ssh`.
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`.
:::
:::warning
The default option and repository specific signing keys are not supported for ssh keys
:::
### `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:
```sh
/api/v1/repos/:username/:reponame/signing-key.gpg
```
For ssh commit signing the default ssh public key can be obtained via the API at:
Thank you for your interest in contributing to Gitea! This guide will help you understand how to contribute to the project effectively.
## Getting Started
Before you start contributing, please read our [Hacking on Gitea](../development/hacking-on-gitea.md) guide to set up your development environment.
## Contribution Guidelines
We have specific guidelines for different types of contributions:
### Backend Development
If you're working on backend code (Go), please follow our [Guidelines for Backend Development](guidelines-backend.md). This includes:
- Package design and dependencies
- Database operations and migrations
- Testing strategies
- Code organization
### Frontend Development
For frontend contributions (JavaScript, CSS, Vue), refer to our [Guidelines for Frontend Development](guidelines-frontend.md). This covers:
- Framework usage (Vue3, Fomantic-UI)
- Code style and best practices
- Accessibility requirements
- TypeScript usage
### Refactoring
When refactoring existing code, follow our [Guidelines for Refactoring](guidelines-refactoring.md) to ensure:
- Clear refactoring objectives
- Proper review process
- Maintaining backward compatibility
- Incremental improvements
### Localization
To contribute translations or localization improvements, see our [Localization Guide](localization.md) which explains:
- How to contribute translations via Crowdin
- Supported languages
- Translation workflow
## Code of Conduct
Please be respectful and constructive in all interactions with the community. We are committed to providing a welcoming and inclusive environment for all contributors.
Gitea uses Golang as the backend programming language. It uses many third-party packages and also write some itself.
For example, Gitea uses [Chi](https://github.com/go-chi/chi) as basic web framework. [Xorm](https://xorm.io) is an ORM framework that is used to interact with the database.
So it's very important to manage these packages. Please take the below guidelines before you start to write backend code.
## Package Design Guideline
### Packages List
To maintain understandable code and avoid circular dependencies it is important to have a good code structure. The Gitea backend is divided into the following parts:
-`build`: Scripts to help build Gitea.
-`cmd`: All Gitea actual sub commands includes web, doctor, serv, hooks, admin and etc. `web` will start the web service. `serv` and `hooks` will be invoked by Git or OpenSSH. Other sub commands could help to maintain Gitea.
-`tests`: Common test utility functions
-`tests/integration`: Integration tests, to test back-end regressions
-`tests/e2e`: E2e tests, to test front-end and back-end compatibility and visual regressions.
-`models`: Contains the data structures used by xorm to construct database tables. It also contains functions to query and update the database. Dependencies to other Gitea code should be avoided. You can make exceptions in cases such as logging.
-`models/db`: Basic database operations. All other `models/xxx` packages should depend on this package. The `GetEngine` function should only be invoked from `models/`.
-`models/fixtures`: Sample data used in unit tests and integration tests. One `yml` file means one table which will be loaded into database when beginning the tests.
-`models/migrations`: Stores database migrations between versions. PRs that change a database structure **MUST** also have a migration step.
-`modules`: Different modules to handle specific functionality in Gitea. Work in Progress: Some of them should be moved to `services`, in particular those that depend on models because they rely on the database.
-`modules/setting`: Store all system configurations read from ini files and has been referenced by everywhere. But they should be used as function parameters when possible.
-`modules/git`: Package to interactive with `Git` command line or Gogit package.
-`routers`: Handling of server requests. As it uses other Gitea packages to serve the request, other packages (models, modules or services) must not depend on routers.
-`routers/api` Contains routers for `/api/v1` aims to handle RESTful API requests.
-`routers/install` Could only respond when system is in INSTALL mode (INSTALL_LOCK=false).
-`routers/private` will only be invoked by internal sub commands, especially `serv` and `hooks`.
-`routers/web` will handle HTTP requests from web browsers or Git SMART HTTP protocols.
-`services`: Support functions for common routing operations or command executions. Uses `models` and `modules` to handle the requests.
-`templates`: Golang templates for generating the html output.
### Package Dependencies
Since Golang doesn't support import cycles, we have to decide the package dependencies carefully. There are some levels between those packages. Below is the ideal package dependencies direction.
From left to right, left packages could depend on right packages, but right packages MUST not depend on left packages. The sub packages on the same level could depend on according this level's rules.
:::warning
Why do we need database transactions outside of `models`? And how?
Some actions should allow for rollback when database record insertion/update/deletion failed.
So services must be allowed to create a database transaction. Here is some example,
```go
// services/repository/repository.go
funcCreateXXXX()error{
returndb.WithTx(func(ctxcontext.Context)error{
// do something, if err is returned, it will rollback automatically
iferr:=issues.UpdateIssue(ctx,repoID);err!=nil{
// ...
returnerr
}
// ...
returnnil
})
}
```
You should **not** use `db.GetEngine(ctx)` in `services` directly, but just write a function under `models/`.
If the function will be used in the transaction, just let `context.Context` as the function's first parameter.
For the top level package, use a plural as package name, i.e. `services`, `models`, for sub packages, use singular,
i.e. `services/user`, `models/repository`.
### Import Alias
Since there are some packages which use the same package name, it is possible that you find packages like `modules/user`, `models/user`, and `services/user`. When these packages are imported in one Go file, it's difficult to know which package we are using and if it's a variable name or an import name. So, we always recommend to use import aliases. To differ from package variables which are commonly in camelCase, just use **snake_case** for import aliases.
i.e. `import user_service "code.gitea.io/gitea/services/user"`
### Implementing `io.Closer`
If a type implements `io.Closer`, calling `Close` multiple times must not fail or `panic` but return an error or `nil`.
### Important Gotchas
- Never write `x.Update(exemplar)` without an explicit `WHERE` clause:
- This will cause all rows in the table to be updated with the non-zero values of the exemplar - including IDs.
- You should usually write `x.ID(id).Update(exemplar)`.
- If during a migration you are inserting into a table using `x.Insert(exemplar)` where the ID is preset:
- You will need to ``SET IDENTITY_INSERT `table` ON`` for the MSSQL variant (the migration will fail otherwise)
- However, you will also need to update the id sequence for postgres - the migration will silently pass here but later insertions will fail:
``SELECT setval('table_name_id_seq', COALESCE((SELECT MAX(id)+1 FROM `table_name`), 1), false)``
### Future Tasks
Currently, we are creating some refactors to do the following things:
- Correct that codes which doesn't follow the rules.
- There are too many files in `models`, so we are moving some of them into a sub package `models/xxx`.
- Some `modules` sub packages should be moved to `services` because they depend on `models`.
Gitea uses [Fomantic-UI](https://fomantic-ui.com/introduction/getting-started.html) (based on [jQuery](https://api.jquery.com)) and [Vue3](https://vuejs.org/) for its frontend.
The HTML pages are rendered by [Go HTML Template](https://pkg.go.dev/html/template).
The source files can be found in the following directories:
* **CSS styles:** `web_src/css/`
* **JavaScript files:** `web_src/js/`
* **Vue components:** `web_src/js/components/`
* **Go HTML templates:** `templates/`
## General Guidelines
We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html) and [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)
### Gitea specific guidelines
1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories.
2. HTML ids and classes should use kebab-case, it's preferred to contain 2-3 feature related keywords.
3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript.
4. CSS styling for classes provided by frameworks should not be overwritten. Always use new class names with 2-3 feature related keywords to overwrite framework styles. Gitea's helper CSS classes in `helpers.less` could be helpful.
5. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`, but do not expose whole models to the frontend to avoid leaking sensitive data.
6. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue3.
7. Clarify variable types, prefer `elem.disabled = true` instead of `elem.setAttribute('disabled', 'anything')`, prefer `$el.prop('checked', var === 'yes')` instead of `$el.prop('checked', var)`.
8. Use semantic elements, prefer `<button class="ui button">` instead of `<div class="ui button">`.
9. Avoid unnecessary `!important` in CSS, add comments to explain why it's necessary if it can't be avoided.
10. Avoid mixing different events in one event listener, prefer to use individual event listeners for every event.
11. Custom event names are recommended to use `ce-` prefix.
12. Prefer using Tailwind CSS which is available via `tw-` prefix, e.g. `tw-relative`. Gitea's helper CSS classes use `gt-` prefix (`gt-ellipsis`), while Gitea's own private framework-level CSS classes use `g-` prefix (`g-modal-confirm`).
13. Avoid inline scripts & styles as much as possible, it's recommended to put JS code into JS files and use CSS classes. If inline scripts & styles are unavoidable, explain the reason why it can't be avoided.
### Accessibility / ARIA
In history, Gitea heavily uses Fomantic UI which is not an accessibility-friendly framework.
Gitea uses some patches to make Fomantic UI more accessible (see `aria.md` and related JS files),
but there are still many problems which need a lot of work and time to fix.
### Framework Usage
Mixing different frameworks together is discouraged, it makes the code difficult to be maintained.
A JavaScript module should follow one major framework and follow the framework's best practice.
Recommended implementations:
* Vue + Vanilla JS
* Fomantic-UI (jQuery)
* htmx (partial page reloads for otherwise static components)
* Vanilla JS
Discouraged implementations:
* Vue + Fomantic-UI (jQuery)
* jQuery + Vanilla JS
* htmx + any other framework which requires heavy JS code, or unnecessary features like htmx scripting (`hx-on`)
To make UI consistent, Vue components can use Fomantic-UI CSS classes.
We use htmx for simple interactions. You can see an example for simple interactions where htmx should be used in this [PR](https://github.com/go-gitea/gitea/pull/28908). Do not use htmx if you require more advanced reactivity, use another framework (Vue/Vanilla JS).
Although mixing different frameworks is discouraged,
it should also work if the mixing is necessary and the code is well-designed and maintainable.
### Typescript
Gitea is in the process of migrating to type-safe Typescript. Here are some specific guidelines regarding Typescript in the codebase:
#### Use type aliases instead of interfaces
Prefer to use type aliases because they can represent any type and are generally more flexible to use than interfaces.
#### Use separate type imports
We use `verbatimModuleSyntax` so type and non-type imports from the same file must be split into two `import type` statements. This enables the typescript compiler to completely eliminate the type import statements during compilation.
#### Use `@ts-expect-error` instead of `@ts-ignore`
Both annotations should be avoided, but if you have to use them, use `@ts-expect-error` because it will not leave ineffective statements after the issue is fixed.
### `async` Functions
Only mark a function as `async` if and only if there are `await` calls
or `Promise` returns inside the function.
It's not recommended to use `async` event listeners, which may lead to problems.
The reason is that the code after await is executed outside the event dispatch.
A lot of legacy code already existed before this document's written. It's recommended to refactor legacy code to follow the guidelines.
### Vue3 and JSX
Gitea is using Vue3 now. We decided not to introduce JSX to keep the HTML and the JavaScript code separated.
### UI Examples
Gitea uses some self-made UI elements and customizes others to integrate them better into the general UI approach. When running Gitea in development mode (`RUN_MODE=dev`), a page with some standardized UI examples is available under `http(s)://your-gitea-url:port/devtest`.
Loaded 50 of 1651 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.