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](UPGRADE.md) for instructions. ## 🚀 Quick Start ```bash # 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!

Dashboard Dashboard Mobile

## ✨ Features - 🔁 Mirror public, private, and starred GitHub repos to Gitea - 🏢 Mirror entire organizations with flexible strategies - 🎯 Custom destination control for repos and organizations - 📦 **Git LFS support** - Mirror large files with Git LFS - 📝 **Metadata mirroring** - Issues, pull requests (as issues), labels, milestones, wiki - 🚫 **Repository ignore** - Mark specific repos to skip - 🔐 Secure authentication with Better Auth (email/password, SSO, OIDC) - 📊 Real-time dashboard with activity logs - ⏱️ Scheduled automatic mirroring with configurable intervals - 🔄 **Auto-discovery** - Automatically import new GitHub repositories (v3.4.0+) - 🧹 **Repository cleanup** - Auto-remove repos deleted from GitHub (v3.4.0+) - 🎯 **Proper mirror intervals** - Respects configured sync intervals (v3.4.0+) - 🗑️ Automatic database cleanup with configurable retention - 🐳 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: ```bash # 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: ```bash # 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 ```bash 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): ```bash # 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](docker-compose.yml) for all available options including GitHub tokens, Gitea URLs, mirror settings, and more. 📚 **For a complete list of all supported environment variables, see the [Environment Variables Documentation](docs/ENVIRONMENT_VARIABLES.md).** ### LXC Container (Proxmox) ```bash # 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](https://community-scripts.github.io/ProxmoxVE/scripts?id=gitea-mirror) for more details. ### Manual Installation ```bash # 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 ## Advanced Features ### Git LFS (Large File Storage) Mirror Git LFS objects along with your repositories: - Enable "Mirror LFS" option in Settings → Mirror Options - Requires Gitea server with LFS enabled (`LFS_START_SERVER = true`) - Requires Git v2.1.2+ on the server ### Metadata Mirroring Transfer complete repository metadata from GitHub to Gitea: - **Issues** - Mirror all issues with comments and labels - **Pull Requests** - Transfer PR discussions to Gitea - **Labels** - Preserve repository labels - **Milestones** - Keep project milestones - **Wiki** - Mirror wiki content - **Releases** - Transfer GitHub releases with assets Enable in Settings → Mirror Options → Mirror metadata ### Repository Management - **Ignore Status** - Mark repositories to skip from mirroring - **Automatic Cleanup** - Configure retention period for activity logs - **Scheduled Sync** - Set custom intervals for automatic mirroring ### Automatic Syncing & Synchronization Gitea Mirror provides powerful automatic synchronization features: #### Features (v3.4.0+) - **Auto-discovery**: Automatically discovers and imports new GitHub repositories - **Repository cleanup**: Removes repositories that no longer exist in GitHub - **Proper intervals**: Mirrors respect your configured sync intervals (not Gitea's default 24h) - **Smart scheduling**: Only syncs repositories that need updating - **Auto-start on boot** (v3.5.3+): Automatically imports and mirrors all repositories when `SCHEDULE_ENABLED=true` or `GITEA_MIRROR_INTERVAL` is set #### Configuration via Web Interface (Recommended) Navigate to the Configuration page and enable "Automatic Syncing" with your preferred interval. #### Configuration via Environment Variables **Set it and forget it!** With these environment variables, Gitea Mirror will automatically: 1. Import all your GitHub repositories on startup 2. Mirror them to Gitea immediately 3. Keep them synchronized based on your interval 4. Auto-discover new repos you create/star on GitHub 5. Clean up repos you delete from GitHub ```bash # Enable automatic scheduling (required for auto features) SCHEDULE_ENABLED=true # Mirror interval (how often to sync) GITEA_MIRROR_INTERVAL=8h # Every 8 hours (default) # Other examples: 5m, 30m, 1h, 24h, 1d, 7d # Auto-import new repositories (default: true) AUTO_IMPORT_REPOS=true # Auto-cleanup orphaned repositories CLEANUP_DELETE_IF_NOT_IN_GITHUB=true CLEANUP_ORPHANED_REPO_ACTION=archive # 'archive' (recommended) or 'delete' CLEANUP_DRY_RUN=false # Set to true to test without changes ``` **Important Notes**: - **Auto-Start**: When `SCHEDULE_ENABLED=true` or `GITEA_MIRROR_INTERVAL` is set, the service automatically imports all GitHub repositories and mirrors them on startup. No manual "Import" or "Mirror" button clicks required! - The scheduler checks every minute for tasks to run. The `GITEA_MIRROR_INTERVAL` determines how often each repository is actually synced. For example, with `8h`, each repo syncs every 8 hours from its last successful sync. **🛡️ Backup Protection Features**: - **No Accidental Deletions**: Repository cleanup is automatically skipped if GitHub is inaccessible (account deleted, banned, or API errors) - **Archive Never Deletes Data**: The `archive` action preserves all repository data: - Regular repositories: Made read-only using Gitea's archive feature - Mirror repositories: Renamed with `[ARCHIVED]` prefix (Gitea API limitation prevents archiving mirrors) - Failed operations: Repository remains fully accessible even if marking as archived fails - **The Whole Point of Backups**: Your Gitea mirrors are preserved even when GitHub sources disappear - that's why you have backups! - **Strongly Recommended**: Always use `CLEANUP_ORPHANED_REPO_ACTION=archive` (default) instead of `delete` ## 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](https://github.com/RayLabsHQ/gitea-mirror/issues/43) for reference. ## Development ```bash # 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:** ```bash # 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:** ```nginx # 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 ## Known Limitations ### Pull Request Mirroring Implementation Pull requests **cannot be created as actual PRs** in Gitea due to API limitations. Instead, they are mirrored as **enriched issues** with comprehensive metadata. **Why real PR mirroring isn't possible:** - Gitea's API doesn't support creating pull requests from external sources - Real PRs require actual Git branches with commits to exist in the repository - Would require complex branch synchronization and commit replication - The mirror relationship is one-way (GitHub → Gitea) for repository content **How we handle Pull Requests:** PRs are mirrored as issues with rich metadata including: - 🏷️ Special "pull-request" label for identification - 📌 [PR #number] prefix in title with status indicators ([MERGED], [CLOSED]) - 👤 Original author and creation date - 📝 Complete commit history (up to 10 commits with links) - 📊 File changes summary with additions/deletions - 📁 List of modified files (up to 20 files) - 💬 Original PR description and comments - 🔀 Base and head branch information - ✅ Merge status tracking This approach preserves all important PR information while working within Gitea's API constraints. The PRs appear in Gitea's issue tracker with clear visual distinction and comprehensive details. ## Contributing Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. ## License GNU General Public License v3.0 - see [LICENSE](LICENSE) file for details. ## Star History

## Support - 📖 [Documentation](https://github.com/RayLabsHQ/gitea-mirror/tree/main/docs) - 🔐 [Custom CA Certificates](docs/CA_CERTIFICATES.md) - 🐛 [Report Issues](https://github.com/RayLabsHQ/gitea-mirror/issues) - 💬 [Discussions](https://github.com/RayLabsHQ/gitea-mirror/discussions) - 🔧 [Proxmox VE Script](https://community-scripts.github.io/ProxmoxVE/scripts?id=gitea-mirror)