> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jenkins change integration

> Sync every build of your Jenkins deployment jobs to Flashduty On-call through the Jenkins Notification plugin, as change events you can correlate with alerts and incidents.

<Tip>**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/)</Tip>

Use the Jenkins [Notification plugin](https://plugins.jenkins.io/notification/) to sync job builds to Flashduty On-call. Each build becomes one Flashduty change; the build's start and finish update that same change.

Jenkins cannot tell whether a build changed anything, so add the notification only to **jobs that deploy**, not to jobs that only compile or test.

<div className="hide">
  ## In Flashduty On-call

  ***

  1. In the Flashduty console, go to **Integration Center → Change Events**
  2. Select **Jenkins** and enter an integration name
  3. To assign changes to specific channels, add rules under the integration's **Routes** that match labels such as `job`
  4. Click **Save** and copy the generated **Push URL**
</div>

## Configure Jenkins

***

<Steps>
  <Step title="Check the Jenkins URL">
    Go to **Manage Jenkins → System** and make sure **Jenkins URL** under **Jenkins Location** is set to the address of your Jenkins. Without it, notifications carry no build link, Flashduty cannot identify the build, and the delivery is rejected.
  </Step>

  <Step title="Install the Notification plugin">
    Go to **Manage Jenkins → Plugins → Available plugins**, search for **Notification**, and install it. You need Jenkins administrator permission.

    The plugin also needs the **JUnit** plugin, which Jenkins does not install with it. If **Manage Jenkins → Plugins → Installed plugins** does not list JUnit, install it too. Without JUnit, no notification is sent and the build log shows `NoClassDefFoundError: hudson/tasks/test/AbstractTestResultAction`.
  </Step>

  <Step title="Add the endpoint to a deployment job">
    1. Open the deployment job, click **Configure**, find the **Job Notifications** section, and click **Add Endpoint**
    2. **Format**: select `JSON`
    3. **Protocol**: select `HTTP`
    4. **Event**: select `All Events`, so Flashduty sees the build both start and finish
    5. **URL Source**: select `Credentials Store`, save the complete Flashduty integration Push URL as a **Secret text** credential, and select that credential in **URL**. With `Plain Text`, the plugin prints the full Push URL, including `integration_key`, in the log of every build
    6. Keep **Branch** at the default `.*`, leave the other options at their defaults, and click **Save**

    If the job configuration is managed by a Jenkinsfile (for example, a multibranch pipeline), add the same settings to the Jenkinsfile's `properties`. You can generate the code on the pipeline's **Pipeline Syntax → Snippet Generator** page by selecting `properties: Set job properties`.
  </Step>

  <Step title="Run a build">
    Run the job once; the change appears in the Flashduty change list. The Notification plugin has no test button. If Jenkins cannot reach Flashduty, the build log shows `Failed to notify endpoint`; the plugin does not check the response, so a delivery that Flashduty rejects is not shown in Jenkins.
  </Step>
</Steps>

## What one change is

***

Each build is one change. Its change key (change\_key) is `<full build URL>#<queue ID>`, for example `https://jenkins.example.com/job/deploy/18/#4711`.

* Every phase of one build updates the same change
* Two builds of the same job are two changes
* When a job is deleted and recreated and its build numbers restart at 1, the queue IDs differ, so new builds are not merged into old ones
* When several Jenkins instances send to the same integration, their build URLs differ, so their builds are kept apart

## Status mapping

***

| Build phase (phase) | Build result (status) | Flashduty change status |
| - | - | - |
| STARTED | — | Processing |
| COMPLETED, FINALIZED | SUCCESS | Done |
| COMPLETED, FINALIZED | UNSTABLE | Done |
| COMPLETED, FINALIZED | FAILURE | Failed |
| COMPLETED, FINALIZED | ABORTED, NOT\_BUILT | Canceled |

Done, Failed, and Canceled are end states; Flashduty records the change's end time when one arrives. COMPLETED means the build steps have finished; FINALIZED means post-build actions (such as archiving artifacts) have finished too. Both carry the same result.

UNSTABLE means every build step ran, but tests or quality checks reported problems, so it is recorded as Done; use the `result` label to filter these changes.

The plugin sends QUEUED only when the build starts, never while the build waits in the queue. Flashduty accepts QUEUED without recording it, so a change appears when its build starts.

A `notifyEndpoints` step in a pipeline with `phase` set to `NONE` is accepted without creating a change.

## Change content

***

| Field | Content |
| - | - |
| Title | `<full job name> #<build number>`, such as `platform/order-service/main #18` |
| Description | The endpoint's **Notes** option; empty when not set |
| Link | The build page |

Labels can be used in routes and to filter the change list:

| Label | Description |
| - | - |
| `job` | Full job name, including folders and the branch of a multibranch pipeline, such as `platform/order-service/main` |
| `build_number` | Build number |
| `branch` | The Git branch the build checked out |
| `commit` | The Git commit the build checked out |
| `phase` | The latest build phase |
| `result` | The build result, present once the build has finished |

`branch` and `commit` are sent only by freestyle jobs that use Git under **Source Code Management**. A Pipeline job that checks out with the `git` step does not send them. A notification sent when the build starts can carry the values from before this build's checkout, so rely on the values at the end of the build. Route on `job`; otherwise the early and late events of one build can land in different channels.

## FAQ

***

<AccordionGroup>
  <Accordion title="Why are no changes arriving?">
    * Make sure **Format** is `JSON` and **Protocol** is `HTTP`
    * Make sure **Jenkins URL** is set under **Manage Jenkins → System**
    * Look for `Notifying endpoint` or `Failed to notify endpoint` in the build log
    * `NoClassDefFoundError: hudson/tasks/test/AbstractTestResultAction` in the build log means the JUnit plugin is missing. Install it
    * When **Branch** is not `.*`, only builds that have a `BRANCH_NAME` environment variable matching it send notifications
  </Accordion>

  <Accordion title="Why does one build have two end events?">
    The plugin sends one notification when the build completes (COMPLETED) and another when post-build actions finish (FINALIZED). Both carry the same result, so the change status does not change. When both arrive within the same second, the second one is not recorded. To receive only one, set **Event** to `Job Finalized`, but then the running phase is not shown.
  </Accordion>

  <Accordion title="Which deliveries does Flashduty reject?">
    Flashduty rejects a delivery in these cases:

    * `build.full_url is missing`: the Jenkins URL is not configured
    * `build.queue_id is missing`: the payload has no queue ID. Make sure the delivery comes from the Notification plugin
    * `build.status is missing`: an end phase arrived without a build result, usually from a pipeline calling `notifyEndpoints(phase: 'COMPLETED')` or `'FINALIZED'` before the result is set
    * `must use Format JSON`: the endpoint's **Format** is `XML`
    * `unsupported build.phase` or `unsupported build.status`: Flashduty received a phase or result it does not support yet. Contact us
  </Accordion>
</AccordionGroup>