feat: Add GitHub link unfurling documentation

Co-authored-by: neel.shah <[email protected]>

Author: cursoragent

develop-docs/integrations/github.mdx

@@ -127,3 +127,277 @@ privatekeyprivatekeyprivatekeyprivatekey
 ```
 
 Take note that your private key should be a multiline string without any whitespace before the start of a new line of the key.
+
+## Link Unfurling
+
+Link unfurling allows Sentry to display rich previews of Sentry links when they're shared in GitHub (such as in pull request descriptions, issue comments, or commit messages). This provides context about Sentry issues directly within GitHub without requiring users to click through.
+
+### Overview
+
+When a user shares a Sentry link in GitHub, the integration should:
+
+1. Detect the shared Sentry link via GitHub webhooks
+2. Parse the link to extract the issue/event ID
+3. Fetch relevant data from Sentry's API
+4. Return formatted preview data to GitHub
+
+### Implementation Steps
+
+#### 1. Configure Webhook Events
+
+Ensure your GitHub App is subscribed to events that include link sharing. While GitHub doesn't have a direct "link_shared" event like Slack, you can detect links in:
+
+- Pull request descriptions and comments
+- Issue comments
+- Commit messages
+
+The relevant webhook events are already configured if you followed the setup above:
+- `pull_request` - Captures links in PR descriptions
+- `issue_comment` - Captures links in comments
+- `push` - Captures links in commit messages
+
+#### 2. Add Link Detection Logic
+
+In your webhook handler, add logic to detect Sentry URLs in the incoming payload:
+
+```python
+import re
+from urllib.parse import urlparse
+
+SENTRY_LINK_PATTERN = re.compile(
+    r'https?://(?:[\w-]+\.)?sentry\.io/(?:organizations/[\w-]+/)?issues/(\d+)/?(?:\?.*)?'
+)
+
+def extract_sentry_links(text):
+    """Extract Sentry issue links from text."""
+    if not text:
+        return []
+    
+    matches = SENTRY_LINK_PATTERN.finditer(text)
+    return [
+        {
+            'url': match.group(0),
+            'issue_id': match.group(1)
+        }
+        for match in matches
+    ]
+```
+
+#### 3. Fetch Issue Data
+
+When a Sentry link is detected, fetch the issue details:
+
+```python
+def get_issue_preview_data(issue_id, organization_slug):
+    """Fetch issue data for preview."""
+    from sentry.models import Group
+    
+    try:
+        issue = Group.objects.get(id=issue_id)
+        
+        return {
+            'title': issue.title,
+            'status': issue.get_status_display(),
+            'level': issue.level,
+            'event_count': issue.times_seen,
+            'user_count': issue.count_unique_users(),
+            'first_seen': issue.first_seen,
+            'last_seen': issue.last_seen,
+            'permalink': issue.get_absolute_url(),
+        }
+    except Group.DoesNotExist:
+        return None
+```
+
+#### 4. Format Preview for GitHub
+
+GitHub doesn't have a native unfurling API like Slack. Instead, you can:
+
+**Option A: Add a Comment with Issue Details**
+
+Post an automated comment with rich issue details:
+
+```python
+def post_issue_preview_comment(github_client, repo, comment_id, issue_data):
+    """Post a comment with Sentry issue preview."""
+    
+    comment_body = f"""
+### 🔍 Sentry Issue Preview
+
+**{issue_data['title']}**
+
+- **Status:** {issue_data['status']}
+- **Level:** {issue_data['level']}
+- **Events:** {issue_data['event_count']}
+- **Users Affected:** {issue_data['user_count']}
+- **Last Seen:** {issue_data['last_seen']}
+
+[View in Sentry]({issue_data['permalink']})
+
+---
+*This preview was automatically generated by Sentry*
+"""
+    
+    github_client.create_comment(
+        repo=repo,
+        issue_number=comment_id,
+        body=comment_body
+    )
+```
+
+**Option B: Use GitHub Checks or Status API**
+
+For pull requests, you can use the Checks API to show Sentry issue information:
+
+```python
+def create_sentry_check(github_client, repo, commit_sha, issues):
+    """Create a GitHub check with Sentry issues."""
+    
+    if not issues:
+        return
+    
+    summary = f"Found {len(issues)} Sentry issue(s) referenced in this PR"
+    
+    text = "\\n".join([
+        f"- [{issue['title']}]({issue['permalink']}) - "
+        f"{issue['event_count']} events, {issue['user_count']} users affected"
+        for issue in issues
+    ])
+    
+    github_client.create_check_run(
+        repo=repo,
+        name="Sentry Issues",
+        head_sha=commit_sha,
+        status="completed",
+        conclusion="neutral",
+        output={
+            "title": "Sentry Issues Referenced",
+            "summary": summary,
+            "text": text
+        }
+    )
+```
+
+#### 5. Handle Webhook Events
+
+Add the unfurling logic to your webhook handler:
+
+```python
+def handle_github_webhook(event_type, payload):
+    """Handle GitHub webhook events for link unfurling."""
+    
+    if event_type == 'pull_request':
+        # Check PR description
+        pr_body = payload.get('pull_request', {}).get('body', '')
+        links = extract_sentry_links(pr_body)
+        
+        if links:
+            repo = payload['repository']['full_name']
+            pr_number = payload['pull_request']['number']
+            
+            for link in links:
+                issue_data = get_issue_preview_data(link['issue_id'], org_slug)
+                if issue_data:
+                    post_issue_preview_comment(
+                        github_client,
+                        repo,
+                        pr_number,
+                        issue_data
+                    )
+    
+    elif event_type == 'issue_comment':
+        # Check comment body
+        comment_body = payload.get('comment', {}).get('body', '')
+        links = extract_sentry_links(comment_body)
+        
+        if links:
+            # Similar logic as above
+            pass
+```
+
+### Best Practices
+
+1. **Rate Limiting**: Be mindful of GitHub's API rate limits. Cache issue data when possible.
+
+2. **Permissions**: Ensure the GitHub App has the necessary permissions:
+   - `issues: write` - To post comments on issues
+   - `pull_requests: write` - To post comments on PRs
+   - `checks: write` - To create check runs (optional)
+
+3. **Deduplication**: Track which links have already been unfurled to avoid posting duplicate previews.
+
+4. **Privacy**: Only unfurl links for issues the GitHub user has access to. Verify permissions before displaying issue details.
+
+5. **Error Handling**: Gracefully handle cases where:
+   - The issue doesn't exist
+   - The user doesn't have permission to view the issue
+   - The GitHub API request fails
+
+### Testing
+
+To test link unfurling locally:
+
+1. Use ngrok to expose your local Sentry instance
+2. Create a test GitHub repository
+3. Install your GitHub App on the test repository
+4. Create a PR or comment with a Sentry issue link
+5. Verify the webhook is received and the preview is generated
+
+### Example: Complete Webhook Handler
+
+```python
+from rest_framework.response import Response
+from rest_framework import status
+
+class GitHubWebhookEndpoint(Endpoint):
+    authentication_classes = ()
+    permission_classes = ()
+    
+    def post(self, request):
+        event_type = request.META.get('HTTP_X_GITHUB_EVENT')
+        
+        if event_type in ['pull_request', 'issue_comment']:
+            # Extract text content
+            text = self._extract_text_from_payload(request.data, event_type)
+            
+            # Find Sentry links
+            sentry_links = extract_sentry_links(text)
+            
+            if sentry_links:
+                # Process each link asynchronously
+                from sentry.tasks.integrations import unfurl_github_links
+                unfurl_github_links.apply_async(
+                    kwargs={
+                        'payload': request.data,
+                        'event_type': event_type,
+                        'links': sentry_links
+                    }
+                )
+        
+        return Response(status=status.HTTP_204_NO_CONTENT)
+    
+    def _extract_text_from_payload(self, payload, event_type):
+        if event_type == 'pull_request':
+            return payload.get('pull_request', {}).get('body', '')
+        elif event_type == 'issue_comment':
+            return payload.get('comment', {}).get('body', '')
+        return ''
+```
+
+### Configuration Options
+
+You may want to add configuration options to control link unfurling behavior:
+
+```yml
+# config.yml
+github-app.unfurl-links: true
+github-app.unfurl-method: "comment"  # or "check"
+github-app.unfurl-delay: 5  # seconds to wait before posting
+```
+
+### Resources
+
+- [GitHub REST API Documentation](https://docs.github.com/en/rest)
+- [GitHub Webhooks Documentation](https://docs.github.com/en/developers/webhooks-and-events/webhooks)
+- [GitHub Checks API](https://docs.github.com/en/rest/checks)
+- [Slack Link Unfurling](./slack/#link-unfurling) - Similar concept for reference

docs/organization/integrations/source-code-mgmt/github/index.mdx

@@ -353,19 +353,6 @@ Sentry will comment on the pull request with up to five issues per file that wer
 
 This feature requires [code mappings](/product/issues/suspect-commits/#2-set-up-code-mappings) and is currently only supported for Python, JavaScript/TypeScript, PHP, and Ruby files. If you're using a different language, [let us know on this GitHub ticket](https://github.com/getsentry/sentry/issues/69824). For JavaScript/TypeScript, please ensure that you've unminified your code by [setting up source maps](/platforms/javascript/sourcemaps/).
 
-### Link Unfurling
-
-When you share Sentry issue links in GitHub (such as in pull request descriptions, issue comments, or commit messages), Sentry can automatically unfurl these links to display rich previews with key issue details. This makes it easier to understand the context of the issue without leaving GitHub.
-
-The link preview includes:
-
-- Issue title and description
-- Issue status and priority
-- Error count and user impact
-- Link to view the full issue in Sentry
-
-This feature is automatically enabled once your GitHub integration has been set up and Sentry detects links shared in your GitHub repositories.
-
 ### Missing Member Detection
 
 If there are users committing to GitHub repositories linked to Sentry and they're not members of your organization, Sentry detects them as missing members. Once a month, Sentry sends organization owners and managers an email reminding them to invite those users to join their org. Sentry also shows a banner to invite missing members in the **Settings > Members** page.