Migration Guide

Overview

gityar supports migrating repositories from GitHub, GitLab, Gogs, Gitea, and any other Git repository via URL.

Migration Methods

1. Migrate via Web Interface

Steps

1. Click "+" → "New Migration"
2. Select source:
   • GitHub
   • GitLab
   • Gogs
   • Gitea
   • Other Git Repository
3. Enter repository URL:
   • GitHub: https://github.com/user/repo.git
   • GitLab: https://gitlab.com/user/repo.git
   • Other: Any Git URL
4. Authenticate (if required):
   • Username/Password
   • Access Token
5. Configure migration:
   • Repository Name: Override name (optional)
   • Description: Override description (optional)
   • Private: Set visibility
   • Mirror: Create mirror repository
6. Click "Migrate Repository"

2. Migrate via Command Line

Clone from Source

git clone --mirror https://source-git.com/user/repo.git
cd repo.git

Push to gityar

git push --mirror http://localhost:3000/user/repo.git

What Gets Migrated

Full Migration

• ✅ All commits and branches
• ✅ All tags
• ✅ Repository files
• ✅ Commit history
• ✅ Contributors

Optional (if supported by source)

• ⚠️ Issues
• ⚠️ Pull requests / Merge requests
• ⚠️ Labels
• ⚠️ Milestones
• ⚠️ Wiki pages
• ⚠️ Releases

Migrating from GitHub

Using Personal Access Token

1. Generate token on GitHub:
   • Go to Settings → Developer settings → Personal access tokens
   • Create token with repo scope
2. In gityar migration:
   • URL: https://github.com/user/repo
   • Authentication: Use token as password

GitHub Enterprise

https://github-enterprise.example.com/user/repo

Migrating from GitLab

Using Personal Access Token

1. Generate token on GitLab:
   • Go to User Settings → Access Tokens
   • Create token with read_api and read_repository scopes
2. In gityar migration:
   • URL: https://gitlab.com/user/repo
   • Authentication: Use token as password

GitLab Self-Hosted

https://gitlab.your-company.com/user/repo

Migrating from Gogs/Gitea

Similar to GitLab migration:

https://gogs.example.com/user/repo.git
https://gitea.example.com/user/repo.git

Migrating Large Repositories

Increase Limits

In app.ini:

[repository]
MAX_CREATION_LIMIT = -1  # Unlimited

[migrations]
MAX_ATTEMPTS = 3
MAX_REQUEST_SIZE = 104857600  # 100MB

Use Mirror Migration

For large repositories:

1. Create mirror repository
2. Sync happens in background
3. Monitor progress in repository settings

Command Line Alternative

For very large repos, use command line:

# Clone with shallow history
git clone --depth 100 --mirror https://source.com/repo.git
cd repo.git

# Push to gityar
git push --mirror http://localhost:3000/repo.git

Post-Migration Tasks

Update Remote URLs

git remote set-url origin http://localhost:3000/user/repo.git
git push -u origin --all
git push -u origin --tags

Verify Migration

• Check all branches present
• Verify tags exist
• Review commit history
• Test repository clone
• Check file contents
• Review issues (if migrated)
• Verify wiki (if migrated)

Configure Repository

1. Update repository settings
2. Add collaborators
3. Configure webhooks
4. Set up branch protection
5. Enable/disable features

Troubleshooting

Common Issues

Authentication Failed:

• Verify credentials
• Check token permissions
• Ensure URL is correct

Repository Not Found:

• Check repository exists
• Verify you have access
• Confirm URL format

Migration Timeout:

• Increase timeout in app.ini
• Use mirror migration
• Try command line method

Incomplete Migration:

• Check logs for errors
• Verify source repository
• Retry migration

Large Files Missing:

• Install Git LFS on source
• Enable LFS in gityar
• Use git lfs migrate

Check Migration Logs

View logs in:

log/gityar.log

Look for migration-related errors.

Mirroring

Create Mirror

During migration, select "Mirror" option.

Mirror Repository Features

• One-way sync from source
• Automatic updates
• Read-only in gityar
• Pull-only from source

Update Mirror

Manual Update:

1. Go to repository Settings
2. Click "Sync" button

Automatic Sync:

Configure in app.ini:

[repository]
PULL_REQUEST_COMMITS = true
DISABLED_REPO_UNITS = 

Convert Mirror to Regular

1. Go to repository Settings
2. Disable mirroring
3. Repository becomes fully editable

Best Practices

Before Migration

• ✅ Backup source repository
• ✅ Verify access credentials
• ✅ Check repository size
• ✅ Review what will be migrated
• ✅ Notify team members

During Migration

• ✅ Monitor migration progress
• ✅ Check logs for errors
• ✅ Don't delete source until verified
• ✅ Test clone after migration

After Migration

• ✅ Verify all data migrated
• ✅ Update documentation
• ✅ Update CI/CD pipelines
• ✅ Update remote URLs for team
• ✅ Archive or redirect old repository

Next Steps

• Learn about Git LFS
• Explore Troubleshooting
• Read FAQ