xiaxinhang/pr-agent
1
0
Fork 0
mirror of https://github.com/qodo-ai/pr-agent.git synced 2025-07-13 17:20:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit 'a134a8bf6d44de526d6fcbba13c1f9813a5dea09' into hl/flip_2_configs

Browse Source 
# Conflicts:
#	pr_agent/settings/configuration.toml
This commit is contained in:
Hussam.lawen
2024-04-16 22:18:29 +03:00
parent f123a6e069 a134a8bf6d
commit f6b5470a96
43 changed files with 581 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/README.md
View File

@ -1,15 +1 @@
# To install:
pip install mkdocs
pip install mkdocs-material
pip install mkdocs-material-extensions
pip install "mkdocs-material[imaging]"
# docs
To run localy: `mkdocs serve`
To expand and customize the theme: [Material MKDocs](https://squidfunk.github.io/mkdocs-material/)
The deployment is managed on the gh-pages branches.
After each merge to main the deplloyment will be taken care of by GH action automatically and the new version will be available at: [Docs](https://codium-ai.github.io/docs/)
Github action is located in `.github/workflows/ci.yml` file.
# [Visit Our Docs Portal](https://pr-agent-docs.codium.ai/)

43
docs/docs/index.md
View File

@ -19,20 +19,19 @@ PR-Agent offers extensive pull request functionalities across various git provid
| | ⮑ [SOC2 Compliance](https://pr-agent-docs.codium.ai/tools/review/#soc2-ticket-compliance){:target="_blank"} 💎 | ✅ | ✅ | ✅ | ✅ |
| | Ask | ✅ | ✅ | ✅ | ✅ |
| | Describe | ✅ | ✅ | ✅ | ✅ |
| | ⮑ [Inline file summary](https://pr-agent-docs.codium.ai/tools/describe/#inline-file-summary){:target="_blank"} 💎 | ✅ | ✅ | ✅ | ✅ |
| | ⮑ [Inline file summary](https://pr-agent-docs.codium.ai/tools/describe/#inline-file-summary){:target="_blank"} 💎 | ✅ | ✅ | | ✅ |
| | Improve | ✅ | ✅ | ✅ | ✅ |
| | ⮑ Extended | ✅ | ✅ | ✅ | ✅ |
| | [Custom Suggestions](./tools/custom_suggestions.md){:target="_blank"} 💎 | ✅ | ✅ | ✅ | ✅ |
| | Reflect and Review | ✅ | ✅ | ✅ | ✅ |
| | Update CHANGELOG.md | ✅ | ✅ | ✅ | ️ |
| | Find Similar Issue | ✅ | | | ️ |
| | [Add PR Documentation](./tools/documentation.md){:target="_blank"} 💎 | ✅ | ✅ | ✅ | ✅ |
| | [Add PR Documentation](./tools/documentation.md){:target="_blank"} 💎 | ✅ | ✅ | | ✅ |
| | [Generate Custom Labels](./tools/describe.md#handle-custom-labels-from-the-repos-labels-page-💎){:target="_blank"} 💎 | ✅ | ✅ | | ✅ |
| | [Analyze PR Components](./tools/analyze.md){:target="_blank"} 💎 | ✅ | ✅ | ✅ | ✅ |
| | [Analyze PR Components](./tools/analyze.md){:target="_blank"} 💎 | ✅ | ✅ | | ✅ |
| | | | | | ️ |
| USAGE | CLI | ✅ | ✅ | ✅ | ✅ |
| | App / webhook | ✅ | ✅ | | ✅ |
| | Tagging bot | ✅ | | | ✅ |
| | App / webhook | ✅ | ✅ | ✅ | ✅ |
| | Actions | ✅ | | | ️ |
| | | | | |
| CORE | PR compression | ✅ | ✅ | ✅ | ✅ |
@ -46,28 +45,34 @@ PR-Agent offers extensive pull request functionalities across various git provid
💎 marks a feature available only in [PR-Agent Pro](https://www.codium.ai/pricing/){:target="_blank"}
## Example results
## Example Results
<hr>
#### [/describe](https://github.com/Codium-ai/pr-agent/pull/530)
<figure markdown="1">
![/describe](https://www.codium.ai/images/pr_agent/describe_new_short_main.png){width=512}
</figure>
<hr>
#### [/review](https://github.com/Codium-ai/pr-agent/pull/732#issuecomment-1975099151)
<figure markdown="1">
![/review](https://www.codium.ai/images/pr_agent/review_new_short_main.png){width=512}
</figure>
<hr>
#### [/improve](https://github.com/Codium-ai/pr-agent/pull/732#issuecomment-1975099159)
<figure markdown="1">
![/improve](https://www.codium.ai/images/pr_agent/improve_new_short_main.png){width=512}
</figure>
<hr>
#### [/generate_labels](https://github.com/Codium-ai/pr-agent/pull/530)
<figure markdown="1">
![/generate_labels](https://www.codium.ai/images/pr_agent/geneare_custom_labels_main_short.png){width=300}
</figure>
<hr>
## How it works
## How it Works
The following diagram illustrates PR-Agent tools and their flow:
@ -81,21 +86,25 @@ Check out the [PR Compression strategy](core-abilities/index.md) page for more d
[PR-Agent Pro](https://www.codium.ai/pricing/) is a hosted version of PR-Agent, provided by CodiumAI. It is available for a monthly fee, and provides the following benefits:
1. **Fully managed** - We take care of everything for you - hosting, models, regular updates, and more. Installation is as simple as signing up and adding the PR-Agent app to your GitHub\BitBucket repo.
1. **Fully managed** - We take care of everything for you - hosting, models, regular updates, and more. Installation is as simple as signing up and adding the PR-Agent app to your GitHub\GitLab\BitBucket repo.
2. **Improved privacy** - No data will be stored or used to train models. PR-Agent Pro will employ zero data retention, and will use an OpenAI account with zero data retention.
3. **Improved support** - PR-Agent Pro users will receive priority support, and will be able to request new features and capabilities.
4. **Extra features** -In addition to the benefits listed above, PR-Agent Pro will emphasize more customization, and the usage of static code analysis, in addition to LLM logic, to improve results. It has the following additional tools and features:
- [**Analyze PR components**](./tools/analyze.md/)
- [**Custom Code Suggestions**](./tools/custom_suggestions.md/)
- [**Tests**](./tools/test.md/)
- [**PR documentation**](./tools/documentation.md/)
- [**CI feedback**](./tools/ci_feedback.md/)
- [**SOC2 compliance check**](./tools/review.md/#soc2-ticket-compliance)
- [**Custom labels**](./tools/describe.md/#handle-custom-labels-from-the-repos-labels-page)
- [**Global and wiki configuration**](./usage-guide/configuration_options.md/#wiki-configuration-file)
- (Tool): [**Analyze PR components**](./tools/analyze.md/)
- (Tool): [**Custom Code Suggestions**](./tools/custom_suggestions.md/)
- (Tool): [**Tests**](./tools/test.md/)
- (Tool): [**PR documentation**](./tools/documentation.md/)
- (Tool): [**Improve Component**](https://pr-agent-docs.codium.ai/tools/improve_component/)
- (Tool): [**Similar code search**](https://pr-agent-docs.codium.ai/tools/similar_code/)
- (Tool): [**CI feedback**](./tools/ci_feedback.md/)
- (Feature): [**Interactive triggering**](./usage-guide/automations_and_usage.md/#interactive-triggering)
- (Feature): [**SOC2 compliance check**](./tools/review.md/#soc2-ticket-compliance)
- (Feature): [**Custom labels**](./tools/describe.md/#handle-custom-labels-from-the-repos-labels-page)
- (Feature): [**Global and wiki configuration**](./usage-guide/configuration_options.md/#wiki-configuration-file)
- (Feature): [**Inline file summary**](https://pr-agent-docs.codium.ai/tools/describe/#inline-file-summary)
## Data privacy
## Data Privacy
If you host PR-Agent with your OpenAI API key, it is between you and OpenAI. You can read their API data privacy policy here:
https://openai.com/enterprise-privacy

24
docs/docs/installation/github.md
View File

@ -7,9 +7,11 @@ You can use our pre-built Github Action Docker image to run PR-Agent as a Github
```yaml
on:
pull_request:
types: [opened, reopened, ready_for_review]
issue_comment:
jobs:
pr_agent_job:
if: ${{ github.event.sender.type != 'Bot' }}
runs-on: ubuntu-latest
permissions:
issues: write
@ -24,27 +26,14 @@ jobs:
OPENAI_KEY: ${{ secrets.OPENAI_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
** if you want to pin your action to a specific release (v0.7 for example) for stability reasons, use:
** if you want to pin your action to a specific release (v2.0 for example) for stability reasons, use:
```yaml
on:
pull_request:
issue_comment:
jobs:
pr_agent_job:
runs-on: ubuntu-latest
permissions:
issues: write
pull-requests: write
contents: write
name: Run pr agent on every pull request, respond to user comments
...
steps:
- name: PR Agent action step
id: pragent
uses: Codium-ai/pr-agent@v0.7
env:
OPENAI_KEY: ${{ secrets.OPENAI_KEY }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
uses: Codium-ai/pr-agent@v2.0
...
```
2) Add the following secret to your repository under `Settings > Secrets and variables > Actions > New repository secret > Add secret`:
@ -66,6 +55,7 @@ When you open your next PR, you should see a comment from `github-actions` bot w
PR_REVIEWER.REQUIRE_TESTS_REVIEW: "false" # Disable tests review
PR_CODE_SUGGESTIONS.NUM_CODE_SUGGESTIONS: 6 # Increase number of code suggestions
```
See detailed usage instructions in the [USAGE GUIDE](https://pr-agent-docs.codium.ai/usage-guide/automations_and_usage/#github-action)
---

2
docs/docs/installation/index.md
View File

@ -1,6 +1,6 @@
# Installation
## self-hosted PR-Agent
## Self-hosted PR-Agent
If you choose to host you own PR-Agent, you first need to acquire two tokens:
1. An OpenAI key from [here](https://platform.openai.com/api-keys), with access to GPT-4 (or a key for [other models](../usage-guide/additional_configurations.md/#changing-a-model), if you prefer).

12
docs/docs/tools/analyze.md
View File

@ -1,7 +1,7 @@
## Overview
The `analyze` tool combines static code analysis with LLM capabilities to provide a comprehensive analysis of the PR code changes.
The `analyze` tool combines advanced 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.
The tool scans the PR code changes, find the code components (methods, functions, classes) that changed, and enables to interactively generate tests, docs, code suggestions and similar code search for each component.
It can be invoked manually by commenting on any PR:
```
@ -9,14 +9,10 @@ It can be invoked manually by commenting on any PR:
```
## Example usage
An example [result](https://github.com/Codium-ai/pr-agent/pull/546#issuecomment-1868524805):
An example result:
![Analyze 1](https://codium.ai/images/pr_agent/analyze_1.png){width=750}
&rarr;
![Analyze 2](https://codium.ai/images/pr_agent/analyze_2.png){width=750}
&rarr;
![Analyze 3](https://codium.ai/images/pr_agent/analyze_3.png){width=750}
**Notes**
- Language that are currently supported: Python, Java, C++, JavaScript, TypeScript.
- Language that are currently supported: Python, Java, C++, JavaScript, TypeScript, C#.

41
docs/docs/tools/ask.md
View File

@ -7,9 +7,9 @@ It can be invoked manually by commenting on any PR:
```
For example:
![Ask Comment](https://codium.ai/images/pr_agent/ask_comment.png){width=768}
![Ask Comment](https://codium.ai/images/pr_agent/ask_comment.png){width=512}
![Ask](https://codium.ai/images/pr_agent/ask.png){width=768}
![Ask](https://codium.ai/images/pr_agent/ask.png){width=512}
## Ask lines
@ -18,6 +18,41 @@ You can run `/ask` on specific lines of code in the PR from the PR's diff view.
- 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.
![Ask Line](https://codium.ai/images/pr_agent/Ask_line.png){width=768}
![Ask Line](https://codium.ai/images/pr_agent/Ask_line.png){width=512}
Note that the tool does not have "memory" of previous questions, and answers each question independently.
## Ask on images
You can also ask questions about images that appear in the comment, where the entire PR code will be used as context.
<br>
The basic syntax is:
```
/ask "..."
[Image](https://real_link_to_image)
```
where `https://real_link_to_image` is the direct link to the image.
Note that GitHub has a built-in mechanism of pasting images in comments. However, pasted image does not provide a direct link.
To get a direct link to an image, we recommend using the following scheme:
1) First, post a comment that contains **only** the image:
![Ask image1](https://codium.ai/images/pr_agent/ask_images1.png){width=512}
2) Quote reply to that comment:
![Ask image2](https://codium.ai/images/pr_agent/ask_images2.png){width=512}
3) In the screen opened, type the question below the image:
![Ask image3](https://codium.ai/images/pr_agent/ask_images3.png){width=512}
![Ask image4](https://codium.ai/images/pr_agent/ask_images4.png){width=512}
4) Post the comment, and receive the answer:
![Ask image5](https://codium.ai/images/pr_agent/ask_images5.png){width=512}
See a full video tutorial [here](https://codium.ai/images/pr_agent/ask_image_video.mov)

73
docs/docs/tools/describe.md
View File

@ -5,6 +5,7 @@ The tool can be triggered automatically every time a new PR is [opened](../usage
```
/describe
```
For example:
![Describe comment](https://codium.ai/images/pr_agent/describe_comment.png){width=512}
@ -27,6 +28,8 @@ To edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agen
- `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 original description. Default is false.
- `publish_description_as_comment_persistent`: if set to true and `publish_description_as_comment` is true, the tool will publish the description as a persistent comment to the PR. Default is true.
- `add_original_user_description`: if set to true, the tool will add the original user description to the generated description. Default is true.
- `generate_ai_title`: if set to true, the tool will automatically generate a title for the PR. If false, it will keep the original title. Default is false.
@ -66,22 +69,6 @@ If you prefer to have the file summaries appear in the "Files changed" tab on ev
**Note**: that this feature is currently available only for GitHub.
### Handle custom labels from the Repo's labels page 💎
You can control the custom labels that will be suggested by the `describe` tool, from the repo's labels page:
* GitHub : go to `https://github.com/{owner}/{repo}/labels` (or click on the "Labels" tab in the issues or PRs page)
* GitLab : go to `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`.<br>
The description should be comprehensive and detailed, indicating when to add the desired label. For example:
![Add native custom labels](https://codium.ai/images/pr_agent/add_native_custom_labels.png){width=768}
### Markers template
To enable markers, set `pr_description.use_description_markers=true`.
@ -114,6 +101,43 @@ The marker `pr_agent:type` will be replaced with the PR type, `pr_agent:summary`
- `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.
## Custom labels
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`].
You can define custom labels that are relevant for your repo and use cases.
Custom labels can be defined in a [configuration file](https://pr-agent-docs.codium.ai/tools/custom_labels/#configuration-options), or directly in the repo's [labels page](#handle-custom-labels-from-the-repos-labels-page).
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.
<br>
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.
Each label description should be a **conditional statement**, that indicates if to add the label to the PR or not, according to the PR content.
### Handle custom labels from the Repo's labels page 💎
You can control the custom labels that will be suggested by the `describe` tool, from the repo's labels page:
* GitHub : go to `https://github.com/{owner}/{repo}/labels` (or click on the "Labels" tab in the issues or PRs page)
* GitLab : go to `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`.<br>
The description should be comprehensive and detailed, indicating when to add the desired label. For example:
![Add native custom labels](https://codium.ai/images/pr_agent/add_native_custom_labels.png){width=768}
## Usage Tips
@ -142,20 +166,3 @@ The marker `pr_agent:type` will be replaced with the PR type, `pr_agent: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.
!!! tip "Custom labels"
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](#handle-custom-labels-from-the-repos-labels-page) 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.
<br>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.

2
docs/docs/tools/documentation.md
View File

@ -19,6 +19,6 @@ For example:
**Notes**
- Language that are currently fully supported: Python, Java, C++, JavaScript, TypeScript.
- Language that are currently fully supported: Python, Java, C++, JavaScript, TypeScript, C#.
- For languages that are not fully supported, the tool will suggest documentation only for new components in the PR.
- A previous version of the tool, that offered support only for new components, was deprecated.

17
docs/docs/tools/help.md Normal file
View File

@ -0,0 +1,17 @@
## Overview
The `help` tool provides a list of all the available tools and their descriptions.
For PR-Agent Pro users, it also enables to trigger each tool by checking the relevant box.
It can be invoked manually by commenting on any PR:
```
/help
```
## Example usage
An example [result](https://github.com/Codium-ai/pr-agent/pull/546#issuecomment-1868524805):
![Help 1](https://codium.ai/images/pr_agent/help1.png){width=750}
&rarr;
![Analyze 2](https://codium.ai/images/pr_agent/help2.png){width=750}

2
docs/docs/tools/improve.md
View File

@ -72,7 +72,7 @@ To edit [configurations](https://github.com/Codium-ai/pr-agent/blob/main/pr_agen
Examples for extra instructions:
```
[pr_code_suggestions] # /improve #
extra_instructions="""
extra_instructions="""\
Emphasize the following aspects:
- Does the code logic cover relevant edge cases?
- Is the code logic clear and easy to understand?

24
docs/docs/tools/improve_component.md Normal file
View File

@ -0,0 +1,24 @@
## Overview
The `improve_component` tool generates code suggestions for a specific code component that changed in the PR.
it can be invoked manually by commenting on any PR:
```
/improve_component component_name
```
To get a list of the components that changed in the PR and choose the relevant component interactively, use the [`analyze`](./analyze.md) tool.
Example result:
![improve_component1](https://codium.ai/images/pr_agent/improve_component1.png){width=768}
![improve_component2](https://codium.ai/images/pr_agent/improve_component2.png){width=768}
**Notes**
- Language that are currently supported by the tool: Python, Java, C++, JavaScript, TypeScript, C#.
## Configuration options
- `num_code_suggestions`: number of code suggestions to provide. Default is 4
- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on ...".
- `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.

30
docs/docs/tools/index.md
View File

@ -2,19 +2,21 @@
Here is a list of PR-Agent tools, each with a dedicated page that explains how to use it:
| Tool | Description |
|-------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| **[PR Description (`/describe`](./describe.md))** | Automatically generating PR description - title, type, summary, code walkthrough and labels |
| **[PR Review (`/review`](./review.md))** | Adjustable feedback about the PR, possible issues, security concerns, review effort and more |
| **[Code Suggestions (`/improve`](./improve.md))** | Code suggestions for improving the PR |
| **[Question Answering (`/ask ...`](./ask.md))** | Answering free-text questions about the PR, or on specific code lines |
| **[Update Changelog (`/update_changelog`](./update_changelog.md))** | Automatically updating the CHANGELOG.md file with the PR changes |
| **[Find Similar Issue (`/similar_issue`](./similar_issues.md))** | Automatically retrieves and presents similar issues |
| **💎 [Add Documentation (`/add_docs`](./documentation.md))** | Generates documentation to methods/functions/classes that changed in the PR |
| **💎 [Generate Custom Labels (`/generate_labels`](./custom_labels.md))** | Generates custom labels for the PR, based on specific guidelines defined by the user |
| **💎 [Analyze (`/analyze`](./analyze.md))** | Identify code components that changed in the PR, and enables to interactively generate tests, docs, and code suggestions for each component |
| **💎 [Custom Suggestions (`/custom_suggestions`](./custom_suggestions.md))** | Automatically generates custom suggestions for improving the PR code, based on specific guidelines defined by the user |
| **💎 [Generate Tests (`/test component_name`](./test.md))** | Automatically generates unit tests for a selected component, based on the PR code changes |
| **💎 [CI Feedback (`/checks ci_job`](./ci_feedback.md))** | Automatically generates feedback and analysis for a failed CI job |
| Tool | Description |
|------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| **[PR Description (`/describe`](./describe.md))** | Automatically generating PR description - title, type, summary, code walkthrough and labels |
| **[PR Review (`/review`](./review.md))** | Adjustable feedback about the PR, possible issues, security concerns, review effort and more |
| **[Code Suggestions (`/improve`](./improve.md))** | Code suggestions for improving the PR |
| **[Question Answering (`/ask ...`](./ask.md))** | Answering free-text questions about the PR, or on specific code lines |
| **[Update Changelog (`/update_changelog`](./update_changelog.md))** | Automatically updating the CHANGELOG.md file with the PR changes |
| **[Find Similar Issue (`/similar_issue`](./similar_issues.md))** | Automatically retrieves and presents similar issues |
| **[Help (`/help`](./help.md))** | Provides a list of all the available tools. Also enables to trigger them interactively (💎) |
| **💎 [Add Documentation (`/add_docs`](./documentation.md))** | Generates documentation to methods/functions/classes that changed in the PR |
| **💎 [Generate Custom Labels (`/generate_labels`](./custom_labels.md))** | Generates custom labels for the PR, based on specific guidelines defined by the user |
| **💎 [Analyze (`/analyze`](./analyze.md))** | Identify code components that changed in the PR, and enables to interactively generate tests, docs, and code suggestions for each component |
| **💎 [Custom Suggestions (`/custom_suggestions`](./custom_suggestions.md))** | Automatically generates custom suggestions for improving the PR code, based on specific guidelines defined by the user |
| **💎 [Generate Tests (`/test component_name`](./test.md))** | Automatically generates unit tests for a selected component, based on the PR code changes |
| **💎 [Improve Component (`/improve_component component_name`](./improve_component.md))** | Generates code suggestions for a specific code component that changed in the PR |
| **💎 [CI Feedback (`/checks ci_job`](./ci_feedback.md))** | Automatically generates feedback and analysis for a failed CI job |
Note that the tools marked with 💎 are available only for PR-Agent Pro users.

4
docs/docs/tools/review.md
View File

@ -124,8 +124,8 @@ The tool will first ask the author questions about the PR, and will guide the re
Examples for extra instructions:
```
[pr_reviewer] # /review #
extra_instructions="""
[pr_reviewer]
extra_instructions="""\
In the code feedback section, emphasize the following:
- Does the code logic cover relevant edge cases?
- Is the code logic clear and easy to understand?

4
docs/docs/tools/test.md
View File

@ -5,7 +5,7 @@ It can be invoked manually by commenting on any PR:
/test component_name
```
where 'component_name' is the name of a specific component in the PR.
To get a list of the components that changed in the PR, use the [`analyze`](./analyze.md) tool.
To get a list of the components that changed in the PR and choose the relevant component interactively, use the [`analyze`](./analyze.md) tool.
An example [result](https://github.com/Codium-ai/pr-agent/pull/598#issuecomment-1913679429):
@ -17,7 +17,7 @@ An example [result](https://github.com/Codium-ai/pr-agent/pull/598#issuecomment-
![test3](https://codium.ai/images/pr_agent/test3.png){width=768}
**Notes**
- Language that are currently supported by the tool: Python, Java, C++, JavaScript, TypeScript.
- Language that are currently supported by the tool: Python, Java, C++, JavaScript, TypeScript, C#.
## Configuration options

18
docs/docs/usage-guide/additional_configurations.md
View File

@ -7,10 +7,10 @@ To ignore files or directories, edit the **[ignore.toml](https://github.com/Codi
- `IGNORE.GLOB`
- `IGNORE.REGEX`
For example, to ignore python files in a PR with online usage, comment on a PR:
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:
To ignore Python files in all PRs, set in a configuration file:
```
[ignore]
glob = ['*.py']
@ -26,13 +26,13 @@ All PR-Agent tools have a parameter called `extra_instructions`, that enables to
## Working with large PRs
The 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.
This mode provides 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](../core-abilities/index.md).
However, for very large PRs, or in case you want to emphasize quality over speed and cost, there are 2 possible solutions:
However, for very large PRs, or in case you want to emphasize quality over speed and cost, there are two possible solutions:
1) [Use a model](https://codium-ai.github.io/Docs-PR-Agent/usage-guide/#changing-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](https://codium-ai.github.io/Docs-PR-Agent/tools/#improve) (`/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)
which divides the PR to chunks, and processes each chunk separately. With this mode, regardless of the model, no compression will be done (but for large PRs, multiple model calls may occur)
## Changing a model
@ -79,6 +79,7 @@ MAX_TOKENS={
[config] # in configuration.toml
model = "ollama/llama2"
model_turbo = "ollama/llama2"
[ollama] # in .secrets.toml
api_base = ... # the base url for your huggingface inference endpoint
@ -101,6 +102,7 @@ MAX_TOKENS={
}
[config] # in configuration.toml
model = "huggingface/meta-llama/Llama-2-7b-chat-hf"
model_turbo = "huggingface/meta-llama/Llama-2-7b-chat-hf"
[huggingface] # in .secrets.toml
key = ... # your huggingface api key
@ -114,13 +116,14 @@ To use Llama2 model with Replicate, for example, set:
```
[config] # in configuration.toml
model = "replicate/llama-2-70b-chat:2c1608e18606fad2812020dc541930f2d0495ce32eee50074220b87300bc16e1"
model_turbo = "replicate/llama-2-70b-chat:2c1608e18606fad2812020dc541930f2d0495ce32eee50074220b87300bc16e1"
[replicate] # in .secrets.toml
key = ...
```
(you can obtain a Llama2 key from [here](https://replicate.com/replicate/llama-2-70b-chat/api))
Also review the [AiHandler](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/algo/ai_handler.py) file for instruction how to set keys for other models.
Also, review the [AiHandler](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/algo/ai_handler.py) file for instructions on how to set keys for other models.
### Vertex AI
@ -129,6 +132,7 @@ To use Google's Vertex AI platform and its associated models (chat-bison/codecha
```
[config] # in configuration.toml
model = "vertex_ai/codechat-bison"
model_turbo = "vertex_ai/codechat-bison"
fallback_models="vertex_ai/codechat-bison"
[vertexai] # in .secrets.toml
@ -183,7 +187,7 @@ AWS session is automatically authenticated from your environment, but you can al
## Patch Extra Lines
By default, around any change in your PR, git patch provides 3 lines of context above and below the change.
By default, around any change in your PR, git patch provides three lines of context above and below the change.
```
@@ -12,5 +12,5 @@ def func1():
code line that already existed in the file...

28
docs/docs/usage-guide/automations_and_usage.md
View File

@ -50,6 +50,10 @@ Any configuration value in [configuration file](https://github.com/Codium-ai/pr-
## GitHub App
!!! note "Configurations for PR-Agent Pro"
PR-Agent Pro for GitHub is an App, hosted by CodiumAI. So all the instructions below are relevant also for PR-Agent Pro users.
Same goes for [GitLab webhook](#gitlab-webhook) and [BitBucket App](#bitbucket-app) sections.
### GitHub app automatic tools when a new PR is opened
The [github_app](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L108) section defines GitHub app specific configurations.
@ -59,7 +63,7 @@ The configuration parameter `pr_commands` defines the list of tools that will be
[github_app]
pr_commands = [
"/describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true --pr_description.final_update_message=false",
"/review --pr_reviewer.num_code_suggestions=0 --pr_reviewer.final_update_message=false",
"/review --pr_reviewer.num_code_suggestions=0",
"/improve",
]
```
@ -99,13 +103,13 @@ The configuration parameter `push_commands` defines the list of tools that will
handle_push_trigger = true
push_commands = [
"/describe --pr_description.add_original_user_description=true --pr_description.keep_original_user_title=true",
"/review --pr_reviewer.num_code_suggestions=0",
"/review --pr_reviewer.num_code_suggestions=0 --pr_reviewer.final_update_message=false",
]
```
This means that when new code is pushed to the PR, the PR-Agent will run the `describe` and `review` tools, with the specified parameters.
## GitHub Action
`GitHub Action` is a different way to trigger PR-Agent tools, and uses a different configuration mechanism than `GitHub App`.
`GitHub Action` is a different way to trigger PR-Agent tools, and uses a different configuration mechanism than `GitHub App`.<br>
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:
```yaml
@ -115,17 +119,23 @@ Specifically, start by setting the following environment variables:
github_action_config.auto_review: "true" # enable\disable auto review
github_action_config.auto_describe: "true" # enable\disable auto describe
github_action_config.auto_improve: "true" # enable\disable auto improve
github_action_config.enable_output: "true" # enable\disable github actions output parameter
```
`github_action_config.auto_review`, `github_action_config.auto_describe` and `github_action_config.auto_improve` are used to enable/disable automatic tools that run when a new PR is opened.
If not set, the default configuration is for all three tools to run automatically when a new PR is opened.
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.
`github_action_config.enable_output` are used to enable/disable github actions [output parameter](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#outputs-for-docker-container-and-javascript-actions) (default is `true`).
Review result is output as JSON to `steps.{step-id}.outputs.review` property.
The JSON structure is equivalent to the yaml data structure defined in [pr_reviewer_prompts.toml](https://github.com/idubnori/pr-agent/blob/main/pr_agent/settings/pr_reviewer_prompts.toml).
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:
Note that you can give additional config parameters by adding environment variables to `.github/workflows/pr_agent.yml`, or by using a `.pr_agent.toml` [configuration file](https://pr-agent-docs.codium.ai/usage-guide/configuration_options/#global-configuration-file) in the root of your repo
For example, you can set an environment variable: `pr_description.publish_labels=false`, or add a `.pr_agent.toml` file with the following content:
```
[pr_description]
add_original_user_description = false
publish_labels = false
```
to prevent PR-Agent from publishing labels when running the `describe` tool.
## 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:
@ -153,11 +163,11 @@ Each time you invoke a `/review` tool, it will use inline code comments.
### BitBucket Self-Hosted App automatic tools
to control which commands will run automatically when a new PR is opened, you can set the `pr_commands` parameter in the configuration file:
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]
```
[bitbucket_app]
pr_commands = [
"/review --pr_reviewer.num_code_suggestions=0",
"/improve --pr_code_suggestions.summarize=false",
@ -196,4 +206,4 @@ pr_commands = [
"/review --pr_reviewer.num_code_suggestions=0",
"/improve",
]
```
```

2
docs/docs/usage-guide/configuration_options.md
View File

@ -22,7 +22,7 @@ Click [here](https://codium.ai/images/pr_agent/wiki_configuration_pr_agent.mp4)
An example content:
```
[pr_description] # /describe #
[pr_description]
keep_original_user_title=false
```

5
docs/docs/usage-guide/index.md
View File

@ -1,8 +1,10 @@
# Usage guide
This page provides a detailed guide on how to use PR-Agent. It includes information on how to adjust PR-Agent configurations, define which tools will run automatically, manage mail notifications, and other advanced configurations.
- [Introduction](./introduction.md)
- [Configuration Options](./configuration_options.md)
- [Managing Mail Notifications](./mail_notifications.md)
- [Usage and Automation](./automations_and_usage.md)
- [Local Repo (CLI)](./automations_and_usage.md#local-repo-cli)
- [Online Usage](./automations_and_usage.md#online-usage)
@ -11,6 +13,7 @@
- [GitLab Webhook](./automations_and_usage.md#gitlab-webhook)
- [BitBucket App](./automations_and_usage.md#bitbucket-app)
- [Azure DevOps Provider](./automations_and_usage.md#azure-devops-provider)
- [Managing Mail Notifications](./mail_notifications.md)
- [Additional Configurations Walkthrough](./additional_configurations.md)
- [Ignoring files from analysis](./additional_configurations.md#ignoring-files-from-analysis)
- [Extra instructions](./additional_configurations.md#extra-instructions)

9
docs/docs/usage-guide/mail_notifications.md
View File

@ -7,3 +7,12 @@ If you are subscribed to notifications for a repo with PR-Agent, we recommend tu
As an alternative, you can filter in your mail provider the notifications specifically from the PR-Agent bot, [see how](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).
![filter_mail_notifications](https://codium.ai/images/pr_agent/filter_mail_notifications.png){width=512}
Another option to reduce the mail overload, yet still receive notifications on PR-Agent tools, is to disable the help collapsible section in PR-Agent bot comments.
This can done by setting `enable_help_text=false` for the relevant tool in the configuration file.
For example, to disable the help text for the `pr_reviewer` tool, set:
```
[pr_reviewer]
enable_help_text = false
```

12
docs/mkdocs.yml
View File

@ -1,4 +1,6 @@
site_name: PR-Agent
site_name: PR-Agent Documentation
repo_url: https://github.com/Codium-ai/pr-agent
repo_name: Codium-ai/pr-agent
nav:
- Overview: 'index.md'
@ -14,7 +16,7 @@ nav:
- 'usage-guide/index.md'
- Introduction: 'usage-guide/introduction.md'
- Configuration Options: 'usage-guide/configuration_options.md'
- Managing email notifications: 'usage-guide/mail_notifications.md'
- Managing Mail Notifications: 'usage-guide/mail_notifications.md'
- Usage and Automation: 'usage-guide/automations_and_usage.md'
- Additional Configurations: 'usage-guide/additional_configurations.md'
- Tools:
@ -25,8 +27,10 @@ nav:
- Ask: 'tools/ask.md'
- Update Changelog: 'tools/update_changelog.md'
- Similar Issues: 'tools/similar_issues.md'
- Help: 'tools/help.md'
- 💎 Analyze: 'tools/analyze.md'
- 💎 Test: 'tools/test.md'
- 💎 Improve Component: 'tools/improve_component.md'
- 💎 Documentation: 'tools/documentation.md'
- 💎 Custom Labels: 'tools/custom_labels.md'
- 💎 Custom Suggestions: 'tools/custom_suggestions.md'
@ -38,6 +42,8 @@ theme:
logo: assets/logo.svg
favicon: assets/favicon.ico
name: material
icon:
repo: fontawesome/brands/github
features:
- navigation.tabs
- navigation.expand
@ -95,7 +101,7 @@ extra:
- icon: fontawesome/brands/instagram
link: https://www.instagram.com/codiumai/
analytics:
provider: google
provider: custom
property: ${{ secrets.GOOGLE_ANALYTICS_ID }}
extra_css:

10
docs/overrides/main.html Normal file
View File

@ -0,0 +1,10 @@
{% extends "base.html" %}
{% block scripts %}
{{ super() }}
<!-- Google Tag Manager (noscript) -->
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5C9KZBM3"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<!-- End Google Tag Manager (noscript) -->
{% endblock %}

7
docs/overrides/partials/integrations/analytics/custom.html Normal file
View File

@ -0,0 +1,7 @@
<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-5C9KZBM3');</script>
<!-- End Google Tag Manager -->