diff --git a/INSTALL.md b/INSTALL.md index 42a16ea6..2ea8a75d 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -4,66 +4,69 @@ To get started with PR-Agent quickly, you first need to acquire two tokens: 1. An OpenAI key from [here](https://platform.openai.com/), with access to GPT-4. -2. A GitHub personal access token (classic) with the repo scope. +2. A GitHub\GitLab\BitBucket personal access token (classic) with the repo scope. There are several ways to use PR-Agent: -- [Method 1: Use Docker image (no installation required)](INSTALL.md#method-1-use-docker-image-no-installation-required) -- [Method 2: Run from source](INSTALL.md#method-2-run-from-source) -- [Method 3: Run as a GitHub Action](INSTALL.md#method-3-run-as-a-github-action) -- [Method 4: Run as a polling server](INSTALL.md#method-4-run-as-a-polling-server) -- [Method 5: Run as a GitHub App](INSTALL.md#method-5-run-as-a-github-app) -- [Method 6: Deploy as a Lambda Function](INSTALL.md#method-6---deploy-as-a-lambda-function) -- [Method 7: AWS CodeCommit](INSTALL.md#method-7---aws-codecommit-setup) -- [Method 8: Run a GitLab webhook server](INSTALL.md#method-8---run-a-gitlab-webhook-server) -- [Method 9: Run as a Bitbucket Pipeline](INSTALL.md#method-9-run-as-a-bitbucket-pipeline) +**Locally** +- [Using Docker image (no installation required)](INSTALL.md#use-docker-image-no-installation-required) +- [Run from source](INSTALL.md#run-from-source) + +**GitHub specific methods** +- [Run as a GitHub Action](INSTALL.md#run-as-a-github-action) +- [Run as a polling server](INSTALL.md#run-as-a-polling-server) +- [Run as a GitHub App](INSTALL.md#run-as-a-github-app) +- [Deploy as a Lambda Function](INSTALL.md#deploy-as-a-lambda-function) +- [AWS CodeCommit](INSTALL.md#aws-codecommit-setup) + +**GitLab specific methods** +- [Run a GitLab webhook server](INSTALL.md#run-a-gitlab-webhook-server) + +**BitBucket specific methods** +- [Run as a Bitbucket Pipeline](INSTALL.md#run-as-a-bitbucket-pipeline) +- [Run on a hosted app](INSTALL.md#run-on-a-hosted-bitbucket-app) --- -### Method 1: Use Docker image (no installation required) +### Use Docker image (no installation required) To request a review for a PR, or ask a question about a PR, you can run directly from the Docker image. Here's how: -1. To request a review for a PR, run the following command: - For GitHub: ``` -docker run --rm -it -e OPENAI.KEY= -e GITHUB.USER_TOKEN= codiumai/pr-agent --pr_url review +docker run --rm -it -e OPENAI.KEY= -e GITHUB.USER_TOKEN= codiumai/pr-agent:latest --pr_url review ``` For GitLab: ``` -docker run --rm -it -e OPENAI.KEY= -e CONFIG.GIT_PROVIDER=gitlab -e GITLAB.PERSONAL_ACCESS_TOKEN= codiumai/pr-agent --pr_url review +docker run --rm -it -e OPENAI.KEY= -e CONFIG.GIT_PROVIDER=gitlab -e GITLAB.PERSONAL_ACCESS_TOKEN= codiumai/pr-agent:latest --pr_url review ``` +For BitBucket: +``` +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 +``` + For 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. -2. To ask a question about a PR, run the following command: +Similarly, to ask a question about a PR, run the following command: ``` docker run --rm -it -e OPENAI.KEY= -e GITHUB.USER_TOKEN= codiumai/pr-agent --pr_url ask "" ``` -Note: If you want to ensure you're running a specific version of the Docker image, consider using the image's digest. -The digest is a unique identifier for a specific version of an image. You can pull and run an image using its digest by referencing it like so: repository@sha256:digest. Always ensure you're using the correct and trusted digest for your operations. -1. To request a review for a PR using a specific digest, run the following command: +A list of the relevant tools can be found in the [tools guide](./docs/TOOLS_GUIDE.md). + + +Note: If you want to ensure you're running a specific version of the Docker image, consider using the image's digest: ```bash docker run --rm -it -e OPENAI.KEY= -e GITHUB.USER_TOKEN= codiumai/pr-agent@sha256:71b5ee15df59c745d352d84752d01561ba64b6d51327f97d46152f0c58a5f678 --pr_url review ``` - -2. To ask a question about a PR using the same digest, run the following command: -```bash -docker run --rm -it -e OPENAI.KEY= -e GITHUB.USER_TOKEN= codiumai/pr-agent@sha256:71b5ee15df59c745d352d84752d01561ba64b6d51327f97d46152f0c58a5f678 --pr_url ask "" +in addition, you can run a [specific released versions](./RELEASE_NOTES.md) of pr-agent, for example: +``` +codiumai/pr-agent@v0.8 ``` - -Possible questions you can ask include: - -- What is the main theme of this PR? -- Is the PR ready for merge? -- What are the main changes in this PR? -- Should this PR be split into smaller parts? -- Can you compose a rhymed song about this PR? --- -### Method 2: Run from source +### Run from source 1. Clone this repository: @@ -93,11 +96,14 @@ python3 -m pr_agent.cli --pr_url review python3 -m pr_agent.cli --pr_url ask python3 -m pr_agent.cli --pr_url describe python3 -m pr_agent.cli --pr_url improve +python3 -m pr_agent.cli --pr_url add_docs +python3 -m pr_agent.cli --issue_url similar_issue +... ``` --- -### Method 3: Run as a GitHub Action +### Run as a GitHub Action You can use our pre-built Github Action Docker image to run PR-Agent as a Github Action. @@ -167,10 +173,11 @@ When you open your next PR, you should see a comment from `github-actions` bot w --- -### Method 4: Run as a polling server -Request reviews by tagging your Github user on a PR +### Run as a polling server +Request reviews by tagging your GitHub user on a PR + +Follow [steps 1-3](#run-as-a-github-action) of the GitHub Action setup. -Follow steps 1-3 of method 2. Run the following command to start the server: ``` @@ -179,7 +186,7 @@ python pr_agent/servers/github_polling.py --- -### Method 5: Run as a GitHub App +### Run as a GitHub App Allowing you to automate the review process on your private or public repositories. 1. Create a GitHub App from the [Github Developer Portal](https://docs.github.com/en/developers/apps/creating-a-github-app). @@ -260,13 +267,13 @@ docker push codiumai/pr-agent:github_app # Push to your Docker repository 9. 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
-> For more information please check out [CONFIGURATION.md](Usage.md#working-from-github-app-pre-built-repo) +> 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](./Usage.md#working-with-github-app) --- -### Method 6 - Deploy as a Lambda Function +### Deploy as a Lambda Function -1. Follow steps 1-5 of [Method 5](#method-5-run-as-a-github-app). +1. Follow steps 1-5 of [Method 5](#run-as-a-github-app). 2. Build a docker image that can be used as a lambda function ```shell docker buildx build --platform=linux/amd64 . -t codiumai/pr-agent:serverless -f docker/Dockerfile.lambda @@ -278,12 +285,12 @@ docker push codiumai/pr-agent:github_app # Push to your Docker repository ``` 4. Create a lambda function that uses the uploaded image. Set the lambda timeout to be at least 3m. 5. Configure the lambda function to have a Function URL. -6. Go back to steps 8-9 of [Method 5](#method-5-run-as-a-github-app) with the function url as your Webhook URL. +6. Go back to steps 8-9 of [Method 5](#run-as-a-github-app) with the function url as your Webhook URL. The Webhook URL would look like `https:///api/v1/github_webhooks` --- -### Method 7 - AWS CodeCommit Setup +### AWS CodeCommit Setup Not 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: @@ -353,7 +360,7 @@ PYTHONPATH="/PATH/TO/PROJECTS/pr-agent" python pr_agent/cli.py \ --- -### Method 8 - Run a GitLab webhook server +### Run a GitLab webhook server 1. From the GitLab workspace or group, create an access token. Enable the "api" scope only. 2. Generate a random secret for your app, and save it for later. For example, you can use: @@ -372,7 +379,7 @@ In the "Trigger" section, check the ‘comments’ and ‘merge request events -### Method 9: Run as a Bitbucket Pipeline +### Run as a Bitbucket Pipeline You can use the Bitbucket Pipeline system to run PR-Agent on every pull request open or update. @@ -398,6 +405,9 @@ BITBUCKET_BEARER_TOKEN: You can get a Bitbucket token for your repository by following Repository Settings -> Security -> Access Tokens. + +### Run on a hosted Bitbucket app + Please contact 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](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/git_providers/bitbucket_provider.py) implmentation. diff --git a/README.md b/README.md index f5bc474e..26cb77d1 100644 --- a/README.md +++ b/README.md @@ -28,16 +28,16 @@ CodiumAI `PR-Agent` is an open-source tool aiming to help developers review pull \ ‣ **Update Changelog ([`/update_changelog`](./docs/UPDATE_CHANGELOG.md))**: Automatically updating the CHANGELOG.md file with the PR changes. \ -‣ **Find similar issue ([`/similar_issue`](./docs/SIMILAR_ISSUE.md))**: Automatically retrieves and presents similar issues +‣ **Find Similar Issue ([`/similar_issue`](./docs/SIMILAR_ISSUE.md))**: Automatically retrieves and presents similar issues \ ‣ **Add Documentation ([`/add_docs`](./docs/ADD_DOCUMENTATION.md))**: Automatically adds documentation to un-documented functions/classes in the PR. -See the [Usage Guide](./Usage.md) for instructions how to run the different tools from _CLI_, _online usage_, Or by _automatically triggering_ them when a new PR is opened. +See the [Installation Guide](./INSTALL.md) for instructions how to install and run the tool on different platforms. + +See the [Usage Guide](./Usage.md) for instructions how to run the different tools from _CLI_, _online usage_, or by _automatically triggering_ them when a new PR is opened. See the [Tools Guide](./docs/TOOLS_GUIDE.md) for detailed description of the different tools. -See the [Release notes](./RELEASE_NOTES.md) for updates on the latest changes. -

Example results:

/describe:

@@ -204,6 +204,9 @@ Here are some advantages of PR-Agent: - [x] Documentation (is the PR properly documented) - [ ] ... +See the [Release notes](./RELEASE_NOTES.md) for updates on the latest changes. + + ## Similar Projects - [CodiumAI - Meaningful tests for busy devs](https://github.com/Codium-ai/codiumai-vscode-release) (although various capabilities are much more advanced in the CodiumAI IDE plugins) @@ -211,7 +214,12 @@ Here are some advantages of PR-Agent: - [openai-pr-reviewer](https://github.com/coderabbitai/openai-pr-reviewer) - [CodeReview BOT](https://github.com/anc95/ChatGPT-CodeReview) - [AI-Maintainer](https://github.com/merwanehamadi/AI-Maintainer) - + +## Data Privacy + +If you use self-host PR-Agent, e.g. via CLI running on your computer, 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 + ## Links [![Join our Discord community](https://raw.githubusercontent.com/Codium-ai/codiumai-vscode-release/main/media/docs/Joincommunity.png)](https://discord.gg/kG35uSHDBc) diff --git a/Usage.md b/Usage.md index 867ccc44..fc5d7b3b 100644 --- a/Usage.md +++ b/Usage.md @@ -12,7 +12,7 @@ ### Introduction -See the **[installation guide](/INSTALL.md)** for instructions on how to setup PR-Agent. After installation, there are three basic ways to invoke CodiumAI PR-Agent: +After [installation](/INSTALL.md), there are three basic ways to invoke CodiumAI PR-Agent: 1. Locally running a CLI command 2. Online usage - by [commenting](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695021901) on a PR 3. Enabling PR-Agent tools to run automatically when a new PR is opened