# Gitea Compatibility This document tracks the compatibility between **Gitea Mail Templates** releases and **Gitea** versions. ## Compatibility Matrix Choose by your **Gitea version**, not by the highest template tag. [PASS] means a documented compatible combination; [PENDING] has not been verified. Legacy [PASS] entries retain the project's earlier compatibility assessment and were not re-tested on every patch release during this documentation update. | Gitea version | Recommended template release | Status | Notes | |---------------|------------------------------|--------|-------| | 28.1.0 | — | [PENDING] | Compatibility verification pending | | 28.0.0 | **v28.0.0** | [PASS] | Earlier template releases use the removed `FileSize` mail function | | 1.27.3 | **v1.27.3** | [PASS] | Push-to-PR commit links fixed in every theme | | 1.27.2 | **v1.27.3** | [PASS] | Matching v1.27.2 has a push-notification defect in Bloom, Ember, and Heritage | | 1.27.1 | **v1.27.3** | [PASS] | Older v1.0.x templates use obsolete push-commit fields; v1.27.2 is only partially fixed | | 1.27.0 | — | [PENDING] | New commit data shape breaks older push templates; v1.27.3 is a plausible fix but was not release-tested here | | 1.26.4 | **v1.0.1** | [PASS] | — | | 1.26.3 | **v1.0.1** | [PASS] | — | | 1.26.2 | **v1.0.1** | [PASS] | — | | 1.26.1 | **v1.0.1** | [PASS] | — | | 1.26.0 | **v1.0.1** | [PASS] | — | | 1.25.5 | **v1.0.1** | [PASS] | — | | 1.25.0 | **v1.0.1** | [PASS] | — | v1.0.1 retains the pre-1.27 push-commit fields used by the listed Gitea 1.25/1.26 releases. Gitea 1.24.x and earlier use a different custom-mail-template layout and are [UNSUPPORTED]. The v1.0.0 template tag is superseded by v1.0.1; it is not a separate recommendation. > **Latest verified:** Release v28.0.0 passes the Gitea 28.0.0 mail-template, mailer-context, function, and translation-key source audit plus all-theme rendering tests. For other Gitea versions, follow the per-version matrix above. ## Versioning and Known Exceptions Release tags name actual downloadable packages. A matching version is useful, but it is not a compatibility guarantee: v1.27.2 has a known defect, and there is no v1.27.1 template tag. Use the recommended package in the matrix; do not infer support from a tag number or from the current `main` branch. - Gitea 1.27.0 changed the push-to-PR commit data shape. Gitea 1.27.1 fixed its **bundled** mail template, but custom overrides still need the new `.UserCommit.GitCommit` path. v1.27.2 updated seven themes; v1.27.3 completed the remaining three. Older v1.0.x templates use the pre-1.27 path. See the [upstream regression report](https://github.com/go-gitea/gitea/issues/38469), [upstream fix](https://github.com/go-gitea/gitea/pull/38467), and [v1.27.2 correction](.github/release-notes/v1.27.2.md). - Gitea 28.0.0 removed the mail-template `FileSize` function in favor of `FormatByteSize` ([mail function map](https://raw.githubusercontent.com/go-gitea/gitea/v28.0.0/modules/templates/mail.go)). v28.0.0 uses the new function; older template releases can fail when rendering release attachments. Conversely, v28.0.0 is not a drop-in replacement for earlier Gitea mail contexts. - A source-only fix is **unreleased** until its tag and downloadable archive exist. New upstream versions remain [PENDING] until their compatibility is checked. ## Check Your Gitea Version ```bash # On your Gitea server: gitea --version # Or check the web UI footer / Site Administration → Monitoring ``` ## Gitea Version History — Mail Template Impact This table describes changes in **Gitea**, not fixes in this template repository. `None` means no relevant new mail-template impact for that Gitea release; the recommended archive is listed in the matrix above. | Gitea | Release Date | Mail Template Changes | Impact | |-------|-------------|-----------------------|--------| | **28.1.0** | 2026-10-06 | [PENDING] Review of mail-template changes | TBD | | **28.0.0** | 2026-09-29 | `FileSize` replaced by `FormatByteSize`; mail template internals reorganized | **Breaking:** legacy release-attachment templates can fail | | **1.27.3** | 2026-08-29 | None | None | | **1.27.2** | 2026-08-14 | None | None | | **1.27.1** | 2026-07-27 | Bundled push template updated to `.UserCommit.GitCommit` ([fix](https://github.com/go-gitea/gitea/pull/38467)) | **Existing incompatibility persists:** old custom push-to-PR templates can fail | | **1.27.0** | 2026-07-13 | Push commit data moved under `.UserCommit.GitCommit` ([report](https://github.com/go-gitea/gitea/issues/38469)) | **Breaking:** old push-to-PR templates can fail | | **1.26.4** | 2026-06-21 | None | None | | **1.26.3** | 2026-06-20 | None | None | | **1.26.2** | 2026-05-20 | None | None | | **1.26.1** | 2026-04-22 | None | None | | **1.26.0** | 2026-04-19 | None | None | | **1.25.5** | 2026-03-10 | None | None | | **1.25.0** | 2025 | Custom-mail paths and subject/body format changed ([refactor](https://github.com/go-gitea/gitea/pull/35150)) | **Breaking:** older template layout is not supported | | **≤ 1.24.x** | — | Legacy custom-mail layout | [UNSUPPORTED] | ## Template Variable Reference All 11 template types use only Gitea built-in variables and functions. Verified against Gitea source (`services/mailer/` + `modules/templates/mail.go`). ### Relevant Template Functions | Function | Gitea version | Notes | |----------|---------------|-------| | `AppName` | ≤ 1.21 | Application name | | `AppUrl` | ≤ 1.21 | Application base URL | | `AppDomain` | ≤ 1.21 | Server domain | | `DotEscape` | ≤ 1.21 | Prevents auto-linking of dotted text | | `QueryEscape` | ≤ 1.21 | URL query encoding | | `PathEscapeSegments` | ≤ 1.21 | Per-segment path encoding | | `ShortSha` | ≤ 1.21 | Truncated commit hash | | `FileSize` | Before 28.0.0 | Used by older template releases for attachment sizes; unavailable in Gitea 28 mail templates | | `FormatByteSize` | 28.0.0 | Used by v28.0.0 for attachment sizes; unavailable in earlier Gitea mail templates | | `HTMLFormat` | ≤ 1.21 | Render string as safe HTML | | `Iif` | ≤ 1.21 | Inline conditional | | `dict` | ≤ 1.21 | Build maps from key-value pairs | | `Eval` | ≤ 1.21 | Evaluate template tokens | | `StringUtils` | ≤ 1.21 | String manipulation helpers | | `SliceUtils` | ≤ 1.21 | Slice manipulation helpers | | `JsonUtils` | ≤ 1.21 | JSON helpers | | `DumpVar` | ≤ 1.21 | Debug variable dump | ### Data Contexts by Template | Template | Key Variables | |----------|--------------| | `user/auth/activate` | `DisplayName`, `Code`, `ActiveCodeLives` | | `user/auth/activate_email` | `DisplayName`, `Code`, `Email`, `ActiveCodeLives` | | `user/auth/register_notify` | `DisplayName`, `Username` | | `user/auth/reset_passwd` | `DisplayName`, `Code`, `ResetPwdCodeLives` | | `org/team_invite` | `Inviter`, `Team`, `Organization`, `InviteURL`, `Invite` | | `repo/collaborator` | `Subject`, `RepoName`, `Link` | | `repo/transfer` | `Doer`, `User`, `Repo`, `Link`, `Destination` | | `repo/release` | `Release` (with `Publisher`, `TagName`, `Title`, `RenderedNote`, `Attachments`), `Link` | | `repo/actions/workflow_run` | `Run` (with `WorkflowID`, `HTMLURL`), `Jobs`, `RunStatusText` | | `repo/issue/assigned` | `Doer`, `Issue`, `Link`, `IsPull` | | `repo/issue/default` | `Doer`, `Issue`, `Link`, `Body`, `ActionName`, `Comment`, `IsPull`, `IsMention`, `ReviewComments`, `CanReply` | > [WARN] **`.DisplayName`** is not available in collaborator, transfer, release, workflow_run, assigned, and default templates — do not reference it. ### Translation Keys All templates use Gitea's official `mail.*` translation namespace. Every referenced key was checked against Gitea 28.0.0's English locale file. ## How Compatibility Is Verified 1. **Local validation** — run `go test ./...` and `go run . preview all` from `tools/`; the preview function map mirrors Gitea 28.0.0 2. **Source audit** — Template data contexts are cross-referenced against Gitea's `services/mailer/` package 3. **Regression tests** — Go tests render push notifications and release attachments in every discovered theme 4. **Release checklist** — Each release records its verified Gitea version in the matrix above ## Version Tracking The [tracker workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/gitea-tracker.yml) scans all repository Markdown files. A participating document declares its subject/content pairs in a `DOC-TAGS` JSON comment, then encloses each managed body between `` and `` (or `RELEASE` equivalents). Only the first block for a repeated pair in a document is processed. `TRACKER:VERSION-MAP` and `TRACKER:HISTORY` add pending rows; `TRACKER:UPSTREAM` updates upstream versions and status; `TRACKER:BADGE` retains the last tested version. On template publication, the [release workflow](https://gitea.kenanzhu.com/KenanZhu/GiteaMailTemplates/src/branch/main/.github/workflows/release.yml) updates `RELEASE:HEADER`, `RELEASE:SUMMARY`, and `RELEASE:CURRENT` labels; their links stay fixed at `/releases/latest`, and published tags remain unchanged. `TRACKER:LATEST-TESTED` and `TRACKER:LATEST-VERIFIED` are manual-only and change only after verification. The script rejects undeclared, unknown, or unclosed blocks and missing declarations. Actions execution and write permissions have not been verified on this Gitea host; until then, check [upstream Gitea releases](https://github.com/go-gitea/gitea/releases) and published assets manually. Publish a new template tag only when template content changes (see [Versioning and Known Exceptions](#versioning-and-known-exceptions)). ## Reporting Issues If you find a compatibility problem with a specific Gitea version: 1. Check the [Gitea changelog](https://github.com/go-gitea/gitea/blob/main/CHANGELOG.md) for recent mail template changes 2. Open an issue with: your Gitea version, which template, and the error