📖 Guide ⏱️ ~15 min read Last updated: Jan 15, 2025

Migrating to .git

A comprehensive, step-by-step guide to migrating your projects, workflows, and team from your existing platform to .git. Follow this guide to ensure a smooth transition with zero downtime.

Overview

Migrating to .git is designed to be a seamless experience. Whether you're coming from GitHub, GitLab, Bitbucket, or a self-hosted solution, our migration tools handle the heavy lifting.

This guide covers:

Repository migration — Code, branches, tags, and commit history
CI/CD pipeline conversion — Automated workflow mapping
Team & access management — Roles, permissions, and SSO
Integration setup — Webhooks, notifications, and third-party tools

💡 Pro Tip

Run your migration in a staging environment first. Use the --dry-run flag to preview changes before committing to production.

Prerequisites

Before beginning the migration, ensure you have the following:

.git Account — A verified .git account with admin privileges
CLI Access — A modern Linux, macOS, or Windows environment with terminal access
Source Repository Access — Read/write access to the repositories you plan to migrate
Service Tokens — Personal access tokens or OAuth credentials for your source platform
DNS Control — Access to your domain's DNS provider (if using custom domains)

⚠️ Important

Ensure all pending CI/CD pipelines on your source platform have completed before starting the migration. Active builds may cause conflicts.

1 Install the CLI

Install the .git CLI

The .git CLI is the primary tool for managing migrations. Install it using your preferred package manager:

bash

# macOS / Linux (curl)
curl -fsSL https://cli.git.dev/install | bash

# macOS (Homebrew)
brew install .git/tap/git-cli

# Windows (Scoop)
scoop bucket add git https://github.com/.git/scoop-bucket
scoop install git-cli

# Windows (Chocolatey)
choco install git-cli

Verify the installation:

bash

git --version
# Expected: .git CLI v2.4.1 (build 20250115)

2 Authenticate

Authenticate with .git

bash

git auth login
# Opens browser for OAuth flow
# Or use token: GIT_TOKEN=your_token git auth login --token

# Set default org
git config --global git.default-org "your-org-name"

Authenticate with your source platform to enable migration:

bash

# GitHub
git auth source github

# GitLab
git auth source gitlab

# Bitbucket
git auth source bitbucket

# Verify active sources
git auth sources list

3 Initialize & Sync

Initialize & Sync Repositories

Start the migration by initializing a sync project. The CLI will detect your repositories and create a migration plan.

bash

# Initialize migration project
git migrate init --source github --org your-org-name

# Review the auto-generated plan
cat .git/migration-plan.yaml

# Dry run to preview changes
git migrate sync --dry-run

# Execute the migration
git migrate sync
# Status: Migrating 12 repositories...
# Status: Transferring 847 branches...
# Status: Preserving commit history (2,341 commits)...
# ✓ Migration complete. 0 errors.

💡 Incremental Sync

Use --incremental to only migrate new commits since the last sync. This is useful for keeping repos in sync before cutover.

4 Configure CI/CD

Configure CI/CD Pipelines

.git automatically converts most popular CI/CD configs. Review and customize as needed:

bash

# Auto-convert GitHub Actions → .git pipelines
git migrate ci --from github-actions --to .git-pipelines

# Convert GitLab CI
git migrate ci --from gitlab-ci --to .git-pipelines

# Preview converted pipeline
git pipeline preview my-repo

# Activate pipeline
git pipeline activate my-repo --environment production

Example: Converted Pipeline

yaml

# .git/pipeline.yaml (auto-generated)
pipeline:
  name: build-and-deploy
  trigger:
    branch: [main, develop]
    tags: [v*]

  steps:
    - name: checkout
      uses: git/checkout@v3

    - name: setup-node
      uses: git/setup-node@v3
      with:
        node-version: '20'

    - name: install
      run: npm ci

    - name: test
      run: npm test

    - name: build
      run: npm run build

    - name: deploy
      uses: git/deploy@v2
      with:
        environment: production

5 Final Verification

Final Verification

After migration, run the verification suite to ensure everything is intact:

bash

# Run full verification suite
git migrate verify --all

# Output:
# ✓ Repository integrity: 12/12 passed
# ✓ Branch migration: 847/847 passed
# ✓ Tag migration: 156/156 passed
# ✓ CI/CD conversion: 24/24 passed
# ✓ Webhook mapping: 18/18 passed
# ✓ Team permissions: 42/42 passed
# 
# 🎉 Migration verified successfully!

Update your remote URLs for local development:

bash

# Update remote for a local clone
git remote set-url origin https://git.dev/your-org/my-repo.git

# Or use the CLI helper
git migrate remote-update --all

Config Reference

The migration plan is stored in .git/migration-plan.yaml. Key options include:

Key	Type	Description	Default
`source`	string	Source platform (github, gitlab, bitbucket)	—
`preserve-history`	boolean	Keep full commit history and authors	true
`migrate-issues`	boolean	Transfer issues and pull requests	true
`migrate-wiki`	boolean	Transfer wiki pages	false
`ci-conversion`	string	CI conversion strategy (auto, manual, skip)	auto
`webhooks`	boolean	Remap webhooks to .git endpoints	true

Troubleshooting

Authentication Failed

If you see Error: 401 Unauthorized, your token may have expired or lacks required scopes.

bash

# Refresh token
git auth refresh github

# Re-authenticate with full scopes
git auth source github --scope "repo,admin:org,write:packages"

Large Repository Timeout

Repositories over 500MB may time out. Enable streaming mode:

bash

git migrate sync --streaming --timeout 3600

CI Conversion Conflicts

If auto-conversion produces errors, switch to manual mode:

bash

# Export conversion diffs for manual review
git migrate ci --diff-only

# Review and edit, then apply
git migrate ci --apply-manual

Need Help?

If you encounter issues not covered in this guide, reach out to our team:

Live Chat — Available 24/7 in your .git dashboard
Email — migrate@git.dev
Community — Discord Server for real-time developer support
Enterprise — Dedicated migration engineers for teams of 50+

🚀 Ready to start?

Run git migrate init and our interactive wizard will guide you through the process step by step.