Skip to content
Snippets Groups Projects
Select Git revision
  • master
  • master default protected
  • ap_update_golang_to_1.24.3
  • vault-the-alt-token
  • faleksic-tanuki-in-terminal-logo
  • lint-eol-spaces-2025-06-12-1402
  • 17-11-stable protected
  • 6412-skip-conf-check
  • add-gitlab-base-cookbook
  • 8999-shared-stuff-from-gitlab-cookbook
  • id-add-dw-go-dependency
  • 8479-remove-omnibus-gitconfig
  • 17-10-stable protected
  • 18-0-stable protected
  • ap_update_golang_to_1.23.3
  • update-codeowners-localization
  • docs-only-mr
  • 9043-move-nginx-files-to-nginx-cookbook
  • improve-wording-clarity
  • cb-ubu-22-fips
  • add-duo-workflow-executor-component
  • 17.10.8+ee.0 protected
  • 17.10.8+ce.0 protected
  • 17.11.4+ee.0 protected
  • 17.11.4+ce.0 protected
  • 18.0.2+ee.0 protected
  • 18.0.2+ce.0 protected
  • 17.10.7+ee.0 protected
  • 17.10.7+ce.0 protected
  • 17.11.3+ee.0 protected
  • 17.11.3+ce.0 protected
  • 18.0.1+ee.0 protected
  • 18.0.1+ce.0 protected
  • 18.0.0+ee.0 protected
  • 18.0.0+ce.0 protected
  • 18.0.0+rc44.ee.0 protected
  • 18.0.0+rc44.ce.0 protected
  • 18.0.0+rc43.ee.0 protected
  • 18.0.0+rc43.ce.0 protected
  • 18.0.0+rc42.ee.0 protected
  • 18.0.0+rc42.ce.0 protected
41 results

smtp.md

Blame
    • 2
    smtp.md 54.62 KiB 
    stage: GitLab Delivery
group: Self Managed
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
title: SMTP settings

    {{< details >}}

    • Tier: Free, Premium, Ultimate
    • Offering: GitLab Self-Managed

    {{< /details >}}

    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.

    {{< alert type="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.

    {{< /alert >}}

    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

    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

    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:

    1. 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'

    2. Edit the encrypted secret:

      sudo gitlab-rake gitlab:smtp:secret:edit EDITOR=vim

    3. The unencrypted contents of the SMTP secret should be entered like:

      user_name: 'smtp user'
password: 'smtp password'

    4. Edit /etc/gitlab/gitlab.rb and remove the settings for smtp_user_name and smtp_password.

    5. 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

    Prerequisites:

    {{< alert type="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.

    {{< /alert >}}

    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.

    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:

    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"
gitlab_rails['gitlab_email_from'] = 'gitlab@domain.com'
gitlab_rails['gitlab_email_reply_to'] = 'noreply@domain.com'

    Zoho Mail

    This configuration was tested on Zoho Mail with a custom domain.

    gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.zoho.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_authentication'] = "plain"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['smtp_user_name'] = "gitlab@mydomain.com"
gitlab_rails['smtp_password'] = "mypassword"
gitlab_rails['smtp_domain'] = "smtp.zoho.com"
gitlab_rails['gitlab_email_from'] = 'gitlab@example.com'
gitlab_rails['gitlab_email_reply_to'] = 'noreply@example.com'

    SiteAge, LLC Zimbra Mail

    gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = 'mail.siteage.net'
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = 'gitlab@domain.com'
gitlab_rails['smtp_password'] = 'password'
gitlab_rails['smtp_authentication'] = 'login'
gitlab_rails['smtp_enable_starttls_auto'] = false
gitlab_rails['gitlab_email_from'] = "gitlab@domain.com"
gitlab_rails['smtp_tls'] = true

    OVH

    gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "ssl0.ovh.net"
gitlab_rails['smtp_port'] = 465
gitlab_rails['smtp_user_name'] = "username@domain.com"
gitlab_rails['smtp_password'] = "password"
gitlab_rails['smtp_domain'] = "ssl0.ovh.net"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = false
gitlab_rails['smtp_tls'] = true
gitlab_rails['smtp_openssl_verify_mode'] = 'none'