Gitea Mirror

Last reviewed Sep 13, 2026 · 791 words

Gitea can already mirror a GitHub repository by itself: New Migration, tick "This repository will be a mirror", set an interval, done. What it cannot do is notice that you starred 40 new repositories last quarter, that your organisation added 6 projects, or that a repo you archived on GitHub should be archived locally too. Gitea Mirror, the RayLabsHQ project the catalogue lists as Gitea Mirror Manager, is the discovery and scheduling layer on top of that built-in feature. If you have fewer than 10 repositories to protect, use Gitea's own screen. If you want "everything I own, everything my org owns and everything I starred, kept current without me remembering", this is the 256 MB container that does it.

What it actually does

You give it a GitHub token and a Gitea token. It enumerates your repositories, your organisations' repositories and optionally your starred ones, shows them in a dashboard, and creates mirror repositories on the Gitea side using Gitea's migration API. From then on a scheduler re-runs discovery, adds new repositories, and triggers mirror syncs on your interval. Per-repo you can include issues, pull requests, wiki, labels, milestones and releases in the migration, which plain Git mirroring does not carry. Organisation structure can be preserved as Gitea organisations or flattened under one account, and starred repositories can land in their own organisation so they do not pollute your namespace.

It works against Forgejo too, since the API it uses is the one the two forges share.

Setup is a single image and two tokens

The image is ghcr.io/raylabshq/gitea-mirror, a Bun-served Astro application with a SQLite database on a /data volume, and the web interface defaults to port 4321. Environment variables cover the base URL and an auth secret; tokens are entered in the UI on first run. The GitHub token needs repository and organisation read scopes, and starred-repository discovery needs read access to your user profile. The Gitea token needs permission to create repositories and organisations. Nothing else is required, which is why the catalogue rates it Easy; a 1-vCPU VPS is plenty.

The scheduling knob deserves a thought. Discovery against the GitHub API is cheap; the mirror sync on the Gitea side clones every changed repository, and 300 repositories on a 15-minute cadence will keep a small server busy for no benefit. Daily is plenty for a backup; hourly for repositories you actively push to.

One-way, and that is the point

Mirrors are read-only on the Gitea side. You cannot push to them, open pull requests against them, or resolve a conflict; changes flow from GitHub to Gitea only. That makes this a backup and an offline reference, not a migration tool. If the goal is to leave GitHub, do a one-time migration with issues and PRs, then switch remotes and never sync again. Gitea Mirror is for the person who stays on GitHub for the network effects and wants a full, current copy on their own disk in case an account lock, an outage or a policy change removes access. That scenario is the one that makes the self-hosted forge argument for most people.

Gickup covers the other direction and more targets

Gickup is the neighbouring project: a YAML-configured job that clones from GitHub, GitLab, Gitea, Bitbucket and others to a local path, S3 or another forge. It has no dashboard and no Gitea-specific features, but it handles "back up everything from every provider to a plain directory", which Gitea Mirror does not attempt. Run Gickup if you want dumb, portable clones on a schedule; run Gitea Mirror if the destination is a browsable Gitea and you want issues and releases along for the ride.

Young project, fast-moving

First released in 2024, the code changes often and the configuration model has shifted between releases. Pin a version tag, back up /data before upgrading, and expect an occasional re-authorisation of tokens. The upside of youth is responsiveness: issues get answered and features arrive monthly rather than yearly. The downside is that a tool whose whole purpose is being reliably boring is not yet boring.

What I'd do

Gitea or Forgejo already running, Gitea Mirror on the same host, one GitHub token with the three scopes, starred repositories into a starred organisation, daily discovery, hourly sync only for the 5 repositories I push to weekly. Verify by cloning one mirror from Gitea and building it. Under 10 repositories, skip this and click "mirror" in Gitea by hand. And if you ever decide to leave GitHub for good, migrate once with history and turn the mirroring off.