Skip to main content

Usage and Automation

Local repo (CLI)​

When running from your locally cloned PR-Agent repo (CLI), your local configuration file will be used. Examples of invoking the different tools via the CLI:

  • Review: python -m pr_agent.cli --pr_url=<pr_url> review
  • Describe: python -m pr_agent.cli --pr_url=<pr_url> describe
  • Improve: python -m pr_agent.cli --pr_url=<pr_url> improve
  • Ask: python -m pr_agent.cli --pr_url=<pr_url> ask "Write me a poem about this PR"
  • Update Changelog: python -m pr_agent.cli --pr_url=<pr_url> update_changelog

The commands above assume the pr_agent package is importable — use the venv created by uv sync, or install PR-Agent.

<pr_url> is the url of the relevant PR (for example: #50).

Notes:

  1. In addition to editing your local configuration file, you can also change repository-configurable values by adding them to the command line:
python -m pr_agent.cli --pr_url=<pr_url>  /review --pr_reviewer.extra_instructions="focus on the file: ..."

Host-controlled values, including provider authentication, TLS, and endpoint settings, are rejected in command arguments. See Configuration Options for details.

  1. You can print results locally, without publishing them, by setting in configuration.toml:
[config]
publish_output=false
verbosity_level=2

This is useful for debugging or experimenting with different tools.

  1. git provider: The git_provider field in a configuration file determines the GIT provider that will be used by PR-Agent. Currently, the following providers are supported: github (default), gitlab, bitbucket, azure, codecommit, local, and gitea.

  2. For scripts that need a failed request to return a non-zero process status, enable tool error propagation:

python -m pr_agent.cli --pr_url=<pr_url> review --config.propagate_tool_errors=true

With config.propagate_tool_errors=true, the installed pr-agent command, python -m pr_agent.cli, and the customizable pip script exit with status 1 when a propagated tool error makes the request fail or a tool records a failure even though it returns successfully. In the latter case, the CLI logs a warning explaining the non-zero exit.

Tool error propagation is disabled by default, preserving the existing status 0 behavior for these tool failures. Argparse parse and usage errors continue to exit with status 2.

CLI Health Check​

To verify that PR-Agent has been configured correctly, you can run this health check command from the repository root:

python -m tests.health_test.main

If the health check passes, you will see the following output:

========
Health test passed successfully
========

At the end of the run.

Before running the health check, ensure you have:

  • Configured your LLM provider
  • Added a valid GitHub token to your configuration file

Online usage​

Online usage means invoking PR-Agent tools by comments on a PR. Commands for invoking the different tools via comments:

  • Review: /review
  • Describe: /describe
  • Improve: /improve (or /improve_code for bitbucket, since /improve is sometimes reserved)
  • Ask: /ask "..."
  • Update Changelog: /update_changelog

To edit a specific configuration value, just add --config_path=<value> to any command. For example, if you want to edit the review tool configurations, you can run:

/review --pr_reviewer.extra_instructions="..." --pr_reviewer.require_score_review=false

Most values in the configuration file can be similarly edited. Host-controlled settings, including provider connection locations and credentials, cannot be changed through PR comments. Comment /config to see the list of available configurations.

PR-Agent Automatic Feedback​

Disabling all automatic feedback​

To easily disable all automatic feedback from PR-Agent (GitHub App, GitLab Webhook, BitBucket App, Azure DevOps Webhook), set in a configuration file:

[config]
disable_auto_feedback = true

When this parameter is set to true, PR-Agent will not run any automatic tools (like describe, review, improve) when a new PR is opened, or when new code is pushed to an open PR.

GitHub App​

Configurations for PR-Agent

These settings apply to self-hosted GitHub App, GitLab webhook, and Bitbucket App deployments.

GitHub app automatic tools when a new PR is opened​

The github_app section defines GitHub app specific configurations.

The configuration parameter pr_commands defines the list of tools that will be run automatically when a new PR is opened:

[github_app]
pr_commands = [
    "/describe",
    "/review",
    "/improve",
]

This means that when a new PR is opened/reopened or marked as ready for review, PR-Agent will run the describe, review and improve tools.

Draft PRs:

By default, draft PRs are not considered for automatic tools, but you can change this by setting the feedback_on_draft_pr parameter to true in the configuration file. When enabled, marking the PR as ready does not run pr_commands a second time. Because this setting can be overridden per repository, draft PR events, including each synchronize event caused by a push, still fetch the repository configuration before being skipped.

[github_app]
feedback_on_draft_pr = true

Changing default tool parameters:

You can override the default tool parameters by using one the three options for a configuration file: local, global, or external URL. For example, if your configuration file contains:

[pr_description]
generate_ai_title = true

Every time you run the describe tool (including automatic runs) the PR title will be generated by the AI.

Parameters for automated runs:

You can customize configurations specifically for automated runs by using the --config_path=<value> parameter. These command parameters apply before repository loading, so they can control that loading, and again afterward so command values take precedence over repository settings. For instance, to modify the review tool settings only for newly opened PRs, use:

[github_app]
pr_commands = [
    "/describe",
    "/review --pr_reviewer.extra_instructions='focus on the file: ...'",
    "/improve",
]

Automatic tools for push actions (commits to an open PR)​

In addition to running automatic tools when a PR is opened, PR-Agent can also respond to new code that is pushed to an open PR. This works for both GitHub App and GitHub Action deployments.

The configuration toggle handle_push_trigger can be used to enable this feature. The configuration parameter push_commands defines the list of tools that will be run automatically when new code is pushed to the PR.

[github_app]
handle_push_trigger = true
push_commands = [
    "/describe",
    "/review",
]

For GitHub Action, settings fall back from github_action_config.* to github_app.*, so you can set either section.

This means that when new code is pushed to the PR, PR-Agent will run the describe and review tools, with the specified parameters.

GitHub Action​

GitHub Action is a different way to trigger PR-Agent tools, and uses a different configuration mechanism than GitHub App.
You can configure settings for GitHub Action by adding environment variables under the env section in .github/workflows/pr_agent.yml file.

Fork/contribution support

To support PRs from forked repositories, use the pull_request_target event instead of pull_request. See the fork contribution guide for a complete example and security considerations.

Specifically, start by setting the following environment variables:

      env:
        OPENAI_KEY: ${{ secrets.OPENAI_KEY }} # Make sure to add your OpenAI key to your repo secrets
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Make sure to add your GitHub token to your repo secrets
        github_action_config.auto_review: "true" # enable\disable auto review
        github_action_config.auto_describe: "true" # enable\disable auto describe
        github_action_config.auto_improve: "true" # enable\disable auto improve
        github_action_config.pr_actions: '["opened", "reopened", "ready_for_review", "review_requested"]'

github_action_config.auto_review, github_action_config.auto_describe and github_action_config.auto_improve are used to enable/disable automatic tools that run when a new PR is opened. If not set, the default configuration is for all three tools to run automatically when a new PR is opened.

github_action_config.pr_actions is used to configure which pull_requests events will trigger the enabled auto flags If not set, the default configuration is ["opened", "reopened", "ready_for_review", "review_requested"] Adding "synchronize" to this list enables auto tools on new commits pushed to an open PR. You must also add synchronize to the workflow pull_request: types: list.

github_action_config.handle_push_trigger controls whether synchronize events run the push commands (default false). Settings fall back to github_app.* if not set under github_action_config. Since it defaults to false, synchronize is opt-in — you must explicitly enable it by either adding "synchronize" to pr_actions or setting handle_push_trigger = true.

github_action_config.push_commands defines which tools run on synchronize events when handle_push_trigger is enabled (fallback to github_app.push_commands).

github_action_config.push_trigger_ignore_merge_commits (default true) skips processing when the push contains a merge commit, avoiding duplicate reviews on "Update branch" clicks.

github_action_config.push_trigger_ignore_bot_commits (default true) skips processing when the push author is a bot, avoiding redundant runs on automated commits.

github_action_config.fail_on_tool_errors (default true) makes the Action exit non-zero when a tool recorded a swallowed failure (the default propagate_tool_errors = false case), instead of finishing green on a pull request that got no review. Set it to false to restore the previous behavior of ignoring recorded tool failures. Set it in the workflow configuration; comment arguments such as /review --github_action_config.fail_on_tool_errors=false are rejected.

Automatic tools after a submitted GitHub review​

The GitHub App can run configured tools after a human reviewer submits a native GitHub review. This is opt-in: review_commands is empty by default. By default, only reviews submitted with the changes_requested state by a User review author trigger the commands. This conservative default avoids running on the repository's high-volume commented reviews; set review_states or review_author_types explicitly when a different workflow is needed.

[github_app]
review_states = ["changes_requested"]
review_author_types = ["User"]
review_commands = [
    "/improve",
]

The event must be submitted; edited or dismissed reviews do not trigger tools. The review author's user.type must match review_author_types, which defaults to User and prevents bot reviews from triggering commands. Existing repository filtering, draft-PR handling, eligibility checks, and config.disable_auto_feedback still apply. The review text is not treated as a command; each configured command runs with the normal pull-request context.

For GitHub Action, add the review event to the workflow and configure the equivalent settings. github_action_config.* overrides the corresponding github_app.* setting when present.

on:
  pull_request_review:
    types: [submitted]

env:
  github_action_config.review_states: '["changes_requested"]'
  github_action_config.review_author_types: '["User"]'
  github_action_config.review_commands: '["/improve"]'

github_action_config.enable_output are used to enable/disable github actions output parameter (default is true). Review result is output as JSON to steps.{step-id}.outputs.review property. The JSON structure is equivalent to the yaml data structure defined in pr_reviewer_prompts.toml.

github.publish_as_check_run controls whether tool output (review, describe, improve) is published as a GitHub Check Run instead of a PR comment (default is false). When enabled, results appear in the "Checks" tab of the PR. Requires checks: write permission in the workflow YAML. On the GitHub App, each automatic command opens its check run as in progress before the tool runs, so the author sees that PR-Agent picked the pull request up before any output exists; while a chunked command runs, that in-progress run also shows the analyzed chunk count, for example PR-Agent is running /review analyzed 2 of 3 chunks. The run is completed with the tool's output, or marked failed if the command did not finish.

Note that you can give additional config parameters by adding environment variables to .github/workflows/pr_agent.yml, or by using a .pr_agent.toml configuration file in the root of your repo

For example, you can set an environment variable: pr_description.publish_labels=false, or add a .pr_agent.toml file with the following content:

[pr_description]
publish_labels = false

to prevent PR-Agent from publishing labels when running the describe tool.

Enable using commands in PR​

You can configure your GitHub Actions workflow to trigger on issue_comment events (created and edited).

Example GitHub Actions workflow configuration:

on:
  issue_comment:
    types: [created, edited]

When this is configured, PR-Agent can be invoked by commenting on the PR.

Quick Reference: Model Configuration in GitHub Actions​

For detailed step-by-step examples of configuring different models (Gemini, Claude, Azure OpenAI, etc.) in GitHub Actions, see the Configuration Examples section in the installation guide.

Common Model Configuration Patterns:

  • OpenAI: Set config.model: "<openai-model>" and OPENAI_KEY
  • Gemini: Set config.model: "gemini/gemini-3.8-flash" and GOOGLE_AI_STUDIO.GEMINI_API_KEY (no OPENAI_KEY needed)
  • Claude: Set config.model: "anthropic/claude-opus-5" and ANTHROPIC.KEY (no OPENAI_KEY needed)
  • Azure OpenAI: Set OPENAI.API_TYPE: "azure", OPENAI.API_BASE, and OPENAI.DEPLOYMENT_ID
  • Local Models: Set config.model: "ollama/model-name" and OLLAMA.API_BASE

Environment Variable Format:

  • Use dots (.) to separate sections and keys: config.model, pr_reviewer.extra_instructions
  • Boolean values as strings: "true" or "false"
  • Arrays as JSON strings: '["item1", "item2"]'

For complete model configuration details, see Changing a model in PR-Agent.

GitLab Webhook​

After setting up a GitLab webhook, to control which commands will run automatically when a new MR is opened, you can set the pr_commands parameter in the configuration file, similar to the GitHub App:

[gitlab]
pr_commands = [
    "/describe",
    "/review",
    "/improve",
]

Draft MRs are skipped by default. Set feedback_on_draft_pr = true under [gitlab] to enable automatic feedback. When enabled, marking the MR as ready does not run pr_commands a second time. Because this setting can be overridden per repository, draft MR events still fetch the repository configuration before being skipped. For environment-based deployments, set GITLAB__FEEDBACK_ON_DRAFT_PR=true.

the GitLab webhook can also respond to new code that is pushed to an open MR. The configuration toggle handle_push_trigger can be used to enable this feature. The configuration parameter push_commands defines the list of tools that will be run automatically when new code is pushed to the MR.

[gitlab]
handle_push_trigger = true
push_commands = [
    "/describe",
    "/review",
]

Note that to use the 'handle_push_trigger' feature, you need to give the gitlab webhook also the "Push events" scope.

The GitLab webhook can also respond to the bot being assigned as a reviewer on an open MR. The configuration toggle handle_reviewer_assignment can be used to enable this feature. The configuration parameter reviewer_commands defines the list of tools that will be run automatically when the bot is added to the MR's reviewers.

[gitlab]
handle_reviewer_assignment = true
reviewer_commands = [
    "/review",
]

The commands run only when the bot is newly added to the reviewer list, so re-saving an MR without changing its reviewers does not run them again. The bot is identified by the user behind gitlab.personal_access_token, which must therefore be set for this feature to work. Draft MRs and MRs matching the ignore settings are skipped.

BitBucket App​

Similar to GitHub app, when running PR-Agent from BitBucket App, the default configuration file will be initially loaded.

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 .pr_agent.toml prior to creating a PR, in order for the configuration to take effect.

Provider endpoint settings are host-controlled. Values for the endpoint keys listed in the local configuration guide are ignored when set in repository-local .pr_agent.toml and must be configured on the host.

For example, if your local .pr_agent.toml file contains:

[pr_reviewer]
extra_instructions = "Answer in japanese"

Each time you invoke a /review tool, it will use the extra instructions you set in the local configuration file.

Note that among other limitations, BitBucket provides relatively low rate-limits for applications (up to 1000 requests per hour), and does not provide an API to track the actual rate-limit usage. If you experience a lack of responses from PR-Agent, you might want to set: bitbucket_app.avoid_full_files=true in your configuration file. This will prevent PR-Agent from acquiring the full file content, and will only use the diff content. This will reduce the number of requests made to BitBucket, at the cost of small decrease in accuracy, as dynamic context will not be applicable.

For self-hosted BitBucket App deployments, bitbucket_app.request_timeout sets both the connection timeout and response-read inactivity timeout, in positive seconds, for offloaded BitBucket HTTP requests. It defaults to 30 and is read from host-level configuration or the BITBUCKET_APP__REQUEST_TIMEOUT environment variable; repository .pr_agent.toml overrides do not apply to this host resource limit.

BitBucket Self-Hosted App automatic tools​

To control which commands will run automatically when a new PR is opened, you can set the pr_commands parameter in the configuration file: Specifically, set the following values:

[bitbucket_app]
pr_commands = [
    "/review",
    "/improve --pr_code_suggestions.committable_code_suggestions=true --pr_code_suggestions.suggestions_score_threshold=7",
]

Note that we set specifically for bitbucket, we recommend using: --pr_code_suggestions.suggestions_score_threshold=7 and that is the default value we set for bitbucket. Since this platform only supports inline code suggestions, we want to limit the number of suggestions, and only present a limited number.

To enable BitBucket app to respond to each push to the PR, set (for example):

[bitbucket_app]
handle_push_trigger = true
push_commands = [
    "/describe",
    "/review",
]

Azure DevOps provider​

To use Azure DevOps provider use the following settings in configuration.toml:

[config]
git_provider="azure"

Azure DevOps provider supports PAT token or DefaultAzureCredential authentication. PAT is faster to create, but has build in expiration date, and will use the user identity for API calls. Using DefaultAzureCredential you can use managed identity or Service principle, which are more secure and will create separate ADO user identity (via AAD) to the agent.

If PAT was chosen, you can assign the value in .secrets.toml. If DefaultAzureCredential was chosen, you can assigned the additional env vars like AZURE_CLIENT_SECRET directly, or use managed identity/az cli (for local development) without any additional configuration. in any case, 'org' value must be assigned in .secrets.toml:

[azure_devops]
org = "https://dev.azure.com/YOUR_ORGANIZATION/"
# pat = "YOUR_PAT_TOKEN" needed only if using PAT for authentication

Azure DevOps Webhook​

To control which commands will run automatically when a new PR is opened, you can set the pr_commands parameter in the configuration file, similar to the GitHub App:

[azure_devops_server]
pr_commands = [
    "/describe",
    "/review",
    "/improve",
]

Gitea Webhook​

After setting up a Gitea webhook, to control which commands will run automatically when a new MR is opened, you can set the pr_commands parameter in the configuration file, similar to the GitHub App:

[gitea]
pr_commands = [
    "/describe",
    "/review",
    "/improve",
]