Skip to main content

Configuration Reference

This page is auto-generated and should not be edited by hand. Regenerate it from the TOML source with:

python scripts/generate_config_reference.py

Every configuration option PR-Agent supports, grouped by section. The configuration.toml file is the single source of truth for defaults and inline comments; this page renders the same list for easy searching and linking.

Rows with an empty Description are keys whose TOML entry carries no explanatory comment yet. They are listed deliberately rather than hidden, so the gaps double as the documentation to-do list.

[config]​

See Configuration options.

KeyDefaultDescription
max_webhook_request_body_bytes5242880maximum request body accepted by webhook servers (5 MiB)
bot_display_name"PR-Agent"product name shown in user-visible PR comments; host-only, repo settings and comment args cannot set it
models
KeyDefaultDescription
model"gpt-6.1-sol"
fallback_models["gpt-6-luna"]
CLI
KeyDefaultDescription
git_provider"github"
publish_outputtrue
publish_output_progresstrue
progress_gif_url""optional, override for the progress loading gif url (example: 'https://.../spinner.gif').
progress_gif_width48optional, width (in px) of the progress loading gif.
verbosity_level00,1,2
use_extra_bad_extensionsfalse
Log
KeyDefaultDescription
log_level"INFO"
Configurations
KeyDefaultDescription
use_repo_settings_filetrue
use_global_settings_filetrue
use_group_settings_filefalsehost-only opt-in to GitLab closest-subgroup settings; also requires use_global_settings_file and a nonempty global_settings_repo
global_settings_repo""host-only name of the repository, in the owning org/group/workspace, whose .pr_agent.toml applies to every repository there. Empty disables namespace-wide settings; set "pr-agent-settings" to keep the previous behaviour
enable_per_directory_settingsfalsewhen true, merge per-directory .pr_agent.toml files found by walking up from the PR's changed files (monorepo support). Adds bounded recursive tree discovery per MR; per-directory files may only override non-critical sections (see REPO_PER_DIRECTORY_OVERRIDABLE_SECTIONS). Nearest (deepest) directory wins on shared keys; equal-depth siblings resolve to the lexicographically-last path; when more files match than the per_directory_settings_max_files cap, shallower files are applied first and a partially capped depth keeps its later-path (winning) siblings; any overlap is logged as a warning.
per_directory_settings_max_files20hard ceiling on the number of per-directory .pr_agent.toml files applied per MR (deeper configs beyond the cap are skipped with a warning)
per_directory_settings_max_tree_pages10maximum GitLab recursive-tree pages (100 entries each); skip nested settings if discovery is incomplete. Root/host-controlled, independent of the settings-file cap.
extra_config_url""optional URL or path to an additional .pr_agent.toml merged before the repo-local config; also settable via --extra_config_url or PR_AGENT_EXTRA_CONFIG_URL. See docs/docs/usage-guide/configuration_options.md#external-configuration-url.
disable_auto_feedbackfalse
enable_auto_approvalfalsehost-only. /review approves or withdraws its approval of the reviewed GitHub or GitLab commit; see docs/docs/commands/review.md
ai_timeout1202 minutes
http_request_timeout60host-only connect/read inactivity seconds for GitLab/Gitea and direct Bitbucket/Gerrit HTTP attempts; capped at 600
retry_same_model_on_timeouttruewhen false, a timed-out call is not retried on the same model and moves on to fallback_models
retry_same_model_on_lengthfalsewhen true, an empty response truncated by the output cap is retried on the same model instead of moving straight to fallback_models
num_retries4same-model retries of a request the provider rejects (429, 5xx, connection error) before fallback_models, waiting for its Retry-After (up to 30 s) or with exponential backoff; 0 falls back at once. Timeouts and empty responses use retry_same_model_on_timeout / retry_same_model_on_length instead
skip_keys[]
custom_reasoning_modelfalsewhen true, disables system messages and temperature controls for models that don't support chat-style inputs
system_instructions""Host-only instructions appended to every command's system prompt; repository settings and comment arguments cannot set it.
response_language"en-US"PR response locale (e.g., "en-US", "it-IT"), also used for fixed comment text; applies only during each command. See additional_configurations.md.
repo_context_files["AGENTS.md"]Prompt context files: paths, alternatives, globs, sibling entries; [] disables. See docs.
repo_context_from_default_branchtrueRead repo context files from the repository default branch (trusts only default-branch content). Set to false to read from the PR target branch instead.
repo_context_max_lines500Maximum total rendered lines for repo context, including wrapper tags
repo_context_expand_importsfalseExpand @path imports in local context files; comment arguments cannot set it. See docs.
repo_context_max_glob_matches20Maximum number of files one repo_context_files glob entry (e.g. "docs/adr/*.md") expands to, in name order; each match is one file fetch. A repository's .pr_agent.toml may set it, comment arguments cannot. Clamped to 100. Matches still share the repo_context_max_lines budget.
repo_context_sibling_repos[]Host-only list of approved sibling repository identifiers (GitHub owner/repo, GitLab group/project or numeric ID strings) that repo_context_files sibling entries may select. On GitHub and GitLab, this also approves repositories for cross-repository issue and ticket context. Empty disables sibling reads. Approve only repositories whose content may be disclosed in consuming PRs, because the actor check bounds who triggers a read, not who chose the target or where the output lands. Repository settings and comment arguments cannot change this list. Canonical identities and owning namespaces are checked after resolution
repo_context_sibling_namespaces[]Host-only list of additional org/group/workspace names an approved repo_context_sibling_repos entry (or an expanded gitlab.expand_submodule_diffs gitlink) may resolve into. Empty, the default, keeps the reviewed repository's own namespace as the only approved one. Set it where a project's dependencies live in sibling groups rather than its own, e.g. a submodule in a shared library group. It widens namespaces only: a repository still has to be in repo_context_sibling_repos, and the requester's read access is still checked. Repository settings and comment arguments cannot change this list
repo_context_max_sibling_files5Maximum number of sibling-repository files fetched per repo-context build. The fetch count is bounded separately from repo_context_max_lines so selected sibling files cannot trigger an unbounded number of cross-repository calls; sibling files still compete for the repo_context_max_lines budget. Host-only (cannot be raised by a repository's .pr_agent.toml or a comment command) and clamped to a hard ceiling of 20 fetches per build.
token limits
KeyDefaultDescription
max_description_tokens500
max_commits_tokens500Token cap on the commit messages sent to the model by /describe, /review, /improve and other commands. 0 means no limit; -1 sends none.
max_model_tokens256000Limits the maximum number of tokens that can be used by any model, regardless of the model's default capabilities.
custom_model_max_tokens-1Override unknown models or Sol-tier GPT-6 on non-native custom providers.
max_output_tokens00 = unset (the provider's own default applies)
model_token_count_estimate_factor0.3factor to increase the token count estimate, in order to reduce likelihood of model failure due to too many tokens - applicable only when requesting an accurate estimate.
image_input_token_allowance4096reserve tokens per image when provider counting omits or underestimates image cost
patch extension logic
KeyDefaultDescription
patch_extension_skip_types[".md", ".txt"]
allow_dynamic_contexttrue
max_extra_lines_before_dynamic_context10will try to include up to 10 extra lines before the hunk in the patch, until we reach an enclosing function or class
patch_extra_lines_before5Number of extra lines (+3 default ones) to include before each hunk in the patch
patch_extra_lines_after1Number of extra lines (+3 default ones) to include after each hunk in the patch
secret_provider"""" (disabled), "google_cloud_storage", or "aws_secrets_manager" for secure secret management
cli_modefalse
output_relevant_configurationsfalse
output_run_detailsfalseif true, append an agent run details section (model, tokens, time cost, AI calls) to generated PR comments
output_run_costfalseif true, collect estimated LiteLLM API cost and include it inside the enabled run details section
large_patch_policy"clip""clip" (default) or "skip"; a missing value is treated as "clip"
duplicate_prompt_examplesfalse
persistent_inline_commentsfalseEnable persistent inline comments (issue #2037) to fingerprint each inline comment and embed a provider-compatible marker, then skip re-posting suggestions already present on the PR/MR across runs.
seed
KeyDefaultDescription
seed-1set positive value to fix the seed (and ensure temperature=0)
temperature0.2
ignore logic
KeyDefaultDescription
ignore_pr_title["^\[Auto\]"]a list of regular expressions to match against the PR title to ignore the PR agent
ignore_pr_target_branches[]a list of regular expressions of target branches to ignore from PR agent when an PR is created
ignore_pr_source_branches[]a list of regular expressions of source branches to ignore from PR agent when an PR is created
ignore_pr_labels[]labels to ignore from PR agent when an PR is created
include_pr_labels[]PR label allowlist (exact match; empty disables); see details
ignore_pr_authors[]authors to ignore from PR agent when an PR is created
reaction_on_start"eyes"added before the command runs
reaction_on_success""replaces the start reaction when the command succeeded (GitHub App, GitLab webhook)
reaction_on_failure""replaces the start reaction when the command failed (GitHub App, GitLab webhook)
ignore_repositories[]a list of regular expressions of repository full names (e.g. "org/repo") to ignore from PR agent processing
ignore_language_framework[]a list of code-generation languages or frameworks (e.g. 'protobuf', 'go_gen') whose auto-generated source files will be excluded from analysis
bot_user_indicators["codium", "bot_", "bot-", "_bot", "-bot"]Substring indicators used to skip bot users on webhook events. Currently consumed by the GitLab webhook (is_bot_user); other providers may adopt this list in future. The match is case-insensitive against the sender's display name. Overriding this setting REPLACES the default list — include the entries below in your override if you want to keep them (e.g. ["codium", "bot_", "bot-", "_bot", "-bot", "renovate"]).
restricted_modefalsewhen true, skip operations that require elevated permissions (e.g. pushing code to the repository)
is_auto_commandfalsewill be auto-set to true if the command is triggered by an automation
skip_unchanged_difffalseskip automatic or CLI /review and /describe when the PR is unchanged since their last successful run. See docs/docs/usage-guide/automations_and_usage.md
propagate_command_errorsfalsewhen true, a command re-raises instead of swallowing an internal error, so a caller can tell a failed run from an empty one
enable_ai_metadatafalsewill enable adding ai metadata
add_user_to_requestsfalsesend the current command and PR URL in the OpenAI-compatible "user" request field, for provider-side attribution of requests (e.g. OpenRouter "external_user")
reasoning_effort"medium""none", "minimal", "low", "medium", "high", "xhigh", "max"
additional_reasoning_effort_models[]Optional: additional model IDs that accept config.reasoning_effort. Reasoning support is otherwise decided by litellm's bundled model metadata (and the maintained Grok registry), so add an ID here when litellm does not know the model (custom OpenAI-compatible endpoints), or when another provider hosts a Sol-tier GPT-6 model under the same ID. Model IDs match exactly or through any provider prefix (e.g. "deepseek-v4-flash-0731" matches "openai/deepseek-v4-flash-0731"). LiteLLM whitelists reasoning_effort through allowed_openai_params for OpenAI-compatible models it does not recognize, so the parameter reaches the endpoint. The default "medium" may be rejected by providers that accept a different subset (e.g. "none"/"low"/"high"/"max"); adding a custom model id now surfaces a provider-side error instead of the previous silent drop.
no_temperature_models["deepseek/deepseek-reasoner", "o1-mini", "o1-mini-2024-09-12", "o1", "o1-2024-12-17", "o3-mini", "o3-mini-2025-01-31", "o3", "o3-2025-04-16", "o4-mini", "o4-mini-2025-04-16", "gpt-5.1-codex", "gpt-5.1-codex-mini", "gpt-5.2-codex", "gpt-5.3-codex", "gpt-5-mini", "moonshotai.kimi-k3", "us.moonshotai.kimi-k3", "global.moonshotai.kimi-k3", "kimi-k3", "kimi-k3.1-pro", "zai.glm-5"]Optional: model IDs that must never receive the temperature parameter, on top of what litellm's parameter metadata reports. Temperature support is otherwise decided by litellm.get_supported_openai_params() (mirroring reasoning_effort), so add an ID here when litellm reports temperature as supported but the provider rejects it, or when an OpenAI-compatible endpoint accepts but you still want it dropped. Adaptive-thinking Claude models (Opus 4.7/4.8, Opus/Sonnet/Fable 5.x and Haiku 5.5) never receive temperature. Match model IDs exactly or through any provider prefix. For OpenRouter :nitro and :floor routing shortcuts, also match the suffix-free base ID (for example, match future-model to openrouter/vendor/future-model:nitro). Keep other model variants at their full ID. Preserve the former static registry entries below when litellm's metadata still marks them temperature-capable; see #3611 (Derive temperature support from LiteLLM metadata and retire NO_SUPPORT_TEMPERATURE_MODELS) for the probe diff. Bedrock rejects temperature for Kimi K3 and GLM-5 ("This model doesn't support the temperature field"); Moonshot/Kimi reasoning endpoints reject custom temperature.
extended thinking for Claude reasoning models
KeyDefaultDescription
enable_claude_extended_thinkingfalseSet to true to enable extended thinking feature
extended_thinking_budget_tokens2048Thinking budget used when enable_claude_extended_thinking is true.
extended_thinking_max_output_tokens4096Output cap in extended-thinking mode; it replaces max_output_tokens and must be at least the thinking budget.
enable_claude_adaptive_thinkingfalseAdaptive thinking for Claude Opus 4.7/4.8 and Claude 5 models. When enabled, these models receive thinking={"type": "adaptive"} and an output_config effort. Do not add adaptive-only models to claude_extended_thinking_models_override; when both features are enabled, adaptive thinking takes precedence.
claude_adaptive_thinking_models_override[]Optional model ids to treat as adaptive-only Claude models, including opaque Bedrock ARNs. See changing a model.
claude_extended_thinking_models_override[]Optional: override the built-in list of Claude models that receive the extended-thinking payload. When non-empty, this list fully replaces the built-in defaults (see CLAUDE_EXTENDED_THINKING_MODELS in pr_agent/algo/init.py). Leave empty to use the defaults.
extract_issue_from_branchtrueInfer branch issues on GitHub and same-project GitLab (123-...); false disables. See https://docs.pr-agent.ai/core-abilities/fetching_ticket_context/.
branch_issue_regex""Optional: custom regex with one or more capturing groups for the issue number (validated at runtime); only the first group is used. If the regex has no capturing group, the default pattern is used; if it does not compile, no branch tickets are extracted. If empty, uses default pattern: first 1-6 digits at start of branch or after a slash, followed by hyphen or end (e.g. feature/1-test, 123-fix), skipping date prefixes such as release/2026-11-15. GitHub only; other providers planned for later.
description_issue_regex""Configure a regex replacing bare #N references, with exactly one capturing group for an ASCII issue number. Leave empty for default matching (up to six digits); fall back with a warning on invalid patterns. Set the custom digit limit in the pattern; use only integer-parseable captures. Keep full URLs and owner/repo#N references. Use TOML literal quotes to preserve backslashes, e.g. description_issue_regex = '(?i)(?:fixes|closes|resolves)\s+#(\d+)'

[pr_reviewer] — /review​

See Review.

enable/disable features

KeyDefaultDescription
require_score_reviewfalse
require_tests_reviewtrue
require_estimate_effort_to_reviewtrue
require_can_be_split_reviewfalse
require_security_reviewtrue
require_estimate_contribution_time_costfalse
require_todo_scanfalse
require_ticket_analysis_reviewtrue
require_risk_assessmentfalseask the model for an overall risk level (low/medium/high)
require_merge_recommendationfalseask the model for a merge recommendation: no_concerns_found (no important blockers or risks identified), needs_review (seems acceptable but deserves focused reviewer attention) or changes_required (clear issues to fix before merge)
max_changed_lines100Host-only changed-line cap; a larger diff vetoes no_concerns_found. See docs/docs/commands/review.md
publish_merge_recommendation_statusfalsePublish the computed verdict as a SHA-scoped check/commit status. See docs/docs/commands/review.md
require_failure_modesfalseask for up to three concrete failure scenarios and their detection/coverage
require_artifact_findingsfalsewith a CI artifact, list up to five neutral facts from it, each with a quote checked against the artifact. See docs/docs/commands/review.md
require_priority_filesfalseask the model which files a human should inspect first
structural_reach_input_file""JSON reach facts from a build-graph tool; when the file exists, adds a deterministic change-risk row. See docs/docs/commands/review.md
enable_risk_checkstrueFlag sensitive paths and risky change shapes; adds nothing when clean. See docs/docs/commands/review.md
sensitive_paths[".github/workflows/", ".github/actions/", ".gitlab-ci.yml", "Jenkinsfile*", ".circleci/", "azure-pipelines*.yml", ".travis.yml", "bitbucket-pipelines.yml", "CODEOWNERS", ".pr_agent.toml", "package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "requirements.txt", "Pipfile", "Pipfile.lock", "pyproject.toml", "poetry.lock", "uv.lock", "Cargo.toml", "Cargo.lock", "go.mod", "go.sum", "pom.xml", "build.gradle*", "Gemfile", "Gemfile.lock", "composer.json", "composer.lock", "Dockerfile", "docker-compose*.yml", "docker-compose*.yaml", ".dockerfile", ".tf", ".tfvars", ".hcl", "migrations/", "migration", "db/migrate/", "alembic/"]Glob patterns of sensitive paths flagging deterministic review risk findings. See docs/docs/commands/review.md
extra_risky_shapes[]Custom regex patterns flagging risky changes in diff hunks. See docs/docs/commands/review.md
general options
KeyDefaultDescription
publish_output_no_suggestionstrueSet to "false" if you only need the reviewer's remarks (not labels, not "security audit", etc.) and want to avoid noisy "No major issues detected" comments.
publish_review_failure_commenttrueSet to false to suppress review failure comments without changing the command's failure status.
publish_error_detailsfalsePublish a deterministic, sanitized failure reason in manual review comments. No AI call is used.
persistent_commenttrue
per_commit_reviewfalseReview each PR commit on its own diff and message, one review per commit. See per commit review.
max_commits_per_review0Optional cap on the commits per_commit_review reviews one by one; above it, the whole PR is reviewed in one review. 0 means no limit.
review_heading"PR Reviewer Guide"Visible base heading for full and incremental review comments. Identity is tracked separately.
persistent_finding_statetruePersist review finding state across complete review runs.
max_previous_findings_chars8000Character budget for the findings stored by earlier reviews, given to /review as context so it keeps their wording instead of re-raising them reworded, and skips findings whose GitHub or GitLab inline thread someone other than PR-Agent resolved (needs persistent_finding_state); 0 disables it.
show_previous_findings_summarytrueShow a 'Since the last review' section at the top of the review: addressed, reappeared, still-open and new findings (needs persistent_finding_state).
inline_key_issuestruePublish each review finding as an inline comment where the provider can verify inline-comment publication (GitHub, Bitbucket Cloud, Azure DevOps, GitLab, Gitea). Findings with a fix become committable suggestions when pr_code_suggestions.committable_code_suggestions is on. Set to false to keep every finding in the review summary.
min_finding_confidence0Drop findings below this model-reported confidence (0-10); 0 keeps every finding and does not ask the model for one.
extra_instructions""
num_max_findings6maximum number of key issues /review reports (integer; default 6)
final_update_messagetrue

Azure DevOps also supplies verified PR-Agent inline key issues as dismissed when their status is wontFix or byDesign and differs from azure_devops.default_comment_status. Matching defaults, fixed, closed, active, and pending threads do not count as dismissals. PR-Agent resolves its posting identity through Azure DevOps; azure_devops_server.agent_identity can override it. This infers a human decision from the current configuration; it cannot verify the status-changing actor or historical defaults. Dismissed findings share the existing max_previous_findings_chars budget and may be reported again if the code makes them worse.

review labels

KeyDefaultDescription
enable_review_labels_securitytrue
enable_review_labels_efforttrue
specific configurations for incremental review (/review -i)
KeyDefaultDescription
require_all_thresholds_for_incremental_reviewfalse
minimal_commits_for_incremental_review0
minimal_minutes_for_incremental_review0
enable_intro_texttrue
enable_help_textfalseDetermines whether to include help text in the PR review.
enable_review_coverage_footertrue
enable_large_pr_chunkingfalselarge-diff chunking (opt-in). When the token budget leaves files out of the review, split the diff into chunks, review each chunk, and merge the per-chunk results into one review.
max_number_of_calls3maximum number of chunk review calls, used only when enable_large_pr_chunking is true

[pr_description] — /describe​

See Describe.

KeyDefaultDescription
publish_labelsfalse
add_original_user_descriptiontrue
generate_ai_titlefalse
extra_instructions""
enable_pr_typetrue
enable_pr_descriptiontrueadds a section with an AI-generated summary of the PR changes
final_update_messagetrue
enable_help_textfalse
enable_help_commentfalse
enable_pr_diagramtrueadds a section with a diagram of the PR changes
pr_diagram_direction"adaptive"'adaptive', 'LR', 'TD'. 'adaptive' picks the direction from the shape of the diagram
pr_diagram_direction_threshold5with 'adaptive', a chain longer than this many nodes is drawn top-down
describe as comment
KeyDefaultDescription
publish_description_as_commentfalse
publish_description_as_comment_persistenttrue
changes walkthrough section
KeyDefaultDescription
enable_semantic_files_typestrue
collapsible_file_list"adaptive"true, false, 'adaptive'
collapsible_file_list_threshold6
file_table_collapsible_open_by_defaultfalse
markers
KeyDefaultDescription
use_description_markersfalse
enable_large_pr_handlingtrue
include_generated_by_headertrueAdd a "Generated by <config.bot_display_name>" header (with the head SHA when available). Only read when use_description_markers is true.
max_ai_calls4Not settable from a per-directory .pr_agent.toml. Caps the /describe AI calls for a large PR (one is kept for the summary).
async_ai_callstrueNot settable from a per-directory .pr_agent.toml. Run a large PR's /describe calls concurrently when enable_large_pr_handling is on.

[pr_questions] — /ask​

See Ask.

KeyDefaultDescription
enable_help_textfalse
use_conversation_historytrue
use_ticket_contextfalseInclude linked ticket context in top-level /ask when true; default false. See commands/ask.md#linked-ticket-context.
ask_heading"Ask"Set the plain-text heading for top-level /ask answers; provider-specific presentation is added automatically.
resolve_threadsfalseEnable to let /ask_line resolve the review thread when the LLM judges the issue addressed. Note: also resolves threads started by human reviewers.
extra_instructions""

[pr_code_suggestions] — /improve​

See Fixes and committable suggestions.

KeyDefaultDescription
committable_code_suggestionsfalseDeprecated alias still accepted until 1.0: pr_code_suggestions.commitable_code_suggestions
dual_publishing_score_threshold-1Not settable from a per-directory .pr_agent.toml. -1 or 0 disables, [1-10] also publishes suggestions scoring >= it as committable, besides the table.
focus_only_on_problemstrue
extra_instructions""
suggestions_heading"PR Code Suggestions"Visible base heading for summary-table /improve comments. Identity is tracked separately.
enable_help_textfalse
enable_chat_textfalse
persistent_commenttrue
publish_failure_commenttrueSet to false to suppress /improve failure comments without changing the command's failure status.
max_history_len4Previous sets to retain; <=0 keeps latest only (same comment if editable).
publish_output_no_suggestionstrue
enable_suggestions_coverage_footertrueshow failed chunks and files omitted by the token or AI-call budget
suggestions scoring
KeyDefaultDescription
suggestions_score_threshold1[0-10]| 0 is treated as 1; recommend not to set this value above 8, since above it may clip highly relevant suggestions
score_on_reflection_failure7[0-10]| score assigned when self-reflection fails or its feedback cannot be parsed; set below suggestions_score_threshold to drop unvetted suggestions
new_score_mechanismtrue
new_score_mechanism_th_high9
new_score_mechanism_th_medium7
params for '/improve --extended' mode
KeyDefaultDescription
num_code_suggestions_per_chunk3
max_suggestions_per_file0Maximum suggestions retained per file after all chunks are merged; 0 disables the cap. Skip unresolvable line locations before applying a positive cap to summarized output; leave inline selection unchanged.
max_discussion_context_chars24000Character budget for prior code-suggestion threads given to /improve as context (GitLab, Azure DevOps); 0 disables it.
max_number_of_calls3
parallel_callstrue
decouple_hunksfalse
self-review checkbox
KeyDefaultDescription
demand_code_suggestions_self_reviewfalseadd a checkbox for the author to self-review the code suggestions
code_suggestions_self_review_text"Author self-review: I have reviewed the PR code suggestions, and addressed the relevant ones."

[pr_add_docs] — /add_docs​

See Add Docs.

KeyDefaultDescription
extra_instructions""
docs_style"Sphinx"Docstring style: Google Style with Args, Returns, Attributes...etc; Numpy Style; Sphinx; PEP257; reStructuredText. See docs/docs/commands/add_docs.md.

[pr_update_changelog] — /update_changelog​

See Update Changelog.

KeyDefaultDescription
changelog_path"CHANGELOG.md"Repository-relative Markdown changelog path. Root .pr_agent.toml or host settings only; see commands/update_changelog.md.
push_changelog_changesfalse
extra_instructions""
add_pr_linktrue
skip_ci_on_pushtrue

[pr_config] — /config​

See Show possible configurations.

This section only documents commented-out examples; see the TOML source for details.

[pr_help_docs]​

See Help Docs.

KeyDefaultDescription
repo_url""If not overwritten, will use the repo from where the context came from (issue or PR)
repo_default_branch"main"
docs_path"docs"
exclude_root_readmefalse
supported_doc_exts[".md", ".mdx", ".rst"]
enable_help_textfalse

[github]​

See GitHub.

KeyDefaultDescription
deployment_type"user"The type of deployment to create. Valid values are 'app' or 'user'.
agent_login""Host-only login PR-Agent posts as when its token cannot call GET /user, e.g. <app-slug>[bot] for a GitHub App installation token in GitHub Actions. Empty falls back to github-actions[bot] under Actions. Repository settings and comment arguments cannot change it
ratelimit_retries5Host-only total attempts for retryable GitHub diff collection failures, including rate limits and transient API errors. Integer-valued floats and integer strings are accepted. Zero returns None without collecting a diff. A negative integer attempt limit retries indefinitely. Boolean, non-finite, non-integral float, and unparseable values fall back to 5 with a warning.
seconds_between_requests0seconds between API requests; 0 = no pacing (1.59 behaviour)
seconds_between_writes0seconds between write calls; 0 = no pacing (1.59 behaviour)
api_retries0max retries per request with backoff; 0 = no retries (1.59 behaviour)
polling_request_timeout10total seconds for comment-history fallback; positive values capped at 60
polling_repositories[]Host-only allowlist of GitHub repositories ("owner/repo") whose mention notifications polling may process. Empty disables all polling notifications. Repository settings and comment arguments cannot change this list
base_url"https://api.github.com"
try_fix_invalid_inline_commentstrue
ignore_bot_prtrue
publish_as_check_runfalsewhen true, publish review/description output as GitHub Checks instead of PR comments

[github_action_config]​

See GitHub Actions.

This section only documents commented-out examples; see the TOML source for details.

[github_app]​

See GitHub App.

KeyDefaultDescription
override_deployment_typetruethese toggles allows running the github app from custom deployments
settings for "pull_request" event
KeyDefaultDescription
handle_pr_actions["opened", "reopened", "ready_for_review"]
feedback_on_draft_prfalse
review_states["changes_requested"]A submitted GitHub review can optionally trigger these commands. The empty default preserves current behavior.
review_author_types["User"]
review_commands[]
webhook_delivery_deduplicationfalseOpt in to in-memory deduplication by X-GitHub-Delivery within each worker process. Active work stays protected; completed IDs expire after the deployment's push_trigger_pending_tasks_ttl (read at startup, 300 seconds by default). Failed or cancelled work can retry immediately. Repeated deliveries do not extend the TTL. Manual redeliveries are also suppressed during this window. State is cleared on restart and is not shared across workers or replicas.
handle_push_triggerfalsesettings for "pull_request" event with "synchronize" action - used to detect and handle push triggers for new commits
push_trigger_ignore_bot_commitstrue
push_trigger_ignore_merge_commitstrueskip push_commands when the push only merges the base branch into the previous head, as "Update branch" does
push_trigger_pending_tasks_backlogtrueGitHub App only. Keep one queued push-trigger task per PR instead of dropping it; other servers always queue.
push_trigger_pending_tasks_ttl300GitHub App only. Seconds idle per-PR push-trigger state is kept (other servers: 300); also the dedupe window when webhook_delivery_deduplication is on.
push_commands["/describe", "/review"]

[gitlab]​

See GitLab.

KeyDefaultDescription
url"https://gitlab.com"
expand_submodule_diffsfalseSubmodule targets must also be listed in config.repo_context_sibling_repos.
feedback_on_draft_prfalse
publish_review_as_threadfalsePost the /review summary as a resolvable thread (discussion) instead of a plain note.
publish_improve_as_threadfalseIgnored: /improve runs /review, so there is no suggestions comment. Use publish_review_as_thread.
reply_to_trigger_commentfalseReply in the triggering GitLab discussion for /review, /improve, or /ask (true/false); see docs/docs/usage-guide/additional_configurations.md.
publish_code_suggestions_as_reviewfalseWhen pr_code_suggestions.committable_code_suggestions is true, queue each suggestion as a GitLab draft note and publish them all together in one batch (like GitLab's own "start a review" flow) instead of posting each as its own live discussion - and its own notification - as soon as it's created.
resolve_outdated_inline_threadsfalseResolve the bot's own inline threads that a later push left on an outdated diff version.
auto_resolve_fixed_inline_threadsfalseResolve the bot's own inline threads whose flagged line was modified after the comment was posted - i.e. the diff between the comment's head sha and the current head sha removes/replaces that line. Unlike resolve_outdated_inline_threads this is content-based: threads on lines nobody touched (or merely shifted by unrelated insertions) stay open.
handle_push_triggerfalse
push_commands["/describe", "/review"]
handle_reviewer_assignmentfalseAuto-trigger commands when the bot is assigned or explicitly re-requested as a reviewer on an MR
reviewer_commands["/review"]
ignore_user_ids[]Numeric GitLab user IDs whose merge request and note events are skipped, checked before the config.bot_user_indicators display-name match. IDs are stable, unlike display names. Host-only: the check runs before repository settings are loaded (e.g. GITLAB__IGNORE_USER_IDS=123).

[gitea]​

See Gitea.

KeyDefaultDescription
url"https://gitea.com"
handle_push_triggerfalse
push_commands["/describe", "/review"]

[bitbucket]​

See Bitbucket.

KeyDefaultDescription
identity_request_timeout30positive seconds for authenticated-account verification requests

[bitbucket_app]​

See Bitbucket App.

KeyDefaultDescription
avoid_full_filesfalse
request_timeout30positive seconds for connection and response-read inactivity timeouts
handle_push_triggerfalserun push_commands when new commits are pushed to an open PR
push_commands[]

[local]​

See Local git provider.

This section only documents commented-out examples; see the TOML source for details.

[gerrit]​

See Supported platforms.

KeyDefaultDescription
command_timeout_seconds120Host-only limit for each direct git or SSH child; use a positive finite number of seconds. Coordinate larger values with the deployment worker timeout. No whole-request or process-tree limit; timed-out SSH review writes are not retried because Gerrit may have accepted them.
webhook_username""both are required: the gerrit webhook endpoint rejects every call until they are set
webhook_password""

[bitbucket_server]​

See Bitbucket Server.

KeyDefaultDescription
url""URL to the BitBucket Server instance
handle_push_triggerfalserun push_commands when new commits are pushed to an open PR
push_commands[]

[jira]​

See Ticket context.

KeyDefaultDescription
cloud_id""optional UUID for scoped tokens; uses the Atlassian API gateway and is host-only
jira_requirements_field""Custom field id holding acceptance criteria / requirements, mapped to the ticket "requirements" section. Instance-specific (e.g. "customfield_10127"); empty disables it.
project_keys["*"]Optional allowlist of Jira project keys, e.g. ["PROJ", "OPS"]. When non-empty, key-shaped text with another prefix ("SHA-256", "UTF-8", "ISO-8601") is dropped before any lookup, so it no longer costs an authenticated 404 each. Entries must be plain upper-case keys; a supplied list with no valid entry disables the lookup rather than widening it. Wildcard ["*"] (default) looks up every key found. An empty list ([]) disables Jira ticket lookups. Host-only, like jira_site and jira_api_email: repository settings and comment arguments cannot change them.

[litellm]​

See Changing a model.

KeyDefaultDescription
enable_callbacksfalse
add_session_id_to_requestsfalsesend a stable session id derived from the PR URL as x-litellm-session-id (LiteLLM session grouping) and the provider's session header (e.g. x-opencode-session)
success_callback[]process-wide: only the deployment's configuration and environment set it, not a repo's .pr_agent.toml; in the Action, use a workflow env entry
failure_callback[]process-wide, set like success_callback
service_callback[]process-wide, set like success_callback
turn_off_message_loggingfalseomit prompts/responses from LiteLLM callbacks and PR-Agent's LiteLLM logs; recommended with the "otel" callback
suppress_debug_infotruehide LiteLLM's "Give Feedback / Get Help" stdout banner on provider errors; process-wide, set like success_callback
custom_llm_provider""Optional: forward a fixed custom_llm_provider to LiteLLM, so a raw hosted model id (e.g. "claude-sonnet-4-5") reaches the provider unchanged instead of being rewritten by LiteLLM's prefix inference. Empty = let LiteLLM infer the provider from the model name.
force_streaming_custom_llm_provider""Force streaming when the request matches this provider AND its api_base contains one of the substrings below. Some OpenAI-compatible endpoints return a response that LiteLLM cannot normalize in non-streaming mode. Both must be set for the workaround to apply.
force_streaming_api_base_substrings[]
callback_timeout_seconds30max seconds to wait for pending litellm callbacks to flush before exiting
base_models{}Optional: map an opaque request model id (for example a Bedrock application inference profile ARN) to a LiteLLM-priced model id, so run cost is reported instead of unavailable. Default empty; named models are priced by LiteLLM directly and need no entry here.
cache_control_injection_points[]Optional: enable Anthropic prompt caching via LiteLLM, e.g. [{location = "message", role = "system"}] (https://docs.litellm.ai/docs/tutorials/prompt_caching). PR-Agent forwards these points only for models whose name contains "claude" or that are listed in a Claude thinking override; LiteLLM adds the cache_control blocks. LiteLLM's own default injection (litellm.enable_anthropic_prompt_caching, env LITELLM_ENABLE_ANTHROPIC_PROMPT_CACHING, off by default) applies only when no points are configured here, so the two never double-inject. A warning is logged once per process when the points cannot take effect (non-Anthropic model, no prompt-cache support, or a prefix below the model's minimum).

[bedrock]​

See Amazon Bedrock.

KeyDefaultDescription
guardrail_identifier""guardrail ID or ARN; empty = disabled. When set, Bedrock models must use "bedrock/converse/..."; other Bedrock routes fail instead of running unguarded
guardrail_version""e.g. "1" or "DRAFT"; required when guardrail_identifier is set
guardrail_trace"disabled""enabled", "enabled_full" or "disabled"

[openrouter]​

See OpenRouter.

KeyDefaultDescription
provider_only[]restrict routing to these upstream providers only, a hard allowlist (e.g. ["z-ai"]); empty = OpenRouter default routing
provider_order[]preferred provider order; ignored when provider_only is set; empty = unset
allow_fallbackstruewhen provider_order is set, allow routing beyond the listed providers
reasoning_effort""Invalid reasoning_effort values are warned about and treated as unset. Empty inherits config.reasoning_effort for reasoning-capable models (probed against litellm's bundled reasoning metadata or the Grok registry, or listed in additional_reasoning_effort_models). Valid values: "none", "minimal", "low", "medium", "high", "xhigh", "max". OpenRouter normalizes "max" to "xhigh" for LiteLLM/OpenRouter compatibility. Model-specific support varies. For models not covered by PR-Agent's clamps, do not assume "none" disables reasoning; check the selected model and provider's support.
reasoning_max_tokens0Use a positive value to override global effort and non-none OpenRouter-specific efforts. Keep reasoning disabled for explicit openrouter.reasoning_effort = "none", except on Grok 4.5/4.6, Gemini 3.7/3.8 Flash, and the GPT-6 models whose pages omit "none" (GPT-6 Astra and GPT-6.1 Sol). Clamp "none" to the lowest supported effort there before applying the budget, so a positive budget wins. Keep max_tokens greater than the reasoning budget where the provider requires it.
max_tokens0hard cap on completion tokens for the request; 0 = unset

[model_routing] — send a small pull request to a cheaper primary model (disabled by default)​

See Model routing.

KeyDefaultDescription
enablefalseSet true to route small pull requests to a cheaper primary model. See changing a model.
rules[]Ordered rules using max_hunks, max_files, max_patch_chars, model, and deployment_id. See changing a model.

[otel]​

See Additional configurations.

KeyDefaultDescription
is_enabledfalsedisabled by default; set to true to enable telemetry
exporter_type"console""console", "otlp", "prometheus", or "none"
service_name"pr-agent"
environment"development""development", "staging", "production", etc.
otlp_timeout3seconds; hard deadline per OTLP export call (incl. retries). Bounds CLI-exit/request stalls when the collector is unreachable; batches slower than this are dropped.
otlp_protocol"http""http" (default; exporter ships with pr-agent) or "grpc" (requires the otel-grpc extra: pip install pr-agent[otel-grpc])
prometheus_multiproc_dir"/tmp/pr-agent-prometheus"shared dir for the prometheus exporter's per-worker state files; required when exporter_type = "prometheus" (multiprocess gunicorn deployments); created 0700 and must stay owned by the run user (symlink or foreign-owner paths are refused)
include_pr_urlfalseset to true to attach PR URLs to spans (may expose private repo names)
include_error_detailsfalseset to true to attach exception messages and rejected-command text to spans (may expose PR URLs, repo names, or other request content)

[pr_similar_issue]​

See Similar Issues.

KeyDefaultDescription
skip_commentsfalse
force_update_datasetfalse
max_issues_to_scan500
vectordb"lancedb"options: "pinecone", "lancedb", "qdrant"

[pinecone]​

See Pinecone.

KeyDefaultDescription
cloud"aws"Serverless index deployment for the modern SDK. cloud is one of "aws", "gcp" or "azure"; pick a region offered by that cloud.
region"us-east-1"

[lancedb]​

See LanceDB.

KeyDefaultDescription
uri"./lancedb"

[qdrant]​

See Qdrant.

This section only documents commented-out examples; see the TOML source for details.

[skills]​

See Agent skills.

KeyDefaultDescription
enabledfalseEnable agent skills (SKILL.md) discovery and prompt injection. See agent skills.
paths[]directories to scan recursively for "*/SKILL.md"; supports ~ and $VAR
max_skills_tokens8000token budget for the combined skills_context block

[artifacts]​

See CI artifacts.

KeyDefaultDescription
enablefalseEnable artifact injection into command prompts (off by default; auto-enabled when artifact_path input is set)
artifact_path""File path or list of paths to artifacts (relative to GITHUB_WORKSPACE, or absolute)
artifact_instructions""Analysis guidance rendered separately before the untrusted artifact label and content (leave empty for a sensible default)
artifact_label""Label shown to the AI — defaults to the filename when empty.
target_commands["pr_reviewer", "pr_description", "pr_code_suggestions", "pr_questions"]Which supported commands receive artifact context; unsupported names are skipped with a warning.
max_artifact_size50000Max artifact size in characters (content is truncated if exceeded)
truncate_from"start"Which end of the file to keep when truncating: "start" (default, keeps the beginning) or "end" (keeps the tail, where build logs carry their verdict - failure, plan summary or test result).

[mosaico]​

See Mosaico server.

KeyDefaultDescription
bearer_tokens{}principal names to distinct bearer secrets; empty permits anonymous trusted-network use
routing_scan_max_chars65536positive character limit for PR URL and command detection; does not truncate diffs
health_timeout_seconds10finite positive seconds for cooperative health-probe work; excludes synchronous initialization and blocking SDK work
context_history_max_tasks100maximum prior tasks considered for a context follow-up; set from 1 to 1000
task_store_max_tasks_per_owner1000maximum retained MOSAICO tasks per owner; evicted tasks lose follow-up history

[asana]​

See Asana.

KeyDefaultDescription
request_timeout10seconds allowed for each Asana task API request

[linear]​

See Linear.

KeyDefaultDescription
request_timeout10seconds allowed for each Linear issue API request

[azure_devops]​

See Azure DevOps.

KeyDefaultDescription
default_comment_status"closed"

[azure_devops_server]​

See Azure DevOps Server.

KeyDefaultDescription
agent_identity""Host-only GUID, unique name, descriptor, or list; empty resolves review authorship automatically. See installation/azure.md

[push_outputs] — push command outputs to external sinks without calling git-provider APIs (disabled by default)​

See Push outputs.

KeyDefaultDescription
enablefalse
channels[]exact names as a list/tuple or comma-separated string: "stdout", "file", "webhook", "slack", "telegram", "teams"; empty emits nothing
commands["review", "describe"]output types; opt in to "ask" or "update_changelog"; accepts comma-separated strings. See docs/docs/usage-guide/push_outputs.md
file_path"pr-agent-outputs/reviews.jsonl"used by the "file" channel
webhook_url""used by the "webhook" channel: generic JSON POST target. Must be an absolute https:// URL
slack_webhook_url""used by the "slack" channel: a Slack Incoming Webhook URL. Must be an absolute https:// URL
telegram_bot_token""used by the "telegram" channel; kept in the fixed api.telegram.org URL path
telegram_chat_id""used by the "telegram" channel as sendMessage's destination chat
teams_webhook_url""used by the "teams" channel: Teams Workflows webhook URL. Must be an absolute https:// URL