@ -127,14 +127,14 @@ the *[How to get faster PR reviews](https://github.com/kubernetes/community/blob
it has lots of useful tips for any project you may want to contribute.
it has lots of useful tips for any project you may want to contribute.
Some of the key points:
Some of the key points:
* Make small pull requests. The smaller, the faster to review and the
- Make small pull requests. The smaller, the faster to review and the
more likely it will be merged soon.
more likely it will be merged soon.
* Don't make changes unrelated to your PR. Maybe there are typos on
- Don't make changes unrelated to your PR. Maybe there are typos on
some comments, maybe refactoring would be welcome on a function... but
some comments, maybe refactoring would be welcome on a function... but
if that is not related to your PR, please make *another* PR for that.
if that is not related to your PR, please make *another* PR for that.
* Split big pull requests into multiple small ones. An incremental change
- Split big pull requests into multiple small ones. An incremental change
will be faster to review than a huge PR.
will be faster to review than a huge PR.
* Use the first comment as a summary explainer of your PR and you should keep this up-to-date as the PR evolves.
- Use the first comment as a summary explainer of your PR and you should keep this up-to-date as the PR evolves.
If your PR could cause a breaking change you must add a BREAKING section to this comment e.g.:
If your PR could cause a breaking change you must add a BREAKING section to this comment e.g.:
@ -146,7 +146,8 @@ To explain how this could affect users and how to mitigate these changes.
## Styleguide
## Styleguide
For imports you should use the following format (_without_ the comments)
For imports you should use the following format (*without* the comments)
```go
```go
import (
import (
// stdlib
// stdlib
@ -181,11 +182,15 @@ To maintain understandable code and avoid circular dependencies it is important
## API v1
## API v1
The API is documented by [swagger](http://try.gitea.io/api/swagger) and is based on [GitHub API v3](https://developer.github.com/v3/).
The API is documented by [swagger](http://try.gitea.io/api/swagger) and is based on [GitHub API v3](https://developer.github.com/v3/).
Thus, Gitea´s API should use the same endpoints and fields as GitHub´s API as far as possible, unless there are good reasons to deviate.
Thus, Gitea´s API should use the same endpoints and fields as GitHub´s API as far as possible, unless there are good reasons to deviate.
If Gitea provides functionality that GitHub does not, a new endpoint can be created.
If Gitea provides functionality that GitHub does not, a new endpoint can be created.
If information is provided by Gitea that is not provided by the GitHub API, a new field can be used that doesn't collide with any GitHub fields.
If information is provided by Gitea that is not provided by the GitHub API, a new field can be used that doesn't collide with any GitHub fields.
Updating an existing API should not remove existing fields unless there is a really good reason to do so.
Updating an existing API should not remove existing fields unless there is a really good reason to do so.
The same applies to status responses. If you notice a problem, feel free to leave a comment in the code for future refactoring to APIv2 (which is currently not planned).
The same applies to status responses. If you notice a problem, feel free to leave a comment in the code for future refactoring to APIv2 (which is currently not planned).
All expected results (errors, success, fail messages) should be documented
All expected results (errors, success, fail messages) should be documented
@ -195,6 +200,7 @@ All JSON input types must be defined as a struct in [modules/structs/](modules/s
* **GET** endpoints return requested object and status **OK (200)**
* **DELETE** endpoints return status **No Content (204)**
- **GET** endpoints return requested object and status **OK (200)**
* **POST** endpoints return status **Created (201)**, used to **create** new objects (e.g. a User)
- **DELETE** endpoints return status **No Content (204)**
* **PUT** endpoints return status **No Content (204)**, used to **add/assign** existing Objects (e.g. User) to something (e.g. Org-Team)
- **POST** endpoints return status **Created (201)**, used to **create** new objects (e.g. a User)
* **PATCH** endpoints return changed object and status **OK (200)**, used to **edit/change** an existing object
- **PUT** endpoints return status **No Content (204)**, used to **add/assign** existing Objects (e.g. User) to something (e.g. Org-Team)
- **PATCH** endpoints return changed object and status **OK (200)**, used to **edit/change** an existing object
An endpoint which changes/edits an object expects all fields to be optional (except ones to identify the object, which are required).
An endpoint which changes/edits an object expects all fields to be optional (except ones to identify the object, which are required).
### Endpoints returning lists should
### Endpoints returning lists should
* support pagination (`page` &`limit` options in query)
* set `X-Total-Count` header via **SetTotalCountHeader** ([example](https://github.com/go-gitea/gitea/blob/7aae98cc5d4113f1e9918b7ee7dd09f67c189e3e/routers/api/v1/repo/issue.go#L444))
- support pagination (`page` &`limit` options in query)
- set `X-Total-Count` header via **SetTotalCountHeader** ([example](https://github.com/go-gitea/gitea/blob/7aae98cc5d4113f1e9918b7ee7dd09f67c189e3e/routers/api/v1/repo/issue.go#L444))
## Large Character Comments
## Large Character Comments
@ -368,35 +378,35 @@ and lead the development of Gitea.
To honor the past owners, here's the history of the owners and the time
To honor the past owners, here's the history of the owners and the time
@ -413,20 +423,20 @@ be reviewed by two maintainers and must pass the automatic tests.
## Releasing Gitea
## Releasing Gitea
* Let $vmaj, $vmin and $vpat be Major, Minor and Patch version numbers, $vpat should be rc1, rc2, 0, 1, ...... $vmaj.$vmin will be kept the same as milestones on github or gitea in future.
- Let $vmaj, $vmin and $vpat be Major, Minor and Patch version numbers, $vpat should be rc1, rc2, 0, 1, ...... $vmaj.$vmin will be kept the same as milestones on github or gitea in future.
* Before releasing, confirm all the version's milestone issues or PRs has been resolved. Then discuss the release on Discord channel #maintainers and get agreed with almost all the owners and mergers. Or you can declare the version and if nobody against in about serval hours.
- Before releasing, confirm all the version's milestone issues or PRs has been resolved. Then discuss the release on Discord channel #maintainers and get agreed with almost all the owners and mergers. Or you can declare the version and if nobody against in about serval hours.
* If this is a big version first you have to create PR for changelog on branch `main` with PRs with label `changelog` and after it has been merged do following steps:
- If this is a big version first you have to create PR for changelog on branch `main` with PRs with label `changelog` and after it has been merged do following steps:
* Create `-dev` tag as `git tag -s -F release.notes v$vmaj.$vmin.0-dev` and push the tag as `git push origin v$vmaj.$vmin.0-dev`.
- Create `-dev` tag as `git tag -s -F release.notes v$vmaj.$vmin.0-dev` and push the tag as `git push origin v$vmaj.$vmin.0-dev`.
* When CI has finished building tag then you have to create a new branch named `release/v$vmaj.$vmin`
- When CI has finished building tag then you have to create a new branch named `release/v$vmaj.$vmin`
* If it is bugfix version create PR for changelog on branch `release/v$vmaj.$vmin` and wait till it is reviewed and merged.
- If it is bugfix version create PR for changelog on branch `release/v$vmaj.$vmin` and wait till it is reviewed and merged.
* Add a tag as `git tag -s -F release.notes v$vmaj.$vmin.$`, release.notes file could be a temporary file to only include the changelog this version which you added to `CHANGELOG.md`.
- Add a tag as `git tag -s -F release.notes v$vmaj.$vmin.$`, release.notes file could be a temporary file to only include the changelog this version which you added to `CHANGELOG.md`.
* And then push the tag as `git push origin v$vmaj.$vmin.$`. Drone CI will automatically create a release and upload all the compiled binary. (But currently it doesn't add the release notes automatically. Maybe we should fix that.)
- And then push the tag as `git push origin v$vmaj.$vmin.$`. Drone CI will automatically create a release and upload all the compiled binary. (But currently it doesn't add the release notes automatically. Maybe we should fix that.)
* If needed send a frontport PR for the changelog to branch `main` and update the version in `docs/config.yaml` to refer to the new version.
- If needed send a frontport PR for the changelog to branch `main` and update the version in `docs/config.yaml` to refer to the new version.
* Send PR to [blog repository](https://gitea.com/gitea/blog) announcing the release.
- Send PR to [blog repository](https://gitea.com/gitea/blog) announcing the release.
* Verify all release assets were correctly published through CI on dl.gitea.io and GitHub releases. Once ACKed:
- Verify all release assets were correctly published through CI on dl.gitea.io and GitHub releases. Once ACKed:
* bump the version of https://dl.gitea.io/gitea/version.json
- bump the version of https://dl.gitea.io/gitea/version.json
* merge the blog post PR
- merge the blog post PR
* announce the release in discord `#announcements`
- announce the release in discord `#announcements`
@ -114,14 +114,16 @@ For more information and instructions about how to install Gitea, please look at
If you have questions that are not covered by the documentation, you can get in contact with us on our [Discord server](https://discord.gg/Gitea) or create a post in the [discourse forum](https://discourse.gitea.io/).
If you have questions that are not covered by the documentation, you can get in contact with us on our [Discord server](https://discord.gg/Gitea) or create a post in the [discourse forum](https://discourse.gitea.io/).
We maintain a list of Gitea-related projects at [gitea/awesome-gitea](https://gitea.com/gitea/awesome-gitea).
We maintain a list of Gitea-related projects at [gitea/awesome-gitea](https://gitea.com/gitea/awesome-gitea).
The Hugo-based documentation theme is hosted at [gitea/theme](https://gitea.com/gitea/theme).
The Hugo-based documentation theme is hosted at [gitea/theme](https://gitea.com/gitea/theme).
The official Gitea CLI is developed at [gitea/tea](https://gitea.com/gitea/tea).
The official Gitea CLI is developed at [gitea/tea](https://gitea.com/gitea/tea).
@ -152,6 +152,7 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
Configuration for set the expected MIME type based on file extensions of downloadable files. Configuration presents in key-value pairs and file extensions starts with leading `.`.
Configuration for set the expected MIME type based on file extensions of downloadable files. Configuration presents in key-value pairs and file extensions starts with leading `.`.
The following configuration set `Content-Type: application/vnd.android.package-archive` header when downloading files with `.apk` file extension.
The following configuration set `Content-Type: application/vnd.android.package-archive` header when downloading files with `.apk` file extension.
```ini
```ini
.apk=application/vnd.android.package-archive
.apk=application/vnd.android.package-archive
```
```
@ -535,7 +536,7 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o
## OAuth2 Client (`oauth2_client`)
## OAuth2 Client (`oauth2_client`)
- `REGISTER_EMAIL_CONFIRM`: *[service]***REGISTER\_EMAIL\_CONFIRM**: Set this to enable or disable email confirmation of OAuth2 auto-registration. (Overwrites the REGISTER\_EMAIL\_CONFIRM setting of the `[service]` section)
- `REGISTER_EMAIL_CONFIRM`: _[service]_**REGISTER\_EMAIL\_CONFIRM**: Set this to enable or disable email confirmation of OAuth2 auto-registration. (Overwrites the REGISTER\_EMAIL\_CONFIRM setting of the `[service]` section)
- `OPENID_CONNECT_SCOPES`: **\<empty\>**: List of additional openid connect scopes. (`openid` is implicitly added)
- `OPENID_CONNECT_SCOPES`: **\<empty\>**: List of additional openid connect scopes. (`openid` is implicitly added)
- `ENABLE_AUTO_REGISTRATION`: **false**: Automatically create user accounts for new oauth2 users.
- `ENABLE_AUTO_REGISTRATION`: **false**: Automatically create user accounts for new oauth2 users.
- `USERNAME`: **nickname**: The source of the username for new oauth2 accounts:
- `USERNAME`: **nickname**: The source of the username for new oauth2 accounts:
@ -731,7 +732,6 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type
- image = default image will be used (which is set in `REPOSITORY_AVATAR_FALLBACK_IMAGE`)
- image = default image will be used (which is set in `REPOSITORY_AVATAR_FALLBACK_IMAGE`)
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: Image used as default repository avatar (if `REPOSITORY_AVATAR_FALLBACK` is set to image and none was uploaded)
- `REPOSITORY_AVATAR_FALLBACK_IMAGE`: **/img/repo_default.png**: Image used as default repository avatar (if `REPOSITORY_AVATAR_FALLBACK` is set to image and none was uploaded)
## Project (`project`)
## Project (`project`)
Default templates for project boards:
Default templates for project boards:
@ -766,11 +766,13 @@ Default templates for project boards:
- `ENABLE_XORM_LOG`: **true**: Set whether to perform XORM logging. Please note SQL statement logging can be disabled by setting `LOG_SQL` to false in the `[database]` section.
- `ENABLE_XORM_LOG`: **true**: Set whether to perform XORM logging. Please note SQL statement logging can be disabled by setting `LOG_SQL` to false in the `[database]` section.
### Router Log (`log`)
### Router Log (`log`)
- `DISABLE_ROUTER_LOG`: **false**: Mute printing of the router log.
- `DISABLE_ROUTER_LOG`: **false**: Mute printing of the router log.
- `ROUTER`: **console**: The mode or name of the log the router should log to. (If you set this to `,` it will log to default Gitea logger.)
- `ROUTER`: **console**: The mode or name of the log the router should log to. (If you set this to `,` it will log to default Gitea logger.)
NB: You must have `DISABLE_ROUTER_LOG` set to `false` for this option to take effect. Configure each mode in per mode log subsections `\[log.modename.router\]`.
NB: You must have `DISABLE_ROUTER_LOG` set to `false` for this option to take effect. Configure each mode in per mode log subsections `\[log.modename.router\]`.
### Access Log (`log`)
### Access Log (`log`)
- `ENABLE_ACCESS_LOG`: **false**: Creates an access.log in NCSA common log format, or as per the following template
- `ENABLE_ACCESS_LOG`: **false**: Creates an access.log in NCSA common log format, or as per the following template
- `ACCESS`: **file**: Logging mode for the access logger, use a comma to separate values. Configure each mode in per mode log subsections `\[log.modename.access\]`. By default the file mode will log to `$ROOT_PATH/access.log`. (If you set this to `,` it will log to the default Gitea logger.)
- `ACCESS`: **file**: Logging mode for the access logger, use a comma to separate values. Configure each mode in per mode log subsections `\[log.modename.access\]`. By default the file mode will log to `$ROOT_PATH/access.log`. (If you set this to `,` it will log to the default Gitea logger.)
- `ACCESS_LOG_TEMPLATE`: **`{{.Ctx.RemoteAddr}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}\" \"{{.Ctx.Req.UserAgent}}"`**: Sets the template used to create the access log.
- `ACCESS_LOG_TEMPLATE`: **`{{.Ctx.RemoteAddr}} - {{.Identity}} {{.Start.Format "[02/Jan/2006:15:04:05 -0700]" }} "{{.Ctx.Req.Method}} {{.Ctx.Req.URL.RequestURI}} {{.Ctx.Req.Proto}}" {{.ResponseWriter.Status}} {{.ResponseWriter.Size}} "{{.Ctx.Req.Referer}}\" \"{{.Ctx.Req.UserAgent}}"`**: Sets the template used to create the access log.
@ -887,6 +889,7 @@ Default templates for project boards:
### Extended cron tasks (not enabled by default)
### Extended cron tasks (not enabled by default)
#### Cron - Garbage collect all repositories ('cron.git_gc_repos')
#### Cron - Garbage collect all repositories ('cron.git_gc_repos')
- `ENABLED`: **false**: Enable service.
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
@ -895,36 +898,42 @@ Default templates for project boards:
- `ARGS`: **\<empty\>**: Arguments for command `git gc`, e.g. `--aggressive --auto`. The default value is same with [git] -> GC_ARGS
- `ARGS`: **\<empty\>**: Arguments for command `git gc`, e.g. `--aggressive --auto`. The default value is same with [git] -> GC_ARGS
#### Cron - Update the '.ssh/authorized_keys' file with Gitea SSH keys ('cron.resync_all_sshkeys')
#### Cron - Update the '.ssh/authorized_keys' file with Gitea SSH keys ('cron.resync_all_sshkeys')
- `ENABLED`: **false**: Enable service.
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
#### Cron - Resynchronize pre-receive, update and post-receive hooks of all repositories ('cron.resync_all_hooks')
#### Cron - Resynchronize pre-receive, update and post-receive hooks of all repositories ('cron.resync_all_hooks')
- `ENABLED`: **false**: Enable service.
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
#### Cron - Reinitialize all missing Git repositories for which records exist ('cron.reinit_missing_repos')
#### Cron - Reinitialize all missing Git repositories for which records exist ('cron.reinit_missing_repos')
- `ENABLED`: **false**: Enable service.
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
#### Cron - Delete all repositories missing their Git files ('cron.delete_missing_repos')
#### Cron - Delete all repositories missing their Git files ('cron.delete_missing_repos')
- `ENABLED`: **false**: Enable service.
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
- `SCHEDULE`: **@every 72h**: Cron syntax for scheduling repository archive cleanup, e.g. `@every 1h`.
#### Cron - Delete all old actions from database ('cron.delete_old_actions')
#### Cron - Delete all old actions from database ('cron.delete_old_actions')
- `ENABLED`: **false**: Enable service.
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
- `NOTICE_ON_SUCCESS`: **false**: Set to true to switch on success notices.
@ -932,6 +941,7 @@ Default templates for project boards:
- `OLDER_THAN`: **@every 8760h**: any action older than this expression will be deleted from database, suggest using `8760h` (1 year) because that's the max length of heatmap.
- `OLDER_THAN`: **@every 8760h**: any action older than this expression will be deleted from database, suggest using `8760h` (1 year) because that's the max length of heatmap.
#### Cron - Check for new Gitea versions ('cron.update_checker')
#### Cron - Check for new Gitea versions ('cron.update_checker')
- `ENABLED`: **false**: Enable service.
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
- `ENABLE_SUCCESS_NOTICE`: **true**: Set to false to switch off success notices.
@ -939,6 +949,7 @@ Default templates for project boards:
- `HTTP_ENDPOINT`: **https://dl.gitea.io/gitea/version.json**: the endpoint that Gitea will check for newer versions
- `HTTP_ENDPOINT`: **https://dl.gitea.io/gitea/version.json**: the endpoint that Gitea will check for newer versions
#### Cron - Delete all old system notices from database ('cron.delete_old_system_notices')
#### Cron - Delete all old system notices from database ('cron.delete_old_system_notices')
- `ENABLED`: **false**: Enable service.
- `ENABLED`: **false**: Enable service.
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `RUN_AT_START`: **false**: Run tasks at start up time (if ENABLED).
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
- `NO_SUCCESS_NOTICE`: **false**: Set to true to switch off success notices.
@ -966,6 +977,7 @@ Default templates for project boards:
- `DISABLE_PARTIAL_CLONE`: **false** Disable the usage of using partial clones for git.
- `DISABLE_PARTIAL_CLONE`: **false** Disable the usage of using partial clones for git.
- iframe: Render the content in a separate standalone page and embed it into current page by iframe. The iframe is in sandbox mode with same-origin disabled, and the JS code are safely isolated from parent page.
- iframe: Render the content in a separate standalone page and embed it into current page by iframe. The iframe is in sandbox mode with same-origin disabled, and the JS code are safely isolated from parent page.
Two special environment variables are passed to the render command:
Two special environment variables are passed to the render command:
- `GITEA_PREFIX_SRC`, which contains the current URL prefix in the `src` path tree. To be used as prefix for links.
- `GITEA_PREFIX_SRC`, which contains the current URL prefix in the `src` path tree. To be used as prefix for links.
- `GITEA_PREFIX_RAW`, which contains the current URL prefix in the `raw` path tree. To be used as prefix for image paths.
- `GITEA_PREFIX_RAW`, which contains the current URL prefix in the `raw` path tree. To be used as prefix for image paths.
Display Office DOCX files with [`pandoc`](https://pandoc.org/):
Display Office DOCX files with [`pandoc`](https://pandoc.org/):
```ini
```ini
[markup.docx]
[markup.docx]
ENABLED = true
ENABLED = true
@ -138,6 +139,7 @@ ALLOW_DATA_URI_IMAGES = true
```
```
The template file has the following content:
The template file has the following content:
```
```
$body$
$body$
```
```
@ -145,6 +147,7 @@ $body$
### Example: Jupyter Notebook
### Example: Jupyter Notebook
Display Jupyter Notebook files with [`nbconvert`](https://github.com/jupyter/nbconvert):
Display Jupyter Notebook files with [`nbconvert`](https://github.com/jupyter/nbconvert):
```ini
```ini
[markup.jupyter]
[markup.jupyter]
ENABLED = true
ENABLED = true
@ -156,9 +159,11 @@ ALLOW_DATA_URI_IMAGES = true
```
```
## Customizing CSS
## Customizing CSS
The external renderer is specified in the .ini in the format `[markup.XXXXX]` and the HTML supplied by your external renderer will be wrapped in a `<div>` with classes `markup` and `XXXXX`. The `markup` class provides out of the box styling (as does `markdown` if `XXXXX` is `markdown`). Otherwise you can use these classes to specifically target the contents of your rendered HTML.
The external renderer is specified in the .ini in the format `[markup.XXXXX]` and the HTML supplied by your external renderer will be wrapped in a `<div>` with classes `markup` and `XXXXX`. The `markup` class provides out of the box styling (as does `markdown` if `XXXXX` is `markdown`). Otherwise you can use these classes to specifically target the contents of your rendered HTML.
And so you could write some CSS:
And so you could write some CSS:
```css
```css
.markup.XXXXX html {
.markup.XXXXX html {
font-size: 100%;
font-size: 100%;
@ -184,6 +189,7 @@ And so you could write some CSS:
```
```
Add your stylesheet to your custom directory e.g `custom/public/css/my-style-XXXXX.css` and import it using a custom header file `custom/templates/custom/header.tmpl`:
Add your stylesheet to your custom directory e.g `custom/public/css/my-style-XXXXX.css` and import it using a custom header file `custom/templates/custom/header.tmpl`:
@ -37,7 +37,7 @@ For an existing remote repository, you can set up pull mirroring as follows:
3. Enter a repository URL.
3. Enter a repository URL.
4. If the repository needs authentication fill in your authentication information.
4. If the repository needs authentication fill in your authentication information.
5. Check the box **This repository will be a mirror**.
5. Check the box **This repository will be a mirror**.
5. Select **Migrate repository** to save the configuration.
6. Select **Migrate repository** to save the configuration.
The repository now gets mirrored periodically from the remote repository. You can force a sync by selecting **Synchronize Now** in the repository settings.
The repository now gets mirrored periodically from the remote repository. You can force a sync by selecting **Synchronize Now** in the repository settings.
The HTML pages are rendered by [Go HTML Template](https://pkg.go.dev/html/template).
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:
The source files can be found in the following directories:
* **Less styles:**`web_src/less/`
* **Less styles:**`web_src/less/`
* **JavaScript files:**`web_src/js/`
* **JavaScript files:**`web_src/js/`
* **Vue components:**`web_src/js/components/`
* **Vue components:**`web_src/js/components/`
@ -45,18 +46,19 @@ We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/h
6. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`
6. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`
7. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue2 (or Vue3 in future).
7. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue2 (or Vue3 in future).
### Framework Usage
### Framework Usage
Mixing different frameworks together is discouraged, it makes the code difficult to be maintained.
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.
A JavaScript module should follow one major framework and follow the framework's best practice.
Recommended implementations:
Recommended implementations:
* Vue + Vanilla JS
* Vue + Vanilla JS
* Fomantic-UI (jQuery)
* Fomantic-UI (jQuery)
* Vanilla JS
* Vanilla JS
Discouraged implementations:
Discouraged implementations:
* Vue + Fomantic-UI (jQuery)
* Vue + Fomantic-UI (jQuery)
* jQuery + Vanilla JS
* jQuery + Vanilla JS
@ -91,7 +93,6 @@ However, there are still some special cases, so the current guideline is:
* `node.dataset` should not be used, use `node.getAttribute` instead.
* `node.dataset` should not be used, use `node.getAttribute` instead.
* never bind any user data to a DOM node, use a suitable design pattern to describe the relation between node and data.
* never bind any user data to a DOM node, use a suitable design pattern to describe the relation between node and data.
### Legacy Code
### Legacy Code
A lot of legacy code already existed before this document's written. It's recommended to refactor legacy code to follow the guidelines.
A lot of legacy code already existed before this document's written. It's recommended to refactor legacy code to follow the guidelines.
@ -34,6 +34,7 @@ Gitea supports acting as an OAuth2 provider to allow third party applications to
## Supported OAuth2 Grants
## Supported OAuth2 Grants
At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the following extensions:
At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the following extensions:
- [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636)
- [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636)
@ -27,5 +27,7 @@ For changes to a **non-English** translation, refer to the Crowdin project above
Any language listed in the above Crowdin project will be supported as long as 25% or more has been translated.
Any language listed in the above Crowdin project will be supported as long as 25% or more has been translated.
After a translation has been accepted, it will be reflected in the main repository after the next Crowdin sync, which is generally after any PR is merged.
After a translation has been accepted, it will be reflected in the main repository after the next Crowdin sync, which is generally after any PR is merged.
At the time of writing, this means that a changed translation may not appear until the following Gitea release.
At the time of writing, this means that a changed translation may not appear until the following Gitea release.
If you use a bleeding edge build, it should appear as soon as you update after the change is synced.
If you use a bleeding edge build, it should appear as soon as you update after the change is synced.
This page contains some common questions and answers.
This page contains some common questions and answers.
For more help resources, check all [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}).
For more help resources, check all [Support Options]({{< relref "doc/help/seek-help.en-us.md" >}}).
**Table of Contents**
**Table of Contents**
@ -25,13 +26,17 @@ For more help resources, check all [Support Options]({{< relref "doc/help/seek-h
## Difference between 1.x and 1.x.x downloads
## Difference between 1.x and 1.x.x downloads
Version 1.7.x will be used for this example.
Version 1.7.x will be used for this example.
**NOTE:** this example applies to Docker images as well!
**NOTE:** this example applies to Docker images as well!
On our [downloads page](https://dl.gitea.io/gitea/) you will see a 1.7 directory, as well as directories for 1.7.0, 1.7.1, 1.7.2, 1.7.3, 1.7.4, 1.7.5, and 1.7.6.
On our [downloads page](https://dl.gitea.io/gitea/) you will see a 1.7 directory, as well as directories for 1.7.0, 1.7.1, 1.7.2, 1.7.3, 1.7.4, 1.7.5, and 1.7.6.
The 1.7 and 1.7.0 directories are **not** the same. The 1.7 directory is built on each merged commit to the [`release/v1.7`](https://github.com/go-gitea/gitea/tree/release/v1.7) branch.
The 1.7 and 1.7.0 directories are **not** the same. The 1.7 directory is built on each merged commit to the [`release/v1.7`](https://github.com/go-gitea/gitea/tree/release/v1.7) branch.
The 1.7.0 directory, however, is a build that was created when the [`v1.7.0`](https://github.com/go-gitea/gitea/releases/tag/v1.7.0) tag was created.
The 1.7.0 directory, however, is a build that was created when the [`v1.7.0`](https://github.com/go-gitea/gitea/releases/tag/v1.7.0) tag was created.
This means that 1.x downloads will change as commits are merged to their respective branch (think of it as a separate "main" branch for each release).
This means that 1.x downloads will change as commits are merged to their respective branch (think of it as a separate "main" branch for each release).
On the other hand, 1.x.x downloads should never change.
On the other hand, 1.x.x downloads should never change.
## How to migrate from Gogs/GitHub/etc. to Gitea
## How to migrate from Gogs/GitHub/etc. to Gitea
@ -42,10 +47,13 @@ To migrate from Gogs to Gitea:
- [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
- [Gogs version 0.11.46.0418](https://github.com/go-gitea/gitea/issues/4286)
To migrate from GitHub to Gitea, you can use Gitea's built-in migration form.
To migrate from GitHub to Gitea, you can use Gitea's built-in migration form.
In order to migrate items such as issues, pull requests, etc. you will need to input at least your username.
In order to migrate items such as issues, pull requests, etc. you will need to input at least your username.
To migrate from GitLab to Gitea, you can use this non-affiliated tool:
To migrate from GitLab to Gitea, you can use this non-affiliated tool:
https://github.com/loganinak/MigrateGitlabToGogs
https://github.com/loganinak/MigrateGitlabToGogs
## Where does Gitea store what file
## Where does Gitea store what file
@ -83,9 +91,9 @@ There are a few places that could make this show incorrectly.
If certain clone options aren't showing up (HTTP/S or SSH), the following options can be checked in your `app.ini`
If certain clone options aren't showing up (HTTP/S or SSH), the following options can be checked in your `app.ini`
`DISABLE_HTTP_GIT`: if set to true, there will be no HTTP/HTTPS link
- `DISABLE_HTTP_GIT`: if set to true, there will be no HTTP/HTTPS link
`DISABLE_SSH`: if set to true, there will be no SSH link
- `DISABLE_SSH`: if set to true, there will be no SSH link
`SSH_EXPOSE_ANONYMOUS`: if set to false, SSH links will be hidden for anonymous users
- `SSH_EXPOSE_ANONYMOUS`: if set to false, SSH links will be hidden for anonymous users
## File upload fails with: 413 Request Entity Too Large
## File upload fails with: 413 Request Entity Too Large
@ -96,18 +104,20 @@ See the [reverse proxy guide]({{< relref "doc/usage/reverse-proxies.en-us.md" >}
## Custom Templates not loading or working incorrectly
## Custom Templates not loading or working incorrectly
Gitea's custom templates must be added to the correct location or Gitea will not find and use them.
Gitea's custom templates must be added to the correct location or Gitea will not find and use them.
The correct path for the template(s) will be relative to the `CustomPath`
The correct path for the template(s) will be relative to the `CustomPath`
1. To find `CustomPath`, look for Custom File Root Path in Site Administration -> Configuration
1. To find `CustomPath`, look for Custom File Root Path in Site Administration -> Configuration
- If that doesn't exist, you can try `echo $GITEA_CUSTOM`
If that doesn't exist, you can try `echo $GITEA_CUSTOM`
2. If you are still unable to find a path, the default can be [calculated above](#where-does-gitea-store-x-file)
2. If you are still unable to find a path, the default can be [calculated above](#where-does-gitea-store-what-file)
3. Once you have figured out the correct custom path, you can refer to the [customizing Gitea]({{< relref "doc/advanced/customizing-gitea.en-us.md" >}}) page to add your template to the correct location.
3. Once you have figured out the correct custom path, you can refer to the [customizing Gitea]({{< relref "doc/advanced/customizing-gitea.en-us.md" >}}) page to add your template to the correct location.
## Active user vs login prohibited user
## Active user vs login prohibited user
In Gitea, an "active" user refers to a user that has activated their account via email.
In Gitea, an "active" user refers to a user that has activated their account via email.
A "login prohibited" user is a user that is not allowed to log in to Gitea anymore
A "login prohibited" user is a user that is not allowed to log in to Gitea anymore
## Setting up logging
## Setting up logging
@ -117,7 +127,9 @@ A "login prohibited" user is a user that is not allowed to log in to Gitea anymo
## What is Swagger?
## What is Swagger?
[Swagger](https://swagger.io/) is what Gitea uses for its API.
[Swagger](https://swagger.io/) is what Gitea uses for its API.
All Gitea instances have the built-in API, though it can be disabled by setting `ENABLE_SWAGGER` to `false` in the `api` section of your `app.ini`
All Gitea instances have the built-in API, though it can be disabled by setting `ENABLE_SWAGGER` to `false` in the `api` section of your `app.ini`
For more information, refer to Gitea's [API docs]({{< relref "doc/developers/api-usage.en-us.md" >}})
For more information, refer to Gitea's [API docs]({{< relref "doc/developers/api-usage.en-us.md" >}})
@ -140,6 +152,7 @@ You can configure `EMAIL_DOMAIN_WHITELIST` or `EMAIL_DOMAIN_BLOCKLIST` in your a
### Only allow/block certain OpenID providers
### Only allow/block certain OpenID providers
You can configure `WHITELISTED_URIS` or `BLACKLISTED_URIS` under `[openid]` in your `app.ini`
You can configure `WHITELISTED_URIS` or `BLACKLISTED_URIS` under `[openid]` in your `app.ini`
**NOTE:** whitelisted takes precedence, so if it is non-blank then blacklisted is ignored
**NOTE:** whitelisted takes precedence, so if it is non-blank then blacklisted is ignored
### Issue only users
### Issue only users
@ -164,37 +177,47 @@ Gitea supports three official themes right now, `gitea` (light), `arc-green` (da
To add your own theme, currently the only way is to provide a complete theme (not just color overrides)
To add your own theme, currently the only way is to provide a complete theme (not just color overrides)
As an example, let's say our theme is `arc-blue` (this is a real theme, and can be found [in this issue](https://github.com/go-gitea/gitea/issues/6011))
As an example, let's say our theme is `arc-blue` (this is a real theme, and can be found [in this issue](https://github.com/go-gitea/gitea/issues/6011))
Name the `.css` file `theme-arc-blue.css` and add it to your custom folder in `custom/public/css`
Name the `.css` file `theme-arc-blue.css` and add it to your custom folder in `custom/public/css`
Allow users to use it by adding `arc-blue` to the list of `THEMES` in your `app.ini`
Allow users to use it by adding `arc-blue` to the list of `THEMES` in your `app.ini`
## SSHD vs built-in SSH
## SSHD vs built-in SSH
SSHD is the built-in SSH server on most Unix systems.
SSHD is the built-in SSH server on most Unix systems.
Gitea also provides its own SSH server, for usage when SSHD is not available.
Gitea also provides its own SSH server, for usage when SSHD is not available.
## Gitea is running slow
## Gitea is running slow
The most common culprit for this is loading federated avatars.
The most common culprit for this is loading federated avatars.
This can be turned off by setting `ENABLE_FEDERATED_AVATAR` to `false` in your `app.ini`
This can be turned off by setting `ENABLE_FEDERATED_AVATAR` to `false` in your `app.ini`
Another option that may need to be changed is setting `DISABLE_GRAVATAR` to `true` in your `app.ini`
Another option that may need to be changed is setting `DISABLE_GRAVATAR` to `true` in your `app.ini`
## Can't create repositories/files
## Can't create repositories/files
Make sure that Gitea has sufficient permissions to write to its home directory and data directory.
Make sure that Gitea has sufficient permissions to write to its home directory and data directory.
See [AppDataPath and RepoRootPath](#where-does-gitea-store-x-file)
See [AppDataPath and RepoRootPath](#where-does-gitea-store-what-file)
**Note for Arch users:** At the time of writing this, there is an issue with the Arch package's systemd file including this line:
**Note for Arch users:** At the time of writing this, there is an issue with the Arch package's systemd file including this line:
`ReadWritePaths=/etc/gitea/app.ini`
`ReadWritePaths=/etc/gitea/app.ini`
Which makes all other paths non-writeable to Gitea.
Which makes all other paths non-writeable to Gitea.
## Translation is incorrect/how to add more translations
## Translation is incorrect/how to add more translations
Our translations are currently crowd-sourced on our [Crowdin project](https://crowdin.com/project/gitea)
Our translations are currently crowd-sourced on our [Crowdin project](https://crowdin.com/project/gitea)
Whether you want to change a translation or add a new one, it will need to be there as all translations are overwritten in our CI via the Crowdin integration.
Whether you want to change a translation or add a new one, it will need to be there as all translations are overwritten in our CI via the Crowdin integration.
## Hooks aren't running
## Hooks aren't running
If Gitea is not running hooks, a common cause is incorrect setup of SSH keys.
If Gitea is not running hooks, a common cause is incorrect setup of SSH keys.
See [SSH Issues](#ssh-issues) for more information.
See [SSH Issues](#ssh-issues) for more information.
You can also try logging into the administration panel and running the `Resynchronize pre-receive, update and post-receive hooks of all repositories.` option.
You can also try logging into the administration panel and running the `Resynchronize pre-receive, update and post-receive hooks of all repositories.` option.
@ -204,6 +227,7 @@ You can also try logging into the administration panel and running the `Resynchr
If you cannot reach repositories over `ssh`, but `https` works fine, consider looking into the following.
If you cannot reach repositories over `ssh`, but `https` works fine, consider looking into the following.
First, make sure you can access Gitea via SSH.
First, make sure you can access Gitea via SSH.
`ssh git@myremote.example`
`ssh git@myremote.example`
If the connection is successful, you should receive an error message like the following:
If the connection is successful, you should receive an error message like the following:
@ -237,6 +261,7 @@ following things:
- Make sure the repository exists and is correctly named.
- Make sure the repository exists and is correctly named.
- Check the permissions of the `.ssh` directory in the system user's home directory.
- Check the permissions of the `.ssh` directory in the system user's home directory.
- Verify that the correct public keys are added to `.ssh/authorized_keys`.
- Verify that the correct public keys are added to `.ssh/authorized_keys`.
Try to run `Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)` on the
Try to run `Rewrite '.ssh/authorized_keys' file (for Gitea SSH keys)` on the
Gitea admin panel.
Gitea admin panel.
- Read Gitea logs.
- Read Gitea logs.
@ -290,6 +315,7 @@ error: failed to push some refs to '<GIT_REPO_URL>'
```
```
Check the value of `LFS_HTTP_AUTH_EXPIRY` in your `app.ini` file.
Check the value of `LFS_HTTP_AUTH_EXPIRY` in your `app.ini` file.
By default, your LFS token will expire after 20 minutes. If you have a slow connection or a large file (or both), it may not finish uploading within the time limit.
By default, your LFS token will expire after 20 minutes. If you have a slow connection or a large file (or both), it may not finish uploading within the time limit.
You may want to set this value to `60m` or `120m`.
You may want to set this value to `60m` or `120m`.
@ -307,16 +333,20 @@ There is no setting for password resets. It is enabled when a [mail service]({{<
- As an **admin**, you can change any user's password (and optionally force them to change it on next login)...
- As an **admin**, you can change any user's password (and optionally force them to change it on next login)...
- By navigating to your `Site Administration -> User Accounts` page and editing a user.
- By navigating to your `Site Administration -> User Accounts` page and editing a user.
- By using the [admin CLI commands]({{< relref "doc/usage/command-line.en-us.md#admin" >}}).
- By using the [admin CLI commands]({{< relref "doc/usage/command-line.en-us.md#admin" >}}).
Keep in mind most commands will also need a [global flag]({{< relref "doc/usage/command-line.en-us.md#global-options" >}}) to point the CLI at the correct configuration.
Keep in mind most commands will also need a [global flag]({{< relref "doc/usage/command-line.en-us.md#global-options" >}}) to point the CLI at the correct configuration.
- As a **user** you can change it...
- As a **user** you can change it...
- In your account `Settings -> Account` page (this method **requires** you to know your current password).
- In your account `Settings -> Account` page (this method **requires** you to know your current password).
- By using the `Forgot Password` link.
- By using the `Forgot Password` link.
If the `Forgot Password/Account Recovery` page is disabled, please contact your administrator to configure a [mail service]({{< relref "doc/usage/email-setup.en-us.md" >}}).
If the `Forgot Password/Account Recovery` page is disabled, please contact your administrator to configure a [mail service]({{< relref "doc/usage/email-setup.en-us.md" >}}).
## Why is my markdown broken
## Why is my markdown broken
In Gitea version `1.11` we moved to [goldmark](https://github.com/yuin/goldmark) for markdown rendering, which is [CommonMark](https://commonmark.org/) compliant.
In Gitea version `1.11` we moved to [goldmark](https://github.com/yuin/goldmark) for markdown rendering, which is [CommonMark](https://commonmark.org/) compliant.
If you have markdown that worked as you expected prior to version `1.11` and after upgrading it's not working anymore, please look through the CommonMark spec to see whether the problem is due to a bug or non-compliant syntax.
If you have markdown that worked as you expected prior to version `1.11` and after upgrading it's not working anymore, please look through the CommonMark spec to see whether the problem is due to a bug or non-compliant syntax.
If it is the latter, _usually_ there is a compliant alternative listed in the spec.
If it is the latter, _usually_ there is a compliant alternative listed in the spec.
## Upgrade errors with MySQL
## Upgrade errors with MySQL
@ -333,7 +363,9 @@ is too small. Gitea requires that the `ROWFORMAT` for its tables is `DYNAMIC`.
If you are receiving an error line containing `Error 1071: Specified key was too long; max key length is 1000 bytes...`
If you are receiving an error line containing `Error 1071: Specified key was too long; max key length is 1000 bytes...`
then you are attempting to run Gitea on tables which use the ISAM engine. While this may have worked by chance in previous versions of Gitea, it has never been officially supported and
then you are attempting to run Gitea on tables which use the ISAM engine. While this may have worked by chance in previous versions of Gitea, it has never been officially supported and
you must use InnoDB. You should run `ALTER TABLE table_name ENGINE=InnoDB;` for each table in the database.
you must use InnoDB. You should run `ALTER TABLE table_name ENGINE=InnoDB;` for each table in the database.
If you are using MySQL 5, another possible fix is
If you are using MySQL 5, another possible fix is
```mysql
```mysql
SET GLOBAL innodb_file_format=Barracuda;
SET GLOBAL innodb_file_format=Barracuda;
SET GLOBAL innodb_file_per_table=1;
SET GLOBAL innodb_file_per_table=1;
@ -404,8 +436,8 @@ gitea doctor recreate-table
It is highly recommended to back-up your database before running these commands.
It is highly recommended to back-up your database before running these commands.
## Why are tabs/indents wrong when viewing files
## Why are tabs/indents wrong when viewing files
If you are using Cloudflare, turn off the auto-minify option in the dashboard.
If you are using Cloudflare, turn off the auto-minify option in the dashboard.
`Speed` -> `Optimization` -> Uncheck `HTML` within the `Auto-Minify` settings.
`Speed` -> `Optimization` -> Uncheck `HTML` within the `Auto-Minify` settings.
1. Your `app.ini` (with any sensitive data scrubbed as necessary).
1. Your `app.ini` (with any sensitive data scrubbed as necessary).
2. The Gitea logs, and any other appropriate log files for the situation.
2. The Gitea logs, and any other appropriate log files for the situation.
* The logs are likely to be outputted to console. If you need to collect logs from files,
- The logs are likely to be outputted to console. If you need to collect logs from files,
you could copy the following config into your `app.ini` (remove all other `[log]` sections),
you could copy the following config into your `app.ini` (remove all other `[log]` sections),
then you can find the `*.log` files in Gitea's log directory (default: `%(GITEA_WORK_DIR)/log`).
then you can find the `*.log` files in Gitea's log directory (default: `%(GITEA_WORK_DIR)/log`).
```ini
```ini
; To show all SQL logs, you can also set LOG_SQL=true in the [database] section
; To show all SQL logs, you can also set LOG_SQL=true in the [database] section
[log]
[log]
@ -39,15 +40,18 @@ menu:
[log.file.xorm]
[log.file.xorm]
FILE_NAME=xorm.log
FILE_NAME=xorm.log
```
```
3. Any error messages you are seeing.
3. Any error messages you are seeing.
4. When possible, try to replicate the issue on [try.gitea.io](https://try.gitea.io) and include steps so that others can reproduce the issue.
4. When possible, try to replicate the issue on [try.gitea.io](https://try.gitea.io) and include steps so that others can reproduce the issue.
* This will greatly improve the chance that the root of the issue can be quickly discovered and resolved.
- This will greatly improve the chance that the root of the issue can be quickly discovered and resolved.
5. If you meet slow/hanging/deadlock problems, please report the stack trace when the problem occurs:
5. If you meet slow/hanging/deadlock problems, please report the stack trace when the problem occurs:
1. Enable pprof in `app.ini` and restart Gitea
1. Enable pprof in `app.ini` and restart Gitea
```ini
```ini
[server]
[server]
ENABLE_PPROF = true
ENABLE_PPROF = true
```
```
2. Trigger the bug, when Gitea gets stuck, use curl or browser to visit: `http://127.0.0.1:6060/debug/pprof/goroutine?debug=1` (IP must be `127.0.0.1` and port must be `6060`).
2. Trigger the bug, when Gitea gets stuck, use curl or browser to visit: `http://127.0.0.1:6060/debug/pprof/goroutine?debug=1` (IP must be `127.0.0.1` and port must be `6060`).
3. If you are using Docker, please use `docker exec -it <container-name> curl "http://127.0.0.1:6060/debug/pprof/goroutine?debug=1"`.
3. If you are using Docker, please use `docker exec -it <container-name> curl "http://127.0.0.1:6060/debug/pprof/goroutine?debug=1"`.
4. Report the output (the stack trace doesn't contain sensitive data)
4. Report the output (the stack trace doesn't contain sensitive data)
Gitea signs all binaries with a [GPG key](https://keys.openpgp.org/search?q=teabot%40gitea.io) to prevent against unwanted modification of binaries.
Gitea signs all binaries with a [GPG key](https://keys.openpgp.org/search?q=teabot%40gitea.io) to prevent against unwanted modification of binaries.
To validate the binary, download the signature file which ends in `.asc` for the binary you downloaded and use the GPG command line tool.
To validate the binary, download the signature file which ends in `.asc` for the binary you downloaded and use the GPG command line tool.
@ -89,10 +90,10 @@ chmod 640 /etc/gitea/app.ini
If you don't want the web installer to be able to write to the config file, it is possible to make the config file read-only for the Gitea user (owner/group `root:git`, mode `0640`) however you will need to edit your config file manually to:
If you don't want the web installer to be able to write to the config file, it is possible to make the config file read-only for the Gitea user (owner/group `root:git`, mode `0640`) however you will need to edit your config file manually to:
* Set `INSTALL_LOCK= true`,
* Set `INSTALL_LOCK= true`,
* Ensure all database configuration details are set correctly
* Ensure all database configuration details are set correctly
* Ensure that the `SECRET_KEY` and `INTERNAL_TOKEN` values are set. (You may want to use the `gitea generate secret` to generate these secret keys.)
* Ensure that the `SECRET_KEY` and `INTERNAL_TOKEN` values are set. (You may want to use the `gitea generate secret` to generate these secret keys.)
* Ensure that any other secret keys you need are set.
* Ensure that any other secret keys you need are set.
See the [command line documentation]({{< relref "doc/usage/command-line.en-us.md" >}}) for information on using `gitea generate secret`.
See the [command line documentation]({{< relref "doc/usage/command-line.en-us.md" >}}) for information on using `gitea generate secret`.
@ -30,7 +30,6 @@ cd $GOPATH/src/code.gitea.io/gitea
Maintenant, il est temps de décider quelle version de Gitea vous souhaitez compiler et installer. Actuellement, ils existent plusieurs options possibles. Si vous voulez compiler notre branche `master`, vous pouvez directement passer à la [section compilation](#compilation), cette branche représente la dernière version en cours de développement et n'a pas vocation à être utiliser en production.
Maintenant, il est temps de décider quelle version de Gitea vous souhaitez compiler et installer. Actuellement, ils existent plusieurs options possibles. Si vous voulez compiler notre branche `master`, vous pouvez directement passer à la [section compilation](#compilation), cette branche représente la dernière version en cours de développement et n'a pas vocation à être utiliser en production.
Si vous souhaitez compiler la dernière version stable, utilisez les étiquettes ou les différentes branches disponibles. Vous pouvez voir les branches disponibles et comment utiliser cette branche avec ces commandes:
Si vous souhaitez compiler la dernière version stable, utilisez les étiquettes ou les différentes branches disponibles. Vous pouvez voir les branches disponibles et comment utiliser cette branche avec ces commandes:
@ -60,9 +60,10 @@ To send a test email to validate the settings, go to Gitea > Site Administration
For the full list of options check the [Config Cheat Sheet]({{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}})
For the full list of options check the [Config Cheat Sheet]({{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}})
Please note: authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through:
Please note: authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through:
- STARTTLS (also known as Opportunistic TLS) via port 587. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
- SMTPS connection (SMTP over TLS) via the default port 465. Connection to the server use TLS from the beginning.
- STARTTLS (also known as Opportunistic TLS) via port 587. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it.
- Forced SMTPS connection with `IS_TLS_ENABLED=true`. (These are both known as Implicit TLS.)
- SMTPS connection (SMTP over TLS) via the default port 465. Connection to the server use TLS from the beginning.
- Forced SMTPS connection with `IS_TLS_ENABLED=true`. (These are both known as Implicit TLS.)
This is due to protections imposed by the Go internal libraries against STRIPTLS attacks.
This is due to protections imposed by the Go internal libraries against STRIPTLS attacks.
Note that Implicit TLS is recommended by [RFC8314](https://tools.ietf.org/html/rfc8314#section-3) since 2018.
Note that Implicit TLS is recommended by [RFC8314](https://tools.ietf.org/html/rfc8314#section-3) since 2018.
@ -29,31 +29,37 @@ on a bad authentication from the web or CLI using SSH or HTTP respectively:
```log
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:143:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
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.)
(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
```log
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:155:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
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.)
(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
```log
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:198:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
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.)
(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
```log
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:213:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
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.)
(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
```log
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:227:publicKeyHandler() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
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.)
(DEPRECATED: This may be a false positive as the user may still go on to correctly authenticate.)
```log
```log
2020/10/15 16:05:09 modules/ssh/ssh.go:249:sshConnectionFailed() [W] Failed authentication attempt from xxx.xxx.xxx.xxx
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.)
(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.)
@ -60,6 +60,7 @@ If you are using Docker, make sure that this port is configured in your `docker-
[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)).
[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:
Minimum setup using the default Let's Encrypt:
```ini
```ini
[server]
[server]
PROTOCOL=https
PROTOCOL=https
@ -72,6 +73,7 @@ ACME_EMAIL=email@example.com
```
```
Minimumg setup using a [smallstep CA](https://github.com/smallstep/certificates), refer to [their tutorial](https://smallstep.com/docs/tutorials/acme-challenge) for more information.
Minimumg setup using a [smallstep CA](https://github.com/smallstep/certificates), refer to [their tutorial](https://smallstep.com/docs/tutorials/acme-challenge) for more information.
@ -138,7 +138,6 @@ In your nginx config file containing your Gitea proxy directive, find the `locat
`client_max_body_size 16M;` to set this limit to 16 megabytes or any other number of choice.
`client_max_body_size 16M;` to set this limit to 16 megabytes or any other number of choice.
If you use Git LFS, this will also limit the size of the largest file you will be able to push.
If you use Git LFS, this will also limit the size of the largest file you will be able to push.
## Apache HTTPD
## 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):
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):
@ -307,6 +306,7 @@ If you wish to run Gitea with IIS. You will need to setup IIS with URL Rewrite a
If you want HAProxy to serve your Gitea instance, you can add the following to your HAProxy configuration
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
add an acl in the frontend section to redirect calls to gitea.example.com to the correct backend
```
```
frontend http-in
frontend http-in
...
...
@ -316,6 +316,7 @@ frontend http-in
```
```
add the previously defined backend section
add the previously defined backend section
```
```
backend gitea
backend gitea
server localhost:3000 check
server localhost:3000 check
@ -338,6 +339,7 @@ frontend http-in
With that configuration http://example.com/gitea/ will redirect to your Gitea instance.
With that configuration http://example.com/gitea/ will redirect to your Gitea instance.
Gitea `1.11.0` and above includes template repositories, and one feature implemented with them is auto-expansion of specific variables within your template files.
Gitea `1.11.0` and above includes template repositories, and one feature implemented with them is auto-expansion of specific variables within your template files.
To tell Gitea which files to expand, you must include a `template` file inside the `.gitea` directory of the template repository.
To tell Gitea which files to expand, you must include a `template` file inside the `.gitea` directory of the template repository.
Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax. It closely resembles a traditional `.gitignore`, however there may be slight differences.
Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax. It closely resembles a traditional `.gitignore`, however there may be slight differences.
## Example `.gitea/template` file
## Example `.gitea/template` file
@ -46,6 +48,7 @@ a/b/c/d.json
## Variable Expansion
## Variable Expansion
In any file matched by the above globs, certain variables will be expanded.
In any file matched by the above globs, certain variables will be expanded.
All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, use a double `$$`, such as `$$VAR` or `$${VAR}`
All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, use a double `$$`, such as `$$VAR` or `$${VAR}`
| Variable | Expands To | Transformable |
| Variable | Expands To | Transformable |
@ -66,6 +69,7 @@ All variables must be of the form `$VAR` or `${VAR}`. To escape an expansion, us
## Transformers :robot:
## Transformers :robot:
Gitea `1.12.0` adds a few transformers to some of the applicable variables above.
Gitea `1.12.0` adds a few transformers to some of the applicable variables above.
For example, to get `REPO_NAME` in `PASCAL`-case, your template would use `${REPO_NAME_PASCAL}`
For example, to get `REPO_NAME` in `PASCAL`-case, your template would use `${REPO_NAME_PASCAL}`
Feeding `go-sdk` to the available transformers yields...
Feeding `go-sdk` to the available transformers yields...
Gitea ist ein einfacher, selbst gehosteter Git-Service. Änlich wie GitHub, Bitbucket oder GitLab.
Gitea ist ein einfacher, selbst gehosteter Git-Service. Änlich wie GitHub, Bitbucket oder GitLab.
Gitea ist ein [Gogs](http://gogs.io)-Fork.
Gitea ist ein [Gogs](http://gogs.io)-Fork.
## Ziele
## Ziele
* Einfach zu installieren
* Einfach zu installieren
* Plattformübergreifend
* Plattformübergreifend
* Leichtgewichtig
* Leichtgewichtig
* Quelloffen
* Quelloffen
## System Voraussetzungen
## System Voraussetzungen
- Ein Raspberry Pi 3 ist leistungsstark genug, um Gitea für kleine Belastungen laufen zu lassen.
* Ein Raspberry Pi 3 ist leistungsstark genug, um Gitea für kleine Belastungen laufen zu lassen.
- 2 CPU Kerne und 1GB RAM sind für kleine Teams/Projekte ausreichend.
* 2 CPU Kerne und 1GB RAM sind für kleine Teams/Projekte ausreichend.
- Gitea sollte unter einem seperaten nicht-root Account auf UNIX-Systemen ausgeführt werden.
* Gitea sollte unter einem seperaten nicht-root Account auf UNIX-Systemen ausgeführt werden.
- Achtung: Gitea verwaltet die `~/.ssh/authorized_keys` Datei. Gitea unter einem normalen Benutzer auszuführen könnte dazu führen, dass dieser sich nicht mehr anmelden kann.
* Achtung: Gitea verwaltet die `~/.ssh/authorized_keys` Datei. Gitea unter einem normalen Benutzer auszuführen könnte dazu führen, dass dieser sich nicht mehr anmelden kann.
- [Git](https://git-scm.com/) Version 2.0 oder später wird benötigt.
* [Git](https://git-scm.com/) Version 2.0 oder später wird benötigt.
- Wenn git >= 2.1.2. und [Git large file storage](https://git-lfs.github.com/) aktiviert ist, dann wird es auch in Gitea verwendbar sein.
* Wenn git >= 2.1.2. und [Git large file storage](https://git-lfs.github.com/) aktiviert ist, dann wird es auch in Gitea verwendbar sein.
- Wenn git >= 2.18, dann wird das Rendern von Commit-Graphen automatisch aktiviert.
* Wenn git >= 2.18, dann wird das Rendern von Commit-Graphen automatisch aktiviert.
## Browser Unterstützung
## Browser Unterstützung
- Letzten 2 Versions von Chrome, Firefox, Safari und Edge
* Letzten 2 Versions von Chrome, Firefox, Safari und Edge
silverwind
2 years ago
committed by
GitHub