@@ -33,15 +35,16 @@ First user signup becomes admin. Configure GitHub and Gitea/Forgejo through the
- ๐ข 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
+- ๐ **Metadata mirroring** - Issues, pull requests (as issues), labels, milestones, releases, wiki
- ๐ซ **Repository ignore** - Mark specific repos to skip
-- ๐ Secure authentication with Better Auth (email/password, SSO, OIDC)
+- ๐ Secure authentication with Better Auth (email/password, SSO, OIDC, header auth)
+- ๐ **[Notifications](docs/NOTIFICATIONS.md)** - ntfy, Apprise, Gotify, or any webhook with signed payloads
- ๐ 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+)
-- ๐ก๏ธ **[Force-push protection](docs/FORCE_PUSH_PROTECTION.md)** - Smart detection with backup-on-demand or block-and-approve modes (Beta)
+- ๐ **Auto-discovery** - Automatically import new GitHub repositories
+- ๐งน **Repository cleanup** - Auto-remove repos deleted from GitHub
+- ๐ฏ **Proper mirror intervals** - Respects configured sync intervals
+- ๐ก๏ธ **[Force-push protection](docs/FORCE_PUSH_PROTECTION.md)** - Smart detection with backup-on-demand or block-and-approve modes
- ๐๏ธ Automatic database cleanup with configurable retention
- ๐ณ Dockerized with multi-arch support (AMD64/ARM64)
@@ -49,7 +52,7 @@ First user signup becomes admin. Configure GitHub and Gitea/Forgejo through the
- 
+
-
-
-
-
-
- Advanced
-
- Advanced Topics
-- Advanced configuration options, deployment strategies, troubleshooting, and performance optimization for Gitea Mirror. -
-Environment Variables
- -- Gitea Mirror can be configured using environment variables. These are particularly useful for containerized deployments. -
- -
-
-
-
-
- | Variable | -Description | -Default | -
|---|---|---|
| {item.var} | -{item.desc} | -{item.default} | -
Database Management
- -- Gitea Mirror uses SQLite for data storage. The database is automatically created on first run. -
- -Database Commands
- -
-
-
-
-
-
- Initialize Database
-
-
- bun run init-db
- Creates or recreates the database schema
-
-
-
- Check Database
-
-
- bun run check-db
- Verifies database integrity and displays statistics
-
-
-
- Fix Database
-
-
- bun run fix-db
- Attempts to repair common database issues
-
-
- Backup Database
-
-
- cp data/gitea-mirror.db data/gitea-mirror.db.backup
- Always backup before major changes
-Database Schema Management
- -
-
-
-
-
-
-
-
-
- Drizzle Kit
-Database schema is managed with Drizzle ORM. Use these commands for schema changes:
--
-
bun run drizzle-kit generate- Generate migration files
- bun run drizzle-kit push- Apply schema changes directly
- bun run drizzle-kit studio- Open database browser
-
Performance Optimization
- -Mirroring Performance
- -
- {[
- {
- title: 'Batch Operations',
- tips: [
- 'Mirror multiple repositories at once',
- 'Use organization-level mirroring',
- 'Schedule mirroring during off-peak hours'
- ]
- },
- {
- title: 'Network Optimization',
- tips: [
- 'Use SSH URLs when possible',
- 'Enable Git LFS only when needed',
- 'Consider repository size limits'
- ]
- }
- ].map(section => (
-
-
-
-
- ))}
- {section.title}
--
- {section.tips.map(tip => (
-
- - โข - {tip} - - ))} -
Database Performance
- -
-
- Regular Maintenance
--
-
- - โข - Enable automatic cleanup in Configuration โ Automation - -
-
- โข
- Periodically vacuum the SQLite database:
sqlite3 data/gitea-mirror.db "VACUUM;"-
- - - โข - Monitor database size and clean old events regularly - -
Reverse Proxy Configuration
- -- For production deployments, it's recommended to use a reverse proxy like Nginx or Caddy. -
- -
-
-
-
-
-
-
-
-
-
- Required Environment Variables for Reverse Proxy
-- When running Gitea Mirror behind a reverse proxy, you must set these environment variables to your external URL. - Without them, sign-in will fail with "invalid origin" errors and pages may appear blank. -
-
-
- {`# All three MUST be set to your external URL:
-BETTER_AUTH_URL=https://gitea-mirror.example.com
-PUBLIC_BETTER_AUTH_URL=https://gitea-mirror.example.com
-BETTER_AUTH_TRUSTED_ORIGINS=https://gitea-mirror.example.com`}
-
- {`# If deployed under a path prefix (example: /mirror):
-# BASE_URL handles the path โ auth URLs stay as origin only
-BASE_URL=/mirror
-BETTER_AUTH_URL=https://git.example.com
-PUBLIC_BETTER_AUTH_URL=https://git.example.com
-BETTER_AUTH_TRUSTED_ORIGINS=https://git.example.com
-# โ Auth endpoints resolve to: https://git.example.com/mirror/api/auth/*`}-
-
BASE_URLโ Application base path for path-prefix deployments (e.g./mirror). This is handled separately from the auth URLs.
- BETTER_AUTH_URLโ Server-side auth origin, scheme + host only (e.g.https://git.example.com). Do not include the base path โ it is applied automatically fromBASE_URL.
- PUBLIC_BETTER_AUTH_URLโ Client-side (browser) auth origin. Same rule: origin only, no path.
- BETTER_AUTH_TRUSTED_ORIGINSโ Comma-separated origins allowed to make auth requests
-
Docker Compose Example
- -
-
-
- {`services:
- gitea-mirror:
- image: ghcr.io/raylabshq/gitea-mirror:latest
- environment:
- - BETTER_AUTH_SECRET=your-secret-key-min-32-chars
- - BASE_URL=/mirror
- - BETTER_AUTH_URL=https://git.example.com
- - PUBLIC_BETTER_AUTH_URL=https://git.example.com
- - BETTER_AUTH_TRUSTED_ORIGINS=https://git.example.com
- # ... other settings ...`}Nginx Example
- -
-
-
- {`server {
- listen 80;
- server_name gitea-mirror.example.com;
- return 301 https://$server_name$request_uri;
-}
-
-server {
- listen 443 ssl http2;
- server_name gitea-mirror.example.com;
-
- ssl_certificate /path/to/cert.pem;
- ssl_certificate_key /path/to/key.pem;
-
- location / {
- proxy_pass http://localhost:4321;
- proxy_http_version 1.1;
- proxy_set_header Upgrade $http_upgrade;
- proxy_set_header Connection 'upgrade';
- proxy_set_header Host $host;
- proxy_cache_bypass $http_upgrade;
- proxy_set_header X-Real-IP $remote_addr;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- }
-
- # SSE endpoint needs special handling
- location /api/sse {
- proxy_pass http://localhost:4321;
- proxy_http_version 1.1;
- proxy_set_header Connection '';
- proxy_set_header Cache-Control 'no-cache';
- proxy_set_header X-Accel-Buffering 'no';
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- proxy_set_header X-Forwarded-Proto $scheme;
- proxy_read_timeout 86400;
- }
-}`}Caddy Example
- -
-
- {`gitea-mirror.example.com {
- reverse_proxy localhost:4321
-}`}Monitoring and Health Checks
- -Health Check Endpoint
- -
-
-
- Monitor application health using the built-in endpoint:
- -
-
-
- GET /api/health
- Response:
-
-
- {`{
- "status": "ok",
- "timestamp": "2024-01-15T10:30:00Z",
- "database": "connected",
- "version": "1.0.0"
-}`}Monitoring with Prometheus
- -- While Gitea Mirror doesn't have built-in Prometheus metrics, you can monitor it using: -
- --
-
- - โข - Blackbox exporter for endpoint monitoring - -
- - โข - Node exporter for system metrics - -
- - โข - Custom scripts to check database metrics - -
Backup and Recovery
- -What to Backup
- -
-
-
-
-
-
- Essential Files
--
-
- โข data/gitea-mirror.db -
- โข .env (if using) -
- โข Custom CA certificates -
-
- Optional Files
--
-
- โข Docker volumes -
- โข Custom configurations -
- โข Logs for auditing -
Backup Script Example
- -
-
- {`#!/bin/bash
-BACKUP_DIR="/backups/gitea-mirror"
-DATE=$(date +%Y%m%d_%H%M%S)
-
-# Create backup directory
-mkdir -p "$BACKUP_DIR/$DATE"
-
-# Backup database
-cp data/gitea-mirror.db "$BACKUP_DIR/$DATE/"
-
-# Backup environment
-cp .env "$BACKUP_DIR/$DATE/" 2>/dev/null || true
-
-# Create tarball
-tar -czf "$BACKUP_DIR/backup_$DATE.tar.gz" -C "$BACKUP_DIR" "$DATE"
-
-# Clean up
-rm -rf "$BACKUP_DIR/$DATE"
-
-# Keep only last 7 backups
-ls -t "$BACKUP_DIR"/backup_*.tar.gz | tail -n +8 | xargs rm -f`}Troubleshooting Guide
- -
- {[
- {
- issue: 'Application won\'t start',
- solutions: [
- 'Check port availability: `lsof -i :4321`',
- 'Verify environment variables are set correctly',
- 'Check database file permissions',
- 'Review logs for startup errors'
- ]
- },
- {
- issue: 'Authentication failures',
- solutions: [
- 'Ensure BETTER_AUTH_SECRET is set and consistent',
- 'Check BETTER_AUTH_URL matches your deployment',
- 'Clear browser cookies and try again',
- 'Verify database contains user records'
- ]
- },
- {
- issue: 'Mirroring failures',
- solutions: [
- 'Test GitHub/Gitea connections individually',
- 'Verify access tokens have correct permissions',
- 'Check network connectivity and firewall rules',
- 'Review Activity Log for detailed error messages'
- ]
- },
- {
- issue: 'Performance issues',
- solutions: [
- 'Check database size and run cleanup',
- 'Monitor system resources (CPU, memory, disk)',
- 'Reduce concurrent mirroring operations',
- 'Consider upgrading deployment resources'
- ]
- }
- ].map(item => (
-
-
-
- ))}
- {item.issue}
--
- {item.solutions.map(solution => (
-
- - โ - {solution} - - ))} -
Migration Guide
- -Migrating from JWT to Better Auth
- -
-
- If you're upgrading from an older version using JWT authentication:
- --
-
-
- 1
- - Backup your database --
Always create a backup before migration
-
- -
- 2
- - Update environment variables --
Replace JWT_SECRET with BETTER_AUTH_SECRET
-
- -
- 3
- - Run database migrations --
New auth tables will be created automatically
-
- -
- 4
- - Users will need to log in again --
Previous sessions will be invalidated
-
-