Git Sync - Auk Documentation

Why Git for Collaboration?

Auk uses Git as its collaboration mechanism instead of cloud services, giving you complete control over your data and collaboration workflow.

Full Control

Choose any Git service - GitHub, GitLab, Gitee, or self-hosted

Version History

Complete change history with the ability to rollback to any point

Standard Workflows

Use familiar Git workflows - branches, pull requests, code review

Offline First

Work offline, commit locally, sync when ready

How It Works

Sync Flow

Local Changes - You modify collections or environments
Auto Commit - Auk automatically commits changes to local Git
Sync - Changes are pushed to remote repository
Pull Updates - Team members’ changes are pulled automatically
Conflict Detection - Conflicts are detected and resolved

Supported Git Services

GitHub
GitLab
Gitee
Self-Hosted

GitHub

Public and private repositories
OAuth authentication (coming soon)
SSH and HTTPS support
Organization repositories

# Example repository URL
[email protected]:username/api-collections.git

GitLab

Self-hosted or GitLab.com
Group and project repositories
SSH and HTTPS support
Deploy tokens

# Example repository URL
[email protected]:username/api-collections.git

Gitee

Popular in China
Public and private repositories
SSH and HTTPS support

# Example repository URL
[email protected]:username/api-collections.git

Self-Hosted Git

Any standard Git server
Complete data control
Custom authentication

# Example repository URL
[email protected]:team/api-collections.git

Authentication Methods

SSH Keys (Recommended)

Most secure and convenient method:

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

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

# Add to Git service (GitHub/GitLab/etc.)

HTTPS with Token

Use personal access tokens:

# GitHub Personal Access Token
# Settings → Developer settings → Personal access tokens

# Clone with token
git clone https://[email protected]/username/repo.git

OAuth (Coming Soon)

One-click authentication with GitHub and GitLab.

Sync Strategies

Automatic Sync

Auk can automatically sync at regular intervals:

Every 5 minutes - For active collaboration
Every 15 minutes - Balanced approach (default)
Every hour - For less frequent updates
Manual only - Full control over when to sync

Manual Sync

Trigger sync manually when needed:

Before starting work (pull latest changes)
After completing a feature (push your changes)
Before switching workspaces
When resolving conflicts

Conflict Resolution

When multiple team members edit the same collection:

Conflict Detection

Auk detects conflicts during sync and pauses the operation

Review Changes

View side-by-side comparison of conflicting changes

Choose Strategy

Keep local changes
Use remote changes
Smart merge (combine both)
Manual resolution

Complete Sync

After resolution, sync completes automatically

Branch Management

Use Git branches for different workflows:

Feature Branches

# Create feature branch
main → feature/new-endpoints

# Work on feature
# Merge back when ready

Environment Branches

# Separate branches for environments
├── main (production)
├── staging
└── development

Team Branches

# Personal branches for each team member
├── main
├── alice/work
└── bob/work

Best Practices

Commit Messages

Auk generates descriptive commit messages automatically:

Add new authentication endpoints

- Added POST /auth/login
- Added POST /auth/refresh
- Updated environment variables

Co-Authored-By: Auk <[email protected]>

Sync Frequency

Active collaboration: Sync every 5-15 minutes
Solo work: Sync hourly or manually
Before meetings: Always sync to get latest changes

Repository Structure

Keep one repository per workspace for clean organization:

team-apis/              # One repository
├── collections/
├── environments/
└── README.md

Sensitive Data

Never commit sensitive data:

Use environment variables for secrets
Add .env files to .gitignore
Use Git secret scanning tools

Advantages Over Cloud Sync

Feature	Cloud Sync	Git Sync
Data Control	Service provider	You
Privacy	Shared infrastructure	Your infrastructure
Version History	Limited	Complete Git history
Branching	Not available	Full Git branching
Offline Work	Limited	Full support
Cost	Subscription fees	Free (or your Git hosting)
Vendor Lock-in	Yes	No

Next Steps

Setup Git Sync

Configure your first Git repository

Authentication

Set up SSH keys or access tokens

Auto Sync

Configure automatic synchronization

Conflict Resolution

Learn how to handle merge conflicts

​Why Git for Collaboration?

Full Control

Version History

Standard Workflows

Offline First

​How It Works

​Sync Flow

​Supported Git Services

​GitHub

​GitLab

​Gitee

​Self-Hosted Git

​Authentication Methods

​SSH Keys (Recommended)

​HTTPS with Token

​OAuth (Coming Soon)

​Sync Strategies

​Automatic Sync

​Manual Sync

​Conflict Resolution

​Branch Management

​Feature Branches

​Environment Branches

​Team Branches

​Best Practices

​Advantages Over Cloud Sync

​Next Steps

Setup Git Sync

Authentication

Auto Sync

Conflict Resolution

Why Git for Collaboration?

How It Works

Sync Flow

Supported Git Services

GitHub

GitLab

Gitee

Self-Hosted Git

Authentication Methods

SSH Keys (Recommended)

HTTPS with Token

OAuth (Coming Soon)

Sync Strategies

Automatic Sync

Manual Sync

Conflict Resolution

Branch Management

Feature Branches

Environment Branches

Team Branches

Best Practices

Advantages Over Cloud Sync

Next Steps