GitLab to GitHub Mirror

A tool to automatically mirror all your GitLab repositories (including commits, branches, and tags) to GitHub.

Features

• Full repository mirroring (commits, branches, tags, and history)
• Automatic repository creation on GitHub if needed
• Support for both public and private repositories
• Batch processing of all accessible GitLab projects
• Detailed logging and error reporting
• Local caching to speed up subsequent mirroring operations
• Configuration via .env file or command-line arguments

Prerequisites

• Python 3.8+
• Git installed and available in PATH
• GitLab Personal Access Token with read_api scope
• GitHub Personal Access Token with repo scope

Installation

# Clone the repository
git clone https://github.com/yourusername/gitlab-github-mirror.git
cd gitlab-github-mirror

# Install dependencies
pip install -r requirements.txt

# Create your configuration file
cp .env.example .env
# Edit .env with your tokens and configuration

Configuration

You can configure the tool in two ways:

1. Using a .env file (recommended)

Create a .env file in the same directory as the script with the following content:

# GitLab configuration
GITLAB_TOKEN=your_gitlab_personal_access_token
GITLAB_URL=https://gitlab.com

# GitHub configuration
GITHUB_TOKEN=your_github_personal_access_token
GITHUB_USERNAME=your_github_username

# Mirror configuration
MIRROR_DIR=./mirror_repos
PRIVATE_REPOS=false  # Set to "true" to create private repos
DRY_RUN=false        # Set to "true" to enable dry-run mode
DEBUG=false          # Set to "true" to enable debug logging

2. Using command-line arguments

If you prefer not to use a .env file, you can provide the configuration via command-line arguments.

Usage

Using .env file (recommended)

If you've set up your .env file, you can simply run:

python mirror_projects.py

Using command-line arguments

python mirror_projects.py \
    --gitlab-token YOUR_GITLAB_TOKEN \
    --github-token YOUR_GITHUB_TOKEN \
    --github-username YOUR_GITHUB_USERNAME \
    [--gitlab-url https://gitlab.com] \
    [--mirror-dir ./mirror_repos] \
    [--private] \
    [--dry-run] \
    [--debug]

Options

• --gitlab-token: Your GitLab Personal Access Token (or set GITLAB_TOKEN in .env)
• --github-token: Your GitHub Personal Access Token (or set GITHUB_TOKEN in .env)
• --github-username: Your GitHub username where mirrored repos will be created (or set GITHUB_USERNAME in .env)
• --gitlab-url: Base URL for GitLab instance (default: "https://gitlab.com" or GITLAB_URL in .env)
• --mirror-dir: Local directory to store mirrored repositories (default: "./mirror_repos" or MIRROR_DIR in .env)
• --private: Flag to create GitHub repositories as private (default is public unless PRIVATE_REPOS=true in .env)
• --dry-run: Simulate the mirroring process without making actual changes (or set DRY_RUN=true in .env)
• --debug: Enable debug logging (or set DEBUG=true in .env)

Generating Access Tokens

GitLab Token

1. Go to your GitLab profile (User Settings > Access Tokens)
2. Create a personal access token with read_api scope
3. Copy the token for use with this script

GitHub Token

1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Generate a new token with repo scope
3. Copy the token for use with this script

Security Notes

• Never commit your tokens to version control
• Consider using environment variables or a secure secret manager
• The script temporarily stores repositories in the mirror directory
• Clean up the mirror directory when no longer needed

Development

• Run tests: pytest tests/
• Run linting: flake8 mirror_projects.py
• Run validation script: ./run_tests.sh

License

MIT