Configure GitLab to send email over SMTP

Self-managed GitLab (Linux package) sends notifications, password resets and confirmations with the `gitlab_rails['smtp_*']` keys in `/etc/gitlab/gitlab.rb`. The common mistake is turning on both TLS flags: `smtp_enable_starttls_auto` is for 587, `smtp_tls` is for 465, and setting both to `true` fails with `:enable_starttls and :tls are mutually exclusive`.

1. 1

   Create a send-only key

   In Unitpost, open Settings → SMTP and create a send-only key. GitLab sends as gitlab_email_from, so pick that address on a verified domain.

2. 2

   Add the SMTP block to gitlab.rb

   Edit /etc/gitlab/gitlab.rb on the GitLab server. For port 587, keep smtp_enable_starttls_auto on and smtp_tls off.

   Ruby

   gitlab_rails['smtp_enable'] = true
   gitlab_rails['smtp_address'] = "smtp.unitpost.com"
   gitlab_rails['smtp_port'] = 587
   gitlab_rails['smtp_user_name'] = "unitpost"
   gitlab_rails['smtp_password'] = "pk_live_..."
   gitlab_rails['smtp_domain'] = "yourdomain.com"
   gitlab_rails['smtp_authentication'] = "login"
   gitlab_rails['smtp_enable_starttls_auto'] = true
   gitlab_rails['smtp_tls'] = false
   gitlab_rails['smtp_openssl_verify_mode'] = 'peer'
   
   gitlab_rails['gitlab_email_from'] = 'gitlab@yourdomain.com'
   gitlab_rails['gitlab_email_reply_to'] = 'noreply@yourdomain.com'

   For port 465, set smtp_port to 465, smtp_tls to true and smtp_enable_starttls_auto to false.

3. 3

   Reconfigure GitLab

   Changes in gitlab.rb apply only after a reconfigure.

   Shell

   sudo gitlab-ctl reconfigure

4. 4

   Send a test from the Rails console

   Open the console with sudo gitlab-rails console, then send a message with Notify.test_email. A failure prints the SMTP error right there; a success shows up in Unitpost Emails.

   Ruby

   Notify.test_email('you@example.com', 'Unitpost SMTP test', 'Sent from GitLab').deliver_now

5. 5

   If it fails

   In the same console, ActionMailer::Base.smtp_settings shows what GitLab loaded. 535 5.7.8 means smtp_user_name isn't unitpost. 550 5.7.1 means gitlab_email_from isn't on a verified domain. The mutually exclusive error means both TLS flags are true.