GiteaMailTemplates/COMPATIBILITY.md

Gitea Compatibility

This document tracks the compatibility between Gitea Mail Templates releases and Gitea versions.

Quick Reference

Template Release	Min Gitea	Max Tested Gitea	Status
v28.0.0	28.0.0	28.0.0	[PASS] Active
v1.27.3	1.25.0	1.27.3	[PASS] Superseded; release emails fail on Gitea 28.0.0 (FileSize removed)
v1.27.2	1.25.0	1.27.3	[WARN] Push notices fail in Bloom, Ember, and Heritage on Gitea 1.27.1+
v1.0.1	1.25.0	1.27.0	[PASS] Superseded; push notices need newer release on 1.27.1+
v1.0.0	1.25.0	1.26.4	[PASS] Superseded

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. This release requires Gitea 28.0.0; use v1.27.3 for Gitea 1.25.0–1.27.3.

Versioning

The release tag identifies the downloadable template package. The supported Gitea version may be appended in parentheses in this compatibility matrix; the parenthesized version is not a Git tag. An unreleased row describes fixes available in the repository but not yet in a downloadable release.

Gitea version	Template release
28.1.0	[PENDING] Compatibility verification; no tested template release yet
28.0.0	v28.0.0; older releases use the removed FileSize function in release emails
1.27.3	v1.27.3; v1.27.2 has a push-notification issue in three themes
1.27.2	v1.27.3; v1.27.2 has the same issue
1.27.1	v1.27.3; v1.27.2 has the same issue

• The tracker workflow records new upstream versions as [PENDING] in this table, the history below, and the marked README and AGENTS lines. Its automatic PR creation has not been verified on the new Gitea host; check releases manually until Gitea automation is configured.
• After verification, update the top Template Release row only when that package has been tested against the new Gitea version. Keep fixes on main marked unreleased until a new tag and downloadable Gitea Release are published; do not assume a tag push uploads archives automatically.
• The older v1.0.1 tag predates the Gitea 1.27.1 push notification data fix and should not be used for Gitea 1.27.1 or newer.
• Gitea 28.0.0 replaces the mail-template FileSize function with FormatByteSize. The two functions are not interchangeable across these Gitea versions; use the matching template release.

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

Gitea	Release Date	Mail Template Changes	Breaking?
28.1.0	2026-10-06	[PENDING] Mail-template compatibility verification	TBD
28.0.0	2026-09-29	FileSize removed and FormatByteSize added; mail templates now have mail/-prefixed internal names and shared head/footer partials; workflow emails gain status-icon fields. Our custom template paths and referenced data fields remain valid.	Yes (release attachment formatting)
1.27.3	2026-08-29	No upstream mail template, mailer, or locale changes; an existing push-notification defect in three themes is fixed in template release v1.27.3	No upstream break
1.27.2	2026-08-14	None — security + bug fixes	No
1.27.1	2026-07-27	Push commit data paths changed: .ID → .UserCommit.GitCommit.ID (#38467); older custom templates can fail on push notifications	Yes (old .ID paths)
1.27.0	2026-07-13	None — no mail template changes	No
1.26.4	2026-06-21	None — hotfix release	No
1.26.3	2026-06-20	None — security release	No
1.26.2	2026-05-20	None — security + bug fixes	No
1.26.1	2026-04-22	None — bug fixes	No
1.26.0	2026-04-19	AppURL cleanup; SanitizeHTML deprecated → use HTMLFormat	No
1.25.5	2026-03-10	None — security + maintenance	No
1.25.0	2025	Directory restructure — templates moved to mail/<category>/<type>.tmpl (PR #35150); subject/body split with --- separator; template preview support added	Yes (structural)
≤ 1.24.x	—	Flat directory structure under custom/templates/mail/	[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).

Template Functions (available in all templates)

Function	Since Gitea	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
FormatByteSize	28.0.0	Human-readable IEC file size; replaces FileSize
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
SanitizeHTML	≤ 1.21	Deprecated in 1.26 — use HTMLFormat

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 all 10 themes
4. Release checklist — Each release confirms the max-tested Gitea version in this file

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).

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