Gitea Mirror

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

Important

Upgrading to v3? v3 requires a fresh start with a new data volume. Please read the Upgrade Guide for instructions.

🚀 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 Better Auth (email/password, SSO, OIDC)
• 📊 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:v3.1.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

# Session secret (auto-generated if not set)
BETTER_AUTH_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

Troubleshooting

Reverse Proxy Configuration

If using a reverse proxy (e.g., nginx proxy manager) and experiencing issues with JavaScript files not loading properly, try enabling HTTP/2 support in your proxy configuration. While not required by the application, some proxy configurations may have better compatibility with HTTP/2 enabled. See issue #43 for reference.

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: Better Auth with session-based authentication

Security

Token Encryption

• All GitHub and Gitea API tokens are encrypted at rest using AES-256-GCM
• Encryption is automatic and transparent to users
• Set ENCRYPTION_SECRET environment variable for production deployments
• Falls back to BETTER_AUTH_SECRET if not set

Password Security

• User passwords are securely hashed by Better Auth
• Never stored in plaintext
• Secure cookie-based session management

Authentication

Gitea Mirror supports multiple authentication methods. Email/password authentication is the default and always enabled.

1. Email & Password (Default)

The standard authentication method. First user to sign up becomes the admin.

2. Single Sign-On (SSO) with OIDC

Enable users to sign in with external identity providers like Google, Azure AD, Okta, Authentik, or any OIDC-compliant service.

Configuration:

1. Navigate to Settings → Authentication & SSO
2. Click "Add Provider"
3. Enter your OIDC provider details:
   • Issuer URL (e.g., https://accounts.google.com)
   • Client ID and Secret from your provider
   • Use the "Discover" button to auto-fill endpoints

Redirect URL for your provider:

https://your-domain.com/api/auth/sso/callback/{provider-id}

3. Header Authentication (Reverse Proxy)

Perfect for automatic authentication when using reverse proxies like Authentik, Authelia, or Traefik Forward Auth.

Environment Variables:

# Enable header authentication
HEADER_AUTH_ENABLED=true

# Header names (customize based on your proxy)
HEADER_AUTH_USER_HEADER=X-Authentik-Username
HEADER_AUTH_EMAIL_HEADER=X-Authentik-Email
HEADER_AUTH_NAME_HEADER=X-Authentik-Name

# Auto-provision new users
HEADER_AUTH_AUTO_PROVISION=true

# Restrict to specific email domains (optional)
HEADER_AUTH_ALLOWED_DOMAINS=example.com,company.org

How it works:

• Users authenticated by your reverse proxy are automatically logged in
• No additional login step required
• New users can be auto-provisioned if enabled
• Falls back to regular authentication if headers are missing

Example Authentik Configuration:

# In your reverse proxy configuration
proxy_set_header X-Authentik-Username $authentik_username;
proxy_set_header X-Authentik-Email $authentik_email;
proxy_set_header X-Authentik-Name $authentik_name;

4. OAuth Applications (Act as Identity Provider)

Gitea Mirror can also act as an OIDC provider for other applications. Register OAuth applications in Settings → Authentication & SSO → OAuth Applications tab.

Use cases:

• Allow other services to authenticate using Gitea Mirror accounts
• Create service-to-service authentication
• Build integrations with your Gitea Mirror instance

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.

Star History

Support

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