Jenkins: Trigger types explanation for Editable Email Notification

Question

In Jenkins for Editable Email Notification, to create a Trigger:

The following items/options:

Question

Is there an official documentation explaining each item shown in the select box? - Of course, some are obvious, others no

Jira

Just in case I created:

• Improve documentation to explain each Trigger's item

Answer 1

I agree the lack of an overall description on the plugins page and forcing the user to add each option and click (?) to find out its purpose is a poor user experience. However, most of the conditions appear to be self-explanatory. A JIRA feature improvement is a reasonable request.

A basic user could reasonably ignore most of them, but as a Dev, if you think you have a condition/state transition that requires special notification, it's probably covered in the list. The conditions are laid out in the code the descriptors are inside the individual help files <condition>/help.html.

The condition categories are (not sure what's not obvious):

• Before Build
• [If] Not Built
• Aborted
• Always
• [Any] Status Changed
• Failure; various criteria [ 1st, 2nd, Any, Still, X ]
• Failure -> Unstable (Test Failures)
• Unstable (Builds but has Test Failures); various criteria [ 1st, Any, Still, F->S ]
• Fixed (Failed Build -> Now Builds successfully)
• Success
• Run Script ( Before / After Build ) (Script evaluates to success, send email)

From my interpretation (not reading below) of criteria, Any is Any failure, regardless of prior result. 1st is ONLY on first failure, 2nd is ONLY on 2nd failure, "X" is on "X" number of (or n-th) failures. Still is every time AFTER more than one failure in a row; so not on first fail. Success resets all counters to zero.

---

I've pulled the "help" explanations (as of v.2.83) here (clone| grep | sed):

AbortedTrigger : An email will be sent if the build status is "Aborted". A build is aborted via the UI or API, but normally requires some sort of user intervention to occur. An aborted build is stopped during its execution.

AlwaysTrigger : Always triggers an email after the build, regardless of the status of the build.

BuildingTrigger : An email will be sent any time the build goes from failing (compilation or build step failures), to unstable (unit test failures). This basically means that all the builds steps were successful, but there are still tests failing.

FailureTrigger : An email will be sent any time the build fails. If the "Failure - Still" trigger is configured, and the previous build status was "Failure", then the "Failure - Still" trigger will send an email instead.

FirstFailureTrigger : An email will be sent when the build status changes from "Success" to "Failure"

FirstUnstableTrigger : An email will be sent when the build status changes from anything to "Unstable".

FixedTrigger : An email will be sent when the build status changes from "Failure" or "Unstable" to "Success".

FixedUnhealthyTrigger : An email will be sent when the build status changes from "Failure" or "Unstable" to "Success". Intermediate "Aborted" builds are ignored.

ImprovementTrigger : An email will be sent any time there is an improvement. A build is considered to have improved whenever it has fewer test failures than the previous build. If the current failure count went to 0 (no more test failures) this trigger will NOT send an email.

NotBuiltTrigger : An email will be sent if the build status is "Not Built". This status code is used in a multi-stage build (like maven2) where a problem in earlier stage prevented later stages from building.

PreBuildScriptTrigger : the build occurs. The last line of the script should resolve to true to send an email, or false to not send an email. There are four objects added to the model for the script to use to interact with the build. Example:

// the last line in the script should resolve to a boolean true or false 
// only send am email if the previous build failed 
// this could be used to notify people that a new build is happening
build.previousBuild.result.toString().equals('FAILURE')

PreBuildTrigger : An email will be sent when the build begins, but after SCM polling has completed.

RegressionTrigger : An email will be sent any time there is a regression. A build is considered to regress whenever it has more failures than the previous build, or if there are new tests that failed.

ScriptTrigger : the build occurs. The last line of the script should resolve to true to send an email, or false to not send an email. There are four objects added to the model for the script to use to interact with the build. Example:

// the last line in the script should resolve to a boolean true or false 
// only send am email if the build failed and 'mickeymouse' had a commit
build.result.toString().equals('FAILURE') && build.hasParticipant(User.get('mickeymouse'))

SecondFailureTrigger : An email will be sent when the build fails twice in a row after a successful build.

StatusChangedTrigger : An email will be sent if the build status changes.

StillFailingTrigger : An email will be sent if the build status is "Failure" for two or more builds in a row.

StillUnstableTrigger : An email will be sent if the build status is "Unstable" for two or more builds in a row. A build is unstable if there are test failures, but all the build steps completed successfully.

SuccessTrigger : An email will be sent if the build status is "Successful". If the "Fixed" trigger is configured, and the previous build status was "Failure" or "Unstable", then the "Fixed" trigger will send an email instead.

UnstableTrigger : An email will be sent any time the build is unstable. A build is unstable if there are test failures, but all the build steps completed successfully. If the "Unstable - Still" trigger is configured, and the previous build status was "Unstable", then the "Unstable - Still" trigger will send an email instead.

XNthFailureTrigger : An email will be sent when the build fails X times in a row after a successful build.

Answer 2

See Email Extension, Triggers

Once you have added a trigger, you have several options. To see what conditions must be met for this plugin to send an email, click on the "?" (question mark) next to the trigger.

So, actually see its inline help () after adding a trigger.

Answer 3

Seems like the docs in the Jenkins plugin page has been improved a bit. (Version: 2.92)

https://plugins.jenkins.io/email-ext/#plugin-content-triggers

Triggers By default, the only trigger configured is the Failure - Any trigger. To add more triggers, select one from the drop-down and it will be added to the list. To see what conditions must be met for this plugin to send an email, click on the "?" (question mark) next to the trigger.

Extended Email Publisher Triggers The following triggers are available as part of the Extended Email Publisher plugin, other plugins can provide triggers as well through the extension point defined in the Extended Email Publisher:

Aborted An email will be sent if the build status is "Aborted". A build is aborted via the UI or API, but normally requires some sort of user intervention to occur. An aborted build is stopped during its execution.

Always Always triggers an email after the build, regardless of the status of the build.

Before Build An email will be sent when the build begins, but after SCM polling has completed.

Failure → Unstable (Test Failures) An email will be sent any time the build goes from failing (compilation or build step failures), to unstable (unit test failures). This basically means that all the builds steps were successful, but there are still tests failing.

Failure - Any An email will be sent any time the build fails. If the "Failure - Still" trigger is configured, and the previous build status was "Failure", then the "Failure - Still" trigger will send an email instead.

Failure - 1st An email will be sent when the build status changes from "Success" to "Failure".

Failure - 2nd An email will be sent when the build fails twice in a row after a successful build.

Failure - Still An email will be sent if the build status is "Failure" for two or more builds in a row.

Failure - X An email will be sent when the build fails X times in a row after a successful build

Fixed An email will be sent when the build status changes from "Failure" or "Unstable" to "Success".

Not Built An email will be sent if the build status is "Not Built". This status code is used in a multi-stage build (like maven2) where a problem in earlier stage prevented later stages from building.

Script - After Build Allows the user to define a script that is executed to determine if an email should be sent AFTER the build occurs. The last line of the script should resolve to true to send an email, or false to not send an email. See Script Trigger Options below for parameters available to the script.

Script - Before Build Allows the user to define a script that is executed to determine if an email should be sent BEFORE the build occurs. The last line of the script should resolve to true to send an email, or false to not send an email. See Script Trigger Options below for parameters available to the script.

Status Changed An email will be sent if the build status changes.

Success An email will be sent if the build status is "Successful". If the "Fixed" trigger is configured, and the previous build status was "Failure" or "Unstable", then the "Fixed" trigger will send an email instead.

Test Improvement An email will be sent any time there is an improvement. A build is considered to have improved whenever it has fewer test failures than the previous build. If the current failure count went to 0 (no more test failures) this trigger will NOT send an email.

Test Regression An email will be sent any time there is a regression. A build is considered to regress whenever it has more failures than the previous build, or if there are new tests that failed.

Unstable (Test Failures) An email will be sent any time the build is unstable. A build is unstable if there are test failures, but all the build steps completed successfully. If the "Unstable - Still" trigger is configured, and the previous build status was "Unstable", then the "Unstable - Still" trigger will send an email instead.

Unstable (Test Failures) - 1st An email will be sent when the build status changes from anything to "Unstable".

Unstable (Test Failures) - Still An email will be sent if the build status is "Unstable" for two or more builds in a row. A build is unstable if there are test failures, but all the build steps completed successfully.

Unstable (Test Failures)/Failure → Success An email will be sent when the build status changes from "Failure" or "Unstable" to "Success". Intermediate "Aborted" builds are ignored.