Skip to content

Sync Settings

Jump to bottom
Björn Platte edited this page Jan 16, 2026 · 1 revision

Sync Settings

Configure how and when the plugin synchronizes with GitHub.

Manual Sync

Ribbon Icon

Click the GitHub sync icon in the left ribbon to trigger a full sync.

Command

Use the command palette: Sync GitHub issues & pull requests

Automatic Sync

Sync on Startup

When enabled, automatically syncs all repositories and projects when Obsidian starts.

Default: Enabled

Background Sync

Enable periodic automatic synchronization while Obsidian is running.

Sync Interval

How often to sync in the background.

  • Minimum: 5 minutes
  • Recommended: 15-30 minutes

Higher intervals reduce API usage and improve performance.

Cleanup Settings

Cleanup Closed Items After (Days)

Automatically delete local files for items that have been closed for longer than the specified number of days.

  • Minimum: 1 day
  • Default: 30 days
  • Tip: Set higher if you want to keep closed items longer

What Gets Cleaned Up

Files are deleted when:

  1. The issue/PR is closed longer than the cleanup period
  2. The item no longer matches your filters (labels, assignees)
  3. The item was deleted on GitHub
  4. The repository/project was removed from tracking

Per-File Override

Each file has an allowDelete frontmatter property:

---
allowDelete: true
---

Set to false to prevent automatic deletion of a specific file.

Notification Level

Control how many notifications you see during sync:

Level Shows
Minimal Only errors and important messages
Normal Start/end of sync, errors
Extensive Detailed progress for each repository
Debug All debug messages (for troubleshooting)

Sync Behavior

What Gets Synced

Each sync operation:

  1. Fetches issues matching your filters
  2. Fetches pull requests matching your filters
  3. Creates new files for new items
  4. Updates existing files (based on update mode)
  5. Removes files for deleted/filtered items
  6. Cleans up old closed items

Update Detection

Files are only updated when:

  • The updated_at timestamp on GitHub is newer
  • The issue/PR state changed (open ↔ closed)

This prevents unnecessary file modifications.

Persist Blocks

Content inside Persist-Blocks is preserved during updates, even when using "Update" mode.

Rate Limiting

The plugin respects GitHub API rate limits:

  • Authenticated: 5,000 requests/hour
  • Sync operations are optimized to minimize API calls
  • Background sync helps spread requests over time

Tips

  1. Start with manual sync to verify your settings work correctly
  2. Use background sync for hands-free updates
  3. Set reasonable intervals (15+ minutes) to avoid hitting rate limits
  4. Use filters to reduce the number of items synced
  5. Check notification level if sync seems slow - Debug mode shows detailed progress

Clone this wiki locally