# 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
opensre integrations setup jenkins
```

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

Or use environment variables:

```bash
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
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
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. |