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

# Jenkins

> Track Jenkins builds and deployments

Connect Jenkins to track your build pipelines, deployment frequency, and DORA metrics. You can connect via API polling or push-based webhooks — if your Jenkins instance is not exposed to the internet, use the webhook option, which only requires Jenkins to make outbound HTTPS calls to Weave.

## Setup

<Steps>
  <Step title="Create a Jenkins API token">
    Click your username in the top-right corner of the Jenkins dashboard, then select **Configure**. Scroll to the **API Token** section and click **Add new Token**. Copy the token immediately — it is only shown once. We recommend using a dedicated read-only service account.
  </Step>

  <Step title="Connect Jenkins in Weave">
    In Weave, go to the **Data** page and click the **Jenkins** tile. You'll see two options:

    * **API polling** — Weave periodically fetches build data from your Jenkins REST API. No Jenkins-side configuration needed. Requires your Jenkins instance to be reachable from the internet (or Weave IPs allowlisted).
    * **Push-based (webhook)** — Jenkins sends build events to Weave in near-real-time. Requires adding a post-build step to your Jenkinsfile. **Does not require Jenkins to be exposed to the internet** — Jenkins only needs outbound HTTPS access to `app.workweave.ai`.

    Choose an option, then enter your Jenkins URL, username, and API token. If you choose push-based, Weave will automatically generate a webhook secret after connecting and show you setup instructions with a ready-to-use Jenkinsfile snippet you can copy.

    You can also add webhooks to an existing instance later by clicking the **bolt icon** next to any connected instance.
  </Step>

  <Step title="Configure jobs">
    Weave will automatically discover and enable all Jenkins jobs on the instance. You'll then review AI-generated predictions for which jobs are production deployments and adjust as needed.
  </Step>

  <Step title="Verify data">
    An initial sync starts immediately after setup and pulls up to 90 days of build history. Subsequent syncs run automatically every few hours. If you chose push-based, new builds will appear in near-real-time once your Jenkinsfile is updated.
  </Step>
</Steps>

You can connect multiple Jenkins instances if your organization uses more than one.

## What's tracked

### Build data

* All completed build executions for configured jobs (in-progress builds sync after completion)
* Build result (success or failure — Jenkins "unstable" is treated as failure, "aborted" as skipped)
* Build duration and timing
* Trigger type (manual, SCM push, scheduled, API, pull request)
* Commit SHAs and branch names (requires the Jenkins Git plugin)

### Deployments

* Production deployment classification via AI and manual configuration
* Deployment frequency and success rate

## DORA metrics enabled

Jenkins integration enables these key DevOps metrics:

* **[Deployment frequency](/metrics/ci-deploy-frequency)** — How often you deploy to production
* **[Deploy success rate](/metrics/ci-deploy-success-rate)** — Percentage of successful deployments
* **[MTTR](/metrics/ci-deploy-mttr)** — Mean time to recovery from failed deployments
* **[Deploy lead time](/metrics/pr-deploy-lead-time)** — Time from code commit to production

## Deployment detection

During setup, Weave uses AI to predict which of your Jenkins jobs are production deployments based on job names. You can review and override these predictions. You can also change the classification at any time from the Jenkins configuration page.

Production deployment jobs are used to calculate DORA metrics like deployment frequency and deploy success rate.

## How it works

### Polling (default)

Weave periodically polls your Jenkins instance via the Jenkins REST API to fetch build data. This means:

* No Jenkins plugin installation is required
* Weave makes outbound HTTPS requests to your Jenkins instance
* Supports Pipeline, Freestyle, and Multibranch Pipeline job types
* Syncs run automatically every few hours and pull the full history of completed builds

### Webhook setup

If you chose **push-based (webhook)** during setup, the webhook secret and setup instructions are shown automatically after connecting. You can also add or regenerate a webhook secret later by clicking the **bolt icon** next to any connected instance on the Jenkins instances page. A green **Webhook** badge indicates instances with an active webhook.

Webhooks complement polling — polling still runs as a backup and handles historical data, while webhooks provide faster updates for new builds.

The webhook endpoint accepts a POST request to:

```
https://app.workweave.ai/api/jenkins/webhook
```

Include the following header:

```
Authorization: Bearer <your-webhook-secret>
```

The request body must be JSON with these fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `job_name` | string | Yes | Full job name (e.g., `my-folder/my-pipeline`) |
| `build_number` | integer | Yes | Jenkins build number |
| `result` | string | Yes | Build result: `SUCCESS`, `FAILURE`, `UNSTABLE`, `ABORTED`, `NOT_BUILT` |
| `duration_ms` | integer | No | Build duration in milliseconds |
| `timestamp_ms` | integer | No | Build start time as Unix epoch milliseconds |
| `commit_sha` | string | No | Git commit SHA |
| `branch` | string | No | Git branch name |
| `build_url` | string | No | Full URL to the Jenkins build |
| `git_url` | string | No | Git remote URL (e.g., `git@github.com:org/repo.git`). When provided, Weave resolves the repository from this URL and does not call back to your Jenkins instance. |
| `build_causes` | string\[] | No | Jenkins build cause class names (e.g., `hudson.model.Cause$UserIdCause`). Used to determine the trigger type. |
| `display_name` | string | No | Build display name |
| `is_multibranch` | boolean | No | Set to `true` for multibranch pipeline jobs. Ensures the external ID includes the branch name to avoid collisions. Automatically detected via `env.BRANCH_NAME != null` in the snippet. |

#### Jenkinsfile example

Add this to the end of your `Jenkinsfile`:

```groovy theme={null}
post {
    always {
        withCredentials([string(credentialsId: 'WEAVE_WEBHOOK_SECRET', variable: 'WEAVE_WEBHOOK_SECRET')]) {
            script {
                def payload = groovy.json.JsonOutput.toJson([
                    job_name: env.JOB_NAME,
                    build_number: env.BUILD_NUMBER as int,
                    result: currentBuild.currentResult,
                    duration_ms: currentBuild.duration,
                    timestamp_ms: currentBuild.startTimeInMillis,
                    commit_sha: env.GIT_COMMIT,
                    branch: env.GIT_BRANCH,
                    build_url: env.BUILD_URL,
                    git_url: env.GIT_URL,
                    build_causes: currentBuild.getBuildCauses().collect { it._class },
                    display_name: env.BUILD_DISPLAY_NAME,
                    is_multibranch: env.BRANCH_NAME != null
                ])
                httpRequest(
                    url: 'https://app.workweave.ai/api/jenkins/webhook',
                    httpMode: 'POST',
                    contentType: 'APPLICATION_JSON',
                    customHeaders: [[name: 'Authorization', value: "Bearer ${WEAVE_WEBHOOK_SECRET}"]],
                    requestBody: payload
                )
            }
        }
    }
}
```

#### Jenkins setup

Before using this snippet, complete these steps in Jenkins:

1. **Install the HTTP Request plugin:** Go to **Manage Jenkins** → **Plugins** → **Available plugins**, search for **HTTP Request**, and install it. This provides the `httpRequest` step used in the snippet above.
2. **Store the webhook secret as a credential:** Go to **Manage Jenkins** → **Credentials** → **System** → **Global credentials** → **Add Credentials**. Select **Secret text** as the kind, paste the webhook secret, and set the ID to `WEAVE_WEBHOOK_SECRET`. Click **Create**.
3. **Add the snippet to your Jenkinsfile:** Paste the `post` block above into your pipeline. The `withCredentials` block binds the stored credential to the `WEAVE_WEBHOOK_SECRET` environment variable.

Jobs must use the **Jenkins Git plugin** so that Weave can extract commit and branch information from builds. Jobs without Git SCM data will be skipped.

<Note>
  Other job types (e.g., Matrix, Multi-configuration) are not currently supported. Jobs nested more than 4 folder levels deep are also not discovered.
</Note>

## Permissions required

The Jenkins user account needs read access to jobs and builds. In most Jenkins setups, granting **Overall: Read** and **Job: Read** is sufficient. If your instance uses project-based authorization, ensure the service account can view all jobs you want to track.

## Data synced

Weave tracks only build metadata:

* Job and build names
* Build status and duration
* Trigger type
* Commit SHAs and branches (from the Git plugin)

**We never access:**

* Build console logs (full text)
* Environment variables or secrets
* Jenkins configuration files
* Application artifacts

## Network requirements

**API polling:** Weave makes outbound HTTPS requests to your Jenkins instance. If Jenkins is behind a firewall, you'll need to allow inbound HTTPS from Weave IPs (see [reference page](/data-sources/reference)).

**Push-based webhooks:** Jenkins makes outbound HTTPS requests to `https://app.workweave.ai`. No inbound firewall rules are needed on your end — your Jenkins instance does not need to be reachable from the internet. Use the Jenkinsfile snippet provided during setup, which includes all required fields.

## Troubleshooting

<AccordionGroup>
  <Accordion icon="plug" title="Connection failing">
    If Jenkins connection fails:

    1. Verify the API token is valid and not expired
    2. If using API polling, check that the Jenkins URL is reachable from the internet (or that Weave IPs are allowlisted). If using webhooks, this is not required.
    3. Ensure the user account has the required permissions
    4. Confirm the username matches the account that generated the token
  </Accordion>

  <Accordion icon="magnifying-glass" title="Builds not appearing">
    If builds aren't showing up:

    1. Check that the job is enabled for tracking in Weave
    2. Ensure builds have completed (in-progress builds sync after completion)
    3. Wait for the next sync cycle (syncs run every few hours)
    4. Verify the Jenkins user can see the job (permissions)
  </Accordion>

  <Accordion icon="webhook" title="Webhooks not working">
    If webhook-triggered builds aren't appearing:

    1. Verify the webhook secret is correct — regenerate it if unsure
    2. Check that the `Authorization` header uses the `Bearer` prefix
    3. Ensure the payload includes the required fields: `job_name`, `build_number`, and `result`
    4. Confirm the job's repository is connected to Weave (webhooks are matched to repos via Git SCM data)
    5. Check that Jenkins can reach `https://app.workweave.ai` (firewall/proxy settings)
  </Accordion>

  <Accordion icon="server" title="Deployments not detected">
    If deployments aren't being tracked:

    1. Check that job names match production patterns
    2. Verify deployment jobs include commit information
    3. Ensure jobs are deploying from tracked branches
    4. Review production job configuration in Weave settings
  </Accordion>
</AccordionGroup>

## Best practices

### Use a dedicated service account

Create a read-only Jenkins service account for Weave rather than using a personal account. This avoids issues when team members leave or change passwords.

### Consistent naming

Use clear, consistent naming for production deployment jobs:

* `deploy-production`, `prod-deploy`, `release-prod`
* Avoid ambiguous names like `deploy-1`, `release`, or `job2`

### Include commit info

Ensure deployment jobs capture and report commit SHAs:

* Links deployments to code changes
* Enables deploy lead time calculation
* Tracks which commits are deployed

### Separate build and deploy

Separate build jobs from deployment jobs:

* Clearer metrics and tracking
* Better failure attribution

## Related documentation

* [Deployment frequency metric](/metrics/ci-deploy-frequency)
* [Deploy success rate metric](/metrics/ci-deploy-success-rate)
* [Deploy MTTR metric](/metrics/ci-deploy-mttr)
* [Deploy lead time metric](/metrics/pr-deploy-lead-time)
* [CI/CD overview](/ci-cd/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.