Skip to content

Latest commit

 

History

History
608 lines (476 loc) · 26.5 KB

notify.md

File metadata and controls

608 lines (476 loc) · 26.5 KB

notify

This party of the pipeline provide useful notification steps.

With jenkins pipeline the sending of notifications lost some functionality. For example the

  • Still Failing
  • Still Unstable and
  • Fixed

results are no longer available (at the moment)

The notify.mail and notify.mattermost steps bring back parts of this convenience.

Table of contents

Build result specific configuration

The notify.mail and the notify.mattermost step support build result specific configurations.

With the configuration options for the build status, like

  • ConfigConstants.NOTIFY_ON_SUCCESS
  • ConfigConstants.NOTIFY_ON_FAILURE

you have the following configuration options. Simply enable it by setting the configuration option to true, or disable it by setting the value to false.

In more complex scenarios you can specify build result specific configurations like:

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

notifyMail(
    (NOTIFY) : [
        (NOTIFY_ON_FAILURE) : [
          (NOTIFY_TO) : "build-failure@example.com",
          (NOTIFY_ATTACH_LOG) : true,
        ],
        (NOTIFY_ON_FIXED) : [
          (NOTIFY_TO) : "build-fixed@example.com",
        ]
    ]
)

So you are able to configure for each build result custom options. You can use each non build result specific configuration options again in these configs maps (because placing a (NOTIFY_ON_FAILURE) inside a (NOTIFY_ON_FAILURE) wouldn't make sence).

💡 Please be aware that the build result specific configuration is merged with the "root" configuration! This especially affects the ConfigConstants.NOTIFY_RECIPIENT_PROVIDERS since this is a list.

notify.mail(Map config)

Examples

Default triggers with attached log and to-recipients

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

notifyMail(
    (NOTIFY) : [
        (NOTIFY_ATTACH_LOG): true,
        (NOTIFY_COMPRESS_LOG) : false,
        (NOTIFY_TO): "recipient1@domain.tld,recipient2@domain.tld"
    ]
)

Send only on first failure all participating developers

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

notifyMail(
    (NOTIFY) : [
        (NOTIFY_ATTACH_LOG): true,
        (NOTIFY_COMPRESS_LOG) : false,
        (NOTIFY_ON_ABORT) : false,
        (NOTIFY_ON_FAILURE) : true,
        (NOTIFY_ON_STILL_FAILING) : false,
        (NOTIFY_ON_FIXED) : false,
        (NOTIFY_ON_SUCCESS) : false,
        (NOTIFY_ON_UNSTABLE) : false,
        (NOTIFY_ON_STILL_UNSTABLE) : false,
        (NOTIFY_RECIPIENT_PROVIDERS): [[$class: 'DevelopersRecipientProvider']]
    ]
)

Custom Subject

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

notifyMail(
    (NOTIFY) : [
        (NOTIFY_SUBJECT): 'Custom notification for ${PROJECT_NAME} with status: ${NOTIFICATION_TRIGGER}',
    ]
)

❗ Make sure to use single quotes here because environment variables would otherwise be directly evaluated!

Configuration options

Complete list of all configuration options.

All configuration options must be inside the notify (ConfigConstants.NOTIFY) map element to be evaluated and used by the step.

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

notifyMail(
    (NOTIFY) : [
        (NOTIFY_ATTACH_LOG): false,
        (NOTIFY_ATTACHMENTS_PATTERN): '',
        (NOTIFY_BODY): null,
        (NOTIFY_COMPRESS_LOG): false,
        (NOTIFY_ENABLED): true,
        (NOTIFY_MIME_TYPE): null,
        (NOTIFY_ON_ABORT): true,
        (NOTIFY_ON_FAILURE): true,
        (NOTIFY_ON_STILL_FAILING): true,
        (NOTIFY_ON_FIXED): true,        
        (NOTIFY_ON_SUCCESS): false,    
        (NOTIFY_ON_UNSTABLE): true,
        (NOTIFY_ON_STILL_UNSTABLE): true,
        (NOTIFY_RECIPIENT_PROVIDERS) : null, 
        (NOTIFY_SUBJECT): '${PROJECT_NAME} - Build # ${BUILD_NUMBER} - ${NOTIFICATION_TRIGGER}',
        (NOTIFY_TO): "recipient@domain.tld"
    ]
)

attachLog (optional)
Constant ConfigConstants.NOTIFY_ATTACH_LOG
Type Boolean
Default false

Controls if the log should be attached to the mail.

💡 See Email Extension Plugin

attachmentsPattern (optional)
Constant ConfigConstants.NOTIFY_ATTACHMENTS_PATTERN
Type String, comma separated list of ANT patterns
Default ''

The pattern(s) for the attachments which should be send along with the email.

💡 See Email Extension Plugin

body (optional)
Constant ConfigConstants.NOTIFY_BODY
Type String
Default ${DEFAULT_CONTENT}

The body of the mail. The pipeline script assumes that you have a configured email template in place so default values is used ${DEFAULT_CONTENT}

💡 See Email Extension Plugin

compressLog (optional)
Constant ConfigConstants.NOTIFY_COMPRESS_LOG
Type Boolean
Default false

When set to true the log is attached to the mail as compressed zip.

💡 See Email Extension Plugin

enabled (optional)
Constant ConfigConstants.NOTIFY_ENABLED
Type Boolean
Default true

Disables the notifications when set to false

mimeType (optional)
Constant ConfigConstants.NOTIFY_MIME_TYPE
Type String
Default null

The mimeType of the mail. The pipeline script assumes that you have configured the mimeType in the "Extended E-mail Notification" section of your Jenkins instance.

💡 See Email Extension Plugin

onAbort (optional)
Constant ConfigConstants.NOTIFY_ON_ABORT
Type Boolean or Map with custom configuration
Default false

When set to true a notification is send when the job is aborted.

onFailure (optional)
Constant ConfigConstants.NOTIFY_ON_FAILURE
Type Boolean or Map with custom configuration
Default true

When set to true a notification is send when the job swiches to failure (first failure)

❗ For controlling the behavior when a job failes more than one time in a row see onStillFailing

onStillFailing (optional)
Constant ConfigConstants.NOTIFY_ON_STILL_FAILING
Type Boolean or Map with custom configuration
Default true

When set to true a notification is send when the job failed and the previous build failed.

onFixed (optional)
Constant ConfigConstants.NOTIFY_ON_FIXED
Type Boolean or Map with custom configuration
Default true

When set to true a notification is send when the job status switches from a non successful to successful.

onSuccess (optional)
Constant ConfigConstants.NOTIFY_ON_SUCCESS
Type Boolean or Map with custom configuration
Default false

When set to true a notification is send every time a job is successful.

onUnstable (optional)
Constant ConfigConstants.NOTIFY_ON_UNSTABLE
Type Boolean or Map with custom configuration
Default true

When set to true a notification is send when the job switches to unstable.

❗ For controlling the behavior when a job is unstable more than one time in a row see onStillUnstable

onStillUnstable (optional)
Constant ConfigConstants.NOTIFY_ON_STILL_UNSTABLE
Type Boolean or Map with custom configuration
Default true

recipientProviders (optional)
Constant ConfigConstants.NOTIFY_RECIPIENT_PROVIDERS
Type List of Map with RecipientProvider classes
Default [[$class: 'CulpritsRecipientProvider'],[$class: 'DevelopersRecipientProvider'],[$class: 'FailingTestSuspectsRecipientProvider'], [$class: 'FirstFailingBuildSuspectsRecipientProvider'],[$class: 'RequesterRecipientProvider'][$class: 'UpstreamComitterRecipientProvider']]

The list of recipient providers used to determine who should receive a notification. Per default all recipent providers (except ListProvider) are used.

💡 See Email Extension Plugin

subject (optional)
Constant ConfigConstants.NOTIFY_SUBJECT
Type String
Default ${PROJECT_NAME} - Build # ${BUILD_NUMBER} - ${NOTIFICATION_TRIGGER}

The subject for the mail.

💡 See Email Extension Plugin

to (optional)
Constant ConfigConstants.NOTIFY_TO
Type String, comma separated list of email adresses
Default null

Recipients that should always get a notification. This list has to be a comma separated String of mail adresses.

💡 See Email Extension Plugin

notify.mattermost(Map config)

The notify.mattermost step uses the Mattermost Notification Plugin to send build notifications to a mattermost instance using mattermost webhooks.

Generic Configuration support

This step supports the GenericConfig mechanism for loading and applying SCM_URL/JOB_NAME based auto-lookup for the appropriate configuration options.

💡 This method of configuration is recommended!

When using this mechanism the step expects a YAML pipeline resource with the path resources/jenkins-pipeline-library/notify/mattermost.yaml.

💡 An example for this mattermost.yaml is here: mattermost.yaml

Configuration options

Complete list of all configuration options.

All configuration options must be inside the NOTIFY_MATTERMOST (ConfigConstants.NOTIFY_MATTERMOST) map element to be evaluated and used by the step.

You have to provide at least a NOTIFY_MATTERMOST_CHANNEL and either a NOTIFY_MATTERMOST_ENDPOINT or a credential containing the endpoint by using NOTIFY_MATTERMOST_ENDPOINT_CREDENTIAL_ID.

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

NotificationTriggerHelper triggerHelper = this.getTriggerHelper()

String defaultMattermostMessage = "${triggerHelper.getTrigger()} - ${env.JOB_NAME} ${env.BUILD_NUMBER} (<${env.BUILD_URL}|Open>)"
String defaultColor = triggerHelper.getTrigger().getColor()

notify.mattermost( 
  (NOTIFY_MATTERMOST): [
      (NOTIFY_MATTERMOST_ENABLED)               : true,
      (NOTIFY_MATTERMOST_CHANNEL)               : null,
      (NOTIFY_MATTERMOST_ENDPOINT)              : null,
      (NOTIFY_MATTERMOST_ENDPOINT_CREDENTIAL_ID): null,
      (NOTIFY_MATTERMOST_ICON)                  : null,
      (NOTIFY_MATTERMOST_COLOR)                 : defaultColor,
      (NOTIFY_MATTERMOST_TEXT)                  : null,
      (NOTIFY_MATTERMOST_MESSAGE)               : defaultMattermostMessage,
      (NOTIFY_MATTERMOST_FAIL_ON_ERROR)         : false,
      (NOTIFY_ON_ABORT)                         : false,
      (NOTIFY_ON_FAILURE)                       : true,
      (NOTIFY_ON_STILL_FAILING)                 : true,
      (NOTIFY_ON_FIXED)                         : true,
      (NOTIFY_ON_SUCCESS)                       : false,
      (NOTIFY_ON_UNSTABLE)                      : true,
      (NOTIFY_ON_STILL_UNSTABLE)                : true
    ]
)

enabled (optional)
Constant ConfigConstants.NOTIFY_MATTERMOST_ENABLED
Type ``
Default ``

channel
Constant ConfigConstants.NOTIFY_MATTERMOST_CHANNEL
Type String
Default null

The channel to post messages to.

color (optional)
Constant ConfigConstants.NOTIFY_MATTERMOST_COLOR
Type String
Default Result.getColor()

The color for the message. When using the defaults the color is retrieved from the parsed build result object. See Result.groovy for the color definition.

endpoint
Constant ConfigConstants.NOTIFY_MATTERMOST_ENDPOINT
Type String
Default null

Configures the mattermost endpoint (e.g. webhook) to use. Overwrites endpointCredentialId/ConfigConstants.NOTIFY_MATTERMOST_ENDPOINT_CREDENTIAL_ID when set. Refer to Mattermost Notification Plugin documentation for more information.

endpointCredentialId
Constant ConfigConstants.NOTIFY_MATTERMOST_ENDPOINT_CREDENTIAL_ID
Type String
Default null

Specifies a secret text (String) credential to use as the Mattermost endpoint. Will not be used when endpoint/NOTIFY_MATTERMOST_ENDPOINT is configured.

failOnError (optional)
Constant ConfigConstants.NOTIFY_MATTERMOST_FAIL_ON_ERROR
Type Boolean
Default false

Controls if the step will fail when there are issues during sending the message.

icon (optional)
Constant ConfigConstants.NOTIFY_MATTERMOST_ICON
Type String
Default null

The icon to use for the message. Refer to Mattermost Notification Plugin documentation for more information.

message (optional)
Constant ConfigConstants.NOTIFY_MATTERMOST_MESSAGE
Type String
Default `"${triggerHelper.getTrigger()} - ${env.JOB_NAME} ${env.BUILD_NUMBER} (<${env.BUILD_URL}

The message of the mattermost notification. Refer to Mattermost Notification Plugin documentation for more information.

text (optional)
Constant ConfigConstants.NOTIFY_MATTERMOST_TEXT
Type String
Default null

Optional text. Refer to Mattermost Notification Plugin.

notify.mqtt(Map config)

The notify.mqtt step is basically a wrapper for the MQTT Notification Plugin.

Configuration options

Complete list of all configuration options.

All configuration options must be inside the notifyMqtt (ConfigConstants.NOTIFY_MQTT) map element to be evaluated and used by the step.

import static io.wcm.devops.jenkins.pipeline.utils.ConfigConstants.*

String defaultMqttMessage = """\
  JOB_DISPLAY_URL: '${env.getProperty("JOB_DISPLAY_URL")}'
  RUN_CHANGES_DISPLAY_URL: '${env.getProperty("RUN_CHANGES_DISPLAY_URL")}'
  BUILD_RESULT: '${currentBuild.result}'
  JOB_NAME: '${env.getProperty("JOB_NAME")}'
  BUILD_NUMBER: '${env.getProperty("BUILD_NUMBER")}'"""

notify.mqtt( 
  (NOTIFY_MQTT) : [
    (NOTIFY_MQTT_BROKER)        : null,
    (NOTIFY_MQTT_CREDENTIALS_ID): '',
    (NOTIFY_MQTT_ENABLED)       : true,
    (NOTIFY_MQTT_MESSAGE)       : defaultMqttMessage,
    (NOTIFY_MQTT_QOS)           : "0",
    (NOTIFY_MQTT_RETAIN)        : false,
    (NOTIFY_MQTT_TOPIC)         : "jenkins/${env.getProperty('JOB_NAME')}",
  ]
)

The minimal configuration is as follows:

Map config = [
  (NOTIFY_MQTT) : [
    (NOTIFY_MQTT_BROKER) : "tcp://localhost:1883"
  ]
]
notify.mqtt(config)

broker (mandatory)
Constant ConfigConstants.NOTIFY_MQTT_BROKER
Type String
Default null

This setting is mandatory. Example:

Map config = [
  (NOTIFY_MQTT) : [
    (NOTIFY_MQTT_BROKER) : "tcp://localhost:1883"
  ]
]

credentialsId (optional)
Constant ConfigConstants.NOTIFY_MQTT_CREDENTIALS_ID
Type String
Default ''

Specifies the username/password credentials to use.

enabled (optional)
Constant ConfigConstants.NOTIFY_MQTT_ENABLED
Type Boolean
Default true

Enables/Disables the notifications.

message (optional)
Constant ConfigConstants.NOTIFY_MQTT_MESSAGE
Type String
Default see below

Specifies the MQTT message to send, default:

String defaultMqttMessage = """\
  JOB_DISPLAY_URL: '${env.getProperty("JOB_DISPLAY_URL")}'
  RUN_CHANGES_DISPLAY_URL: '${env.getProperty("RUN_CHANGES_DISPLAY_URL")}'
  BUILD_RESULT: '${currentBuild.result}'
  JOB_NAME: '${env.getProperty("JOB_NAME")}'
  BUILD_NUMBER: '${env.getProperty("BUILD_NUMBER")}'"""

qos (optional)
Constant ConfigConstants.NOTIFY_MQTT_QOS
Type String
Default '0'

Specifies the MQTT qos to use.

retain (optional)
Constant ConfigConstants.NOTIFY_MQTT_RETAIN
Type Boolean
Default 'false'

Sets the message retain option.

topic (optional)
Constant ConfigConstants.NOTIFY_MQTT_TOPIC
Type String
Default jenkins/${env.getProperty('JOB_NAME')}

Specifies the MQTT topic to send.