Gitea SMTP setup with Pharos

Send Gitea's mail through Pharos: PROTOCOL smtp+starttls, SMTP_ADDR smtp.pharosinfra.net, SMTP_PORT 587. Tested app.ini settings and errors.

Settings

ENABLED true

PROTOCOL smtp+starttls Not smtps, which is implicit TLS and fails on this port.

SMTP_ADDR smtp.pharosinfra.net

SMTP_PORT 587 2525 also works, and is the one to use on DigitalOcean.

USER from the dashboard The generated SMTP username, not your account email.

PASSWD from the dashboard Wrap it in backticks in app.ini if it contains

FROM Gitea <git@yourdomain.com> An address on your verified sending domain.

Gitea mailer sectionapp.ini

[mailer]
ENABLED   = true
PROTOCOL  = smtp+starttls
SMTP_ADDR = smtp.pharosinfra.net
SMTP_PORT = 587
USER      = <your Pharos SMTP username>
PASSWD    = `<your Pharos SMTP password>`
FROM      = Gitea <git@yourdomain.com>

Send a test email

Restart Gitea after editing app.ini.
Sign in as an administrator and open Site Administration, then Configuration.
Under Mailer Configuration, enter an address and choose Send Testing Email.

The page shows only that the request was accepted. Gitea queues the message and sends it in the background, so a failure appears in the Gitea log, not in the browser. With Docker, run docker logs <gitea-container> and look for a line from services/mailer.

Check the From address

Gitea also uses FROM as the sender on notification emails. Use an address on the sending domain you verified in Pharos. Mail from a credential leaves from that domain whatever FROM says, so a mismatch shows up as a different sender, not as an error.

Common errors

could not initiate SMTP session: tls: first record does not look like a TLS handshake PROTOCOL is smtps, so Gitea opened implicit TLS on a STARTTLS port. Set PROTOCOL = smtp+starttls.

dial tcp ... i/o timeout The host blocks outbound port 587. DigitalOcean does this on every droplet. Set SMTP_PORT = 2525.

Questions

How do I set this with Docker environment variables?

Every app.ini key maps to GITEA__section__KEY. For example GITEA__mailer__ENABLED=true, GITEA__mailer__PROTOCOL=smtp+starttls, GITEA__mailer__SMTP_ADDR=smtp.pharosinfra.net, GITEA__mailer__SMTP_PORT=587, GITEA__mailer__USER, GITEA__mailer__PASSWD and GITEA__mailer__FROM. The official image writes them into app.ini when the container starts.

Does this work for Forgejo?

Forgejo uses the same [mailer] keys, because it is a fork of Gitea. We have not tested it on Forgejo yet.