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.

Snapshot-Driven Source Status

The refactor on main is unreleased. It locks Gitea v28.0.0, commit 15b8a5805adf57c5189602008d38cccfd3c795e0, with 13 mail files (11 entrypoints and 2 shared partials) and 28 official locale files. New source architecture supports Gitea 28+; it does not replace historical release assets or change recommendations in the published matrix.

Theme sources contain CSS and metadata only. A shared framework organizes official mail values/translations into reusable branding, action/fallback and footer controls. Its single alignment layer preserves notification branches, subjects and functional link targets while allowing presentation changes. Only generated gitea.lock.json is committed; immutable official inputs are downloaded to ignored build/upstream/. Builds fail on checksum, English-key, adapter-reference or unreviewed action-anchor changes. New mail types require framework alignment and fixtures.

Missing translations in other languages follow the official English fallback and are reported as [FALLBACK]. Gitea v28.0.0's Polish mail.team_invite.text_1 starts with malformed %[1]z… instead of %[1]s; preview preserves this official defect and reports [UPSTREAM-WARN]. The exception matches the exact source text; other formatting defects fail rendering.

Gitea 28.1.0 remains [PENDING]. Updating pending documentation does not synchronize the snapshot or verify a new version.

upstream prepare requires the committed root lock and creates only an absent cache; upstream verify requires both lock and cache and performs no download. Missing locks are not inferred from cache or latest releases. Explicit upstream sync --tag vX.Y.Z can initialize or replace the lock, but does not update this matrix or certify compatibility. See command usage and cache recovery.

Current-source validation includes all-theme/all-language rendering and notification parity, browser checks for static/HTTP language switching and mobile layouts, and an isolated Gitea 28.0.0 template-loading/password-reset mail smoke test. This does not certify rendering in Gmail, Outlook or Apple Mail; those clients still require deployment-specific testing. The optional real-Gitea and browser suites are not automatically run by the current release workflow.

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

The downloaded official inputs define mail variables and calls; themes do not add business variables. The table below summarizes preview contexts. The locked upstream commit, shared alignment layer and strict fixture rendering are authoritative.

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	Subject, Repo, Link
repo/release	Release (with Publisher, TagName, Title, RenderedNote, Attachments), Link
repo/actions/workflow_run	Subject, Run (with WorkflowID, HTMLURL), Jobs (with status class, icon CID/alt, attempt, URL and duration)
repo/issue/assigned	Subject, Doer, Issue, Link, IsPull, CanReply
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

Official templates reference mail.* keys and actions.runs.attempt. AST-based checks inspect .locale.Tr, $.locale.Tr and both plural keys in TrN, including nested pipelines. Every referenced key must exist in the locked English catalog. Preview loads full official locale JSON files rather than a copied Go dictionary; formatting, escaping and plural selection follow the reviewed Gitea adapter.

How Compatibility Is Verified

1. Locked input verification — run go run . upstream prepare then go run . upstream verify from tools/; first preparation downloads missing cache files, verification checks hashes, adapter references and English keys offline.
2. Framework alignment — go test ./... checks deterministic shared adaptation/generation and fails on changed primary-action anchors; theme sources cannot own business templates.
3. Notification semantics and controls — tests compare subjects, notification text and functional links for every theme/language and critical branches, accounting explicitly for added controls/branding. Browser QA checks translated button labels, identical fallback targets, logos and mobile layout. go run . preview all builds all language bundles and reports fallback/upstream defects.
4. Matching-instance smoke test — before publication, load generated overrides in an isolated Gitea matching the snapshot and capture a real notification or password-reset mail. The admin test email does not exercise custom templates.
5. Release identity — the release tag must match the snapshot tag. Only mark the new release verified after its tests and smoke check; published tags/assets remain unchanged.

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