-
Achilleas Pipinellis authored
Adds the **(FREE SELF)** badge on all headings that need it. https://docs.gitlab.com/ee/development/documentation/styleguide/#available-product-tier-badges
Achilleas Pipinellis authoredAdds the **(FREE SELF)** badge on all headings that need it. https://docs.gitlab.com/ee/development/documentation/styleguide/#available-product-tier-badges
stage: Enablement
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
SMTP settings (FREE SELF)
If you would rather send application email via an SMTP server instead of via
Sendmail, 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 self signed certificates you can specify a custom ca file
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 do not support communication over SSL use following settings: