Lab2Hub - GitLab to GitHub Mirror Manager

A Python CLI tool for managing GitLab to GitHub repository mirroring with 2-way synchronization support.

Features

• Interactive CLI: User-friendly command-line interface for managing mirrors
• 2-Way Sync: Supports GitLab-to-Github mirroring with local synchronization
• Batch Operations: Select and process multiple projects at once
• Read-Only Mode: Preview operations without making changes
• Registry Management: JSON-based state persistence for mirror tracking
• Error Handling: Robust error handling with retry mechanisms
• Local Git Integration: Manual setup of GitHub remotes in local repos via dedicated command

Tech Stack / Built With

• Python 3.8+ - Core runtime
• python-gitlab - GitLab API client
• PyGithub - GitHub API client
• console-menu - Interactive CLI menus
• python-dotenv - Environment variable management

Prerequisites

• Python 3.8 or higher
• Git installed and configured
• GitLab account with appropriate permissions
• GitHub account with repository creation permissions
• GitLab Personal Access Token with api scope
• GitHub Personal Access Token with repo scope

Installation

Quick Install (Recommended)

The easiest way to install and run lab2hub is with uv:

# Clone the repository
git clone https://gitlab.com/user4302_Projects/coding/python/lab2hub.git
cd lab2hub

# Run directly - uv handles venv creation and dependencies automatically
uv run lab2hub

That's it! The uv run lab2hub command will:

• Automatically create a virtual environment if needed
• Install all dependencies
• Run the lab2hub CLI

Alternative/Manual Installation

If you prefer to use pip or need more control over the installation:

1. Clone the repository:

   git clone https://gitlab.com/user4302_Projects/coding/python/lab2hub.git
   cd lab2hub

2. Create and activate virtual environment:

   # Create virtual environment
   python -m venv .venv
   
   # Activate virtual environment
   # On Windows:
   .venv\Scripts\activate
   # On macOS/Linux:
   source .venv/bin/activate

3. Install dependencies:

   pip install -e .

   Or with development dependencies:

   pip install -e ".[dev]"

4. Set up environment variables:

   cp .env.example .env
   # Edit .env with your tokens

Usage / Quick Start

1. Configure your tokens in .env:

   GITLAB_TOKEN=your_gitlab_token_here
   GITHUB_TOKEN=your_github_token_here
   GITLAB_URL=https://gitlab.com
   GITHUB_URL=https://github.com
   

2. Run the CLI:

   # With uv (recommended)
   uv run lab2hub
   
   # Or if installed with pip
   lab2hub

3. Available modes:

   # Interactive mirror setup (default)
   uv run lab2hub
   
   # Or if installed with pip
   lab2hub
   
   # Read-only mode - preview without changes
   uv run lab2hub --read-only
   
   # Sync existing mirrors
   uv run lab2hub --sync
   
   # Force refresh GitLab cache
   uv run lab2hub --refresh
   
   # Setup local GitHub remote for 2-way sync
   uv run lab2hub --setup-local-remote

Project Structure

lab2hub/
|-- lab2hub/           # Main package
|   |-- __init__.py
|   |-- cli.py              # Command-line interface
|   |-- config.py           # Configuration management
|   |-- core.py              # Main Lab2Hub class
|   |-- client_manager.py   # API client management
|   |-- project_service.py  # GitLab project operations
|   |-- github_service.py   # GitHub repository operations
|   |-- mirror_service.py   # Mirror setup and sync
|   |-- registry.py         # JSON registry management
|   |-- local_operations.py # Local git operations
|-- tests/                  # Test suite
|   |-- __init__.py
|   |-- test_config.py
|-- .env.example           # Environment template
|-- .gitignore
|-- pyproject.toml         # Project configuration
`-- README.md

Configuration

The tool uses environment variables for configuration:

Required Environment Variables

• GITLAB_TOKEN - GitLab Personal Access Token
• GITHUB_TOKEN - GitHub Personal Access Token

Optional Environment Variables

• GITLAB_URL - GitLab instance URL (default: https://gitlab.com)
• GITHUB_URL - GitHub instance URL (default: https://github.com)
• GITLAB_GROUP - GitLab group to mirror from (default: auto-detect)

Token Permissions

GitLab Token Requirements:

• api scope - Full API access

GitHub Token Requirements:

• repo scope - Full repository access

Development / Running Locally

With uv (Recommended)

1. Set up development environment:

   # Clone and install
   git clone https://gitlab.com/user4302_Projects/coding/python/lab2hub.git
   cd lab2hub
   
   # Install with dev dependencies
   uv sync --dev
   
   # Run the CLI
   uv run lab2hub

2. Run tests:

   uv run pytest

3. Code formatting:

   uv run black gitlab_mirror/

4. Linting:

   uv run flake8 gitlab_mirror/

5. Type checking:

   uv run mypy gitlab_mirror/

With pip (Alternative)

1. Set up development environment:

   # Clone and create virtual environment
   git clone https://gitlab.com/user4302_Projects/coding/python/lab2hub.git
   cd lab2hub
   python -m venv .venv
   
   # Activate virtual environment
   # On Windows:
   .venv\Scripts\activate
   # On macOS/Linux:
   source .venv/bin/activate
   
   # Install with dev dependencies
   pip install -e ".[dev]"

2. Run tests:

   pytest

3. Code formatting:

   black gitlab_mirror/

4. Linting:

   flake8 gitlab_mirror/

5. Type checking:

   mypy gitlab_mirror/

Testing

With uv (Recommended)

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=lab2hub

# Run specific test file
uv run pytest tests/test_config.py

With pip (Alternative)

# Run all tests
pytest

# Run with coverage
pytest --cov=lab2hub

# Run specific test file
pytest tests/test_config.py

Building for Production

With uv (Recommended)

1. Build the package:

   uv build

2. Install from wheel:

   pip install dist/lab2hub-1.6.2-py3-none-any.whl

With pip (Alternative)

1. Build the package:

   python -m build

2. Install from wheel:

   pip install dist/lab2hub-1.6.2-py3-none-any.whl

Deployment

The tool is distributed as a Python package. Deploy by:

Option 1: Install from PyPI (when published)

pip install lab2hub

Option 2: Use uv directly from source

git clone https://gitlab.com/user4302_Projects/coding/python/lab2hub.git
cd lab2hub
uv run lab2hub

Option 3: Traditional pip installation

# Clone and create virtual environment
git clone https://gitlab.com/user4302_Projects/coding/python/lab2hub.git
cd lab2hub
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install the package
pip install -e .

# Run the CLI
lab2hub

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

For questions, bugs, features, or security, open an issue on GitLab: https://gitlab.com/user4302_Projects/coding/python/lab2hub/-/issues

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support & Contact

For questions, bugs, features, or security, open an issue on GitLab: https://gitlab.com/user4302_Projects/coding/python/lab2hub/-/issues

No email or direct support.