Git Sync Setup - Auk Documentation

Prerequisites

Before setting up Git sync, ensure you have:

Git Installed

Verify Git is installed on your system:

git --version

If not installed, download from git-scm.com

Git Repository

Create a repository on your preferred Git service:

GitHub
GitLab
Gitee
Self-hosted Git server

Authentication

Set up SSH keys or access tokens for authentication

Quick Setup

For New Workspaces

Create Workspace

Create a new workspace in Auk

Enable Git Sync

In workspace settings, enable “Git Synchronization”

Enter Repository URL

[email protected]:username/api-collections.git

Initial Push

Auk will push your current workspace data to the repository

For Existing Workspaces

Open Workspace Settings

Navigate to Settings → Git Sync

Initialize Git

Click “Initialize Git Repository”

Add Remote

Enter your remote repository URL

Push Existing Data

Auk commits and pushes your existing collections

Repository Setup

GitHub

Create Repository
SSH Setup
HTTPS with Token

Go to github.com/new
Enter repository name: api-collections
Choose Private (recommended for API data)
Do NOT initialize with README
Click “Create repository”

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

# Copy public key
cat ~/.ssh/id_ed25519.pub

# Add to GitHub:
# Settings → SSH and GPG keys → New SSH key

# Create Personal Access Token:
# Settings → Developer settings → Personal access tokens
# → Tokens (classic) → Generate new token

# Required scopes:
# - repo (full control of private repositories)

# Use token in Auk:
# https://[email protected]/username/api-collections.git

GitLab

Create Project
SSH Setup
Deploy Token

Go to GitLab → New Project
Choose “Create blank project”
Enter project name: api-collections
Set visibility to Private
Uncheck “Initialize repository with a README”
Click “Create project”

# Generate SSH key (if not already done)
ssh-keygen -t ed25519 -C "[email protected]"

# Copy public key
cat ~/.ssh/id_ed25519.pub

# Add to GitLab:
# Preferences → SSH Keys → Add new key

# Create Deploy Token:
# Project → Settings → Repository → Deploy tokens

# Scopes:
# - read_repository
# - write_repository

# Use in Auk:
# https://USERNAME:[email protected]/username/api-collections.git

Gitee (码云)

创建仓库
SSH 配置

访问 gitee.com
点击 ”+” → “新建仓库”
输入仓库名称：api-collections
选择私有
不要初始化 README
点击 “创建”

# 生成 SSH 密钥
ssh-keygen -t ed25519 -C "[email protected]"

# 复制公钥
cat ~/.ssh/id_ed25519.pub

# 添加到 Gitee：
# 设置 → SSH 公钥 → 添加公钥

Authentication Methods

SSH Keys (Recommended)

Most secure and convenient method:

Generate SSH Key

ssh-keygen -t ed25519 -C "[email protected]"

Press Enter to accept default location

Start SSH Agent

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Copy Public Key

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

# Linux
xclip -sel clip < ~/.ssh/id_ed25519.pub

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

Add to Git Service

Add the public key to your Git service (GitHub/GitLab/etc.)

Test Connection

# GitHub
ssh -T [email protected]

# GitLab
ssh -T [email protected]

# Gitee
ssh -T [email protected]

HTTPS with Personal Access Token

Alternative method using HTTPS:

Generate Token

Create a personal access token in your Git service settings

Required Permissions

GitHub: repo scope
GitLab: read_repository, write_repository
Gitee: projects scope

Use in Auk

Enter repository URL with token:

https://[email protected]/username/api-collections.git

Store tokens securely. Never commit tokens to Git or share them publicly.

Initial Configuration

Configure Git User

Set your Git identity:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Configure Auk Git Settings

In Auk workspace settings:

{
  "git": {
    "enabled": true,
    "remoteUrl": "[email protected]:username/api-collections.git",
    "branch": "main",
    "autoSync": true,
    "syncInterval": 900,
    "autoCommit": true,
    "conflictResolution": "prompt"
  }
}

Sync Strategies

Automatic Sync

Enable automatic synchronization:

autoSync

boolean

default:"false"

Automatically sync at regular intervals

syncInterval

number

default:"900"

Sync interval in secondsRecommended values:

300 (5 min) - Active team collaboration
900 (15 min) - Balanced (default)
3600 (1 hour) - Less frequent updates

Manual Sync

Trigger sync manually when needed:

Click sync button in workspace toolbar
Use keyboard shortcut: Cmd/Ctrl + Shift + S
Before switching workspaces
After completing a feature

Branch Strategy

Single Branch (Simple)

Use one branch for all work:

main
  ↓
All team members work here

Best for:

Small teams
Simple workflows
Quick collaboration

Feature Branches

Create branches for features:

main
  ├── feature/auth-endpoints
  ├── feature/payment-api
  └── feature/user-management

Best for:

Larger teams
Complex changes
Code review workflows

Environment Branches

Separate branches per environment:

production
  ↓
staging
  ↓
development

Best for:

Multiple environments
Staged deployments
Testing workflows

First Sync

Push Existing Data

If you have existing collections:

Auk Creates Initial Commit

Initial commit: Add existing collections

- 5 collections
- 3 environments
- Workspace settings

Push to Remote

Auk pushes the commit to your remote repository

Verify

Check your Git service to confirm data is uploaded

Clone Existing Repository

If joining an existing team:

Create Workspace

Choose “Clone from Git” when creating workspace

Enter Repository URL

[email protected]:team/api-collections.git

Clone and Open

Auk clones the repository and opens the workspace

Verification

Check Git Status

Verify Git is working correctly:

# Navigate to workspace directory
cd ~/Library/Application\ Support/Auk/workspaces/my-workspace

# Check Git status
git status

# View commit history
git log --oneline

# Check remote
git remote -v

Test Sync

Make a small change and verify sync:

Create a new collection or request
Wait for auto-sync or trigger manual sync
Check Git service for new commit
Verify changes appear for team members

Troubleshooting

Authentication failed

Symptoms: Cannot push/pull, authentication errorsSolutions:

Verify SSH key is added to Git service
Test SSH connection: ssh -T [email protected]
Check token has correct permissions
Regenerate SSH key or token if needed

Permission denied

Symptoms: “Permission denied (publickey)” errorSolutions:

# Check SSH agent is running
eval "$(ssh-agent -s)"

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

# Verify key is loaded
ssh-add -l

Repository not found

Symptoms: “Repository not found” or 404 errorSolutions:

Verify repository URL is correct
Check you have access to the repository
Ensure repository exists on Git service
Try cloning manually to test access

Sync fails with conflicts

Symptoms: Sync stops with merge conflictSolutions:

See Conflict Resolution
Pull latest changes first
Resolve conflicts manually if needed

Next Steps

Auto Sync

Configure automatic synchronization

Conflict Resolution

Learn how to handle merge conflicts

Authentication

Advanced authentication options

Troubleshooting

Common issues and solutions

​Prerequisites

​Quick Setup

​For New Workspaces

​For Existing Workspaces

​Repository Setup

​GitHub

​GitLab

​Gitee (码云)

​Authentication Methods

​SSH Keys (Recommended)

​HTTPS with Personal Access Token

​Initial Configuration

​Configure Git User

​Configure Auk Git Settings

​Sync Strategies

​Automatic Sync

​Manual Sync

​Branch Strategy

​Single Branch (Simple)

​Feature Branches

​Environment Branches

​First Sync

​Push Existing Data

​Clone Existing Repository

​Verification

​Check Git Status

​Test Sync

​Troubleshooting

​Next Steps

Auto Sync

Conflict Resolution

Authentication

Troubleshooting

Prerequisites

Quick Setup

For New Workspaces

For Existing Workspaces

Repository Setup

GitHub

GitLab

Gitee (码云)

Authentication Methods

SSH Keys (Recommended)

HTTPS with Personal Access Token

Initial Configuration

Configure Git User

Configure Auk Git Settings

Sync Strategies

Automatic Sync

Manual Sync

Branch Strategy

Single Branch (Simple)

Feature Branches

Environment Branches

First Sync

Push Existing Data

Clone Existing Repository

Verification

Check Git Status

Test Sync

Troubleshooting

Next Steps