Jenkins Job Insight uses AI CLI tools to analyze test failures. Choose your preferred provider and configure authentication.
Architecture
The service uses a CLI-based architecture instead of direct SDK integrations:
- No SDK dependencies - AI providers are called via subprocess
- Provider-agnostic - Easy to add new AI CLIs
- Auth handled externally - CLIs manage their own authentication
- Environment-driven -
AI_PROVIDER env var selects the provider
All AI providers use the same analysis workflow. The CLI interface is abstracted, so switching providers requires only changing configuration.
Choosing a Provider
Set the AI_PROVIDER environment variable to select your provider:
AI_PROVIDER=claude
AI_MODEL=claude-opus-4-6[1m]
AI_PROVIDER=gemini
AI_MODEL=gemini-pro
AI_PROVIDER=cursor
AI_MODEL=claude-3.5-sonnet
Claude CLI
The Claude CLI (claude) supports two authentication methods.
Option 1: API Key (Recommended)
Simplest method using direct Anthropic API key.
AI_PROVIDER=claude
AI_MODEL=claude-opus-4-6[1m]
ANTHROPIC_API_KEY=your-anthropic-api-key
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-6[1m] \
-e ANTHROPIC_API_KEY=your-anthropic-api-key \
jenkins-job-insight
Option 2: Vertex AI
Use Google Cloud Vertex AI for Claude access.
AI_PROVIDER=claude
AI_MODEL=claude-opus-4-6[1m]
CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=us-east5
ANTHROPIC_VERTEX_PROJECT_ID=your-project-id
Requires Google Cloud credentials configured in your environment. The Claude CLI reads these environment variables for Vertex authentication.
services:
jenkins-job-insight:
image: jenkins-job-insight
ports:
- "8000:8000"
volumes:
- ./data:/data
environment:
- JENKINS_URL=https://jenkins.example.com
- JENKINS_USER=your-username
- JENKINS_PASSWORD=your-api-token
- AI_PROVIDER=claude
- AI_MODEL=claude-opus-4-6[1m]
- CLAUDE_CODE_USE_VERTEX=1
- CLOUD_ML_REGION=us-east5
- ANTHROPIC_VERTEX_PROJECT_ID=your-project-id
Gemini CLI
The Gemini CLI (gemini) supports API key and OAuth authentication.
Option 1: API Key
AI_PROVIDER=gemini
AI_MODEL=gemini-pro
GEMINI_API_KEY=your-gemini-api-key
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=gemini \
-e AI_MODEL=gemini-pro \
-e GEMINI_API_KEY=your-gemini-api-key \
jenkins-job-insight
Option 2: OAuth
Authenticate using OAuth (requires one-time login).
AI_PROVIDER=gemini
AI_MODEL=gemini-pro
# Run once to authenticate
gemini auth login
No environment variable needed for OAuth. The CLI stores credentials locally after gemini auth login.
# Start container
docker run -d --name jji \
-p 8000:8000 \
-v ./data:/data \
-e AI_PROVIDER=gemini \
-e AI_MODEL=gemini-pro \
jenkins-job-insight
# Authenticate inside container
docker exec -it jji gemini auth login
Cursor Agent CLI
The Cursor Agent CLI (agent) provides AI-powered analysis with workspace awareness.
Option 1: API Key
AI_PROVIDER=cursor
AI_MODEL=claude-3.5-sonnet
CURSOR_API_KEY=your-cursor-api-key
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=cursor \
-e AI_MODEL=claude-3.5-sonnet \
-e CURSOR_API_KEY=your-cursor-api-key \
jenkins-job-insight
Option 2: Web Login (Docker)
For web-based authentication inside a container:
# Start container
docker run -d --name jji \
-p 8000:8000 \
-v ./data:/data \
-e AI_PROVIDER=cursor \
-e AI_MODEL=claude-3.5-sonnet \
jenkins-job-insight
# Authenticate inside container
docker exec jji agent login
Cursor Agent manages its own working directory, so repository context is passed via the --workspace flag.
Timeout Configuration
Adjust the AI CLI timeout for slower models or complex analyses:
AI_CLI_TIMEOUT=15 # minutes (default: 10)
Ensure your timeout is sufficient for your chosen model. Large models analyzing complex failures may require 15+ minutes.
Sanity Check
Before processing analysis requests, Jenkins Job Insight performs a lightweight sanity check to verify the AI CLI is reachable. This catches misconfigured providers early without wasting API credits.
# The service sends "Hi" to the AI CLI
# Expects a successful response within 60 seconds
{
"status": "failed",
"summary": "CLAUDE (claude-opus-4-6[1m]) sanity check failed: Invalid API key"
}
Per-Request Override
Override the AI provider and model for individual requests:
curl -X POST "http://localhost:8000/analyze?sync=true" \
-H "Content-Type: application/json" \
-d '{
"job_name": "my-project",
"build_number": 123,
"ai_provider": "gemini",
"ai_model": "gemini-pro",
"ai_cli_timeout": 15
}'
Request values take precedence over environment variable defaults.
Adding a New Provider
The CLI-based architecture makes it easy to add new AI providers. See the Adding AI Providers guide for instructions on adding custom providers.
Steps:
- Add command builder function in
analyzer.py
- Register provider in
PROVIDER_CONFIG
- Install CLI in Dockerfile
- Update environment variables documentation
Troubleshooting
Authentication Failures
Claude:
CLAUDE (claude-opus-4-6[1m]) CLI error: Invalid API key
ANTHROPIC_API_KEY is set correctly or Vertex AI credentials are configured.
Gemini:
GEMINI (gemini-pro) CLI error: Unauthorized
GEMINI_API_KEY or run gemini auth login for OAuth.
Cursor:
CURSOR (claude-3.5-sonnet) CLI error: Authentication required
CURSOR_API_KEY or run agent login inside the container.
Timeout Issues
CLAUDE (claude-opus-4-6[1m]) CLI error: Analysis timed out after 10 minutes
AI_CLI_TIMEOUT:
AI_CLI_TIMEOUT=20 # Increase to 20 minutes
Unknown Provider
Unknown AI provider: 'openai'. Valid providers: claude, gemini, cursor