GiteaMailTemplates/COMPATIBILITY.md

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, upstream fix, and v1.27.2 correction.
• Gitea 28.0.0 removed the mail-template FileSize function in favor of FormatByteSize (mail function map). 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

# 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)	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)	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)	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 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 <!-- TRACKER:CONTENT --> and <!-- /TRACKER:CONTENT --> (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 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 and published assets manually. Publish a new template tag only when template content changes (see Versioning and Known Exceptions).

Reporting Issues

If you find a compatibility problem with a specific Gitea version:

1. Check the Gitea changelog for recent mail template changes
2. Open an issue with: your Gitea version, which template, and the error