Skip to main content

Configuration File

The different tools and sub-tools used by PR-Agent are adjustable via a Git configuration file. There are three main ways to set persistent configurations:

  1. Local configuration file
  2. Global configuration file
  3. External configuration URL (CLI flag)

In terms of precedence, local configurations will override global configurations, and global configurations will override an external configuration URL.

For a list of all possible configurations, see the configuration options page, or the rendered Configuration Reference which lists every option grouped by section. In addition to general configuration options, each tool has its own configurations. For example, the review tool will use parameters from the pr_reviewer section in the configuration file.

Tip1: Edit only what you need

Your configuration file should be minimal, and edit only the relevant values. Don't copy the entire configuration options, since it can lead to legacy problems when something changes.

Tip2: Show relevant configurations

If you set config.output_relevant_configurations to True, each tool will also output in a collapsible section its relevant configurations. This can be useful for debugging, or getting to know the configurations better.

Local configuration file​

Platforms supported: GitHub, GitLab, Bitbucket, Azure DevOps

By uploading a local .pr_agent.toml file to the root of the repo's default branch, you can customize parameters that support repository-level overrides. Note that you need to upload or update .pr_agent.toml before using the PR Agent tools (either at PR creation or via manual trigger) for the configuration to take effect.

Provider endpoint settings are host-controlled: openai.api_base, openai.api_type, openai.api_version, azure_ad.api_base, databricks.api_base, huggingface.api_base, moonshot.api_base, ollama.api_base, and openrouter.api_base are ignored when set in repository-local .pr_agent.toml and must be configured on the host. The same restriction applies to provider authentication and TLS settings: github.deployment_type, bitbucket.auth_type, gitlab.auth_type, gitlab.ssl_verify, gitea.skip_ssl_verification, and gitea.ssl_ca_cert. Jira ticket lookups run with the host's Atlassian credentials, so jira.jira_site, jira.jira_api_email, and jira.project_keys are host-controlled as well. These settings are also rejected in command arguments.

For example, if you set in .pr_agent.toml:

[pr_reviewer]
extra_instructions="""\
- instruction a
- instruction b
...
"""

Then you can give a list of extra instructions to the review tool.

Loading the local configuration from a non-default branch​

Platforms supported: GitHub, GitLab

By default, the local .pr_agent.toml is read from the repo's default branch. When running PR-Agent from the CLI (or any wrapper that exposes its arguments), you can point it at a different branch — for example to test configuration changes from a feature branch before merging them:

python -m pr_agent.cli \
  --pr_url=<PR URL> \
  --config-branch=<branch name> \
  review

Equivalently, set the PR_AGENT_CONFIG_BRANCH environment variable. The CLI flag takes precedence over the environment variable, and whitespace-only values are ignored.

If .pr_agent.toml cannot be loaded from the requested branch (e.g. the branch or file does not exist), PR-Agent logs a warning and falls back to the default branch.

Security: treat the config branch as privileged

By default, configuration is read from the default branch, so only users who can merge to it can change how PR-Agent behaves. --config-branch / PR_AGENT_CONFIG_BRANCH move that trust boundary to whatever branch you name.

Never set the config branch from untrusted or PR-derived input (e.g. --config-branch=$GITHUB_HEAD_REF / ${{ github.head_ref }} in CI). Doing so lets anyone who can push a branch to the repository supply their own .pr_agent.toml and control the review — for example pointing model/the API base at an attacker endpoint to exfiltrate the diff, injecting extra_instructions, or enabling auto-approval of their own PR. Always pin the config branch to a fixed, maintainer-controlled branch.

Provider branch behavior

Branch selection is currently implemented for GitHub and GitLab. Gitea ignores these options and reads the local .pr_agent.toml from the pull request target ref, which may differ from the default branch. Gerrit also ignores these options, but reads the file from the cloned default branch. Other platforms retain their provider-specific settings source.

Global configuration file​

Platforms supported: GitHub, GitLab, Bitbucket (cloud), Bitbucket Server, Azure DevOps, Gitea

Name an organization-level settings repository with global_settings_repo in the deployment's own configuration; its .pr_agent.toml (read from that repo's default branch) is used as a global configuration for every repository under the same organization. The setting is empty by default, which turns this off, and a repository's .pr_agent.toml or a comment cannot set it. With global_settings_repo = "pr-agent-settings", the repository read is:

  • GitHub: <organization>/pr-agent-settings
  • GitLab: <top-level-group>/pr-agent-settings (both GitLab.com and self-hosted GitLab)
  • Bitbucket (cloud): <workspace>/pr-agent-settings
  • Bitbucket Server: <project>/pr-agent-settings
  • Azure DevOps: <org>/<project>/pr-agent-settings (looked up in the same project as the current repository)
  • Gitea: <owner>/pr-agent-settings

Parameters from a local .pr_agent.toml file, in a specific repo, will override the global configuration parameters (the global file is merged beneath the repo-local one). For GitHub Enterprise Server, use the same organization-level repository on your GHES host. The app installation or token used by PR-Agent must have read access to both the pull request repository and the settings repository; otherwise, PR-Agent will skip the global configuration and continue with repository-local settings.

Caching

In long-running deployments (the GitHub App / webhook server), the fetched global settings are cached in-process for up to 15 minutes to avoid re-fetching on every webhook event, so a change to the settings repository may take up to that long to take effect there. CLI and CI (GitHub Action) runs are short-lived processes, so they fetch the global settings once per invocation and always see the latest version.

Loading the global settings file is controlled by the use_global_settings_file flag, which is enabled by default but reads nothing until global_settings_repo is set. To opt out and rely only on each repo's local .pr_agent.toml, set:

[config]
use_global_settings_file = false

For example, with global_settings_repo = "pr-agent-settings" in a GitHub organization named my-org:

  • The file my-org/pr-agent-settings/.pr_agent.toml (read from that repository's default branch) serves as a global configuration file for all the repos in the organization.

  • A repository such as my-org/my-repo inherits that global configuration file, and may override its repository-configurable values in its own .pr_agent.toml.

Project/Group level configuration file​

Platforms supported: GitLab, Bitbucket Data Center

Once global_settings_repo is set, the repository with that name within a specific project (Bitbucket) or a group/subgroup (GitLab) is read. The configuration file in this repository will apply to all repositories directly under the same project/group/subgroup.

Note

For GitLab, in case of a repository nested in several sub groups, the lookup for the settings repository will be only on one level above such repository.

External configuration URL​

Platforms supported: GitHub, GitLab, Bitbucket, Azure DevOps

When running PR-Agent from the CLI (or any wrapper that exposes its arguments), you can merge an additional .pr_agent.toml from any URL or local path before the repo-local and global configurations are applied. This is useful when:

  • You want a single shared configuration that applies to repositories nested deep inside subgroups, where the project/group-level lookup only walks one level up.
  • The shared configuration is published outside of a Git host (a static site, an internal artifact server, an S3 bucket, etc.).
  • You want CI-time control over which defaults are layered in, without committing a file to the target repository.

Usage​

Pass --extra_config_url to the CLI, or set the PR_AGENT_EXTRA_CONFIG_URL environment variable:

python -m pr_agent.cli \
  --pr_url=<MR/PR URL> \
  --extra_config_url=https://config.example.com/pr-agent/shared.toml \
  review

Accepted values:

  • https://… or http://… — fetched at runtime
  • file:///path/to/shared.toml — read from the local filesystem
  • A bare filesystem path — same as file://

GitLab comment webhooks apply this host layer before their first provider lookup; repository and per-directory settings remain part of normal command dispatch.

GitLab tokens obtained from a secret provider during webhook authentication remain bound to that request. External files and environment reapplication cannot replace those authenticated credentials.

Authentication for private endpoints​

For private endpoints (e.g. a GitLab API URL pointing at a private pr-agent-settings file), provide a single header via the PR_AGENT_EXTRA_CONFIG_AUTH_HEADER environment variable, formatted as <HeaderName>: <value>:

# GitLab Personal Access Token
export PR_AGENT_EXTRA_CONFIG_AUTH_HEADER="PRIVATE-TOKEN: <your-personal-access-token>"

# GitLab CI job token
export PR_AGENT_EXTRA_CONFIG_AUTH_HEADER="JOB-TOKEN: $CI_JOB_TOKEN"

# Generic bearer token
export PR_AGENT_EXTRA_CONFIG_AUTH_HEADER="Authorization: Bearer <your-token>"

Precedence​

External-URL settings are applied first, so every other layer overrides them:

built-in defaults
  < --extra_config_url
    < global pr-agent-settings
      < local .pr_agent.toml (repo default branch)
        < environment variables (PR_AGENT__SECTION__KEY)

This means an external URL acts as an organization-wide default that any team can still override with their own pr-agent-settings or repo-local .pr_agent.toml.

Security and limits​

The external file is loaded through the same secure loader as the repo-local .pr_agent.toml: includes, preloads, custom loaders, and other directives that could execute code or read arbitrary files are rejected. The fetcher additionally:

  • Limits the response size to 1 MB
  • Uses a 10-second request timeout
  • Only accepts http, https, file schemes (or a bare local path)

If the fetch fails, the request is logged and PR-Agent continues with the remaining configuration layers.