How to test the SMTP configuration in Gitlab CE through the CLI sending a test email

GitLab stands out as a powerful code management tool in the world of software development nowadays. In the last few days, I was configuring my self-hosted instance of GitLab and quickly needed to configure an important aspect of its setup, the configuration of email notification through an SMTP server (Simple Mail Transfer Protocol). Aimed at both newcomers and seasoned GitLab administrators, in this article, I will explain to you how to easily test whether your SMTP configuration is working properly to send emails in GitLab, and in case it's not properly configured, show you how to easily configure it with the most common SMTP providers out there.

1. Access your server via SSH

To test your SMTP configuration, you will need to launch the GitLab Rails Console using the following command in your installation server:

gitlab-rails console -e production

This will launch the GitLab Rails console in production mode. In this console, you will run the rest of the commands that I will mention throughout the article:

2. Verify the configured SMTP

The first thing that you need to do is to check the current SMTP configuration of your GitLab instance. You can print out the current settings with the following instruction:

ActionMailer::Base.smtp_settings

This will generate an output similar to the following one in case that you already configured something:

In case you don't know where to configure it, you need to add the following configuration information to /etc/gitlab/gitlab.rb and run gitlab-ctl reconfigure afterward (in my case, I use the Zoho Mail SMTP, so the configuration looks like this):

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.zoho.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "[email protected]"
gitlab_rails['smtp_password'] = "P@ssw0rd"
gitlab_rails['smtp_domain'] = "smtp.zoho.com"
gitlab_rails['smtp_authentication'] = "plain"
gitlab_rails['smtp_enable_starttls_auto'] = true
gitlab_rails['gitlab_email_from'] = '[email protected]'
gitlab_rails['gitlab_email_reply_to'] = '[email protected]'

There's an official document on Gitlab that specifies the configuration of multiple email providers such as AWS SES, Google SMTP relay, Zoho Mail etc. You can find the whole list here. Depending on your setup, whether you're running GitLab on your bare metal server, or with Docker, you may either restart the service to get the new parameters of your SMTP configuration:

gitlab-ctl restart

Or in case you're using Docker Compose, rebuild the stack:

docker compose down && docker compose up --build -d

3. Send a test email

GitLab offers a method to test the current SMTP configuration by simply delivering a test email. This method is Notify.test_email and expects 3 parameters:

• Email address.
• Subject.
• Content.

You can send a test email from the CLI using the mentioned command (replace the email address with your email where the test email should be delivered):

Notify.test_email('[email protected]', 'Castle of Glass', 'Leave out all the rest').deliver_now

In case of success

If your SMTP was properly configured, the utility should be able to deliver the email and generate an output similar to the following one:

In your inbox you should have a new email with the message you sent:

In case of error

If your SMTP is misconfigured, you will obtain an EOFError through the execution:

This means that either the configuration is not correct or maybe your SMTP is Down. If that's the case, I'd recommend you check the SMTP configuration guide of GitLab here.

4. Test in production

Now after verifying that the SMTP configuration works, you can test in production using GitLab by simply triggering an action that sends an email notification, such as the creation of a new account on GitLab, where the registered user should receive an email with the details:

Happy coding ❤️!