Setting Up Email Notifications in the Jenkins CI System

An important part of the feedback mechanism from a continuous integration system like Jenkins is to generate automated email notifications. While Jenkins provides a simple web interface to set up and configure email notifications, it’s not so straightforward to set up.  Here I’ll walk you through the steps to generate automated emails to stakeholders once a build fails in the Jenkins CI system.

Step 1: Install required plugins (Email Extension Plugin, only required for customized emails)

Jenkins primarily works and operates with the help of plugins. They are the most important components to get your builds working. The same holds true for email notifications. You will need to install and configure the Email Extension Plugin. Navigate to Jenkins > Manage Jenkins > Manage Plugins. Then under the Available tab, search for Email Extension Plugin and choose Install without restart.  This plugin is required only if you want to set up customized email notifications. Otherwise, jump to step 2.

Jenkins email extension plugin

Email extension plugin

Step 2a: Configure Jenkins System Options

Once the plugin is installed, configure the Global System Options.  In this post, we will be setting up the simple email notifications. Navigate to Jenkins > Manage Jenkins > Configure System. Then scroll down to the Email Notification section.

Enter the values below for SMTP server based on your email. Below are the values that you should entering for Outlook and Gmail users. Contact your email administrator to find out values for other email clients.

Outlook Users:

SMTP server: smtp-mail.outlook.com

Use SMTP Authentication: ON

Username: <your email address>

Password: <your email password>

Use SSL: OFF

SMTP Port: 587

Charset: UTF-8

GMail Users:

SMTP server: smtp.gmail.com

Use STMP Authentication: ON

Username: <your email address>

Password: <your email password>

Use SSL: OFF

SMTP Port: 465

Charset: UTF-8

Step 2b: Configure System Admin email address – important

While still under the Configure System Page, navigate to Jenkins Location to set the admin email address. This is probably the most ignored option during this set up. Make sure you provide an admin email address.  Notification e-mails to project owners will be sent with this address in the “From” header.

Step 3: Create the build to set up notifications

The next step is to create a build to execute. If you already have a build available and ready to set up notifications, you can ignore this step. To create a new build, navigate to the Jenkins home page and click on New Item. Fill out the fields according to your build requirement.

The most common option is to choose a FreeStyle Project.

Step 4: Configure the post build Actions – set up notifications

Choose the build to configure email notifications. Open the build and click on the Configure option to navigate to the build configuration page. Scroll down to the Post-build Actions section and choose Add post-build action.

Email notifications should be triggered once the build is complete. If you need a more customized email to be sent, choose Editable Email Notification.

The section above should appear once you have selected the Email Notification option.  Provide a list of recipients (valid email addresses) who should be receiving the notifications. You can choose to send email for every unstable build or to trigger an email every time a build gets executed.  Nest, save the build and exit out of the configuration page.

Your email notifications for this build are now set up.  There’s one more important step before you’ll see these emails in action.

Step 5: Configure the Jenkins Start Up Parameters (important)

The Jenkins configuration file “Jenkins.xml” will dictate the start-up parameters for your Jenkins system. You will need to enable the SMTP.StartTLS command to successfully trigger emails. On a windows system, the Jenkins.xml file can generally be found at the path C:\Program Files\Jenkins\. Open the Jenkins.xml file to see the <arguments> tag. Add the parameters below to the <arguments> tag.  Your existing arguments tag might look like:

<arguments>-Xmx2048m -XX:MaxPermSize=512m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -jar “%BASE%\jenkins.war” –httpPort=8080</arguments>

To enable the StartTLS command, add the following argument to the <arguments> tag:

<arguments>-Xmx2048m -XX:MaxPermSize=512m -Djava.awt.headless=true -Dmail.smtp.starttls.enable=true -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -jar “%BASE%\jenkins.war” –httpPort=8080 –webroot=”%BASE%\war”</arguments>

Now save and close the file.

Note: You will need to stop the already running Jenkins windows service to modify the Jenkins.xml configuration file.

Step 6:  Test emails before activation

Jenkins offers a test option to see whether emails are triggered successfully. To conduct this test, navigate back to the Jenkins System Options page – Jenkins > Manage Jenkins > Configure System. Then scroll down to the Email Notification section as in step 2.  Check Test Configuration by sending test e-mail. Enter a test email ID where you would like to send the test email and click the Test configuration button. You should see the message “Email was successfully sent.”

This will ensure the email notifications were set up and configured correctly. Now you can navigate back the build and click the “Build now” button on the Jenkins build you have configured.

Leave a Reply

Your email address will not be published. Required fields are marked *