Skip to main content

​
Team Collaboration with Git

Auk uses Git for team collaboration, providing version control, conflict resolution, and distributed workflows.

Version Control

Complete history of all changes

Distributed

Each team member has full copy

Conflict Resolution

Built-in conflict handling

Standard Workflows

Use familiar Git workflows

​
Team Setup

​
Initial Setup

1

Create Shared Repository

One team member creates a Git repository:
# On GitHub/GitLab
# Create new repository: team-api-collections
2

Push Initial Data

Push existing collections to repository:
# In Auk workspace settings
# Enable Git Sync
# Enter repository URL
# Initial push happens automatically
3

Team Members Clone

Other team members clone the repository:
# In Auk
# Create New Workspace → Clone from Git
# Enter repository URL
4

Configure Sync

Each team member configures auto-sync:
{
  "git": {
    "autoSync": true,
    "syncInterval": 900
  }
}

​
Collaboration Patterns

​
Small Team (2-5 people)

Strategy: Single branch, frequent syncing 
{
  "git": {
    "autoSync": true,
    "syncInterval": 300,
    "conflictResolution": "smartMerge"
  }
}
Best practices:
  • Sync every 5-15 minutes
  • Communicate before major changes
  • Use smart merge for conflicts
  • Keep collections organized

​
Large Team (5+ people)

Strategy: Feature branches, code review 
# Create feature branch
git checkout -b feature/payment-api

# Work on changes
# ...

# Push feature branch
git push origin feature/payment-api

# Create pull request for review
Best practices:
  • Use feature branches
  • Require pull request reviews
  • Assign collection ownership
  • Document changes

​
Avoiding Conflicts

​
Communication

Before making significant changes:
  • Notify team in chat
  • Create feature branch
  • Coordinate timing
Divide collections by ownership:
collections/
├── auth/           # Alice owns
├── users/          # Bob owns
└── payments/       # Carol owns
Reduce conflicts by syncing often:
  • Pull before starting work
  • Push after completing features
  • Sync before meetings

​
Division of Work

collections/
├── authentication/
├── user-management/
└── payment-processing/
Each team member owns a feature area

​
Workflow Examples

​
Feature Development

1

Create Branch

git checkout -b feature/new-endpoints
2

Develop Feature

Add new endpoints and test them in Auk
3

Commit Changes

Changes auto-committed by Auk
4

Push and Review

git push origin feature/new-endpoints
# Create pull request on GitHub/GitLab
5

Merge

After review, merge to main branch

​
Hotfix Workflow

For urgent fixes:
1

Create Hotfix Branch

git checkout -b hotfix/critical-bug
2

Fix Issue

Make necessary changes in Auk
3

Test

Verify fix works correctly
4

Fast-Track Merge

git push origin hotfix/critical-bug
# Quick review and merge

​
Code Review Process

​
Pull Request Checklist

Before creating PR:
  • All tests pass
  • Collections are organized
  • Environment variables documented
  • No sensitive data committed
  • Descriptive commit messages

​
Review Guidelines

When reviewing:
  • Check request organization
  • Verify environment variables
  • Test endpoints if possible
  • Look for sensitive data
  • Provide constructive feedback

​
Team Communication

​
Daily Standup

Share during standup:
  • What collections you’re working on
  • Any conflicts encountered
  • Planned major changes
  • Sync status

​
Documentation

Maintain team documentation: 
# Team API Collections

## Current Work
- Alice: Authentication endpoints
- Bob: User management
- Carol: Payment processing

## Conventions
- Use `{{baseUrl}}` for all endpoints
- Mark secrets as secret variables
- Sync before end of day

## Contacts
- Questions: #api-testing channel
- Issues: GitHub Issues

​
Handling Conflicts

​
Prevention

  • Sync frequently (every 5-15 min)
  • Communicate before major changes
  • Use feature branches
  • Assign clear ownership

​
Resolution

When conflicts occur:
  1. Don’t Panic - Conflicts are normal
  2. Review Changes - Understand both versions
  3. Choose Strategy - Smart merge, keep local, or use remote
  4. Test Result - Verify merged version works
  5. Communicate - Inform team of resolution
See Conflict Resolution for details.

​
Best Practices

Always sync before team meetings:
  • Ensures everyone has latest changes
  • Reduces meeting time spent on sync issues
  • Shows current state of work
Auk generates commit messages, but you can customize:
{
  "git": {
    "commitMessageTemplate": "[{{collection}}] {{description}}"
  }
}
Keep repository clean:
  • Delete merged branches
  • Archive old collections
  • Remove unused environments
Multiple backups:
  • Git remote (primary)
  • Local backups (secondary)
  • External drive (tertiary)

​
Troubleshooting

Solutions:
  • Reduce sync interval
  • Better communication
  • Split collections by ownership
  • Use feature branches
Solutions:
  • Split large collections
  • Increase sync interval
  • Use shallow clone
  • Check network speed
Solutions:
  • Verify Git credentials
  • Check repository access
  • Test SSH/HTTPS connection
  • Review sync logs

​
Next Steps

Conflict Resolution

Handle merge conflicts

Git Sync Setup

Configure Git synchronization

Workspace Organization

Organize team workspaces

Local-First Workflow

Local-first best practices