The database preparation page covered only MySQL and PostgreSQL. MSSQL setups without schema permissions break on upgrades, like in https://github.com/go-gitea/gitea/issues/40256.
The new section shows the login, database and user setup with the roles Gitea needs, for main and 28, including zh-cn and zh-tw.
_Written by Claude (Opus 5.5)._
Reviewed-on: https://gitea.com/gitea/docs/pulls/636
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
Documents https://github.com/go-gitea/gitea/pull/40144 for main, which adds `read:commitstatus` and `write:commitstatus` token scopes so CI integrations can report commit statuses without full repository access. The repository scopes include them.
Adds the scope to the OAuth2 provider scope table and the API usage permission list. Draft until the Gitea PR merges.
_Written by Claude (Opus 5.5)._
---------
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/622
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
Documents https://github.com/go-gitea/gitea/pull/40036 for main, which renames the built-in tea OAuth2 application to gitea-cli and keeps `tea` as an alias in `[oauth2] DEFAULT_APPLICATIONS`.
The default list and the pre-configured applications table also gain the missing gitea-app and gitea-vscode entries.
_Written by Claude (Opus 5.5)._
---------
Co-authored-by: bircni <bircni@icloud.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/620
Reviewed-by: bircni <bircni@icloud.com>
Co-authored-by: silverwind <me@silverwind.io>
https://gitea.com/gitea/runner/pulls/1358 mirrors every built-in `GITHUB_*` variable as `GITEA_*`. The variables page now lists both names for each, in the same paired style as the context table.
It also adds variables that runners already set but the page left out (`*_ACTOR_ID`, `*_REF_PROTECTED`, `*_REPOSITORY_ID`, `*_REPOSITORY_OWNER_ID`, `*_TRIGGERING_ACTOR`, `*_WORKFLOW_SHA`, `ACT`, `ImageOS`, `RUNNER_DEBUG`, `RUNNER_ENVIRONMENT`, `RUNNER_NAME`, `RUNNER_WORKSPACE`, `TRACEPARENT`, `TRACESTATE`).
Examples copied from GitHub's runner (`/home/runner/work/_temp/...` paths, `__run`, `ghs_***`) are replaced with the values gitea-runner and Gitea actually produce, using placeholder users, repositories and instance URLs.
The zh-cn and zh-tw pages get the environment variable section they never had.
Reviewed-on: https://gitea.com/gitea/docs/pulls/618
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
Document https://github.com/go-gitea/gitea/pull/39190, which reads the RFC 7239 `Forwarded` header when `X-Forwarded-For` is absent and keeps the forwarded client port.
- `REVERSE_PROXY_LIMIT`: list `X-Real-IP`, `X-Forwarded-For` and `Forwarded` in the order they are read, and where the client port comes from, also in zh-cn and zh-tw
- Reverse proxies: require the proxy to set `X-Real-IP`, since Caddy, Apache and HAProxy pass a client-sent one through by default, and mention `X-Real-Port` for logging the client port
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/560
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Packages belong to the owner, so a team's packages permission covers every package of the organization, regardless of the team's repositories. State that in the access restrictions section, matching the team settings change in https://github.com/go-gitea/gitea/pull/39953.
The old note announced a dedicated team permission for finer control, which has existed since the packages unit was added, so it is replaced.
Reviewed-on: https://gitea.com/gitea/docs/pulls/605
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
Fixes the binary-install restore example in the Backup and Restore docs.
The default `[repository] ROOT` is `{APP_DATA_PATH}/gitea-repositories`, but the example restored repos to `/var/lib/gitea/data/repositories/`, so restored repositories did not show up. Changed it to `/var/lib/gitea/data/gitea-repositories/`.
The Docker and Docker-rootless examples are unchanged: their app.ini templates set `[repository] ROOT` explicitly, so their paths are already correct.
Refs go-gitea/gitea#39736
---------
Co-authored-by: silverwind <me@silverwind.io>
Co-authored-by: silverwind <2021+silverwind@noreply.gitea.com>
Co-authored-by: souvik-biswas-dev <souvikbiswas.dev@gmail.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/601
Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>
Co-authored-by: souvikbiswasdev <258416+souvikbiswasdev@noreply.gitea.com>
The runner pages had drifted from the runner. They claimed Podman is unsupported, a registration retry limit of 10, a `container.env` proxy override that has no effect, and they used the deprecated `generate-config` command, while the actual instructions were buried under implementation details.
The develop and 5.x pages are rewritten from the current runner sources (`main` is `v5.2.0`). They are shorter and aimed at operators, with a new page covering what jobs get. The reference generator now documents the `config` command, and the quickstart pages in every language use the `gitea-runner` binary name.
Reviewed-on: https://gitea.com/gitea/docs/pulls/600
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
The Docker Compose example currently mounts the PostgreSQL data directory to `/var/lib/postgresql/data`.
With PostgreSQL 18, the official PostgreSQL Docker image expects the volume to be mounted at `/var/lib/postgresql` instead. Mounting `/var/lib/postgresql/data` causes the container to fail during startup because the image detects PostgreSQL data at an unused mount point.
This change updates the example to use the recommended `/var/lib/postgresql` mount path for PostgreSQL 18 and newer.
---------
Co-authored-by: silverwind <me@silverwind.io>
Reviewed-on: https://gitea.com/gitea/docs/pulls/570
Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>
Co-authored-by: JWheelMaker <250540+jwheelmaker@noreply.gitea.com>
Documents the settings changed by https://github.com/go-gitea/gitea/pull/39426: `EGRESS_MODE`, the `[migrations]` `ALLOWED_HOST_LIST`/`BLOCKED_HOST_LIST` replacing `ALLOWED_DOMAINS`, `BLOCKED_DOMAINS` and `ALLOW_LOCALNETWORKS`, and the host list syntax with ports, CGNAT and reserved addresses. Also fixes the `socks://` examples, Go only speaks `socks5://`.
_Written by Claude._
---------
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: TheFox0x7 <thefox0x7@gmail.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/557
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
Fixes https://github.com/go-gitea/gitea/issues/39310
The docker install pages tell readers to use `:nightly` / `:nightless-rootless` for the latest development version, but those tags are no longer published — the registry only carries `main-nightly` and `main-nightly-rootless` (plus the per-release-branch `1.x-nightly` tags):
```
$ curl -s https://docker.gitea.com/v2/gitea/tags/list?n=1000 | tr ',' '\n' | grep -E '"(main-)?nightly(-rootless)?"'
"main-nightly"
"main-nightly-rootless"
```
Anyone who followed the rootless page has been pinned to an image that has not been rebuilt since 2025-08-23.
Changes:
- point the docker and rootless docker install pages at `:main-nightly` / `:main-nightly-rootless`, in English and in the zh-cn/zh-tw translations
- use `1.27-nightly` instead of the long gone `1.16-nightly` as the release branch example (the oldest one still published is `1.19-nightly`)
- fix the zh-cn/zh-tw claim that `:latest` installs a development version, and mention the nightly tags there the way the English page does
- render `@dockerVersion@` as `main-nightly` for the next version, so the compose snippets on the unreleased docs no longer reference `gitea:nightly`
Not touched: the 1.22–1.26 versioned docs carry the same stale tag, but those versions are already out of maintenance — happy to include them if preferred.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- cloudflare-preview --> Preview: https://pr-550.docs-gitea-com.pages.dev
---------
Co-authored-by: bircni <bircni@icloud.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/550
Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Several cron tasks in the cheat sheet listed `ENABLE_SUCCESS_NOTICE` or `NO_SUCCESS_NOTICE`. Gitea reads neither, only `NOTICE_ON_SUCCESS`. `NO_SUCCESS_NOTICE` was removed in https://github.com/go-gitea/gitea/pull/19221.
1. Replace both dead keys with `NOTICE_ON_SUCCESS` (default `false`).
2. Fix "Notice if not success" descriptions, which inverted the key's meaning.
3. List the key for `cleanup_hook_task_table`, `cleanup_actions`, `cleanup_action_runs` and `gc_lfs`, which honor it but omitted it.
Matches https://github.com/go-gitea/gitea/pull/39352.
Written by Claude.
Reviewed-on: https://gitea.com/gitea/docs/pulls/552
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
Two unrelated but small fixes, closes#258 and closes#32.
**The reference does not name its types (#258)**
Since the api reference is rendered from the openapi 3.0 document, a field of type `ReviewStateType` is rendered as the bare string enum the `$ref` points at: starlight-openapi dereferences everything and the schema has no `title`, so the name of the type is nowhere on the page. Searching the current reference for `ReviewStateType` returns nothing, which is what the issue reports (the plugin also has no route for `components/schemas`, so there is no page per type either).
`normalizeSchema()` now titles every named schema of an openapi 3.0 document with its own name, which the plugin renders next to the type of a field:
- before: `state` · `string` · Allowed values: APPROVED …
- after: `state` · `ReviewStateType` · `string` · Allowed values: APPROVED …
The go doc comments start with the name of the type, so the description would repeat it ("ChangeFilesOptions — ChangeFilesOptions options for creating …"); a leading `<name> ` is stripped from the description.
For the record, how the three generations of documents describe that type:
| Versions | Type name | Allowed values |
| --- | --- | --- |
| 1.22 – 1.25 (swagger, `ReviewStateType` definition without `enum`) | shown | missing |
| 1.26 – 1.27 (swagger, enum inlined upstream) | missing | shown |
| 1.27, next (openapi 3.0, with this change) | shown | shown |
The released swagger documents are frozen, so 1.22 – 1.26 keep what they have; from 1.27 on the reference answers the question the issue asks.
**Gmail needs an app password (#32)**
The configuration in the guide is still correct after Google turned off password-only access, because it already asks for an app password. What was missing is why there is no alternative: Gitea's mailer authenticates with `CRAM-MD5`, `PLAIN` or `LOGIN` and has no XOAUTH2, so "Sign in with Google" is not an option. Added that, together with the two things people run into — an app password needs 2-step verification and a Workspace administrator can disable app passwords for the domain — and the `587` + `smtp+starttls` variant.
Verified by building the api and the next docs: the type names show up on the operation pages, the descriptions are not duplicated, and 1.26 and older are unchanged. `pnpm check` passes.
<!-- cloudflare-preview --> Preview: https://pr-541.docs-gitea-com.pages.dev
---------
Co-authored-by: bircni <bircni@icloud.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/541
Reviewed-by: bircni <bircni@icloud.com>
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Closes#243.
The `sha` of the contents API is compared against the ID of the blob the commit has at that path, and for a file tracked by Git LFS that blob is the pointer file. Sending the `lfs_oid` or a checksum of the file content fails with `sha does not match`, and nothing in the documentation said so.
Adds a section to the LFS page: use the `sha` from `GET /repos/{owner}/{repo}/contents/{filepath}`, not `lfs_oid`, and note that the API does turn the content into an LFS object by itself when `.gitattributes` tracks the path (`modifyFile()` stores the object and commits the pointer), so nothing else has to be done differently.
The swagger comments upstream are being fixed in https://github.com/go-gitea/gitea/pull/38915, which will reach `/api/next/` through the scheduled job and the released reference with 1.28. The documents of 1.22 – 1.27 are frozen, so the guide is the only place where readers of the current release can find it.
<!-- cloudflare-preview --> Preview: https://pr-542.docs-gitea-com.pages.dev
Reviewed-on: https://gitea.com/gitea/docs/pulls/542
Reviewed-by: bircni <bircni@icloud.com>
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
## Summary
Adds Sealos to the cloud-provider installation page for the current and next
Gitea documentation.
## Why
Sealos provides a public, community-maintained one-click Gitea template. The
entry fits alongside the existing Cloudron, Linode, alwaysdata, and Exoscale
options.
## Proposed files
- `docs/installation/on-cloud-provider.md`
- `versioned_docs/version-1.27/installation/on-cloud-provider.md`
## Validation
- Sealos App Store: https://sealos.io/products/app-store/gitea
- Template source: https://github.com/labring-actions/templates/tree/kb-0.9/template/gitea
- Gitea image: `docker.gitea.com/gitea:1.27.0-rootless`
- Live deployment validated on 2026-07-24
- Verified administrator initialization, login, repository creation, commits,
issues, release uploads, persistence, and S3 upload, read, and delete flows
## Maintenance
I maintain the Sealos template and can update the documentation when its
deployment path changes. Deployment-specific support is handled in the
[Sealos templates repository](https://github.com/labring-actions/templates/issues).
## AI assistance
This proposal was prepared with OpenAI Codex assistance. I reviewed the
deployment evidence and proposed content and will personally handle review
feedback.
---------
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/525
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: yangchuansheng <yangchuansheng33@gmail.com>
Five documentation fixes that do not depend on anything upstream.
**PostgreSQL version in the docker guide** (closes#224)
The compose example pinned `postgres:14`, the oldest version Gitea still tests against, and PostgreSQL does not upgrade its data directory on its own, so every new deployment that copies the example is one major upgrade behind from day one. The example now uses `postgres:18`, with a note about why the major version is pinned and a pointer to the supported range.
**SELinux** (closes#211)
`setcap 'cap_net_bind_service=+ep'` is what the docs suggest for binding to a port below 1024, but it is denied under SELinux depending on the label of the binary, and it is lost on every upgrade because the capability lives in an extended attribute of the file. A new page describes granting the capability through the systemd unit instead (`AmbientCapabilities`, plus `PrivateUsers=false` when the sandboxing gets in the way), the `semanage fcontext` / `restorecon` labels for the binary and the data directory, and how to read the denials with `ausearch` and `audit2allow`. It is linked from the binary and source installation pages and from the `gitea web` notes.
**OAuth2 and OpenID Connect** (closes#106)
The authentication page documented LDAP, PAM, SMTP, FreeIPA, SPNEGO and the reverse proxy, but not that Gitea can log users in against an external OAuth2 or OpenID Connect provider, which made it look like the only OAuth2 support is Gitea acting as the provider. The new section covers the fields of the authentication source, the callback URL to register at the provider, the group and claim mappings, and the `[oauth2_client]` settings, and separates it from the older OpenID 2.0 sign-in.
**IIS reverse proxy** (closes#39)
Application Request Routing rewrites the host of the `Location` header back to the internal one while "Reverse rewrite host in response headers" is on, which sends the browser to `127.0.0.1:3000` after a sign-in. The IIS section now says to turn it off and where the setting lives.
**ACME in containers** (closes#292)
`ACME_DIRECTORY` defaults to the relative path `https`, which is resolved against the working directory of the process. In the official image that is `/app/gitea`, outside the `/data` volume, so a recreated container asks the CA for a new certificate and runs into the Let's Encrypt limit of 5 certificates per week for the same domains. The HTTPS page now warns about it and shows an absolute path inside the volume; the cheat sheet entry points at the warning. The default itself is being changed in https://github.com/go-gitea/gitea/pull/35851, the note stays useful for every released version.
Only `docs/` is touched, the released versions keep their content.
<!-- cloudflare-preview --> Preview: https://pr-513.docs-gitea-com.pages.dev
Reviewed-on: https://gitea.com/gitea/docs/pulls/513
Reviewed-by: bircni <bircni@icloud.com>
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
wxiaoguangandLunny Xiao
Shudhanshu Singh
Jakub VránaandJakub Vrana
JWheelMakerandsilverwind
wxiaoguang
yangchuanshengandLunny Xiao
Erik Bloß