Problem

How do I set up outbound SMTP using GitLab?
How do I use outMail in GitLab?

Solution

This article assumes you have already got a fully functional self-hosted gitlab server working.

Configure gitlab.rb

In order to enable GitLab to send outbound emails using outMail you need to edit the /etc/gitlab/gitlab.rb file.

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = 'mxXXXXXX.smtp-engine.com'   # Please see your outMail service settings in the portal
gitlab_rails['smtp_port'] = 587                             # Alternate SMTP ports are available
gitlab_rails['smtp_user_name'] = 'outmail-username'         # Please see your outMail service settings in the portal
gitlab_rails['smtp_password'] = 'outmail-password'          # Please see your outMail service settings in the portal
gitlab_rails['smtp_domain'] = 'example.com'                 # Change to your domain name
gitlab_rails['gitlab_email_from'] = 'user@example.com'      # Must be a valid email address
gitlab_rails['gitlab_email_reply_to'] = 'user@example.com'  # Must be a valid email address
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_authentication'] = 'login'
gitlab_rails['smtp_tls'] = false
gitlab_rails['smtp_openssl_verify_mode'] = 'peer'

If you're using port 465 (SMTPS) change the above lines to the below

gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_tls'] = true

Notes

• You must specify valid from and reply_to addresses
• Set up a valid SPF (Sender Policy Framework) record to include outMail
• Enable outMail to DKIM (DomainKeys Identified Mail) sign your gitlab emails

As a responsible sender of emails for your domain name you should also consider adding a DMARC policy.

You can find your outMail service details in the portal.