From 24ae6b966f3cfaadbc049b0e28ba77d339b0b3df Mon Sep 17 00:00:00 2001 From: "Hussam.lawen" Date: Sun, 16 Jul 2023 19:56:58 +0300 Subject: [PATCH] Refactor Install section to a separate MD file --- INSTALL.md | 180 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 181 +++-------------------------------------------------- 2 files changed, 189 insertions(+), 172 deletions(-) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..4a9c5752 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,180 @@ + +## Installation + +--- + +#### Method 1: 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: + +``` +docker run --rm -it -e OPENAI.KEY= -e GITHUB.USER_TOKEN= codiumai/pr-agent --pr_url review +``` + +2. 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 "" +``` + +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 as a Github Action + +You can use our pre-built Github Action Docker image to run PR-Agent as a Github Action. + +1. Add the following file to your repository under `.github/workflows/pr_agent.yml`: + +```yaml +on: + pull_request: + issue_comment: +jobs: + pr_agent_job: + runs-on: ubuntu-latest + 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@main + env: + OPENAI_KEY: ${{ secrets.OPENAI_KEY }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +``` + +2. Add the following secret to your repository under `Settings > Secrets`: + +``` +OPENAI_KEY: +``` + +The GITHUB_TOKEN secret is automatically created by Github. + +3. 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. + +4. You may configure PR-Agent by adding environment variables under the env section that corresponds to any configurable property in the [configuration](./CONFIGURATION.md) file. Some examples: +```yaml + env: + # ... previous environment values + OPENAI.ORG: "" + PR_REVIEWER.REQUIRE_TESTS_REVIEW: "false" # Disable tests review + PR_CODE_SUGGESTIONS.NUM_CODE_SUGGESTIONS: 6 # Increase number of code suggestions +``` + +--- + +#### Method 3: Run from source + +1. Clone this repository: + +``` +git clone https://github.com/Codium-ai/pr-agent.git +``` + +2. Install the requirements in your favorite virtual environment: + +``` +pip install -r requirements.txt +``` + +3. Copy the secrets template file and fill in your OpenAI key and your GitHub user token: + +``` +cp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml +# Edit .secrets.toml file +``` + +4. Run the appropriate Python scripts from the scripts folder: + +``` +python pr_agent/cli.py --pr_url review +python pr_agent/cli.py --pr_url ask +python pr_agent/cli.py --pr_url describe +python pr_agent/cli.py --pr_url improve +``` + +--- + +#### Method 4: Run as a polling server +Request reviews by tagging your Github user on a PR. + +Follow steps 1-3 of method 2. +Run the following command to start the server: + +``` +python pr_agent/servers/github_polling.py +``` + +--- + +#### Method 5: 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). + + - Set the following permissions: + - Pull requests: Read & write + - Issue comment: Read & write + - Metadata: Read-only + - Set the following events: + - Issue comment + - Pull request + +2. 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))") +``` + +3. Acquire 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 + +4. Clone this repository: + +``` +git clone https://github.com/Codium-ai/pr-agent.git +``` + +5. Copy the secrets template file and fill in the following: + - Your OpenAI key. + - Set deployment_type to 'app' + - Copy your app's private key to the private_key field. + - Copy your app's ID to the app_id field. + - Copy your app's webhook secret to the webhook_secret field. + +``` +cp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml +# Edit .secrets.toml file +``` + +6. Build a Docker image for the app and optionally push it to a Docker repository. We'll use Dockerhub as an example: + +``` +docker build . -t codiumai/pr-agent:github_app --target github_app -f docker/Dockerfile +docker push codiumai/pr-agent:github_app # Push to your Docker repository +``` + +7. Host 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. + +8. Go back to your app's settings, 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. + +9. Install the app by navigating to the "Install App" tab, and selecting your desired repositories. + +--- diff --git a/README.md b/README.md index 4279bf69..97b5b615 100644 --- a/README.md +++ b/README.md @@ -101,179 +101,16 @@ To get started with PR-Agent quickly, you first need to acquire two tokens: There are several ways to use PR-Agent. Let's start with the simplest one: --- +## Install +Here are several ways to install and run PR-Agent: -#### Method 1: 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: - -``` -docker run --rm -it -e OPENAI.KEY= -e GITHUB.USER_TOKEN= codiumai/pr-agent --pr_url review -``` - -2. 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 "" -``` - -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 as a Github Action - -You can use our pre-built Github Action Docker image to run PR-Agent as a Github Action. - -1. Add the following file to your repository under `.github/workflows/pr_agent.yml`: - -```yaml -on: - pull_request: - issue_comment: -jobs: - pr_agent_job: - runs-on: ubuntu-latest - 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@main - env: - OPENAI_KEY: ${{ secrets.OPENAI_KEY }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` - -2. Add the following secret to your repository under `Settings > Secrets`: - -``` -OPENAI_KEY: -``` - -The GITHUB_TOKEN secret is automatically created by Github. - -3. 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. - -4. You may configure PR-Agent by adding environment variables under the env section that corresponds to any configurable property in the [configuration](./CONFIGURATION.md) file. Some examples: -```yaml - env: - # ... previous environment values - OPENAI.ORG: "" - PR_REVIEWER.REQUIRE_TESTS_REVIEW: "false" # Disable tests review - PR_CODE_SUGGESTIONS.NUM_CODE_SUGGESTIONS: 6 # Increase number of code suggestions -``` - ---- - -#### Method 3: Run from source - -1. Clone this repository: - -``` -git clone https://github.com/Codium-ai/pr-agent.git -``` - -2. Install the requirements in your favorite virtual environment: - -``` -pip install -r requirements.txt -``` - -3. Copy the secrets template file and fill in your OpenAI key and your GitHub user token: - -``` -cp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml -# Edit .secrets.toml file -``` - -4. Run the appropriate Python scripts from the scripts folder: - -``` -python pr_agent/cli.py --pr_url review -python pr_agent/cli.py --pr_url ask -python pr_agent/cli.py --pr_url describe -python pr_agent/cli.py --pr_url improve -``` - ---- - -#### Method 4: Run as a polling server; request reviews by tagging your Github user on a PR - -Follow steps 1-3 of method 2. -Run the following command to start the server: - -``` -python pr_agent/servers/github_polling.py -``` - ---- - -#### Method 5: 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). - - - Set the following permissions: - - Pull requests: Read & write - - Issue comment: Read & write - - Metadata: Read-only - - Set the following events: - - Issue comment - - Pull request - -2. 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))") -``` - -3. Acquire 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 - -4. Clone this repository: - -``` -git clone https://github.com/Codium-ai/pr-agent.git -``` - -5. Copy the secrets template file and fill in the following: - - Your OpenAI key. - - Set deployment_type to 'app' - - Copy your app's private key to the private_key field. - - Copy your app's ID to the app_id field. - - Copy your app's webhook secret to the webhook_secret field. - -``` -cp pr_agent/settings/.secrets_template.toml pr_agent/settings/.secrets.toml -# Edit .secrets.toml file -``` - -6. Build a Docker image for the app and optionally push it to a Docker repository. We'll use Dockerhub as an example: - -``` -docker build . -t codiumai/pr-agent:github_app --target github_app -f docker/Dockerfile -docker push codiumai/pr-agent:github_app # Push to your Docker repository -``` - -7. Host 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. - -8. Go back to your app's settings, 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. - -9. Install the app by navigating to the "Install App" tab, and selecting your desired repositories. - +- [Method 1: Use Docker image (no installation required)](INSTALL.md#method-1-use-docker-image-no-installation-required) +- [Method 2: Run as a Github Action](INSTALL.md#method-2-run-as-a-github-action) +- [Method 3: Run from source](INSTALL.md#method-3-run-from-source) +- [Method 4: Run as a polling server](INSTALL.md#method-4-run-as-a-polling-server) + - Request reviews by tagging your Github user on a PR +- [Method 5: Run as a Github App](INSTALL.md#method-5-run-as-a-github-app) + - Allowing you to automate the review process on your private or public repositories --- ## Usage and Tools