Locally

To run PR-Agent locally, you first need to acquire two keys:

Local execution has two distinct cases: use the hosted-provider examples below for an existing PR/MR URL, or use the Local Git Provider guide for branch comparisons without a hosted PR/MR.

An API key for your configured language model provider. For OpenAI, create one here.
A personal access token from your Git platform (GitHub, GitLab, BitBucket, Gitea) with repo scope. GitHub token, for example, can be issued from here

Using Docker image

A list of the relevant tools can be found in the tools guide.

To invoke a tool (for example review), you can run PR-Agent directly from the Docker image. Here's how:

For GitHub:

docker run --rm -it -e OPENAI__KEY=<your_openai_key> -e GITHUB__USER_TOKEN=<your_github_token> pragent/pr-agent:latest --pr_url <pr_url> review

If you are using GitHub enterprise server, you need to specify the custom url as variable. For example, if your GitHub server is at https://github.mycompany.com, add the following to the command:

-e GITHUB__BASE_URL=https://github.mycompany.com/api/v3

For GitLab:

docker run --rm -it -e OPENAI__KEY=<your key> -e CONFIG__GIT_PROVIDER=gitlab -e GITLAB__PERSONAL_ACCESS_TOKEN=<your token> pragent/pr-agent:latest --pr_url <pr_url> review

If you have a dedicated GitLab instance, you need to specify the custom url as variable:

-e GITLAB__URL=<your gitlab instance url>

For BitBucket:

docker run --rm -it -e CONFIG__GIT_PROVIDER=bitbucket -e OPENAI__KEY=$OPENAI_API_KEY -e BITBUCKET__BEARER_TOKEN=$BITBUCKET_BEARER_TOKEN pragent/pr-agent:latest --pr_url=<pr_url> review

For Gitea:

docker run --rm -it -e OPENAI__KEY=<your key> -e CONFIG__GIT_PROVIDER=gitea -e GITEA__PERSONAL_ACCESS_TOKEN=<your token> pragent/pr-agent:latest --pr_url <pr_url> review

If you have a dedicated Gitea instance, you need to specify the custom url as variable:

-e GITEA__URL=<your gitea instance url>

For other git providers, update CONFIG__GIT_PROVIDER accordingly and check the pr_agent/settings/.secrets_template.toml file for environment variables expected names and values.

Utilizing environment variables

It is also possible to provide or override the configuration by setting the corresponding environment variables. You can define the corresponding environment variables by following this convention: <TABLE>__<KEY>=<VALUE> or <TABLE>.<KEY>=<VALUE>. The <TABLE> refers to a table/section in a configuration file and <KEY>=<VALUE> refers to the key/value pair of a setting in the configuration file.

For example, suppose you want to run pr_agent that connects to a self-hosted GitLab instance similar to an example above. You can define the environment variables in a plain text file named .env with the following content:

CONFIG__GIT_PROVIDER="gitlab"
GITLAB__URL="<your url>"
GITLAB__PERSONAL_ACCESS_TOKEN="<your token>"
OPENAI__KEY="<your key>"

Then, you can run pr_agent using Docker with the following command:

docker run --rm -it --env-file .env pragent/pr-agent:latest <tool> <tool parameter>

I get an error when running the Docker image. What should I do?

If you encounter an error when running the Docker image, it is almost always due to a misconfiguration of api keys or tokens.

Note that litellm, which is used by pr-agent, sometimes returns non-informative error messages such as APIError: OpenAIException - Connection error. Carefully check the api keys and tokens you provided and make sure they are correct. Adjustments may be needed depending on your llm provider.

For example, for Azure OpenAI, additional keys are needed. Same goes for other providers, make sure to check the documentation

Using pip package

Install the package:

pip install "pr-agent[github]"

Git provider SDKs are optional extras, so install the one for your provider: github, gitlab, bitbucket (Bitbucket Cloud, Bitbucket Server and Jira), azure, codecommit or gitea. google adds Vertex AI, mosaico adds the Mosaico server, and pr-agent[all] installs every integration.

Then run the relevant tool with the script below.
Make sure to fill in the required parameters (user_token, openai_key, pr_url, command):

from pr_agent import cli
from pr_agent.config_loader import get_settings

def main():
    # Fill in the following values
    provider = "github" # github/gitlab/bitbucket/azure_devops
    user_token = "..."  #  user token
    openai_key = "..."  # OpenAI key
    pr_url = "..."      # PR URL, for example 'https://github.com/the-pr-agent/pr-agent/pull/809'
    command = "/review" # Command to run (e.g. '/review', '/describe', '/ask="What is the purpose of this PR?"', ...)

    # Setting the configurations
    get_settings().set("CONFIG.git_provider", provider)
    get_settings().set("openai.key", openai_key)
    get_settings().set("github.user_token", user_token)

    # Run the command. Feedback will appear in GitHub PR comments
    return cli.run_command(pr_url, command)


if __name__ == '__main__':
    raise SystemExit(main())

With config.propagate_tool_errors enabled, forwarding the return value through SystemExit makes this script exit with status 1 after a propagated tool error. The default remains status 0.

The Python helper accepts quoted arguments, for example cli.run_command(pr_url, "/review --pr_reviewer.extra_instructions='be concise please'"). It uses the same quoting rules as configured automation commands: explicitly quoted setting values stay strings, and unquoted values retain their normal types. For questions containing apostrophes, use double quotes around the question, such as command = '/ask "What\'s changed?"'. This does not change how interactive PR comments are parsed.

Run from source

Clone this repository:

git clone https://github.com/the-pr-agent/pr-agent.git

Navigate to the /pr-agent folder and install dependencies with uv (creates a .venv from uv.lock):

uv sync

Note: If you get an error related to Rust in the dependency installation then make sure Rust is installed and in your PATH, instructions: https://rustup.rs

Copy the secrets template file and fill in your OpenAI key and your GitHub user token:

cp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml
chmod 600 pr_agent/settings/.secrets.toml
# Edit .secrets.toml file

Run the cli.py script:

uv run pr-agent --pr_url <pr_url> review
uv run pr-agent --pr_url <pr_url> ask "<your question>"
uv run pr-agent --pr_url <pr_url> describe
uv run pr-agent --pr_url <pr_url> improve
uv run pr-agent --pr_url <pr_url> add_docs
uv run pr-agent --pr_url <pr_url> generate_labels
uv run pr-agent --issue_url <issue_url> similar_issue
...

Note: the similar_issue tool needs extra dependencies that a bare uv sync does not install. Install them with uv sync --group similar-issue before running it.

[Optional] Add the pr_agent folder to your PYTHONPATH

export PYTHONPATH=$PYTHONPATH:<PATH to pr_agent folder>

Using Docker image​

Utilizing environment variables​

I get an error when running the Docker image. What should I do?​

Using pip package​

Run from source​

Using Docker image

Utilizing environment variables

I get an error when running the Docker image. What should I do?

Using pip package

Run from source