Setup Git Sync - Auk Documentation

Why Use Git Sync?

Auk uses Git as the collaboration and backup solution instead of cloud services: ✅ Full Control - Choose any Git service (GitHub, GitLab, self-hosted) ✅ Version History - Complete change history and rollback capability ✅ Team Collaboration - Standard Git workflows ✅ Offline Work - Local changes, sync when needed ✅ Data Security - Data stored on servers you control

How It Works

Local Workspace ←→ Git Repository ←→ Team Members
    ↓
Auto-commit local changes
    ↓
Periodic sync (Pull + Push)
    ↓
Conflict detection & resolution

Supported Git Services

GitHub - Public/private repositories
GitLab - Self-hosted or GitLab.com
Gitee - Chinese Git service
Bitbucket - Atlassian Git service
Self-hosted Git - Any standard Git server

Prerequisites

Before setting up Git sync, you need:

Git installed on your system
Git repository created on your chosen service
Authentication configured (SSH keys or access token)

Check Git Installation

# Check if Git is installed
git --version

# If not installed, install Git:
# macOS: brew install git
# Windows: Download from git-scm.com
# Linux: sudo apt install git

Authentication Methods

SSH Keys (Recommended)

SSH keys provide secure, password-less authentication.

Generate SSH Key

# Generate new SSH key
ssh-keygen -t ed25519 -C "[email protected]"

# Press Enter to accept default location
# Enter passphrase (optional but recommended)

Add to SSH Agent

# Start SSH agent
eval "$(ssh-agent -s)"

# Add SSH key
ssh-add ~/.ssh/id_ed25519

Copy Public Key

# macOS
pbcopy < ~/.ssh/id_ed25519.pub

# Linux
cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard

# Windows (Git Bash)
cat ~/.ssh/id_ed25519.pub | clip

Add to Git Service

GitHub:

Go to Settings → SSH and GPG keys
Click “New SSH key”
Paste your public key
Click “Add SSH key”

GitLab:

Go to Preferences → SSH Keys
Paste your public key
Click “Add key”

Test Connection

# GitHub
ssh -T [email protected]

# GitLab
ssh -T [email protected]

# Should see: "Hi username! You've successfully authenticated"

HTTPS with Personal Access Token

For HTTPS authentication, use a personal access token.

GitHub
GitLab
Gitee

Go to Settings → Developer settings → Personal access tokens → Tokens (classic)
Click “Generate new token (classic)”
Select scopes: repo (full control of private repositories)
Click “Generate token”
Copy the token (you won’t see it again!)

Go to Preferences → Access Tokens
Enter token name
Select scopes: read_repository, write_repository
Click “Create personal access token”
Copy the token

Go to Settings → Private Tokens
Click “Generate new token”
Select scopes: projects
Click “Submit”
Copy the token

Create Git Repository

Before configuring Auk, create a repository on your Git service:

GitHub
GitLab
Command Line

# Using GitHub CLI
gh repo create my-api-collections --private

# Or via web interface:
# 1. Go to github.com
# 2. Click "+" → "New repository"
# 3. Enter repository name
# 4. Choose "Private"
# 5. Click "Create repository"

# Using GitLab CLI
glab repo create my-api-collections --private

# Or via web interface:
# 1. Go to gitlab.com
# 2. Click "New project"
# 3. Enter project name
# 4. Choose "Private"
# 5. Click "Create project"

# Create local repository
mkdir my-api-collections
cd my-api-collections
git init

# Create README
echo "# My API Collections" > README.md
git add README.md
git commit -m "Initial commit"

# Add remote (replace with your URL)
git remote add origin [email protected]:username/my-api-collections.git

# Push to remote
git push -u origin main

Configure Git in Auk

Now configure Git sync in your workspace:

Open Workspace Settings

Click workspace selector at the top
Click the gear icon next to your workspace
Or use keyboard shortcut: Cmd/Ctrl + ,

Enable Git Sync

Navigate to “Git Sync” section
Toggle “Enable Git Sync” to ON

Configure Repository

Remote URL:

# SSH (recommended)
[email protected]:username/my-api-collections.git

# HTTPS
https://github.com/username/my-api-collections.git

Branch:

main

(or master for older repositories)

Configure Authentication

SSH
HTTPS

Select “SSH” as authentication method
SSH keys are automatically used from your system
If you have a passphrase, you’ll be prompted to enter it

Test Connection

Click “Test Connection” to verify:

Repository is accessible
Authentication works
Branch exists

If successful, you’ll see: ✅ “Connection successful”

Initial Sync

Choose initial sync method:Option 1: Push Local Data

Use if you have existing collections in Auk
Pushes your local data to empty repository

Option 2: Pull Remote Data

Use if repository already has data
Downloads data from repository to Auk

Option 3: Merge

Use if both local and remote have data
Attempts to merge both datasets

Configure Auto Sync

Auto Sync Interval:

5 minutes (frequent updates)
15 minutes (balanced)
30 minutes (less frequent)
60 minutes (hourly)
Manual only (no auto sync)

Sync on Changes:

Enable to sync immediately after changes
Disable to sync only at intervals

Verify Git Sync

After configuration, verify Git sync is working:

Check Sync Status
- Look for Git icon in workspace selector
- Should show “Synced” or last sync time
Make a Change
- Create a new collection or request
- Wait for auto sync or click “Sync Now”
Check Repository
- Visit your Git repository on the web
- You should see your collections in collections/ folder
Test from Another Device
- Install Auk on another device
- Create workspace with same Git repository
- Your collections should appear

Git Workflow

Daily Workflow

Start Auk → Auto pull latest changes
Make changes → Auto-commit locally
Auto sync → Push to remote
Team members pull → See your changes

Manual Sync

If you prefer manual control:

Disable auto sync in settings
Make your changes
Click “Sync Now” when ready
Review changes before pushing

Branch Workflow

For larger changes, use branches:

Create a new branch in workspace settings
Make your changes
Push branch to remote
Create pull request on Git service
After merge, switch back to main branch

Troubleshooting

Authentication Failed

SSH:

# Test SSH connection
ssh -T [email protected]

# If fails, check SSH agent
ssh-add -l

# Re-add key if needed
ssh-add ~/.ssh/id_ed25519

HTTPS:

Verify token has correct permissions
Check token hasn’t expired
Try regenerating token

Push Rejected

Problem: “Updates were rejected because the remote contains work” Solution:

# Pull latest changes first
# Auk will do this automatically, or click "Pull"

# If conflicts, resolve them
# Then push again

Merge Conflicts

Problem: “Merge conflict detected” Solution:

Auk will show conflict resolution dialog
Choose resolution strategy:
- Keep local changes
- Use remote changes
- Manual merge
After resolving, sync again

Large Files

Problem: “File too large” error Solution:

Git has file size limits (usually 100MB)
Don’t commit large files (videos, images, etc.)
Use .gitignore to exclude them
Consider Git LFS for large files

Slow Sync

Problem: Sync takes too long Solution:

Check network connection
Reduce auto sync frequency
Use shallow clone for large repositories
Consider splitting into multiple workspaces

Best Practices

Repository Organization

my-api-collections/
├── collections/
│   ├── rest/
│   │   ├── users-api.json
│   │   └── products-api.json
│   └── graphql/
│       └── main-api.json
├── environments/
│   ├── development.json
│   ├── staging.json
│   └── production.json
├── .gitignore
└── README.md

.gitignore Template

# Secrets
*.secret.json
secrets/
.env

# Local state
.local/
*.local.json
history/

# System files
.DS_Store
Thumbs.db

Commit Messages

Auk auto-generates commit messages:

Update collections: Added new endpoint
Update environments: Changed API URL
Sync: 3 collections updated

Team Collaboration

Communicate - Tell team before major changes
Sync Often - Reduce merge conflicts
Use Branches - For experimental changes
Review Changes - Check diffs before pushing
Document - Add README to repository

Advanced Configuration

Multiple Remotes

Configure multiple Git remotes:

# Add backup remote
git remote add backup [email protected]:username/backup.git

# Push to both
git push origin main
git push backup main

Custom Git Commands

Run custom Git commands in workspace directory:

# Navigate to workspace
cd ~/Documents/Auk/my-workspace

# View commit history
git log --oneline

# View changes
git diff

# Create branch
git checkout -b feature-branch

# Merge branch
git merge feature-branch

Hooks

Set up Git hooks for automation:

# Pre-commit hook
# .git/hooks/pre-commit
#!/bin/bash
echo "Running pre-commit checks..."
# Add your checks here

Next Steps

Conflict Resolution

Learn how to resolve merge conflicts

Branch Management

Work with Git branches

Team Collaboration

Best practices for team collaboration

Troubleshooting

Common Git sync issues

​Why Use Git Sync?

​How It Works

​Supported Git Services

​Prerequisites

​Check Git Installation

​Authentication Methods

​SSH Keys (Recommended)

​HTTPS with Personal Access Token

​Create Git Repository

​Configure Git in Auk

​Verify Git Sync

​Git Workflow

​Daily Workflow

​Manual Sync

​Branch Workflow

​Troubleshooting

​Authentication Failed

​Push Rejected

​Merge Conflicts

​Large Files

​Slow Sync

​Best Practices

​Repository Organization

​.gitignore Template

​Commit Messages

​Team Collaboration

​Advanced Configuration

​Multiple Remotes

​Custom Git Commands

​Hooks

​Next Steps

Conflict Resolution

Branch Management

Team Collaboration

Troubleshooting

Why Use Git Sync?

How It Works

Supported Git Services

Prerequisites

Check Git Installation

Authentication Methods

SSH Keys (Recommended)

HTTPS with Personal Access Token

Create Git Repository

Configure Git in Auk

Verify Git Sync

Git Workflow

Daily Workflow

Manual Sync

Branch Workflow

Troubleshooting

Authentication Failed

Push Rejected

Merge Conflicts

Large Files

Slow Sync

Best Practices

Repository Organization

.gitignore Template

Commit Messages

Team Collaboration

Advanced Configuration

Multiple Remotes

Custom Git Commands

Hooks

Next Steps