Gitea Mirror

Automatically mirror repositories from GitHub to your self-hosted Gitea instance.

🚀 Quick Start

# Fastest way - using the simplified Docker setup
docker compose -f docker-compose.alt.yml up -d

# Access at http://localhost:4321

First user signup becomes admin. Configure GitHub and Gitea through the web interface!

✨ Features

• 🔁 Mirror public, private, and starred GitHub repos to Gitea
• 🏢 Mirror entire organizations with flexible strategies
• 🎯 Custom destination control for repos and organizations
• 🔐 Secure authentication with JWT tokens
• 📊 Real-time dashboard with activity logs
• ⏱️ Scheduled automatic mirroring
• 🐳 Dockerized with multi-arch support (AMD64/ARM64)

📸 Screenshots

Installation

Docker (Recommended)

We provide two Docker Compose options:

Option 1: Quick Start (docker-compose.alt.yml)

Perfect for trying out Gitea Mirror or simple deployments:

# Clone repository
git clone https://github.com/RayLabsHQ/gitea-mirror.git
cd gitea-mirror

# Start with simplified setup
docker compose -f docker-compose.alt.yml up -d

# Access at http://localhost:4321

Features:

• ✅ Pre-built image - no building required
• ✅ Minimal configuration needed
• ✅ Data stored in ./data directory
• ✅ Configure everything through web UI
• ✅ Automatic user/group ID mapping

Best for:

• First-time users
• Testing and evaluation
• Simple deployments
• When you prefer web-based configuration

Option 2: Full Setup (docker-compose.yml)

For production deployments with environment-based configuration:

# Start with full configuration options
docker compose up -d

Features:

• ✅ Build from source or use pre-built image
• ✅ Complete environment variable configuration
• ✅ Support for custom CA certificates
• ✅ Advanced mirror settings (forks, wiki, issues)
• ✅ Multi-registry support

Best for:

• Production deployments
• Automated/scripted setups
• Advanced mirror configurations
• When using self-signed certificates

Using Pre-built Image Directly

docker pull ghcr.io/raylabshq/gitea-mirror:v2.20.1

Configuration Options

Quick Start Configuration (docker-compose.alt.yml)

Minimal .env file (optional - has sensible defaults):

# Custom port (default: 4321)
PORT=4321

# User/Group IDs for file permissions (default: 1000)
PUID=1000
PGID=1000

# JWT secret (auto-generated if not set)
JWT_SECRET=your-secret-key-change-this-in-production

All other settings are configured through the web interface after starting.

Full Setup Configuration (docker-compose.yml)

Supports extensive environment variables for automated deployment. See the full docker-compose.yml for all available options including GitHub tokens, Gitea URLs, mirror settings, and more.

LXC Container (Proxmox)

# One-line install on Proxmox VE
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/gitea-mirror.sh)"

See the Proxmox VE Community Scripts for more details.

Manual Installation

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Setup and run
bun run setup
bun run dev

Usage

1. First Time Setup

   • Navigate to http://localhost:4321
   • Create admin account (first user signup)
   • Configure GitHub and Gitea connections

2. Mirror Strategies

   • Preserve Structure: Maintains GitHub organization structure
   • Single Organization: All repos go to one Gitea organization
   • Flat User: All repos under your Gitea user account
   • Mixed Mode: Personal repos in one org, organization repos preserve structure

3. Customization

   • Click edit buttons on organization cards to set custom destinations
   • Override individual repository destinations in the table view
   • Starred repositories automatically go to a dedicated organization

Development

# Install dependencies
bun install

# Run development server
bun run dev

# Run tests
bun test

# Build for production
bun run build

Technologies

• Frontend: Astro, React, Shadcn UI, Tailwind CSS v4
• Backend: Bun runtime, SQLite, Drizzle ORM
• APIs: GitHub (Octokit), Gitea REST API
• Auth: JWT tokens with bcryptjs password hashing

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on our code of conduct and the process for submitting pull requests.

License

GNU General Public License v3.0 - see LICENSE file for details.

Support

• 📖 Documentation
• 🔐 Custom CA Certificates
• 🐛 Report Issues
• 💬 Discussions
• 🔧 Proxmox VE Script