Gitea Mail Template
Gitea Mail Template offers a range of email template styles for self-hosted Gitea instances.
Latest release: v28.0.0
The repository includes several themes for Gitea emails, suitable for most deployment scenarios and use cases. Before installing, consult the compatibility matrix for your Gitea version and choose the corresponding release archive.
Style Gallery
The gallery shows how the email templates render in the preview tool.
| Preview | Theme | Style Features |
|---|---|---|
 |
Aurora | Dark purple background, teal accents and a soft glow |
 |
Bloom | Light blue gradients, rounded cards and buttons |
 |
Ember | Warm orange tones, serif headings and rounded buttons |
 |
Heritage | Navy and gold, double borders and serif fonts |
 |
Horizon | Blue accents, gray text and a centered white card |
 |
Ink | Newspaper layout, a sidebar, serif fonts and drop caps |
 |
Mono | Black and white, red accents and square borders |
 |
Neon | Dark background, pink and cyan accents and glow effects |
 |
Terminal | Dark background, monospace fonts and green accents |
 |
Terra | Earth tones, terracotta buttons and serif fonts |
Screenshots show only the current default build. Use the local preview to view other email types and languages. See the screenshot guide when updating screenshots.
Installation
Choose an Installation Source
Run gitea --version to confirm the version of your deployed Gitea instance, then choose a template version from the compatibility matrix.
Warning
We do not recommend building directly from the source repository, as these versions have not yet been fully tested for release readiness. Outdated or missing template parameters that have not been identified may prevent your Gitea instance from starting correctly.
Tip
If you still need to build the email templates from source, follow the steps below.
| Source | Email Template Directory | Preparation |
|---|---|---|
| Release archive | themes/<name>/mail/ |
Download and extract the recommended release archive |
| Source | build/themes/<name>/mail/ |
Build with Go 1.24 or later |
To build from source, run the following from the repository root:
cd tools
go run . build all
cd ..
Building usable templates requires resources from the official Gitea repository to ensure consistent source inputs. The command automatically downloads the official files pinned by gitea.lock.json. Subsequent builds use the cached resources without downloading them again. For missing files or a damaged cache, see official snapshot updates.
Install a Theme
Copy the contents of the selected theme's mail/ directory into <GITEA_CUSTOM>/templates/mail/, then restart Gitea to apply the theme. Before copying, confirm the custom directory your instance actually uses. Common deployment paths include:
| Deployment | Example Custom Directory |
|---|---|
| Linux binary | /var/lib/gitea/custom |
| Docker | /data/gitea |
| Windows | C:\gitea\custom |
For example, on a Linux host where systemd manages Gitea, run the following from the extracted release archive directory:
systemctl stop gitea
mkdir -p /var/lib/gitea/custom/templates/mail
cp -r themes/horizon/mail/. /var/lib/gitea/custom/templates/mail/
systemctl restart gitea
Tip
For templates built from source, change the copy source to
build/themes/horizon/mail/.. For Docker and Windows deployments, use the appropriate container or service controls to stop and restart Gitea.
Switch Themes
Back up or remove the files installed by the previous theme, choose a new email theme, and repeat the installation steps above.
Confirm the Theme Is Applied
Use a test account to trigger an email notification, such as a password reset, and check its appearance and links. The administration panel's test-email button does not use custom email templates, so it cannot confirm whether the theme has been applied.
Preview
The preview tool included in the repository lets you view how emails render across themes, template types and languages before deployment.
Static Preview
First, generate the preview data in the source repository:
cd tools
go run . preview all
cd ..
Open preview/index.html in a browser. No server is required.
Development with Live Reload
cd tools
go run . dev
# Press Ctrl+C in the terminal to stop the server.
cd ..
Open http://127.0.0.1:3456. The Go server watches theme files, the shared framework, the lock file and cache, and preview test data. When a file changes, it rebuilds the email templates and refreshes the page through server-sent events (SSE) to provide live reload.
Controls and Keyboard Shortcuts
| Control | Options or Shortcuts |
|---|---|
| Theme, template, language and view | ← / → moves between selectors; ↑ / ↓ selects an option |
| View | Modern displays the rendered result; Source displays the generated HTML text |
| Viewport | Desktop (1386 × 780), Mobile (390 × 780); shortcuts d / m |
| Information panel | p expands or collapses the panel |
Warning
The preview renders templates using example data. Browsers and email clients differ in their CSS support, so check the appearance in your target email clients before deployment.
Compatibility
- Latest tested: Gitea 28.0.0
- Latest release: v28.0.0
- Upstream Gitea 28.1.0: [PENDING]
Project Directory Structure
The project is organized around a shared framework, theme styles and build tools. Source code and documentation are tracked in version control; downloaded official files, generated templates and preview data are not.
Tracked in Version Control
.github/ # Workflows and maintenance scripts
release-notes/ # Release notes for each version
scripts/ # Documentation updates, packaging and Gitea release scripts
workflows/ # Validation and publication
docs/ # Chinese documentation, documentation index and gallery images
framework/ # Shared email controls and layout presets
layouts/ # Layout presets shared across email types
mail/base/ # Header, action buttons, fallback links, sidebar and footer
preview/index.html # Preview interface
themes/<THEME_NAME>/ # Theme source files
tools/ # Go CLI, build tools and tests
builder/ # Official template adaptation and theme generation
cli/ # Command definitions and argument handling
config/ # Preview configuration loading and validation
data/ # Email type descriptions and preview example data
preview/ # Email rendering, locale adaptation and development server
upstream/ # Official snapshot downloads, verification and translation key discovery
gitea.lock.json # Official version tag, commit and file checksums
README.md
Official templates provide notification content, conditions, subject lines and links. The shared framework handles email presentation, while themes use metadata and CSS to select layouts and define styles. Theme directories do not contain official email source files or translations.
Not Tracked in Version Control
The following files are generated by the build and preview commands or downloaded according to the lock file. They do not need to be maintained manually or committed:
build/themes/<THEME_NAME>/ # Theme build output
mail/ # Email templates ready to install in Gitea
build.json # Build provenance and generated file checksums
build/upstream/ # Official templates, locales, assets and licenses pinned by the lock file
dist/ # Default output directory for release archives
preview/rendered.js # Preview manifest
preview/rendered/<LOCALE>.js # Preview data for each locale
build all generates installable templates for all themes. preview all generates both templates and preview data for each locale. On first use, the tools prepare any missing official file cache according to gitea.lock.json; subsequent uses verify the cache before proceeding.
Template Types
Gitea currently includes the following 11 email templates 1:
| File | Notification Type |
|---|---|
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 |
New release published |
mail/repo/actions/workflow_run.tmpl |
Actions workflow run |
mail/repo/issue/assigned.tmpl |
Issue or pull request assignment |
mail/repo/issue/default.tmpl |
Issue or pull request activity |
Contributing
Contributions to themes, tools, documentation and translations are welcome. The contributor guide covers local environment setup, design guidelines, required checks and the release process.
License
This project is licensed under MIT. Generated release archives retain Gitea's license and snapshot provenance.
Notes
1: Mail templates | Gitea Documentation
This project is not affiliated with Gitea.