From b4dddf88041746c5bb8d0d3f72c50b5259400be2 Mon Sep 17 00:00:00 2001 From: Lunny Xiao Date: Fri, 7 Jun 2024 18:03:08 +0800 Subject: [PATCH] Use docusaurus warning/note syntax instead markdown --- docs/administration/cmd-embedded.md | 4 +- docs/administration/config-cheat-sheet.md | 42 +++++++++++----- docs/administration/customizing-gitea.md | 16 +++++-- docs/administration/email-setup.md | 12 +++-- docs/administration/git-lfs-support.md | 4 +- docs/administration/https-support.md | 4 +- docs/administration/reverse-proxies.md | 8 +++- docs/contributing/guidelines-backend.md | 4 +- docs/development/hacking-on-gitea.md | 17 +++++-- docs/development/oauth2-provider.md | 4 +- docs/help/faq.md | 4 +- docs/help/support.md | 4 +- docs/index.md | 48 ++++++++++++++----- docs/installation/database-preparation.md | 16 +++++-- docs/installation/from-binary.md | 17 +++++-- docs/installation/from-source.md | 4 +- docs/installation/on-kubernetes.md | 2 +- docs/installation/with-docker-rootless.md | 14 ++++-- docs/installation/with-docker.md | 4 +- docs/usage/authentication.md | 4 +- docs/usage/code-owners.md | 2 +- docs/usage/linked-references.md | 4 +- docs/usage/multi-factor-authentication.md | 6 ++- docs/usage/packages/container.md | 4 +- docs/usage/repo-mirror.md | 8 +++- docs/usage/template-repositories.md | 2 +- docs/usage/webhooks.md | 8 ++-- docusaurus.config.js | 6 +-- .../current/installation/on-kubernetes.md | 2 +- .../installation/with-docker-rootless.md | 10 ++-- .../current/installation/with-docker.md | 2 + .../current/usage/repo-mirror.md | 4 ++ .../current/usage/webhooks.md | 4 +- .../installation/on-kubernetes.md | 2 +- .../installation/with-docker-rootless.md | 10 ++-- .../version-1.19/installation/with-docker.md | 2 + .../version-1.19/usage/repo-mirror.md | 4 ++ .../version-1.19/usage/webhooks.md | 4 +- .../installation/on-kubernetes.md | 2 +- .../installation/with-docker-rootless.md | 10 ++-- .../version-1.20/usage/repo-mirror.md | 4 ++ .../version-1.20/usage/webhooks.md | 4 +- .../installation/on-kubernetes.md | 2 +- .../installation/with-docker-rootless.md | 10 ++-- .../version-1.21/installation/with-docker.md | 2 + .../version-1.21/usage/repo-mirror.md | 4 ++ .../version-1.21/usage/webhooks.md | 4 +- .../installation/on-kubernetes.md | 2 +- .../installation/with-docker-rootless.md | 10 ++-- .../version-1.22/installation/with-docker.md | 2 + .../version-1.22/usage/repo-mirror.md | 4 ++ .../version-1.22/usage/webhooks.md | 4 +- .../administration/cmd-embedded.md | 4 +- .../administration/config-cheat-sheet.md | 37 ++++++++++---- .../administration/customizing-gitea.md | 16 +++++-- .../administration/git-lfs-support.md | 4 +- .../administration/https-support.md | 4 +- .../administration/reverse-proxies.md | 4 +- .../contributing/guidelines-backend.md | 4 +- .../development/hacking-on-gitea.md | 17 +++++-- .../development/oauth2-provider.md | 4 +- versioned_docs/version-1.19/help/faq.md | 8 +++- versioned_docs/version-1.19/help/seek-help.md | 4 +- .../installation/database-preparation.md | 4 +- .../version-1.19/installation/from-binary.md | 18 +++++-- .../version-1.19/installation/from-source.md | 8 +++- .../installation/on-kubernetes.md | 2 +- .../installation/with-docker-rootless.md | 14 ++++-- .../version-1.19/installation/with-docker.md | 6 ++- .../version-1.19/packages/container.md | 4 +- .../version-1.19/usage/authentication.md | 4 +- .../version-1.19/usage/repo-mirror.md | 8 +++- .../usage/template-repositories.md | 4 +- versioned_docs/version-1.19/usage/webhooks.md | 8 ++-- .../administration/cmd-embedded.md | 4 +- .../administration/config-cheat-sheet.md | 37 ++++++++++---- .../administration/customizing-gitea.md | 16 +++++-- .../administration/email-setup.md | 18 +++++-- .../administration/git-lfs-support.md | 4 +- .../contributing/guidelines-backend.md | 4 +- .../development/hacking-on-gitea.md | 17 +++++-- .../development/oauth2-provider.md | 4 +- versioned_docs/version-1.20/help/faq.md | 4 +- versioned_docs/version-1.20/help/support.md | 4 +- .../version-1.20/installation/from-binary.md | 18 +++++-- .../version-1.20/installation/from-source.md | 8 +++- .../installation/on-kubernetes.md | 2 +- .../installation/with-docker-rootless.md | 14 ++++-- .../version-1.20/installation/with-docker.md | 6 ++- .../version-1.20/usage/authentication.md | 4 +- .../usage/multi-factor-authentication.md | 6 ++- .../version-1.20/usage/packages/container.md | 4 +- .../version-1.20/usage/repo-mirror.md | 8 +++- .../usage/template-repositories.md | 4 +- versioned_docs/version-1.20/usage/webhooks.md | 8 ++-- .../administration/cmd-embedded.md | 4 +- .../administration/config-cheat-sheet.md | 42 +++++++++++----- .../administration/customizing-gitea.md | 16 +++++-- .../administration/git-lfs-support.md | 4 +- .../contributing/guidelines-backend.md | 4 +- .../development/hacking-on-gitea.md | 17 +++++-- .../development/oauth2-provider.md | 4 +- versioned_docs/version-1.21/help/faq.md | 4 +- versioned_docs/version-1.21/help/support.md | 4 +- versioned_docs/version-1.21/index.md | 48 ++++++++++++++----- .../version-1.21/installation/from-binary.md | 18 +++++-- .../version-1.21/installation/from-source.md | 4 +- .../installation/on-kubernetes.md | 2 +- .../installation/with-docker-rootless.md | 14 ++++-- .../version-1.21/installation/with-docker.md | 6 ++- .../version-1.21/usage/authentication.md | 4 +- .../version-1.21/usage/code-owners.md | 2 +- .../usage/multi-factor-authentication.md | 6 ++- .../version-1.21/usage/packages/container.md | 4 +- .../version-1.21/usage/repo-mirror.md | 8 +++- .../usage/template-repositories.md | 4 +- versioned_docs/version-1.21/usage/webhooks.md | 8 ++-- .../administration/cmd-embedded.md | 4 +- .../administration/config-cheat-sheet.md | 30 +++++++++--- .../administration/customizing-gitea.md | 16 +++++-- .../administration/git-lfs-support.md | 4 +- .../contributing/guidelines-backend.md | 5 +- .../development/hacking-on-gitea.md | 17 +++++-- .../development/oauth2-provider.md | 4 +- versioned_docs/version-1.22/help/faq.md | 4 +- versioned_docs/version-1.22/help/support.md | 4 +- versioned_docs/version-1.22/index.md | 48 ++++++++++++++----- .../version-1.22/installation/from-binary.md | 18 +++++-- .../version-1.22/installation/from-source.md | 4 +- .../installation/on-kubernetes.md | 2 +- .../installation/with-docker-rootless.md | 14 ++++-- .../version-1.22/installation/with-docker.md | 6 ++- .../version-1.22/usage/authentication.md | 4 +- .../version-1.22/usage/code-owners.md | 2 +- .../usage/multi-factor-authentication.md | 6 ++- .../version-1.22/usage/packages/container.md | 4 +- .../version-1.22/usage/repo-mirror.md | 8 +++- .../usage/template-repositories.md | 2 +- versioned_docs/version-1.22/usage/webhooks.md | 8 ++-- 139 files changed, 860 insertions(+), 341 deletions(-) diff --git a/docs/administration/cmd-embedded.md b/docs/administration/cmd-embedded.md index b7f68361..a7a4db72 100644 --- a/docs/administration/cmd-embedded.md +++ b/docs/administration/cmd-embedded.md @@ -24,7 +24,9 @@ inside the `custom` directory (see [Customizing Gitea](administration/customizin To obtain a copy of the embedded resources ready for editing, the `embedded` command from the CLI can be used from the OS shell interface. -**NOTE:** The embedded data extraction tool is included in Gitea versions 1.12 and above. +:::note +The embedded data extraction tool is included in Gitea versions 1.12 and above. +::: ## Listing resources diff --git a/docs/administration/config-cheat-sheet.md b/docs/administration/config-cheat-sheet.md index f11d674a..6be6f89d 100644 --- a/docs/administration/config-cheat-sheet.md +++ b/docs/administration/config-cheat-sheet.md @@ -33,7 +33,9 @@ In the default values below, a value in the form `$XYZ` refers to an environment Values containing `#` or `;` must be quoted using `` ` `` or `"""`. -**Note:** A full restart is required for Gitea configuration changes to take effect. +:::info +A full restart is required for Gitea configuration changes to take effect. +::: ## Default Configuration (non-`app.ini` configuration) @@ -96,8 +98,12 @@ In addition, there is _`StaticRootPath`_ which can be set as a built-in at build - `GO_GET_CLONE_URL_PROTOCOL`: **https**: Value for the "go get" request returns the repository url as https or ssh default is https. - `ACCESS_CONTROL_ALLOW_ORIGIN`: **_empty_**: Value for Access-Control-Allow-Origin header, - default is not to present. **WARNING**: This maybe harmful to you website if you do not - give it a right value. + default is not to present. + + :::warning + This maybe harmful to you website if you do not give it a right value. + ::: + - `DEFAULT_CLOSE_ISSUES_VIA_COMMITS_IN_ANY_BRANCH`: **false**: Close an issue if a commit on a non default branch marks it as closed. - `ENABLE_PUSH_CREATE_USER`: **false**: Allow users to push local repositories to Gitea and have them automatically created for a user. - `ENABLE_PUSH_CREATE_ORG`: **false**: Allow users to push local repositories to Gitea and have them automatically created for an org. @@ -544,13 +550,17 @@ And the following unique queues: Number of trusted proxy count. Set to zero to not use these headers. - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all. - `DISABLE_GIT_HOOKS`: **true**: Set to `false` to enable users with Git Hook privilege to create custom Git Hooks. - WARNING: Custom Git Hooks can be used to perform arbitrary code execution on the host operating system. - This enables the users to access and modify this config file and the Gitea database and interrupt the Gitea service. - By modifying the Gitea database, users can gain Gitea administrator privileges. - It also enables them to access other resources available to the user on the operating system that is running the - Gitea instance and perform arbitrary actions in the name of the Gitea OS user. - This maybe harmful to you website or your operating system. - Setting this to true does not change existing hooks in git repos; adjust it before if necessary. + + :::warning + Custom Git Hooks can be used to perform arbitrary code execution on the host operating system. + This enables the users to access and modify this config file and the Gitea database and interrupt the Gitea service. + By modifying the Gitea database, users can gain Gitea administrator privileges. + It also enables them to access other resources available to the user on the operating system that is running the + Gitea instance and perform arbitrary actions in the name of the Gitea OS user. + This maybe harmful to you website or your operating system. + Setting this to true does not change existing hooks in git repos; adjust it before if necessary. + ::: + - `DISABLE_WEBHOOKS`: **false**: Set to `true` to disable webhooks feature. - `ONLY_ALLOW_PUSH_IF_GITEA_ENVIRONMENT_SET`: **true**: Set to `false` to allow local users to push to gitea-repositories without setting up the Gitea environment. This is not recommended and if you want local users to push to Gitea repositories you should set the environment appropriately. - `IMPORT_LOCAL_PATHS`: **false**: Set to `false` to prevent all users (including admin) from importing local path on server. @@ -632,8 +642,12 @@ And the following unique queues: - `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create accounts for users. - `REQUIRE_EXTERNAL_REGISTRATION_PASSWORD`: **false**: Enable this to force externally created - accounts (via GitHub, OpenID Connect, etc) to create a password. Warning: enabling this will - decrease security, so you should only enable it if you know what you're doing. + accounts (via GitHub, OpenID Connect, etc) to create a password. + + :::warning + Enabling this will decrease security, so you should only enable it if you know what you're doing. + ::: + - `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page or to use API. - `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when something happens, like creating issues. Requires `Mailer` to be enabled. @@ -1238,7 +1252,9 @@ in this mapping or the filetype using heuristics. - `SHARE_USER_STATISTICS`: **true**: Enable/Disable user statistics for nodeinfo if federation is enabled - `MAX_SIZE`: **4**: Maximum federation request and response size (MB) - WARNING: Changing the settings below can break federation. + :::warning + Changing the settings below can break federation. + ::: - `ALGORITHMS`: **rsa-sha256, rsa-sha512, ed25519**: HTTP signature algorithms - `DIGEST_ALGORITHM`: **SHA-256**: HTTP signature digest algorithm diff --git a/docs/administration/customizing-gitea.md b/docs/administration/customizing-gitea.md index 8475f6d1..4af254f8 100644 --- a/docs/administration/customizing-gitea.md +++ b/docs/administration/customizing-gitea.md @@ -46,7 +46,9 @@ is set under the "Configuration" tab on the site administration page. - [List of Environment Variables](administration/environment-variables.md) -**Note:** Gitea must perform a full restart to see configuration changes. +:::note +Gitea must perform a full restart to see configuration changes. +::: ## Serving custom public files @@ -288,7 +290,9 @@ Google Analytics, Matomo (previously Piwik), and other analytics services can be Place custom files in corresponding sub-folder under `custom/options`. -**NOTE:** The files should not have a file extension, e.g. `Labels` rather than `Labels.txt` +:::note +The files should not have a file extension, e.g. `Labels` rather than `Labels.txt` +::: ### gitignores @@ -340,7 +344,7 @@ Gitea's default locale files can be found in the [`options/locale`](https://gith To add a completely new locale, as well as placing the file in the above location, you will need to add the new lang and name to the `[i18n]` section in your `app.ini`. Keep in mind that Gitea will use those settings as **overrides**, so if you want to keep the other languages as well you will need to copy/paste the default values and add your own to them. -``` +```ini title="app.ini" [i18n] LANGS = en-US,foo-BAR NAMES = English,FooBar @@ -354,14 +358,16 @@ Locales may change between versions, so keeping track of your customized locales To add a custom Readme, add a markdown formatted file (without an `.md` extension) to `$GITEA_CUSTOM/options/readme` -**NOTE:** readme templates support **variable expansion**. +:::note +Readme templates support **variable expansion**. currently there are `{Name}` (name of repository), `{Description}`, `{CloneURL.SSH}`, `{CloneURL.HTTPS}` and `{OwnerName}` +::: ### Reactions To change reaction emoji's you can set allowed reactions at app.ini -``` +```ini title="app.ini" [ui] REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes ``` diff --git a/docs/administration/email-setup.md b/docs/administration/email-setup.md index 690d8041..aa88d9be 100644 --- a/docs/administration/email-setup.md +++ b/docs/administration/email-setup.md @@ -23,9 +23,13 @@ Gitea has mailer functionality for sending transactional emails (such as registr 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 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. +:::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. +::: ```ini title="app.ini" [mailer] @@ -57,7 +61,9 @@ 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](administration/config-cheat-sheet.md) -Please note: authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through: +:::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. diff --git a/docs/administration/git-lfs-support.md b/docs/administration/git-lfs-support.md index d2c55a29..79e45572 100644 --- a/docs/administration/git-lfs-support.md +++ b/docs/administration/git-lfs-support.md @@ -29,4 +29,6 @@ LFS_START_SERVER = true PATH = /home/gitea/data/lfs ``` -**Note**: LFS server support needs at least Git v2.1.2 installed on the server +:::note +LFS server support needs at least Git v2.1.2 installed on the server +::: diff --git a/docs/administration/https-support.md b/docs/administration/https-support.md index 981a29bd..2587e3f5 100644 --- a/docs/administration/https-support.md +++ b/docs/administration/https-support.md @@ -97,4 +97,6 @@ After that, enable HTTPS by following one of these guides: - [apache2/httpd](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html) - [caddy](https://caddyserver.com/docs/tls) -Note: 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. +:::note +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. +::: diff --git a/docs/administration/reverse-proxies.md b/docs/administration/reverse-proxies.md index dff58c10..093046af 100644 --- a/docs/administration/reverse-proxies.md +++ b/docs/administration/reverse-proxies.md @@ -173,7 +173,9 @@ If you want Apache HTTPD to serve your Gitea instance, you can add the following ``` -Note: The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`. +:::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. @@ -198,7 +200,9 @@ In case you already have a site, and you want Gitea to share the domain name, yo 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`. +:::note +The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`. +::: ## Caddy diff --git a/docs/contributing/guidelines-backend.md b/docs/contributing/guidelines-backend.md index 3159a5ff..11455c3a 100644 --- a/docs/contributing/guidelines-backend.md +++ b/docs/contributing/guidelines-backend.md @@ -58,8 +58,7 @@ Since Golang doesn't support import cycles, we have to decide the package depend 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. -**NOTICE** - +:::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, @@ -90,6 +89,7 @@ func UpdateIssue(ctx context.Context, repoID int64) error { // ... } ``` +::: ### Package Name diff --git a/docs/development/hacking-on-gitea.md b/docs/development/hacking-on-gitea.md index 004e8038..eba4da17 100644 --- a/docs/development/hacking-on-gitea.md +++ b/docs/development/hacking-on-gitea.md @@ -32,17 +32,21 @@ Next, [install Node.js with npm](https://nodejs.org/en/download/) which is required to build the JavaScript and CSS files. The minimum supported Node.js version is @minNodeVersion@ and the latest LTS version is recommended. -**Note**: When executing make tasks that require external tools, like +:::note +When executing make tasks that require external tools, like `make watch-backend`, Gitea will automatically download and build these as necessary. To be able to use these you must have the `"$GOPATH"/bin` directory on the executable path. If you don't add the go bin directory to the executable path you will have to manage this yourself. +::: -**Note 2**: Go version @minGoVersion@ or higher is required. +:::note +Go version @minGoVersion@ or higher is required. Gitea uses `gofmt` to format source code. However, the results of `gofmt` can differ by the version of `go`. Therefore it is recommended to install the version of Go that our continuous integration is running. As of last update, the Go version should be @goVersion@. +::: To lint the template files, ensure [Python](https://www.python.org/) and [Poetry](https://python-poetry.org/) are installed. @@ -82,7 +86,9 @@ One of these three distributions of Make will run on Windows: - To compile Gitea with CGO_ENABLED (eg: SQLite3), you might need to use [tdm-gcc](https://jmeubank.github.io/tdm-gcc/) instead of MSYS2 gcc, because MSYS2 gcc headers lack some Windows-only CRT functions like `_beginthread`. - [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make` -**Note**: If you are attempting to build using make with Windows Command Prompt, you may run into issues. The above prompts (Git bash, or MinGW) are recommended, however if you only have command prompt (or potentially PowerShell) you can set environment variables using the [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) command, e.g. `set TAGS=bindata`. +:::note +If you are attempting to build using make with Windows Command Prompt, you may run into issues. The above prompts (Git bash, or MinGW) are recommended, however if you only have command prompt (or potentially PowerShell) you can set environment variables using the [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) command, e.g. `set TAGS=bindata`. +::: ## Downloading and cloning the Gitea source code @@ -256,8 +262,9 @@ server will check that this has been done using: make swagger-check ``` -**Note**: Please note you should use the Swagger 2.0 documentation, not the -OpenAPI 3 documentation. +:::note +Please note you should use the Swagger 2.0 documentation, not the OpenAPI 3 documentation. +::: ### Creating new configuration options diff --git a/docs/development/oauth2-provider.md b/docs/development/oauth2-provider.md index 54674f92..cc504502 100644 --- a/docs/development/oauth2-provider.md +++ b/docs/development/oauth2-provider.md @@ -100,7 +100,9 @@ For public clients, a redirect URI of a loopback IP address such as `http://127. ### Confidential client -**Note:** This example does not use PKCE. +:::note +This example does not use PKCE. +::: 1. Redirect the user to the authorization endpoint in order to get their consent for accessing the resources: diff --git a/docs/help/faq.md b/docs/help/faq.md index e94f3421..a8082807 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -160,7 +160,9 @@ You can configure `EMAIL_DOMAIN_WHITELIST` or `EMAIL_DOMAIN_BLOCKLIST` in your a 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 diff --git a/docs/help/support.md b/docs/help/support.md index bc8a8e3f..9dd30727 100644 --- a/docs/help/support.md +++ b/docs/help/support.md @@ -30,7 +30,9 @@ menu: If you found a bug, please [create an issue on GitHub](https://github.com/go-gitea/gitea/issues). -**NOTE:** When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need: +:::note +When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need: +::: 1. Your `app.ini` (with any sensitive data scrubbed as necessary). 2. Any error messages you are seeing. diff --git a/docs/index.md b/docs/index.md index dc2eb147..73dc86d6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,6 +13,12 @@ Gitea is a painless self-hosted all-in-one software development service, it incl Gitea was forked from [Gogs](http://gogs.io) originally and almost all the code has been changed. See the [Gitea Announcement](https://blog.gitea.com/welcome-to-gitea/) blog post to read about the justification for a fork. +:::warning + +Gitea has never sent commits to upstream or cherry-pick commits from upstream. So Gitea is totally not compatible with Gogs. No any gurantee it can work if you upgrade from Gogs to Gitea. The recommands method is to migrate repositories from Gogs to Gitea. + +::: + ## Purpose The goal of this project is to provide the easiest, fastest, and most painless way of setting @@ -25,27 +31,47 @@ You can try it out using [the online demo](https://demo.gitea.com). ## Features -- Code Hosting: Gitea supports creating and managing repositories, browsing commit history and code files, reviewing and merging code submissions, managing collaborators, handling branches, and more. It also supports many common Git features such as tags, Cherry-pick, hooks, integrated collaboration tools, and more. +- **Code Hosting** -- Lightweight and Fast: One of Gitea's design goals is to be lightweight and fast in response. Unlike some large code hosting platforms, it remains lean, performing well in terms of speed, and is suitable for resource-limited server environments. Due to its lightweight design, Gitea has relatively low resource consumption and performs well in resource-constrained environments. + Gitea supports creating and managing repositories, browsing commit history and code files, reviewing and merging code submissions, managing collaborators, handling branches, and more. It also supports many common Git features such as tags, Cherry-pick, hooks, integrated collaboration tools, and more. -- Easy Deployment and Maintenance: It can be easily deployed on various servers without complex configurations or dependencies. This makes it convenient for individual developers or small teams to set up and manage their own Git services. +- **Lightweight and Fast** -- Security: Gitea places a strong emphasis on security, offering features such as user permission management, access control lists, and more to ensure the security of code and data. + One of Gitea's design goals is to be lightweight and fast in response. Unlike some large code hosting platforms, it remains lean, performing well in terms of speed, and is suitable for resource-limited server environments. Due to its lightweight design, Gitea has relatively low resource consumption and performs well in resource-constrained environments. -- Code Review: Code review supports both the Pull Request workflow and AGit workflow. Reviewers can browse code online and provide review comments or feedback. Submitters can receive review comments and respond or modify code online. Code reviews can help individuals and organizations enhance code quality. +- **Easy Deployment and Maintenance** -- CI/CD: Gitea Actions supports CI/CD functionality, compatible with GitHub Actions. Users can write workflows in familiar YAML format and reuse a variety of existing Actions plugins. Actions plugins support downloading from any Git website. + It can be easily deployed on various servers without complex configurations or dependencies. This makes it convenient for individual developers or small teams to set up and manage their own Git services. -- Project Management: Gitea tracks project requirements, features, and bugs through columns and issues. Issues support features like branches, tags, milestones, assignments, time tracking, due dates, dependencies, and more. +- **Security** -- Artifact Repository: Gitea supports over 20 different types of public or private software package management, including Cargo, Chef, Composer, Conan, Conda, Container, Helm, Maven, npm, NuGet, Pub, PyPI, RubyGems, Vagrant, and more. + Gitea places a strong emphasis on security, offering features such as user permission management, access control lists, and more to ensure the security of code and data. -- Open Source Community Support: Gitea is an open-source project based on the MIT license. It has an active open-source community that continuously develops and improves the platform. The project also actively welcomes community contributions, ensuring updates and innovation. +- **Code Review** -- Multilingual Support: Gitea provides interfaces in multiple languages, catering to users globally and promoting internationalization and localization. + Code review supports both the Pull Request workflow and AGit workflow. Reviewers can browse code online and provide review comments or feedback. Submitters can receive review comments and respond or modify code online. Code reviews can help individuals and organizations enhance code quality. -Additional Features: For more detailed information, please refer to: https://docs.gitea.com/installation/comparison#general-features +- **CI/CD** + + Gitea Actions supports CI/CD functionality, compatible with GitHub Actions. Users can write workflows in familiar YAML format and reuse a variety of existing Actions plugins. Actions plugins support downloading from any Git website. + +- **Project Management** + + Gitea tracks project requirements, features, and bugs through columns and issues. Issues support features like branches, tags, milestones, assignments, time tracking, due dates, dependencies, and more. + +- **Artifact Repository** + + Gitea supports over 20 different types of public or private software package management, including Cargo, Chef, Composer, Conan, Conda, Container, Helm, Maven, npm, NuGet, Pub, PyPI, RubyGems, Vagrant, and more. + +- **Open Source Community Support** + + Gitea is an open-source project based on the MIT license. It has an active open-source community that continuously develops and improves the platform. The project also actively welcomes community contributions, ensuring updates and innovation. + +- **Multilingual Support** + + Gitea provides interfaces in multiple languages, catering to users globally and promoting internationalization and localization. + +For more detailed information, please refer to: https://docs.gitea.com/installation/comparison#general-features ## System Requirements diff --git a/docs/installation/database-preparation.md b/docs/installation/database-preparation.md index 6a9e334d..a1898aa7 100644 --- a/docs/installation/database-preparation.md +++ b/docs/installation/database-preparation.md @@ -23,7 +23,9 @@ If you use an unsupported database version, please [get in touch](/help/support) Database instance can be on same machine as Gitea (local database setup), or on different machine (remote database). -Note: All steps below requires that the database engine of your choice is installed on your system. For remote database setup, install the server application on database instance and client program on your Gitea server. The client program is used to test connection to the database from Gitea server, while Gitea itself use database driver provided by Go to accomplish the same thing. In addition, make sure you use same engine version for both server and client for some engine features to work. For security reason, protect `root` (MySQL) or `postgres` (PostgreSQL) database superuser with secure password. The steps assumes that you run Linux for both database and Gitea servers. +:::note +All steps below requires that the database engine of your choice is installed on your system. For remote database setup, install the server application on database instance and client program on your Gitea server. The client program is used to test connection to the database from Gitea server, while Gitea itself use database driver provided by Go to accomplish the same thing. In addition, make sure you use same engine version for both server and client for some engine features to work. For security reason, protect `root` (MySQL) or `postgres` (PostgreSQL) database superuser with secure password. The steps assumes that you run Linux for both database and Gitea servers. +::: ## MySQL/MariaDB @@ -155,7 +157,9 @@ Note: All steps below requires that the database engine of your choice is instal Replace database name, user, and IP address of Gitea instance with your own. - Note: rules on `pg_hba.conf` are evaluated sequentially, that is the first matching rule will be used for authentication. Your PostgreSQL installation may come with generic authentication rules that match all users and databases. You may need to place the rules presented here above such generic rules if it is the case. + :::note + Rules on `pg_hba.conf` are evaluated sequentially, that is the first matching rule will be used for authentication. Your PostgreSQL installation may come with generic authentication rules that match all users and databases. You may need to place the rules presented here above such generic rules if it is the case. + ::: Restart PostgreSQL to apply new authentication rules. @@ -163,13 +167,13 @@ Note: All steps below requires that the database engine of your choice is instal For local database: - ``` + ```bash psql -U gitea -d giteadb ``` For remote database: - ``` + ```bash psql "postgres://gitea@203.0.113.3/giteadb" ``` @@ -239,7 +243,9 @@ The PostgreSQL driver used by Gitea supports two-way TLS. In two-way TLS, both d - `~/.postgresql/postgresql.key`: Database client private key - `~/.postgresql/root.crt`: CA certificate chain to validate server certificate - Note: Those file names above are hardcoded in PostgreSQL and it is not possible to change them. + :::note + Those file names above are hardcoded in PostgreSQL and it is not possible to change them. + ::: 7. Adjust credentials, ownership and permission as required: diff --git a/docs/installation/from-binary.md b/docs/installation/from-binary.md index cf5d11c7..dda08aa8 100644 --- a/docs/installation/from-binary.md +++ b/docs/installation/from-binary.md @@ -64,8 +64,10 @@ despite warnings like `This key is not certified with a trusted signature!`. ## Recommended server configuration -**NOTE:** Many of the following directories can be configured using [Environment Variables](administration/environment-variables.md) as well! +:::note +Many of the following directories can be configured using [Environment Variables](administration/environment-variables.md) as well! Of note, configuring `GITEA_WORK_DIR` will tell Gitea where to base its working directory, as well as ease installation. +::: ### Prepare environment @@ -111,7 +113,10 @@ chown root:git /etc/gitea chmod 770 /etc/gitea ``` -> **NOTE:** `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using: +:::note +> `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using: +::: + > > ```sh > chmod 750 /etc/gitea @@ -129,7 +134,9 @@ See the [command line documentation](administration/command-line.md) for informa ### Configure Gitea's working directory -**NOTE:** If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory. +:::note +If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory. +::: ```sh export GITEA_WORK_DIR=/var/lib/gitea/ @@ -185,7 +192,9 @@ To restart your Gitea instance, we recommend to use SIGHUP signal. If you know y To gracefully stop the Gitea instance, a simple `kill $GITEA_PID` or `killall gitea` is enough. -**NOTE:** We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.) +:::note +We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.) +::: See below for troubleshooting instructions to repair broken repositories after an update of your Gitea version. diff --git a/docs/installation/from-source.md b/docs/installation/from-source.md index cd9fd565..79ad660d 100644 --- a/docs/installation/from-source.md +++ b/docs/installation/from-source.md @@ -27,9 +27,11 @@ Next, [install Node.js with npm](https://nodejs.org/en/download/) which is required to build the JavaScript and CSS files. The minimum supported Node.js version is @minNodeVersion@ and the latest LTS version is recommended. -**Note**: Go version @minGoVersion@ or higher is required. However, it is recommended to +:::note +Go version @minGoVersion@ or higher is required. However, it is recommended to obtain the same version as our continuous integration, see the advice given in [Hacking on Gitea](development/hacking-on-gitea.md) +::: ## Download diff --git a/docs/installation/on-kubernetes.md b/docs/installation/on-kubernetes.md index 00f2aab2..c9036af1 100644 --- a/docs/installation/on-kubernetes.md +++ b/docs/installation/on-kubernetes.md @@ -46,7 +46,7 @@ Gitea comes with a health check endpoint `/api/healthz`, you can configure it in a successful health check response will respond with http code `200`, here's example: -``` +```json HTTP/1.1 200 OK { diff --git a/docs/installation/with-docker-rootless.md b/docs/installation/with-docker-rootless.md index 10f12122..df287c55 100644 --- a/docs/installation/with-docker-rootless.md +++ b/docs/installation/with-docker-rootless.md @@ -242,8 +242,10 @@ started properly. Logs can be viewed with `docker-compose logs`. To shut down the setup, execute `docker-compose down`. This will stop and kill the containers. The volumes will still exist. -Notice: if using a non-3000 port on http, change app.ini to match +:::note +If using a non-3000 port on http, change app.ini to match `LOCAL_ROOT_URL = http://localhost:3000/`. +::: ## Install @@ -252,7 +254,7 @@ favorite browser to finalize the installation. Visit http://server-ip:3000 and f installation wizard. If the database was started with the `docker-compose` setup as documented above, please note that `db` must be used as the database hostname. -# Customization +## Customization Customization files described [here](administration/customizing-gitea.md) should be placed in `/var/lib/gitea/custom` directory. If using host volumes, it's quite easy to access these @@ -260,13 +262,15 @@ files; for named volumes, this is done through another container or by direct ac `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea`. The configuration file will be saved at `/etc/gitea/app.ini` after the installation. -# Upgrading +## Upgrading +:::warning :exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: +::: To upgrade your installation to the latest release: -``` +```bash # Edit `docker-compose.yml` to update the version, if you have one specified # Pull new images docker-compose pull @@ -274,7 +278,7 @@ docker-compose pull docker-compose up -d ``` -# Upgrading from standard image +## Upgrading from standard image - Backup your setup - Change volume mountpoint from /data to /var/lib/gitea diff --git a/docs/installation/with-docker.md b/docs/installation/with-docker.md index 4ddfa470..cd81ab43 100644 --- a/docs/installation/with-docker.md +++ b/docs/installation/with-docker.md @@ -243,8 +243,10 @@ started properly. Logs can be viewed with `docker-compose logs`. To shut down the setup, execute `docker-compose down`. This will stop and kill the containers. The volumes will still exist. -Notice: if using a non-3000 port on http, change app.ini to match +:::note +If using a non-3000 port on http, change app.ini to match `LOCAL_ROOT_URL = http://localhost:3000/`. +::: ## Installation diff --git a/docs/usage/authentication.md b/docs/usage/authentication.md index 963f03a0..40c8f80f 100644 --- a/docs/usage/authentication.md +++ b/docs/usage/authentication.md @@ -348,4 +348,6 @@ 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. -Notice: Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests. +:::note +Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests. +::: diff --git a/docs/usage/code-owners.md b/docs/usage/code-owners.md index 7642175d..d39b3855 100644 --- a/docs/usage/code-owners.md +++ b/docs/usage/code-owners.md @@ -32,7 +32,7 @@ Regexp can start with `!` for negative rules - match all files except specified. Example file: -``` +```bash .*\\.go @user1 @user2 # This is comment # Comment too diff --git a/docs/usage/linked-references.md b/docs/usage/linked-references.md index a0acb024..440727b4 100644 --- a/docs/usage/linked-references.md +++ b/docs/usage/linked-references.md @@ -197,5 +197,7 @@ _The last section is for repositories with external issue trackers that use alph _**-**: not applicable._ -Note: automatic references between repositories with different types of issues (external vs. internal) are not fully supported +:::note +Automatic references between repositories with different types of issues (external vs. internal) are not fully supported and may render invalid links. +::: diff --git a/docs/usage/multi-factor-authentication.md b/docs/usage/multi-factor-authentication.md index 30323f6d..9bfa3e8a 100644 --- a/docs/usage/multi-factor-authentication.md +++ b/docs/usage/multi-factor-authentication.md @@ -28,8 +28,10 @@ This interface does not support MFA, and trying to use a password normally will If SSH is not an option for Git operations, an access token can be generated within the "Applications" tab of the user settings page. This access token can be used as if it were a password in order to allow the Git CLI to function over HTTP. -> **Warning** - By its very nature, an access token sidesteps the security benefits of MFA. -> It must be kept secure and should only be used as a last resort. +:::warning +By its very nature, an access token sidesteps the security benefits of MFA. +It must be kept secure and should only be used as a last resort. +::: The Gitea API supports providing the relevant TOTP password in the `X-Gitea-OTP` header, as described in [API Usage](development/api-usage.md). This should be used instead of an access token where possible. diff --git a/docs/usage/packages/container.md b/docs/usage/packages/container.md index 5676aa36..cdc2fdc9 100644 --- a/docs/usage/packages/container.md +++ b/docs/usage/packages/container.md @@ -57,7 +57,9 @@ For example, these are all valid image names for the owner `testuser`: `gitea.example.com/testuser/my/image` -**NOTE:** The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. +:::note +The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. +::: ## Push an image diff --git a/docs/usage/repo-mirror.md b/docs/usage/repo-mirror.md index 9d231598..5e3dd21a 100644 --- a/docs/usage/repo-mirror.md +++ b/docs/usage/repo-mirror.md @@ -39,7 +39,9 @@ For an existing remote repository, you can set up pull mirroring as follows: The repository now gets mirrored periodically from the remote repository. You can force a sync by selecting **Synchronize Now** in the repository settings. -:exclamation::exclamation: **NOTE:** You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation: +:::warning +:exclamation::exclamation: You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation: +::: ## Pushing to a remote repository @@ -52,7 +54,9 @@ For an existing repository, you can set up push mirroring as follows: The repository now gets mirrored periodically to the remote repository. You can force a sync by selecting **Synchronize Now**. In case of an error a message displayed to help you resolve it. -:exclamation::exclamation: **NOTE:** This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation: +:::warning +:exclamation::exclamation: This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation: +::: ### Setting up a push mirror from Gitea to GitHub diff --git a/docs/usage/template-repositories.md b/docs/usage/template-repositories.md index e57ed85c..8ce3cc03 100644 --- a/docs/usage/template-repositories.md +++ b/docs/usage/template-repositories.md @@ -32,7 +32,7 @@ Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax. It All paths are relative to the base of the repository -```gitignore +```bash # Expand all .go files, anywhere in the repository **.go diff --git a/docs/usage/webhooks.md b/docs/usage/webhooks.md index 684911f8..3d92e109 100644 --- a/docs/usage/webhooks.md +++ b/docs/usage/webhooks.md @@ -34,12 +34,14 @@ All event pushes are POST requests. The methods currently supported are: ### Event information -**WARNING**: The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 +:::warning +The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 +::: The following is an example of event information that will be sent by Gitea to a Payload URL: -``` +```http X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 X-GitHub-Event: push X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 @@ -133,7 +135,7 @@ In your repository Settings, under Webhooks, Setup a Gitea webhook as follows: Now on your server create the php file webhook.php -``` +```php :3000` 并按照安装向导进行操作。如果数据库是使用上述文档中的 `docker-compose` 设置启动的，请注意必须使用 `db` 作为数据库主机名。 -# 自定义 +## 自定义 自定义文件的位置位于 `/var/lib/gitea/custom` 目录中，可以在这里找到有关自定义的文件说明。如果使用主机卷（host volumes），很容易访问这些文件；如果使用命名卷（named volumes），则可以通过另一个容器或直接访问 `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea` 来进行访问。在安装后，配置文件将保存在 `/etc/gitea/app.ini` 中。 -# 升级 +## 升级 +:::warning :exclamation::exclamation: **确保您已将数据卷迁移到 Docker 容器之外的其他位置** :exclamation::exclamation: +::: 要将安装升级到最新版本，请按照以下步骤操作： -``` +```bash # 如果在 docker-compose.yml 中指定了版本，请编辑该文件以更新版本 # 拉取新的镜像 docker-compose pull @@ -251,7 +253,7 @@ docker-compose pull docker-compose up -d ``` -# 从标准镜像升级 +## 从标准镜像升级 - 备份您的设置 - 将卷挂载点从 `/data` 更改为 `/var/lib/gitea` diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/current/installation/with-docker.md b/i18n/zh-cn/docusaurus-plugin-content-docs/current/installation/with-docker.md index fcaff1c1..77ac6ab2 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/current/installation/with-docker.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/installation/with-docker.md @@ -264,7 +264,9 @@ MySQL 或 PostgreSQL 容器将需要分别创建。 ## 升级 +:::warning :exclamation::exclamation: **确保已将数据卷到 Docker 容器外部的某个位置** :exclamation::exclamation: +::: 要将安装升级到最新版本： diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/repo-mirror.md b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/repo-mirror.md index b74a1b62..eab8329f 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/repo-mirror.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/repo-mirror.md @@ -39,7 +39,9 @@ menu: 现在，该仓库会定期从远程仓库进行镜像。您可以通过在仓库设置中选择“立即同步”来强制进行同步。 +:::warning :exclamation::exclamation: **注意：**您只能为尚不存在于您的实例上的仓库设置拉取镜像。一旦仓库创建成功，您就无法再将其转换为拉取镜像。:exclamation::exclamation: +::: ## 推送到远程仓库 @@ -52,7 +54,9 @@ menu: 该仓库现在会定期镜像到远程仓库。您可以通过选择**立即同步**来强制同步。如果出现错误，会显示一条消息帮助您解决问题。 +:::warning :exclamation::exclamation: **注意：** 这将强制推送到远程仓库。这将覆盖远程仓库中的任何更改！ :exclamation::exclamation: +::: ### 从 Gitea 向 GitHub 设置推送镜像 diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/webhooks.md b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/webhooks.md index dfc70994..6ebf0aec 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/webhooks.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/webhooks.md @@ -37,7 +37,7 @@ Gitea支持用于仓库事件的Webhooks。这可以在仓库管理员在设置 以下是 Gitea 将发送给 payload URL的事件信息示例： -``` +```http X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 X-GitHub-Event: push X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 @@ -131,7 +131,7 @@ X-Gitea-Event: push 现在在你的服务器上创建 php 文件 webhook.php。 -``` +```php :3000` 并按照安装向导进行操作。如果数据库是使用上述文档中的 `docker-compose` 设置启动的，请注意必须使用 `db` 作为数据库主机名。 -# 自定义 +## 自定义 自定义文件的位置位于 `/var/lib/gitea/custom` 目录中，可以在这里找到有关自定义的文件说明。如果使用主机卷（host volumes），很容易访问这些文件；如果使用命名卷（named volumes），则可以通过另一个容器或直接访问 `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea` 来进行访问。在安装后，配置文件将保存在 `/etc/gitea/app.ini` 中。 -# 升级 +## 升级 +:::warning :exclamation::exclamation: **确保您已将数据卷迁移到 Docker 容器之外的其他位置** :exclamation::exclamation: +::: 要将安装升级到最新版本，请按照以下步骤操作： -``` +```bash # 如果在 docker-compose.yml 中指定了版本，请编辑该文件以更新版本 # 拉取新的镜像 docker-compose pull @@ -251,7 +253,7 @@ docker-compose pull docker-compose up -d ``` -# 从标准镜像升级 +## 从标准镜像升级 - 备份您的设置 - 将卷挂载点从 `/data` 更改为 `/var/lib/gitea` diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/installation/with-docker.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/installation/with-docker.md index 803336c0..5c74e823 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/installation/with-docker.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/installation/with-docker.md @@ -262,7 +262,9 @@ MySQL 或 PostgreSQL 容器将需要分别创建。 ## 升级 +:::warning :exclamation::exclamation: **确保已将数据卷到 Docker 容器外部的某个位置** :exclamation::exclamation: +::: 要将安装升级到最新版本： diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/usage/repo-mirror.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/usage/repo-mirror.md index 3723b81e..7b2b801f 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/usage/repo-mirror.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/usage/repo-mirror.md @@ -39,7 +39,9 @@ menu: 现在，该仓库会定期从远程仓库进行镜像。您可以通过在仓库设置中选择“立即同步”来强制进行同步。 +:::warning :exclamation::exclamation: **注意：**您只能为尚不存在于您的实例上的仓库设置拉取镜像。一旦仓库创建成功，您就无法再将其转换为拉取镜像。:exclamation::exclamation: +::: ## 推送到远程仓库 @@ -52,7 +54,9 @@ menu: 该仓库现在会定期镜像到远程仓库。您可以通过选择**立即同步**来强制同步。如果出现错误，会显示一条消息帮助您解决问题。 +:::warning :exclamation::exclamation: **注意：** 这将强制推送到远程仓库。这将覆盖远程仓库中的任何更改！ :exclamation::exclamation: +::: ### 从 Gitea 向 GitHub 设置推送镜像 diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/usage/webhooks.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/usage/webhooks.md index 7ca4ac51..4614b3a0 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/usage/webhooks.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.19/usage/webhooks.md @@ -35,7 +35,7 @@ Gitea支持用于仓库事件的Webhooks。这可以在仓库管理员在设置 以下是 Gitea 将发送给 payload URL的事件信息示例： -``` +```http X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 X-GitHub-Event: push X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 @@ -129,7 +129,7 @@ X-Gitea-Event: push 现在在你的服务器上创建 php 文件 webhook.php。 -``` +```php :3000` 并按照安装向导进行操作。如果数据库是使用上述文档中的 `docker-compose` 设置启动的，请注意必须使用 `db` 作为数据库主机名。 -# 自定义 +## 自定义 自定义文件的位置位于 `/var/lib/gitea/custom` 目录中，可以在这里找到有关自定义的文件说明。如果使用主机卷（host volumes），很容易访问这些文件；如果使用命名卷（named volumes），则可以通过另一个容器或直接访问 `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea` 来进行访问。在安装后，配置文件将保存在 `/etc/gitea/app.ini` 中。 -# 升级 +## 升级 +:::warning :exclamation::exclamation: **确保您已将数据卷迁移到 Docker 容器之外的其他位置** :exclamation::exclamation: +::: 要将安装升级到最新版本，请按照以下步骤操作： -``` +```bash # 如果在 docker-compose.yml 中指定了版本，请编辑该文件以更新版本 # 拉取新的镜像 docker-compose pull @@ -251,7 +253,7 @@ docker-compose pull docker-compose up -d ``` -# 从标准镜像升级 +## 从标准镜像升级 - 备份您的设置 - 将卷挂载点从 `/data` 更改为 `/var/lib/gitea` diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.20/usage/repo-mirror.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.20/usage/repo-mirror.md index 3723b81e..7b2b801f 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.20/usage/repo-mirror.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.20/usage/repo-mirror.md @@ -39,7 +39,9 @@ menu: 现在，该仓库会定期从远程仓库进行镜像。您可以通过在仓库设置中选择“立即同步”来强制进行同步。 +:::warning :exclamation::exclamation: **注意：**您只能为尚不存在于您的实例上的仓库设置拉取镜像。一旦仓库创建成功，您就无法再将其转换为拉取镜像。:exclamation::exclamation: +::: ## 推送到远程仓库 @@ -52,7 +54,9 @@ menu: 该仓库现在会定期镜像到远程仓库。您可以通过选择**立即同步**来强制同步。如果出现错误，会显示一条消息帮助您解决问题。 +:::warning :exclamation::exclamation: **注意：** 这将强制推送到远程仓库。这将覆盖远程仓库中的任何更改！ :exclamation::exclamation: +::: ### 从 Gitea 向 GitHub 设置推送镜像 diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.20/usage/webhooks.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.20/usage/webhooks.md index dfc70994..6ebf0aec 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.20/usage/webhooks.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.20/usage/webhooks.md @@ -37,7 +37,7 @@ Gitea支持用于仓库事件的Webhooks。这可以在仓库管理员在设置 以下是 Gitea 将发送给 payload URL的事件信息示例： -``` +```http X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 X-GitHub-Event: push X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 @@ -131,7 +131,7 @@ X-Gitea-Event: push 现在在你的服务器上创建 php 文件 webhook.php。 -``` +```php :3000` 并按照安装向导进行操作。如果数据库是使用上述文档中的 `docker-compose` 设置启动的，请注意必须使用 `db` 作为数据库主机名。 -# 自定义 +## 自定义 自定义文件的位置位于 `/var/lib/gitea/custom` 目录中，可以在这里找到有关自定义的文件说明。如果使用主机卷（host volumes），很容易访问这些文件；如果使用命名卷（named volumes），则可以通过另一个容器或直接访问 `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea` 来进行访问。在安装后，配置文件将保存在 `/etc/gitea/app.ini` 中。 -# 升级 +## 升级 +:::warning :exclamation::exclamation: **确保您已将数据卷迁移到 Docker 容器之外的其他位置** :exclamation::exclamation: +::: 要将安装升级到最新版本，请按照以下步骤操作： -``` +```bash # 如果在 docker-compose.yml 中指定了版本，请编辑该文件以更新版本 # 拉取新的镜像 docker-compose pull @@ -251,7 +253,7 @@ docker-compose pull docker-compose up -d ``` -# 从标准镜像升级 +## 从标准镜像升级 - 备份您的设置 - 将卷挂载点从 `/data` 更改为 `/var/lib/gitea` diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/installation/with-docker.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/installation/with-docker.md index fcaff1c1..77ac6ab2 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/installation/with-docker.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/installation/with-docker.md @@ -264,7 +264,9 @@ MySQL 或 PostgreSQL 容器将需要分别创建。 ## 升级 +:::warning :exclamation::exclamation: **确保已将数据卷到 Docker 容器外部的某个位置** :exclamation::exclamation: +::: 要将安装升级到最新版本： diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/usage/repo-mirror.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/usage/repo-mirror.md index b74a1b62..eab8329f 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/usage/repo-mirror.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/usage/repo-mirror.md @@ -39,7 +39,9 @@ menu: 现在，该仓库会定期从远程仓库进行镜像。您可以通过在仓库设置中选择“立即同步”来强制进行同步。 +:::warning :exclamation::exclamation: **注意：**您只能为尚不存在于您的实例上的仓库设置拉取镜像。一旦仓库创建成功，您就无法再将其转换为拉取镜像。:exclamation::exclamation: +::: ## 推送到远程仓库 @@ -52,7 +54,9 @@ menu: 该仓库现在会定期镜像到远程仓库。您可以通过选择**立即同步**来强制同步。如果出现错误，会显示一条消息帮助您解决问题。 +:::warning :exclamation::exclamation: **注意：** 这将强制推送到远程仓库。这将覆盖远程仓库中的任何更改！ :exclamation::exclamation: +::: ### 从 Gitea 向 GitHub 设置推送镜像 diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/usage/webhooks.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/usage/webhooks.md index dfc70994..6ebf0aec 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/usage/webhooks.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.21/usage/webhooks.md @@ -37,7 +37,7 @@ Gitea支持用于仓库事件的Webhooks。这可以在仓库管理员在设置 以下是 Gitea 将发送给 payload URL的事件信息示例： -``` +```http X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 X-GitHub-Event: push X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 @@ -131,7 +131,7 @@ X-Gitea-Event: push 现在在你的服务器上创建 php 文件 webhook.php。 -``` +```php :3000` 并按照安装向导进行操作。如果数据库是使用上述文档中的 `docker-compose` 设置启动的，请注意必须使用 `db` 作为数据库主机名。 -# 自定义 +## 自定义 自定义文件的位置位于 `/var/lib/gitea/custom` 目录中，可以在这里找到有关自定义的文件说明。如果使用主机卷（host volumes），很容易访问这些文件；如果使用命名卷（named volumes），则可以通过另一个容器或直接访问 `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea` 来进行访问。在安装后，配置文件将保存在 `/etc/gitea/app.ini` 中。 -# 升级 +## 升级 +:::warning :exclamation::exclamation: **确保您已将数据卷迁移到 Docker 容器之外的其他位置** :exclamation::exclamation: +::: 要将安装升级到最新版本，请按照以下步骤操作： -``` +```bash # 如果在 docker-compose.yml 中指定了版本，请编辑该文件以更新版本 # 拉取新的镜像 docker-compose pull @@ -251,7 +253,7 @@ docker-compose pull docker-compose up -d ``` -# 从标准镜像升级 +## 从标准镜像升级 - 备份您的设置 - 将卷挂载点从 `/data` 更改为 `/var/lib/gitea` diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/installation/with-docker.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/installation/with-docker.md index fcaff1c1..77ac6ab2 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/installation/with-docker.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/installation/with-docker.md @@ -264,7 +264,9 @@ MySQL 或 PostgreSQL 容器将需要分别创建。 ## 升级 +:::warning :exclamation::exclamation: **确保已将数据卷到 Docker 容器外部的某个位置** :exclamation::exclamation: +::: 要将安装升级到最新版本： diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/usage/repo-mirror.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/usage/repo-mirror.md index b74a1b62..eab8329f 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/usage/repo-mirror.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/usage/repo-mirror.md @@ -39,7 +39,9 @@ menu: 现在，该仓库会定期从远程仓库进行镜像。您可以通过在仓库设置中选择“立即同步”来强制进行同步。 +:::warning :exclamation::exclamation: **注意：**您只能为尚不存在于您的实例上的仓库设置拉取镜像。一旦仓库创建成功，您就无法再将其转换为拉取镜像。:exclamation::exclamation: +::: ## 推送到远程仓库 @@ -52,7 +54,9 @@ menu: 该仓库现在会定期镜像到远程仓库。您可以通过选择**立即同步**来强制同步。如果出现错误，会显示一条消息帮助您解决问题。 +:::warning :exclamation::exclamation: **注意：** 这将强制推送到远程仓库。这将覆盖远程仓库中的任何更改！ :exclamation::exclamation: +::: ### 从 Gitea 向 GitHub 设置推送镜像 diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/usage/webhooks.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/usage/webhooks.md index dfc70994..c710ac8f 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/usage/webhooks.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-1.22/usage/webhooks.md @@ -37,7 +37,7 @@ Gitea支持用于仓库事件的Webhooks。这可以在仓库管理员在设置 以下是 Gitea 将发送给 payload URL的事件信息示例： -``` +```php X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 X-GitHub-Event: push X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 @@ -131,7 +131,7 @@ X-Gitea-Event: push 现在在你的服务器上创建 php 文件 webhook.php。 -``` +```php 5.6. Gitea is unable to check this. +- `CHARSET`: **utf8mb4**: For MySQL only, either "utf8" or "utf8mb4". + + :::note + For "utf8mb4" you must use MySQL InnoDB > 5.6. Gitea is unable to check this. + ::: + - `PATH`: **data/gitea.db**: For SQLite3 only, the database file path. - `LOG_SQL`: **true**: Log the executed SQL. - `DB_RETRIES`: **10**: How many ORM init / DB connect attempts allowed. @@ -556,13 +567,17 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o Number of trusted proxy count. Set to zero to not use these headers. - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all. - `DISABLE_GIT_HOOKS`: **true**: Set to `false` to enable users with Git Hook privilege to create custom Git Hooks. - WARNING: Custom Git Hooks can be used to perform arbitrary code execution on the host operating system. + + :warning + Custom Git Hooks can be used to perform arbitrary code execution on the host operating system. This enables the users to access and modify this config file and the Gitea database and interrupt the Gitea service. By modifying the Gitea database, users can gain Gitea administrator privileges. It also enables them to access other resources available to the user on the operating system that is running the Gitea instance and perform arbitrary actions in the name of the Gitea OS user. This maybe harmful to you website or your operating system. Setting this to true does not change existing hooks in git repos; adjust it before if necessary. + ::: + - `DISABLE_WEBHOOKS`: **false**: Set to `true` to disable webhooks feature. - `ONLY_ALLOW_PUSH_IF_GITEA_ENVIRONMENT_SET`: **true**: Set to `false` to allow local users to push to gitea-repositories without setting up the Gitea environment. This is not recommended and if you want local users to push to Gitea repositories you should set the environment appropriately. - `IMPORT_LOCAL_PATHS`: **false**: Set to `false` to prevent all users (including admin) from importing local path on server. @@ -638,8 +653,12 @@ Certain queues have defaults that override the defaults set in `[queue]` (this o - `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create accounts for users. - `REQUIRE_EXTERNAL_REGISTRATION_PASSWORD`: **false**: Enable this to force externally created - accounts (via GitHub, OpenID Connect, etc) to create a password. Warning: enabling this will - decrease security, so you should only enable it if you know what you're doing. + accounts (via GitHub, OpenID Connect, etc) to create a password. + + :::warning + Enabling this will decrease security, so you should only enable it if you know what you're doing. + ::: + - `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page or to use API. - `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when something happens, like creating issues. Requires `Mailer` to be enabled. @@ -1222,7 +1241,9 @@ Task queue configuration has been moved to `queue.task`. However, the below conf - `SHARE_USER_STATISTICS`: **true**: Enable/Disable user statistics for nodeinfo if federation is enabled - `MAX_SIZE`: **4**: Maximum federation request and response size (MB) - WARNING: Changing the settings below can break federation. + :::warning + Changing the settings below can break federation. + ::: - `ALGORITHMS`: **rsa-sha256, rsa-sha512, ed25519**: HTTP signature algorithms - `DIGEST_ALGORITHM`: **SHA-256**: HTTP signature digest algorithm diff --git a/versioned_docs/version-1.19/administration/customizing-gitea.md b/versioned_docs/version-1.19/administration/customizing-gitea.md index 24c689ed..b1c1ef9c 100644 --- a/versioned_docs/version-1.19/administration/customizing-gitea.md +++ b/versioned_docs/version-1.19/administration/customizing-gitea.md @@ -44,7 +44,9 @@ is set under the "Configuration" tab on the site administration page. - [List of Environment Variables](https://docs.gitea.io/en-us/environment-variables/) -**Note:** Gitea must perform a full restart to see configuration changes. +:::note +Gitea must perform a full restart to see configuration changes. +::: ## Serving custom public files @@ -270,7 +272,9 @@ Google Analytics, Matomo (previously Piwik), and other analytics services can be Place custom files in corresponding sub-folder under `custom/options`. -**NOTE:** The files should not have a file extension, e.g. `Labels` rather than `Labels.txt` +:::note +The files should not have a file extension, e.g. `Labels` rather than `Labels.txt` +::: ### gitignores @@ -306,7 +310,7 @@ Gitea's default locale files can be found in the [`options/locale`](https://gith To add a completely new locale, as well as placing the file in the above location, you will need to add the new lang and name to the `[i18n]` section in your `app.ini`. Keep in mind that Gitea will use those settings as **overrides**, so if you want to keep the other languages as well you will need to copy/paste the default values and add your own to them. -``` +```ini title="app.ini" [i18n] LANGS = en-US,foo-BAR NAMES = English,FooBar @@ -320,14 +324,16 @@ Locales may change between versions, so keeping track of your customized locales To add a custom Readme, add a markdown formatted file (without an `.md` extension) to `$GITEA_CUSTOM/options/readme` -**NOTE:** readme templates support **variable expansion**. +:::note +Readme templates support **variable expansion**. currently there are `{Name}` (name of repository), `{Description}`, `{CloneURL.SSH}`, `{CloneURL.HTTPS}` and `{OwnerName}` +::: ### Reactions To change reaction emoji's you can set allowed reactions at app.ini -``` +```ini title="app.ini" [ui] REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes ``` diff --git a/versioned_docs/version-1.19/administration/git-lfs-support.md b/versioned_docs/version-1.19/administration/git-lfs-support.md index 3156d801..d31154d6 100644 --- a/versioned_docs/version-1.19/administration/git-lfs-support.md +++ b/versioned_docs/version-1.19/administration/git-lfs-support.md @@ -27,4 +27,6 @@ LFS_START_SERVER = true PATH = /home/gitea/data/lfs ``` -**Note**: LFS server support needs at least Git v2.1.2 installed on the server +:::note +LFS server support needs at least Git v2.1.2 installed on the server +::: diff --git a/versioned_docs/version-1.19/administration/https-support.md b/versioned_docs/version-1.19/administration/https-support.md index 878240c7..07f3565a 100644 --- a/versioned_docs/version-1.19/administration/https-support.md +++ b/versioned_docs/version-1.19/administration/https-support.md @@ -95,4 +95,6 @@ After that, enable HTTPS by following one of these guides: - [apache2/httpd](https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html) - [caddy](https://caddyserver.com/docs/tls) -Note: 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. +:::note +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. +::: diff --git a/versioned_docs/version-1.19/administration/reverse-proxies.md b/versioned_docs/version-1.19/administration/reverse-proxies.md index fe0b97b0..c937bf94 100644 --- a/versioned_docs/version-1.19/administration/reverse-proxies.md +++ b/versioned_docs/version-1.19/administration/reverse-proxies.md @@ -171,7 +171,9 @@ In case you already have a site, and you want Gitea to share the domain name, yo 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`. +:::note +The following Apache HTTPD mods must be enabled: `proxy`, `proxy_http`. +::: ## Caddy diff --git a/versioned_docs/version-1.19/contributing/guidelines-backend.md b/versioned_docs/version-1.19/contributing/guidelines-backend.md index 2ead40d0..a44be69f 100644 --- a/versioned_docs/version-1.19/contributing/guidelines-backend.md +++ b/versioned_docs/version-1.19/contributing/guidelines-backend.md @@ -56,7 +56,7 @@ Since Golang doesn't support import cycles, we have to decide the package depend 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. -**NOTICE** +:::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. @@ -89,6 +89,8 @@ func UpdateIssue(ctx context.Context, repoID int64) error { } ``` +::: + ### Package Name For the top level package, use a plural as package name, i.e. `services`, `models`, for sub packages, use singular, diff --git a/versioned_docs/version-1.19/development/hacking-on-gitea.md b/versioned_docs/version-1.19/development/hacking-on-gitea.md index 622cc551..29653e42 100644 --- a/versioned_docs/version-1.19/development/hacking-on-gitea.md +++ b/versioned_docs/version-1.19/development/hacking-on-gitea.md @@ -30,17 +30,21 @@ Next, [install Node.js with npm](https://nodejs.org/en/download/) which is required to build the JavaScript and CSS files. The minimum supported Node.js version is @minNodeVersion@ and the latest LTS version is recommended. -**Note**: When executing make tasks that require external tools, like +:::note +When executing make tasks that require external tools, like `make watch-backend`, Gitea will automatically download and build these as necessary. To be able to use these you must have the `"$GOPATH"/bin` directory on the executable path. If you don't add the go bin directory to the executable path you will have to manage this yourself. +::: -**Note 2**: Go version @minGoVersion@ or higher is required. +:::note +Go version @minGoVersion@ or higher is required. Gitea uses `gofmt` to format source code. However, the results of `gofmt` can differ by the version of `go`. Therefore it is recommended to install the version of Go that our continuous integration is running. As of last update, the Go version should be @goVersion@. +::: ## Installing Make @@ -77,7 +81,9 @@ One of these three distributions of Make will run on Windows: - To compile Gitea with CGO_ENABLED (eg: SQLite3), you might need to use [tdm-gcc](https://jmeubank.github.io/tdm-gcc/) instead of MSYS2 gcc, because MSYS2 gcc headers lack some Windows-only CRT functions like `_beginthread`. - [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make` -**Note**: If you are attempting to build using make with Windows Command Prompt, you may run into issues. The above prompts (Git bash, or MinGW) are recommended, however if you only have command prompt (or potentially PowerShell) you can set environment variables using the [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) command, e.g. `set TAGS=bindata`. +:::note +If you are attempting to build using make with Windows Command Prompt, you may run into issues. The above prompts (Git bash, or MinGW) are recommended, however if you only have command prompt (or potentially PowerShell) you can set environment variables using the [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) command, e.g. `set TAGS=bindata`. +::: ## Downloading and cloning the Gitea source code @@ -251,8 +257,9 @@ server will check that this has been done using: make swagger-check ``` -**Note**: Please note you should use the Swagger 2.0 documentation, not the -OpenAPI 3 documentation. +:::note +Please note you should use the Swagger 2.0 documentation, not the OpenAPI 3 documentation. +::: ### Creating new configuration options diff --git a/versioned_docs/version-1.19/development/oauth2-provider.md b/versioned_docs/version-1.19/development/oauth2-provider.md index 1d21f3c7..177ae2b8 100644 --- a/versioned_docs/version-1.19/development/oauth2-provider.md +++ b/versioned_docs/version-1.19/development/oauth2-provider.md @@ -82,7 +82,9 @@ For public clients, a redirect URI of a loopback IP address such as `http://127. ## Example -**Note:** This example does not use PKCE. +:::note +This example does not use PKCE. +::: 1. Redirect to user to the authorization endpoint in order to get their consent for accessing the resources: diff --git a/versioned_docs/version-1.19/help/faq.md b/versioned_docs/version-1.19/help/faq.md index 1fa65f7b..100acf7e 100644 --- a/versioned_docs/version-1.19/help/faq.md +++ b/versioned_docs/version-1.19/help/faq.md @@ -23,7 +23,9 @@ For more help resources, check all [Support Options](help/seek-help.md). 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. @@ -163,7 +165,9 @@ You can configure `EMAIL_DOMAIN_WHITELIST` or `EMAIL_DOMAIN_BLOCKLIST` in your a 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 diff --git a/versioned_docs/version-1.19/help/seek-help.md b/versioned_docs/version-1.19/help/seek-help.md index f6c98448..487c713b 100644 --- a/versioned_docs/version-1.19/help/seek-help.md +++ b/versioned_docs/version-1.19/help/seek-help.md @@ -19,7 +19,9 @@ menu: - [Discord](https://discord.gg/Gitea) - [Discourse Forum](https://discourse.gitea.io/) -**NOTE:** When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need: +:::note +When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need: +::: 1. Your `app.ini` (with any sensitive data scrubbed as necessary). 2. The Gitea logs, and any other appropriate log files for the situation. diff --git a/versioned_docs/version-1.19/installation/database-preparation.md b/versioned_docs/version-1.19/installation/database-preparation.md index 189d6b96..e1aa720e 100644 --- a/versioned_docs/version-1.19/installation/database-preparation.md +++ b/versioned_docs/version-1.19/installation/database-preparation.md @@ -19,7 +19,9 @@ You need a database to use Gitea. Gitea supports PostgreSQL (>=10), MySQL (>=5.7 Database instance can be on same machine as Gitea (local database setup), or on different machine (remote database). -Note: All steps below requires that the database engine of your choice is installed on your system. For remote database setup, install the server application on database instance and client program on your Gitea server. The client program is used to test connection to the database from Gitea server, while Gitea itself use database driver provided by Go to accomplish the same thing. In addition, make sure you use same engine version for both server and client for some engine features to work. For security reason, protect `root` (MySQL) or `postgres` (PostgreSQL) database superuser with secure password. The steps assumes that you run Linux for both database and Gitea servers. +:::note +All steps below requires that the database engine of your choice is installed on your system. For remote database setup, install the server application on database instance and client program on your Gitea server. The client program is used to test connection to the database from Gitea server, while Gitea itself use database driver provided by Go to accomplish the same thing. In addition, make sure you use same engine version for both server and client for some engine features to work. For security reason, protect `root` (MySQL) or `postgres` (PostgreSQL) database superuser with secure password. The steps assumes that you run Linux for both database and Gitea servers. +::: ## MySQL diff --git a/versioned_docs/version-1.19/installation/from-binary.md b/versioned_docs/version-1.19/installation/from-binary.md index b4ad9eec..fedb11e5 100644 --- a/versioned_docs/version-1.19/installation/from-binary.md +++ b/versioned_docs/version-1.19/installation/from-binary.md @@ -60,8 +60,10 @@ despite warnings like `This key is not certified with a trusted signature!`. ## Recommended server configuration -**NOTE:** Many of the following directories can be configured using [Environment Variables](administration/environment-variables.md) as well! +:::note +Many of the following directories can be configured using [Environment Variables](administration/environment-variables.md) as well! Of note, configuring `GITEA_WORK_DIR` will tell Gitea where to base its working directory, as well as ease installation. +::: ### Prepare environment @@ -95,8 +97,10 @@ chown root:git /etc/gitea chmod 770 /etc/gitea ``` -> **NOTE:** `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using: -> +:::note +> `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using: +::: + > ```sh > chmod 750 /etc/gitea > chmod 640 /etc/gitea/app.ini @@ -113,7 +117,9 @@ See the [command line documentation](administration/command-line.md) for informa ### Configure Gitea's working directory -**NOTE:** If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory. +:::note +If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory. +::: ```sh export GITEA_WORK_DIR=/var/lib/gitea/ @@ -169,7 +175,9 @@ To restart your Gitea instance, we recommend to use SIGHUP signal. If you know y To gracefully stop the Gitea instance, a simple `kill $GITEA_PID` or `killall gitea` is enough. -**NOTE:** We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.) +:::note +We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.) +::: See below for troubleshooting instructions to repair broken repositories after an update of your Gitea version. diff --git a/versioned_docs/version-1.19/installation/from-source.md b/versioned_docs/version-1.19/installation/from-source.md index 1de52759..8baf7bb8 100644 --- a/versioned_docs/version-1.19/installation/from-source.md +++ b/versioned_docs/version-1.19/installation/from-source.md @@ -25,15 +25,19 @@ Next, [install Node.js with npm](https://nodejs.org/en/download/) which is required to build the JavaScript and CSS files. The minimum supported Node.js version is @minNodeVersion@ and the latest LTS version is recommended. -**Note**: When executing make tasks that require external tools, like +:::note +When executing make tasks that require external tools, like `make misspell-check`, Gitea will automatically download and build these as necessary. To be able to use these, you must have the `"$GOPATH/bin"` directory on the executable path. If you don't add the go bin directory to the executable path, you will have to manage this yourself. +::: -**Note 2**: Go version @minGoVersion@ or higher is required. However, it is recommended to +:::note +Go version @minGoVersion@ or higher is required. However, it is recommended to obtain the same version as our continuous integration, see the advice given in [Hacking on Gitea](development/hacking-on-gitea.md) +::: ## Download diff --git a/versioned_docs/version-1.19/installation/on-kubernetes.md b/versioned_docs/version-1.19/installation/on-kubernetes.md index c66674bb..769c750b 100644 --- a/versioned_docs/version-1.19/installation/on-kubernetes.md +++ b/versioned_docs/version-1.19/installation/on-kubernetes.md @@ -44,7 +44,7 @@ Gitea comes with a health check endpoint `/api/healthz`, you can configure it in a successful health check response will respond with http code `200`, here's example: -``` +```json HTTP/1.1 200 OK { diff --git a/versioned_docs/version-1.19/installation/with-docker-rootless.md b/versioned_docs/version-1.19/installation/with-docker-rootless.md index 33a5d551..5ca1b687 100644 --- a/versioned_docs/version-1.19/installation/with-docker-rootless.md +++ b/versioned_docs/version-1.19/installation/with-docker-rootless.md @@ -240,8 +240,10 @@ started properly. Logs can be viewed with `docker-compose logs`. To shut down the setup, execute `docker-compose down`. This will stop and kill the containers. The volumes will still exist. -Notice: if using a non-3000 port on http, change app.ini to match +:::note +If using a non-3000 port on http, change app.ini to match `LOCAL_ROOT_URL = http://localhost:3000/`. +::: ## Install @@ -250,7 +252,7 @@ favorite browser to finalize the installation. Visit http://server-ip:3000 and f installation wizard. If the database was started with the `docker-compose` setup as documented above, please note that `db` must be used as the database hostname. -# Customization +## Customization Customization files described [here](https://docs.gitea.io/en-us/customizing-gitea/) should be placed in `/var/lib/gitea/custom` directory. If using host volumes, it's quite easy to access these @@ -258,13 +260,15 @@ files; for named volumes, this is done through another container or by direct ac `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea`. The configuration file will be saved at `/etc/gitea/app.ini` after the installation. -# Upgrading +## Upgrading +:::warning :exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: +::: To upgrade your installation to the latest release: -``` +```bash # Edit `docker-compose.yml` to update the version, if you have one specified # Pull new images docker-compose pull @@ -272,7 +276,7 @@ docker-compose pull docker-compose up -d ``` -# Upgrading from standard image +## Upgrading from standard image - Backup your setup - Change volume mountpoint from /data to /var/lib/gitea diff --git a/versioned_docs/version-1.19/installation/with-docker.md b/versioned_docs/version-1.19/installation/with-docker.md index 7e1f92f3..9bda8f01 100644 --- a/versioned_docs/version-1.19/installation/with-docker.md +++ b/versioned_docs/version-1.19/installation/with-docker.md @@ -241,8 +241,10 @@ started properly. Logs can be viewed with `docker-compose logs`. To shut down the setup, execute `docker-compose down`. This will stop and kill the containers. The volumes will still exist. -Notice: if using a non-3000 port on http, change app.ini to match +:::note +If using a non-3000 port on http, change app.ini to match `LOCAL_ROOT_URL = http://localhost:3000/`. +::: ## Installation @@ -267,7 +269,9 @@ files; for named volumes, this is done through another container or by direct ac ## Upgrading +:::warning :exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: +::: To upgrade your installation to the latest release: diff --git a/versioned_docs/version-1.19/packages/container.md b/versioned_docs/version-1.19/packages/container.md index f082e15c..91974771 100644 --- a/versioned_docs/version-1.19/packages/container.md +++ b/versioned_docs/version-1.19/packages/container.md @@ -47,7 +47,9 @@ For example, these are all valid image names for the owner `testuser`: `gitea.example.com/testuser/my/image` -**NOTE:** The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. +:::note +The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. +::: ## Push an image diff --git a/versioned_docs/version-1.19/usage/authentication.md b/versioned_docs/version-1.19/usage/authentication.md index ec8d1b35..51de1ee4 100644 --- a/versioned_docs/version-1.19/usage/authentication.md +++ b/versioned_docs/version-1.19/usage/authentication.md @@ -345,4 +345,6 @@ 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. -Notice: Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests. +:::note +Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests. +::: diff --git a/versioned_docs/version-1.19/usage/repo-mirror.md b/versioned_docs/version-1.19/usage/repo-mirror.md index 9a101800..358ff887 100644 --- a/versioned_docs/version-1.19/usage/repo-mirror.md +++ b/versioned_docs/version-1.19/usage/repo-mirror.md @@ -37,7 +37,9 @@ For an existing remote repository, you can set up pull mirroring as follows: The repository now gets mirrored periodically from the remote repository. You can force a sync by selecting **Synchronize Now** in the repository settings. -:exclamation::exclamation: **NOTE:** You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation: +:::warning +:exclamation::exclamation: You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation: +::: ## Pushing to a remote repository @@ -50,7 +52,9 @@ For an existing repository, you can set up push mirroring as follows: The repository now gets mirrored periodically to the remote repository. You can force a sync by selecting **Synchronize Now**. In case of an error a message displayed to help you resolve it. -:exclamation::exclamation: **NOTE:** This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation: +:::warning +:exclamation::exclamation: This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation: +::: ### Setting up a push mirror from Gitea to GitHub diff --git a/versioned_docs/version-1.19/usage/template-repositories.md b/versioned_docs/version-1.19/usage/template-repositories.md index 49a525ec..1ad81e70 100644 --- a/versioned_docs/version-1.19/usage/template-repositories.md +++ b/versioned_docs/version-1.19/usage/template-repositories.md @@ -39,7 +39,9 @@ a/b/c/d.json **.[bB][aA][tT] ``` -**NOTE:** The `template` file will be removed from the `.gitea` directory when a repository is generated from the template. +:::note +The `template` file will be removed from the `.gitea` directory when a repository is generated from the template. +::: ## Variable Expansion diff --git a/versioned_docs/version-1.19/usage/webhooks.md b/versioned_docs/version-1.19/usage/webhooks.md index 8d8e1caa..f4ffed3f 100644 --- a/versioned_docs/version-1.19/usage/webhooks.md +++ b/versioned_docs/version-1.19/usage/webhooks.md @@ -32,12 +32,14 @@ All event pushes are POST requests. The methods currently supported are: ### Event information -**WARNING**: The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 +:::warning +The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 +::: The following is an example of event information that will be sent by Gitea to a Payload URL: -``` +```http X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 X-GitHub-Event: push X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 @@ -131,7 +133,7 @@ In your repository Settings, under Webhooks, Setup a Gitea webhook as follows: Now on your server create the php file webhook.php -``` +```php 5.6. Gitea is unable to check this. +- `CHARSET`: **utf8mb4**: For MySQL only, either "utf8" or "utf8mb4". + + :::note + For "utf8mb4" you must use MySQL InnoDB > 5.6. Gitea is unable to check this. + ::: + - `PATH`: **data/gitea.db**: For SQLite3 only, the database file path. - `LOG_SQL`: **false**: Log the executed SQL. - `DB_RETRIES`: **10**: How many ORM init / DB connect attempts allowed. @@ -527,13 +538,17 @@ And the following unique queues: Number of trusted proxy count. Set to zero to not use these headers. - `REVERSE_PROXY_TRUSTED_PROXIES`: **127.0.0.0/8,::1/128**: List of IP addresses and networks separated by comma of trusted proxy servers. Use `*` to trust all. - `DISABLE_GIT_HOOKS`: **true**: Set to `false` to enable users with Git Hook privilege to create custom Git Hooks. - WARNING: Custom Git Hooks can be used to perform arbitrary code execution on the host operating system. + + :::warning + Custom Git Hooks can be used to perform arbitrary code execution on the host operating system. This enables the users to access and modify this config file and the Gitea database and interrupt the Gitea service. By modifying the Gitea database, users can gain Gitea administrator privileges. It also enables them to access other resources available to the user on the operating system that is running the Gitea instance and perform arbitrary actions in the name of the Gitea OS user. This maybe harmful to you website or your operating system. Setting this to true does not change existing hooks in git repos; adjust it before if necessary. + ::: + - `DISABLE_WEBHOOKS`: **false**: Set to `true` to disable webhooks feature. - `ONLY_ALLOW_PUSH_IF_GITEA_ENVIRONMENT_SET`: **true**: Set to `false` to allow local users to push to gitea-repositories without setting up the Gitea environment. This is not recommended and if you want local users to push to Gitea repositories you should set the environment appropriately. - `IMPORT_LOCAL_PATHS`: **false**: Set to `false` to prevent all users (including admin) from importing local path on server. @@ -609,8 +624,12 @@ And the following unique queues: - `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create accounts for users. - `REQUIRE_EXTERNAL_REGISTRATION_PASSWORD`: **false**: Enable this to force externally created - accounts (via GitHub, OpenID Connect, etc) to create a password. Warning: enabling this will - decrease security, so you should only enable it if you know what you're doing. + accounts (via GitHub, OpenID Connect, etc) to create a password. + + :::warning + Enabling this will decrease security, so you should only enable it if you know what you're doing. + ::: + - `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page or to use API. - `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when something happens, like creating issues. Requires `Mailer` to be enabled. @@ -1189,7 +1208,9 @@ Task queue configuration has been moved to `queue.task`. However, the below conf - `SHARE_USER_STATISTICS`: **true**: Enable/Disable user statistics for nodeinfo if federation is enabled - `MAX_SIZE`: **4**: Maximum federation request and response size (MB) - WARNING: Changing the settings below can break federation. + :::warning + Changing the settings below can break federation. + ::: - `ALGORITHMS`: **rsa-sha256, rsa-sha512, ed25519**: HTTP signature algorithms - `DIGEST_ALGORITHM`: **SHA-256**: HTTP signature digest algorithm diff --git a/versioned_docs/version-1.20/administration/customizing-gitea.md b/versioned_docs/version-1.20/administration/customizing-gitea.md index 66feaaf2..dbe5ea46 100644 --- a/versioned_docs/version-1.20/administration/customizing-gitea.md +++ b/versioned_docs/version-1.20/administration/customizing-gitea.md @@ -46,7 +46,9 @@ is set under the "Configuration" tab on the site administration page. - [List of Environment Variables](administration/environment-variables.md) -**Note:** Gitea must perform a full restart to see configuration changes. +:::note +Gitea must perform a full restart to see configuration changes. +::: ## Serving custom public files @@ -272,7 +274,9 @@ Google Analytics, Matomo (previously Piwik), and other analytics services can be Place custom files in corresponding sub-folder under `custom/options`. -**NOTE:** The files should not have a file extension, e.g. `Labels` rather than `Labels.txt` +:::note +The files should not have a file extension, e.g. `Labels` rather than `Labels.txt` +::: ### gitignores @@ -324,7 +328,7 @@ Gitea's default locale files can be found in the [`options/locale`](https://gith To add a completely new locale, as well as placing the file in the above location, you will need to add the new lang and name to the `[i18n]` section in your `app.ini`. Keep in mind that Gitea will use those settings as **overrides**, so if you want to keep the other languages as well you will need to copy/paste the default values and add your own to them. -``` +```ini title="app.ini" [i18n] LANGS = en-US,foo-BAR NAMES = English,FooBar @@ -338,14 +342,16 @@ Locales may change between versions, so keeping track of your customized locales To add a custom Readme, add a markdown formatted file (without an `.md` extension) to `$GITEA_CUSTOM/options/readme` -**NOTE:** readme templates support **variable expansion**. +:::note +Readme templates support **variable expansion**. currently there are `{Name}` (name of repository), `{Description}`, `{CloneURL.SSH}`, `{CloneURL.HTTPS}` and `{OwnerName}` +::: ### Reactions To change reaction emoji's you can set allowed reactions at app.ini -``` +```ini title="app.ini" [ui] REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes ``` diff --git a/versioned_docs/version-1.20/administration/email-setup.md b/versioned_docs/version-1.20/administration/email-setup.md index c4b24e7d..67950907 100644 --- a/versioned_docs/version-1.20/administration/email-setup.md +++ b/versioned_docs/version-1.20/administration/email-setup.md @@ -23,9 +23,11 @@ Gitea has mailer functionality for sending transactional emails (such as registr Use `sendmail` command as mailer. -Note: For use in the official Gitea Docker image, please configure with the SMTP version (see the following section). +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. +:::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. +::: ```ini title="app.ini" [mailer] @@ -57,14 +59,18 @@ 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](administration/config-cheat-sheet.md) -Please note: authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through: +:::note +Authentication is only supported when the SMTP server communication is encrypted with TLS or `HOST=localhost`. TLS encryption can be through: +::: - STARTTLS (also known as Opportunistic TLS) via port 587. Initial connection is done over cleartext, but then be upgraded over TLS if the server supports it. - SMTPS connection (SMTP over TLS) via the default port 465. Connection to the server use TLS from the beginning. - Forced SMTPS connection with `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. -Note that Implicit TLS is recommended by [RFC8314](https://tools.ietf.org/html/rfc8314#section-3) since 2018. +:::note +Implicit TLS is recommended by [RFC8314](https://tools.ietf.org/html/rfc8314#section-3) since 2018. +::: ### Gmail @@ -84,5 +90,7 @@ PROTOCOL = smtps ; Gitea >= 1.19.0 ; IS_TLS_ENABLED = true ; Gitea < 1.19.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 +:::note +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. +::: diff --git a/versioned_docs/version-1.20/administration/git-lfs-support.md b/versioned_docs/version-1.20/administration/git-lfs-support.md index d2c55a29..79e45572 100644 --- a/versioned_docs/version-1.20/administration/git-lfs-support.md +++ b/versioned_docs/version-1.20/administration/git-lfs-support.md @@ -29,4 +29,6 @@ LFS_START_SERVER = true PATH = /home/gitea/data/lfs ``` -**Note**: LFS server support needs at least Git v2.1.2 installed on the server +:::note +LFS server support needs at least Git v2.1.2 installed on the server +::: diff --git a/versioned_docs/version-1.20/contributing/guidelines-backend.md b/versioned_docs/version-1.20/contributing/guidelines-backend.md index 084b3886..94e83d18 100644 --- a/versioned_docs/version-1.20/contributing/guidelines-backend.md +++ b/versioned_docs/version-1.20/contributing/guidelines-backend.md @@ -58,8 +58,7 @@ Since Golang doesn't support import cycles, we have to decide the package depend 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. -**NOTICE** - +:::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, @@ -90,6 +89,7 @@ func UpdateIssue(ctx context.Context, repoID int64) error { // ... } ``` +::: ### Package Name diff --git a/versioned_docs/version-1.20/development/hacking-on-gitea.md b/versioned_docs/version-1.20/development/hacking-on-gitea.md index e8d24ca7..2abc4b7a 100644 --- a/versioned_docs/version-1.20/development/hacking-on-gitea.md +++ b/versioned_docs/version-1.20/development/hacking-on-gitea.md @@ -32,17 +32,21 @@ Next, [install Node.js with npm](https://nodejs.org/en/download/) which is required to build the JavaScript and CSS files. The minimum supported Node.js version is @minNodeVersion@ and the latest LTS version is recommended. -**Note**: When executing make tasks that require external tools, like +:::note +When executing make tasks that require external tools, like `make watch-backend`, Gitea will automatically download and build these as necessary. To be able to use these you must have the `"$GOPATH"/bin` directory on the executable path. If you don't add the go bin directory to the executable path you will have to manage this yourself. +::: -**Note 2**: Go version @minGoVersion@ or higher is required. +:::note +Go version @minGoVersion@ or higher is required. Gitea uses `gofmt` to format source code. However, the results of `gofmt` can differ by the version of `go`. Therefore it is recommended to install the version of Go that our continuous integration is running. As of last update, the Go version should be @goVersion@. +::: ## Installing Make @@ -79,7 +83,9 @@ One of these three distributions of Make will run on Windows: - To compile Gitea with CGO_ENABLED (eg: SQLite3), you might need to use [tdm-gcc](https://jmeubank.github.io/tdm-gcc/) instead of MSYS2 gcc, because MSYS2 gcc headers lack some Windows-only CRT functions like `_beginthread`. - [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make` -**Note**: If you are attempting to build using make with Windows Command Prompt, you may run into issues. The above prompts (Git bash, or MinGW) are recommended, however if you only have command prompt (or potentially PowerShell) you can set environment variables using the [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) command, e.g. `set TAGS=bindata`. +:::note +If you are attempting to build using make with Windows Command Prompt, you may run into issues. The above prompts (Git bash, or MinGW) are recommended, however if you only have command prompt (or potentially PowerShell) you can set environment variables using the [set](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1) command, e.g. `set TAGS=bindata`. +::: ## Downloading and cloning the Gitea source code @@ -253,8 +259,9 @@ server will check that this has been done using: make swagger-check ``` -**Note**: Please note you should use the Swagger 2.0 documentation, not the -OpenAPI 3 documentation. +:::note +Please note you should use the Swagger 2.0 documentation, not the OpenAPI 3 documentation. +::: ### Creating new configuration options diff --git a/versioned_docs/version-1.20/development/oauth2-provider.md b/versioned_docs/version-1.20/development/oauth2-provider.md index d1d8252c..33dbf60f 100644 --- a/versioned_docs/version-1.20/development/oauth2-provider.md +++ b/versioned_docs/version-1.20/development/oauth2-provider.md @@ -88,7 +88,9 @@ For public clients, a redirect URI of a loopback IP address such as `http://127. ### Confidential client -**Note:** This example does not use PKCE. +:::note +This example does not use PKCE. +::: 1. Redirect the user to the authorization endpoint in order to get their consent for accessing the resources: diff --git a/versioned_docs/version-1.20/help/faq.md b/versioned_docs/version-1.20/help/faq.md index 83a61f2c..2fa6de7a 100644 --- a/versioned_docs/version-1.20/help/faq.md +++ b/versioned_docs/version-1.20/help/faq.md @@ -161,7 +161,9 @@ You can configure `EMAIL_DOMAIN_WHITELIST` or `EMAIL_DOMAIN_BLOCKLIST` in your a 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 diff --git a/versioned_docs/version-1.20/help/support.md b/versioned_docs/version-1.20/help/support.md index db735b81..49567540 100644 --- a/versioned_docs/version-1.20/help/support.md +++ b/versioned_docs/version-1.20/help/support.md @@ -30,7 +30,9 @@ menu: If you found a bug, please [create an issue on GitHub](https://github.com/go-gitea/gitea/issues). -**NOTE:** When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need: +:::note +When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need: +::: 1. Your `app.ini` (with any sensitive data scrubbed as necessary). 2. Any error messages you are seeing. diff --git a/versioned_docs/version-1.20/installation/from-binary.md b/versioned_docs/version-1.20/installation/from-binary.md index 88f82be3..4688d699 100644 --- a/versioned_docs/version-1.20/installation/from-binary.md +++ b/versioned_docs/version-1.20/installation/from-binary.md @@ -62,8 +62,10 @@ despite warnings like `This key is not certified with a trusted signature!`. ## Recommended server configuration -**NOTE:** Many of the following directories can be configured using [Environment Variables](administration/environment-variables.md) as well! +:::note +Many of the following directories can be configured using [Environment Variables](administration/environment-variables.md) as well! Of note, configuring `GITEA_WORK_DIR` will tell Gitea where to base its working directory, as well as ease installation. +::: ### Prepare environment @@ -109,8 +111,10 @@ chown root:git /etc/gitea chmod 770 /etc/gitea ``` -> **NOTE:** `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using: -> +:::note +> `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using: +::: + > ```sh > chmod 750 /etc/gitea > chmod 640 /etc/gitea/app.ini @@ -127,7 +131,9 @@ See the [command line documentation](administration/command-line.md) for informa ### Configure Gitea's working directory -**NOTE:** If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory. +:::note +If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory. +::: ```sh export GITEA_WORK_DIR=/var/lib/gitea/ @@ -183,7 +189,9 @@ To restart your Gitea instance, we recommend to use SIGHUP signal. If you know y To gracefully stop the Gitea instance, a simple `kill $GITEA_PID` or `killall gitea` is enough. -**NOTE:** We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.) +:::note +We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.) +::: See below for troubleshooting instructions to repair broken repositories after an update of your Gitea version. diff --git a/versioned_docs/version-1.20/installation/from-source.md b/versioned_docs/version-1.20/installation/from-source.md index 9d5a9cae..54672c36 100644 --- a/versioned_docs/version-1.20/installation/from-source.md +++ b/versioned_docs/version-1.20/installation/from-source.md @@ -27,15 +27,19 @@ Next, [install Node.js with npm](https://nodejs.org/en/download/) which is required to build the JavaScript and CSS files. The minimum supported Node.js version is @minNodeVersion@ and the latest LTS version is recommended. -**Note**: When executing make tasks that require external tools, like +:::note +When executing make tasks that require external tools, like `make misspell-check`, Gitea will automatically download and build these as necessary. To be able to use these, you must have the `"$GOPATH/bin"` directory on the executable path. If you don't add the go bin directory to the executable path, you will have to manage this yourself. +::: -**Note 2**: Go version @minGoVersion@ or higher is required. However, it is recommended to +:::note +Go version @minGoVersion@ or higher is required. However, it is recommended to obtain the same version as our continuous integration, see the advice given in [Hacking on Gitea](development/hacking-on-gitea.md) +::: ## Download diff --git a/versioned_docs/version-1.20/installation/on-kubernetes.md b/versioned_docs/version-1.20/installation/on-kubernetes.md index 00f2aab2..c9036af1 100644 --- a/versioned_docs/version-1.20/installation/on-kubernetes.md +++ b/versioned_docs/version-1.20/installation/on-kubernetes.md @@ -46,7 +46,7 @@ Gitea comes with a health check endpoint `/api/healthz`, you can configure it in a successful health check response will respond with http code `200`, here's example: -``` +```json HTTP/1.1 200 OK { diff --git a/versioned_docs/version-1.20/installation/with-docker-rootless.md b/versioned_docs/version-1.20/installation/with-docker-rootless.md index 10f12122..df287c55 100644 --- a/versioned_docs/version-1.20/installation/with-docker-rootless.md +++ b/versioned_docs/version-1.20/installation/with-docker-rootless.md @@ -242,8 +242,10 @@ started properly. Logs can be viewed with `docker-compose logs`. To shut down the setup, execute `docker-compose down`. This will stop and kill the containers. The volumes will still exist. -Notice: if using a non-3000 port on http, change app.ini to match +:::note +If using a non-3000 port on http, change app.ini to match `LOCAL_ROOT_URL = http://localhost:3000/`. +::: ## Install @@ -252,7 +254,7 @@ favorite browser to finalize the installation. Visit http://server-ip:3000 and f installation wizard. If the database was started with the `docker-compose` setup as documented above, please note that `db` must be used as the database hostname. -# Customization +## Customization Customization files described [here](administration/customizing-gitea.md) should be placed in `/var/lib/gitea/custom` directory. If using host volumes, it's quite easy to access these @@ -260,13 +262,15 @@ files; for named volumes, this is done through another container or by direct ac `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea`. The configuration file will be saved at `/etc/gitea/app.ini` after the installation. -# Upgrading +## Upgrading +:::warning :exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: +::: To upgrade your installation to the latest release: -``` +```bash # Edit `docker-compose.yml` to update the version, if you have one specified # Pull new images docker-compose pull @@ -274,7 +278,7 @@ docker-compose pull docker-compose up -d ``` -# Upgrading from standard image +## Upgrading from standard image - Backup your setup - Change volume mountpoint from /data to /var/lib/gitea diff --git a/versioned_docs/version-1.20/installation/with-docker.md b/versioned_docs/version-1.20/installation/with-docker.md index e67f5bcc..48fcf44f 100644 --- a/versioned_docs/version-1.20/installation/with-docker.md +++ b/versioned_docs/version-1.20/installation/with-docker.md @@ -243,8 +243,10 @@ started properly. Logs can be viewed with `docker-compose logs`. To shut down the setup, execute `docker-compose down`. This will stop and kill the containers. The volumes will still exist. -Notice: if using a non-3000 port on http, change app.ini to match +:::note +If using a non-3000 port on http, change app.ini to match `LOCAL_ROOT_URL = http://localhost:3000/`. +::: ## Installation @@ -269,7 +271,9 @@ files; for named volumes, this is done through another container or by direct ac ## Upgrading +:::warning :exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: +::: To upgrade your installation to the latest release: diff --git a/versioned_docs/version-1.20/usage/authentication.md b/versioned_docs/version-1.20/usage/authentication.md index 6a6de08d..219236c9 100644 --- a/versioned_docs/version-1.20/usage/authentication.md +++ b/versioned_docs/version-1.20/usage/authentication.md @@ -348,4 +348,6 @@ 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. -Notice: Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests. +:::note +Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests. +::: diff --git a/versioned_docs/version-1.20/usage/multi-factor-authentication.md b/versioned_docs/version-1.20/usage/multi-factor-authentication.md index 30323f6d..9bfa3e8a 100644 --- a/versioned_docs/version-1.20/usage/multi-factor-authentication.md +++ b/versioned_docs/version-1.20/usage/multi-factor-authentication.md @@ -28,8 +28,10 @@ This interface does not support MFA, and trying to use a password normally will If SSH is not an option for Git operations, an access token can be generated within the "Applications" tab of the user settings page. This access token can be used as if it were a password in order to allow the Git CLI to function over HTTP. -> **Warning** - By its very nature, an access token sidesteps the security benefits of MFA. -> It must be kept secure and should only be used as a last resort. +:::warning +By its very nature, an access token sidesteps the security benefits of MFA. +It must be kept secure and should only be used as a last resort. +::: The Gitea API supports providing the relevant TOTP password in the `X-Gitea-OTP` header, as described in [API Usage](development/api-usage.md). This should be used instead of an access token where possible. diff --git a/versioned_docs/version-1.20/usage/packages/container.md b/versioned_docs/version-1.20/usage/packages/container.md index 6be21c2b..14bba0ff 100644 --- a/versioned_docs/version-1.20/usage/packages/container.md +++ b/versioned_docs/version-1.20/usage/packages/container.md @@ -47,7 +47,9 @@ For example, these are all valid image names for the owner `testuser`: `gitea.example.com/testuser/my/image` -**NOTE:** The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. +:::note +The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. +::: ## Push an image diff --git a/versioned_docs/version-1.20/usage/repo-mirror.md b/versioned_docs/version-1.20/usage/repo-mirror.md index 4a657103..279cdfc9 100644 --- a/versioned_docs/version-1.20/usage/repo-mirror.md +++ b/versioned_docs/version-1.20/usage/repo-mirror.md @@ -39,7 +39,9 @@ For an existing remote repository, you can set up pull mirroring as follows: The repository now gets mirrored periodically from the remote repository. You can force a sync by selecting **Synchronize Now** in the repository settings. -:exclamation::exclamation: **NOTE:** You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation: +:::warning +:exclamation::exclamation: You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation: +::: ## Pushing to a remote repository @@ -52,7 +54,9 @@ For an existing repository, you can set up push mirroring as follows: The repository now gets mirrored periodically to the remote repository. You can force a sync by selecting **Synchronize Now**. In case of an error a message displayed to help you resolve it. -:exclamation::exclamation: **NOTE:** This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation: +:::warning +:exclamation::exclamation: This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation: +::: ### Setting up a push mirror from Gitea to GitHub diff --git a/versioned_docs/version-1.20/usage/template-repositories.md b/versioned_docs/version-1.20/usage/template-repositories.md index 66b2d54b..958c84cb 100644 --- a/versioned_docs/version-1.20/usage/template-repositories.md +++ b/versioned_docs/version-1.20/usage/template-repositories.md @@ -41,7 +41,9 @@ a/b/c/d.json **.[bB][aA][tT] ``` -**NOTE:** The `template` file will be removed from the `.gitea` directory when a repository is generated from the template. +:::note +The `template` file will be removed from the `.gitea` directory when a repository is generated from the template. +::: ## Variable Expansion diff --git a/versioned_docs/version-1.20/usage/webhooks.md b/versioned_docs/version-1.20/usage/webhooks.md index 684911f8..3d92e109 100644 --- a/versioned_docs/version-1.20/usage/webhooks.md +++ b/versioned_docs/version-1.20/usage/webhooks.md @@ -34,12 +34,14 @@ All event pushes are POST requests. The methods currently supported are: ### Event information -**WARNING**: The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 +:::warning +The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 +::: The following is an example of event information that will be sent by Gitea to a Payload URL: -``` +```http X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 X-GitHub-Event: push X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 @@ -133,7 +135,7 @@ In your repository Settings, under Webhooks, Setup a Gitea webhook as follows: Now on your server create the php file webhook.php -``` +```php **NOTE:** `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using: -> +:::note +> `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using: +::: + > ```sh > chmod 750 /etc/gitea > chmod 640 /etc/gitea/app.ini @@ -127,7 +131,9 @@ See the [command line documentation](administration/command-line.md) for informa ### Configure Gitea's working directory -**NOTE:** If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory. +:::note +If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory. +::: ```sh export GITEA_WORK_DIR=/var/lib/gitea/ @@ -183,7 +189,9 @@ To restart your Gitea instance, we recommend to use SIGHUP signal. If you know y To gracefully stop the Gitea instance, a simple `kill $GITEA_PID` or `killall gitea` is enough. -**NOTE:** We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.) +:::note +We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.) +::: See below for troubleshooting instructions to repair broken repositories after an update of your Gitea version. diff --git a/versioned_docs/version-1.21/installation/from-source.md b/versioned_docs/version-1.21/installation/from-source.md index e6998ce8..d6513202 100644 --- a/versioned_docs/version-1.21/installation/from-source.md +++ b/versioned_docs/version-1.21/installation/from-source.md @@ -27,9 +27,11 @@ Next, [install Node.js with npm](https://nodejs.org/en/download/) which is required to build the JavaScript and CSS files. The minimum supported Node.js version is @minNodeVersion@ and the latest LTS version is recommended. -**Note**: Go version @minGoVersion@ or higher is required. However, it is recommended to +:::note +Go version @minGoVersion@ or higher is required. However, it is recommended to obtain the same version as our continuous integration, see the advice given in [Hacking on Gitea](development/hacking-on-gitea.md) +::: ## Download diff --git a/versioned_docs/version-1.21/installation/on-kubernetes.md b/versioned_docs/version-1.21/installation/on-kubernetes.md index 00f2aab2..c9036af1 100644 --- a/versioned_docs/version-1.21/installation/on-kubernetes.md +++ b/versioned_docs/version-1.21/installation/on-kubernetes.md @@ -46,7 +46,7 @@ Gitea comes with a health check endpoint `/api/healthz`, you can configure it in a successful health check response will respond with http code `200`, here's example: -``` +```json HTTP/1.1 200 OK { diff --git a/versioned_docs/version-1.21/installation/with-docker-rootless.md b/versioned_docs/version-1.21/installation/with-docker-rootless.md index 5b59098f..452179fc 100644 --- a/versioned_docs/version-1.21/installation/with-docker-rootless.md +++ b/versioned_docs/version-1.21/installation/with-docker-rootless.md @@ -242,8 +242,10 @@ started properly. Logs can be viewed with `docker-compose logs`. To shut down the setup, execute `docker-compose down`. This will stop and kill the containers. The volumes will still exist. -Notice: if using a non-3000 port on http, change app.ini to match +:::note +If using a non-3000 port on http, change app.ini to match `LOCAL_ROOT_URL = http://localhost:3000/`. +::: ## Install @@ -252,7 +254,7 @@ favorite browser to finalize the installation. Visit http://server-ip:3000 and f installation wizard. If the database was started with the `docker-compose` setup as documented above, please note that `db` must be used as the database hostname. -# Customization +## Customization Customization files described [here](administration/customizing-gitea.md) should be placed in `/var/lib/gitea/custom` directory. If using host volumes, it's quite easy to access these @@ -260,13 +262,15 @@ files; for named volumes, this is done through another container or by direct ac `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea`. The configuration file will be saved at `/etc/gitea/app.ini` after the installation. -# Upgrading +## Upgrading +:::warning :exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: +::: To upgrade your installation to the latest release: -``` +```bash # Edit `docker-compose.yml` to update the version, if you have one specified # Pull new images docker-compose pull @@ -274,7 +278,7 @@ docker-compose pull docker-compose up -d ``` -# Upgrading from standard image +## Upgrading from standard image - Backup your setup - Change volume mountpoint from /data to /var/lib/gitea diff --git a/versioned_docs/version-1.21/installation/with-docker.md b/versioned_docs/version-1.21/installation/with-docker.md index e8a80f7c..8f070496 100644 --- a/versioned_docs/version-1.21/installation/with-docker.md +++ b/versioned_docs/version-1.21/installation/with-docker.md @@ -243,8 +243,10 @@ started properly. Logs can be viewed with `docker-compose logs`. To shut down the setup, execute `docker-compose down`. This will stop and kill the containers. The volumes will still exist. -Notice: if using a non-3000 port on http, change app.ini to match +:::note +If using a non-3000 port on http, change app.ini to match `LOCAL_ROOT_URL = http://localhost:3000/`. +::: ## Installation @@ -269,7 +271,9 @@ files; for named volumes, this is done through another container or by direct ac ## Upgrading +:::warning :exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: +::: To upgrade your installation to the latest release: diff --git a/versioned_docs/version-1.21/usage/authentication.md b/versioned_docs/version-1.21/usage/authentication.md index 6a6de08d..219236c9 100644 --- a/versioned_docs/version-1.21/usage/authentication.md +++ b/versioned_docs/version-1.21/usage/authentication.md @@ -348,4 +348,6 @@ 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. -Notice: Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests. +:::note +Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests. +::: diff --git a/versioned_docs/version-1.21/usage/code-owners.md b/versioned_docs/version-1.21/usage/code-owners.md index 7642175d..d39b3855 100644 --- a/versioned_docs/version-1.21/usage/code-owners.md +++ b/versioned_docs/version-1.21/usage/code-owners.md @@ -32,7 +32,7 @@ Regexp can start with `!` for negative rules - match all files except specified. Example file: -``` +```bash .*\\.go @user1 @user2 # This is comment # Comment too diff --git a/versioned_docs/version-1.21/usage/multi-factor-authentication.md b/versioned_docs/version-1.21/usage/multi-factor-authentication.md index 30323f6d..9bfa3e8a 100644 --- a/versioned_docs/version-1.21/usage/multi-factor-authentication.md +++ b/versioned_docs/version-1.21/usage/multi-factor-authentication.md @@ -28,8 +28,10 @@ This interface does not support MFA, and trying to use a password normally will If SSH is not an option for Git operations, an access token can be generated within the "Applications" tab of the user settings page. This access token can be used as if it were a password in order to allow the Git CLI to function over HTTP. -> **Warning** - By its very nature, an access token sidesteps the security benefits of MFA. -> It must be kept secure and should only be used as a last resort. +:::warning +By its very nature, an access token sidesteps the security benefits of MFA. +It must be kept secure and should only be used as a last resort. +::: The Gitea API supports providing the relevant TOTP password in the `X-Gitea-OTP` header, as described in [API Usage](development/api-usage.md). This should be used instead of an access token where possible. diff --git a/versioned_docs/version-1.21/usage/packages/container.md b/versioned_docs/version-1.21/usage/packages/container.md index 5676aa36..cdc2fdc9 100644 --- a/versioned_docs/version-1.21/usage/packages/container.md +++ b/versioned_docs/version-1.21/usage/packages/container.md @@ -57,7 +57,9 @@ For example, these are all valid image names for the owner `testuser`: `gitea.example.com/testuser/my/image` -**NOTE:** The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. +:::note +The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. +::: ## Push an image diff --git a/versioned_docs/version-1.21/usage/repo-mirror.md b/versioned_docs/version-1.21/usage/repo-mirror.md index 4a657103..279cdfc9 100644 --- a/versioned_docs/version-1.21/usage/repo-mirror.md +++ b/versioned_docs/version-1.21/usage/repo-mirror.md @@ -39,7 +39,9 @@ For an existing remote repository, you can set up pull mirroring as follows: The repository now gets mirrored periodically from the remote repository. You can force a sync by selecting **Synchronize Now** in the repository settings. -:exclamation::exclamation: **NOTE:** You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation: +:::warning +:exclamation::exclamation: You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation: +::: ## Pushing to a remote repository @@ -52,7 +54,9 @@ For an existing repository, you can set up push mirroring as follows: The repository now gets mirrored periodically to the remote repository. You can force a sync by selecting **Synchronize Now**. In case of an error a message displayed to help you resolve it. -:exclamation::exclamation: **NOTE:** This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation: +:::warning +:exclamation::exclamation: This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation: +::: ### Setting up a push mirror from Gitea to GitHub diff --git a/versioned_docs/version-1.21/usage/template-repositories.md b/versioned_docs/version-1.21/usage/template-repositories.md index 4618d10f..f7a9fa98 100644 --- a/versioned_docs/version-1.21/usage/template-repositories.md +++ b/versioned_docs/version-1.21/usage/template-repositories.md @@ -41,7 +41,9 @@ a/b/c/d.json **.[bB][aA][tT] ``` -**NOTE:** The `template` file will be removed from the `.gitea` directory when a repository is generated from the template. +:::note +The `template` file will be removed from the `.gitea` directory when a repository is generated from the template. +::: ## Variable Expansion diff --git a/versioned_docs/version-1.21/usage/webhooks.md b/versioned_docs/version-1.21/usage/webhooks.md index 684911f8..3d92e109 100644 --- a/versioned_docs/version-1.21/usage/webhooks.md +++ b/versioned_docs/version-1.21/usage/webhooks.md @@ -34,12 +34,14 @@ All event pushes are POST requests. The methods currently supported are: ### Event information -**WARNING**: The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 +:::warning +The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 +::: The following is an example of event information that will be sent by Gitea to a Payload URL: -``` +```http X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 X-GitHub-Event: push X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 @@ -133,7 +135,7 @@ In your repository Settings, under Webhooks, Setup a Gitea webhook as follows: Now on your server create the php file webhook.php -``` +```php **NOTE:** `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using: -> +:::note +> `/etc/gitea` is temporarily set with write permissions for user `git` so that the web installer can write the configuration file. After the installation is finished, it is recommended to set permissions to read-only using: +::: + > ```sh > chmod 750 /etc/gitea > chmod 640 /etc/gitea/app.ini @@ -127,7 +131,9 @@ See the [command line documentation](administration/command-line.md) for informa ### Configure Gitea's working directory -**NOTE:** If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory. +:::note +If you plan on running Gitea as a Linux service, you can skip this step, as the service file allows you to set `WorkingDirectory`. Otherwise, consider setting this environment variable (semi-)permanently so that Gitea consistently uses the correct working directory. +::: ```sh export GITEA_WORK_DIR=/var/lib/gitea/ @@ -183,7 +189,9 @@ To restart your Gitea instance, we recommend to use SIGHUP signal. If you know y To gracefully stop the Gitea instance, a simple `kill $GITEA_PID` or `killall gitea` is enough. -**NOTE:** We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.) +:::note +We don't recommend to use the SIGKILL signal (`-9`); you may be forcefully stopping some of Gitea's internal tasks, and it will not gracefully stop (tasks in queues, indexers, etc.) +::: See below for troubleshooting instructions to repair broken repositories after an update of your Gitea version. diff --git a/versioned_docs/version-1.22/installation/from-source.md b/versioned_docs/version-1.22/installation/from-source.md index cd9fd565..79ad660d 100644 --- a/versioned_docs/version-1.22/installation/from-source.md +++ b/versioned_docs/version-1.22/installation/from-source.md @@ -27,9 +27,11 @@ Next, [install Node.js with npm](https://nodejs.org/en/download/) which is required to build the JavaScript and CSS files. The minimum supported Node.js version is @minNodeVersion@ and the latest LTS version is recommended. -**Note**: Go version @minGoVersion@ or higher is required. However, it is recommended to +:::note +Go version @minGoVersion@ or higher is required. However, it is recommended to obtain the same version as our continuous integration, see the advice given in [Hacking on Gitea](development/hacking-on-gitea.md) +::: ## Download diff --git a/versioned_docs/version-1.22/installation/on-kubernetes.md b/versioned_docs/version-1.22/installation/on-kubernetes.md index 00f2aab2..c9036af1 100644 --- a/versioned_docs/version-1.22/installation/on-kubernetes.md +++ b/versioned_docs/version-1.22/installation/on-kubernetes.md @@ -46,7 +46,7 @@ Gitea comes with a health check endpoint `/api/healthz`, you can configure it in a successful health check response will respond with http code `200`, here's example: -``` +```json HTTP/1.1 200 OK { diff --git a/versioned_docs/version-1.22/installation/with-docker-rootless.md b/versioned_docs/version-1.22/installation/with-docker-rootless.md index 10f12122..df287c55 100644 --- a/versioned_docs/version-1.22/installation/with-docker-rootless.md +++ b/versioned_docs/version-1.22/installation/with-docker-rootless.md @@ -242,8 +242,10 @@ started properly. Logs can be viewed with `docker-compose logs`. To shut down the setup, execute `docker-compose down`. This will stop and kill the containers. The volumes will still exist. -Notice: if using a non-3000 port on http, change app.ini to match +:::note +If using a non-3000 port on http, change app.ini to match `LOCAL_ROOT_URL = http://localhost:3000/`. +::: ## Install @@ -252,7 +254,7 @@ favorite browser to finalize the installation. Visit http://server-ip:3000 and f installation wizard. If the database was started with the `docker-compose` setup as documented above, please note that `db` must be used as the database hostname. -# Customization +## Customization Customization files described [here](administration/customizing-gitea.md) should be placed in `/var/lib/gitea/custom` directory. If using host volumes, it's quite easy to access these @@ -260,13 +262,15 @@ files; for named volumes, this is done through another container or by direct ac `/var/lib/docker/volumes/gitea_gitea/_/var_lib_gitea`. The configuration file will be saved at `/etc/gitea/app.ini` after the installation. -# Upgrading +## Upgrading +:::warning :exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: +::: To upgrade your installation to the latest release: -``` +```bash # Edit `docker-compose.yml` to update the version, if you have one specified # Pull new images docker-compose pull @@ -274,7 +278,7 @@ docker-compose pull docker-compose up -d ``` -# Upgrading from standard image +## Upgrading from standard image - Backup your setup - Change volume mountpoint from /data to /var/lib/gitea diff --git a/versioned_docs/version-1.22/installation/with-docker.md b/versioned_docs/version-1.22/installation/with-docker.md index a16d4a8d..6102d7d7 100644 --- a/versioned_docs/version-1.22/installation/with-docker.md +++ b/versioned_docs/version-1.22/installation/with-docker.md @@ -243,8 +243,10 @@ started properly. Logs can be viewed with `docker-compose logs`. To shut down the setup, execute `docker-compose down`. This will stop and kill the containers. The volumes will still exist. -Notice: if using a non-3000 port on http, change app.ini to match +:::note +If using a non-3000 port on http, change app.ini to match `LOCAL_ROOT_URL = http://localhost:3000/`. +::: ## Installation @@ -269,7 +271,9 @@ files; for named volumes, this is done through another container or by direct ac ## Upgrading +:::warning :exclamation::exclamation: **Make sure you have volumed data to somewhere outside Docker container** :exclamation::exclamation: +::: To upgrade your installation to the latest release: diff --git a/versioned_docs/version-1.22/usage/authentication.md b/versioned_docs/version-1.22/usage/authentication.md index 963f03a0..40c8f80f 100644 --- a/versioned_docs/version-1.22/usage/authentication.md +++ b/versioned_docs/version-1.22/usage/authentication.md @@ -348,4 +348,6 @@ 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. -Notice: Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests. +:::note +Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests. +::: diff --git a/versioned_docs/version-1.22/usage/code-owners.md b/versioned_docs/version-1.22/usage/code-owners.md index 7642175d..d39b3855 100644 --- a/versioned_docs/version-1.22/usage/code-owners.md +++ b/versioned_docs/version-1.22/usage/code-owners.md @@ -32,7 +32,7 @@ Regexp can start with `!` for negative rules - match all files except specified. Example file: -``` +```bash .*\\.go @user1 @user2 # This is comment # Comment too diff --git a/versioned_docs/version-1.22/usage/multi-factor-authentication.md b/versioned_docs/version-1.22/usage/multi-factor-authentication.md index 30323f6d..9bfa3e8a 100644 --- a/versioned_docs/version-1.22/usage/multi-factor-authentication.md +++ b/versioned_docs/version-1.22/usage/multi-factor-authentication.md @@ -28,8 +28,10 @@ This interface does not support MFA, and trying to use a password normally will If SSH is not an option for Git operations, an access token can be generated within the "Applications" tab of the user settings page. This access token can be used as if it were a password in order to allow the Git CLI to function over HTTP. -> **Warning** - By its very nature, an access token sidesteps the security benefits of MFA. -> It must be kept secure and should only be used as a last resort. +:::warning +By its very nature, an access token sidesteps the security benefits of MFA. +It must be kept secure and should only be used as a last resort. +::: The Gitea API supports providing the relevant TOTP password in the `X-Gitea-OTP` header, as described in [API Usage](development/api-usage.md). This should be used instead of an access token where possible. diff --git a/versioned_docs/version-1.22/usage/packages/container.md b/versioned_docs/version-1.22/usage/packages/container.md index 5676aa36..cdc2fdc9 100644 --- a/versioned_docs/version-1.22/usage/packages/container.md +++ b/versioned_docs/version-1.22/usage/packages/container.md @@ -57,7 +57,9 @@ For example, these are all valid image names for the owner `testuser`: `gitea.example.com/testuser/my/image` -**NOTE:** The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. +:::note +The registry only supports case-insensitive tag names. So `image:tag` and `image:Tag` get treated as the same image and tag. +::: ## Push an image diff --git a/versioned_docs/version-1.22/usage/repo-mirror.md b/versioned_docs/version-1.22/usage/repo-mirror.md index 9d231598..5e3dd21a 100644 --- a/versioned_docs/version-1.22/usage/repo-mirror.md +++ b/versioned_docs/version-1.22/usage/repo-mirror.md @@ -39,7 +39,9 @@ For an existing remote repository, you can set up pull mirroring as follows: The repository now gets mirrored periodically from the remote repository. You can force a sync by selecting **Synchronize Now** in the repository settings. -:exclamation::exclamation: **NOTE:** You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation: +:::warning +:exclamation::exclamation: You can only set up pull mirroring for repos that don't exist yet on your instance. Once the repo is created, you can't convert it into a pull mirror anymore. :exclamation::exclamation: +::: ## Pushing to a remote repository @@ -52,7 +54,9 @@ For an existing repository, you can set up push mirroring as follows: The repository now gets mirrored periodically to the remote repository. You can force a sync by selecting **Synchronize Now**. In case of an error a message displayed to help you resolve it. -:exclamation::exclamation: **NOTE:** This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation: +:::warning +:exclamation::exclamation: This will force push to the remote repository. This will overwrite any changes in the remote repository! :exclamation::exclamation: +::: ### Setting up a push mirror from Gitea to GitHub diff --git a/versioned_docs/version-1.22/usage/template-repositories.md b/versioned_docs/version-1.22/usage/template-repositories.md index e57ed85c..8ce3cc03 100644 --- a/versioned_docs/version-1.22/usage/template-repositories.md +++ b/versioned_docs/version-1.22/usage/template-repositories.md @@ -32,7 +32,7 @@ Gitea uses [gobwas/glob](https://github.com/gobwas/glob) for its glob syntax. It All paths are relative to the base of the repository -```gitignore +```bash # Expand all .go files, anywhere in the repository **.go diff --git a/versioned_docs/version-1.22/usage/webhooks.md b/versioned_docs/version-1.22/usage/webhooks.md index 684911f8..3d92e109 100644 --- a/versioned_docs/version-1.22/usage/webhooks.md +++ b/versioned_docs/version-1.22/usage/webhooks.md @@ -34,12 +34,14 @@ All event pushes are POST requests. The methods currently supported are: ### Event information -**WARNING**: The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 +:::warning +The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755 +::: The following is an example of event information that will be sent by Gitea to a Payload URL: -``` +```http X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 X-GitHub-Event: push X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473 @@ -133,7 +135,7 @@ In your repository Settings, under Webhooks, Setup a Gitea webhook as follows: Now on your server create the php file webhook.php -``` +```php