-
Anton Smith authoredAnton Smith authored
stage: Systems
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
SMTP settings (FREE SELF)
If you would rather send application email via an SMTP server instead of via
Sendmail or Postfix, add the following configuration information to
/etc/gitlab/gitlab.rb
and run gitlab-ctl reconfigure
.
WARNING:
Your smtp_password
should not contain any String delimiters used in
Ruby or YAML (f.e. '
) to avoid unexpected behavior during the processing of
config settings.
There are example configurations at the end of this page.
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.server"
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = "smtp user"
gitlab_rails['smtp_password'] = "smtp password"
gitlab_rails['smtp_domain'] = "example.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_openssl_verify_mode'] = 'peer'
# If your SMTP server does not like the default 'From: gitlab@localhost' you
# can change the 'From' with this setting.
gitlab_rails['gitlab_email_from'] = 'gitlab@example.com'
gitlab_rails['gitlab_email_reply_to'] = 'noreply@example.com'
# If your SMTP server is using a self signed certificate or a certificate which
# is signed by a CA which is not trusted by default, you can specify a custom ca file.
# Please note that the certificates from /etc/gitlab/trusted-certs/ are
# not used for the verification of the SMTP server certificate.
gitlab_rails['smtp_ca_file'] = '/path/to/your/cacert.pem'
SMTP connection pooling
Introduced in GitLab 13.5.
You can enable SMTP connection pooling with the following setting:
gitlab_rails['smtp_pool'] = true
This allows Sidekiq workers to reuse SMTP connections for multiple jobs. The maximum number of connections in the pool follows the maximum concurrency configuration for Sidekiq.
Using encrypted credentials
Introduced in GitLab 14.3.
Instead of storing the SMTP credentials in the configuration files as plain text, you can optionally use an encrypted file for the SMTP credentials. To use this feature, you first need to enable GitLab encrypted configuration.
The encrypted configuration for SMTP exists in an encrypted YAML file. By default the file will be created at
/var/opt/gitlab/gitlab-rails/shared/encrypted_configuration/smtp.yaml.enc
. This location is configurable in the GitLab configuration.
The unencrypted contents of the file should be a subset of the settings from your smtp_*'
settings in the gitlab_rails
configuration block.
The supported configuration items for the encrypted file are:
user_name
password
The encrypted contents can be configured with the SMTP secret edit Rake command.
Configuration
If initially your SMTP configuration looked like:
- In
/etc/gitlab/gitlab.rb
:
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.server"
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = "smtp user"
gitlab_rails['smtp_password'] = "smtp password"
gitlab_rails['smtp_domain'] = "example.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_openssl_verify_mode'] = 'peer'
-
Edit the encrypted secret:
sudo gitlab-rake gitlab:smtp:secret:edit EDITOR=vim
-
The unencrypted contents of the SMTP secret should be entered like:
user_name: 'smtp user' password: 'smtp password'
-
Edit
/etc/gitlab/gitlab.rb
and remove the settings forsmtp_user_name
andsmtp_password
. -
Reconfigure GitLab:
sudo gitlab-ctl reconfigure
Example configurations
SMTP on localhost
This configuration, which simply enables SMTP and otherwise uses the default settings, can be used for an MTA running on localhost that does not provide a sendmail
interface or that provides a sendmail
interface that is incompatible with GitLab, such as Exim.
gitlab_rails['smtp_enable'] = true
SMTP without SSL
By default SSL is enabled for SMTP. If your SMTP server does not support communication over SSL use following settings:
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = 'localhost'
gitlab_rails['smtp_port'] = 25
gitlab_rails['smtp_domain'] = 'localhost'
gitlab_rails['smtp_tls'] = false
gitlab_rails['smtp_openssl_verify_mode'] = 'none'
gitlab_rails['smtp_enable_starttls_auto'] = false
gitlab_rails['smtp_ssl'] = false
gitlab_rails['smtp_force_ssl'] = false
Gmail
NOTE: Gmail has strict sending limits that can impair functionality as your organization grows. We strongly recommend using a transactional service like SendGrid or Mailgun for teams using SMTP configuration.
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.gmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "my.email@gmail.com"
gitlab_rails['smtp_password'] = "my-gmail-password"
gitlab_rails['smtp_domain'] = "smtp.gmail.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' # Can be: 'none', 'peer', 'client_once', 'fail_if_no_peer_cert', see http://api.rubyonrails.org/classes/ActionMailer/Base.html
Don't forget to change my.email@gmail.com
to your email address and my-gmail-password
to your own password.
If you encounter authentication errors, ensure you have allowed less secure apps to access the account or try turning on 2-step validation and using an application password.
Google SMTP relay
You can route outgoing non-Gmail messages through Google using Google's SMTP relay service.
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp-relay.gmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_domain'] = "yourdomain.com"
gitlab_rails['gitlab_email_from'] = 'username@yourdomain.com'
gitlab_rails['gitlab_email_reply_to'] = 'username@yourdomain.com'
Mailgun
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.mailgun.org"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_authentication'] = "plain"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_user_name'] = "postmaster@mg.gitlab.com"
gitlab_rails['smtp_password'] = "password"
gitlab_rails['smtp_domain'] = "mg.gitlab.com"
Amazon Simple Email Service (AWS SES)
- Using STARTTLS
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "email-smtp.region-1.amazonaws.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "IAMmailerKey"
gitlab_rails['smtp_password'] = "IAMmailerSecret"
gitlab_rails['smtp_domain'] = "yourdomain.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
Make sure to permit egress through port 587 in your ACL and security group.
- Using TLS Wrapper
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "email-smtp.region-1.amazonaws.com"
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = "IAMmailerKey"
gitlab_rails['smtp_password'] = "IAMmailerSecret"
gitlab_rails['smtp_domain'] = "yourdomain.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_ssl'] = true
gitlab_rails['smtp_force_ssl'] = true
Make sure to permit egress through port 465 in your ACL and security group.
Mandrill
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.mandrillapp.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "MandrillUsername"
gitlab_rails['smtp_password'] = "MandrillApiKey" # https://mandrillapp.com/settings
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
SMTP.com
You can use the SMTP.com email service. Retrieve your sender login and password from your account.
To improve delivery by authorizing SMTP.com
to send emails on behalf of your domain, you should:
- Specify
from
andreply_to
addresses using your GitLab domain name. - Set up SPF and DKIM for the domain.
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = 'send.smtp.com'
gitlab_rails['smtp_port'] = 25 # If your outgoing port 25 is blocked, try 2525, 2082
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_authentication'] = 'plain'
gitlab_rails['smtp_user_name'] = 'your_sender_login'
gitlab_rails['smtp_password'] = 'your_sender_password'
gitlab_rails['smtp_domain'] = 'your.gitlab.domain.com'
gitlab_rails['gitlab_email_from'] = 'user@your.gitlab.domain.com'
gitlab_rails['gitlab_email_reply_to'] = 'user@your.gitlab.domain.com'
Check the SMTP.com Knowledge Base for further assistance.
SparkPost
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.sparkpostmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "SMTP_Injection"
gitlab_rails['smtp_password'] = "SparkPost_API_KEY" # https://app.sparkpost.com/account/credentials
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true
Gandi
gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "mail.gandi.net"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_authentication'] = "plain"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_user_name'] = "your.email@domain.com"
gitlab_rails['smtp_password'] = "your.password"
gitlab_rails['smtp_domain'] = "domain.com"