GiteaMailTemplates/COMPATIBILITY.md

Gitea Compatibility

This document lists supported release combinations, known limitations and the checks used to assess compatibility.

Project overview · Contributor guide · 简体中文使用说明

Compatibility Matrix

Select a template release for the Gitea version you run. [PASS] records a compatible combination; [PENDING] means verification is incomplete. Legacy entries reflect the project's recorded compatibility assessments rather than a fresh test of every patch release.

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 source architecture on main is unreleased. Its lock pins Gitea v28.0.0, commit 15b8a5805adf57c5189602008d38cccfd3c795e0, with 13 mail files (11 entrypoints and 2 shared partials) and 28 locale files. It targets Gitea 28 and later, with each new snapshot requiring review. Historical archives retain the compatibility recorded above.

Themes contain CSS and metadata. The shared framework adapts official templates into reusable headers, action buttons, fallback links and footers while preserving notification conditions, subjects and functional URLs. Official inputs are downloaded to build/upstream/ and verified against the committed gitea.lock.json. Builds reject mismatched checksums, missing English keys, changed adapter references and unreviewed action anchors. New mail types require framework support and fixtures.

Translation Behavior

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.

Validation Scope

Source validation covers rendering and notification parity across all themes and languages. Optional browser checks cover static and HTTP previews, language switching and mobile layouts. An isolated Gitea smoke test checks template loading and captures a password-reset email. These checks do not establish rendering compatibility with Gmail, Outlook or Apple Mail; test those clients for your deployment. The release workflow does not automatically run the optional browser or real-Gitea suites.

Snapshot preparation, cache verification and version updates are separate operations. upstream prepare uses the root lock to create an absent cache; upstream verify checks an existing cache offline. upstream sync --tag vX.Y.Z explicitly replaces the snapshot and lock. A successful sync does not certify compatibility or update this matrix. See command usage and cache recovery.

Versioning and Known Exceptions

Release tags identify downloadable packages. Use the matrix to select a supported combination: v1.27.2 has a known defect despite its matching version number, and there is no v1.27.1 template tag. Changes on main become part of a release only when a new tag and archive are published.

• 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

Official templates define each mail context. The tables below summarize functions and example data relevant to development; they are not a complete API reference. Check the locked official sources and framework adapter when changing a template or fixture.

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

.DisplayName is available in the authentication mail contexts. Collaborator, transfer, release, workflow, assignment and issue-update templates use the context-specific fields listed above.

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 records upstream releases as pending. Snapshot updates and compatibility verification require a separate review.

Participating Markdown files declare managed subject/content pairs in a DOC-TAGS JSON comment. Each body is enclosed by <!-- TRACKER:CONTENT --> and <!-- /TRACKER:CONTENT -->, or the corresponding RELEASE pair. Only the first occurrence of a repeated pair in a document is processed. Undeclared, unknown or unclosed blocks, and missing declared blocks, cause validation to fail.

Managed blocks	Update policy
TRACKER:VERSION-MAP, TRACKER:HISTORY	Add pending rows for new upstream releases
TRACKER:UPSTREAM	Update the upstream version and pending status
TRACKER:BADGE	Update the upstream version while retaining the last tested version
TRACKER:LATEST-TESTED, TRACKER:LATEST-VERIFIED	Updated manually after verification
RELEASE:HEADER, RELEASE:SUMMARY, RELEASE:CURRENT	Updated by the release workflow after publication; archive labels are prepared during packaging

The release workflow keeps release links at /releases/latest and leaves published tags unchanged. Actions execution and write permissions have not been verified on the configured Gitea host. Until confirmed, check upstream releases and published assets manually. New template tags are published when template content changes; see versioning and known exceptions.

Reporting Issues

Open an issue with the Gitea version, template release or source commit, affected theme and mail type, language, reproduction steps and error output. Include the mail client for display problems. See the reporting guide for source-build diagnostics.