How to modify Jenkins Email Notifications?

jenkins-plugin-cli --plugins email-ext:1806.v856a_01a_fa_39a_

Email Extension

Jenkins Email Extension Plugin

What is Email Extension Plugin?​

This plugin is an extension of the existing Mailer plugin, and it significantly expands what we can do with it.

Key Features:

• Triggers: We can now set specific conditions that prompt an email notification. This makes our alerts much more targeted.
• Content: For each condition that triggers an email, we can define what the subject line and the body of the email will say. It’s customizable to fit our needs.
• Recipients: It also allows us to specify who should receive these notifications, ensuring the right people are informed at the right time.

It lets us automate updates and alerts, which means less manual oversight and more focus on what really matters.

How to use Email Extension Plugin on Jenkins?​

It’s a bit of a step up from what we've used before, offering more flexibility and control.

System-wide Setup: First off, we need to handle some configurations that apply across the board. You’d start on the Jenkins system-wide configuration page. Look for the section titled Extended E-mail Notification. It’s similar to what we have under the standard Mailer plugin, but with some extras. You can set default subjects, content, and recipients for emails right there. This is really handy because it standardizes our initial setup, and we only tweak it project by project if needed.

Project-specific Setup: For each project that uses this plugin:

1. Go to the project’s configuration page.
2. In the Post-build Actions section, add an Editable Email Notification.
3. You’ll find fields to specify recipients (either comma or whitespace-separated), and default tokens for subjects and content of the emails. These tokens help us quickly align all project emails to our standard setup.

The great thing here is the customization level—configuring once system-wide and tweaking per project as necessary. It seems like this will simplify our workflow and ensure everyone necessary gets the updates they need without extra fuss.

Pipeline Step

Here's a basic example of how to send an email using the emailext step:

emailext body: 'Test Message',
    subject: 'Test Subject',
    to: '[email protected]'

We can also specify additional recipients dynamically using the recipientProviders parameter. For instance, to include all developers involved in a change and the person who triggered the build, you'd configure it like this:

emailext body: 'Test Message',
    recipientProviders: [developers(), requestor()],
    subject: 'Test Subject',
    to: '[email protected]'

Additionally, this plugin’s recipient providers can be utilized with the traditional Mailer plugin to enhance its functionality. For example, to notify culprits of a build failure and the build initiator, we'd use:

step([$class: 'Mailer',
  notifyEveryUnstableBuild: true,
  recipients: emailextrecipients([culprits(), requestor()])])

These examples show how our new tools can make our email notifications more targeted and effective. Let's discuss how we can further integrate this into our projects.

How to configure Email Extension Plugin on Jenkins?​

It's pretty robust, so here’s a breakdown of the key features and how to configure them:

Advanced Configuration: To access the advanced settings, click on the Advanced button in the plugin settings. Here, you can define:

• Recipients for Each Trigger: Choose who gets notified for each type of email trigger.
• Pre-send Script: A script to modify the email before it's sent, such as adding headers or changing the body.

Pre-send and Post-send Scripts: These scripts let you manipulate the email:

• msg (MimeMessage): Modify the actual email message.
• logger (PrintStream): Log messages to the build log.
• build/run (AbstractBuild/Run): Reference the build.
• cancel (boolean): Set to true to stop the email from being sent.

Triggers Overview:

• Aborted: Sends an email if the build is manually aborted.
• Always: Always sends an email post-build, regardless of status.
• Before Build: Sends an email right after SCM polling but before the build starts.
• Failure → Unstable (Test Failures): Notifies when the build moves from failure due to build issues to unstable due to test failures.
• Failure - Any: Triggers an email whenever the build fails.
• Fixed: Notifies when a build changes from failure or unstable to success.
• Not Built: Sends an email if the build couldn’t start in multi-stage setups.
• Script - After/Before Build: Executes a custom script to decide whether to send an email.
• Status Changed: Notifies when the build status changes.
• Success: Triggers an email if the build succeeds.
• Test Improvement/Regression: Sends notifications based on test performance changes.
• Unstable (Test Failures): Emails when there are test failures, but other steps are successful.

This plugin gives us powerful options to keep our team updated about build statuses and issues automatically. Let's make sure to configure it to best suit our workflow needs.

We've delved deeper into setting up triggers for our new email notification plugin and wanted to outline the common options available, which can be quite handy:

Common Trigger Options:

• Recipient List: Adds recipients from the Project Recipient List we set earlier.
• Developers: Targets emails to developers who committed code in the last build. The plugin auto-generates email addresses by appending a default suffix from the system settings.
• Requestor: Sends notifications to the user who manually initiated the build.
• Include Culprits: Includes anyone who committed code since the last successful build alongside developers.
• Previous: Targets the culprits, requestor, and developers from previous builds.

Advanced Configuration per Trigger:

• Recipient List: You can specify additional email addresses here, which will append to the project's recipient list.
• Subject and Content: Set specific subject lines and email body content for triggers.

Script Trigger Options: Using Groovy scripts, we can decide the condition under which emails are sent:

• Script - Before Build: This might notify people a new build is starting if the last one failed.

  build.previousBuild.result.toString().equals('FAILURE')
  
• Script - After Build: Can be set to send an email only under specific conditions like a build failure involving a certain user or specific log messages.

  // Email if the build failed and 'mickeymouse' had a commit
  build.result.toString().equals('FAILURE') && build.hasParticipant(User.get('mickeymouse'))
  
  // Email if the word {{ERROR}} is found in build logs
  build.logFile.text.readLines().any { it =~ /.*ERROR.*/ }
  

These features enhance our ability to manage notifications precisely, making sure the right people get the necessary info at the right time. We should consider how to best implement these in our projects to improve our workflow.

Attachments​

We can attach files to our emails using Ant pattern matching, which is already familiar to us from various Jenkins configurations.

Here’s what’s new:

• Attachments: We can specify file patterns to automatically attach relevant files to our emails. This uses the Ant pattern matching syntax.
• Attachment Size Limit: While there's no limit by default, we can set a maximum size for attachments in the Extended E-mail Notification section of the system configuration. This helps in preventing overly large files from being sent.

This feature should be super useful for including logs, reports, or any relevant documents in our automated emails, especially when sharing build artifacts or detailed error logs might be necessary.

Let me know if you need more info on setting this up or if you want to walk through the configuration together.