Skip to main content

​
Quick start

Get Jenkins Job Insight running and analyze your first failed build in minutes.

​
Prerequisites

  • Docker installed
  • Jenkins server with API access
  • AI provider API key (Claude, Gemini, or Cursor)

​
Run the service

1

Create data directory

The data directory is required for SQLite persistence. Docker creates mounted directories as root, but the container runs as a non-root user for security.
mkdir -p data
2

Start the container

Run Jenkins Job Insight with your Jenkins and AI provider credentials:
docker run -d \
  -p 8000:8000 \
  -v ./data:/data \
  -e JENKINS_URL=https://jenkins.example.com \
  -e JENKINS_USER=your-username \
  -e JENKINS_PASSWORD=your-api-token \
  -e AI_PROVIDER=claude \
  -e AI_MODEL=claude-opus-4 \
  -e ANTHROPIC_API_KEY=your-anthropic-api-key \
  jenkins-job-insight
Replace jenkins.example.com with your Jenkins server URL, and use your actual API credentials.
3

Verify the service is running

Check the health endpoint:
curl http://localhost:8000/health
You should receive a {"status": "healthy"} response.

​
Analyze your first failure

Now let’s analyze a failed Jenkins build using synchronous mode for immediate results.
1

Submit analysis request

Use the /analyze?sync=true endpoint to analyze a failed build:
curl -X POST "http://localhost:8000/analyze?sync=true" \
  -H "Content-Type: application/json" \
  -d '{
    "job_name": "my-project",
    "build_number": 123,
    "ai_provider": "claude",
    "ai_model": "claude-opus-4"
  }'
For jobs inside folders, use the folder path: "job_name": "folder/subfolder/my-project"
2

Review the results

The response includes AI analysis for each failure:
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "summary": "2 failure(s) analyzed",
  "failures": [
    {
      "test_name": "test_user_login",
      "error": "AssertionError: expected 200 but got 401",
      "analysis": {
        "classification": "PRODUCT BUG",
        "details": "The authentication endpoint returns 401...",
        "product_bug_report": {
          "title": "Authentication endpoint rejects valid credentials",
          "severity": "high",
          "component": "auth-service"
        }
      }
    }
  ],
  "html_report_url": "/results/550e8400-e29b-41d4-a716-446655440000.html"
}
3

View the HTML report

Download and open the HTML report in your browser:
curl http://localhost:8000/results/550e8400-e29b-41d4-a716-446655440000.html -o report.html
open report.html  # macOS
# xdg-open report.html  # Linux
The HTML report includes:
  • Sticky header with job name and failure count
  • Root cause analysis cards grouped by bug
  • Collapsible bug details with AI analysis
  • Complete failures table

​
Async mode

For long-running analyses, use async mode to queue the job and retrieve results later: 
# Submit analysis job (returns immediately)
curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "job_name": "my-project",
    "build_number": 123,
    "ai_provider": "claude",
    "ai_model": "claude-opus-4",
    "callback_url": "https://my-service.example.com/webhook"
  }'
Response: 
{
  "status": "queued",
  "message": "Analysis job queued. Poll /results/{job_id} for status.",
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
Retrieve results: 
curl http://localhost:8000/results/550e8400-e29b-41d4-a716-446655440000
Use callback webhooks to receive results automatically when analysis completes, avoiding the need to poll.

​
Analyze raw test failures

You can also analyze test failures directly without Jenkins using the /analyze-failures endpoint: 
curl -X POST http://localhost:8000/analyze-failures \
  -H "Content-Type: application/json" \
  -d '{
    "failures": [
      {
        "test_name": "tests/test_auth.py::test_login",
        "error_message": "AssertionError: expected 200 but got 401",
        "stack_trace": "...",
        "duration": 1.5,
        "status": "FAILED"
      }
    ],
    "ai_provider": "claude",
    "ai_model": "claude-opus-4"
  }'
When raw_xml is provided, the server extracts failures from the XML, runs analysis, and returns enriched_xml with analysis results injected back into the XML.

​
Next steps

Docker setup

Learn about Docker Compose, environment variables, and advanced configuration

API reference

Explore all available endpoints and request options

Jira integration

Set up Jira bug search to avoid duplicate reports

pytest plugin

Enrich JUnit XML reports with AI analysis automatically

Build docs developers (and LLMs) love

Get started for freeTalk to us