Allows users to send Change Events and trigger postbuild Incidents via PagerDuty
- Support for PagerDuty Change Events API
- Trigger incidents on various job statuses Success/Failure/Aborted/Unstable/Not_Built
- Trigger incidents based on number of consecutive build results
- Automatically Resolve incidents when job is back to normal
- Pipeline compatible
- TokenMacro consumer (TokenMacro - adds reusable macro expansion capability)
- Jenkins version 1.580.1 or newer is required.
- PagerDuty account (you can create a free developer account here)
Before you can use this plugin you'll need an integration key (also known as a routing key). This key tells PagerDuty which service the incoming event should be sent to. If you already have a service in PagerDuty you can add an integration to it; otherwise, you can add the integration when creating a new service. For the integration type, choose "Jenkins CI".
Once you have an integration key you can add the appropriate action to your Jenkins project and supply it with the integration key. Be sure to select which job results you want to send an event to PagerDuty.
There is a break in backwards compatibility between versions 4.x.x and 6.x.x
if you are migrating from earlier versions to 6.x.x and above note the following changes:
- serviceKey is replaced with routingKey
- incidentKey is replaced with dedupKey
- incDescription/incDetails are replaced with incidentSummary
- please note the new fields introduced starting version 6.x.x
PLEASE NOTE - routing key and integration key are the same thing!
pagerduty(resolve: false, routingKey: "$ROUTING_KEY [NOT NULL]", dedupKey:"$DEDUP_KEY", incidentSummary:"$INCIDENT_SUMMARY", incidentSource: "$INCIDENT_SOURCE", incidentSeverity:"$INCIDENT_SEVERITY", incidentComponent:"$INCIDENT_COMPONENT", incidentGroup:"$INCIDENT_GROUP", incidentClass:"$INCIDENT_CLASS")
if resolve == false, pagerduty triggers an incident and returns the incidentKey
pagerdutyChangeEvent(integrationKey: '$INTEGRATION_KEY')
You can choose one (or both) of the options to use PagerDuty
Using the "PagerDuty Incident Trigger" action, you can trigger or resolve incidents based on the results of a job.
Using the "PagerDuty Change Events" action, you can create a change event when a job completes.
The configuration of a freestyle job allows for including PagerDuty change events as build steps by passing the integration key, a custom summary text field and custom details in JSON format. If the summary text field is left blank, the default description of the Jenkins build job and its build number are used. Custom details are optional. Any custom details provided will be merged into the default custom detail fields (build number, cause, duration). Token substitution works on all fields. Note in the post build version, you need to use a slightly different syntax. Ex. ${ENV, var="PD_INTEGRATION_KEY"}
Here's an example of a freestyle job configuration page:
The PagerDuty change event results of the above freestyle job are shown below:
(thanks Bryan Bishop and Adam Krapfl!)
- ChangeEvent custom summary text
- Support for tokenized strings in ChangeEvent
- Freestyle job change events (Resolves JENKINS-64774 and #51)
- Bug Fixes
- Documentation Fix
- Bug Fixes (Resolves JENKINS-64485 and #43)
- Add Change Events support (thanks Adam Vaughan!)
- Bug fixes
- Remove Jetty dependency from pom
- Move docs to Github
- Add Change Events support (thanks Adam Vaughan!)
- Bug fixes
- <<< THIS VERSION BREAKS BACKWARDS COMPATIBILITY WITH EARLIER VERSIONS >>>
- Add TokenMacro support
- Bug fixes
- Code refactor
- Pipeline compatible
- Code refactor
- Bug fixes
- Allow automatic resolution of the incident on BACK-TO-NORMAL (from not success to success)
- Bug fixes
- Allow triggering alert in all job statuses (SUCCESS/FAILED/ABORTED/UNSTABLE/NOT_BUILT)
- Allow using multiple service keys for different job
- Allow using Environment Variables for config
- Initial public release