Reviewer Configuration

You can configure the reviewer with env vars or a repo-local file at .intelligencex/reviewer.json . The JSON file is the cleanest way to keep settings versioned with your repo.

Schema: ../../Schemas/reviewer.schema.json

The reviewer validates .intelligencex/reviewer.json against the schema at runtime. Unknown properties emit warnings; invalid types or enum values fail the run.

Source precedence (important)

Settings are applied in this order:

1. Reviewer defaults
2. .intelligencex/reviewer.json (or REVIEW_CONFIG_PATH )
3. Environment / workflow inputs ( INPUT_* , REVIEW_* )

Because workflow inputs are mapped to environment variables, they override JSON.

If you want a full YAML-vs-JSON split guide, see Workflow vs JSON .

Multiple ChatGPT accounts (rotation + failover)

If your auth store contains more than one ChatGPT login, you can pin a primary account and optionally rotate/fail over to additional accounts. List available account ids with:

intelligencex auth list

{
  "review": {
    "openaiAccountId": "acc-primary",
    "openaiAccountIds": ["acc-primary", "acc-backup", "acc-team"],
    "openaiAccountRotation": "round-robin",
    "openaiAccountFailover": true
  }
}

openaiAccountRotation supports:

• first-available : preserve configured order
• round-robin : rotate by workflow run seed ( GITHUB_RUN_NUMBER , then GITHUB_RUN_ID , then GITHUB_RUN_ATTEMPT )
• sticky : prefer openaiAccountId first, then preserve remaining order

GitHub Actions input/env aliases:

• openai_account_id / REVIEW_OPENAI_ACCOUNT_ID / INTELLIGENCEX_OPENAI_ACCOUNT_ID
• openai_account_ids / REVIEW_OPENAI_ACCOUNT_IDS / INTELLIGENCEX_OPENAI_ACCOUNT_IDS
• openai_account_rotation / REVIEW_OPENAI_ACCOUNT_ROTATION
• openai_account_failover / REVIEW_OPENAI_ACCOUNT_FAILOVER

Minimal example

{
  "review": {
    "provider": "openai",
    "model": "gpt-5.3-codex",
    "mode": "inline",
    "length": "long",
    "outputStyle": "compact",
    "reviewUsageSummary": false
  }
}

OpenAI-compatible provider (Ollama/OpenRouter/etc.)

Use provider: openai-compatible when you want to talk to an OpenAI-style HTTP endpoint (for example Ollama or OpenRouter). This provider uses POST /v1/chat/completions and requires:

• review.model
• review.openaiCompatible.baseUrl
• an API key (via review.openaiCompatible.apiKeyEnv , OPENAI_COMPATIBLE_API_KEY , or review.openaiCompatible.apiKey )

Security note: baseUrl must use https:// for non-loopback hosts by default. Plain http:// is allowed only for loopback (for example http://localhost:11434 ). To allow non-loopback http:// , set review.openaiCompatible.allowInsecureHttp: true and review.openaiCompatible.allowInsecureHttpNonLoopback: true (dangerous).

Compatibility note: by default, Authorization is kept on same-host redirects. To force-drop it when a redirect changes scheme/host/port, set review.openaiCompatible.dropAuthorizationOnRedirect: true (or OPENAI_COMPATIBLE_DROP_AUTHORIZATION_ON_REDIRECT=1 ).

{
  "review": {
    "provider": "openai-compatible",
    "model": "gpt-4o-mini",
    "openaiCompatible": {
      "baseUrl": "http://localhost:11434",
      "apiKeyEnv": "OPENAI_COMPATIBLE_API_KEY",
      "allowInsecureHttp": false,
      "dropAuthorizationOnRedirect": false,
      "timeoutSeconds": 60
    }
  }
}

Strict (security-first) example

{
  "review": {
    "mode": "inline",
    "length": "long",
    "strictness": "high",
    "focus": ["security", "correctness"],
    "reviewDiffRange": "current",
    "includeReviewThreads": true,
    "reviewThreadsIncludeBots": false,
    "maxInlineComments": 20,
    "reviewUsageSummary": true
  }
}

Merge-blocker loop policy (section contract)

Use this when your repo wants different merge-blocker sections than the default Todo List + Critical Issues contract, or when you want to relax the section-presence gate used by no-blockers thread sweep.

{
  "review": {
    "outputStyle": "compact",
    "mergeBlockerSections": ["Todo List"],
    "mergeBlockerRequireAllSections": true,
    "mergeBlockerRequireSectionMatch": true
  }
}

• mergeBlockerSections : headings treated as merge-blocking sections (case-insensitive contains match).
• mergeBlockerRequireAllSections : true (default) requires every configured section to be present; false allows any matching configured section.
• mergeBlockerRequireSectionMatch : true (default) treats no-match output as blocked; false allows no-match output to be non-blocking.

Setup shortcuts:

• Vision-aligned baseline: intelligencex setup --with-config --review-loop-policy vision
• Vision file override: intelligencex setup --with-config --review-loop-policy vision --review-vision-path VISION.md
• Custom strictness + contract: intelligencex setup --with-config --review-intent maintainability --review-strictness strict --merge-blocker-sections "Todo List,Critical Issues" --merge-blocker-require-all-sections false

Fast (cost-aware) example

{
  "review": {
    "mode": "summary",
    "length": "short",
    "maxFiles": 30,
    "maxPatchChars": 4000,
    "progressUpdates": false,
    "reviewUsageSummary": true
  }
}

Note: set maxFiles to 0 to disable file count limits; the reviewer will still trim individual patches using maxPatchChars .

Provider fallback example

Use providerFallback to opt into a secondary provider when the primary provider fails.

{
  "review": {
    "provider": "openai",
    "providerFallback": "copilot"
  }
}

Provider health checks + circuit breaker

Use this to preflight providers before request execution and temporarily open a breaker after repeated failures.

{
  "review": {
    "providerHealthChecks": true,
    "providerHealthCheckTimeoutSeconds": 10,
    "providerCircuitBreakerFailures": 3,
    "providerCircuitBreakerOpenSeconds": 120
  }
}

Auto-resolve + triage example

{
  "review": {
    "mode": "inline",
    "length": "long",
    "reviewDiffRange": "current",
    "includeReviewThreads": true,
    "reviewThreadsAutoResolveAI": true,
    "reviewThreadsAutoResolveRequireEvidence": true,
    "reviewThreadsAutoResolveAIPostComment": true,
    "reviewThreadsAutoResolveSummaryComment": true,
    "reviewThreadsAutoResolveAIEmbedPlacement": "bottom",
    "reviewThreadsAutoResolveAISummary": true,    "reviewThreadsAutoResolveSummaryAlways": true,
    "reviewThreadsAutoResolveBotLogins": [
      "intelligencex-review",
      "copilot-pull-request-reviewer"
    ]
  }
}

Triage-only example

Use this to skip the main review and only assess existing review threads.

{
  "review": {
    "triageOnly": true,
    "reviewThreadsAutoResolveAI": true,
    "reviewThreadsAutoResolveAIPostComment": true
  }
}

Intent preset example

{
  "review": {
    "intent": "security"
  }
}

Azure DevOps example (summary-only)

{
  "review": {
    "codeHost": "azure",
    "azureOrg": "my-org",
    "azureProject": "my-project",
    "azureRepo": "my-repo",
    "azureTokenEnv": "SYSTEM_ACCESSTOKEN",
    "azureAuthScheme": "bearer"
  }
}

Azure DevOps notes

• The reviewer uses the PR-level changes endpoint and follows continuation tokens for large diffs.
• Auth scheme heuristic when azureAuthScheme is not set: SYSTEM_ACCESSTOKEN defaults to bearer ; otherwise a JWT-style token (two or more . ) is treated as bearer ; everything else defaults to basic / pat .
• Set azureAuthScheme explicitly to override the heuristic.

Path filters example

{
  "review": {
    "includePaths": ["src/**", "tests/**"],
    "excludePaths": ["**/*.md", "**/*.snap"],
    "skipPaths": ["**/*.lock"]
  }
}

Language hints

{
  "review": {
    "languageHints": true
  }
}

Usage summary line

{
  "review": {
    "reviewUsageSummary": true,
    "reviewUsageSummaryCacheMinutes": 30
  }
}

When code-review rate-limit windows are present, their labels are prefixed with code review in the usage line so they remain distinct from general limits.

Usage budget guard (credits vs weekly limit)

Use this to fail early when selected usage budget sources are exhausted, and explicitly choose whether credits and/or weekly windows are allowed to keep runs going.

{
  "review": {
    "reviewUsageBudgetGuard": true,
    "reviewUsageBudgetAllowCredits": true,
    "reviewUsageBudgetAllowWeeklyLimit": true
  }
}

GitHub Actions input/env aliases:

• usage_budget_guard / REVIEW_USAGE_BUDGET_GUARD
• usage_budget_allow_credits / REVIEW_USAGE_BUDGET_ALLOW_CREDITS
• usage_budget_allow_weekly_limit / REVIEW_USAGE_BUDGET_ALLOW_WEEKLY_LIMIT

Budget summary note

{
  "review": {
    "reviewBudgetSummary": true
  }
}

When context is truncated, the note explains impact directly in the PR comment:

• only included files/patch snippets were reviewed
• findings may miss issues outside included diff context
• increase review.maxFiles and/or review.maxPatchChars to widen coverage

Structured findings (automation)

{
  "review": {
    "structuredFindings": true
  }
}

Static analysis (preview)

Enable analysis summaries sourced from SARIF or IntelligenceX findings JSON.

{
  "analysis": {
    "enabled": true,
    "packs": ["all-50"],
    "configMode": "respect",
    "disabledRules": ["CA2000"],
    "severityOverrides": { "CA1062": "error" },
    "run": {
      "strict": false
    },
    "gate": {
      "enabled": true,
      "minSeverity": "warning",
      "types": ["vulnerability", "bug"],
      "failOnUnavailable": true,
      "failOnNoEnabledRules": true,
      "includeOutsidePackRules": false,
      "failOnHotspotsToReview": false
    },
    "results": {
      "inputs": ["artifacts/**/*.sarif", "artifacts/intelligencex.findings.json"],
      "minSeverity": "warning",
      "maxInline": 0,
      "summary": true,
      "summaryMaxItems": 10,
      "summaryPlacement": "bottom",
      "showPolicy": true,
      "policyRulePreviewItems": 10
    }
  }
}

analysis.results.policyRulePreviewItems controls how many rule IDs are shown per policy line:

• 0 : hide per-rule lists and keep counts only
• 10 (default): compact preview
• 50 , 100 , 500 : progressively fuller visibility (schema max: 500 )

analysis.results.maxInline defaults to 0 , which keeps static-analysis output in the summary only. Set it to a positive value only if you explicitly want the legacy inline-comment behavior.

analysis.gate enables a deterministic CI gate via intelligencex analyze gate :

• minSeverity : minimum severity to consider for gating.
• types : optional filter of rule types (when empty, all types are considered).
• ruleIds : optional explicit rule IDs (for example IXTOOL001 ) that should be gated even when types would not match.
• failOnUnavailable : fail when no result files match configured inputs or when result parsing fails.
• failOnNoEnabledRules : fail when analysis.packs selects zero rules.
• includeOutsidePackRules : when true , all findings from non-enabled rules can still fail the gate; explicit ruleIds always remain eligible.

Gate output Outside-pack findings included/ignored counts are post-filter scoped (after types / ruleIds gate filters).

• failOnHotspotsToReview : when true , security hotspots in to-review state can fail the gate (after minSeverity / types filtering).

analysis.run.strict controls intelligencex analyze run exit semantics:

• false (default): tool runner failures are reported as warnings and the command exits 0 .
• true : any tool runner failure returns exit 1 .
• --strict or --strict true : force strict behavior for that invocation.
• --strict false : force non-strict behavior for that invocation (even if config has run.strict=true ).
• --pack <id> / --packs <id1,id2> : override analysis.packs for that invocation.
• Setup shortcut: intelligencex setup --with-config --analysis-enabled true --analysis-run-strict true .

Setup analysis option constraints:

• --analysis-* options are supported only for setup when generating config from presets ( --with-config and no --config-json/--config-path override).
• --analysis-gate , --analysis-run-strict , --analysis-packs , and --analysis-export-path require --analysis-enabled true .

Setup review-policy option constraints:

• --review-intent , --review-strictness , --review-loop-policy , --review-vision-path , and --merge-blocker-* options are setup-time config-generation options.
• They are intended for setup with generated config ( --with-config and no --config-json/--config-path override).
• --review-vision-path is only supported with --review-loop-policy vision .

Summary stability (avoid noisy reruns)

{
  "review": {
    "summaryStability": true
  }
}

Redaction (secrets)

When redactPii is enabled, the reviewer applies default redaction patterns for common secrets (private keys, GitHub tokens, AWS access keys, JWTs, Authorization headers, and generic key/value secrets). Override the defaults by setting redactionPatterns .

{
  "review": {
    "redactPii": true,
    "redactionPatterns": [
      "-----BEGIN [A-Z ]*PRIVATE KEY-----[\\s\\S]+?-----END [A-Z ]*PRIVATE KEY-----",
      "\\bgh[pousr]_[A-Za-z0-9]{36}\\b"
    ],
    "redactionReplacement": "[REDACTED]"
  }
}

Untrusted PR guardrails (forks)

When a pull request comes from a fork, the reviewer treats it as untrusted. By default it skips the review to avoid accessing secrets. You can override this behavior explicitly if you are using pull_request_target or have other safeguards in place.

{
  "review": {
    "untrustedPrAllowSecrets": false,
    "untrustedPrAllowWrites": false
  }
}

Set untrustedPrAllowSecrets to true to allow reviews on forked PRs. Set untrustedPrAllowWrites to true to allow posting comments or resolving threads on untrusted PRs (default is false ).

Workflow integrity guardrail

By default the reviewer applies a workflow integrity guardrail:

• Workflow files ( .github/workflows/*.yml|*.yaml ) are excluded from review context.
• If a PR changes only workflow files, the reviewer skips with an explicit summary note.

This prevents self-modifying workflow runs while still reviewing non-workflow changes in mixed PRs. Set allowWorkflowChanges (or REVIEW_ALLOW_WORKFLOW_CHANGES=true ) to review workflow files too.

{
  "review": {
    "allowWorkflowChanges": true
  }
}

Secrets audit logging

When enabled, the reviewer emits a short audit log listing which secret sources were accessed (environment variable names, auth bundle source). Secret values are never logged.

Env: REVIEW_SECRETS_AUDIT

{
  "review": {
    "secretsAudit": true
  }
}

Output style example

{
  "review": {
    "outputStyle": "compact",
    "narrativeMode": "freedom",
    "style": "colorful",
    "tone": "friendly"
  }
}

narrativeMode controls writing style while preserving merge-blocking behavior:

• structured (default): deterministic, concise rationale formatting
• freedom : natural reviewer voice (bullets/paragraphs/tables) while keeping explicit unblock actions

GitHub Actions input/env aliases:

• narrative_mode / REVIEW_NARRATIVE_MODE

Copilot CLI auth env pass-through

Use this to forward selected environment variables into the Copilot CLI process without committing secrets. By default the CLI process does inherit the runner environment. Set inheritEnvironment to false and use envAllowlist / env to pass only what the CLI needs when you want a strict environment.

{
  "review": {
    "provider": "copilot"
  },
  "copilot": {
    "inheritEnvironment": false,
    "envAllowlist": ["GH_TOKEN", "GITHUB_TOKEN"]
  }
}

copilot.env can be used to set fixed, non-secret environment variables for the Copilot CLI.

Copilot direct (experimental)

This path skips the Copilot CLI and posts directly to a compatible HTTP endpoint. It is not enabled by default.

{
  "review": {
    "provider": "copilot"
  },
  "copilot": {
    "transport": "direct",
    "directUrl": "https://example.internal/copilot/chat",
    "directTokenEnv": "COPILOT_DIRECT_TOKEN",
    "directTimeoutSeconds": 60
  }
}

If directTokenEnv is set, the value is pulled from the environment at runtime. directToken or an Authorization header in directHeaders is required for most endpoints. Use directHeaders to attach custom headers required by your gateway. Prefer directTokenEnv over directToken to avoid committing secrets to source control.

Common knobs

• provider : openai / codex / chatgpt / openai-codex , openai-compatible (aliases: openai-api , ollama , openrouter ), or copilot
• providerFallback : optional fallback provider (same value set as provider )
• model : model name for the selected provider
• reasoningEffort : minimal|low|medium|high|xhigh (when set to low/medium/high, the header shows a reasoning level label)
• mode : inline , summary , or hybrid
• length : short|medium|long
• intent : security|performance|perf|maintainability (sets focus areas and default strictness/notes when not set)
• visionPath : optional repository-local vision markdown path used by setup-time vision policy inference
• mergeBlockerSections : custom heading names that represent merge-blocking sections in the review output
• mergeBlockerRequireAllSections : require every configured blocker section to be present before treating review as unblocked
• mergeBlockerRequireSectionMatch : require at least one configured blocker section to appear before treating review as unblocked
• codeHost : github or azure
• reviewDiffRange : current , pr-base , or first-review
• outputStyle : rendering style preset (for the compact template, use compact )
• narrativeMode : structured (default) or freedom
• reviewUsageSummary : append usage line to the footer (ChatGPT auth only)
• openaiAccountId : pin a preferred ChatGPT account id
• openaiAccountIds : ordered account ids used for rotation/failover
• openaiAccountRotation : first-available , round-robin , or sticky
• openaiAccountFailover : allow trying additional accounts when the selected account is blocked/unavailable
• reviewUsageBudgetGuard : fail early when configured usage budget sources are exhausted
• reviewUsageBudgetAllowCredits : allow runs when credits are available
• reviewUsageBudgetAllowWeeklyLimit : allow runs when weekly limit capacity is available
• githubMaxConcurrency : limit concurrent GitHub API requests (default 4)
• languageHints : include language-aware hint block in the prompt
• reviewBudgetSummary : include a note when review context is truncated
• retryCount : total attempts for provider requests
• retryBackoffMultiplier : exponential backoff multiplier (default 2.0)
• retryJitterMinMs / retryJitterMaxMs : retry jitter bounds
• providerHealthChecks : run provider health checks before calls (default true)
• providerHealthCheckTimeoutSeconds : timeout for provider health checks
• providerCircuitBreakerFailures : consecutive failures before opening provider circuit (set 0 to disable)
• providerCircuitBreakerOpenSeconds : how long the provider circuit remains open
• failOpen : emit a failure summary instead of failing the workflow
• failOpenTransientOnly : when true, fail-open only on transient errors
• summaryStability : reuse the previous summary (same commit) as prompt context to avoid noisy rewrites
• structuredFindings : emit a structured findings JSON block for automation
• skipPaths : if all changed files in a PR match these globs, skip reviewing the entire PR
• skipBinaryFiles : skip binary assets (images, archives, executables) from review context (default true)
• skipGeneratedFiles : skip generated files (build output, generated sources) from review context (default true)
• generatedFileGlobs : extra glob patterns to treat as generated files (appended to defaults)
• includePaths : only review files matching these globs
• excludePaths : ignore files matching these globs
• allowWorkflowChanges : include .github/workflows/* changes in review context (default excludes them)
• secretsAudit : emit an audit log of secret sources used (default true)
• includeReviewThreads : include existing review threads in context
• triageOnly : run thread triage only (skip full review)
• reviewThreadsAutoResolve* : auto-resolve rules for bot threads
• reviewThreadsAutoResolveAIReply : reply on kept threads to explain why they were not resolved (includes resolve failures)
• reviewThreadsAutoResolveRequireEvidence : require a diff evidence snippet to resolve threads
• reviewThreadsAutoResolveSummaryAlways : always append a triage summary line to the main review comment
• reviewThreadsAutoResolveSummaryComment : post a standalone summary comment for auto-resolve decisions
• reviewThreadsAutoResolveAIEmbedPlacement : top or bottom placement for embedded triage blocks
• azureOrg / azureProject / azureRepo : Azure DevOps identifiers
• azureBaseUrl : override Azure DevOps base URL (defaults to SYSTEM_COLLECTIONURI or https://dev.azure.com/{org} )
• azureTokenEnv : env var name that contains the ADO token (default SYSTEM_ACCESSTOKEN if set)
• azureAuthScheme : bearer (System.AccessToken/JWT) or basic / pat
• copilot.transport : cli or direct (aliases: api , http )
• copilot.inheritEnvironment : inherit full runner environment for Copilot CLI ( true by default)

Path filter order of operations

1. skipPaths is evaluated first at the PR level. If every changed file matches skipPaths , the PR is skipped.
2. If the PR is not skipped, skipBinaryFiles / skipGeneratedFiles (when enabled) remove binary and generated files from the review list.

generatedFileGlobs extends the default generated-file patterns.

3. includePaths (if set) selects which changed files are eligible for review.
4. Finally, excludePaths (if set) removes any remaining files from review.

Auto-resolve notes

• reviewThreadsAutoResolveBotLogins defaults to intelligencex-review and copilot-pull-request-reviewer . When set,

it acts as an allowlist for auto-resolve; set an empty list to fall back to generic bot detection.

• reviewThreadsAutoResolveDiffRange supports current , pr-base , or first-review .
• Thread assessment ids are trimmed, expected to be unique, and keyed case-insensitively; missing ids are skipped and duplicate ids keep the last occurrence (with warnings).

Choosing a diff range (review vs last commit)

The reviewer does not default to "last commit only". By default, reviewDiffRange: current uses the current PR file list from GitHub (cumulative changes for the PR at HEAD).

When you want the bot to always have an explicit base SHA range in its prompt (useful for debugging and determinism), set reviewDiffRange: pr-base so the prompt includes a PR base → head (abc1234..def5678) range label.

There is no dedicated "last commit only" diff range at the moment. If you want an incremental review, prefer keeping the review comment sticky and rely on summaryStability: true so the summary stays consistent unless new evidence changes it.

Tip: if you enable reviewThreadsIncludeBots: true , the model can see its own prior guidance in thread context, which can reduce repeated suggestions. Tradeoff: it can also "echo" incorrect prior bot advice, so consider leaving this off in repos where you expect frequent bot mistakes or highly sensitive review requirements.

Review thread states (active/resolved/stale)

GitHub can mark a review thread as:

• active: still anchored to the current diff
• stale: shown as "Outdated" in the GitHub UI (the diff hunk changed), but the thread may still be unresolved
• resolved: explicitly resolved (hidden/collapsed by default)

Important: Outdated does not mean resolved . Outdated only means the diff context changed. If you want to reduce PR noise from bot-only outdated threads, enable reviewThreadsAutoResolveStale to auto-resolve stale threads that contain only bot comments.

Auto-resolve troubleshooting

If you see Resource not accessible by integration when resolving threads:

• Re-authorize or reinstall the GitHub App after permission changes.
• Confirm the app installation includes this repository.
• Ensure the app has Pull requests: Read & write (and Issues: write if needed).
• Verify INTELLIGENCEX_GITHUB_APP_ID / INTELLIGENCEX_GITHUB_APP_PRIVATE_KEY point to the intended app.
• To bypass the app token, remove the app secrets so GITHUB_TOKEN is used instead.
• GITHUB_TOKEN is available in GitHub Actions; outside Actions you need a PAT and set it as GITHUB_TOKEN .

Full example

See ../../Schemas/reviewer.schema.json for all available options.