mirror of
https://github.com/Sea-Haven-Industries/open-swe.git
synced 2026-10-02 07:23:15 +00:00
docs: update documentation for Open SWE PR tagging feature (#785)
* Apply patch [skip ci] * Apply patch [skip ci] * Apply patch [skip ci] * Apply patch [skip ci] * cr --------- Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com> Co-authored-by: Brace Sproul <braceasproul@gmail.com>
This commit is contained in:
open-swe[bot]
GitHub
parent
df43631d59
commit
92223cc25f
4 changed files with 197 additions and 1 deletions
|
|
@ -23,6 +23,7 @@
|
|||
"usage/intro",
|
||||
"usage/ui",
|
||||
"usage/github",
|
||||
"usage/pr-tagging",
|
||||
"usage/examples",
|
||||
"usage/best-practices",
|
||||
"usage/custom-rules"
|
||||
|
|
@ -83,3 +84,4 @@
|
|||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -180,7 +180,7 @@ Before starting, ensure you have the following installed:
|
|||
This gif shows how/where to enable the permissions on the GitHub App:
|
||||
<iframe
|
||||
className="w-full aspect-video rounded-xl"
|
||||
src="https://www.youtube.com/embed/FP02bprNtrA"
|
||||
src="https://www.youtube.com/embed/rw6ddYmiTMo"
|
||||
title="Permissions Walkthrough"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
|
|
@ -189,6 +189,9 @@ Before starting, ensure you have the following installed:
|
|||
### Subscribe to Events
|
||||
|
||||
- ✅ **Issues** - Required for webhook functionality
|
||||
- ✅ **Pull request review** - Required for PR tagging functionality
|
||||
- ✅ **Pull request review comment** - Required for PR tagging functionality
|
||||
- ✅ **Issue comment** - Required for PR tagging functionality
|
||||
|
||||
### Installation Settings
|
||||
|
||||
|
|
@ -287,3 +290,4 @@ Once both servers are running:
|
|||
- Learn about [Authentication](/labs/swe/setup/authentication) to understand how the GitHub App integration works
|
||||
- Explore [Usage](/labs/swe/usage/intro) to start using Open SWE for code changes
|
||||
- Review the [Monorepo Structure](/labs/swe/setup/monorepo) for development best practices
|
||||
|
||||
|
|
|
|||
187
apps/docs/usage/pr-tagging.mdx
Normal file
187
apps/docs/usage/pr-tagging.mdx
Normal file
|
|
@ -0,0 +1,187 @@
|
|||
---
|
||||
title: "PR Tagging"
|
||||
description: "How to trigger Open SWE runs by tagging it in PR comments and reviews"
|
||||
---
|
||||
|
||||
<Warning>
|
||||
PR tagging functionality is **not available** on the demo application at [swe.langchain.com](https://swe.langchain.com). To use PR tagging, you must self-host Open SWE following the [development setup guide](/labs/swe/setup/development).
|
||||
</Warning>
|
||||
|
||||
# PR Tagging Integration
|
||||
|
||||
Open SWE supports triggering automated runs directly from pull request interactions by tagging the agent in comments and reviews. This feature provides a seamless way to request code changes, ask questions, or resolve review feedback without leaving the GitHub interface.
|
||||
|
||||
## How PR Tagging Works
|
||||
|
||||
You can trigger Open SWE by mentioning `@open-swe` in any of the following contexts:
|
||||
|
||||
### PR Reviews
|
||||
- **Leave a review** on a pull request and tag `@open-swe` in the review body
|
||||
- Open SWE will process the entire review and resolve all comments within it
|
||||
- Ideal for comprehensive feedback that requires multiple changes
|
||||
|
||||
### Review Comments
|
||||
- **Tag `@open-swe`** in specific line-by-line review comments
|
||||
- Open SWE will focus on resolving that particular comment
|
||||
- Perfect for targeted fixes on specific code sections
|
||||
|
||||
### General PR Comments
|
||||
- **Comment on the PR** and tag `@open-swe` to request general changes
|
||||
- Open SWE will implement the requested modifications
|
||||
- Best for broader changes or new feature requests
|
||||
|
||||
<Note>
|
||||
Each time you tag `@open-swe`, it creates a **new independent run**. Multiple tags in the same comment or across different comments will result in separate runs being executed.
|
||||
</Note>
|
||||
|
||||
## Context and Security Considerations
|
||||
|
||||
<Warning>
|
||||
**Security Notice**: When you tag Open SWE in a PR, it will have access to **all comments, reviews, and review comments** on that pull request, along with any linked issues. Be aware of potential prompt injection attacks and avoid including sensitive information in PR discussions, or linked issues, when using this feature.
|
||||
</Warning>
|
||||
|
||||
### What Context is Included
|
||||
|
||||
When Open SWE processes a PR tagging request, it automatically gathers:
|
||||
|
||||
- **All PR comments** (general discussion comments)
|
||||
- **All reviews** (including their associated review comments)
|
||||
- **All review comments** (line-by-line feedback)
|
||||
- **Linked issues** referenced in the PR description (issue title and description)
|
||||
|
||||
### Linked Issues Detection
|
||||
|
||||
Open SWE automatically detects and includes linked issues using these keywords in the PR description:
|
||||
- `fixes #123` or `fix #123`
|
||||
- `closes #456` or `close #456`
|
||||
- `resolves #789` or `resolve #789`
|
||||
|
||||
When these patterns are found, Open SWE will include the issue title and description as additional context for better understanding of the requirements.
|
||||
|
||||
## How Open SWE Responds
|
||||
|
||||
Open SWE can handle both **code changes** and **questions** depending on your request:
|
||||
|
||||
### Code Changes
|
||||
When you request code modifications, Open SWE will:
|
||||
1. **Create a new branch** pointing to the original PR branch
|
||||
2. **Implement the requested changes** on this new branch
|
||||
3. **Create a new pull request** with the changes
|
||||
4. **Link the new PR** back to the original PR for easy review
|
||||
|
||||
This workflow ensures your original PR remains unchanged while allowing you to review the proposed modifications separately.
|
||||
|
||||
### Questions and Investigations
|
||||
Open SWE can also respond to questions that don't require code changes:
|
||||
- Ask about code functionality or architecture decisions
|
||||
- Request explanations of existing implementations
|
||||
- Get suggestions for alternative approaches
|
||||
|
||||
### Response Types by Comment Location
|
||||
|
||||
**Review Comments (line-by-line)**
|
||||
- Open SWE replies **directly to the review comment**
|
||||
- Response appears in the same conversation thread
|
||||
|
||||
**Review Messages (overall review)**
|
||||
- Open SWE creates a **new comment** on the PR
|
||||
- Quotes the original review and tags the reviewer
|
||||
- Provides a comprehensive response to the review
|
||||
|
||||
**General PR Comments**
|
||||
- Open SWE creates a **new comment** on the PR
|
||||
- Quotes the original comment and tags the commenter
|
||||
- Addresses the specific request or question
|
||||
|
||||
## Getting Started
|
||||
|
||||
To start using PR tagging:
|
||||
|
||||
1. **Ensure Open SWE is properly configured** for your repository (see self-hosting section below)
|
||||
2. **Navigate to any pull request** in a repository where Open SWE is installed
|
||||
3. **Leave a comment, review, or review comment** describing what you want
|
||||
4. **Tag `@open-swe`** anywhere in your message
|
||||
5. **Wait for Open SWE to respond** - it will reply immediately and begin processing
|
||||
|
||||
### Example Usage
|
||||
|
||||
```markdown
|
||||
@open-swe can you refactor this function to use async/await instead of promises?
|
||||
```
|
||||
|
||||
```markdown
|
||||
This code looks good overall, but I think we need better error handling.
|
||||
@open-swe please add try-catch blocks and proper error logging.
|
||||
```
|
||||
|
||||
```markdown
|
||||
@open-swe what's the performance impact of this approach compared to the previous implementation?
|
||||
```
|
||||
|
||||
## Self-Hosting Configuration
|
||||
|
||||
To use PR tagging with your self-hosted Open SWE instance, you'll need to configure a custom trigger username:
|
||||
|
||||
### Step 1: Create a GitHub User Account
|
||||
|
||||
Create a dedicated GitHub user account that will serve as your tagging trigger:
|
||||
- Choose a username that's easy to remember (e.g., matching your GitHub App name)
|
||||
- This account doesn't need any special permissions - it's just used for tagging
|
||||
|
||||
### Step 2: Update the Trigger Function
|
||||
|
||||
Modify the `mentionsGitHubUserForTrigger` function in `apps/open-swe/src/routes/github/utils.ts`:
|
||||
|
||||
```typescript
|
||||
export function mentionsGitHubUserForTrigger(commentBody: string): boolean {
|
||||
return /@your-custom-username\b/.test(commentBody);
|
||||
}
|
||||
```
|
||||
|
||||
Replace `your-custom-username` with the GitHub username you created.
|
||||
|
||||
### Step 3: Set Environment Variable
|
||||
|
||||
Add the trigger username to your environment configuration in `apps/open-swe/.env`:
|
||||
|
||||
```bash
|
||||
GITHUB_TRIGGER_USERNAME="your-custom-username"
|
||||
```
|
||||
|
||||
This should match the username from Step 1 (without the @ symbol).
|
||||
|
||||
### Step 4: Update Allowed Users
|
||||
|
||||
Add the GitHub usernames who should be allowed to trigger runs to the `ALLOWED_USERS` list in `packages/shared/src/github/allowed-users.ts`:
|
||||
|
||||
```typescript
|
||||
export const ALLOWED_USERS = [
|
||||
"your-github-username",
|
||||
"teammate-username",
|
||||
// ... other allowed users
|
||||
];
|
||||
```
|
||||
|
||||
<Tip>
|
||||
After making these configuration changes, restart your Open SWE instance to ensure the new settings take effect. You can then test the functionality by tagging your custom username in a PR comment.
|
||||
</Tip>
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Be specific** in your requests to get better results
|
||||
- **Use separate tags** for different types of changes to keep runs focused
|
||||
- **Review generated PRs** before merging to ensure quality
|
||||
- **Be mindful of context** - avoid sensitive information in PR discussions
|
||||
- **Test with simple requests** first when setting up self-hosting
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If PR tagging isn't working:
|
||||
|
||||
1. **Check GitHub App permissions** - Ensure you have the required event subscriptions enabled
|
||||
2. **Verify environment variables** - Confirm `GITHUB_TRIGGER_USERNAME` is set correctly
|
||||
3. **Review allowed users** - Make sure your GitHub username is in the `ALLOWED_USERS` list
|
||||
4. **Check webhook configuration** - Ensure webhooks are properly configured and receiving events
|
||||
5. **Monitor logs** - Check the Open SWE logs for any error messages or debugging information
|
||||
|
||||
For additional help, refer to the [development setup guide](/labs/swe/setup/development) or check the GitHub repository for troubleshooting resources.
|
||||
|
|
@ -34,6 +34,8 @@ GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
|
|||
"
|
||||
# Secret key for verifying GitHub webhook events.
|
||||
GITHUB_WEBHOOK_SECRET=""
|
||||
# GitHub username to tag for triggering runs from PR comments (without the @ symbol)
|
||||
GITHUB_TRIGGER_USERNAME="open-swe"
|
||||
|
||||
|
||||
# ------------------------Other------------------------
|
||||
|
|
@ -55,3 +57,4 @@ SKIP_CI_UNTIL_LAST_COMMIT="true"
|
|||
# For the CLI to work, you need to set these variables.
|
||||
# OPEN_SWE_LOCAL_MODE=false
|
||||
# OPEN_SWE_LOCAL_PROJECT_PATH=""
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue