Jenkins Local

The Jenkins Local plugin is a fully self-contained solution. It stores all CI data in your own PostgreSQL database and surfaces analytics directly inside the Jenkins UI — no external services, no internet required. Think of Jenkins local plugin as a 'super plugin'. It is a plugin with a host of capabilities like slack, email, test case management integrations, jira, etc.

How it works

┌────────────────────────────────────────────────────────┐
│                    Your Infrastructure                 │
│                                                        │
│  ┌─────────────┐    ingest    ┌────────────────────┐   │
│  │   Jenkins   │─────────────▶│   PostgreSQL DB    │   │
│  │  (+ plugin) │              │   (your own)       │   │
│  └─────────────┘              └────────────────────┘   │
│         │                              │               │
│         └──────── reads ───────────────┘               │
│         │                                              │
│  ┌──────▼──────────────────────────────┐              │
│  │  BuildButler dashboard (Jenkins UI) │              │
└──┴─────────────────────────────────────┴──────────────┘

Data never leaves your infrastructure. The plugin writes directly to Postgres and reads from it to render the BuildButler dashboard panels inside Jenkins.

Prerequisites

• Jenkins 2.387.3 or later
• A PostgreSQL 14+ database accessible from Jenkins
• Java 11+

Installation

Step 1 — Install the plugin

1. Download the buildbutler-local.hpi plugin from the Downloads page.
2. In Jenkins, go to Manage Jenkins → Plugins → Advanced.
3. Under Deploy Plugin, upload the .hpi file and click Deploy.
4. Restart Jenkins when prompted.

Step 2 — Activate your license

1. Go to Manage Jenkins → Build Butler Local
2. Under License, paste your license key from your welcome email into the License Key field (format: BB-XXXX-XXXX-XXXX-XXXX)
3. Click Activate / Check License
4. Tick Enabled and save

Configuration

After installation, go to Manage Jenkins → BuildButler Local to configure the plugin.

Build Data Collection

Control which jobs are monitored and how build logs are collected.

Database Connection

Enter your PostgreSQL connection details. Click Test Connection to verify, then Initialize Schema to create the required tables on first setup.

Log Storage (S3-Compatible)

Optionally configure an S3-compatible object store (AWS S3, MinIO, etc.) to store raw build console logs.

Slack Notifications

Configure a default Slack webhook and per-event overrides. Toggle which build events trigger notifications and how many console log lines to include.

Queue Alerts

Define rules that fire when the build queue exceeds a threshold for a sustained duration. Rules are expressed as a JSON array and support total-queue and per-label modes.

Email Notifications (SMTP)

Configure your SMTP server to send email alerts on build events.

Flaky Test Detection

Configure how BuildButler identifies flaky tests — set the number of status transitions, the evaluation window, and the reliability threshold below which a test is flagged.

JIRA Integration

Connect BuildButler to your Jira instance to link build failures to tickets directly from the dashboard.

TestRail Integration

Push Jenkins test results to TestRail automatically after every build. Credentials and job mappings are configured globally here; per-job overrides are not required.

• TestRail Base URL — e.g. https://yourcompany.testrail.io
• Email — your TestRail account email
• API Key — generate from TestRail under My Settings → API Keys

Click Test Connection to verify credentials before saving.

Job mappings are configured in the TestRail tab of the BuildButler dashboard. See Test Case Management → TestRail for the full configuration reference.

ALM Integration

Push Jenkins test results to HP ALM / Micro Focus ALM automatically after every build. Global credentials are configured here; per-job post-build steps are configured inside each Jenkins job.

• ALM Base URL — e.g. https://alm.yourcompany.com/qcbin
• Username — your ALM login username
• Password — your ALM login password
• ALM Field Mappings XML — Bumblebee-compatible XML for mapping custom ALM field names to human-readable labels (see below)

Click Test ALM Connection to verify credentials before saving.

ALM Field Mappings XML

This field accepts the same field-mappings XML format used by Bumblebee. Paste your existing Bumblebee XML directly, or write one from scratch. It controls how the Custom Properties values in the post-build step (and customProperties in the JSON config) are translated to internal ALM field names.

<mappings>
  <url url="https://alm.example.com:8080/qcbin">
    <domain name="DEFAULT">
      <project name="test_project">
        <!-- Test entity field -->
        <mapping alm_field="TS_USER_01" default_value="value" label="test user 1"/>
        <!-- TestSet entity field -->
        <mapping alm_field="CY_USER_01" default_value="" label="test set user 1"/>
        <!-- Run entity field -->
        <mapping alm_field="RN_USER_01" label="run user 1"/>
      </project>
    </domain>
  </url>
</mappings>

Job mappings and per-job post-build steps are configured outside global settings. See Test Case Management → ALM for the full configuration reference.

AI Provider

Configure an AI provider (Anthropic, OpenAI, or Google) to enable the Ask AI feature for natural language queries about your build data.

Build Configuration

Some BuildButler features are configured at the individual job level rather than in global settings. These are added as post-build steps inside each Jenkins job.

HP ALM Uploader

Add Build Butler HP ALM Uploader as a post-build step to any Jenkins job that should push results to ALM. This step runs after the build and uploads test results directly to ALM using the credentials configured in Manage Jenkins → BuildButler Local → ALM Integration.

HP ALM Auto Defect Management

Defect management is configured as part of the HP ALM Uploader post-build step. Defects are created, reopened, or closed automatically based on test results.

App Configuration

Some configuration is done inside the BuildButler app view rather than in Jenkins global settings. This is intentional — it allows non-admin users to manage their own rules without needing access to Manage Jenkins.

Email Rules

Email notification rules (which jobs send alerts, to whom, and on what events) are created in the Email tab of the BuildButler dashboard. Any user can create rules for their own projects.

See Email Notifications for the full configuration reference.

TestRail Job Mappings

TestRail job mappings (which Jenkins jobs sync to which TestRail projects and test runs) are configured in the TestRail tab of the BuildButler dashboard.

See Test Case Management → TestRail for the full configuration reference.

ALM Job Mappings

For the Standalone ALM mode (pattern-based routing without per-job post-build steps), job mappings are configured in the ALM tab of the BuildButler dashboard.

See Test Case Management → ALM for the full configuration reference.

Data ingested

The plugin hooks into the Jenkins build lifecycle and collects:

Multiple Jenkins controllers

If you run multiple Jenkins controllers, each can be configured to write to the same PostgreSQL database. Install the plugin on each controller and configure it with a unique Server Label — each controller gets its own label so data can be filtered by source in the dashboard.

Network requirements

The plugin is fully self-contained — it writes build data directly to your own PostgreSQL database and handles everything locally. There is no dependency on api.buildbutler.dev or any BuildButler-hosted infrastructure.

Outbound connections are only made to the following destinations, depending on which features are enabled:

Compatibility matrix

Troubleshooting

Enable debug logging

To see detailed plugin logs in Jenkins:

1. Go to Manage Jenkins → System Log → Add new log recorder
2. Set Name to io.jenkins.plugins.buildbutler
3. Under Loggers, click Add and set:
   • Logger: io.jenkins.plugins.buildbutler
   • Log level: ALL
4. Click Save

Logs will appear live in the log recorder view. This captures all plugin activity including database connections, build reporting, and any errors.