Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

wiki #729

Merged
merged 3 commits into from
Mar 2, 2024
Merged

wiki #729

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
db79641
wiki
mrT23 Feb 29, 2024
aabe96c
Refactor Usage.md for improved readability and organization
mrT23 Mar 2, 2024
917bdd5
Refactor Usage.md for improved readability and organization
mrT23 Mar 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,13 @@ Making pull requests less painful with an AI agent
- [Why use PR-Agent?](#why-use-pr-agent)

## News and Updates

### Feb 29, 2024
- You can now use the repo's [wiki page](./Usage.md#configuration) to set configurations for PR-Agent 💎

<kbd><img src="https://codium.ai/images/pr_agent/wiki_configuration.png" width="512"></kbd>


### Feb 21, 2024
- Added a new command, `/help`, to easily provide a list of available tools and their descriptions, and run them interactively.

Expand Down Expand Up @@ -93,7 +100,7 @@ CodiumAI PR-Agent is an open-source tool to help efficiently review and handle p
| | Adaptive and token-aware file patch fitting | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| | Multiple models support | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| | [Static code analysis](https://github.com/Codium-ai/pr-agent/blob/main/docs/Analyze.md) 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| | [Global configuration](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#global-configuration-file-) 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| | [Global and wiki configurations](./Usage.md#configuration) 💎 | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| | [PR Actions](https://www.codium.ai/images/pr_agent/pr-actions.mp4) 💎 | :white_check_mark: | | | |
- 💎 means this feature is available only in [PR-Agent Pro](https://www.codium.ai/pricing/)
- Support for additional git providers is described in [here](./docs/Full_environments.md)
Expand Down
174 changes: 104 additions & 70 deletions Usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,25 @@

### Table of Contents
- [Introduction](#introduction)
- [Local Repo (CLI)](#working-from-a-local-repo-cli)
- [Online Usage](#online-usage)
- [GitHub App](#working-with-github-app)
- [GitHub Action](#working-with-github-action)
- [GitLab Webhook](#working-with-gitlab-webhook)
- [BitBucket App](#working-with-bitbucket-self-hosted-app)
- [Azure DevOps Provider](#azure-devops-provider)
- [Configuration Options](#configuration-options)
- [Managing Mail Notifications](#managing-mail-notifications)
- [Usage Types](#usage-types)
- [Local Repo (CLI)](#working-from-a-local-repo-cli)
- [Online Usage](#online-usage)
- [GitHub App](#working-with-github-app)
- [GitHub Action](#working-with-github-action)
- [GitLab Webhook](#working-with-gitlab-webhook)
- [BitBucket App](#working-with-bitbucket-self-hosted-app)
- [Azure DevOps Provider](#azure-devops-provider)
- [Additional Configurations Walkthrough](#appendix---additional-configurations-walkthrough)
- [Ignoring files from analysis](#ignoring-files-from-analysis)
- [Extra instructions](#extra-instructions)
- [Working with large PRs](#working-with-large-prs)
- [Changing a model](#changing-a-model)
- [Patch Extra Lines](#patch-extra-lines)
- [Editing the prompts](#editing-the-prompts)

### Introduction
## Introduction

After [installation](/INSTALL.md), there are three basic ways to invoke CodiumAI PR-Agent:
1. Locally running a CLI command
Expand All @@ -24,14 +33,46 @@ For online usage, you will need to setup either a [GitHub App](INSTALL.md#method
GitHub App and GitHub Action also enable to run PR-Agent specific tool automatically when a new PR is opened.


#### The configuration file
- The different tools and sub-tools used by CodiumAI PR-Agent are adjustable via the **[configuration file](pr_agent/settings/configuration.toml)**.
### git provider
The [git_provider](pr_agent/settings/configuration.toml#L4) 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"
`

## Configuration Options

The different tools and sub-tools used by CodiumAI PR-Agent are adjustable via the **[configuration file](pr_agent/settings/configuration.toml)**.

In addition to general configuration options, each tool has its own configurations. For example, the `review` tool will use parameters from the [pr_reviewer](/pr_agent/settings/configuration.toml#L16) section in the configuration file.
See the [Tools Guide](./docs/TOOLS_GUIDE.md) for a detailed description of the different tools and their configurations.

There are three ways to set persistent configurations:
1. Wiki configuration page 💎
2. Local configuration file
3. Global configuration file 💎

- The [Tools Guide](./docs/TOOLS_GUIDE.md) provides a detailed description of the different tools and their configurations.
In terms of precedence, wiki configurations will override local configurations, and local configurations will override global configurations.

### Wiki configuration file 💎

- 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.
Specifically for GitHub, with PR-Agent-Pro you can set configurations by creating a page called `.pr_agent.toml` in the [wiki](https://github.com/Codium-ai/pr-agent/wiki/pr_agent.toml) 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**.

<kbd><img src="https://codium.ai/images/pr_agent/wiki_configuration.png" width="512"></kbd>

We recommend surrounding the configuration content with triple-quotes, to allow better presentation when displayed in the wiki as markdown.
An example content:

\`\`\`<br>
[pr_description] # /describe #<br>
keep_original_user_title=false<br>
\`\`\`

PR-Agent will know to remove the triple-quotes when reading the configuration content.

### Local configuration file

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`:

Expand All @@ -47,7 +88,7 @@ extra_instructions="""\
Then you can give a list of extra instructions to the `review` tool.


#### Global configuration file 💎
### Global configuration file 💎

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.
Expand All @@ -56,28 +97,19 @@ For example, in the GitHub organization `Codium-ai`:
- The repo [`https://github.com/Codium-ai/pr-agent-settings`](https://github.com/Codium-ai/pr-agent-settings/blob/main/.pr_agent.toml) 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`](https://github.com/Codium-ai/pr-agent/blob/main/.pr_agent.toml) inherits the global configuration file from `pr-agent-settings`.

#### Ignoring files from analysis
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](/pr_agent/settings/ignore.toml)** configuration file. This setting also exposes the following environment variables:
## Managing mail notifications

- `IGNORE.GLOB`
- `IGNORE.REGEX`
If you are subscribed to notifications for a repo with PR-Agent, we recommend turning off notifications for PR comments, to avoid lengthy emails:

For example, to ignore python files in a PR with online usage, comment on a PR:
`/review --ignore.glob=['*.py']`
<kbd><img src="https://codium.ai/images/pr_agent/notifications.png" width="512"></kbd>

To ignore python files in all PRs, set in a configuration file:
```
[ignore]
glob = ['*.py']
```
As an alternative, you can filter in you mail provider the notifications specifically from the PR-Agent bot:
https://www.quora.com/How-can-you-filter-emails-for-specific-people-in-Gmail#:~:text=On%20the%20Filters%20and%20Blocked,the%20body%20of%20the%20email

#### git provider
The [git_provider](pr_agent/settings/configuration.toml#L4) field in the configuration file determines the GIT provider that will be used by PR-Agent. Currently, the following providers are supported:
`
"github", "gitlab", "azure", "codecommit", "local", "gerrit"
`
<kbd><img src="https://codium.ai/images/pr_agent/filter_mail_notifications.png" width="512"></kbd>

## Usage Types

### Working from a local repo (CLI)
When running from your local repo (CLI), your local configuration file will be used.
Expand Down Expand Up @@ -130,23 +162,11 @@ Any configuration value in [configuration file](pr_agent/settings/configuration.


### Working with GitHub App
When running PR-Agent from GitHub App, the default [configuration file](pr_agent/settings/configuration.toml) 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 you set in `.pr_agent.toml`:
#### GitHub app automatic tools when a new PR is opened

```
[pr_reviewer]
num_code_suggestions=1
```

Then you will overwrite the default number of code suggestions to 1.

#### GitHub app automatic tools
The [github_app](pr_agent/settings/configuration.toml#L108) section defines GitHub app specific configurations.

##### GitHub app automatic tools for PR actions
The configuration parameter `pr_commands` defines the list of tools that will be **run automatically** when a new PR is opened.
```
[github_app]
Expand All @@ -159,7 +179,7 @@ pr_commands = [
This means that when a new PR is opened/reopened or marked as ready for review, PR-Agent will run the `describe`, `review` and `improve` tools.
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 uploading a local configuration file called `.pr_agent.toml` to the root of your repo.
You can override the default tool parameters by using one the three options for a [configuration file](#configuration-options): **wiki**, **local**, or **global**.
For example, if your local `.pr_agent.toml` file contains:
```
[pr_description]
Expand All @@ -181,7 +201,8 @@ ignore_pr_title = ["^[Auto]", ".*ignore.*"]
```
will ignore PRs with titles that start with "Auto" or contain the word "ignore".

##### GitHub app automatic tools for push actions (commits to an open PR)
#### GitHub app automatic tools for push actions (commits to an open PR)

In 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.
Expand All @@ -200,29 +221,6 @@ For the `review` tool, it will run in incremental mode, and the `remove_previous

Much like the configurations for `pr_commands`, you can override the default tool parameters by uploading a local configuration file to the root of your repo.

#### Editing the prompts
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.toml`file, and override the default value.

For example, if you want to edit the prompts of the [describe](./pr_agent/settings/pr_description_prompts.toml) tool, you can add the following to your `.pr_agent.toml` file:
```
[pr_description_prompt]
system="""
...
"""
user="""
...
"""
```
Note that the new prompt will need to generate an output compatible with the relevant [post-process function](./pr_agent/tools/pr_description.py#L137).

#### Managing notifications
If you are subscribed to notifications for a repo with PR-Agent, we recommend turning off notifications for PR comments, to avoid lengthy emails:

<kbd><img src="https://codium.ai/images/pr_agent/notifications.png" width="512"></kbd>


### Working with GitHub Action
`GitHub Action` is a different way to trigger PR-Agent tools, and uses a different configuration mechanism than `GitHub App`.
You can configure settings for `GitHub Action` by adding environment variables under the env section in `.github/workflows/pr_agent.yml` file.
Expand All @@ -245,6 +243,7 @@ For example, you can set an environment variable: `pr_description.add_original_u
[pr_description]
add_original_user_description = false
```

### Working with GitLab Webhook
After 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:
```
Expand Down Expand Up @@ -332,8 +331,25 @@ webhook_password = "<basic auth password>"
> :warning: **Ensure that the webhook endpoint is only accessible over HTTPS** to mitigate the risk of credential interception when using basic authentication.


### Appendix - additional configurations walkthrough
## Appendix - additional configurations walkthrough


#### Ignoring files from analysis
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](/pr_agent/settings/ignore.toml)** configuration file. This setting also exposes the following environment variables:

- `IGNORE.GLOB`
- `IGNORE.REGEX`

For 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]
glob = ['*.py']
```

#### Extra instructions
All PR-Agent tools have a parameter called `extra_instructions`, that enables to add free-text extra instructions. Example usage:
Expand Down Expand Up @@ -495,4 +511,22 @@ patch_extra_lines=3
```

Increasing 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_COMPRESSION.md)), PR-Agent automatically sets this number to 0, using the original git patch.
If the PR is too large (see [PR Compression strategy](./PR_COMPRESSION.md)), PR-Agent automatically sets this number to 0, using the original git patch.


#### Editing the prompts
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.toml`file, and override the default value.

For example, if you want to edit the prompts of the [describe](./pr_agent/settings/pr_description_prompts.toml) tool, you can add the following to your `.pr_agent.toml` file:
```
[pr_description_prompt]
system="""
...
"""
user="""
...
"""
```
Note that the new prompt will need to generate an output compatible with the relevant [post-process function](./pr_agent/tools/pr_description.py#L137).
4 changes: 4 additions & 0 deletions pr_agent/servers/github_app.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,8 @@ async def handle_comments_on_pr(body: Dict[str, Any],
get_logger().info(f"Processing comment on PR {api_url=}, comment_body={comment_body}")
await agent.handle_request(api_url, comment_body,
notify=lambda: provider.add_eyes_reaction(comment_id, disable_eyes=disable_eyes))
else:
get_logger().info(f"User {sender=} is not eligible to process comment on PR {api_url=}")

async def handle_new_pr_opened(body: Dict[str, Any],
event: str,
Expand All @@ -136,6 +138,8 @@ async def handle_new_pr_opened(body: Dict[str, Any],
if action in get_settings().github_app.handle_pr_actions: # ['opened', 'reopened', 'ready_for_review', 'review_requested']
if get_identity_provider().verify_eligibility("github", sender_id, api_url) is not Eligibility.NOT_ELIGIBLE:
await _perform_auto_commands_github("pr_commands", agent, body, api_url, log_context)
else:
get_logger().info(f"User {sender=} is not eligible to process PR {api_url=}")

async def handle_push_trigger_for_new_commits(body: Dict[str, Any],
event: str,
Expand Down
1 change: 1 addition & 0 deletions pr_agent/settings/configuration.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ publish_output=true
publish_output_progress=true
verbosity_level=0 # 0,1,2
use_extra_bad_extensions=false
use_wiki_settings_file=true
use_repo_settings_file=true
use_global_settings_file=true
ai_timeout=120 # 2minutes
Expand Down
Loading