github connector docs

[nexxeln]

No description provided.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
❌ Deployment failed View logs	supermemory-app	8f1ba87	Dec 02 2025, 08:30 PM

[nexxeln]

• github connector docs #594 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label Main to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Pull Request Review: GitHub Connector Documentation

Thank you for this comprehensive documentation addition! Overall, this is excellent, high-quality documentation that follows the established patterns and will be very helpful for users. Below are my findings across various review dimensions:

---

✅ Strengths

1. Excellent Structure and Consistency

• Follows the exact same pattern as existing connector docs (Google Drive, Notion)
• Code examples provided in TypeScript, Python, and cURL for every operation
• Progressive complexity: starts simple, builds to advanced features
• Clear section hierarchy with appropriate use of headings

2. Comprehensive Coverage

• Covers the full connection lifecycle: create → configure → manage → delete
• Documents GitHub-specific features (repository selection, webhooks, file types)
• Includes advanced configuration (custom OAuth apps)
• Good use of callouts, notes, and warnings for important information

3. API-First Design Clarity

• The Warning section clearly explains that Supermemory provides APIs, not UI (lines 208-218)
• Sets proper expectations about customer implementation responsibilities
• This is a critical distinction that could prevent confusion

---

🔍 Issues Found

1. Critical: Inconsistent Document Deletion Behavior ⚠️

Location: Line 468

- **Permanently delete all synced documents** from your Supermemory knowledge base

Issue: This contradicts other connectors:

• Google Drive (line 253): "Keep existing synced documents in Supermemory (they won't be deleted)"
• Notion (line 231): "Keep existing synced documents in Supermemory (they won't be deleted)"

Questions:

1. Does GitHub connector actually delete documents, or is this copy-paste error?
2. If it does delete documents, why is GitHub different from other connectors?
3. This is a critical data loss warning that must be accurate

Recommendation: Verify actual deletion behavior and ensure consistency across all connector docs.

---

2. Minor: Webhook Configuration Response Inconsistency

Location: Line 205

{
  "message": "Repository sync initiated",
  "repositories": 2,
  "webhookConfigured": true
}

Issue: Response format differs from other patterns:

• Uses webhookConfigured (boolean) in response
• But metadata uses webhookConfigured elsewhere (line 263)
• Inconsistent casing: some places use webhook_configured (Python style)

Impact: Low - documentation only
Recommendation: Verify actual API response format and normalize casing conventions.

---

3. Minor: Missing Error Handling Examples

Observation: Unlike Notion docs which mention API rate limits and limitations (lines 422-429), the GitHub docs don't mention:

• GitHub API rate limits (5000/hour for authenticated requests)
• Potential 409 conflicts when repository already configured
• Webhook delivery failures
• What happens when user lacks admin:repo_hook permission

Recommendation: Add a "Common Issues" or "Troubleshooting" section, or reference the general troubleshooting doc.

---

4. Minor: Metadata Field Inconsistency

Location: Lines 263-264

console.log('Webhook configured:', connection.metadata.webhookConfigured);
console.log('Last sync:', connection.metadata.lastSyncedAt);

Issue: The initial connection creation example (lines 22-30) shows different metadata:

metadata: {
  source: 'github',
  team: 'engineering'
}

Questions:

1. Are webhookConfigured and lastSyncedAt automatically added by Supermemory?
2. Should this be documented in the response format?

Impact: Low - may confuse users about what metadata they can access
Recommendation: Add a note explaining that Supermemory adds system metadata fields automatically.

---

🎨 Style & Best Practices

Excellent:

• ✅ Consistent use of code examples
• ✅ Proper use of tabs for multi-language support
• ✅ Good balance of technical detail and readability
• ✅ Appropriate use of callouts and warnings
• ✅ Clear distinction between user-provided and system-generated data

Could Improve:

• Consider adding a "Prerequisites" section mentioning GitHub account requirements
• Could benefit from a "How It Works" diagram or flow for the repository selection process
• Consider linking to GitHub's official OAuth documentation

---

🔒 Security Considerations

Good:

• ✅ Mentions OAuth scopes required (line 87)
• ✅ Documents webhook security with HMAC-SHA256 (line 247)
• ✅ Shows proper environment variable usage for secrets
• ✅ Documents custom OAuth app setup securely

Potential Concerns:

• Consider adding: Recommendation to rotate GitHub OAuth secrets periodically
• Consider adding: Note about webhook endpoint security requirements
• Consider adding: Mention that repo scope grants access to private repositories (line 88)

---

📊 Test Coverage

N/A - This is documentation only, no code to test.

Recommendation: Consider adding:

• Example integration tests that customers can reference
• Link to example implementation repository
• Common code patterns for handling webhook events

---

⚡ Performance Considerations

Documented Well:

• ✅ File type filtering to limit sync scope (lines 225-234)
• ✅ Document limits configuration (line 27)
• ✅ Incremental sync via webhooks (lines 237-282)

Could Add:

• Mention expected initial sync times for large repositories
• Guidance on repository size limits
• Rate limiting considerations

---

🎯 Recommendations Summary

Must Fix Before Merge:

1. Verify and fix document deletion behavior documentation (critical data loss implications)

Should Fix:

2. Verify API response formats match actual implementation
3. Add error handling/troubleshooting section or reference
4. Clarify which metadata fields are system-generated

Nice to Have:

5. Add prerequisites section
6. Link to example implementations
7. Add visual diagram for repository selection flow
8. Expand security best practices section

---

📝 Overall Assessment

Quality: ⭐⭐⭐⭐½ (4.5/5)

• Excellent structure and comprehensiveness
• One critical issue to verify (deletion behavior)
• Minor inconsistencies to address
• Overall, this is production-ready documentation with minor fixes needed

Recommendation: ✅ Approve with minor changes requested

Focus on verifying the document deletion behavior first, as this has data loss implications. Everything else is minor polish.

Great work on maintaining consistency with existing docs! 🎉