--- import MainLayout from '../../layouts/main.astro'; const envVars = [ { name: 'NODE_ENV', desc: 'Runtime environment', default: 'development', example: 'production' }, { name: 'DATABASE_URL', desc: 'SQLite database URL', default: 'file:data/gitea-mirror.db', example: 'file:path/to/database.db' }, { name: 'JWT_SECRET', desc: 'Secret key for JWT auth', default: 'Auto-generated', example: 'your-secure-string' }, { name: 'HOST', desc: 'Server host', default: 'localhost', example: '0.0.0.0' }, { name: 'PORT', desc: 'Server port', default: '4321', example: '8080' } ]; const githubOptions = [ { name: 'Username', desc: 'Your GitHub username', default: '-' }, { name: 'Token', desc: 'GitHub personal access token (Classic PAT)', default: '-' }, { name: 'Private Repositories', desc: 'Include private repositories', default: 'false' }, { name: 'Mirror Starred', desc: 'Mirror repositories you\'ve starred', default: 'false' }, { name: 'Mirror Issues', desc: 'Mirror issues from GitHub to Gitea', default: 'false' }, { name: 'Mirror Wiki', desc: 'Mirror wiki pages from GitHub to Gitea', default: 'false' }, { name: 'Mirror Organizations', desc: 'Mirror organization repositories', default: 'false' }, { name: 'Only Mirror Orgs', desc: 'Only mirror organization repositories', default: 'false' }, { name: 'Skip Forks', desc: 'Exclude repositories that are forks', default: 'false' }, { name: 'Skip Starred Issues', desc: 'Skip issues for starred repositories', default: 'false' } ]; const giteaOptions = [ { name: 'URL', desc: 'Gitea server URL', default: '-' }, { name: 'Token', desc: 'Gitea access token', default: '-' }, { name: 'Organization', desc: 'Default organization for mirrored repositories', default: '-' }, { name: 'Visibility', desc: 'Default visibility for mirrored repositories', default: 'public' }, { name: 'Starred Repos Org', desc: 'Organization for starred repositories', default: 'github' } ]; ---
Back to Documentation
Configuration Guide

Gitea Mirror Configuration

This guide provides detailed information on how to configure Gitea Mirror for your environment.

Configuration Methods

🔧

Environment Variables

Set configuration options through environment variables for automated deployments

🖥️

Web UI

Configure the application through the web interface after installation

Environment Variables

The following environment variables can be used to configure Gitea Mirror:

{envVars.map((v, i) => ( ))}
Variable Description Default Example
{v.name} {v.desc} {v.default} {v.example}

Security Note

The application will automatically generate a secure random JWT_SECRET on first run if one isn't provided. This generated secret is stored in the data directory for persistence across container restarts.

While this auto-generation feature provides good security by default, you can still explicitly set your own JWT_SECRET for complete control over your deployment.

Web UI Configuration

After installing and starting Gitea Mirror, you can configure it through the web interface:

    {[ 'Navigate to http://your-server:port/', 'If this is your first time, you\'ll be guided through creating an admin account', 'Log in with your credentials', 'Go to the Configuration page' ].map((step, i) => (
  1. {i + 1}
    2. ))}

GitHub Configuration

The GitHub configuration section allows you to connect to GitHub and specify which repositories to mirror.

{githubOptions.map((opt, i) => ( ))}
Option Description Default
{opt.name} {opt.desc} {opt.default}

Required Permissions

You need to create a Classic GitHub PAT Token with the following scopes:

  • • repo - Full control of private repositories
  • • admin:org - Full control of orgs and teams, read and write org projects

The organization access is required for mirroring organization repositories.

To create a GitHub token:
  1. Go to GitHub Settings > Developer settings > Personal access tokens
  2. Click "Generate new token"
  3. Select the required permissions
  4. Copy the generated token and paste it into Gitea Mirror

Gitea Configuration

The Gitea configuration section allows you to connect to your Gitea instance and specify how repositories should be mirrored.

{giteaOptions.map((opt, i) => ( ))}
Option Description Default
{opt.name} {opt.desc} {opt.default}

Mirror Strategies

Choose how your repositories will be organized in Gitea:

📁 Preserve GitHub Structure

Maintains the exact structure from GitHub:

  • • Personal repos → Your Gitea username
  • • Organization repos → Same organization name in Gitea
🏢 Single Organization

Consolidates all repositories into one organization:

  • • All repos → One designated organization
  • • Requires setting "Organization" field
👤 Flat User Structure

Mirrors all repositories under your user account:

  • • All repos → Your Gitea username
  • • No organizations needed

Note: Starred repositories are always mirrored to the "Starred Repos Org" (default: "starred") regardless of the chosen strategy.

To create a Gitea access token:
  1. Log in to your Gitea instance
  2. Go to Settings > Applications
  3. Under "Generate New Token", enter a name for your token
  4. Click "Generate Token"
  5. Copy the generated token and paste it into Gitea Mirror

Schedule Configuration

You can configure automatic mirroring on a schedule:

Option Description Default
Enable Scheduling Enable automatic mirroring false
Interval (seconds) Time between mirroring operations 3600 (1 hour)

Advanced Configuration

Database Management

Gitea Mirror includes several database management tools that can be run from the command line:

{`# Initialize the database (only if it doesn't exist)
bun run init-db

# Check database status
bun run check-db

# Fix database location issues
bun run fix-db

# Reset all users (for testing signup flow)
bun run reset-users

# Remove database files completely
bun run cleanup-db`}

Event Management

Events in Gitea Mirror (such as repository mirroring operations) are stored in the SQLite database and can be viewed in the Activity Log page.

Event Management Features:

  • • View all events with filtering by type, status, and search
  • • Real-time updates via Server-Sent Events (SSE)
  • • Clean up old events using the cleanup button in the Activity Log
  • • Automatic cleanup with configurable retention period

Automatic Recovery System

Gitea Mirror includes a robust recovery system that automatically handles interrupted operations:

  • ✓
    Startup Recovery:

    Automatically recovers interrupted jobs when the application starts

  • ✓
    Graceful Shutdown:

    Saves job state before shutting down to enable recovery on restart

  • ✓
    Job State Persistence:

    Stores mirror job progress in the database for resilience

Manual recovery tools:

{`# Run startup recovery manually
bun run startup-recovery

# Fix interrupted jobs
bun scripts/fix-interrupted-jobs.ts

# Test recovery system
bun run test-recovery`}

Health Check Endpoint

System Health Monitoring

Gitea Mirror includes a built-in health check endpoint at /api/health that provides:

  • ✓ System status and uptime
  • ✓ Database connectivity check
  • ✓ Memory usage statistics
  • ✓ Environment information 
{`# Basic check (returns 200 OK if healthy)
curl -I http://your-server:port/api/health

# Detailed health information (JSON)
curl http://your-server:port/api/health`}