GitHub Sync Feature

Overview

The GitHub Sync feature allows you to backup and synchronize your Curlex data (collections, environments, tabs, and workspaces) to a GitHub repository. This provides a reliable backup solution and enables data portability across different machines.

Features

  • Secure Storage: Your GitHub Personal Access Token (PAT) is stored securely using the system keychain
  • Multi-File Sync: Data is split into separate files to avoid GitHub's 100MB file size limit
  • Automatic Sync: Changes are automatically synced to GitHub with a 5-second debounce
  • Manual Sync: Trigger sync manually using the Sync button in the toolbar
  • Startup Sync: Automatically pulls latest data from GitHub when the app starts
  • Conflict Resolution: Uses a last-write-wins strategy to handle conflicts
  • Test Connection: Verify your GitHub credentials before enabling sync

Setup Instructions

1. Create a GitHub Personal Access Token

  1. Go to GitHub Settings > Tokens
  2. Click "Generate new token (classic)"
  3. Give your token a descriptive name (e.g., "Curlex Sync")
  4. Select the repo scope (Full control of private repositories)
  5. Set an expiration date (recommended: 90 days or no expiration)
  6. Click "Generate token"
  7. Important: Copy the token immediately - you won't be able to see it again!

2. Create a Repository for Sync

You can use an existing repository or create a new one:

  1. Go to GitHub
  2. Click the "+" icon in the top right
  3. Select "New repository"
  4. Name it (e.g., "curlex-backup")
  5. Make it Private to keep your API data secure
  6. Initialize it (optional - Curlex will create the file automatically)

3. Configure GitHub Sync in Curlex

  1. Open Curlex
  2. Click the Settings icon or press Ctrl+, (Windows/Linux) or Cmd+, (Mac)
  3. Navigate to the "GitHub Sync" tab
  4. Enter your GitHub Personal Access Token and click "Store"
  5. Fill in the repository details:
    • Repository Owner: Your GitHub username or organization name
    • Repository Name: The name of your repository
    • Branch: The branch to use (default: main)
    • Sync Format: Choose between Multi-File (Recommended) or Single File (Legacy)
    • Commit Message Pattern: Pattern for commit messages (use {timestamp} for current date/time)
  6. Click "Test Connection" to verify your setup
  7. Enable GitHub Sync using the toggle switch

Using GitHub Sync

Manual Sync

Click the Sync button in the toolbar (cloud icon) to manually trigger a sync operation. This will:

  1. Pull the latest data from GitHub
  2. Compare timestamps
  3. If remote is newer, update local data
  4. If local is newer, push local data to GitHub

Automatic Sync

When GitHub Sync is enabled, Curlex automatically syncs your data:

  • On Save: After creating, updating, or deleting collections, environments, or workspaces (with 5-second debounce)
  • On Startup: When you open the app, it pulls the latest data from GitHub

Conflict Resolution

Curlex uses a last-write-wins strategy:

  • Each sync operation includes a timestamp
  • When syncing, timestamps are compared
  • The data with the most recent timestamp is kept
  • This ensures you always have the latest version

Note: This means if you make changes on multiple devices simultaneously, only the last saved changes will be preserved.

Sync Data Structure

Data is split into separate files stored in a .curlex/ directory:

.curlex/
  ├── manifest.json       # Tracks all files and sync timestamps
  ├── collections.json    # Your API collections
  ├── environments.json   # Environment variables
  ├── tabs.json          # Open tabs
  ├── workspaces.json    # Workspace configuration
  └── settings.json      # App settings

Benefits:

  • No single file exceeds GitHub's 100MB limit
  • Better organization and easier inspection
  • More scalable as your data grows
  • Each file syncs independently

Single File Format (Legacy)

All data in one file (curlex-data.json):

{
  "collections": [...],
  "environments": [...],
  "tabs": [...],
  "workspaces": [...],
  "settings": {...},
  "lastSync": 1234567890
}

Note: Single file format is kept for backward compatibility but may hit the 100MB limit with large collections.

Security Considerations

Personal Access Token Storage

  • Your PAT is stored securely using your system's keychain:
    • macOS: Keychain Access
    • Windows: Windows Credential Manager
    • Linux: libsecret
  • The PAT is never displayed in the UI after storage
  • The PAT is never included in the synced data file

Repository Privacy

  • Always use a private repository for syncing
  • Your API collections may contain sensitive information (API keys, tokens, etc.)
  • Never share your sync repository publicly

Best Practices

  1. Use a dedicated PAT for Curlex (not your main GitHub token)
  2. Set an expiration date on your PAT
  3. Use a private repository
  4. Regularly review your GitHub security settings
  5. Revoke and regenerate PATs periodically

Troubleshooting

"Connection failed" Error

Possible causes:

  • Invalid Personal Access Token
  • Incorrect repository owner or name
  • Repository doesn't exist
  • PAT doesn't have repo scope
  • Network connectivity issues

Solutions:

  1. Verify your PAT has the repo scope
  2. Double-check repository owner and name (case-sensitive)
  3. Ensure the repository exists and is accessible
  4. Test your network connection

"GitHub sync not configured" Error

Solution: Complete the setup steps in Settings > GitHub Sync

Sync Button Not Appearing

Solution: Enable GitHub Sync in Settings > GitHub Sync

Data Not Syncing

Possible causes:

  • GitHub Sync is disabled
  • Network connectivity issues
  • Invalid credentials
  • Repository permissions issues

Solutions:

  1. Verify GitHub Sync is enabled in Settings
  2. Test your connection using the "Test Connection" button
  3. Check your network connection
  4. Verify repository permissions

"Sync already in progress" Error

Solution: Wait for the current sync operation to complete. Sync operations cannot run concurrently.

Limitations

  • Only one sync operation can run at a time
  • Concurrent edits on multiple devices may result in data loss (last-write-wins)
  • Single-file format: Limited by GitHub's 100MB file size restriction (use multi-file format instead)
  • Multi-file format: Each individual file limited to 100MB (unlikely to be reached per table)
  • GitHub API rate limits apply (60 requests/hour for unauthenticated, 5000/hour for authenticated)
  • Multi-file format uses 6 API calls per sync vs 1 for single-file (well within rate limits)

FAQ

Can I use the same repository for multiple devices?

Yes! That's the main purpose of this feature. Just configure each device with the same repository details.

What happens if I edit data on two devices simultaneously?

The last device to sync will overwrite the previous changes. We recommend syncing manually before making changes if you use multiple devices.

Can I disable automatic sync?

Yes, disable the "Enable GitHub Sync" toggle in Settings > GitHub Sync. You can still use manual sync.

Can I sync to different branches?

Yes, configure the branch name in Settings > GitHub Sync.

How do I stop syncing?

  1. Disable GitHub Sync in Settings
  2. Optionally, remove your PAT by clicking "Remove"
  3. Optionally, delete the sync file from your GitHub repository

Can I see my sync history?

Yes, check your repository's commit history on GitHub. Each sync creates a commit with your configured message pattern.

Is my data encrypted?

The PAT is encrypted using your system keychain. The sync file in GitHub is not encrypted by Curlex, but you can enable GitHub repository encryption if needed.

Should I use single-file or multi-file format?

Use Multi-File (Recommended):

  • You have many collections or large collections
  • You want to avoid the 100MB limit
  • You want better organization and scalability
  • You're starting fresh with GitHub sync

Use Single-File (Legacy):

  • You have existing synced data in single-file format
  • You have very small datasets (< 10MB)
  • You prefer simplicity over scalability

Note: You can change the format at any time in Settings, but be aware that switching formats will require a fresh sync and may cause your repository structure to change.

Support

For issues or questions:

  1. Check this documentation
  2. Review GitHub's Personal Access Tokens documentation
  3. Open an issue on the Curlex repository