8.8 KiB
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
mainmarked unreleased until a new tag and downloadable Gitea Release are published; do not assume a tag push uploads archives automatically. - The older
v1.0.1tag 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
FileSizefunction withFormatByteSize. 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]
.DisplayNameis 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
- Local validation — run
go test ./...andgo run . preview allfromtools/; the preview function map mirrors Gitea 28.0.0 - Source audit — Template data contexts are cross-referenced against Gitea's
services/mailer/package - Regression tests — Go tests render push notifications and release attachments in all 10 themes
- Release checklist — Each release confirms the max-tested Gitea version in this file
Version Tracking
The tracker workflow scans root-level and docs/ Markdown for TRACKER: markers. VERSION-MAP and HISTORY add pending rows; UPSTREAM updates the latest upstream version and status in English/Chinese README and AGENTS; BADGE shows the new version as pending while retaining the last tested version. LATEST-TESTED and LATEST-VERIFIED are manual-only markers and must change only after compatibility verification. The script rejects unknown or missing required markers and is idempotent. Its GitHub Actions schedule and PR creation have not been verified on this Gitea host; until then, check upstream Gitea releases 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:
- Check the Gitea changelog for recent mail template changes
- Open an issue with: your Gitea version, which template, and the error