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 commands 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.

  2. 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 commands.

  3. 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, bitbucket_server, azure, codecommit, local, gerrit, gitea, and plain-diff.

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

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

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

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

CLI Health Check​

For a quick preflight that needs no token and no PR, run:

pr-agent doctor

It checks that config.model is set and that a completion against the configured model succeeds. Where required, it also checks for a real static API key. Azure AD, Bedrock IAM, Anthropic bearer tokens without captured API keys, keyless local endpoints, and custom endpoints defer authentication validation to the completion. For Watsonx, an API URL alone is insufficient: configure an API key, WATSONX_TOKEN, WATSONX_ZENAPIKEY, or an explicit Authorization header. Watsonx checks these credentials in header, bearer-token, Zen-key, then API-key order; placeholder credentials are not accepted. An Anthropic bearer token must also be non-placeholder. Keyless local providers and eligible OpenRouter gateway fallbacks defer placeholder-key validation to the model completion. Native providers that require a real key still reject placeholders. The exit code is 0 only when every check passes, so CI setups can gate on it. It ships with the package, unlike the fuller health check below, which exercises real commands on a real PR.

In Docker, run it from the CLI image (pragent/pr-agent:<version> or pragent/pr-agent:latest), whose entrypoint takes the command directly:

docker run --rm --env-file .env pragent/pr-agent:latest doctor

Service images such as pragent/pr-agent:<version>-github_app are intended for long-running servers and do not install the pr-agent console script. To run the check from one of them, override the command with python -m pr_agent.cli doctor.

When host-configured push_outputs is enabled, doctor adds a fourth check for the selected output destinations: registered channel names, a nonempty file path, HTTPS scheme and hostname for webhook/Slack URLs, and a nonempty Telegram token string and a chat ID that is a nonempty string or nonzero integer. An omitted file path uses the normal default. Distinct custom sink names receive recognition-only checks; their private settings are not validated.

push_outputs.enable accepts booleans or strings. String values false, 0, no, off, and the empty string disable it (ignoring case and surrounding whitespace); other strings enable it. Disabled output keeps the existing three checks and output unchanged.

The output check reads the active host settings but does not construct sinks, send output, access files, or contact destinations. It checks only the fields listed above; URL ports and other URL components are not validated. Success does not establish delivery, file writability, destination reachability, authentication, or permissions. The existing model ping still contacts the configured model before the output check. No PR URL or git-provider setup is needed.

To verify that PR-Agent has been configured correctly end to end, you can also 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 commands by comments on a PR. Commands for invoking the different commands via comments:

  • Review: /review
  • Describe: /describe
  • Improve: /improve (or /improve_code for bitbucket, since /improve is sometimes reserved). Runs /review; a list that names both runs one review.
  • 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 command 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 commands (like describe and review) 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 commands when a new PR is opened​

The github_app section defines GitHub app specific configurations.

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

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

This means that when a new PR is opened/reopened or marked as ready for review, PR-Agent will run the describe and review commands (improve runs review, so a list naming both runs one review).

Draft PRs:

By default, the GitHub App does not consider draft PRs for automatic commands. You can change this by setting the feedback_on_draft_pr parameter to true in the configuration file. The GitHub Action applies the same setting to pull_request_review events. The GitLab webhook also skips draft MRs by default, while Gitea, Azure DevOps, and Bitbucket do not apply a draft check. 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 command parameters:

You can override the default command 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 command (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 command settings only for newly opened PRs, use:

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

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

In addition to running automatic commands 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 commands 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 commands, with the specified parameters.

The push_trigger_pending_tasks_backlog and push_trigger_pending_tasks_ttl settings apply to the GitHub App only; the GitLab, Gitea, and Bitbucket servers use fixed values.

GitHub Action​

GitHub Action is a different way to trigger PR-Agent commands, 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 commands that run when a new PR is opened. /improve runs /review, so the review runs when either auto_review or auto_improve is enabled, and only once. If not set, describe and review 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 commands 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 commands 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 only merges the base branch into the PR, as "Update branch" does, avoiding duplicate reviews on those clicks. The pushed head must be a merge commit whose first parent is the previous head and whose second parent is on the base branch. Any other push is processed, including one that adds commits before the merge or merges another branch.

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_command_errors (default true) makes the Action exit non-zero when a command recorded a swallowed failure (the default propagate_command_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 command failures. Set it in the workflow configuration; comment arguments such as /review --github_action_config.fail_on_command_errors=false are rejected.

Automatic commands after a submitted GitHub review​

The GitHub App can run configured commands 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 = [
"/review",
]

The event must be submitted; edited or dismissed reviews do not trigger commands. 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: '["/review"]'

Output and Check Run settings​

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 command output (review, describe) 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 command 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 command'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 command.

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",
]

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 commands 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 or explicitly re-requested 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 commands that will be run automatically for these events.

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

The commands run when the bot is newly added to the reviewer list or its review is explicitly re-requested, so re-saving an MR without either change does not run them again. Review re-request webhook events require GitLab 18.6 or later. 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 command, 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 commands​

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 --pr_code_suggestions.committable_code_suggestions=true",
]

Since this platform only supports inline code suggestions, /review posts each finding inline and limits their number with pr_reviewer.num_max_findings (6 by default).

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",
]

BitBucket Server webhook​

For a BitBucket Server webhook deployment, new commits pushed to an open PR (the pr:from_ref_updated and repo:refs_changed events) run no commands by default. To run commands on each push, set (for example):

[bitbucket_server]
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",
]

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",
]