Using Email-ext plugin in Jenkins pipeline

By | July 12, 2018

Using Email-ext plugin in Jenkins pipeline can be easy. And this post will show how. We will create a step in the JenkinsFile incorporating the email functionality. We will then gather useful information about the build. And then email it.

WHY

Email-ext plugin is one of the most popular plugin in Jenkins ecosystem. And it is one of the most tricky one to work with too. Documentation is sparse and samples are hard to come by. And for a non-java background person it is frankly a house of pain. Hopefully this post will help you on getting started with this plugin.
So lets see how to train this dragon.

HOW

First install the Email-ext plugin. There is a default section in the Jenkins->Manage Jenkins->Configure System.
Fill in the needed configuration data.

Email-ext plugin

Email-ext plugin

Since I am working in .NET environment, the I will also install MSTest plugin for publishing the test results. Once that is sorted then start creating the JenkinsFile. Check the sample JenkinsFile below. For the uninitiated this JenkinsFile is the big thing in Jenkins 2. It is essentially the recommended way to store the Jenkins pipeline. You create this file and then check it in the source code repository. Jenkins on doing the code checkout will automatically detect this file and then use it to run the build.

In this example we will use the Email-ext plugin to create an email having:
* Subject line having the information about the build, namely the build name and the status if it is failed or success.
* Contain the code changes which triggered the build.
* Test cases passing or failing, if the build involved running some test cases.
* Pass variables to the Email-ext plugin.

Email-ext plugin can use groovy scripts to create custom mails. This is very powerful since you get access to Jenkins internals. This can allow you to pull out hard to get details about the job and put the same in the email. Email-ext plugin creators have provided two sample templates. We will use the HTML version. Go to the Jenkins home. Create a folder email-templates if it is not there. Put this file there. If you do not have access to this then you might have to ask the administrator of the Jenkins instance to do this for you.

Here is the JenkinsFile.

I will skip the explanation of the different stages and concentrate on the stage for Email-ext plugin. See how I have kept it in finally section so that even when there is some error, email is still sent. Many things are happening.

  • Line 24 : We publish the test results of the job using the MSTest plugin for Jenkins.
  • Line 36 : Believe it or not, email-ext plugin does not have access to many of the environment variables we take for granted in Jenkins pipeline. This is the way we send the current workspace location to the template. Later we will see how to access this in the template.
  • Line 37 : We pass location and pattern of the files to be attached to the email. In my case it is the mstest and hence the report files are .trx files.
  • Line 38 : We set the body of the email. Here we simply specify the template location. The template will do the hard work of populating the email.
  • Line 39 : We set the subject of the email. Here we will keep the subject as FAILURE or SUCCESS followed by the JOB_NAME.
  • Line 40 : I am sending it to the custom email address.

And that is it. It will work. However there is much you can do in this. Remember how we sent the WORKSPACE as environment variable to the template.
Add this in the template file to get the value.

Do not ask me to explain this syntax. I am a .NET guy and looking at this groovy template was painful enough.

And here are the emails you can expect. See how the test file is attached. And the plugin read the tests passing and failing. It has rendered them beautifully.
Email-Ext plugin

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.