CI/CD #02. Jenkins: basic email using your Gmail account.

We look at the most basic approach to send emails in Jenkins. The SMTP server we use is the Gmail SMTP server.

To recap, I have installed Jenkins 2.388 LTS on my Ubuntu 22.10, with all suggested plugins, the name of this machine is HP-Pavilion-15.

I am accessing Jenkins on HP-Pavilion-15 from my Windows 10 machine using FireFox -- please keep in mind this point.

The steps required to get the Gmail SMTP server to work with Jenkins are straightforward: ❶ apply some simple configurations to the Gmail account, some of which we might have already done; ❷ configure Jenkins, which is quite easy. ❸ Not part of the steps, but we will have to prove that the configuration is working, we will write a simple Jenkins Pipeline whose main task is just to send out an email.

❶ Configure the Gmail account which we are using with Jenkins.

The Gmail account I'm using is behai.van.nguyen@gmail.com, and it is the Gmail SMTP user name.

Start Gmail, click on the avatar icon on the top right hand corner, then click on Manage your Google Account button, then on the Google Account page, click on the Security button:

On this screen, we are interested in:

1. 2-Step Verification -- this must be turned on.
2. App passwords -- it sounds scary, but it is simple. We use this to generate the password for the Gmail SMTP server. Click anywhere on this row to go to the App passwords screen, it might ask for the password, use your current Gmail password.

On the App passwords screen, for Select device, I have to select Windows Computer, since I'm running Jenkins on Windows 10 using FireFox. For Select app, select Other (Custom name), then enter Jenkins. The screen now should look like:

Click on the GENERATE button to generate the password. The 16 (sixteen) letter string in the orange box is the Gmail SMTP server password.

We now have all required information for the Gmail SMTP server:

• Gmail SMTP server address: smtp.gmail.com
• Gmail SMTP user name: behai.van.nguyen@gmail.com
• Gmail SMTP password: gwrnafeanafjlgsj
• Gmail SMTP port: 465 -- please note, some resulting posts for this Google search port 465 vs 25 state that port 465 has been deprecated, we should use port 587 instead.I did try port 587, it does not work yet!

Updated on 12/06/2023 -- Starts

I do apologise, I was wrong on ports port 465 and port 587. Both ports are working just fine, but we need to select another option correctly: please see section ❷ below.

When both Use SSL and Use TLS are checked, Use SSL seems to take precedence, SSL requires port 465; while TLS uses port port 587. Tick only Use TLS and port 587 will work. In fact, port 587 is most preferred, follow by port 465.

Updated on 12/06/2023 -- Ends

❷ Configure Jenkins.

Please note, during the configuration process, sometimes Jenkins raises the error, (possibly due to long idle period), HTTP ERROR 403 No valid crumb was included in the request, I just do a hard refresh, losing any unsaved information, but my next submission is usually valid.

Click on Manage Jenkins, then Configure System. On the Configure System screen, scroll a bit down to Jenkins Location, enter a valid email for System Admin e-mail address:

Scroll down to the last section E-mail Notification, click on the Advanced button to open the SMTP section, then fill out the screen as per below, I think all fields are compulsory, I understand that port 465 requires SSL:

Jenkins should now be able to send emails via user behai.van.nguyen@gmail.com. Let's test it. Click on the checkbox Test configuration by sending test e-mail, enter a valid email address which you have access to for Test e-mail recipient, then click on the Test configuration button. After a little while, we should get the Email was successfully sent as per the screen below:

Updated on 12/06/2023 -- Starts

Please note, on the above screenshot, both Use SSL and Use TLS are checked:

When both Use SSL and Use TLS are checked, Use SSL seems to take precedence, SSL requires port 465; while TLS uses port port 587. Tick only Use TLS and port 587 will work. In fact, port 587 is most preferred, follow by port 465.

Updated on 12/06/2023 -- Ends

I can confirm that I did receive the email to address Test e-mail recipient, whose content is:

From: behai.van.nguyen@gmail.com 
Subject: Test email #2
Body: This is test email #2 sent from Jenkins

#2 means the second test email, since this was the second test email which I've sent.

Click on the Save button to save the Configure System information.

❸ A simple Jenkins Pipeline whose main task is to send out an email using the above configurations.

Click on + New Item. On the next page, for Enter an item name, enter something meaningful, then select the second option Pipeline. Click on the OK button to move to the General page.

On the General page, scroll down to the bottom, then click on the Pipeline Syntax link, the next page helps us write the Pipeline code to send emails.

On the next page, under Sample Step, select mail: Mail, then fill out To, Subject and Body fields. For To email address, ensure some valid address and you have access to it, I don't fill out other fields, but you could certainly try:

Scroll a bit further down to see last section of the page. Click on the Advanced button to see the rest of the fields. I did not fill out any other fields under this section.

Finally, click on the Generate Pipeline Script button, the code to send email based on the information we fill out appears in the text box underneath the button, as seen:

Note also, it seems that there is an idle time set on this screen, too. If we leave it for too long then clicking on the Generate Pipeline Script button, there would be no response. I had to do a hard refresh, losing all unsaved information, and start again.

Below is the original generated code:

mail bcc: '', body: 'This email was sent by a test Jenkins Pipeline job, using Gmail SMTP.', cc: '', from: '', replyTo: '', subject: 'Jenkins Pipeline job email', to: '***kiem@gmail.com'

I removed the bcc, cc, from and replyTo fields, since they are empty; and wrapped the parameters in parentheses:

mail(body: 'This email was sent by a test Jenkins Pipeline job, using Gmail SMTP.', subject: 'Jenkins Pipeline job email', to: '***kiem@gmail.com')

Go back to the Pipeline General page, select Hello World as per the screen below:

Then, change 'Hello' to 'Send Test Email', and echo 'Hello World' with the modified code above. The final Pipeline:

pipeline {
    agent any

    stages {
        stage('Send Test Email') {
            steps {
                mail(body: 'This email was sent by a test Jenkins Pipeline job, using Gmail SMTP.', subject: 'Jenkins Pipeline job email', to: '***kiem@gmail.com')
            }
        }
    }
}

Click on the Save button to save the Pipeline and to move to the project page. Then click ▷ Build Now to run. It should run successfully:

And we should receive the email as expected:

This post is a baby step to understand how email works in Jenkins. There are much more to email. I have tried the Gmail API before, e.g.: GMail API: quick start with Python and NodeJs, and GMail API: send emails with NodeJs. -- It is tough. With App passwords, Gmail SMTP server seems much easier to use. We don't have to use Gmail, there're other free services available, but I haven't tried any yet.

I'll feel comfortable knowing how email works in Jenkins. And I hope the information in this post is useful. Thank you for reading and stay safe as always.

✿✿✿

PS: I have already removed the Gmail SMTP password used in this post 😂, and generated a new one -- we can do that and Jenkins email should still work.