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>
The `usage/actions/runner` has duplicated runner documentations as `/runner`. This PR remove the duplicated content and leave obtain registry token in `usage/actions/runner` and runner install/configurations in `/runner`.
Reviewed-on: https://gitea.com/gitea/docs/pulls/479
Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>
Fixes https://gitea.com/gitea/docs/issues/386
`gitea.event` was documented as `{...}` only. Adds an "Event payload" section listing the commonly used fields per event, including `gitea.event.schedule`, and notes where Gitea's payloads deviate from GitHub's.
Also corrects the trigger event table:
1. `pull_request` takes `synchronize`, not `synchronized`
1. `workflow_run` also emits `in_progress`
1. `schedule`, `workflow_call` and `pull_request_target` were missing
Reviewed-on: https://gitea.com/gitea/docs/pulls/478
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
Documents the WebSocket endpoint `/-/ws` added in https://github.com/go-gitea/gitea/pull/36965 and fixes the examples that could not serve it.
1. Nginx: adds the missing `proxy_http_version 1.1`, without it Nginx talks HTTP/1.0 upstream and Gitea rejects the handshake.
1. Apache HTTPD: `upgrade=websocket` on the existing `ProxyPass` rule, handled by `mod_proxy_http` since 2.4.48.
1. Nginx Proxy Manager: use the `Websockets Support` toggle, a duplicate `proxy_http_version` stops Nginx from starting.
1. IIS: the `WebSocket Protocol` Windows feature is required.
---------
Co-authored-by: silverwind <2021+silverwind@noreply.gitea.com>
Co-authored-by: silverwind <me@silverwind.io>
Co-authored-by: mohammad rahimi <indo@epid.co>
Reviewed-on: https://gitea.com/gitea/docs/pulls/463
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Reviewed-by: silverwind <2021+silverwind@noreply.gitea.com>
Co-authored-by: mohammad rahimi <218245+mohammad-rj@noreply.gitea.com>
Lunny Xiaoandbircni
wxiaoguang
yangchuanshengandLunny Xiao
Erik Bloß
TheFox0x7andLunny Xiao
SudhanshuSingh
Zettat123andLunny Xiao
nico-i
Zettat123
harryzcyandChongyi Zheng