From 92223cc25fc34521c8f16d90009b25415403425c Mon Sep 17 00:00:00 2001
From: "open-swe[bot]" <215916821+open-swe[bot]@users.noreply.github.com>
Date: Wed, 20 Aug 2025 11:17:56 -0700
Subject: [PATCH] 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>
---
 apps/docs/docs.json             |   2 +
 apps/docs/setup/development.mdx |   6 +-
 apps/docs/usage/pr-tagging.mdx  | 187 ++++++++++++++++++++++++++++++++
 apps/open-swe/.env.example      |   3 +
 4 files changed, 197 insertions(+), 1 deletion(-)
 create mode 100644 apps/docs/usage/pr-tagging.mdx

diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index d210e7af..063af3df 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -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 @@
     }
   }
 }
+
diff --git a/apps/docs/setup/development.mdx b/apps/docs/setup/development.mdx
index 1daf6c88..8911d162 100644
--- a/apps/docs/setup/development.mdx
+++ b/apps/docs/setup/development.mdx
@@ -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
+
diff --git a/apps/docs/usage/pr-tagging.mdx b/apps/docs/usage/pr-tagging.mdx
new file mode 100644
index 00000000..d411718a
--- /dev/null
+++ b/apps/docs/usage/pr-tagging.mdx
@@ -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.
diff --git a/apps/open-swe/.env.example b/apps/open-swe/.env.example
index 04f0209e..b863ea0c 100644
--- a/apps/open-swe/.env.example
+++ b/apps/open-swe/.env.example
@@ -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=""
+