In this tutorial, we will see two different ways to send email notifications from Jenkins. They can be very useful when we want to be notified of problems in our pipeline quickly.
2. Environment Setup
First, we’ll set up our environment. Let’s use Docker Compose because it allows us to do this quite simply.
For this tutorial, we need a container that runs the Jenkins Docker image. In addition, we will be using MailHog to test the email sending functionality.
let’s make docker-compose.yaml File that describes our environment:
version: '3.7' services: mailhog: image: mailhog/mailhog:v1.0.1 container_name: mailhog networks: - jenkins ports: - 1025:1025 - 8025:8025 jenkins: image: jenkins/jenkins:2.361.1-lts-jdk11 container_name: jenkins networks: - jenkins ports: - 8080:8080 - 50000:50000 networks: jenkins:
Here are some important details we need to know about. First, let’s look at the network configuration. Both containers use the same network. This is important because otherwise, they would not be able to communicate with each other.
Secondly, let’s take a look at the ports of these containers. mailhog uses port 1025 For SMTP server. So, we need to use this port of Jenkins to send email. The second port can be used to access the user interface from our browser. Jenkins provides its own user interface on the port 8080,
2.2. running container
Let’s start the Docker container:
$ docker-compose up -d
Now we can access them on the ports mentioned above. Let’s start with MailHog and open http://localhost:8025/ in your browser. We should see this interface:
The emails will appear in a list as soon as we send them from Jenkins.
Now, let’s go to http://localhost:8080/ and also open Jenkins UI.
2.3. jenkins setup
Jenkins container takes some time to start and it shows a loading indicator on the UI. After that, we see a password prompt where we enter the generated administrator password.
On the next screen, We should install all suggested plugins And wait for it to end. Then, we can create a new user, but it is not necessary. Let’s leave it and continue as administrator. similarly, but instance configuration page, we can just click on save and finish. Now, we can use all the required functionalities.
3. Built-in Solution
Jenkins provides a built-in solution for sending emails. we can configure it in manage jenkins menu under configure system alternative.
Let’s scroll to the bottom of the page and take a look e-mail notification section:
Here, we need to configure SMTP details. This should be the address and port of the mailhog container. The SMTP server can only be a “mailhog” because two containers can reach each other. The port can be configured under advanced settings section and it should be set 1025 for this tutorial.
We can also test this configuration after checking the checkbox and providing the email address. Let’s apply the configuration and send a test email. We can verify this on the MailHog UI, a new email appeared in the list.
3.1. job use
We can send test emails from settings, but in real world scenarios, we want to receive emails about relevant events. For example, we want to be notified when a build fails. Let’s create a simple function for this which simply prints a message.
First, we will choose new item Create more from the menu on the left freestyle project With the name “email test job”.
When we create this task we are redirected to the configuration screen. let’s scroll down make steps add more execute shell Step. Let’s add a simple script here:
echo "Test job for sending emails."
Under this section, we can add some tasks which will be executed after our work. we will make one e-mail notification Post-construction action. Let’s set an email address as the recipient and save the task configuration:
Let’s save the configuration, then click build now To run this job and check the result. We see our message in the console output, but we didn’t receive any email via Mailhog. This is expected behavior in this case.
This email notification is only triggered for certain events. When a build fails, becomes unstable, or freezes, an e-mail will be sent. This means that we must create a situation where one of these events occurs. For example, we can create a failed build by modifying the executed shell script. Let’s exit this script with a non-zero exit code. This treats Jenkins as a failed build:
echo "Test job for sending emails." exit 1
Let’s run the task again and check the result. This execution is marked as failed in Jenkins and we have also received an email to Mailhog. The subject of the email is “Build failed in Jenkins: Email test job #2”. We can see the details in the body.
let’s remove get out off Command from script and run the task again. This time, the build status was successful and we received an email again. Subject “Jenkins Build Is Back to Normal: Email Test Job #3”. However, sometimes we need to be notified about more incidents and the Email Extensions plugin can help with that.
4. Email Extension Plugin
We can also use email extension plugin to send email from Jenkins. More importantly, it supports more events than the built-in solution.
let’s open configure system Menu. We should see a section titled Extended Email Notification,
Let’s use the same SMTP configuration values as we did in the previous example. SMTP server must be with “mailhog” 1025 Port. We can customize it as much as we want, but that’s enough for our example. Unfortunately, we cannot test the configuration of this plugin. Let’s try it in the job I used before.
4.1. job use
We will change the configuration of the “Email Test Job” used earlier. Let’s remove the previous post-build action and add a new one editable email notification,
First, let’s enter an email address list of project recipients Farm. Information will be received at this address. By default, this plugin only sends emails when a build fails. We should change it to see all the events that support it. Let’s open Advanced Settings and scroll down triggers, We can already see the trigger that sends an email to the developers if any of the builds fail:
Let’s remove this and replace it with a trigger of type Always, We can find many other types of triggers here as well. There are many other configuration options as well. For example, we can set who receives notifications, the subject and content of the email, or even add attachments. But, we can keep the default settings and save the job as for this example:
Let’s run it and take a look at our inbox at MailHog. We received an email about a successful build. Let’s refactor the job’s shell script and exit with an error code:
echo "Test job for sending emails." exit 1
If we run the task again, we receive an email notification about the failure. let’s remove get out off Command from script and check it one more time. As a result, we get an email saying that the build is fixed.
In this article, we looked at two different ways to send email notifications from Jenkins. First, we used a built-in solution that can send an email when the build fails or is stable again. Secondly, we have used the Email Extensions plugin which can be used when we need more control over the events that trigger the notifications.
- Enable HTTPS in Jenkins
- how to clone jenkins job
- Export/Import Jobs in Jenkins