configuration.toml

# Important: This file contains all available configuration options.
# Do not copy this entire file to your repository configuration.
# Your repository configuration should only include options you wish to override from the defaults.

[config]
max_webhook_request_body_bytes = 5242880 # maximum request body accepted by webhook servers (5 MiB)
# models
model="gpt-5.6"
fallback_models=["gpt-5.6-terra"]
#model_reasoning="gpt-5.6-terra" # dedicated reasoning model for self-reflection
#model_weak="gpt-5.6-luna" # optional, a weaker model to use for some easier tasks
# CLI
git_provider="github"
publish_output=true
publish_output_progress=true
progress_gif_url="" # optional, override for the progress loading gif url (example: 'https://.../spinner.gif').
progress_gif_width=48 # optional, width (in px) of the progress loading gif.
verbosity_level=0 # 0,1,2
use_extra_bad_extensions=false
# Log
log_level="DEBUG"
# Configurations
use_repo_settings_file=true
use_global_settings_file=true
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_settings=false # when 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_files=20 # hard 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_pages=10 # maximum 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_feedback = false
enable_auto_approval = false # when true, /review may auto-approve a PR via auto_approve_logic(); that caller is currently commented out
ai_timeout=120 # 2 minutes
http_request_timeout=60 # host-only connect/read inactivity seconds for GitLab/Gitea and direct Bitbucket/Gerrit HTTP attempts; capped at 600
retry_same_model_on_timeout = true # when false, a timed-out call is not retried on the same model and moves on to fallback_models
retry_same_model_on_length = false # when true, an empty response truncated by the output cap is retried on the same model instead of moving straight to fallback_models
# num_retries = 0 # per-call retries inside the completion client itself; unset keeps the client's default. These multiply the handler's own retry attempts
skip_keys = []
custom_reasoning_model = false # when true, disables system messages and temperature controls for models that don't support chat-style inputs
response_language="en-US" # Language locales code for PR responses in ISO 3166 and ISO 639 format (e.g., "en-US", "it-IT", "zh-CN", ...)
repo_context_files = ["AGENTS.md"] # Repository-relative files (e.g. AGENTS.md, CLAUDE.md) to include as AI prompt context; set to [] to disable local context. A structured entry {"repo_id" = ..., "file_path" = ...} selects a sibling default-branch file from the same namespace/owner; repo_id must be in the host-issued repo_context_sibling_repos allowlist below. Reads use the sibling default branch and share repo_context_max_lines; repository settings may select entries, comment arguments cannot override this key
# The repo-context cache is keyed on the revision read: the PR target commit for target-branch
# reads, and the resolved default branch head on GitHub, so a default-branch push invalidates
# cached content within the TTL. Providers without commit resolution key on a branch name or None.
repo_context_from_default_branch = true # Read 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_lines = 500 # Maximum total rendered lines for repo context, including wrapper tags
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, this also approves repositories for linked-issue and sub-issue 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_max_sibling_files = 5 # Maximum 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
max_description_tokens = 500
max_commits_tokens = 500
max_model_tokens = 32000 # Limits the maximum number of tokens that can be used by any model, regardless of the model's default capabilities.
custom_model_max_tokens=-1 # Override unknown models or Sol-tier GPT-6 on non-native custom providers.
# Send max_completion_tokens for recognized Astra IDs, including bare IDs on custom providers,
# and native OpenAI/Azure Sol-tier GPT-6. OpenRouter Astra uses it only without a routing suffix or with :nitro/:floor.
# Use max_tokens for other routes, including azure_text and text-completion-openai.
# Choose a limit supported by the selected model.
max_output_tokens = 0 # 0 = unset (the provider's own default applies)
model_token_count_estimate_factor=0.3 # factor 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_allowance=4096 # reserve tokens per image when provider counting omits or underestimates image cost
# patch extension logic
patch_extension_skip_types =[".md",".txt"]
allow_dynamic_context=true
max_extra_lines_before_dynamic_context = 10 # will 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_before = 5 # Number of extra lines (+3 default ones) to include before each hunk in the patch
patch_extra_lines_after = 1 # Number 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_mode=false
output_relevant_configurations=false
output_run_details=false # if true, append an agent run details section (model, tokens, time cost, AI calls) to generated PR comments
output_run_cost=false # if true, collect estimated LiteLLM API cost and include it inside the enabled run details section
large_patch_policy = "clip" # "clip", "skip"
duplicate_prompt_examples = false
# Enable 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.
persistent_inline_comments = false
# seed
seed=-1 # set positive value to fix the seed (and ensure temperature=0)
temperature=0.2
# ignore logic
ignore_pr_title = ["^\\[Auto\\]", "^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
ignore_pr_authors = [] # authors to ignore from PR agent when an PR is created
# Reactions added to the comment that triggered a command. Names are provider-specific:
# GitHub accepts only +1, -1, laugh, confused, heart, hooray, rocket, eyes; GitLab and Gitea
# take any award-emoji name. An empty value disables that reaction. When an outcome reaction
# is configured it replaces the start reaction rather than joining it. The GitHub App and the
# GitLab webhook both apply the outcome reactions. They differ on auto_review, which runs without
# the notify hook the start reaction hangs off: the GitLab webhook gives it nothing, because it
# gates the outcome on that hook too, while the GitHub App still gives it the outcome reaction. A
# comment that is not a command gets no reaction at all on the GitLab webhook.
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
# 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"]`).
bot_user_indicators = ["codium", "bot_", "bot-", "_bot", "-bot"]
#
restricted_mode = false # when true, skip operations that require elevated permissions (e.g. pushing code to the repository)
is_auto_command = false # will be auto-set to true if the command is triggered by an automation
propagate_tool_errors = false # when true, a tool re-raises instead of swallowing an internal error, so a caller can tell a failed run from an empty one
enable_ai_metadata = false # will enable adding ai metadata
add_user_to_requests = false # send 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"
# 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.
additional_reasoning_effort_models = []
# 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 and Opus/Sonnet/Fable 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 the issue for the probe diff.
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"]
# extended thinking for Claude reasoning models
enable_claude_extended_thinking = false # Set to true to enable extended thinking feature
extended_thinking_budget_tokens = 2048
extended_thinking_max_output_tokens = 4096
# Adaptive 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.
enable_claude_adaptive_thinking = false
# Optional: list model ids to additionally treat as adaptive-only Claude models. Add opaque Bedrock
# application inference profile ARNs here while keeping built-in detection for named models.
# When adaptive thinking is enabled, use the exact request model ids so LiteLLM keeps the adaptive
# payload instead of converting it to the legacy budget_tokens shape.
claude_adaptive_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.
claude_extended_thinking_models_override = []
# Extract issue number from PR source branch name (e.g. feature/1-auth-google -> issue #1). When true, branch-derived
# issue URLs are merged with tickets from the PR description for compliance. Set to false to restore description-only behaviour.
# Note: Branch-name extraction is GitHub-only for now; other providers planned for later.
extract_issue_from_branch = true
# Optional: custom regex with exactly one capturing group for the issue number (validated at runtime; falls back
# to default if missing). 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). GitHub only; other providers planned for later.
branch_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+)'
description_issue_regex = ""


[pr_reviewer] # /review #
# enable/disable features
require_score_review=false
require_tests_review=true
require_estimate_effort_to_review=true
require_can_be_split_review=false
require_security_review=true
require_estimate_contribution_time_cost=false
require_todo_scan=false
require_ticket_analysis_review=true
# Opt-in structured assessment fields. Each adds one field to the review output and to the model's output schema.
require_risk_assessment=false # ask the model for an overall risk level (low/medium/high)
require_merge_recommendation=false # ask 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)
require_failure_modes=false # ask for up to three concrete failure scenarios and their detection/coverage
require_priority_files=false # ask the model which files a human should inspect first
# general options
publish_output_no_suggestions=true # Set 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_comment=true # Set to false to suppress review failure comments without changing the command's failure status.
publish_error_details=false # Publish a deterministic, sanitized failure reason in manual review comments. No AI call is used.
persistent_comment=true
# Visible base heading for full and incremental review comments. Identity is tracked separately.
review_heading = "PR Reviewer Guide"
persistent_finding_state=true # Persist review finding state across complete review runs.
# Character 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.
max_previous_findings_chars = 8000

inline_key_issues=false # Publish each review finding as an inline comment where the provider can verify inline-comment publication (GitHub, Bitbucket Cloud, Azure DevOps, GitLab).
extra_instructions = ""
num_max_findings = 3
final_update_message = true
# review labels
enable_review_labels_security=true
enable_review_labels_effort=true
# specific configurations for incremental review (/review -i)
require_all_thresholds_for_incremental_review=false
minimal_commits_for_incremental_review=0
minimal_minutes_for_incremental_review=0
enable_intro_text=true
enable_help_text=false # Determines whether to include help text in the PR review.
enable_review_coverage_footer=true
# large-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.
enable_large_pr_chunking=false
max_number_of_calls=3 # maximum number of chunk review calls, used only when enable_large_pr_chunking is true

[pr_description] # /describe #
publish_labels=false
add_original_user_description=true
generate_ai_title=false
extra_instructions = ""
enable_pr_type=true
enable_pr_description=true # adds a section with an AI-generated summary of the PR changes
final_update_message = true
enable_help_text=false
enable_help_comment=false
enable_pr_diagram=true # adds 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_threshold=5 # with 'adaptive', a chain longer than this many nodes is drawn top-down
# describe as comment
publish_description_as_comment=false
publish_description_as_comment_persistent=true
## changes walkthrough section
enable_semantic_files_types=true
collapsible_file_list='adaptive' # true, false, 'adaptive'
collapsible_file_list_threshold=6
file_table_collapsible_open_by_default=false
# markers
use_description_markers=false
enable_large_pr_handling=true
include_generated_by_header=true
#custom_labels = ['Bug fix', 'Tests', 'Bug fix with tests', 'Enhancement', 'Documentation', 'Other']
max_ai_calls=4
async_ai_calls=true
[pr_questions] # /ask #
enable_help_text=false
use_conversation_history=true
# Set the plain-text heading for top-level /ask answers; provider-specific presentation is added automatically.
ask_heading = "Ask"
# Enable to let /ask_line resolve the review thread when the LLM judges the
# issue addressed. Note: also resolves threads started by human reviewers.
resolve_threads=false
extra_instructions = ""


[pr_code_suggestions] # /improve #
# Deprecated alias still accepted until 1.0: pr_code_suggestions.commitable_code_suggestions
committable_code_suggestions = false
dual_publishing_score_threshold=-1 # -1 to disable, [0-10] to set the threshold (>=) for publishing a code suggestion both in a table and as committable
focus_only_on_problems=true
#
extra_instructions = ""
# Visible base heading for summary-table /improve comments. Identity is tracked separately.
suggestions_heading = "PR Code Suggestions"
enable_help_text=false
enable_chat_text=false
persistent_comment=true
max_history_len=4
publish_output_no_suggestions=true
enable_suggestions_coverage_footer=true # show failed chunks and files omitted by the token or AI-call budget
# suggestions scoring
suggestions_score_threshold=0 # [0-10]| recommend not to set this value above 8, since above it may clip highly relevant suggestions
score_on_reflection_failure=7 # [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_mechanism=true
new_score_mechanism_th_high=9
new_score_mechanism_th_medium=7
# params for '/improve --extended' mode
num_code_suggestions_per_chunk=3
# Maximum 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_suggestions_per_file = 0
# Character budget for prior code-suggestion threads given to /improve as context (GitLab, Azure DevOps); 0 disables it.
max_discussion_context_chars = 24000
max_number_of_calls = 3
parallel_calls = true

decouple_hunks = false
# self-review checkbox
demand_code_suggestions_self_review=false # add 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."
approve_pr_on_self_review=false # no effect: the self-review checkbox is a visual marker only, and PR-Agent does not approve PRs (see the improve docs and the FAQ)
fold_suggestions_on_self_review=true # no effect: the self-review checkbox is a visual marker only, and suggestions are not folded when it is ticked

[pr_add_docs] # /add_docs #
extra_instructions = ""
docs_style = "Sphinx" # "Google Style with Args, Returns, Attributes...etc", "Numpy Style", "Sphinx Style", "PEP257", "reStructuredText"

[pr_update_changelog] # /update_changelog #
push_changelog_changes=false
extra_instructions = ""
add_pr_link=true
skip_ci_on_push=true

[pr_config] # /config #

[pr_help_docs]
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_readme = false
supported_doc_exts = [".md", ".mdx", ".rst"]
enable_help_text=false

[github]
# The type of deployment to create. Valid values are 'app' or 'user'.
deployment_type = "user"
ratelimit_retries = 5
# PyGithub 2.x enables request pacing and transient retries by default (0.25s
# between requests, 1s between writes, 10 retries); PyGithub 1.59 applied none.
# The defaults below mirror the 1.59 behaviour, so the 2.x upgrade stays neutral
# unless an operator opts in. Raise them to throttle or retry on the GitHub API.
seconds_between_requests = 0 # seconds between API requests; 0 = no pacing (1.59 behaviour)
seconds_between_writes = 0 # seconds between write calls; 0 = no pacing (1.59 behaviour)
api_retries = 0 # max retries per request with backoff; 0 = no retries (1.59 behaviour)
polling_request_timeout = 10 # total seconds for comment-history fallback; positive values capped at 60
base_url = "https://api.github.com"
try_fix_invalid_inline_comments = true
ignore_bot_pr = true
publish_as_check_run = false # when true, publish review/description/improve output as GitHub Checks instead of PR comments

[github_action_config]
# auto_review = true    # set as env var in .github/workflows/pr-agent.yaml
# auto_describe = true  # set as env var in .github/workflows/pr-agent.yaml
# auto_improve = true   # set as env var in .github/workflows/pr-agent.yaml
# pr_actions = ['opened', 'reopened', 'ready_for_review', 'review_requested']
# handle_push_trigger = false  # when true, handle synchronize events using push_commands (falls back to github_app.handle_push_trigger)
# push_trigger_ignore_bot_commits = true
# push_trigger_ignore_merge_commits = true
# push_commands = ['/describe', '/review']  # defaults mirror github_app.push_commands
# review_states = ['changes_requested']  # states that trigger review_commands after a submitted GitHub review
# review_author_types = ['User']  # review.user.type values allowed to trigger review_commands
# review_commands = []  # empty by default; falls back to github_app.review_commands when unset
# fail_on_tool_errors = true  # a recorded tool failure (propagate_tool_errors=false) fails the Action; set false to keep the old green behavior

[github_app]
# these toggles allows running the github app from custom deployments
override_deployment_type = true
# settings for "pull_request" event
handle_pr_actions = ['opened', 'reopened', 'ready_for_review']
feedback_on_draft_pr = false
# A submitted GitHub review can optionally trigger these commands. The empty default preserves current behavior.
review_states = ["changes_requested"]
review_author_types = ["User"]
review_commands = []
# Opt 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.
webhook_delivery_deduplication = false
# settings for "pull_request" event with "synchronize" action - used to detect and handle push triggers for new commits
handle_push_trigger = false
push_trigger_ignore_bot_commits = true
push_trigger_ignore_merge_commits = true
push_trigger_pending_tasks_backlog = true
push_trigger_pending_tasks_ttl = 300
push_commands = [
    "/describe",
    "/review",
]

[gitlab]
url = "https://gitlab.com"
# Submodule targets must also be listed in config.repo_context_sibling_repos.
expand_submodule_diffs = false
feedback_on_draft_pr = false
# Post the /review summary as a resolvable thread (discussion) instead of a plain note.
publish_review_as_thread = false
# Post the /improve suggestions comment as a resolvable thread (discussion) instead of a plain note.
publish_improve_as_thread = false
# On GitLab, reply to the triggering note's discussion for `/review` and `/improve` output when a discussion ID is available.
reply_to_trigger_comment = false
# When 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.
publish_code_suggestions_as_review = false
# Resolve the bot's own inline threads that a later push left on an outdated diff version.
resolve_outdated_inline_threads = false
# Resolve 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.
auto_resolve_fixed_inline_threads = false
handle_push_trigger = false
push_commands = [
    "/describe",
    "/review",
]
# Configure SSL validation for GitLab. Can be either set to the path of a custom CA or disabled entirely.
# ssl_verify = true
# Auto-trigger commands when the bot is assigned as a reviewer on an MR
handle_reviewer_assignment = false
reviewer_commands = [
    "/review",
]

[gitea]
url = "https://gitea.com"
# Optional user-facing base URL used to build links published in comments, for
# self-hosted instances where the API is reached via an internal address but
# users browse a different external URL, or where the server's own ROOT_URL is
# misconfigured. Defaults to `url` when it differs from the shipped default
# above, else derived from the PR's html_url.
# web_url = ""
handle_push_trigger = false
push_commands = [
    "/describe",
    "/review",
]

[bitbucket]
identity_request_timeout = 30 # positive seconds for authenticated-account verification requests

[bitbucket_app]
avoid_full_files = false
request_timeout = 30 # positive seconds for connection and response-read inactivity timeouts

[local]
# LocalGitProvider settings - uncomment to use paths other than default
# description_path= "path/to/description.md"
# review_path= "path/to/review.md"
# improve_path= "path/to/improve.md"

[gerrit]
# both are required: the gerrit webhook endpoint rejects every call until they are set
webhook_username = ""
webhook_password = ""
# endpoint to the gerrit service
# url = "ssh://gerrit.example.com:29418"
# user for gerrit authentication
# user = "ai-reviewer"
# patch server where patches will be saved
# patch_server_endpoint = "http://127.0.0.1:5000/patch"
# token to authenticate in the patch server
# patch_server_token = ""

[bitbucket_server]
# url = "https://git.bitbucket.com"
url = "" # URL to the BitBucket Server instance

[jira]
# Jira Cloud ticket context. Only Jira Cloud is supported; the base URL is built as
# https://<jira_site>.atlassian.net from the site name below, so repo configuration
# cannot redirect the authenticated request to another host.
# Credentials: fill and place in .secrets.toml, or set via environment variables
# (e.g. jira__jira_api_token).
# jira_site = "your-org"   # the "<site>" in https://<site>.atlassian.net
# jira_api_email = "..."   # Atlassian account email
# jira_api_token = "..."   # Atlassian API token
# Custom field id holding acceptance criteria / requirements, mapped to the ticket
# "requirements" section. Instance-specific (e.g. "customfield_10127"); empty disables it.
jira_requirements_field = ""
# 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.
# Empty (default) looks up every key found. Host-only, like jira_site and jira_api_email:
# repository settings and comment arguments cannot change them.
project_keys = []

[litellm]
# use_client = false
# drop_params = false
enable_callbacks = false
success_callback = []
failure_callback = []
service_callback = []
turn_off_message_logging = false # set true to keep prompt/response content (the whole PR diff) out of callback payloads; strongly recommended with the "otel" callback
# 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.
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_custom_llm_provider = ""
force_streaming_api_base_substrings = []
callback_timeout_seconds = 30 # max seconds to wait for pending litellm callbacks to flush before exiting
# Application inference profile ARN for classic `bedrock/` calls through the `bedrock-runtime` APIs.
# Not used by `bedrock_mantle/`, which uses Projects for cost allocation.
# model_id = ""
# 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.
base_models = {}
# Optional: set a profile per model (fallbacks included), keyed by the exact model name.
# An entry here takes priority over model_id for that model.
# model_ids = {"bedrock/us.anthropic.claude-sonnet-4-6" = "arn:aws:bedrock:...", "bedrock/qwen.qwen3-235b-a22b-2507-v1:0" = "arn:aws:bedrock:..."}
# 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).
cache_control_injection_points = []

[openrouter]
# OpenRouter provider routing, reasoning control and output cap. These apply only
# to models addressed as "openrouter/...". The API key and api_base live in
# .secrets.toml (or the openrouter__key env var); the keys below are non-secret.
# Refs: https://openrouter.ai/docs/guides/routing/provider-selection
#       https://openrouter.ai/docs/guides/best-practices/reasoning-tokens
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_fallbacks = true # when provider_order is set, allow routing beyond the listed providers
# 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_effort = ""
# Use 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.
reasoning_max_tokens = 0
max_tokens = 0 # hard cap on completion tokens for the request; 0 = unset

[model_routing] # send a small pull request to a cheaper primary model (disabled by default)
# Rules are checked in order; the first one whose limits the pull request fits selects the primary model for the
# call, and config.fallback_models still apply after it. A pull request that fits no rule uses config.model.
# Size is measured after the [ignore] rules by diff hunks (max_hunks) and changed files (max_files), which every
# git provider reports and which do not depend on any model's tokenizer. Only calls that ask for the regular model
# are routed (/review, /improve, /generate_labels, /add_docs); tools that use model_weak are left alone.
# With Azure (openai.deployment_id set) a rule also needs its own deployment_id, or it is skipped.
enable = false
rules = [] # e.g. [{ max_hunks = 3, model = "gpt-5.6-luna" }, { max_hunks = 15, max_files = 6, model = "gpt-5.6-terra" }]

[otel]
# Keys map to settings.get("OTEL.*") via section-key dot notation.
is_enabled = false # disabled 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_timeout = 3 # seconds; 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_url = false # set to true to attach PR URLs to spans (may expose private repo names)
include_error_details = false # set 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]
skip_comments = false
force_update_dataset = false
max_issues_to_scan = 500
vectordb = "lancedb" # options: "pinecone", "lancedb", "qdrant"

[pinecone]
# fill and place in .secrets.toml
#api_key = ...
# Serverless index deployment for the modern SDK. `cloud` is one of "aws",
# "gcp" or "azure"; pick a `region` offered by that cloud.
cloud = "aws"
region = "us-east-1"

[lancedb]
uri = "./lancedb"

[qdrant]
# fill and place credentials in .secrets.toml
# url = "https://YOUR-QDRANT-URL"
# api_key = "..."

[skills]
# Agent skills (SKILL.md) support: discovers SKILL.md files from the configured
# filesystem paths and injects their content into review/improve/describe and
# top-level /ask prompts.
# Sibling *.md files in the skill directory tree (e.g. references/guide.md) are
# inlined alongside SKILL.md. PR-Agent supports text-only skills: scripts/ and
# assets/ subdirectories are skipped because PR-Agent uses a single-shot model
# call (no tool-use loop) and cannot execute scripts or load binary assets on
# demand. Skills that depend on script execution will not work here.
# See https://github.com/The-PR-Agent/pr-agent/issues/2384
enabled = false
paths = [] # directories to scan recursively for "*/SKILL.md"; supports ~ and $VAR
max_skills_tokens = 8000 # token budget for the combined skills_context block

[artifacts]
# Enable artifact injection into tool prompts (off by default; auto-enabled when artifact_path input is set)
enable = false
# File path to the artifact (relative to GITHUB_WORKSPACE, or absolute)
artifact_path = ""
# Analysis guidance rendered separately before the untrusted artifact label and content (leave empty for a sensible default)
artifact_instructions = ""
# Label shown to the AI — defaults to the filename when empty.
artifact_label = ""
# Which supported tools receive artifact context; unsupported names are skipped with a warning.
target_tools = ["pr_reviewer", "pr_description", "pr_code_suggestions"]
# Max artifact size in characters (content is truncated if exceeded)
max_artifact_size = 50000
# 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).
truncate_from = "start"

[mosaico]
bearer_tokens = {} # principal names to distinct bearer secrets; empty permits anonymous trusted-network use
routing_scan_max_chars = 65536 # positive character limit for PR URL and command detection; does not truncate diffs
health_timeout_seconds = 10 # finite positive seconds for cooperative health-probe work; excludes synchronous initialization and blocking SDK work
context_history_max_tasks = 100 # maximum prior tasks considered for a context follow-up; set from 1 to 1000

[asana]
request_timeout = 10 # seconds allowed for each Asana task API request

[azure_devops]
default_comment_status = "closed"

[azure_devops_server]
agent_identity = "" # empty: discover the identity from earlier agent comments on the PR

[push_outputs] # push tool outputs to external sinks without calling git-provider APIs (disabled by default)
enable = false
channels = [] # any of: "stdout", "file", "webhook", "slack", "telegram". Nothing is emitted until a channel is listed here
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