Configure Gitlab to use Gmail SMTP for Outbound Mails

This tutorial will describe how to configure Gitlab to use Gmail SMTP for Outbound mails. In our previous tutorials, we learnt how to install and setup Gitlab CE.

Install Gitlab CE on Debian 11

Install Gitlab with SSL/TLS Certificate on Ubuntu 20.04

Configuring Gitlab to use Gmail SMTP for Outbound Mails

Gitlab can be configured to use Sendmail or Postfix to relay emails. However, if you want to configure it to sent emails through Gmail SMTP, proceed as follows.

Configure Gitlab Gmail Server Settings

Open the Gitlab configuration file for editing;

vim /etc/gitlab/gitlab.rb

Navigate to ### Gitlab email server settings section, uncomment (by removing hashe, # at the beginning of the lines) and update appropriate values in the lines below;

# 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_tls'] = false
# gitlab_rails['smtp_pool'] = false
...
# gitlab_rails['smtp_openssl_verify_mode'] = 'none'

Such that they look like as shown below.

Ensure that you replace the [email protected] with your correct Gmail ID like, [email protected].

Similarly, replace the value email-id-password with your Gmail account password.

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.gmail.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "[email protected]"
gitlab_rails['smtp_password'] = "email-id-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_pool'] = false
...
gitlab_rails['smtp_openssl_verify_mode'] = 'peer'

Save and exit the configuration file once done editing.

Encrypting Gitlab Gmail SMTP Credentials

If instead of setting the credentials in plain text as defined by the lines below, as shown above;

gitlab_rails['smtp_user_name'] = "[email protected]"
gitlab_rails['smtp_password'] = "email-id-password"

You can encrypt them for security purposes.

To encrypt Gitlab Gmail SMTP credentials;

• Update the username and password in the encrypted YAML file by running the command below. You can use your preferred editor instead of VIM in the command below;

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

The command opens a file. Uncomment the lines and set the correct values for the username and password.

password: 'email-id-password'
user_name: '[email protected]'

Save and exit the file.

The encrypted configurations are stored in the file, /var/opt/gitlab/gitlab-rails/shared/encrypted_settings/smtp.yaml.enc.

Next, remove these lines;

gitlab_rails['smtp_user_name'] = "[email protected]"
gitlab_rails['smtp_password'] = "email-id-password"

from the configuration file, if you already configured them by running the command below;

sed -i -r '/smtp_user_name|smtp_password/d' /etc/gitlab/gitlab.rb

Reconfigure Gitlab Application

Next, reconfigure Gitlab application;

gitlab-ctl reconfigure

Allow Gmail Account Less Secure App Access

Ensure that you configure Gmail account well;

Configure Postfix to Use Gmail App Passwords

You should now be able to receive emails from Gitlab.

For example, update the administrator’s email, log out and attempt to reset the password.

You will be prompted to enter the administrator’s email address to which the reset details will be sent to.

Sample Password reset email.

Reference

Gitlab SMTP Settings