GitHub Auto-Sync

Connect your repository once and keep docs, supported code, and supported binary files current automatically. Snipara preserves the right lane for each file so retrieval stays clean.

How It Works

Supported File Types

GitHub sync has three ingestion lanes. Documentation and supported binary parsers feed snipara_context_query. Source code is stored as CODE documents and indexed into the code graph for structural tools such as snipara_code_callers.

What's NOT Synced

The following are automatically excluded from sync:

• Unsupported binaries - videos, compiled assets, and image formats without a parser
• Large files - Files over 1MB
• Dependencies - node_modules/, vendor/, .venv/
• Build outputs - dist/, build/, .next/
• Version control - .git/
• Minified files - *.min.js, *.min.css
• Lock files - package-lock.json, yarn.lock, pnpm-lock.yaml

Viewing Sync Status

Check your sync status in the dashboard:

1. Navigate to Project → Settings → GitHub
2. View the sync panel showing:
   • Last sync time - When docs were last updated
   • Commit SHA - The Git commit that was synced
   • Document count - Number of files indexed
   • Webhook status - Whether push events are wired, disabled, missing, or need attention
3. Yellow indicator means pending changes detected
4. Click Sync Now to trigger a manual sync

Setup Guide

Step 1: Connect Your GitHub Account

1. Go to Settings in your Snipara dashboard
2. Click Connect GitHub in the Integrations section
3. Authorize Snipara to access your repositories

Step 2: Configure Repository

In your project settings, configure the GitHub sync:

Step 3: Initial Sync

Save settings first. If Auto-Sync is enabled, Snipara creates or repairs the repository webhook. Then click Sync Now to perform the initial sync. Snipara will:

1. Fetch all matching files from your repository
2. Create document records for each file
3. Generate embeddings for semantic search
4. Record the latest commit SHA for change detection

Step 4: Webhook Status

The GitHub Sync panel shows the current delivery state so you can tell whether future commits will sync automatically:

Path Filtering

You can limit which files are synced using path filters. Snipara supports both directory paths and glob patterns:

Directory Paths

docs/

→ Syncs all files in docs/ and subdirectories

src/components/

→ Syncs all files in src/components/

Glob Patterns

*.md

→ All .md files in root directory

**/*.md

→ All .md files in any directory (recursive)

docs/**/*.mdx

→ All .mdx files under docs/

Multiple Filters

Separate multiple paths or patterns with commas:

docs/, README.md, CONTRIBUTING.md

→ All docs + specific files

**/*.md, **/*.mdx

→ All markdown and MDX files

Sync Behavior

Incremental Updates

Snipara uses content hashing to detect changes. On each sync:

Sync Results

After each sync, you'll see a summary:

{
  "message": "Sync completed",
  "created": 5,
  "updated": 2,
  "deleted": 1,
  "unchanged": 42,
  "errors": []
}

Manual vs Automatic Sync

API Reference

Get Sync Status

GET /api/projects/{projectId}/github
X-API-Key: snp-...

Response:
{
  "isGitHubConnected": true,
  "project": {
    "githubRepo": "acme/docs",
    "githubBranch": "main",
    "githubPath": "docs/",
    "githubLastSyncAt": "2025-01-20T12:00:00Z",
    "githubLastCommitSha": "abc123...",
    "githubSyncEnabled": true,
    "githubWebhookId": "123456789",
    "documentCount": 45
  },
  "webhookStatus": {
    "configured": true,
    "managed": true,
    "hookId": "123456789",
    "active": true,
    "events": ["push", "pull_request"],
    "lastResponse": {
      "code": 200,
      "status": "active",
      "message": "OK"
    },
    "error": null
  },
  "branches": ["main", "develop"],
  "hasChanges": true,
  "latestSha": "def456..."
}

Configure Sync

PUT /api/projects/{projectId}/github
Content-Type: application/json

{
  "githubRepo": "acme/docs",
  "githubBranch": "main",
  "githubPath": "docs/",
  "githubSyncEnabled": true
}

When githubSyncEnabled is true, saving settings also creates or repairs the GitHub push webhook. If GitHub does not allow webhook management, the settings still save and the dashboard shows manual fallback details.

Trigger Sync

POST /api/projects/{projectId}/github

Response:
{
  "message": "Sync completed",
  "created": 5,
  "updated": 2,
  "deleted": 1,
  "unchanged": 42,
  "errors": []
}

Private Repositories

Snipara fully supports private repositories. When connecting your GitHub account, you grant read access to your private repos. The sync process:

1. Uses your OAuth token to authenticate with GitHub API
2. Falls back to Contents API when download URLs aren't available
3. Decodes base64 content for private repo files
4. Never stores your GitHub credentials - only OAuth tokens

Troubleshooting

Rate Limiting

Snipara includes a 100ms delay between file downloads to avoid hitting GitHub's rate limits. For large repositories, consider:

• Using path filters to limit the number of files
• Syncing during off-peak hours
• Keeping Auto-Sync enabled so GitHub sends only push events that need processing

Next Steps