---
title: CI Insights Setup – Jenkins
description: Enable Mergify CI Insights and configure flaky test detection using Jenkins.
---

import { Image } from "astro:assets"
import JenkinsConfiguration from "../../../images/ci-insights/jenkins-configuration.png"
import JenkinsInstallation from "../../../images/ci-insights/jenkins-installation.png"
import JobsScreenshot from "../../../images/ci-insights/jobs.png"

## Enabling CI Insights for Jenkins

1. Enable CI Insights on your repositories by visiting the [GitHub Integration
   page](https://dashboard.mergify.com/integrations/github)
   ([docs](/integrations/github)).

2. Install and configure the [Mergify Jenkins plugin](https://plugins.jenkins.io/mergify/):

   **Installation:**
   - Go to `Manage Jenkins` → `Manage Plugins`
   - Select the `Available` tab
   - Search for `Mergify` and select the checkbox next to `Mergify Plugin`
   - Install the plugin using one of the install buttons at the bottom
   - To verify installation, search for `Mergify Plugin` on the `Installed` tab

   <Image src={JenkinsInstallation} alt="CI Insights Jenkins installation" />

   **Configuration:**
   After installation, you need to add a Mergify application key with `ci`
   scope for each GitHub organization you want to support. Go to `Manage
   Jenkins` → `Configure System` and configure the Mergify plugin with your
   application keys.

   <Image src={JenkinsConfiguration} alt="CI Insights Jenkins configuration" />

   **Note**: It's highly recommended to set the GitHub project URL for each job
   if you're not using the [GitHub Branch Source plugin](https://plugins.jenkins.io/github-branch-source/).
   This ensures proper correlation between Jenkins jobs and GitHub repositories.

3. Configure your Jenkins pipeline job with the `MERGIFY_TOKEN` environment variable.
   First, create an application key with `ci` scope as described in the [API Usage documentation](/api/usage).

   Then add the key to Jenkins credentials and configure your pipeline to use it:

   ```groovy
   pipeline {
       agent any
       environment {
           MERGIFY_TOKEN = credentials('MERGIFY_TOKEN')
       }
       ...
   }
   ```

   Make sure to store your application key as a Jenkins credential with the ID `MERGIFY_TOKEN`.

4. Click on `CI Insights` in the Mergify dashboard navigation.
   You should start seeing your Jenkins job runs appear:

   <Image src={JobsScreenshot} alt="CI Insights Jobs" />

## Setting Up Flaky Test Detection

To effectively detect flaky tests, you need to run the same tests multiple
times on the same code (identified by the SHA1 of the repository). This section
explains how to set up your CI to systematically detect flaky tests.

### Prerequisites

Before setting up flaky test detection, ensure you have:

1. Enabled [CI Insights](#enabling-ci-insights-for-jenkins) for your repository

2. Created an application key with `ci` scope and set it as `MERGIFY_TOKEN` in Jenkins credentials.

3. Configured test integration (e.g., `pytest-mergify` or `mergify cli upload`)
   for your test framework

### Jenkins job Setup

The recommended approach is to use a scheduled job that runs your test
suite multiple times on the default branch. Here's an example configuration
that runs tests twice daily with 5 parallel executions:

- Example with native integration (e.g. `pytest-mergify`)

```groovy
pipeline {
  agent any
  environment {
      MERGIFY_TOKEN = credentials('MERGIFY_TOKEN')
      RUN_COUNT = '5'
  }
  triggers {
    cron('0 H/12 * * 1-5')  // Every 12 hours, Monday to Friday
  }

  stages {
    stage('Test') {
      steps {
        sh '''
          # Run your test suite multiple times to detect flakiness
          set +e
          failed=0
          for i in $(seq "$RUN_COUNT"); do
            pytest tests/
            exit_code=$?
            if [ $exit_code -ne 0 ]; then
              failed=1
            fi
          done
          exit $failed
        '''
      }
    }
  }
}
```

- Examples with `mergify cli upload` integration

```groovy
pipeline {
  agent any
  environment {
      MERGIFY_TOKEN = credentials('MERGIFY_TOKEN')
      RUN_COUNT = '5'
  }
  triggers {
    cron('0 H/12 * * 1-5')  // Every 12 hours, Monday to Friday
  }

  stages {
    stage('Test') {
      steps {
        sh '''
          # Run your test suite multiple times to detect flakiness
          set +e
          for i in $(seq "$RUN_COUNT"); do
            pytest tests/
            # Run your test command with unique output file, e.g.:
            # npm test -- --reporters=default --reporters=jest-junit --outputFile=test-results-$i.xml
          done
          set -e
          mergify ci junit-process test-results-*.xml
        '''
      }
    }
  }
}
```

### Configuration Tips

- **Frequency**: Running twice daily (every 12 hours) provides a good balance
  between detection accuracy and resource usage

- **Default Branch Only**: Focus on the default branch where flaky tests have
  the most impact

- **Weekday Schedule**: The example runs Monday to Friday (`1-5`) to avoid
  running when no changes are made on the code

- **Job name**: Ensure the job name is the same as the one running tests on your pull request,
  allowing CI-Insights to identify them. It can be overriden with `MERGIFY_JOB_NAME` if needed.

### Key Environment Variables

- `MERGIFY_TOKEN`: Application key with `ci` scope for uploading test results to CI Insights
- `RUN_COUNT`: Number of times to execute each test within a single job
- `MERGIFY_JOB_NAME`: The job name reported to CI Insights