Configuration and Environment Reference

Note: Settings-backed variables support a local .env file. Variables marked process env are read directly with os.getenv() and must already be in the real environment when the server or CLI process starts. docker-compose.yaml in this repository injects .env into the container, so both kinds work there.

Server Environment Variables

Analysis Runtime

Default AI selection and timeout settings for analysis requests.

AI_PROVIDER=claude
AI_MODEL=claude-opus-4-1
AI_CLI_TIMEOUT=15

Effect: POST /analyze and POST /analyze-failures use these values when the request body omits them. Missing or invalid AI_PROVIDER/AI_MODEL returns 400.

Jenkins Connection and Artifact Collection

Default Jenkins access, wait behavior, and artifact download limits for Jenkins-backed analysis.

JENKINS_URL=https://jenkins.example.com
JENKINS_USER=svc-jji
JENKINS_PASSWORD=your-api-token
JENKINS_SSL_VERIFY=true
WAIT_FOR_COMPLETION=true
POLL_INTERVAL_MINUTES=2
MAX_WAIT_MINUTES=30
GET_JOB_ARTIFACTS=true
JENKINS_ARTIFACTS_MAX_SIZE_MB=500

Effect: These defaults apply only to POST /analyze. If WAIT_FOR_COMPLETION=true but no Jenkins URL is available after request merge, the server skips the waiting phase. Artifact processing runs only when GET_JOB_ARTIFACTS=true and the Jenkins build exposes artifacts.

Repository Context and Peer Analysis

Default repository cloning and multi-model review settings.

TESTS_REPO_URL=https://github.com/acme/tests:release-1.2
ADDITIONAL_REPOS=infra:https://github.com/acme/infra:main,product:https://github.com/acme/product
PEER_AI_CONFIGS=cursor:gpt-5.4-xhigh,gemini:gemini-2.5-pro
PEER_ANALYSIS_MAX_ROUNDS=3

Effect: TESTS_REPO_URL is cloned into the analysis workspace. ADDITIONAL_REPOS entries are cloned into named subdirectories. Malformed repo or peer strings fail when the request resolves them.

Jira Analysis and Issue Toggles

Default Jira connection settings for analysis-time enrichment and Jira issue operations.

JIRA_URL=https://acme.atlassian.net
JIRA_EMAIL=triage@example.com
JIRA_API_TOKEN=your-jira-token
JIRA_PROJECT_KEY=PROJ
JIRA_SSL_VERIFY=true
JIRA_MAX_RESULTS=5
ENABLE_JIRA=true
ENABLE_JIRA_ISSUES=true

Effect: Analysis-time Jira enrichment runs only when ENABLE_JIRA is not false and Jira URL, credentials, and project key are all present. Jira issue preview/create is controlled independently by ENABLE_JIRA_ISSUES. Auth resolution is:

• with JIRA_EMAIL: Cloud mode, token preference JIRA_API_TOKEN then JIRA_PAT
• without JIRA_EMAIL: Server/DC mode, token preference JIRA_PAT then JIRA_API_TOKEN

GitHub Issue Creation

Default GitHub credential and feature toggle settings.

GITHUB_TOKEN=ghp_your_token
ENABLE_GITHUB_ISSUES=true

Effect: ENABLE_GITHUB_ISSUES=false blocks GitHub issue preview/create. When the toggle is not false, /api/capabilities reports server token presence separately through server_github_token.

Report Portal and Public URLs

Default Report Portal connection settings and absolute-link base URL.

REPORTPORTAL_URL=https://rp.example.com
REPORTPORTAL_API_TOKEN=rp-token
REPORTPORTAL_PROJECT=e2e
REPORTPORTAL_VERIFY_SSL=true
ENABLE_REPORTPORTAL=true
PUBLIC_BASE_URL=https://jji.example.com

Effect: Report Portal is enabled only when ENABLE_REPORTPORTAL is not false and URL, token, and project are all set. PUBLIC_BASE_URL controls absolute result_url values and is required for POST /results/{job_id}/push-reportportal. When PUBLIC_BASE_URL is unset, the server returns relative URLs.

Note: Request headers do not change PUBLIC_BASE_URL. When unset, base_url is "" and result_url is relative.

Authentication and Secret Handling

Bootstrap admin authentication, cookie security, and at-rest encryption.

ADMIN_KEY=change-this-admin-secret
SECURE_COOKIES=true
JJI_ENCRYPTION_KEY=change-this-encryption-secret
XDG_DATA_HOME=/var/lib/jji

Effect: Request auth order is jji_session cookie, then Bearer token, then jji_username cookie. Admin login sets:

• jji_session: HttpOnly, SameSite=Strict, max-age=8h
• jji_username: SameSite=Lax, max-age=1 year

If JJI_ENCRYPTION_KEY is unset, the server creates and reuses $XDG_DATA_HOME/jji/.encryption_key or ~/.local/share/jji/.encryption_key with mode 0600.

Warning: Changing JJI_ENCRYPTION_KEY invalidates stored API key hashes and can leave previously stored encrypted request values undecryptable.

Storage and Process Runtime

Database location, bind port, reload mode, and log level.

DB_PATH=/var/lib/jji/results.db
PORT=8000
DEBUG=false
LOG_LEVEL=INFO

Effect: PORT is used both for server binding and for the app's internal self-references. Invalid PORT values stop startup.

Provider CLI Passthrough and Container Dev Mode

Provider-specific auth variables and container-only dev-mode switches.

ANTHROPIC_API_KEY=your-anthropic-key
# or Claude via Vertex:
CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=us-east5
ANTHROPIC_VERTEX_PROJECT_ID=my-gcp-project

GEMINI_API_KEY=your-gemini-key
CURSOR_API_KEY=your-cursor-key
DEV_MODE=true

Effect: These variables are not parsed by Settings; they are consumed by installed provider CLIs or by entrypoint.sh. In the container, DEV_MODE=true starts the frontend dev server on port 5173 and appends --reload --reload-dir /app/src to uvicorn.

Docker Compose

docker-compose.yaml Service: jenkins-job-insight

Repository-provided container settings for the combined API and web UI service.

services:
  jenkins-job-insight:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: jenkins-job-insight
    ports:
      - "8000:8000"
    volumes:
      - ./data:/data
    env_file:
      - .env
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

Effect: The service stores its database under the host ./data directory and exposes both the React UI and API on port 8000.

Note: docker-compose.yaml includes commented optional settings for: - 5173:5173 frontend HMR port publishing - ./src:/app/src and ./frontend:/app/frontend source mounts - ~/.config/gcloud:/home/appuser/.config/gcloud:ro for Claude Vertex credentials

CLI Configuration File

File Location and Sections

Named server profiles for the jji CLI.

[default]
server = "prod"

[defaults]
ai_provider = "claude"
ai_model = "claude-opus-4-1"

[servers.prod]
url = "https://jji.example.com"
username = "alice"
no_verify_ssl = false

Effect: [defaults] values are merged first, then [servers.<name>] overrides them. [defaults].server is not supported. servers.<name>.url and [default].server must be non-empty trimmed strings.

Connection Profile Fields

Fields used to connect the CLI to a JJI server.

[servers.prod]
url = "https://jji.example.com"
username = "alice"
no_verify_ssl = false
api_key = "admin-api-key"

Effect: If --server or JJI_SERVER is a full URL, the CLI does not inherit any other values from config.toml.

Analysis Default Fields

Client-side defaults that jji analyze can send when you omit CLI flags.

[defaults]
jenkins_url = "https://jenkins.example.com"
tests_repo_url = "https://github.com/acme/tests"
ai_provider = "claude"
ai_model = "claude-opus-4-1"
wait_for_completion = true
poll_interval_minutes = 2
max_wait_minutes = 30
peers = "cursor:gpt-5.4-xhigh,gemini:gemini-2.5-pro"
peer_analysis_max_rounds = 3
additional_repos = "infra:https://github.com/acme/infra:main"

Effect: The CLI sends populated values to the server only when they are set in the profile and not overridden by CLI flags.

Note: In config.toml, empty strings and 0 values are treated as unset. 0 is the sentinel for ai_cli_timeout, jira_max_results, peer_analysis_max_rounds, poll_interval_minutes, and max_wait_minutes.

Issue Helper Fields

Client-side defaults for issue-related CLI commands.

[servers.prod]
url = "https://jji.example.com"
jira_token = "jira-user-token"
jira_security_level = "Internal"
github_repo_url = "https://github.com/acme/tests"

Effect: These fields are CLI-side defaults only. They do not change the server's own environment configuration.

CLI Environment Variables

Global CLI environment variables.

export JJI_SERVER=prod
export JJI_USERNAME=alice
export JJI_API_KEY=admin-api-key
export JJI_NO_VERIFY_SSL=false

jji health

Effect: JJI_SERVER can be either a profile name or a full URL. Full URLs bypass profile inheritance.

Note: jji analyze also accepts these client-side environment defaults: JENKINS_URL, JENKINS_USER, JENKINS_PASSWORD, TESTS_REPO_URL, JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN, JIRA_PAT, JIRA_PROJECT_KEY, and GITHUB_TOKEN.

Per-Request Override Behavior

Note: For POST /analyze and POST /analyze-failures, omitted JSON fields do not override server defaults. Some request models have JSON defaults, but the server applies those defaults as overrides only when the field is actually present in the request body.

Note: POST /results/{job_id}/preview-github-issue, POST /results/{job_id}/preview-jira-bug, POST /results/{job_id}/create-github-issue, and POST /results/{job_id}/create-jira-bug do not use the analysis override merge described below.

Common Analysis Override Fields

Fields accepted by both POST /analyze and POST /analyze-failures.

{
  "tests_repo_url": "https://github.com/acme/tests:release-1.2",
  "ai_provider": "gemini",
  "ai_model": "gemini-2.5-pro",
  "enable_jira": false,
  "raw_prompt": "Focus on networking regressions first.",
  "peer_ai_configs": [],
  "additional_repos": [
    {
      "name": "infra",
      "url": "https://github.com/acme/infra",
      "ref": "main"
    }
  ]
}

Effect: Omitted fields inherit the server defaults. peer_ai_configs=[] disables peer analysis for that request. additional_repos=[] disables additional repo cloning for that request.

Jenkins-Only Override Fields

Fields accepted only by POST /analyze.

{
  "jenkins_url": "https://jenkins.internal.example.com",
  "jenkins_user": "svc-jji",
  "jenkins_password": "your-api-token",
  "jenkins_ssl_verify": false,
  "get_job_artifacts": true,
  "jenkins_artifacts_max_size_mb": 250,
  "wait_for_completion": true,
  "poll_interval_minutes": 5,
  "max_wait_minutes": 0
}

Effect: wait_for_completion, poll_interval_minutes, and max_wait_minutes override only when the JSON field is present. Sending max_wait_minutes: 0 explicitly sets unlimited waiting for that request.

Direct Failure Input Source

Input-source fields accepted by POST /analyze-failures.

{
  "raw_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><testsuite>...</testsuite>",
  "ai_provider": "claude",
  "ai_model": "claude-opus-4-1"
}

Effect: Exactly one of failures or raw_xml is required. When raw_xml is supplied, the response includes enriched_xml.

Feature Toggle and Capability Reporting

GET /api/capabilities

Returns server-level feature toggles and credential presence.

{
  "github_issues_enabled": true,
  "jira_issues_enabled": true,
  "server_github_token": true,
  "server_jira_token": false,
  "server_jira_email": false,
  "server_jira_project_key": "PROJ",
  "reportportal": true,
  "reportportal_project": "e2e"
}

Effect: This endpoint reports server configuration only. It does not apply per-request analysis overrides. reportportal reflects actual enablement after validating Report Portal URL, token, and project.

Related Pages

• Running Your First Analysis
• CLI Command Reference
• REST API Reference
• Improving Analysis with Repository Context
• Managing Admin Users and API Keys