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
Unreleased	1.25.0	1.27.3	✅ Source verified; release pending
v1.27.2	1.25.0	1.27.3	⚠️ Push notices fail in Bloom, Ember, and Heritage on Gitea 1.27.1+
v1.0.1	1.25.0	1.27.0	✅ Superseded; push notices need newer release on 1.27.1+
v1.0.0	1.25.0	1.26.4	✅ Superseded

Latest verified: The current source tree passes the Gitea 1.27.3 source audit and push-render test. The published v1.27.2 archive still contains three broken push-notification templates.

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 in the source tree that are not yet in a downloadable release.

Gitea version	Template release
1.27.3	Unreleased fix; published v1.27.2 has a push-notification issue in three themes
1.27.2	Unreleased fix; published v1.27.2 has the same issue
1.27.1	Unreleased fix; published v1.27.2 has the same issue

• The tracker workflow opens a PR when a new Gitea release appears, marking it ⏳ Pending Verification.
• After verification, update the top Template Release row. Keep source-only fixes marked Unreleased until a new tag is published; the release workflow packages the archive on tag push.
• 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.

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?
1.27.3	2026-08-29	No upstream mail template, mailer, or locale changes; an existing push-notification defect in three published themes was found and fixed in the current source tree	No upstream break (local fix pending release)
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
FileSize	≤ 1.21	Human-readable file size
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

⚠️ .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. Keys are stable across Gitea 1.25+.

How Compatibility Is Verified

1. Automated lint — CI renders all templates via go run . preview all on every push
2. Source audit — Template data contexts are cross-referenced against Gitea's services/mailer/ package
3. Release checklist — Each release confirms the max-tested Gitea version in this file

Automated Tracking

A workflow runs daily (UTC 08:00) to detect new Gitea releases. When a new version is found, it automatically creates a PR updating the matrix and badges with a ⏳ Pending Verification status. Manual trigger is also available via workflow_dispatch. Once verification passes, update the compatibility matrix; publish a new template tag when template changes require a release (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