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

# Jenkins

# Jenkins Integration

Correlate failed builds and deployments with incidents. OpenSRE reads your
[Jenkins](https://www.jenkins.io) server over its REST API to answer: *"was there
a recent build or deployment that coincides with this alert?"*

## Commands

| Command                               | What it does                                     |
| ------------------------------------- | ------------------------------------------------ |
| `opensre integrations setup jenkins`  | Store your Jenkins URL, username, and API token. |
| `opensre integrations verify jenkins` | Check connectivity to the Jenkins server.        |
| `opensre integrations show jenkins`   | Show the configured Jenkins connection.          |
| `opensre integrations remove jenkins` | Remove the stored Jenkins credentials.           |

## What the agent can do

During an investigation (or in chat), the agent can call these tools:

* **`list_jenkins_builds`** — Recent builds for a job with status (SUCCESS / FAILURE / RUNNING / ABORTED) and timestamp.
* **`get_jenkins_build_log`** — The console log for a specific build, to read the failing step or error.
* **`get_jenkins_pipeline_stages`** — Per-stage status and duration for a Pipeline build (empty for freestyle jobs).
* **`list_jenkins_jobs`** — All jobs with their last-build status.
* **`list_jenkins_running_builds`** — Builds currently in progress across all jobs.

## Setup

### 1. Create a Jenkins API token

In Jenkins: click your **username** (top-right) → **Security** → **API Token** →
**Add new Token** → **Generate**. Copy the token — Jenkins shows it only once.

API access uses HTTP Basic auth with your **username** and this **token** (not your password).

### 2. Configure credentials

Either run the setup wizard:

```bash theme={null}
opensre integrations setup jenkins
```

You'll be prompted for the Jenkins URL, username, and API token.

Or use environment variables:

```bash theme={null}
export JENKINS_URL="http://localhost:8080"
export JENKINS_USER="your-username"        # required — Basic auth is username:token
export JENKINS_API_TOKEN="<your-api-token>"
```

> Folder-organized jobs are supported — pass the full path, e.g. `team/payment-service`.

### 3. Verify connectivity

```bash theme={null}
opensre integrations verify jenkins
```

A successful check reports the server it reached, e.g.
`Jenkins connectivity successful at http://localhost:8080 (node: built-in)`.

## Example investigation

Provide the affected job name so the agent can pull its recent builds and logs:

```bash theme={null}
opensre investigate --input-json '{
  "alert_name": "PaymentServiceErrors",
  "pipeline_name": "payment-service",
  "severity": "critical",
  "commonAnnotations": {
    "summary": "Error rate spiked shortly after a deploy",
    "job_name": "payment-service-deploy"
  }
}'
```

The agent lists recent builds for the job, spots the failed one near the alert
time, fetches its console log, and surfaces the failing step in the RCA.

## API reference

| Purpose            | Endpoint                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| Connectivity check | `GET {JENKINS_URL}/api/json`                                                                      |
| Recent builds      | `GET {JENKINS_URL}/job/<job>/api/json?tree=builds[number,result,timestamp,duration,url,building]` |
| Build console log  | `GET {JENKINS_URL}/job/<job>/<number>/consoleText`                                                |
| Pipeline stages    | `GET {JENKINS_URL}/job/<job>/<number>/wfapi/describe` (Pipeline Stage View)                       |
| Job list           | `GET {JENKINS_URL}/api/json?tree=jobs[name,url,color,lastBuild[...]]`                             |

## Troubleshooting

| Symptom                         | Fix                                                                             |
| ------------------------------- | ------------------------------------------------------------------------------- |
| `Jenkins base URL is required`  | Set `JENKINS_URL` or run `opensre integrations setup jenkins`.                  |
| `Jenkins API token is required` | Generate an API token (User → Security → API Token) and configure it.           |
| `HTTP 401` on verify            | Check the username and regenerate the API token; passwords are not accepted.    |
| `HTTP 403` on verify            | The user lacks Overall/Read permission, or CSRF/crumb settings block the token. |
| No builds returned              | Confirm the job name is correct and has at least one build.                     |