10 KiB
Gitea Mail Templates
Email themes for self-hosted Gitea, with a local preview and tools for building custom mail templates.
简体中文 · Installation · Preview · Compatibility · Contributing
Latest release: v28.0.0
The repository includes ten themes for account, repository, issue and workflow notifications. Gitea supplies notification content and translations; themes provide the visual presentation.
The source architecture on main is unreleased and uses Gitea v28.0.0 as its baseline. It builds templates from locked official inputs and a shared layout framework. Published archives retain their original contents and compatibility. Use the compatibility matrix to choose an archive for your Gitea version.
Style Gallery
| Preview | Theme | Appearance |
|---|---|---|
 |
Horizon | Blue accents, gray text and a centered white card |
 |
Terminal | Dark background, monospace text and green accents |
 |
Ember | Warm orange palette, serif headings and rounded buttons |
 |
Bloom | Light blue gradients, rounded cards and buttons |
 |
Heritage | Navy and gold accents, double borders and serif text |
 |
Neon | Dark background, pink and cyan accents and glow effects |
 |
Mono | Black and white, red accents and square borders |
 |
Terra | Earth tones, terracotta buttons and serif text |
 |
Ink | Newspaper layout, sidebar, serif text and drop caps |
 |
Aurora | Dark purple background, teal accents and soft glow effects |
Images show the current source build. For other mail types and languages, generate the local preview. See the capture guide when updating screenshots.
Installation
Choose a Package
Check your Gitea version with gitea --version, then select a template release from the compatibility matrix.
| Source | Mail template directory | Preparation |
|---|---|---|
| Release archive | themes/<name>/mail/ |
Download and extract the archive for the recommended release |
| Source checkout | build/themes/<name>/mail/ |
Build with Go 1.24 or later |
For a source checkout, run from the repository root:
cd tools
go run . build all
cd ..
The first build downloads the official files pinned by gitea.lock.json if the cache is absent. Later builds verify the cache before use. The root lock file is required; missing or damaged inputs are covered in the setup and recovery guide.
Install a Theme
Copy the chosen theme's mail/ contents into <GITEA_CUSTOM>/templates/mail/, then restart Gitea. Confirm your instance's custom directory before copying files. Common deployment paths include:
| Deployment | Example custom directory |
|---|---|
| Linux binary | /var/lib/gitea/custom |
| Docker | /data/gitea |
| Windows | C:\gitea\custom |
For example, from an extracted release archive on a Linux host managed by systemd:
mkdir -p /var/lib/gitea/custom/templates/mail
cp -r themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
systemctl restart gitea
For a source build, use build/themes/horizon/mail/. as the copy source. Docker and Windows installations should restart Gitea using their deployment's service or container controls.
Switching Styles
Back up existing mail overrides before replacing a theme. Remove the previous theme's installed files, then copy the new theme's complete output. Current source builds include a build.json file listing the generated files; for historical archives, refer to the archive contents. Preserve unrelated custom templates.
Removing old overrides is especially important when switching from framed to shared mode: files left behind can keep the previous theme's layout.
Confirming It Works
Trigger a notification that uses Gitea's mail templates, such as a password-reset email for a test account, and check its appearance and links. The administration test-email button does not use custom mail templates.
Preview
The preview supports theme, mail type and language selection, rendered HTML and source views, desktop/mobile viewports, and a panel showing the example data. The v28.0.0 snapshot contains 11 mail types and 28 languages.
Static Preview
From a source checkout, generate the preview data:
cd tools
go run . preview all
cd ..
Open preview/index.html in a browser. Generated language bundles load on demand and work over file://, so no server is needed. Archives produced by the current packaging script include these bundles; historical archives retain their original preview contents.
Dev Server (Live Reload)
cd tools
go run . dev
Open http://127.0.0.1:3456. The Go server watches theme files, the shared framework, the lock/cache and preview fixtures. Changes trigger a rebuild and browser refresh through server-sent events (SSE).
| Control | Options or shortcut |
|---|---|
| Theme, template, language and view | ← / → moves between selectors; ↑ / ↓ selects an option |
| View | Modern for rendered HTML; Source for generated HTML text |
| Viewport | Desktop (1386 × 780), Mobile (390 × 780); d / m |
| Information panel | p toggles the panel |
The preview renders templates using example data. Check your target mail clients separately; browser rendering does not reproduce their CSS support.
Compatibility
- Latest tested: Gitea 28.0.0
- Latest release: v28.0.0
- Upstream Gitea 28.1.0: [PENDING]
The current source architecture targets Gitea 28 and later, with compatibility verified against the locked version. A newer upstream release remains pending until reviewed. Earlier Gitea versions require the packages listed in the compatibility matrix, which also records the incomplete push-notification fix in v1.27.2.
Generated templates use Gitea's built-in functions and official translation keys. Missing translations fall back to English. The locked v28.0.0 catalog has a known Polish invitation formatting defect; preview reports [UPSTREAM-WARN] and preserves the official output. See known limitations.
Directory Structure
gitea.lock.json # Official tag, commit and file checksums
framework/ # Shared mail controls and layout presets
themes/<name>/ # Theme metadata (theme.json) and CSS (theme.css)
tools/ # Go CLI, build tools and tests
cli/ # Command definitions
upstream/ # Snapshot downloads, verification and key discovery
builder/ # Official template adaptation and theme generation
preview/ # Mail rendering, locale adapter and development server
config/, data/ # Preview metadata and example contexts
integration/, qa/ # Optional Gitea and browser checks
preview/ # Browser UI; generated manifest and language bundles
docs/ # Simplified Chinese guides and gallery images
.github/ # Workflows, release notes and packaging/tracking scripts
build/upstream/ # Downloaded official inputs (ignored)
build/themes/ # Generated installable templates (ignored)
Gitea's official templates define notification data, conditions, subjects and URLs. The shared framework arranges these into headers, action buttons, fallback links and footers. Themes define colors, typography and spacing. See theme development for the framed and shared modes.
Template Types
Mail types are discovered from the locked snapshot. The v28.0.0 entrypoints are:
| File | Notification |
|---|---|
mail/user/auth/activate.tmpl |
Account activation |
mail/user/auth/activate_email.tmpl |
Email address verification |
mail/user/auth/register_notify.tmpl |
Registration notification |
mail/user/auth/reset_passwd.tmpl |
Password reset |
mail/org/team_invite.tmpl |
Team invitation |
mail/repo/collaborator.tmpl |
Repository collaborator added |
mail/repo/transfer.tmpl |
Repository ownership transfer |
mail/repo/release.tmpl |
Release published |
mail/repo/actions/workflow_run.tmpl |
Actions workflow run |
mail/repo/issue/assigned.tmpl |
Issue or pull request assigned |
mail/repo/issue/default.tmpl |
Issue or pull request activity |
Contributing
Contributions to themes, tooling, documentation and translations are welcome. Start with CONTRIBUTING.md for local setup, design guidelines, checks and release procedures.
Documentation
License
This project is licensed under MIT. Generated release archives retain Gitea's license and snapshot provenance; see third-party notices.
This project is not affiliated with Gitea.