# Gitea Compatibility
---
[简体中文](docs/COMPATIBILITY.zh-CN.md)

This document describes the compatibility of Gitea Mail Templates with different Gitea versions.

## Compatibility Matrix

Select the recommended template release for the Gitea version you run. `[PASS]` identifies a combination recorded as compatible; `[PENDING]` means verification is incomplete.

> [!NOTE]
> Historical entries reflect the project's existing compatibility assessments. They do not mean that every patch version is retested for each release.

| Gitea version | Recommended template release | Status | Notes |
|---|---|---|---|
| 28.1.0 | — | [PENDING] | Compatibility verification pending |
| 28.0.0 | **v28.0.0** | [PASS] | Gitea replaced the mail function `FileSize` with `FormatByteSize` |
| 1.27.3 | **v1.27.3** | [PASS] | Pull request push notification commit links fixed in every theme |
| 1.27.2 | **v1.27.3** | [PASS] | The matching v1.27.2 template release has push notification defects in Bloom, Ember and Heritage |
| 1.27.1 | **v1.27.3** | [PASS] | Older v1.0.x templates use obsolete push commit fields |
| 1.27.0 | — | [PENDING] | Gitea uses a new commit data structure; v1.27.3 may be compatible but has not been verified against this version |
| 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] | — |

> [!NOTE]
> Gitea 1.24.x and earlier use a different mail template layout and are `[UNSUPPORTED]`; Gitea Mail Templates no longer provides separate support for them. The v1.0.0 template tag has been superseded by v1.0.1 and is no longer recommended separately.

## Gitea Version History — Mail Template Impact

This table describes changes in **Gitea**, not fixes in this template repository. “None” means that the Gitea version introduces no relevant mail template changes; recommended archives are listed in the compatibility matrix above.

| Gitea | Release date | Mail template changes | Impact |
|---|---|---|---|
| **28.1.0** | 2026-10-06 | [PENDING] | [PENDING] |
| **28.0.0** | 2026-09-29 | Mail function `FileSize` renamed to `FormatByteSize` ([PR](https://github.com/go-gitea/gitea/pull/39083)) | **Breaking change:** old release attachment templates fail |
| | | Introduced `templates/mail/base/` ([PR](https://github.com/go-gitea/gitea/pull/38396)) | **Breaking change:** older Gitea versions cannot directly use the new mail templates |
| **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 use `.UserCommit.GitCommit` ([PR](https://github.com/go-gitea/gitea/pull/38467)) | **Breaking change: an existing defect remains unresolved.** Old custom pull request push templates can fail |
| **1.27.0** | 2026-07-13 | Push commit data moved under `.UserCommit.GitCommit` ([ISSUE](https://github.com/go-gitea/gitea/issues/38469)) | **Breaking change:** old pull request push templates 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 ([PR](https://github.com/go-gitea/gitea/pull/35150)) | **Breaking change:** older template layouts are unsupported |
| **≤ 1.24.x** | — | Legacy custom mail layout | [UNSUPPORTED] |

## Template Variable Reference

Official templates define the context for each mail type. For specific mail templates, functions and variables used during development, refer to the official mail template documentation [1](#notes).

## Translation Keys

Official templates reference `mail.*` and `actions.runs.attempt`. AST-based checks cover `.locale.Tr`, `$.locale.Tr` and both plural keys in `TrN`, including nested pipelines. Every referenced key must exist in the locked English catalog.

---
### Notes

[1](#notes): [Mail templates | Gitea Documentation](https://docs.gitea.com/administration/mail-templates/)