PR-Agent offers extensive pull request functionalities across various git providers.
\ud83d\udc8e marks a feature available only in PR-Agent Pro
GitHub Gitlab Bitbucket TOOLS Review \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Incremental \u2714\ufe0f SOC2 Compliance \ud83d\udc8e \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Ask \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Describe \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Inline file summary \ud83d\udc8e \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Improve \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f \u2b91 Extended \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Custom Suggestions \ud83d\udc8e \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Reflect and Review \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Update CHANGELOG.md \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Find Similar Issue \u2714\ufe0f Add PR Documentation \ud83d\udc8e \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Generate Custom Labels \ud83d\udc8e \u2714\ufe0f \u2714\ufe0f Analyze PR Components \ud83d\udc8e \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f USAGE CLI \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f App / webhook \u2714\ufe0f \u2714\ufe0f Tagging bot \u2714\ufe0f Actions \u2714\ufe0f CORE PR compression \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Repo language prioritization \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Adaptive and token-aware file patch fitting \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Multiple models support \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Incremental PR review \u2714\ufe0f Static code analysis \ud83d\udc8e \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f Global configuration \ud83d\udc8e \u2714\ufe0f \u2714\ufe0f \u2714\ufe0f"},{"location":"core-abilities/","title":"Core Abilities","text":"Do we want to add something here?
"},{"location":"core-abilities/pr-compression/","title":"PR Compression Strategy","text":"There are two scenarios:
For both scenarios, we first use the following strategy
"},{"location":"core-abilities/pr-compression/#repo-language-prioritization-strategy","title":"Repo language prioritization strategy","text":"We prioritize the languages of the repo based on the following criteria:
[[file.py, file2.py],[file3.js, file4.jsx],[readme.md]]In this case, we can fit the entire PR in a single prompt: 1. Exclude binary files and non code files (e.g. images, pdfs, etc) 2. We Expand the surrounding context of each patch to 3 lines above and below the patch
"},{"location":"core-abilities/pr-compression/#large-pr","title":"Large PR","text":""},{"location":"core-abilities/pr-compression/#motivation","title":"Motivation","text":"Pull Requests can be very long and contain a lot of information with varying degree of relevance to the pr-agent. We want to be able to pack as much information as possible in a single LMM prompt, while keeping the information relevant to the pr-agent.
"},{"location":"core-abilities/pr-compression/#compression-strategy","title":"Compression strategy","text":"We prioritize additions over deletions: - Combine all deleted files into a single list (deleted files) - File patches are a list of hunks, remove all hunks of type deletion-only from the hunks in the file patch
We use tiktoken to tokenize the patches after the modifications described above, and we use the following strategy to fit the patches into the prompt:
[[file2.py, file.py],[file4.jsx, file3.js],[readme.md]]other modified files to the prompt until the prompt reaches the max token length (hard stop), skip the rest of the patches.deleted files to the prompt until the prompt reaches the max token length (hard stop), skip the rest of the patches.If you choose to host you own PR-Agent, you first need to acquire two tokens:
There are several ways to use self-hosted PR-Agent:
Note that PR-Agent Pro \ud83d\udc8e, an app for GitHub\\GitLab\\BitBucket hosted by CodiumAI, is also available. With PR-Agent Pro Installation is as simple as signing up and adding the PR-Agent app to your relevant repo.
"},{"location":"installation/azure/","title":"Azure","text":""},{"location":"installation/azure/#azure-devops-provider","title":"Azure DevOps provider","text":"To use Azure DevOps provider use the following settings in configuration.toml:
[config]\ngit_provider=\"azure\"\nuse_repo_settings_file=false\nAzure DevOps provider supports PAT token or DefaultAzureCredential authentication. PAT is faster to create, but has build in experation 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 seperate ADO user identity (via AAD) to the agent.
If PAT was choosen, you can assign the value in .secrets.toml. If DefaultAzureCredential was choosen, you can assigned the additional env vars like AZURE_CLIENT_SECRET directly, or use managed identity/az cli (for local develpment) without any additional configuration. in any case, 'org' value must be assigned in .secrets.toml:
[azure_devops]\norg = \"https://dev.azure.com/YOUR_ORGANIZATION/\"\n# pat = \"YOUR_PAT_TOKEN\" needed only if using PAT for authentication\nTo trigger from an Azure webhook, you need to manually add a webhook. Use the \"Pull request created\" type to trigger a review, or \"Pull request commented on\" to trigger any supported comment with / comment on the relevant PR. Note that for the \"Pull request commented on\" trigger, only API v2.0 is supported.
For webhook security, create a sporadic username/password pair and configure the webhook username and password on both the server and Azure DevOps webhook. These will be sent as basic Auth data by the webhook with each request:
[azure_devops_server]\nwebhook_username = \"<basic auth user>\"\nwebhook_password = \"<basic auth password>\"\nEnsure that the webhook endpoint is only accessible over HTTPS to mitigate the risk of credential interception when using basic authentication.
"},{"location":"installation/bitbucket/","title":"BitBucket","text":""},{"location":"installation/bitbucket/#run-as-a-bitbucket-pipeline","title":"Run as a Bitbucket Pipeline","text":"You can use the Bitbucket Pipeline system to run PR-Agent on every pull request open or update.
pipelines:\n pull-requests:\n '**':\n - step:\n name: PR Agent Review\n image: python:3.10\n services:\n - docker\n script:\n - docker run -e CONFIG.GIT_PROVIDER=bitbucket -e OPENAI.KEY=$OPENAI_API_KEY -e BITBUCKET.BEARER_TOKEN=$BITBUCKET_BEARER_TOKEN codiumai/pr-agent:latest --pr_url=https://bitbucket.org/$BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG/pull-requests/$BITBUCKET_PR_ID review\n<your key> BITBUCKET_BEARER_TOKEN: <your token>You can get a Bitbucket token for your repository by following Repository Settings -> Security -> Access Tokens.
Note that comments on a PR are not supported in Bitbucket Pipeline.
"},{"location":"installation/bitbucket/#run-using-codiumai-hosted-bitbucket-app","title":"Run using CodiumAI-hosted Bitbucket app","text":"Please contact support@codium.ai or visit CodiumAI pricing page if you're interested in a hosted BitBucket app solution that provides full functionality including PR reviews and comment handling. It's based on the bitbucket_app.py implementation.
"},{"location":"installation/bitbucket/#bitbucket-server-and-data-center","title":"Bitbucket Server and Data Center","text":"Login into your on-prem instance of Bitbucket with your service account username and password. Navigate to Manage account, HTTP Access tokens, Create Token. Generate the token and add it to .secret.toml under bitbucket_server section
[bitbucket_server]\nbearer_token = \"<your key>\"\nModify configuration.toml:
git_provider=\"bitbucket_server\"\nand pass the Pull request URL:
python cli.py --pr_url https://git.onpreminstanceofbitbucket.com/projects/PROJECT/repos/REPO/pull-requests/1 review\nTo run pr-agent as webhook, build the docker image:
docker build . -t codiumai/pr-agent:bitbucket_server_webhook --target bitbucket_server_webhook -f docker/Dockerfile\ndocker push codiumai/pr-agent:bitbucket_server_webhook # Push to your Docker repository\nNavigate to Projects or Repositories, Settings, Webhooks, Create Webhook. Fill the name and URL, Authentication None select the Pull Request Opened checkbox to receive that event as webhook.
The URL should end with /webhook, for example: https://domain.com/webhook
You can use our pre-built Github Action Docker image to run PR-Agent as a Github Action.
.github/workflows/pr_agent.yml:on:\n pull_request:\n issue_comment:\njobs:\n pr_agent_job:\n runs-on: ubuntu-latest\n permissions:\n issues: write\n pull-requests: write\n contents: write\n name: Run pr agent on every pull request, respond to user comments\n steps:\n - name: PR Agent action step\n id: pragent\n uses: Codium-ai/pr-agent@main\n env:\n OPENAI_KEY: ${{ secrets.OPENAI_KEY }}\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\non:\n pull_request:\n issue_comment:\n\njobs:\n pr_agent_job:\n runs-on: ubuntu-latest\n permissions:\n issues: write\n pull-requests: write\n contents: write\n name: Run pr agent on every pull request, respond to user comments\n steps:\n - name: PR Agent action step\n id: pragent\n uses: Codium-ai/pr-agent@v0.7\n env:\n OPENAI_KEY: ${{ secrets.OPENAI_KEY }}\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\nSettings > Secrets and variables > Actions > New repository secret > Add secret: Name = OPENAI_KEY\nSecret = <your key>\nThe GITHUB_TOKEN secret is automatically created by GitHub.
Merge this change to your main branch. When you open your next PR, you should see a comment from github-actions bot with a review of your PR, and instructions on how to use the rest of the tools.
You may configure PR-Agent by adding environment variables under the env section corresponding to any configurable property in the configuration file. Some examples:
env:\n # ... previous environment values\n OPENAI.ORG: \"<Your organization name under your OpenAI account>\"\n PR_REVIEWER.REQUIRE_TESTS_REVIEW: \"false\" # Disable tests review\n PR_CODE_SUGGESTIONS.NUM_CODE_SUGGESTIONS: 6 # Increase number of code suggestions\nRequest reviews by tagging your GitHub user on a PR
Follow steps 1-3 of the GitHub Action setup.
Run the following command to start the server:
python pr_agent/servers/github_polling.py\nAllowing you to automate the review process on your private or public repositories.
Create a GitHub App from the Github Developer Portal.
Set the following permissions:
Set the following events:
Generate a random secret for your app, and save it for later. For example, you can use:
WEBHOOK_SECRET=$(python -c \"import secrets; print(secrets.token_hex(10))\")\nAcquire the following pieces of information from your app's settings page:
App private key (click \"Generate a private key\" and save the file)
App ID
Clone this repository:
git clone https://github.com/Codium-ai/pr-agent.git\ncp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml\n# Edit .secrets.toml file\nThe .secrets.toml file is not copied to the Docker image by default, and is only used for local development. If you want to use the .secrets.toml file in your Docker image, you can add remove it from the .dockerignore file. In most production environments, you would inject the secrets file as environment variables or as mounted volumes. For example, in order to inject a secrets file as a volume in a Kubernetes environment you can update your pod spec to include the following, assuming you have a secret named pr-agent-settings with a key named .secrets.toml:
volumes:\n - name: settings-volume\n secret:\n secretName: pr-agent-settings\n// ...\n containers:\n// ...\n volumeMounts:\n - mountPath: /app/pr_agent/settings_prod\n name: settings-volume\nAnother option is to set the secrets as environment variables in your deployment environment, for example OPENAI.KEY and GITHUB.USER_TOKEN.
docker build . -t codiumai/pr-agent:github_app --target github_app -f docker/Dockerfile\ndocker push codiumai/pr-agent:github_app # Push to your Docker repository\nHost the app using a server, serverless function, or container environment. Alternatively, for development and debugging, you may use tools like smee.io to forward webhooks to your local machine. You can check Deploy as a Lambda Function
Go back to your app's settings, and set the following:
Webhook URL: The URL of your app's server or the URL of the smee.io channel.
Webhook secret: The secret you generated earlier.
Install the app by navigating to the \"Install App\" tab and selecting your desired repositories.
Note: When running PR-Agent from GitHub App, the default configuration file (configuration.toml) will be loaded. However, you can override the default tool parameters by uploading a local configuration file .pr_agent.toml For more information please check out the USAGE GUIDE
shell docker buildx build --platform=linux/amd64 . -t codiumai/pr-agent:serverless -f docker/Dockerfile.lambdadocker tag codiumai/pr-agent:serverless <AWS_ACCOUNT>.dkr.ecr.<AWS_REGION>.amazonaws.com/codiumai/pr-agent:serverless\ndocker push <AWS_ACCOUNT>.dkr.ecr.<AWS_REGION>.amazonaws.com/codiumai/pr-agent:serverless\nAZURE_DEVOPS_CACHE_DIR to a writable location such as /tmp. (see link)https://<LAMBDA_FUNCTION_URL>/api/v1/github_webhooksNot all features have been added to CodeCommit yet. As of right now, CodeCommit has been implemented to run the pr-agent CLI on the command line, using AWS credentials stored in environment variables. (More features will be added in the future.) The following is a set of instructions to have pr-agent do a review of your CodeCommit pull request from the command line:
git_provider value to codecommit in the pr_agent/settings/configuration.toml settings filePYTHONPATH to include your pr-agent project directoryPYTHONPATH=\"/PATH/TO/PROJECTS/pr-agent to your .env filePYTHONPATH and run the CLI in one command, for example:PYTHONPATH=\"/PATH/TO/PROJECTS/pr-agent python pr_agent/cli.py [--ARGS]Example IAM permissions to that user to allow access to CodeCommit:
\"Resource\": \"*\" with your list of repos, to limit access to only those repos{\n \"Version\": \"2012-10-17\",\n \"Statement\": [\n {\n \"Effect\": \"Allow\",\n \"Action\": [\n \"codecommit:BatchDescribe*\",\n \"codecommit:BatchGet*\",\n \"codecommit:Describe*\",\n \"codecommit:EvaluatePullRequestApprovalRules\",\n \"codecommit:Get*\",\n \"codecommit:List*\",\n \"codecommit:PostComment*\",\n \"codecommit:PutCommentReaction\",\n \"codecommit:UpdatePullRequestDescription\",\n \"codecommit:UpdatePullRequestTitle\"\n ],\n \"Resource\": \"*\"\n }\n ]\n}\nExample setting the Access Key and Secret using environment variables
export AWS_ACCESS_KEY_ID=\"XXXXXXXXXXXXXXXX\"\nexport AWS_SECRET_ACCESS_KEY=\"XXXXXXXXXXXXXXXX\"\nexport AWS_DEFAULT_REGION=\"us-east-1\"\nAfter you set up AWS CodeCommit using the instructions above, here is an example CLI run that tells pr-agent to review a given pull request. (Replace your specific PYTHONPATH and PR URL in the example)
PYTHONPATH=\"/PATH/TO/PROJECTS/pr-agent\" python pr_agent/cli.py \\\n --pr_url https://us-east-1.console.aws.amazon.com/codesuite/codecommit/repositories/MY_REPO_NAME/pull-requests/321 \\\n review\nWEBHOOK_SECRET=$(python -c \"import secrets; print(secrets.token_hex(10))\")\nA list of the relevant tools can be found in the tools guide.
To invoke a tool (for example review), you can run directly from the Docker image. Here's how:
For GitHub:
docker run --rm -it -e OPENAI.KEY=<your key> -e GITHUB.USER_TOKEN=<your token> codiumai/pr-agent:latest --pr_url <pr_url> review\nFor GitLab:
docker run --rm -it -e OPENAI.KEY=<your key> -e CONFIG.GIT_PROVIDER=gitlab -e GITLAB.PERSONAL_ACCESS_TOKEN=<your token> codiumai/pr-agent:latest --pr_url <pr_url> review\nNote: If you have a dedicated GitLab instance, you need to specify the custom url as variable:
docker run --rm -it -e OPENAI.KEY=<your key> -e CONFIG.GIT_PROVIDER=gitlab -e GITLAB.PERSONAL_ACCESS_TOKEN=<your token> -e GITLAB.URL=<your gitlab instance url> codiumai/pr-agent:latest --pr_url <pr_url> review\ndocker run --rm -it -e CONFIG.GIT_PROVIDER=bitbucket -e OPENAI.KEY=$OPENAI_API_KEY -e BITBUCKET.BEARER_TOKEN=$BITBUCKET_BEARER_TOKEN codiumai/pr-agent:latest --pr_url=<pr_url> review\nFor other git providers, update CONFIG.GIT_PROVIDER accordingly, and check the pr_agent/settings/.secrets_template.toml file for the environment variables expected names and values.
If you want to ensure you're running a specific version of the Docker image, consider using the image's digest:
docker run --rm -it -e OPENAI.KEY=<your key> -e GITHUB.USER_TOKEN=<your token> codiumai/pr-agent@sha256:71b5ee15df59c745d352d84752d01561ba64b6d51327f97d46152f0c58a5f678 --pr_url <pr_url> review\nOr you can run a specific released versions of pr-agent, for example:
codiumai/pr-agent@v0.9\ngit clone https://github.com/Codium-ai/pr-agent.git\n/pr-agent folder and install the requirements in your favorite virtual environment:pip install -e .\nNote: 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
cp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml\nchmod 600 pr_agent/settings/.secrets.toml\n# Edit .secrets.toml file\npython3 -m pr_agent.cli --pr_url <pr_url> review\npython3 -m pr_agent.cli --pr_url <pr_url> ask <your question>\npython3 -m pr_agent.cli --pr_url <pr_url> describe\npython3 -m pr_agent.cli --pr_url <pr_url> improve\npython3 -m pr_agent.cli --pr_url <pr_url> add_docs\npython3 -m pr_agent.cli --pr_url <pr_url> generate_labels\npython3 -m pr_agent.cli --issue_url <issue_url> similar_issue\n...\n[Optional]\u00a0Add the pr_agent folder to your PYTHONPATH
export PYTHONPATH=$PYTHONPATH:<PATH to pr_agent folder>\nHere is a list of PR-Agent tools, each with a dedicated page that explains how to use it:
Tool Description PR Description (/describe) Automatically generating PR description - title, type, summary, code walkthrough and labels PR Review (/review) Adjustable feedback about the PR, possible issues, security concerns, review effort and more Code Suggestions (/improve) Code suggestions for improving the PR Question Answering (/ask ...) Answering free-text questions about the PR, or on specific code lines Update Changelog (/update_changelog) Automatically updating the CHANGELOG.md file with the PR changes Find Similar Issue (/similar_issue) Automatically retrieves and presents similar issues \ud83d\udc8e Add Documentation (/add_docs) Generates documentation to methods/functions/classes that changed in the PR \ud83d\udc8e Generate Custom Labels (/generate_labels) Generates custom labels for the PR, based on specific guidelines defined by the user \ud83d\udc8e Analyze (/analyze) Identify code components that changed in the PR, and enables to interactively generate tests, docs, and code suggestions for each component \ud83d\udc8e Custom Suggestions (/custom_suggestions) Automatically generates custom suggestions for improving the PR code, based on specific guidelines defined by the user \ud83d\udc8e Generate Tests (/test component_name) Automatically generates unit tests for a selected component, based on the PR code changes \ud83d\udc8e CI Feedback (/checks ci_job) Automatically generates feedback and analysis for a failed CI job Note that the tools marked with \ud83d\udc8e are available only for PR-Agent Pro users.
"},{"location":"tools/analyze/","title":"\ud83d\udc8e Analyze","text":""},{"location":"tools/analyze/#overview","title":"Overview","text":"The analyze tool combines static code analysis with LLM capabilities to provide a comprehensive analysis of the PR code changes.
The tool scans the PR code changes, find the code components (methods, functions, classes) that changed, and summarizes the changes in each component.
It can be invoked manually by commenting on any PR:
/analyze\nAn example result:
Notes
The ask tool answers questions about the PR, based on the PR code changes. Make sure to be specific and clear in your questions. It can be invoked manually by commenting on any PR:
/ask \"...\"\nYou can run /ask on specific lines of code in the PR from the PR's diff view. The tool will answer questions based on the code changes in the selected lines. - Click on the '+' sign next to the line number to select the line. - To select multiple lines, click on the '+' sign of the first line and then hold and drag to select the rest of the lines. - write /ask \"...\" in the comment box and press Add single comment button.
Note that the tool does not have \"memory\" of previous questions, and answers each question independently.
"},{"location":"tools/ci_feedback/","title":"\ud83d\udc8e CI Feedback","text":""},{"location":"tools/ci_feedback/#overview","title":"Overview","text":"The CI feedback tool (/checks) automatically triggers when a PR has a failed check. The tool analyzes the failed checks and provides several feedbacks:
\u2192
In addition to being automatically triggered, the tool can also be invoked manually by commenting on a PR:
/checks \"https://github.com/{repo_name}/actions/runs/{run_number}/job/{job_number}\"\n{repo_name} is the name of the repository, {run_number} is the run number of the failed check, and {job_number} is the job number of the failed check."},{"location":"tools/ci_feedback/#configuration-options","title":"Configuration options","text":"enable_auto_checks_feedback - if set to true, the tool will automatically provide feedback when a check is failed. Default is true.excluded_checks_list - a list of checks to exclude from the feedback, for example: [\"check1\", \"check2\"]. Default is an empty list.persistent_comment - if set to true, the tool will overwrite a previous checks comment with the new feedback. Default is true.enable_help_text=true - if set to true, the tool will provide a help message when a user comments \"/checks\" on a PR. Default is true.The generate_labels tool scans the PR code changes, and given a list of labels and their descriptions, it automatically suggests labels that match the PR code changes.
It can be invoked manually by commenting on any PR:
/generate_labels\nIf we wish to add detect changes to SQL queries in a given PR, we can add the following custom label along with its description:
When running the generate_labels tool on a PR that includes changes in SQL queries, it will automatically suggest the custom label:
Note that in addition to the dedicated tool generate_labels, the custom labels will also be used by the describe tool.
There are 3 ways to enable custom labels:
"},{"location":"tools/custom_labels/#1-cli-local-configuration-file","title":"1. CLI (local configuration file)","text":"When working from CLI, you need to apply the configuration changes to the custom_labels file:
"},{"location":"tools/custom_labels/#2-repo-configuration-file","title":"2. Repo configuration file","text":"To enable custom labels, you need to apply the configuration changes to the local .pr_agent.toml file in you repository.
This feature is available only in PR-Agent Pro
https://github.com/{owner}/{repo}/labels, or click on the \"Labels\" tab in the issues or PRs page.https://gitlab.com/{owner}/{repo}/-/labels, or click on \"Manage\" -> \"Labels\" on the left menu.b. Add/edit the custom labels. It should be formatted as follows: * Label name: The name of the custom label. * Description: Start the description of with prefix pr_agent:, for example: pr_agent: Description of when AI should suggest this label. The description should be comprehensive and detailed, indicating when to add the desired label.
c. Now the custom labels will be included in the generate_labels tool.
This feature is supported in GitHub and GitLab.
"},{"location":"tools/custom_labels/#configuration-options","title":"Configuration options","text":"enable_custom_labels to True: This will turn off the default labels and enable the custom labels provided in the custom_labels.toml file.[config]\nenable_custom_labels=true\n\n[custom_labels.\"Custom Label Name\"]\ndescription = \"Description of when AI should suggest this label\"\n\n[custom_labels.\"Custom Label 2\"]\ndescription = \"Description of when AI should suggest this label 2\"\nThe custom_suggestions tool scans the PR code changes, and automatically generates custom suggestions for improving the PR code. It shares similarities with the improve tool, but with one main difference: the custom_suggestions tool will only propose suggestions that follow specific guidelines defined by the prompt in: pr_custom_suggestions.prompt configuration.
The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on a PR.
When commenting, use the following template:
/custom_suggestions --pr_custom_suggestions.prompt=\"The suggestions should focus only on the following:\\n-...\\n-...\\n-...\"\nWith a configuration file, use the following template:
[pr_custom_suggestions]\nprompt=\"\"\"\\\nThe suggestions should focus only on the following:\n-...\n-...\n-...\n\"\"\"\nDon't forget - with this tool, you are the prompter. Be specific, clear, and concise in the instructions. Specify relevant aspects that you want the model to focus on. \\ You might benefit from several trial-and-error iterations, until you get the correct prompt for your use case.
"},{"location":"tools/custom_suggestions/#example-usage","title":"Example usage","text":"Here is an example of a possible prompt:
[pr_custom_suggestions]\nprompt=\"\"\"\\\nThe suggestions should focus only on the following:\n- look for edge cases when implementing a new function\n- make sure every variable has a meaningful name\n- make sure the code is efficient\n\"\"\"\nThe instructions above are just an example. We want to emphasize that the prompt should be specific and clear, and be tailored to the needs of your project.
Results obtained with the prompt above:
"},{"location":"tools/custom_suggestions/#configuration-options","title":"Configuration options","text":"prompt: the prompt for the tool. It should be a multi-line string.
num_code_suggestions: number of code suggestions provided by the 'custom_suggestions' tool. Default is 4.
enable_help_text: if set to true, the tool will display a help text in the comment. Default is true.
The describe tool scans the PR code changes, and generates a description for the PR - title, type, summary, walkthrough and labels.
The tool can be triggered automatically every time a new PR is opened, or it can be invoked manually by commenting on any PR:
/describe\nTo edit configurations related to the describe tool (pr_description section), use the following template:
/describe --pr_description.some_config1=... --pr_description.some_config2=...\npublish_labels: if set to true, the tool will publish the labels to the PR. Default is true.
publish_description_as_comment: if set to true, the tool will publish the description as a comment to the PR. If false, it will overwrite the origianl description. Default is false.
add_original_user_description: if set to true, the tool will add the original user description to the generated description. Default is true.
keep_original_user_title: if set to true, the tool will keep the original PR title, and won't change it. Default is true.
extra_instructions: Optional extra instructions to the tool. For example: \"focus on the changes in the file X. Ignore change in ...\".
To enable custom labels, apply the configuration changes described here
enable_pr_type: if set to false, it will not show the PR type as a text value in the description content. Default is true.
final_update_message: if set to true, it will add a comment message PR Description updated to latest commit... after finishing calling /describe. Default is true.
enable_semantic_files_types: if set to true, \"Changes walkthrough\" section will be generated. Default is true.
collapsible_file_list: if set to true, the file list in the \"Changes walkthrough\" section will be collapsible. If set to \"adaptive\", the file list will be collapsible only if there are more than 8 files. Default is \"adaptive\".This feature is available only in PR-Agent Pro
This feature will enable you to quickly understand the changes in each file while reviewing the code changes (diff view).
To add the walkthrough table to the \"Files changed\" tab, you can click on the checkbox that appears PR Description status message below the main PR Description:
If you prefer to have the file summaries appear in the \"Files changed\" tab on every PR, change the pr_description.inline_file_summary parameter in the configuration file, possible values are:
'table': File changes walkthrough table will be displayed on the top of the \"Files changed\" tab, in addition to the \"Conversation\" tab.
true: A collapsable file comment with changes title and a changes summary for each file in the PR.
false (default): File changes walkthrough will be added only to the \"Conversation\" tab.
Note that this feature is currently available only for GitHub.
"},{"location":"tools/describe/#handle-custom-labels-from-the-repos-labels-page","title":"Handle custom labels from the Repo's labels page \ud83d\udc8e","text":"This feature is available only in PR-Agent Pro
You can control the custom labels that will be suggested by the describe tool, from the repo's labels page:
https://github.com/{owner}/{repo}/labels (or click on the \"Labels\" tab in the issues or PRs page)https://gitlab.com/{owner}/{repo}/-/labels (or click on \"Manage\" -> \"Labels\" on the left menu)Now add/edit the custom labels. they should be formatted as follows: * Label name: The name of the custom label. * Description: Start the description of with prefix pr_agent:, for example: pr_agent: Description of when AI should suggest this label.
The description should be comprehensive and detailed, indicating when to add the desired label. For example:
"},{"location":"tools/describe/#markers-template","title":"Markers template","text":"To enable markers, set pr_description.use_description_markers=true. Markers enable to easily integrate user's content and auto-generated content, with a template-like mechanism.
For example, if the PR original description was:
User content...\n\n## PR Type:\npr_agent:type\n\n## PR Description:\npr_agent:summary\n\n## PR Walkthrough:\npr_agent:walkthrough\npr_agent:type will be replaced with the PR type, pr_agent:summary will be replaced with the PR summary, and pr_agent:walkthrough will be replaced with the PR walkthrough. \u2192
"},{"location":"tools/describe/#configuration-params","title":"Configuration params:","text":"use_description_markers: if set to true, the tool will use markers template. It replaces every marker of the form pr_agent:marker_name with the relevant content. Default is false.include_generated_by_header: if set to true, the tool will add a dedicated header: 'Generated by PR Agent at ...' to any automatic content. Default is true.pr_commands = [\"/describe --pr_description.add_original_user_description=true\" \n \"--pr_description.keep_original_user_title=true\", ...]\ndescribe tool will run automatically on every PR, will keep the original title, and will add the original user description above the generated description. This default settings aim to strike a good balance between automation and control: If you want more automation, just give the PR a title, and the tool will auto-write a full description; If you want more control, you can add a detailed description, and the tool will add the complementary description below it.pr_commands = [\"/describe --pr_description.add_original_user_description=false\" \n \"--pr_description.keep_original_user_title=true\", ...]\npr_commands = [\"/describe --pr_description.use_description_markers=true\", ...]\npr_agent:marker_name in the PR description with the relevant content, where marker_name is one of the following:type: the PR type.summary: the PR summary.walkthrough: the PR walkthrough.Note that when markers are enabled, if the original PR description does not contain any markers, the tool will not alter the description at all.
"},{"location":"tools/describe/#custom-labels","title":"Custom labels","text":"The default labels of the describe tool are quite generic, since they are meant to be used in any repo: [Bug fix, Tests, Enhancement, Documentation, Other].
If you specify custom labels in the repo's labels page, you can get tailored labels for your use cases. Examples for custom labels: - Main topic:performance - pr_agent:The main topic of this PR is performance - New endpoint - pr_agent:A new endpoint was added in this PR - SQL query - pr_agent:A new SQL query was added in this PR - Dockerfile changes - pr_agent:The PR contains changes in the Dockerfile - ...
The list above is eclectic, and aims to give an idea of different possibilities. Define custom labels that are relevant for your repo and use cases. Note that Labels are not mutually exclusive, so you can add multiple label categories. Make sure to provide proper title, and a detailed and well-phrased description for each label, so the tool will know when to suggest it.
"},{"location":"tools/documentation/","title":"\ud83d\udc8e Documentation","text":""},{"location":"tools/documentation/#overview","title":"Overview","text":"The add_docs tool scans the PR code changes, and automatically suggests documentation for any code components that changed in the PR (functions, classes, etc.).
It can be invoked manually by commenting on any PR:
/add_docs\ndocs_style: The exact style of the documentation (for python docstring). you can choose between: google, numpy, sphinx, restructuredtext, plain. Default is sphinx.extra_instructions: Optional extra instructions to the tool. For example: \"focus on the changes in the file X. Ignore change in ...\".Notes
The improve tool scans the PR code changes, and automatically generates suggestions for improving the PR code. The tool can be triggered automatically every time a new PR is opened, or it can be invoked manually by commenting on any PR:
/improve\nThe code suggestions can be presented as a single comment (via pr_code_suggestions.summarize=true):
Or as a separate commitable code comment for each suggestion:
Note that a single comment has a significantly smaller PR footprint. We recommend this mode for most cases. Also note that collapsible are not supported in Bitbucket. Hence, the suggestions are presented there as code comments.
"},{"location":"tools/improve/#extended-mode","title":"Extended mode","text":"An extended mode, which does not involve PR Compression and provides more comprehensive suggestions, can be invoked by commenting on any PR:
/improve --extended\nor by setting:
[pr_code_suggestions]\nauto_extended_mode=true\nNote that the extended mode divides the PR code changes into chunks, up to the token limits, where each chunk is handled separately (might use multiple calls to GPT-4 for large PRs). Hence, the total number of suggestions is proportional to the number of chunks, i.e., the size of the PR.
"},{"location":"tools/improve/#configuration-options","title":"Configuration options","text":"To edit configurations related to the improve tool (pr_code_suggestions section), use the following template:
/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...\nnum_code_suggestions: number of code suggestions provided by the 'improve' tool. Default is 4.extra_instructions: Optional extra instructions to the tool. For example: \"focus on the changes in the file X. Ignore change in ...\".rank_suggestions: if set to true, the tool will rank the suggestions, based on importance. Default is false.summarize: if set to true, the tool will display the suggestions in a single comment. Default is false.enable_help_text: if set to true, the tool will display a help text in the comment. Default is true.auto_extended_mode: enable extended mode automatically (no need for the --extended option). Default is true.num_code_suggestions_per_chunk: number of code suggestions provided by the 'improve' tool, per chunk. Default is 8.rank_extended_suggestions: if set to true, the tool will rank the suggestions, based on importance. Default is true.max_number_of_calls: maximum number of chunks. Default is 5.final_clip_factor: factor to remove suggestions with low confidence. Default is 0.9.Extra instructions are very important for the imrpove tool, since they enable you to guide the model to suggestions that are more relevant to the specific needs of the project.
Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify relevant aspects that you want the model to focus on.
Examples for extra instructions:
[pr_code_suggestions] # /improve #\nextra_instructions=\"\"\"\nEmphasize the following aspects:\n- Does the code logic cover relevant edge cases?\n- Is the code logic clear and easy to understand?\n- Is the code logic efficient?\n...\n\"\"\"\nexra_instructions field to guide the model to suggestions that are more relevant to the specific needs of the project.The review tool scans the PR code changes, and automatically generates a PR review. The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on any PR:
/review\nTo edit configurations related to the review tool (pr_reviewer section), use the following template:
/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...\nnum_code_suggestions: number of code suggestions provided by the 'review' tool. For manual comments, default is 4. For PR-Agent app auto tools, default is 0, meaning no code suggestions will be provided by the review tool, unless you manually edit pr_commands.inline_code_comments: if set to true, the tool will publish the code suggestions as comments on the code diff. Default is false.persistent_comment: if set to true, the review comment will be persistent, meaning that every new review request will edit the previous one. Default is true.extra_instructions: Optional extra instructions to the tool. For example: \"focus on the changes in the file X. Ignore change in ...\".require_focused_review: if set to true, the tool will add a section - 'is the PR a focused one'. Default is false.require_score_review: if set to true, the tool will add a section that scores the PR. Default is false.require_tests_review: if set to true, the tool will add a section that checks if the PR contains tests. Default is true.require_estimate_effort_to_review: if set to true, the tool will add a section that estimates the effort needed to review the PR. Default is true.This feature is available only in PR-Agent Pro
This sub-tool checks if the PR description properly contains a ticket to a project management system (e.g., Jira, Asana, Trello, etc.), as required by SOC2 compliance. If not, it will add a label to the PR: \"Missing SOC2 ticket\". - require_soc2_ticket: If set to true, the SOC2 ticket checker sub-tool will be enabled. Default is false. - soc2_ticket_prompt: The prompt for the SOC2 ticket review. Default is: Does the PR description include a link to ticket in a project management system (e.g., Jira, Asana, Trello, etc.) ?. Edit this field if your compliance requirements are different.
enable_review_labels_security: if set to true, the tool will publish a 'possible security issue' label if it detects a security issue. Default is true.enable_review_labels_effort: if set to true, the tool will publish a 'Review effort [1-5]: x' label. Default is true.enable_auto_approval: if set to true, the tool will approve the PR when invoked with the 'auto_approve' command. Default is false. This flag can be changed only from configuration file.maximal_review_effort: maximal effort level for auto-approval. If the PR's estimated review effort is above this threshold, the auto-approval will not run. Default is 5.Incremental review only considers changes since the last PR-Agent review. This can be useful when working on the PR in an iterative manner, and you want to focus on the changes since the last review instead of reviewing the entire PR again. For invoking the incremental mode, the following command can be used:
/review -i\nUnder the section 'pr_reviewer', the configuration file contains options to customize the 'review -i' tool. These configurations can be used to control the rate at which the incremental review tool will create new review comments when invoked automatically, to prevent making too much noise in the PR. - minimal_commits_for_incremental_review: Minimal number of commits since the last review that are required to create incremental review. If there are less than the specified number of commits since the last review, the tool will not perform any action. Default is 0 - the tool will always run, no matter how many commits since the last review. - minimal_minutes_for_incremental_review: Minimal number of minutes that need to pass since the last reviewed commit to create incremental review. If less than the specified number of minutes have passed between the last reviewed commit and running this command, the tool will not perform any action. Default is 0 - the tool will always run, no matter how much time have passed since the last reviewed commit. - require_all_thresholds_for_incremental_review: If set to true, all the previous thresholds must be met for incremental review to run. If false, only one is enough to run the tool. For example, if minimal_commits_for_incremental_review=2 and minimal_minutes_for_incremental_review=2, and we have 3 commits since the last review, but the last reviewed commit is from 1 minute ago: When require_all_thresholds_for_incremental_review=true the incremental review will not run, because only 1 out of 2 conditions were met (we have enough commits but the last review is too recent), but when require_all_thresholds_for_incremental_review=false the incremental review will run, because one condition is enough (we have 3 commits which is more than the configured 2). Default is false - the tool will run as long as at least once conditions is met.
By invoking:
/reflect_and_review\nThe review tool provides a collection of possible feedbacks about a PR. It is recommended to review the Configuration options section, and choose the relevant options for your use case.
Some of the features that are disabled by default are quite useful, and should be considered for enabling. For example: require_score_review, require_soc2_ticket, and more.
On the other hand, if you find one of the enabled features to be irrelevant for your use case, disable it. No default configuration can fit all use cases.
"},{"location":"tools/review/#code-suggestions","title":"Code suggestions","text":"If you set num_code_suggestions>0 , the review tool will also provide code suggestions.
Notice If you are interested only in the code suggestions, it is recommended to use the improve feature instead, since it is a dedicated only to code suggestions, and usually gives better results. Use the review tool if you want to get more comprehensive feedback, which includes code suggestions as well.
review tool is: pr_commands = [\"/review\", ...]\nreview tool will run automatically on every PR, with the default configuration. Edit this field to enable/disable the tool, or to change the used configurations.The review tool can auto-generate two specific types of labels for a PR:
possible security issue label that detects a possible security issue (enable_review_labels_security flag)Review effort [1-5]: x label, where x is the estimated effort to review the PR (enable_review_labels_effort flag)Both modes are useful, and we recommended to enable them.
"},{"location":"tools/review/#extra-instructions","title":"Extra instructions","text":"Extra instructions are important. The review tool can be configured with extra instructions, which can be used to guide the model to a feedback tailored to the needs of your project.
Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify the relevant sub-tool, and the relevant aspects of the PR that you want to emphasize.
Examples for extra instructions:
[pr_reviewer] # /review #\nextra_instructions=\"\"\"\nIn the code feedback section, emphasize the following:\n- Does the code logic cover relevant edge cases?\n- Is the code logic clear and easy to understand?\n- Is the code logic efficient?\n...\n\"\"\"\nPR-Agent can approve a PR when a specific comment is invoked.
To ensure safety, the auto-approval feature is disabled by default. To enable auto-approval, you need to actively set in a pre-defined configuration file the following:
[pr_reviewer]\nenable_auto_approval = true\nAfter enabling, by commenting on a PR:
/review auto_approve\nYou can also enable auto-approval only if the PR meets certain requirements, such as that the estimated_review_effort label is equal or below a certain threshold, by adjusting the flag:
[pr_reviewer]\nmaximal_review_effort = 5\nThe similar issue tool retrieves the most similar issues to the current issue. It can be invoked manually by commenting on any PR:
/similar_issue\nNote that to perform retrieval, the similar_issue tool indexes all the repo previous issues (once).
Select VectorDBs by changing pr_similar_issue parameter in configuration.toml file
2 VectorDBs are available to switch in 1. LanceDB 2. Pinecone
To enable usage of the 'similar issue' tool for Pinecone, you need to set the following keys in .secrets.toml (or in the relevant environment variables):
[pinecone]\napi_key = \"...\"\nenvironment = \"...\"\nTo invoke the 'similar issue' tool from CLI, run: python3 cli.py --issue_url=... similar_issue
To invoke the 'similar' issue tool via online usage, comment on a PR: /similar_issue
You can also enable the 'similar issue' tool to run automatically when a new issue is opened, by adding it to the pr_commands list in the github_app section
By combining LLM abilities with static code analysis, the test tool generate tests for a selected component, based on the PR code changes. It can be invoked manually by commenting on any PR:
/test component_name\nanalyze tool. An example result:
Notes - Language that are currently supported by the tool: Python, Java, C++, JavaScript, TypeScript.
"},{"location":"tools/test/#configuration-options","title":"Configuration options","text":"num_tests: number of tests to generate. Default is 3.testing_framework: the testing framework to use. If not set, for Python it will use pytest, for Java it will use JUnit, for C++ it will use Catch2, and for JavaScript and TypeScript it will use jest.avoid_mocks: if set to true, the tool will try to avoid using mocks in the generated tests. Note that even if this option is set to true, the tool might still use mocks if it cannot generate a test without them. Default is true.extra_instructions: Optional extra instructions to the tool. For example: \"use the following mock injection scheme: ...\".file: in case there are several components with the same name, you can specify the relevant file.class_name: in case there are several methods with the same name in the same file, you can specify the relevant class name.enable_help_text: if set to true, the tool will add a help text to the PR comment. Default is true.The update_changelog tool automatically updates the CHANGELOG.md file with the PR changes. It can be invoked manually by commenting on any PR:
/update_changelog\nUnder the section 'pr_update_changelog', the configuration file contains options to customize the 'update changelog' tool:
push_changelog_changes: whether to push the changes to CHANGELOG.md, or just print them. Default is false (print only).extra_instructions: Optional extra instructions to the tool. For example: \"focus on the changes in the file X. Ignore change in ...In some cases, you may want to exclude specific files or directories from the analysis performed by CodiumAI PR-Agent. This can be useful, for example, when you have files that are generated automatically or files that shouldn't be reviewed, like vendored code.
To ignore files or directories, edit the ignore.toml configuration file. This setting also exposes the following environment variables:
IGNORE.GLOBIGNORE.REGEXFor example, to ignore python files in a PR with online usage, comment on a PR: /review --ignore.glob=['*.py']
To ignore python files in all PRs, set in a configuration file:
[ignore]\nglob = ['*.py']\nAll PR-Agent tools have a parameter called extra_instructions, that enables to add free-text extra instructions. Example usage:
/update_changelog --pr_update_changelog.extra_instructions=\"Make sure to update also the version ...\"\nThe default mode of CodiumAI is to have a single call per tool, using GPT-4, which has a token limit of 8000 tokens. This mode provide a very good speed-quality-cost tradeoff, and can handle most PRs successfully. When the PR is above the token limit, it employs a PR Compression strategy.
However, for very large PRs, or in case you want to emphasize quality over speed and cost, there are 2 possible solutions: 1) Use a model with larger context, like GPT-32K, or claude-100K. This solution will be applicable for all the tools. 2) For the /improve tool, there is an 'extended' mode (/improve --extended), which divides the PR to chunks, and process each chunk separately. With this mode, regardless of the model, no compression will be done (but for large PRs, multiple model calls may occur)
See here for the list of available models. To use a different model than the default (GPT-4), you need to edit configuration file. For models and environments not from OPENAI, you might need to provide additional keys and other parameters. See below for instructions.
"},{"location":"usage-guide/additional_configurations/#azure","title":"Azure","text":"To use Azure, set in your .secrets.toml (working from CLI), or in the GitHub Settings > Secrets and variables (working from GitHub App or GitHub Action):
[openai]\nkey = \"\" # your azure api key\napi_type = \"azure\"\napi_version = '2023-05-15' # Check Azure documentation for the current API version\napi_base = \"\" # The base URL for your Azure OpenAI resource. e.g. \"https://<your resource name>.openai.azure.com\"\ndeployment_id = \"\" # The deployment name you chose when you deployed the engine\nand set in your configuration file:
[config]\nmodel=\"\" # the OpenAI model you've deployed on Azure (e.g. gpt-3.5-turbo)\nLocal You can run Huggingface models locally through either VLLM or Ollama
E.g. to use a new Huggingface model locally via Ollama, set:
[__init__.py]\nMAX_TOKENS = {\n \"model-name-on-ollama\": <max_tokens>\n}\ne.g.\nMAX_TOKENS={\n ...,\n \"ollama/llama2\": 4096\n}\n\n\n[config] # in configuration.toml\nmodel = \"ollama/llama2\"\n\n[ollama] # in .secrets.toml\napi_base = ... # the base url for your huggingface inference endpoint\n# e.g. if running Ollama locally, you may use:\napi_base = \"http://localhost:11434/\"\nTo use a new model with Huggingface Inference Endpoints, for example, set:
[__init__.py]\nMAX_TOKENS = {\n \"model-name-on-huggingface\": <max_tokens>\n}\ne.g.\nMAX_TOKENS={\n ...,\n \"meta-llama/Llama-2-7b-chat-hf\": 4096\n}\n[config] # in configuration.toml\nmodel = \"huggingface/meta-llama/Llama-2-7b-chat-hf\"\n\n[huggingface] # in .secrets.toml\nkey = ... # your huggingface api key\napi_base = ... # the base url for your huggingface inference endpoint\nTo use Llama2 model with Replicate, for example, set:
[config] # in configuration.toml\nmodel = \"replicate/llama-2-70b-chat:2c1608e18606fad2812020dc541930f2d0495ce32eee50074220b87300bc16e1\"\n[replicate] # in .secrets.toml\nkey = ...\nAlso review the AiHandler file for instruction how to set keys for other models.
"},{"location":"usage-guide/additional_configurations/#vertex-ai","title":"Vertex AI","text":"To use Google's Vertex AI platform and its associated models (chat-bison/codechat-bison) set:
[config] # in configuration.toml\nmodel = \"vertex_ai/codechat-bison\"\nfallback_models=\"vertex_ai/codechat-bison\"\n\n[vertexai] # in .secrets.toml\nvertex_project = \"my-google-cloud-project\"\nvertex_location = \"\"\nYour application default credentials will be used for authentication so there is no need to set explicit credentials in most environments.
If you do want to set explicit credentials then you can use the GOOGLE_APPLICATION_CREDENTIALS environment variable set to a path to a json credentials file.
To use Anthropic models, set the relevant models in the configuration section of the configuration file:
[config]\nmodel=\"anthropic/claude-3-opus-20240229\"\nmodel_turbo=\"anthropic/claude-3-opus-20240229\"\nfallback_models=[\"anthropic/claude-3-opus-20240229\"]\nAnd also set the api key in the .secrets.toml file:
[anthropic]\nKEY = \"...\"\nTo use Amazon Bedrock and its foundational models, add the below configuration:
[config] # in configuration.toml\nmodel = \"anthropic.claude-v2\"\nfallback_models=\"anthropic.claude-instant-v1\"\n\n[aws] # in .secrets.toml\nbedrock_region = \"us-east-1\"\nNote that you have to add access to foundational models before using them. Please refer to this document for more details.
AWS session is automatically authenticated from your environment, but you can also explicitly set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.
By default, around any change in your PR, git patch provides 3 lines of context above and below the change.
@@ -12,5 +12,5 @@ def func1():\n code line that already existed in the file...\n code line that already existed in the file...\n code line that already existed in the file....\n-code line that was removed in the PR\n+new code line added in the PR\n code line that already existed in the file...\n code line that already existed in the file...\n code line that already existed in the file...\nFor the review, describe, ask and add_docs tools, if the token budget allows, PR-Agent tries to increase the number of lines of context, via the parameter:
[config]\npatch_extra_lines=3\nIncreasing this number provides more context to the model, but will also increase the token budget. If the PR is too large (see PR Compression strategy), PR-Agent automatically sets this number to 0, using the original git patch.
"},{"location":"usage-guide/additional_configurations/#editing-the-prompts","title":"Editing the prompts","text":"The prompts for the various PR-Agent tools are defined in the pr_agent/settings folder. In practice, the prompts are loaded and stored as a standard setting object. Hence, editing them is similar to editing any other configuration value - just place the relevant key in .pr_agent.tomlfile, and override the default value.
For example, if you want to edit the prompts of the describe tool, you can add the following to your .pr_agent.toml file:
[pr_description_prompt]\nsystem=\"\"\"\n...\n\"\"\"\nuser=\"\"\"\n...\n\"\"\"\nWhen running from your local repo (CLI), your local configuration file will be used. Examples of invoking the different tools via the CLI:
python -m pr_agent.cli --pr_url=<pr_url> reviewpython -m pr_agent.cli --pr_url=<pr_url> describepython -m pr_agent.cli --pr_url=<pr_url> improvepython -m pr_agent.cli --pr_url=<pr_url> ask \"Write me a poem about this PR\"python -m pr_agent.cli --pr_url=<pr_url> reflectpython -m pr_agent.cli --pr_url=<pr_url> update_changelog<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 any configuration value by adding it to the command line:
python -m pr_agent.cli --pr_url=<pr_url> /review --pr_reviewer.extra_instructions=\"focus on the file: ...\"\n(2) You can print results locally, without publishing them, by setting in configuration.toml:
[config]\npublish_output=false\nverbosity_level=2\nOnline usage means invoking PR-Agent tools by comments on a PR. Commands for invoking the different tools via comments:
/review/describe/improve/ask \"...\"/reflect/update_changelogTo 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\n/config to see the list of available configurations."},{"location":"usage-guide/automations_and_usage/#github-app","title":"GitHub App","text":""},{"location":"usage-guide/automations_and_usage/#github-app-automatic-tools-when-a-new-pr-is-opened","title":"GitHub app automatic tools when a new PR is opened","text":"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]\npr_commands = [\n \"/describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true --pr_description.final_update_message=false\",\n \"/review --pr_reviewer.num_code_suggestions=0 --pr_reviewer.final_update_message=false\",\n \"/improve\",\n]\ndescribe, review and improve tools. For the describe tool, for example, the add_original_user_description and keep_original_user_title parameters will be set to true. You can override the default tool parameters by using one the three options for a configuration file: wiki, local, or global. For example, if your local .pr_agent.toml file contains:
[pr_description]\nadd_original_user_description = false\nkeep_original_user_title = false\ndescribe tool with the above parameters. To cancel the automatic run of all the tools, set:
[github_app]\nhandle_pr_actions = []\nYou can also disable automatic runs for PRs with specific titles, by setting the ignore_pr_titles parameter with the relevant regex. For example:
[github_app]\nignore_pr_title = [\"^[Auto]\", \".*ignore.*\"]\nIn addition to running automatic tools when a PR is opened, the GitHub app can also respond to new code that is pushed to an open PR.
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]\nhandle_push_trigger = true\npush_commands = [\n \"/describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true\",\n \"/review --pr_reviewer.num_code_suggestions=0\",\n]\ndescribe and review tools, with the specified parameters."},{"location":"usage-guide/automations_and_usage/#github-action","title":"GitHub Action","text":"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. Specifically, start by setting the following environment variables:
env:\n OPENAI_KEY: ${{ secrets.OPENAI_KEY }} # Make sure to add your OpenAI key to your repo secrets\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Make sure to add your GitHub token to your repo secrets\n github_action_config.auto_review: \"true\" # enable\\disable auto review\n github_action_config.auto_describe: \"true\" # enable\\disable auto describe\n github_action_config.auto_improve: \"true\" # enable\\disable auto improve\ngithub_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. 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 file in the root of your repo, similar to the GitHub App usage.
For example, you can set an environment variable: pr_description.add_original_user_description=false, or add a .pr_agent.toml file with the following content:
[pr_description]\nadd_original_user_description = false\nAfter setting up a GitLab 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:
[gitlab]\npr_commands = [\n \"/describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true\",\n \"/review --pr_reviewer.num_code_suggestions=0\",\n \"/improve\",\n]\nSimilar to GitHub app, when running PR-Agent from BitBucket App, the default configuration file from a pre-built docker will be initially loaded.
By uploading a local .pr_agent.toml file to the root of the repo's main branch, you can edit and customize any configuration parameter. Note that you need to upload .pr_agent.toml prior to creating a PR, in order for the configuration to take effect.
For example, if your local .pr_agent.toml file contains:
[pr_reviewer]\ninline_code_comments = true\nEach time you invoke a /review tool, it will use inline code comments.
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 = [\n \"/review --pr_reviewer.num_code_suggestions=0\",\n \"/improve --pr_code_suggestions.summarize=false\",\n]\nTo use Azure DevOps provider use the following settings in configuration.toml:
[config]\ngit_provider=\"azure\"\nuse_repo_settings_file=false\nAzure DevOps provider supports PAT token or DefaultAzureCredential authentication. PAT is faster to create, but has build in experation 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 seperate ADO user identity (via AAD) to the agent.
If PAT was choosen, you can assign the value in .secrets.toml. If DefaultAzureCredential was choosen, you can assigned the additional env vars like AZURE_CLIENT_SECRET directly, or use managed identity/az cli (for local develpment) without any additional configuration. in any case, 'org' value must be assigned in .secrets.toml:
[azure_devops]\norg = \"https://dev.azure.com/YOUR_ORGANIZATION/\"\n# pat = \"YOUR_PAT_TOKEN\" needed only if using PAT for authentication\nTo 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]\npr_commands = [\n \"/describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true\",\n \"/review --pr_reviewer.num_code_suggestions=0\",\n \"/improve\",\n]\nThe different tools and sub-tools used by CodiumAI PR-Agent are adjustable via the configuration file.
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. See the Tools Guide for a detailed description of the different tools and their configurations.
There are three ways to set persistent configurations:
In terms of precedence, wiki configurations will override local configurations, and local configurations will override global configurations.
"},{"location":"usage-guide/configuration_options/#wiki-configuration-file","title":"Wiki configuration file \ud83d\udc8e","text":"Specifically for GitHub, with PR-Agent-Pro you can set configurations by creating a page called .pr_agent.toml in the wiki of the repo. The advantage of this method is that it allows to set configurations without needing to commit new content to the repo - just edit the wiki page and save.
Click here to see a short instructional video. We recommend surrounding the configuration content with triple-quotes, to allow better presentation when displayed in the wiki as markdown. An example content:
[pr_description] # /describe #\nkeep_original_user_title=false\nPR-Agent will know to remove the triple-quotes when reading the configuration content.
"},{"location":"usage-guide/configuration_options/#local-configuration-file","title":"Local configuration file","text":"By uploading a local .pr_agent.toml file to the root of the repo's main branch, you can edit and customize any configuration parameter. Note that you need to upload .pr_agent.toml prior to creating a PR, in order for the configuration to take effect.
For example, if you set in .pr_agent.toml:
[pr_reviewer]\nextra_instructions=\"\"\"\\\n- instruction a\n- instruction b\n...\n\"\"\"\nThen you can give a list of extra instructions to the review tool.
If you create a repo called pr-agent-settings in your organization, it's configuration file .pr_agent.toml will be used as a global configuration file for any other repo that belongs to the same organization. Parameters from a local .pr_agent.toml file, in a specific repo, will override the global configuration parameters.
For example, in the GitHub organization Codium-ai: - The repo https://github.com/Codium-ai/pr-agent-settings contains a .pr_agent.toml file that serves as a global configuration file for all the repos in the GitHub organization Codium-ai. - The repo https://github.com/Codium-ai/pr-agent inherits the global configuration file from pr-agent-settings.
After installation, there are three basic ways to invoke CodiumAI PR-Agent:
Specifically, CLI commands can be issued by invoking a pre-built docker image, or by invoking a locally cloned repo. For online usage, you will need to setup either a GitHub App, or a GitHub Action. GitHub App and GitHub Action also enable to run PR-Agent specific tool automatically when a new PR is opened.
git provider: The git_provider field in the configuration file determines the GIT provider that will be used by PR-Agent. Currently, the following providers are supported: \"github\", \"gitlab\", \"bitbucket\", \"azure\", \"codecommit\", \"local\", \"gerrit\"
Unfortunately, it is not possible in GitHub to disable mail notifications from a specific user. If you are subscribed to notifications for a repo with PR-Agent, we recommend turning off notifications for PR comments, to avoid lengthy emails:
As an alternative, you can filter in your mail provider the notifications specifically from the PR-Agent bot, see how.
"}]}