+++ /dev/null
----
-date: "2018-06-24:00:00+02:00"
-title: "API Usage"
-slug: "api-usage"
-weight: 40
-toc: true
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "API Usage"
- weight: 40
- identifier: "api-usage"
----
-
-# Gitea API Usage
-
-## Enabling/configuring API access
-
-By default, `ENABLE_SWAGGER` is true, and
-`MAX_RESPONSE_ITEMS` is set to 50. See [Config Cheat
-Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) for more
-information.
-
-## Authentication via the API
-
-Gitea supports these methods of API authentication:
-
-- HTTP basic authentication
-- `token=...` parameter in URL query string
-- `access_token=...` parameter in URL query string
-- `Authorization: token ...` header in HTTP headers
-
-All of these methods accept the same API key token type. You can
-better understand this by looking at the code -- as of this writing,
-Gitea parses queries and headers to find the token in
-[modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
-
-You can create an API key token via your Gitea installation's web interface:
-`Settings | Applications | Generate New Token`.
-
-### OAuth2
-
-Access tokens obtained from Gitea's [OAuth2 provider](https://docs.gitea.io/en-us/oauth2-provider) are accepted by these methods:
-
-- `Authorization bearer ...` header in HTTP headers
-- `token=...` parameter in URL query string
-- `access_token=...` parameter in URL query string
-
-### More on the `Authorization:` header
-
-For historical reasons, Gitea needs the word `token` included before
-the API key token in an authorization header, like this:
-
-```
-Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
-```
-
-In a `curl` command, for instance, this would look like:
-
-```
-curl -X POST "http://localhost:4000/api/v1/repos/test1/test1/issues" \
- -H "accept: application/json" \
- -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
- -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
-```
-
-As mentioned above, the token used is the same one you would use in
-the `token=` string in a GET request.
-
-## API Guide:
-
-API Reference guide is auto-generated by swagger and available on:
- `https://gitea.your.host/api/swagger`
- or on
- [gitea demo instance](https://try.gitea.io/api/swagger)
-
-
-## Listing your issued tokens via the API
-
-As mentioned in
-[#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346),
-`/users/:name/tokens` is special and requires you to authenticate
-using BasicAuth, as follows:
-
-### Using basic authentication:
-
-```
-$ curl --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
-[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
-```
-
-As of v1.8.0 of Gitea, if using basic authentication with the API and your user has two factor authentication enabled, you'll need to send an additional header that contains the one time password (6 digit rotating token). An example of the header is `X-Gitea-OTP: 123456` where `123456` is where you'd place the code from your authenticator. Here is how the request would look like in curl:
-
-```
-$ curl -H "X-Gitea-OTP: 123456" --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
-```
-
-## Sudo
-
-The API allows admin users to sudo API requests as another user. Simply add either a `sudo=` parameter or `Sudo:` request header with the username of the user to sudo.
-
-## SDKs
-
-* [Official go-sdk](https://gitea.com/gitea/go-sdk)
-* [more](https://gitea.com/gitea/awesome-gitea#user-content-sdk)
+++ /dev/null
----
-date: "2018-06-24:00:00+02:00"
-title: "API 使用指南"
-slug: "api-usage"
-weight: 40
-toc: true
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "API 使用指南"
- weight: 40
- identifier: "api-usage"
----
-
-# Gitea API 使用指南
-
-## 开启/配置 API 访问
-
-通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat
-Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) 中获取更多配置相关信息。
-
-## 通过 API 认证
-
-Gitea 支持以下几种 API 认证方式：
-
-- HTTP basic authentication 方式
-- 通过指定 `token=...` URL 查询参数方式
-- 通过指定 `access_token=...` URL 查询参数方式
-- 通过指定 `Authorization: token ...` HTTP header 方式
-
-以上提及的认证方法接受相同的 apiKey token 类型，您可以在编码时通过查阅代码更好地理解这一点。
-Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。
-
-您可以通过您的 gitea web 界面来创建 apiKey token：
-`Settings | Applications | Generate New Token`.
-
-### 关于 `Authorization:` header
-
-由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 `token`，类似于如下形式：
-
-```
-Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
-```
-
-以 `curl` 命令为例，它会以如下形式携带在请求中：
-
-```
-curl -X POST "http://localhost:4000/api/v1/repos/test1/test1/issues" \
- -H "accept: application/json" \
- -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
- -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
-```
-
-正如上例所示，您也可以在 GET 请求中使用同一个 token 并以 `token=` 的查询参数形式携带 token 来进行认证。
-
-## 通过 API 列出您发布的令牌
-
-`/users/:name/tokens` 是一个特殊的接口，需要您使用 basic authentication 进行认证，具体原因在 issue 中
-[#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及，使用方法如下所示：
-
-### 使用 Basic authentication 认证：
-
-```
-$ curl --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
-[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
-```
-
-## 使用 Sudo 方式请求 API
-
-此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。
+++ /dev/null
----
-date: "2019-08-27:00:00+02:00"
-title: "CI/CD Usage"
-slug: "ci-cd"
-weight: 40
-toc: true
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "CI/CD Usage"
- weight: 40
- identifier: "ci-cd"
----
-
-# Gitea and CI/CD
-**NOTE:** These tools are not endorsed by Gitea. They are listed here for convenience only.
-
-## Hey! This page may be out of date or even removed in the future! :scream:
-Instead, check out [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/branch/master/README.md#user-content-devops)!
-
-## Listing
-
-CI/CD solutions that have integration with Gitea. Following list is not complete,
-the purpose is to give a starting point to integrate a CI/CD process with your Gitea instance.
-
- - [Drone](https://drone.io) with [Gitea documentation](https://docs.drone.io/installation/providers/gitea/)
- - [Jenkins](https://jenkins.io/) with [Gitea plugin](https://plugins.jenkins.io/gitea)
- - [Agola](https://agola.io)
- - [Buildkite](https://buildkite.com) with [Gitea connector](https://github.com/techknowlogick/gitea-buildkite-connector)
- - [AppVeyor](https://www.appveyor.com) with [built-in Gitea support](https://www.appveyor.com/blog/2019/09/05/gitea-receives-first-class-support-in-appveyor/)
- - [Buildbot](https://www.buildbot.net/) with [Gitea plugin](https://github.com/lab132/buildbot-gitea)
-
-
-Others CI/CD solutions that can partially be integrated with Gitea:
-
- - [Concourse](https://www.concourse-ci.org), see more information at [Concourse community forum](https://discuss.concourse-ci.org/t/concourse-ci-and-gitea-oauth/1475)
--- /dev/null
+---
+date: "2017-04-08T11:34:00+02:00"
+title: "Environment variables"
+slug: "environment-variables"
+weight: 20
+toc: false
+draft: false
+menu:
+ sidebar:
+ parent: "advanced"
+ name: "Environment variables"
+ weight: 20
+ identifier: "environment-variables"
+---
+
+# Environment variables
+
+This is an inventory of Gitea environment variables. They change Gitea behaviour.
+
+Initialize them before Gitea command to be effective, for example:
+
+```
+GITEA_CUSTOM=/home/gitea/custom ./gitea web
+```
+
+## From Go language
+
+As Gitea is written in Go, it uses some Go variables, such as:
+
+ * `GOOS`
+ * `GOARCH`
+ * [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
+
+For documentation about each of the variables available, refer to the
+[official Go documentation](https://golang.org/cmd/go/#hdr-Environment_variables).
+
+## Gitea files
+
+ * `GITEA_WORK_DIR`: Absolute path of working directory.
+ * `GITEA_CUSTOM`: Gitea uses `GITEA_WORK_DIR`/custom folder by default. Use this variable
+ to change *custom* directory.
+ * `GOGS_WORK_DIR`: Deprecated, use `GITEA_WORK_DIR`
+ * `GOGS_CUSTOM`: Deprecated, use `GITEA_CUSTOM`
+
+## Operating system specifics
+
+ * `USER`: System user that Gitea will run as. Used for some repository access strings.
+ * `USERNAME`: if no `USER` found, Gitea will use `USERNAME`
+ * `HOME`: User home directory path. The `USERPROFILE` environment variable is used in Windows.
+
+### Only on Windows
+
+ * `USERPROFILE`: User home directory path. If empty, uses `HOMEDRIVE` + `HOMEPATH`
+ * `HOMEDRIVE`: Main drive path used to access the home directory (C:)
+ * `HOMEPATH`: Home relative path in the given home drive path
+
+## Macaron (framework used by Gitea)
+
+ * `HOST`: Host Macaron will listen on
+ * `PORT`: Port Macaron will listen on
+ * `MACARON_ENV`: global variable to provide special functionality for development environments
+ vs. production environments. If MACARON_ENV is set to "" or "development", then templates will
+ be recompiled on every request. For more performance, set the MACARON_ENV environment variable
+ to "production".
+
+## Miscellaneous
+
+ * `SKIP_MINWINSVC`: If set to 1, do not run as a service on Windows.
--- /dev/null
+---
+date: "2017-04-08T11:34:00+02:00"
+title: "环境变量清单"
+slug: "environment-variables"
+weight: 20
+toc: false
+draft: false
+menu:
+ sidebar:
+ parent: "advanced"
+ name: "环境变量清单"
+ weight: 20
+ identifier: "environment-variables"
+---
+
+# 环境变量清单
+
+这里是用来控制 Gitea 行为表现的的环境变量清单，您需要在执行如下 Gitea 启动命令前设置它们来确保配置生效：
+
+```
+GITEA_CUSTOM=/home/gitea/custom ./gitea web
+```
+
+## Go 的配置
+
+因为 Gitea 使用 Go 语言编写，因此它使用了一些相关的 Go 的配置参数：
+
+ * `GOOS`
+ * `GOARCH`
+ * [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
+
+您可以在[官方文档](https://golang.org/cmd/go/#hdr-Environment_variables)中查阅这些配置参数的详细信息。
+
+## Gitea 的文件目录
+
+ * `GITEA_WORK_DIR`：工作目录的绝对路径
+ * `GITEA_CUSTOM`：默认情况下 Gitea 使用默认目录 `GITEA_WORK_DIR`/custom，您可以使用这个参数来配置 *custom* 目录
+ * `GOGS_WORK_DIR`： 已废弃，请使用 `GITEA_WORK_DIR` 替代
+ * `GOGS_CUSTOM`： 已废弃，请使用 `GITEA_CUSTOM` 替代
+
+## 操作系统配置
+
+ * `USER`：Gitea 运行时使用的系统用户，它将作为一些 repository 的访问地址的一部分
+ * `USERNAME`： 如果没有配置 `USER`， Gitea 将使用 `USERNAME`
+ * `HOME`： 用户的 home 目录，在 Windows 中会使用 `USERPROFILE` 环境变量
+
+### 仅限于 Windows 的配置
+
+ * `USERPROFILE`： 用户的主目录，如果未配置则会使用 `HOMEDRIVE` + `HOMEPATH`
+ * `HOMEDRIVE`: 用于访问 home 目录的主驱动器路径（C盘）
+ * `HOMEPATH`：在指定主驱动器下的 home 目录相对路径
+
+## Macaron（Gitea 使用的 web 框架）
+
+ * `HOST`：Macaron 监听的主机地址
+ * `PORT`：Macaron 监听的端口地址
+ * `MACARON_ENV`：为开发环境和生产环境提供特殊功能性配置的全局变量，当 MACARON_ENV 设置为 "" 或 "development"
+ 时，每次请求都会重编译页面模板。为了提高性能表现，可将它设置为 "production"。
+
+## Miscellaneous
+
+ * `SKIP_MINWINSVC`：如果设置为 1，在 Windows 上不会以 service 的形式运行。
+++ /dev/null
----
-date: "2016-12-01T16:00:00+02:00"
-title: "Hacking on Gitea"
-slug: "hacking-on-gitea"
-weight: 10
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "Hacking on Gitea"
- weight: 10
- identifier: "hacking-on-gitea"
----
-
-# Hacking on Gitea
-
-## Installing go
-
-You should [install go](https://golang.org/doc/install) and set up your go
-environment correctly.
-
-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 {{< min-node-version >}} and the latest LTS version is recommended.
-
-You will also need make.
-<a href='{{< relref "doc/advanced/make.en-us.md" >}}'>(See here how to get Make)</a>
-
-**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 {{< min-go-version >}} or higher is required; however, it is important
-to note that our continuous integration will check that the formatting of the
-source code is not changed by `gofmt` using `make fmt-check`. Unfortunately,
-the results of `gofmt` can differ by the version of `go`. It is therefore
-recommended to install the version of Go that our continuous integration is
-running. As of last update, it should be Go version {{< go-version >}}.
-
-## Downloading and cloning the Gitea source code
-
-The recommended method of obtaining the source code is by using `git clone`.
-
-```bash
-git clone https://github.com/go-gitea/gitea
-```
-
-(Since the advent of go modules, it is no longer necessary to build go projects
-from within the `$GOPATH`, hence the `go get` approach is no longer recommended.)
-
-## Forking Gitea
-
-Download the master Gitea source code as above. Then, fork the
-[Gitea repository](https://github.com/go-gitea/gitea) on GitHub,
-and either switch the git remote origin for your fork or add your fork as another remote:
-
-```bash
-# Rename original Gitea origin to upstream
-git remote rename origin upstream
-git remote add origin "git@github.com:$GITHUB_USERNAME/gitea.git"
-git fetch --all --prune
-```
-
-or:
-
-```bash
-# Add new remote for our fork
-git remote add "$FORK_NAME" "git@github.com:$GITHUB_USERNAME/gitea.git"
-git fetch --all --prune
-```
-
-To be able to create pull requests, the forked repository should be added as a remote
-to the Gitea sources. Otherwise, changes can't be pushed.
-
-## Building Gitea (Basic)
-
-Take a look at our
-<a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>instructions</a>
-for <a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>building
-from source</a>.
-
-The simplest recommended way to build from source is:
-
-```bash
-TAGS="bindata sqlite sqlite_unlock_notify" make build
-```
-
-The `build` target will execute both `frontend` and `backend` sub-targets. If the `bindata` tag is present, the frontend files will be compiled into the binary. It is recommended to leave out the tag when doing frontend development so that changes will be reflected.
-
-See `make help` for all available `make` targets. Also see [`.drone.yml`](https://github.com/go-gitea/gitea/blob/master/.drone.yml) to see how our continuous integration works.
-
-## Building continuously
-
-To run and continously rebuild when source files change:
-
-````bash
-make watch
-````
-
-On macOS, watching all backend source files may hit the default open files limit which can be increased via `ulimit -n 12288` for the current shell or in your shell startup file for all future shells.
-
-### Formatting, code analysis and spell check
-
-Our continuous integration will reject PRs that are not properly formatted, fail
-code analysis or spell check.
-
-You should format your code with `go fmt` using:
-
-```bash
-make fmt
-```
-
-and can test whether your changes would match the results with:
-
-```bash
-make fmt-check # which runs make fmt internally
-```
-
-**Note**: The results of `go fmt` are dependent on the version of `go` present.
-You should run the same version of go that is on the continuous integration
-server as mentioned above. `make fmt-check` will only check if your `go` would
-format differently - this may be different from the CI server version.
-
-You should run revive, vet and spell-check on the code with:
-
-```bash
-make revive vet misspell-check
-```
-
-### Working on JS and CSS
-
-Either use the `watch-frontend` target mentioned above or just build once:
-
-```bash
-make build && ./gitea
-```
-
-Before committing, make sure the linters pass:
-
-```bash
-make lint-frontend
-```
-
-Note: When working on frontend code, set `USE_SERVICE_WORKER` to `false` in `app.ini` to prevent undesirable caching of frontend assets.
-
-### Building and adding SVGs
-
-SVG icons are built using the `make svg` target which compiles the icon sources defined in `build/generate-svg.js` into the output directory `public/img/svg`. Custom icons can be added in the `web_src/svg` directory.
-
-### Building the Logo
-
-The PNG versions of the logo are built from a single SVG source file `assets/logo.svg` using the `make generate-images` target. To run it, Node.js and npm must be available. The same process can also be used to generate a custom logo PNGs from a SVG source file. It's possible to remove parts of the SVG logo for the favicon build by adding a `detail-remove` class to the SVG nodes to be removed.
-
-### Updating the API
-
-When creating new API routes or modifying existing API routes, you **MUST**
-update and/or create [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)
-documentation for these using [go-swagger](https://goswagger.io/) comments.
-The structure of these comments is described in the [specification](https://goswagger.io/use/spec.html#annotation-syntax).
-If you want more information about the Swagger structure, you can look at the
-[Swagger 2.0 Documentation](https://swagger.io/docs/specification/2-0/basic-structure/)
-or compare with a previous PR adding a new API endpoint, e.g. [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
-
-You should be careful not to break the API for downstream users which depend
-on a stable API. In general, this means additions are acceptable, but deletions
-or fundamental changes to the API will be rejected.
-
-Once you have created or changed an API endpoint, please regenerate the Swagger
-documentation using:
-
-```bash
-make generate-swagger
-```
-
-You should validate your generated Swagger file and spell-check it with:
-
-```bash
-make swagger-validate misspell-check
-```
-
-You should commit the changed swagger JSON file. The continous integration
-server will check that this has been done using:
-
-```bash
-make swagger-check
-```
-
-**Note**: Please note you should use the Swagger 2.0 documentation, not the
-OpenAPI 3 documentation.
-
-### Creating new configuration options
-
-When creating new configuration options, it is not enough to add them to the
-`modules/setting` files. You should add information to `custom/conf/app.ini`
-and to the
-<a href='{{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}}'>configuration cheat sheet</a>
-found in `docs/content/doc/advanced/config-cheat-sheet.en-us.md`
-
-### Changing the logo
-
-When changing the Gitea logo SVG, you will need to run and commit the results
-of:
-
-```bash
-make generate-images
-```
-
-This will create the necessary Gitea favicon and others.
-
-### Database Migrations
-
-If you make breaking changes to any of the database persisted structs in the
-`models/` directory, you will need to make a new migration. These can be found
-in `models/migrations/`. You can ensure that your migrations work for the main
-database types using:
-
-```bash
-make test-sqlite-migration # with sqlite switched for the appropriate database
-```
-
-## Testing
-
-There are two types of test run by Gitea: Unit tests and Integration Tests.
-
-```bash
-TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
-```
-
-Unit tests will not and cannot completely test Gitea alone. Therefore, we
-have written integration tests; however, these are database dependent.
-
-```bash
-TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
-```
-
-will run the integration tests in an sqlite environment. Integration tests
-require `git lfs` to be installed. Other database tests are available but
-may need adjustment to the local environment.
-
-Look at
-[`integrations/README.md`](https://github.com/go-gitea/gitea/blob/master/integrations/README.md)
-for more information and how to run a single test.
-
-Our continuous integration will test the code passes its unit tests and that
-all supported databases will pass integration test in a Docker environment.
-Migration from several recent versions of Gitea will also be tested.
-
-Please submit your PR with additional tests and integration tests as
-appropriate.
-
-## Documentation for the website
-
-Documentation for the website is found in `docs/`. If you change this you
-can test your changes to ensure that they pass continuous integration using:
-
-```bash
-# from the docs directory within Gitea
-make trans-copy clean build
-```
-
-You will require a copy of [Hugo](https://gohugo.io/) to run this task. Please
-note: this may generate a number of untracked git objects, which will need to
-be cleaned up.
-
-## Visual Studio Code
-
-A `launch.json` and `tasks.json` are provided within `contrib/ide/vscode` for
-Visual Studio Code. Look at
-[`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/master/contrib/ide/README.md)
-for more information.
-
-## Submitting PRs
-
-Once you're happy with your changes, push them up and open a pull request. It
-is recommended that you allow Gitea Managers and Owners to modify your PR
-branches as we will need to update it to master before merging and/or may be
-able to help fix issues directly.
-
-Any PR requires two approvals from the Gitea maintainers and needs to pass the
-continous integration. Take a look at our
-[`CONTRIBUTING.md`](https://github.com/go-gitea/gitea/blob/master/CONTRIBUTING.md)
-document.
-
-If you need more help pop on to [Discord](https://discord.gg/gitea) #Develop
-and chat there.
-
-That's it! You are ready to hack on Gitea.
+++ /dev/null
----
-date: "2017-01-14T11:00:00-02:00"
-title: "Make"
-slug: "make"
-weight: 10
-toc: true
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "Make"
- weight: 30
- identifier: "make"
----
-
-# Make
-
-Gitea makes heavy use of Make to automate tasks and improve development. This
-guide covers how to install Make.
-
-### On Linux
-
-Install with the package manager.
-
-On Ubuntu/Debian:
-
-```bash
-sudo apt-get install make
-```
-
-On Fedora/RHEL/CentOS:
-
-```bash
-sudo yum install make
-```
-
-### On Windows
-
-One of these three distributions of Make will run on Windows:
-
-- [Single binary build](http://www.equation.com/servlet/equation.cmd?fa=make). Copy somewhere and add to `PATH`.
- - [32-bits version](ftp://ftp.equation.com/make/32/make.exe)
- - [64-bits version](ftp://ftp.equation.com/make/64/make.exe)
-- [MinGW](http://www.mingw.org/) includes a build.
- - The binary is called `mingw32-make.exe` instead of `make.exe`. Add the `bin` folder to `PATH`.
-- [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make`
+++ /dev/null
----
-date: "2019-04-15T17:29:00+08:00"
-title: "Advanced: Migrations Interfaces"
-slug: "migrations-interfaces"
-weight: 30
-toc: true
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "Migrations Interfaces"
- weight: 55
- identifier: "migrations-interfaces"
----
-
-# Migration Features
-
-The new migration features were introduced in Gitea 1.9.0. It defines two interfaces to support migrating
-repositories data from other git host platforms to gitea or, in the future migrating gitea data to other
-git host platforms. Currently, migrations from Github, Gitlab and Gitea to Gitea is implemented.
-
-First of all, Gitea defines some standard objects in packages `modules/migrations/base`. They are
- `Repository`, `Milestone`, `Release`, `ReleaseAsset`, `Label`, `Issue`, `Comment`, `PullRequest`, `Reaction`, `Review`, `ReviewComment`.
-
-## Downloader Interfaces
-
-To migrate from a new git host platform, there are two steps to be updated.
-
-- You should implement a `Downloader` which will get all kinds of repository informations.
-- You should implement a `DownloaderFactory` which is used to detect if the URL matches and
-create a Downloader.
-- You'll need to register the `DownloaderFactory` via `RegisterDownloaderFactory` on init.
-
-```Go
-type Downloader interface {
- GetAsset(relTag string, relID, id int64) (io.ReadCloser, error)
- SetContext(context.Context)
- GetRepoInfo() (*Repository, error)
- GetTopics() ([]string, error)
- GetMilestones() ([]*Milestone, error)
- GetReleases() ([]*Release, error)
- GetLabels() ([]*Label, error)
- GetIssues(page, perPage int) ([]*Issue, bool, error)
- GetComments(issueNumber int64) ([]*Comment, error)
- GetPullRequests(page, perPage int) ([]*PullRequest, bool, error)
- GetReviews(pullRequestNumber int64) ([]*Review, error)
-}
-```
-
-```Go
-type DownloaderFactory interface {
- New(ctx context.Context, opts MigrateOptions) (Downloader, error)
- GitServiceType() structs.GitServiceType
-}
-```
-
-## Uploader Interface
-
-Currently, only a `GiteaLocalUploader` is implemented, so we only save downloaded
-data via this `Uploader` on the local Gitea instance. Other uploaders are not supported
-and will be implemented in future.
-
-```Go
-// Uploader uploads all the informations
-type Uploader interface {
- MaxBatchInsertSize(tp string) int
- CreateRepo(repo *Repository, opts MigrateOptions) error
- CreateTopics(topic ...string) error
- CreateMilestones(milestones ...*Milestone) error
- CreateReleases(downloader Downloader, releases ...*Release) error
- SyncTags() error
- CreateLabels(labels ...*Label) error
- CreateIssues(issues ...*Issue) error
- CreateComments(comments ...*Comment) error
- CreatePullRequests(prs ...*PullRequest) error
- CreateReviews(reviews ...*Review) error
- Rollback() error
- Close()
-}
-
-```
+++ /dev/null
----
-date: "2019-04-19:44:00+01:00"
-title: "OAuth2 provider"
-slug: "oauth2-provider"
-weight: 41
-toc: true
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "OAuth2 Provider"
- weight: 41
- identifier: "oauth2-provider"
----
-
-
-# OAuth2 provider
-
-Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0.
-
-## Endpoints
-
-
-Endpoint | URL
------------------------|----------------------------
-Authorization Endpoint | `/login/oauth/authorize`
-Access Token Endpoint | `/login/oauth/access_token`
-
-
-## Supported OAuth2 Grants
-
-At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) extension.
-
-
-To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings.
-
-## Scopes
-
-Currently Gitea does not support scopes (see [#4300](https://github.com/go-gitea/gitea/issues/4300)) and all third party applications will be granted access to all resources of the user and his/her organizations.
-
-## Example
-
-**Note:** This example does not use PKCE.
-
-1. Redirect to user to the authorization endpoint in order to get his/her consent for accessing the resources:
-
-```curl
-https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
-```
-
-The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks.
-
-
-
-
-The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example:
-
-```curl
-https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
-```
-
-2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
-
-```curl
-POST https://[YOUR-GITEA-URL]/login/oauth/access_token
-```
-
-```json
-{
- "client_id": "YOUR_CLIENT_ID",
- "client_secret": "YOUR_CLIENT_SECRET",
- "code": "RETURNED_CODE",
- "grant_type": "authorization_code",
- "redirect_uri": "REDIRECT_URI"
-}
-```
-
-Response:
-```json
-{
-"access_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
-"token_type":"bearer",
-"expires_in":3600,
-"refresh_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
-}
-```
-
-The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings.
-
-The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request.
-
-3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources.
+++ /dev/null
----
-date: "2017-04-08T11:34:00+02:00"
-title: "Specific variables"
-slug: "specific-variables"
-weight: 20
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "Specific variables"
- weight: 20
- identifier: "specific-variables"
----
-
-# Specific variables
-
-This is an inventory of Gitea environment variables. They change Gitea behaviour.
-
-Initialize them before Gitea command to be effective, for example:
-
-```
-GITEA_CUSTOM=/home/gitea/custom ./gitea web
-```
-
-## From Go language
-
-As Gitea is written in Go, it uses some Go variables, such as:
-
- * `GOOS`
- * `GOARCH`
- * [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
-
-For documentation about each of the variables available, refer to the
-[official Go documentation](https://golang.org/cmd/go/#hdr-Environment_variables).
-
-## Gitea files
-
- * `GITEA_WORK_DIR`: Absolute path of working directory.
- * `GITEA_CUSTOM`: Gitea uses `GITEA_WORK_DIR`/custom folder by default. Use this variable
- to change *custom* directory.
- * `GOGS_WORK_DIR`: Deprecated, use `GITEA_WORK_DIR`
- * `GOGS_CUSTOM`: Deprecated, use `GITEA_CUSTOM`
-
-## Operating system specifics
-
- * `USER`: System user that Gitea will run as. Used for some repository access strings.
- * `USERNAME`: if no `USER` found, Gitea will use `USERNAME`
- * `HOME`: User home directory path. The `USERPROFILE` environment variable is used in Windows.
-
-### Only on Windows
-
- * `USERPROFILE`: User home directory path. If empty, uses `HOMEDRIVE` + `HOMEPATH`
- * `HOMEDRIVE`: Main drive path used to access the home directory (C:)
- * `HOMEPATH`: Home relative path in the given home drive path
-
-## Macaron (framework used by Gitea)
-
- * `HOST`: Host Macaron will listen on
- * `PORT`: Port Macaron will listen on
- * `MACARON_ENV`: global variable to provide special functionality for development environments
- vs. production environments. If MACARON_ENV is set to "" or "development", then templates will
- be recompiled on every request. For more performance, set the MACARON_ENV environment variable
- to "production".
-
-## Miscellaneous
-
- * `SKIP_MINWINSVC`: If set to 1, do not run as a service on Windows.
+++ /dev/null
----
-date: "2017-04-08T11:34:00+02:00"
-title: "环境变量清单"
-slug: "specific-variables"
-weight: 20
-toc: false
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "环境变量清单"
- weight: 20
- identifier: "specific-variables"
----
-
-# 环境变量清单
-
-这里是用来控制 Gitea 行为表现的的环境变量清单，您需要在执行如下 Gitea 启动命令前设置它们来确保配置生效：
-
-```
-GITEA_CUSTOM=/home/gitea/custom ./gitea web
-```
-
-## Go 的配置
-
-因为 Gitea 使用 Go 语言编写，因此它使用了一些相关的 Go 的配置参数：
-
- * `GOOS`
- * `GOARCH`
- * [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
-
-您可以在[官方文档](https://golang.org/cmd/go/#hdr-Environment_variables)中查阅这些配置参数的详细信息。
-
-## Gitea 的文件目录
-
- * `GITEA_WORK_DIR`：工作目录的绝对路径
- * `GITEA_CUSTOM`：默认情况下 Gitea 使用默认目录 `GITEA_WORK_DIR`/custom，您可以使用这个参数来配置 *custom* 目录
- * `GOGS_WORK_DIR`： 已废弃，请使用 `GITEA_WORK_DIR` 替代
- * `GOGS_CUSTOM`： 已废弃，请使用 `GITEA_CUSTOM` 替代
-
-## 操作系统配置
-
- * `USER`：Gitea 运行时使用的系统用户，它将作为一些 repository 的访问地址的一部分
- * `USERNAME`： 如果没有配置 `USER`， Gitea 将使用 `USERNAME`
- * `HOME`： 用户的 home 目录，在 Windows 中会使用 `USERPROFILE` 环境变量
-
-### 仅限于 Windows 的配置
-
- * `USERPROFILE`： 用户的主目录，如果未配置则会使用 `HOMEDRIVE` + `HOMEPATH`
- * `HOMEDRIVE`: 用于访问 home 目录的主驱动器路径（C盘）
- * `HOMEPATH`：在指定主驱动器下的 home 目录相对路径
-
-## Macaron（Gitea 使用的 web 框架）
-
- * `HOST`：Macaron 监听的主机地址
- * `PORT`：Macaron 监听的端口地址
- * `MACARON_ENV`：为开发环境和生产环境提供特殊功能性配置的全局变量，当 MACARON_ENV 设置为 "" 或 "development"
- 时，每次请求都会重编译页面模板。为了提高性能表现，可将它设置为 "production"。
-
-## Miscellaneous
-
- * `SKIP_MINWINSVC`：如果设置为 1，在 Windows 上不会以 service 的形式运行。
+++ /dev/null
----
-date: "2018-05-22T11:00:00+00:00"
-title: "Advanced: Third Party Tools"
-slug: "third-party-tools"
-weight: 50
-toc: true
-draft: false
-menu:
- sidebar:
- parent: "advanced"
- name: "Third Party Tools"
- weight: 50
- identifier: "third-party-tools"
----
-
-# List of third-party tools
-**NOTE:** These tools are not endorsed by Gitea. They are listed here for convenience only.
-
-## Hey! This page may be out of date or even removed in the future! :scream:
-Instead, check out [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/branch/master/README.md)!
-
-### Continuous Integration
-
-Check our [CI/CD page]({{< relref "doc/advanced/ci-cd.en-us.md" >}})
-
-### Internationalization
-- [Weblate](https://docs.weblate.org/en/latest/admin/continuous.html#gitea-setup)
-
-### Migrating
-- [Installation script for Gitea](https://git.coolaj86.com/coolaj86/gitea-installer.sh)
-- [GitHub Migrator](https://gitea.com/gitea/migrator)
-
-
-### Mobile
-- [GitNex for Android](https://codeberg.org/gitnex/GitNex)
-- [GitTouch for Android and iOS](https://github.com/git-touch/git-touch)
-
-### Editor Extensions
-- [Gitea Extension for Visual Studio](https://github.com/maikebing/Gitea.VisualStudio)
- - Download from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=MysticBoy.GiteaExtensionforVisualStudio)
-
-### Project Management
-- [YouTrack by JetBrains](https://blog.jetbrains.com/youtrack/2019/12/whats-new-in-youtrack-2019-3/)
--- /dev/null
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Developers"
+slug: "developers"
+weight: 40
+toc: false
+draft: false
+menu:
+ sidebar:
+ name: "Developers"
+ weight: 50
+ identifier: "developers"
+---
--- /dev/null
+---
+date: "2018-06-24:00:00+02:00"
+title: "API Usage"
+slug: "api-usage"
+weight: 40
+toc: true
+draft: false
+menu:
+ sidebar:
+ parent: "developers"
+ name: "API Usage"
+ weight: 40
+ identifier: "api-usage"
+---
+
+# Gitea API Usage
+
+## Enabling/configuring API access
+
+By default, `ENABLE_SWAGGER` is true, and
+`MAX_RESPONSE_ITEMS` is set to 50. See [Config Cheat
+Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) for more
+information.
+
+## Authentication via the API
+
+Gitea supports these methods of API authentication:
+
+- HTTP basic authentication
+- `token=...` parameter in URL query string
+- `access_token=...` parameter in URL query string
+- `Authorization: token ...` header in HTTP headers
+
+All of these methods accept the same API key token type. You can
+better understand this by looking at the code -- as of this writing,
+Gitea parses queries and headers to find the token in
+[modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
+
+You can create an API key token via your Gitea installation's web interface:
+`Settings | Applications | Generate New Token`.
+
+### OAuth2
+
+Access tokens obtained from Gitea's [OAuth2 provider](https://docs.gitea.io/en-us/oauth2-provider) are accepted by these methods:
+
+- `Authorization bearer ...` header in HTTP headers
+- `token=...` parameter in URL query string
+- `access_token=...` parameter in URL query string
+
+### More on the `Authorization:` header
+
+For historical reasons, Gitea needs the word `token` included before
+the API key token in an authorization header, like this:
+
+```
+Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
+```
+
+In a `curl` command, for instance, this would look like:
+
+```
+curl -X POST "http://localhost:4000/api/v1/repos/test1/test1/issues" \
+ -H "accept: application/json" \
+ -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
+ -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
+```
+
+As mentioned above, the token used is the same one you would use in
+the `token=` string in a GET request.
+
+## API Guide:
+
+API Reference guide is auto-generated by swagger and available on:
+ `https://gitea.your.host/api/swagger`
+ or on
+ [gitea demo instance](https://try.gitea.io/api/swagger)
+
+
+## Listing your issued tokens via the API
+
+As mentioned in
+[#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346),
+`/users/:name/tokens` is special and requires you to authenticate
+using BasicAuth, as follows:
+
+### Using basic authentication:
+
+```
+$ curl --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
+[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
+```
+
+As of v1.8.0 of Gitea, if using basic authentication with the API and your user has two factor authentication enabled, you'll need to send an additional header that contains the one time password (6 digit rotating token). An example of the header is `X-Gitea-OTP: 123456` where `123456` is where you'd place the code from your authenticator. Here is how the request would look like in curl:
+
+```
+$ curl -H "X-Gitea-OTP: 123456" --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
+```
+
+## Sudo
+
+The API allows admin users to sudo API requests as another user. Simply add either a `sudo=` parameter or `Sudo:` request header with the username of the user to sudo.
+
+## SDKs
+
+* [Official go-sdk](https://gitea.com/gitea/go-sdk)
+* [more](https://gitea.com/gitea/awesome-gitea#user-content-sdk)
--- /dev/null
+---
+date: "2018-06-24:00:00+02:00"
+title: "API 使用指南"
+slug: "api-usage"
+weight: 40
+toc: true
+draft: false
+menu:
+ sidebar:
+ parent: "developers"
+ name: "API 使用指南"
+ weight: 40
+ identifier: "api-usage"
+---
+
+# Gitea API 使用指南
+
+## 开启/配置 API 访问
+
+通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat
+Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) 中获取更多配置相关信息。
+
+## 通过 API 认证
+
+Gitea 支持以下几种 API 认证方式：
+
+- HTTP basic authentication 方式
+- 通过指定 `token=...` URL 查询参数方式
+- 通过指定 `access_token=...` URL 查询参数方式
+- 通过指定 `Authorization: token ...` HTTP header 方式
+
+以上提及的认证方法接受相同的 apiKey token 类型，您可以在编码时通过查阅代码更好地理解这一点。
+Gitea 调用解析查询参数以及头部信息来获取 token 的代码可以在 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47) 中找到。
+
+您可以通过您的 gitea web 界面来创建 apiKey token：
+`Settings | Applications | Generate New Token`.
+
+### 关于 `Authorization:` header
+
+由于一些历史原因，Gitea 需要在 header 的 apiKey token 里引入前缀 `token`，类似于如下形式：
+
+```
+Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
+```
+
+以 `curl` 命令为例，它会以如下形式携带在请求中：
+
+```
+curl -X POST "http://localhost:4000/api/v1/repos/test1/test1/issues" \
+ -H "accept: application/json" \
+ -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
+ -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
+```
+
+正如上例所示，您也可以在 GET 请求中使用同一个 token 并以 `token=` 的查询参数形式携带 token 来进行认证。
+
+## 通过 API 列出您发布的令牌
+
+`/users/:name/tokens` 是一个特殊的接口，需要您使用 basic authentication 进行认证，具体原因在 issue 中
+[#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346) 有所提及，使用方法如下所示：
+
+### 使用 Basic authentication 认证：
+
+```
+$ curl --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
+[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]
+```
+
+## 使用 Sudo 方式请求 API
+
+此 API 允许管理员借用其他用户身份进行 API 请求。只需在请求中指定查询参数 `sudo=` 或是指定 header 中的 `Sudo:` 为需要使用的用户 username 即可。
--- /dev/null
+---
+date: "2016-12-01T16:00:00+02:00"
+title: "Hacking on Gitea"
+slug: "hacking-on-gitea"
+weight: 10
+toc: false
+draft: false
+menu:
+ sidebar:
+ parent: "developers"
+ name: "Hacking on Gitea"
+ weight: 10
+ identifier: "hacking-on-gitea"
+---
+
+# Hacking on Gitea
+
+## Installing go
+
+You should [install go](https://golang.org/doc/install) and set up your go
+environment correctly.
+
+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 {{< min-node-version >}} and the latest LTS version is recommended.
+
+**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 {{< min-go-version >}} or higher is required; however, it is important
+to note that our continuous integration will check that the formatting of the
+source code is not changed by `gofmt` using `make fmt-check`. Unfortunately,
+the results of `gofmt` can differ by the version of `go`. It is therefore
+recommended to install the version of Go that our continuous integration is
+running. As of last update, it should be Go version {{< go-version >}}.
+
+## Installing Make
+
+Gitea makes heavy use of Make to automate tasks and improve development. This
+guide covers how to install Make.
+
+#### On Linux
+
+Install with the package manager.
+
+On Ubuntu/Debian:
+
+```bash
+sudo apt-get install make
+```
+
+On Fedora/RHEL/CentOS:
+
+```bash
+sudo yum install make
+```
+
+#### On Windows
+
+One of these three distributions of Make will run on Windows:
+
+- [Single binary build](http://www.equation.com/servlet/equation.cmd?fa=make). Copy somewhere and add to `PATH`.
+ - [32-bits version](ftp://ftp.equation.com/make/32/make.exe)
+ - [64-bits version](ftp://ftp.equation.com/make/64/make.exe)
+- [MinGW](http://www.mingw.org/) includes a build.
+ - The binary is called `mingw32-make.exe` instead of `make.exe`. Add the `bin` folder to `PATH`.
+- [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make`
+
+## Downloading and cloning the Gitea source code
+
+The recommended method of obtaining the source code is by using `git clone`.
+
+```bash
+git clone https://github.com/go-gitea/gitea
+```
+
+(Since the advent of go modules, it is no longer necessary to build go projects
+from within the `$GOPATH`, hence the `go get` approach is no longer recommended.)
+
+## Forking Gitea
+
+Download the master Gitea source code as above. Then, fork the
+[Gitea repository](https://github.com/go-gitea/gitea) on GitHub,
+and either switch the git remote origin for your fork or add your fork as another remote:
+
+```bash
+# Rename original Gitea origin to upstream
+git remote rename origin upstream
+git remote add origin "git@github.com:$GITHUB_USERNAME/gitea.git"
+git fetch --all --prune
+```
+
+or:
+
+```bash
+# Add new remote for our fork
+git remote add "$FORK_NAME" "git@github.com:$GITHUB_USERNAME/gitea.git"
+git fetch --all --prune
+```
+
+To be able to create pull requests, the forked repository should be added as a remote
+to the Gitea sources. Otherwise, changes can't be pushed.
+
+## Building Gitea (Basic)
+
+Take a look at our
+<a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>instructions</a>
+for <a href='{{< relref "doc/installation/from-source.en-us.md" >}}'>building
+from source</a>.
+
+The simplest recommended way to build from source is:
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make build
+```
+
+The `build` target will execute both `frontend` and `backend` sub-targets. If the `bindata` tag is present, the frontend files will be compiled into the binary. It is recommended to leave out the tag when doing frontend development so that changes will be reflected.
+
+See `make help` for all available `make` targets. Also see [`.drone.yml`](https://github.com/go-gitea/gitea/blob/master/.drone.yml) to see how our continuous integration works.
+
+## Building continuously
+
+To run and continously rebuild when source files change:
+
+````bash
+make watch
+````
+
+On macOS, watching all backend source files may hit the default open files limit which can be increased via `ulimit -n 12288` for the current shell or in your shell startup file for all future shells.
+
+### Formatting, code analysis and spell check
+
+Our continuous integration will reject PRs that are not properly formatted, fail
+code analysis or spell check.
+
+You should format your code with `go fmt` using:
+
+```bash
+make fmt
+```
+
+and can test whether your changes would match the results with:
+
+```bash
+make fmt-check # which runs make fmt internally
+```
+
+**Note**: The results of `go fmt` are dependent on the version of `go` present.
+You should run the same version of go that is on the continuous integration
+server as mentioned above. `make fmt-check` will only check if your `go` would
+format differently - this may be different from the CI server version.
+
+You should run revive, vet and spell-check on the code with:
+
+```bash
+make revive vet misspell-check
+```
+
+### Working on JS and CSS
+
+Either use the `watch-frontend` target mentioned above or just build once:
+
+```bash
+make build && ./gitea
+```
+
+Before committing, make sure the linters pass:
+
+```bash
+make lint-frontend
+```
+
+Note: When working on frontend code, set `USE_SERVICE_WORKER` to `false` in `app.ini` to prevent undesirable caching of frontend assets.
+
+### Building and adding SVGs
+
+SVG icons are built using the `make svg` target which compiles the icon sources defined in `build/generate-svg.js` into the output directory `public/img/svg`. Custom icons can be added in the `web_src/svg` directory.
+
+### Building the Logo
+
+The PNG versions of the logo are built from a single SVG source file `assets/logo.svg` using the `make generate-images` target. To run it, Node.js and npm must be available. The same process can also be used to generate a custom logo PNGs from a SVG source file. It's possible to remove parts of the SVG logo for the favicon build by adding a `detail-remove` class to the SVG nodes to be removed.
+
+### Updating the API
+
+When creating new API routes or modifying existing API routes, you **MUST**
+update and/or create [Swagger](https://swagger.io/docs/specification/2-0/what-is-swagger/)
+documentation for these using [go-swagger](https://goswagger.io/) comments.
+The structure of these comments is described in the [specification](https://goswagger.io/use/spec.html#annotation-syntax).
+If you want more information about the Swagger structure, you can look at the
+[Swagger 2.0 Documentation](https://swagger.io/docs/specification/2-0/basic-structure/)
+or compare with a previous PR adding a new API endpoint, e.g. [PR #5483](https://github.com/go-gitea/gitea/pull/5843/files#diff-2e0a7b644cf31e1c8ef7d76b444fe3aaR20)
+
+You should be careful not to break the API for downstream users which depend
+on a stable API. In general, this means additions are acceptable, but deletions
+or fundamental changes to the API will be rejected.
+
+Once you have created or changed an API endpoint, please regenerate the Swagger
+documentation using:
+
+```bash
+make generate-swagger
+```
+
+You should validate your generated Swagger file and spell-check it with:
+
+```bash
+make swagger-validate misspell-check
+```
+
+You should commit the changed swagger JSON file. The continous integration
+server will check that this has been done using:
+
+```bash
+make swagger-check
+```
+
+**Note**: Please note you should use the Swagger 2.0 documentation, not the
+OpenAPI 3 documentation.
+
+### Creating new configuration options
+
+When creating new configuration options, it is not enough to add them to the
+`modules/setting` files. You should add information to `custom/conf/app.ini`
+and to the
+<a href='{{< relref "doc/advanced/config-cheat-sheet.en-us.md" >}}'>configuration cheat sheet</a>
+found in `docs/content/doc/advanced/config-cheat-sheet.en-us.md`
+
+### Changing the logo
+
+When changing the Gitea logo SVG, you will need to run and commit the results
+of:
+
+```bash
+make generate-images
+```
+
+This will create the necessary Gitea favicon and others.
+
+### Database Migrations
+
+If you make breaking changes to any of the database persisted structs in the
+`models/` directory, you will need to make a new migration. These can be found
+in `models/migrations/`. You can ensure that your migrations work for the main
+database types using:
+
+```bash
+make test-sqlite-migration # with sqlite switched for the appropriate database
+```
+
+## Testing
+
+There are two types of test run by Gitea: Unit tests and Integration Tests.
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make test # Runs the unit tests
+```
+
+Unit tests will not and cannot completely test Gitea alone. Therefore, we
+have written integration tests; however, these are database dependent.
+
+```bash
+TAGS="bindata sqlite sqlite_unlock_notify" make build test-sqlite
+```
+
+will run the integration tests in an sqlite environment. Integration tests
+require `git lfs` to be installed. Other database tests are available but
+may need adjustment to the local environment.
+
+Look at
+[`integrations/README.md`](https://github.com/go-gitea/gitea/blob/master/integrations/README.md)
+for more information and how to run a single test.
+
+Our continuous integration will test the code passes its unit tests and that
+all supported databases will pass integration test in a Docker environment.
+Migration from several recent versions of Gitea will also be tested.
+
+Please submit your PR with additional tests and integration tests as
+appropriate.
+
+## Documentation for the website
+
+Documentation for the website is found in `docs/`. If you change this you
+can test your changes to ensure that they pass continuous integration using:
+
+```bash
+# from the docs directory within Gitea
+make trans-copy clean build
+```
+
+You will require a copy of [Hugo](https://gohugo.io/) to run this task. Please
+note: this may generate a number of untracked git objects, which will need to
+be cleaned up.
+
+## Visual Studio Code
+
+A `launch.json` and `tasks.json` are provided within `contrib/ide/vscode` for
+Visual Studio Code. Look at
+[`contrib/ide/README.md`](https://github.com/go-gitea/gitea/blob/master/contrib/ide/README.md)
+for more information.
+
+## Submitting PRs
+
+Once you're happy with your changes, push them up and open a pull request. It
+is recommended that you allow Gitea Managers and Owners to modify your PR
+branches as we will need to update it to master before merging and/or may be
+able to help fix issues directly.
+
+Any PR requires two approvals from the Gitea maintainers and needs to pass the
+continous integration. Take a look at our
+[`CONTRIBUTING.md`](https://github.com/go-gitea/gitea/blob/master/CONTRIBUTING.md)
+document.
+
+If you need more help pop on to [Discord](https://discord.gg/gitea) #Develop
+and chat there.
+
+That's it! You are ready to hack on Gitea.
--- /dev/null
+---
+date: "2019-04-15T17:29:00+08:00"
+title: "Integrations"
+slug: "integrations"
+weight: 40
+toc: true
+draft: false
+menu:
+ sidebar:
+ parent: "developers"
+ name: "Integrations"
+ weight: 65
+ identifier: "integrations"
+---
+
+# Integrations
+
+Gitea has a wonderful community of third-party integrations, as well as first-class support in various other
+projects.
+
+We are curating a list over at [awesome-gitea](https://gitea.com/gitea/awesome-gitea) to track these!
+
+If you are looking for [CI/CD](https://gitea.com/gitea/awesome-gitea#devops),
+an [SDK](https://gitea.com/gitea/awesome-gitea#sdk),
+or even some extra [themes](https://gitea.com/gitea/awesome-gitea#themes),
+you can find them listed in the [awesome-gitea](https://gitea.com/gitea/awesome-gitea) repository!
--- /dev/null
+---
+date: "2019-04-15T17:29:00+08:00"
+title: "Migrations Interfaces"
+slug: "migrations-interfaces"
+weight: 30
+toc: true
+draft: false
+menu:
+ sidebar:
+ parent: "developers"
+ name: "Migrations Interfaces"
+ weight: 55
+ identifier: "migrations-interfaces"
+---
+
+# Migration Features
+
+Complete migrations were introduced in Gitea 1.9.0. It defines two interfaces to support migrating
+repository data from other git host platforms to Gitea or, in the future, migrating Gitea data to other
+git host platforms.
+Currently, migrations from Github, Gitlab, and other Gitea instances are implemented.
+
+First of all, Gitea defines some standard objects in packages [modules/migrations/base](https://github.com/go-gitea/gitea/tree/master/modules/migrations/base).
+They are `Repository`, `Milestone`, `Release`, `ReleaseAsset`, `Label`, `Issue`, `Comment`, `PullRequest`, `Reaction`, `Review`, `ReviewComment`.
+
+## Downloader Interfaces
+
+To migrate from a new git host platform, there are two steps to be updated.
+
+- You should implement a `Downloader` which will be used to get repository information.
+- You should implement a `DownloaderFactory` which will be used to detect if the URL matches and create the above `Downloader`.
+ - You'll need to register the `DownloaderFactory` via `RegisterDownloaderFactory` on `init()`.
+
+You can find these interfaces in [downloader.go](https://github.com/go-gitea/gitea/blob/master/modules/migrations/base/downloader.go).
+
+## Uploader Interface
+
+Currently, only a `GiteaLocalUploader` is implemented, so we only save downloaded
+data via this `Uploader` to the local Gitea instance. Other uploaders are not supported at this time.
+
+You can find these interfaces in [uploader.go](https://github.com/go-gitea/gitea/blob/master/modules/migrations/base/uploader.go).
--- /dev/null
+---
+date: "2019-04-19:44:00+01:00"
+title: "OAuth2 provider"
+slug: "oauth2-provider"
+weight: 41
+toc: true
+draft: false
+menu:
+ sidebar:
+ parent: "developers"
+ name: "OAuth2 Provider"
+ weight: 41
+ identifier: "oauth2-provider"
+---
+
+
+# OAuth2 provider
+
+Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0.
+
+## Endpoints
+
+
+Endpoint | URL
+-----------------------|----------------------------
+Authorization Endpoint | `/login/oauth/authorize`
+Access Token Endpoint | `/login/oauth/access_token`
+
+
+## Supported OAuth2 Grants
+
+At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) extension.
+
+
+To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings.
+
+## Scopes
+
+Currently Gitea does not support scopes (see [#4300](https://github.com/go-gitea/gitea/issues/4300)) and all third party applications will be granted access to all resources of the user and his/her organizations.
+
+## Example
+
+**Note:** This example does not use PKCE.
+
+1. Redirect to user to the authorization endpoint in order to get his/her consent for accessing the resources:
+
+```curl
+https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE
+```
+
+The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks.
+
+
+
+
+The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example:
+
+```curl
+https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
+```
+
+2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
+
+```curl
+POST https://[YOUR-GITEA-URL]/login/oauth/access_token
+```
+
+```json
+{
+ "client_id": "YOUR_CLIENT_ID",
+ "client_secret": "YOUR_CLIENT_SECRET",
+ "code": "RETURNED_CODE",
+ "grant_type": "authorization_code",
+ "redirect_uri": "REDIRECT_URI"
+}
+```
+
+Response:
+```json
+{
+"access_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
+"token_type":"bearer",
+"expires_in":3600,
+"refresh_token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
+}
+```
+
+The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings.
+
+The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request.
+
+3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources.
## What is Swagger?
[Swagger](https://swagger.io/) is what Gitea uses for its API.
All Gitea instances have the built-in API, though it can be disabled by setting `ENABLE_SWAGGER` to `false` in the `api` section of your `app.ini`
-For more information, refer to Gitea's [API docs]({{< relref "doc/advanced/api-usage.en-us.md" >}})
+For more information, refer to Gitea's [API docs]({{< relref "doc/developers/api-usage.en-us.md" >}})
[Swagger Example](https://try.gitea.io/api/swagger)
1. By only whitelisting certain domains with OpenID (see below)
2. Setting `ENABLE_CAPTCHA` to `true` in your `app.ini` and properly configuring `RECAPTCHA_SECRET` and `RECAPTCHA_SITEKEY`
-3. Settings `DISABLE_REGISTRATION` to `true` and creating new users via the [CLI]({{< relref "doc/usage/command-line.en-us.md" >}}), [API]({{< relref "doc/advanced/api-usage.en-us.md" >}}), or Gitea's Admin UI
+3. Settings `DISABLE_REGISTRATION` to `true` and creating new users via the [CLI]({{< relref "doc/usage/command-line.en-us.md" >}}), [API]({{< relref "doc/developers/api-usage.en-us.md" >}}), or Gitea's Admin UI
### Only allow certain email domains
You can configure `EMAIL_DOMAIN_WHITELIST` in your app.ini under `[service]`
## Recommended server configuration
-**NOTE:** Many of the following directories can be configured using [Environment Variables]({{< relref "doc/advanced/specific-variables.en-us.md" >}}) as well!
+**NOTE:** Many of the following directories can be configured using [Environment Variables]({{< relref "doc/advanced/environment-variables.en-us.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
**Note 2**: Go version {{< min-go-version >}} or higher is required. However, it is recommended to
obtain the same version as our continuous integration, see the advice given in
-<a href='{{< relref "doc/advanced/hacking-on-gitea.en-us.md" >}}'>Hacking on
+<a href='{{< relref "doc/developers/hacking-on-gitea.en-us.md" >}}'>Hacking on
Gitea</a>
## Download
- `go` {{< min-go-version >}} or higher, see [here](https://golang.org/dl/)
- `node` {{< min-node-version >}} or higher with `npm`, see [here](https://nodejs.org/en/download/)
-- `make`, see <a href='{{< relref "doc/advanced/make.en-us.md" >}}'>here</a>
+- `make`, see <a href='{{< relref "doc/developers/hacking-on-gitea.en-us.md" >}}#installing-make'>here</a>
Various [make tasks](https://github.com/go-gitea/gitea/blob/master/Makefile)
are provided to keep the build process as simple as possible.
/ /zh-cn/ 302! Language=zh-cn
/ /zh-tw/ 302! Language=zh-tw
/ /en-us/ 302!
+
+/en-us/ci-cd/ /en-us/integrations/ 302!
+/en-us/third-party-tools/ /en-us/integrations/ 302!
+/en-us/make/ /en-us/hacking-on-gitea/ 302!
projects / gitea.git / commitdiff