PagerDuty v2 Jenkins Plugin

This guide covers installing and configuring the rebelcore/jenkins-plugin-pagerduty-v2 Jenkins plugin, which sends incident events to PagerDuty Events API v2 from Jenkins builds. It supports Freestyle/classic jobs via a post-build notifier and Pipeline via a pagerDutyV2 step.

What this plugin does

  • Sends PagerDuty Events API v2 trigger and resolve events from Jenkins.
  • Provides:
    • Freestyle / classic jobs post-build notifier
    • Pipeline step: pagerDutyV2(...)
  • Uses a deterministic trigger → resolve workflow by storing the exact trigger payload per build and replaying it for resolve.

Prerequisites

  • A working Jenkins controller (admin access required)
  • Java + Maven (for building the plugin locally)
  • A PagerDuty account and an Events API v2 routing key (integration key)

PagerDuty setup (get a routing key)

  1. In PagerDuty, create or use an integration from AIOps Event Orchestration.
  2. Copy the Integration Key (aka routing key).

Jenkins setup (credential)

Create a Jenkins credential to store your routing key:

  1. Manage Jenkins → Credentials → (choose a domain) → Add Credentials
  2. Kind: Secret text
  3. Secret: (PagerDuty integration key / routing key)

Install the plugin

Current Release

Current Release

Upload to Jenkins

  1. Manage Jenkins → Manage Plugins → Advanced
  2. Upload the generated pagerduty-v2.hpi or pagerduty-v2.jpi
  3. Restart Jenkins if prompted.

Global configuration (required)

Go to Manage Jenkins → System → PagerDuty v2.

1) Routing key credential (required)

Set Routing key credential (Secret Text) to the credential you created earlier.

2) Events API v2 endpoint

  • Default: https://events.pagerduty.com/v2/enqueue
  • Only override if you’re using a proxy/test endpoint.

3) Disable notifications (kill switch)

If enabled, the plugin will send nothing and logs: [pagerduty-v2] PagerDuty is disabled in system configuration; skipping.

4) Require Tags (optional)

If enabled, jobs can’t be saved unless Tags are provided in the job notifier config.

5) Service list (optional but recommended)

You can restrict “Service” values to a known list (one-per-line and/or comma-separated).

Example:

payments
search, onboarding
ops-tools

Behavior:

  • If configured: Freestyle job shows a dropdown; selection must match the allowed list.
  • If not configured: Freestyle job shows a free-text Service field.

Configure Freestyle / classic jobs

  1. Open your job → Configure
  2. Add Post-build Actions → PagerDuty v2

Service (required)

  • If a global Service list exists: choose from dropdown (placeholder is invalid).
  • Otherwise: enter any service string.

The service is used in:

  • payload.component
  • payload.custom_details.service

Tags (optional or required)

Comma-separated string like: team=oncall,env=prod,app=payments

Custom summary (optional)

If blank, the default summary is: Jenkins <JOB_NAME> build <BUILD_NUMBER>

Severity (trigger events)

Choose one of:

  • critical, error, warning, info

Trigger conditions

Enable which build results should trigger:

  • SUCCESS, FAILURE, UNSTABLE, ABORTED, NOT_BUILT

Consecutive builds before trigger (noise reduction)

If set to N > 1, the plugin only triggers after N consecutive builds match the trigger condition.

Resolve when back to normal

If enabled, on SUCCESS the plugin searches backwards for the most recent open incident and resolves it.

Console log tail (optional)

If enabled, it adds the last N lines of console output to:

  • payload.custom_details.console_log_tail

Pipeline usage

The plugin provides a pipeline step named pagerDutyV2.

Trigger

pagerDutyV2(action: 'trigger', severity: 'critical')

Resolve

pagerDutyV2(action: 'resolve')

Resolve searches backwards through build history to find the most recent open incident and resolves it; if none exist it prints: No open incident found; nothing to resolve.

Example Jenkinsfile snippet

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        sh 'make test'
      }
    }
  }
  post {
    failure {
      pagerDutyV2(action: 'trigger', severity: 'error')
    }
    success {
      pagerDutyV2(action: 'resolve')
    }
  }
}

Note: The pipeline step currently does not accept service/tags parameters; it sends the base payload from Jenkins environment variables + severity.

Troubleshooting

“No routing key credential configured; skipping.”

Set the routing key credential in Manage Jenkins → System → PagerDuty v2.

“Service is required; skipping PagerDuty notification.”

Set the Service in job configuration; if using a global Service list, choose a real entry (not the placeholder).

HTTP failures (enqueue failed)

If PagerDuty returns non-2xx, the plugin throws an IOException that includes HTTP code and a response snippet. Common causes include wrong routing key, firewall/proxy blocks, TLS interception, or PagerDuty outage.

Resolve didn’t happen

Freestyle resolve requires:

  • Resolve enabled
  • Current build is SUCCESS
  • A previously stored open action exists in build history

Pipeline resolve requires a prior pagerDutyV2(action: 'trigger') that stored an open action.