apps/docs/connectors/github.mdx
Connect GitHub repositories to sync documentation files into your Supermemory knowledge base with OAuth authentication, webhook support, and automatic incremental syncing.
<Warning> The GitHub connector requires a **Scale Plan** or **Enterprise Plan**. </Warning>const client = new Supermemory({
apiKey: process.env.SUPERMEMORY_API_KEY!
});
const connection = await client.connections.create('github', {
redirectUrl: 'https://yourapp.com/auth/github/callback',
containerTags: ['user-123', 'github-sync'],
documentLimit: 5000,
metadata: {
source: 'github',
team: 'engineering'
}
});
// Redirect user to GitHub OAuth
window.location.href = connection.authLink;
console.log('Auth expires in:', connection.expiresIn);
```
client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))
connection = client.connections.create(
'github',
redirect_url='https://yourapp.com/auth/github/callback',
container_tags=['user-123', 'github-sync'],
document_limit=10000,
metadata={
'source': 'github',
'team': 'engineering'
}
)
# Redirect user to GitHub OAuth
print(f'Redirect to: {connection.auth_link}')
print(f'Expires in: {connection.expires_in}')
```
After the user grants permissions, GitHub redirects to your callback URL. The connection is automatically established, and the user can now select which repositories to sync.
Unlike other connectors, GitHub requires repository selection before syncing begins. This gives your users control over which repositories to index.
<Note> **Generic Endpoints:** GitHub uses the generic resource management endpoints (Get Resources and Configure Connection) that work for any provider supporting resource management. See [Managing Connection Resources](/memory-api/connectors/managing-resources) for detailed API documentation. </Note> <Tabs> <Tab title="TypeScript"> ```typescript // List available repositories for the user const repositories = await client.connections.github.listRepositories( connectionId, { page: 1, perPage: 100 } );// Display repositories in your UI
repositories.forEach(repo => {
console.log(`${repo.full_name} - ${repo.description}`);
console.log(`Private: ${repo.private}`);
console.log(`Default branch: ${repo.default_branch}`);
console.log(`Last updated: ${repo.updated_at}`);
});
// After user selects repositories, configure them
await client.connections.github.configure(connectionId, {
repositories: [
{
id: repo.id,
name: repo.full_name,
defaultBranch: repo.default_branch
}
]
});
console.log('Repository sync initiated');
```
# Display repositories in your UI
for repo in repositories:
print(f'{repo.full_name} - {repo.description}')
print(f'Private: {repo.private}')
print(f'Default branch: {repo.default_branch}')
print(f'Last updated: {repo.updated_at}')
# After user selects repositories, configure them
client.connections.github.configure(
connection_id,
repositories=[
{
'id': repo.id,
'name': repo.full_name,
'defaultBranch': repo.default_branch
}
]
)
print('Repository sync initiated')
```
# Configure selected repositories
curl -X POST "https://api.supermemory.ai/v3/connections/{connectionId}/configure" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"resources": [
{
"id": 123456789,
"name": "your-org/documentation",
"defaultBranch": "main"
},
{
"id": 987654321,
"name": "your-org/api-docs",
"defaultBranch": "main"
}
]
}'
```
Supermemory provides the API endpoints to list and configure repositories. As a Supermemory customer, you need to build the UI in your application where your end-users can:
This gives you complete control over the user experience and allows you to integrate repository selection seamlessly into your application's workflow. </Warning>
The GitHub connector syncs documentation and text files with the following extensions:
.md, .mdx, .markdown.txt.rst.adoc.orgFiles are indexed as github_markdown document type in Supermemory.
The GitHub connector automatically sets up webhooks for real-time incremental syncing. When files are pushed or deleted in configured repositories, Supermemory is notified immediately.
<Note> **Batch Processing:** Webhook events are processed in batches with a 10-minute delay to optimize performance and prevent excessive syncing during rapid commits. This means changes pushed to your repository will be reflected in Supermemory within approximately 10 minutes. </Note>Webhooks are secured using HMAC-SHA256 signature validation with constant-time comparison. Supermemory automatically validates that webhook events come from GitHub before processing them. Each repository gets a unique webhook secret for maximum security.
<Tabs> <Tab title="TypeScript"> ```typescript // Check webhook status const connection = await client.connections.get(connectionId);console.log('Webhooks configured:', connection.metadata.webhooks?.length);
console.log('Last sync:', new Date(connection.metadata.lastSyncedAt));
console.log('Repositories:', connection.metadata.repositories);
```
print(f'Webhooks configured: {len(connection.metadata.get("webhooks", []))}')
print(f'Last sync: {connection.metadata.get("lastSyncedAt")}')
print(f'Repositories: {connection.metadata.get("repositories")}')
```
connections.forEach(conn => {
console.log(`Provider: ${conn.provider}`);
console.log(`ID: ${conn.id}`);
console.log(`Email: ${conn.email}`);
console.log(`Created: ${conn.createdAt}`);
console.log(`Document limit: ${conn.documentLimit}`);
console.log(`Repositories: ${conn.metadata.repositories?.length || 0}`);
console.log('---');
});
```
for conn in connections:
print(f'Provider: {conn.provider}')
print(f'ID: {conn.id}')
print(f'Email: {conn.email}')
print(f'Created: {conn.created_at}')
print(f'Document limit: {conn.document_limit}')
print(f'Repositories: {len(conn.metadata.get("repositories", []))}')
print('---')
```
You can update which repositories are synced at any time:
<Tabs> <Tab title="TypeScript"> ```typescript // Add or remove repositories await client.connections.github.configure(connectionId, { repositories: [ { id: 123456789, name: 'your-org/documentation', defaultBranch: 'main' }, { id: 987654321, name: 'your-org/new-repo', defaultBranch: 'develop' // Can specify different branch } ] });console.log('Repository configuration updated');
```
print('Repository configuration updated')
```
// Or delete by provider (requires container tags)
const result = await client.connections.deleteByProvider('github', {
containerTags: ['user-123']
});
console.log('Deleted connection:', result.id);
```
# Or delete by provider (requires container tags)
result = client.connections.delete_by_provider(
provider='github',
container_tags=['user-123']
)
print(f'Deleted connection: {result.id}')
```
Trigger a manual synchronization for all configured repositories:
<Tabs> <Tab title="TypeScript"> ```typescript // Trigger sync for GitHub connections await client.connections.import('github');// Trigger sync for specific container tags
await client.connections.import('github', {
containerTags: ['user-123']
});
console.log('Manual sync initiated');
```
# Trigger sync for specific container tags
client.connections.import_(
'github',
container_tags=['user-123']
)
print('Manual sync initiated')
```
# Trigger sync for specific container tags
curl -X POST "https://api.supermemory.ai/v3/connections/github/import" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"containerTags": ["user-123"]
}'
# Response: {"message": "Manual sync initiated", "provider": "github"}
```
For white-label deployments or custom branding, configure your own GitHub OAuth app using the settings API:
<Tabs> <Tab title="TypeScript"> ```typescript // Update organization settings with your GitHub OAuth app await client.settings.update({ githubCustomKeyEnabled: true, githubClientId: 'Iv1.1234567890abcdef', githubClientSecret: 'your-github-client-secret' });// Get current settings
const settings = await client.settings.get();
console.log('GitHub custom key enabled:', settings.githubCustomKeyEnabled);
console.log('Client ID configured:', !!settings.githubClientId);
```
# Get current settings
settings = client.settings.get()
print(f'GitHub custom key enabled: {settings.github_custom_key_enabled}')
print(f'Client ID configured: {bool(settings.github_client_id)}')
```
# Get current settings
curl -X GET "https://api.supermemory.ai/v3/settings" \
-H "Authorization: Bearer $SUPERMEMORY_API_KEY"
```
https://api.supermemory.ai/v3/connections/auth/callback/githubAfter configuration, all new GitHub connections will use your custom OAuth app instead of Supermemory's default app. </Note>