Welcome to the Gitea Mirror documentation. This guide covers everything you need to know about developing, building, and deploying the open-source version of Gitea Mirror.

Documentation Overview

Getting Started

Development Workflow - Set up your development environment and start contributing
Build Guide - Build Gitea Mirror from source
Configuration Guide - Configure all available options

Deployment

Deployment Guide - Deploy to production environments
Docker Guide - Container-based deployment
Reverse Proxy Setup - Configure with nginx/Caddy

Features

SSO/OIDC Setup - Configure authentication providers
Sponsor Integration - GitHub Sponsors integration
Webhook Configuration - Set up GitHub webhooks

Marketing Site

Use Case Library (www/src/pages/use-cases/) - MDX guides surfaced on the landing page use case section
Use Case Cards (www/src/lib/use-cases.ts) - Central place to update titles, summaries, and CTA links shown across the site

Architecture

Architecture Overview - System design and components
API Documentation - REST API endpoints
Database Schema - SQLite structure

Maintenance

Migration Guide - Upgrade from previous versions
Better Auth Migration - Migrate authentication system
Troubleshooting - Common issues and solutions
Backup & Restore - Data management

Quick Start

Clone and install:

git clone https://github.com/yourusername/gitea-mirror.git
cd gitea-mirror
bun install

Configure:

cp .env.example .env
# Edit .env with your GitHub and Gitea tokens

Initialize and run:

bun run init-db
bun run dev

Access: Open http://localhost:4321

Key Features

🔄 Automatic Syncing - Keep repositories synchronized
🗂️ Organization Support - Mirror entire organizations
⭐ Starred Repos - Mirror your starred repositories
🔐 Self-Hosted - Full control over your data
🚀 Fast - Built with Bun for optimal performance
🔒 Secure - JWT authentication, encrypted tokens

Technology Stack

Runtime: Bun
Framework: Astro with React
Database: SQLite with Drizzle ORM
Styling: Tailwind CSS v4
Authentication: Better Auth

System Requirements

Bun >= 1.2.9
Node.js >= 20 (optional, for compatibility)
SQLite 3
512MB RAM minimum
1GB disk space

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

Code of Conduct

Please read our Code of Conduct before contributing.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Wiki: GitHub Wiki

Security

For security issues, please see SECURITY.md.

License

Gitea Mirror is open source software licensed under the MIT License.

For detailed information on any topic, please refer to the specific documentation guides listed above.