Built by and for homelab tinkerers
Gitea Mirror in Action: Use Cases for Self-Hosted GitHub Backups
Gitea Mirror is an open-source side project. It’s perfect for your homelab, indie dev studio, or early-stage team that needs backups and optional failover. There’s no enterprise SLA—just practical playbooks you can own, fork, and improve.
Ideal for
Homelabbers, solo builders, and scrappy startups that want GitHub peace of mind without managed pricing.
Worth noting
Community support only. No compliance guarantees, no 24/7 pager. Kick the tires before depending on it.
Use Cases
Real-World Gitea Mirror Workflows
Discover how developers and teams are using Gitea Mirror to create reliable, self-hosted backups of their GitHub repositories. These use cases provide step-by-step instructions for common scenarios.
Backup GitHub Repositories
Continuously mirror GitHub repositories into self-hosted Gitea so your side projects stay safe even when GitHub hiccups.
- Pain Point
- Homelabbers rely on GitHub availability but want local backups that preserve history, metadata, and LFS assets.
- Outcome
- Automated syncs capture full repository history, metadata, and file storage so you always have an up-to-date local copy.
Deploy with Helm Chart
Install the project on Kubernetes in a few commands using the maintained Helm chart to keep your backup mirror humming.
- Pain Point
- Self-hosters want reproducible Git backups without hand-rolling manifests for every cluster or upgrade.
- Outcome
- Versioned Helm values capture backup config, making redeploys and upgrades fast, scriptable, and low-risk.
Spin Up on Proxmox LXC
Run the one-liner Proxmox VE script to launch gitea-mirror inside a tuned LXC container for your lab backups.
- Pain Point
- Proxmox homelabbers want a repeatable Git backup without manually wiring containers, volumes, and services.
- Outcome
- The community script provisions the container, installs Bun, and wires persistence so mirroring works minutes after boot.
Sync GitHub to Self-Hosted Gitea
Run continuous mirrors so your homelab Gitea instance stays in lockstep with GitHub without manual pulls.
- Pain Point
- Tinkerers want to keep a local Gitea in sync but `git pull --mirror` cron jobs break on metadata and new repos.
- Outcome
- Gitea Mirror auto-discovers repos, syncs metadata, and respects intervals so your LAN copy matches upstream every hour.
Preserve GitHub History Forever
Archive commit history, issues, and releases into Gitea so side projects survive account removals or repo deletion.
- Pain Point
- Homelab archivists fear SaaS changes wiping years of work, but manual exports miss metadata and LFS assets.
- Outcome
- Scheduled mirrors capture full history with metadata snapshots, giving you an air-gapped archive you control.
Automate GitHub Backups
Replace brittle scripts with policy-driven schedules, health checks, and alerts that keep your Git backups honest.
- Pain Point
- Cron jobs and shell scripts fail silently, leaving you with stale mirrors when you need a restore most.
- Outcome
- Gitea Mirror tracks sync status, retries failures, and exposes health endpoints so you can trust every backup window.
Build a Starred Repo Collection
Mirror starred GitHub projects into your own Gitea library so favorites stay browsable even when upstream disappears.
- Pain Point
- Curators star dozens of repos but lose them when owners delete or rename, and there’s no offline copy.
- Outcome
- The starred collector funnels every star into a dedicated Gitea org with metadata intact for long-term tinkering.
Stay Ready to Leave GitHub
Keep an always-current mirror so you can pivot from GitHub to self-hosted tooling whenever policies shift.
- Pain Point
- Indie builders worry about pricing, auth changes, or ToS updates but lack a live fallback they can swap to instantly.
- Outcome
- Continuous mirrors mean you can flip DNS to Gitea, keep working locally, and evaluate alternatives without downtime.
Migrate from GitHub to Gitea
Move repositories, issues, PRs, releases, and wikis to self-hosted Gitea by running both platforms in parallel until the switch sticks.
- Pain Point
- One-shot migrations copy the code and lose everything else, so teams drift back to GitHub within weeks.
- Outcome
- A continuously updated mirror carries the whole project, letting you flip the default only when reads and CI already live on Gitea.
Mirror Git LFS Repositories
Bring LFS objects along with your mirrors, and turn LFS off per repository when a broken LFS store blocks the whole migration.
- Pain Point
- One repository with missing LFS objects fails its entire Gitea migration, and a global LFS switch forces an all-or-nothing choice.
- Outcome
- Per-repository overrides mirror LFS content where it works and skip it where it does not, so no repository is left behind.
Survive GitHub API Rate Limits
Understand what the 5,000 requests per hour budget means for mirroring and why conditional requests make frequent syncs nearly free.
- Pain Point
- Metadata-heavy syncs across hundreds of repositories can burn the hourly API budget and stall naive mirroring tools.
- Outcome
- ETag-based conditional requests turn unchanged answers into free 304s, so sync cost tracks what changed rather than how often you check.
Mirror Issues and Pull Requests
Carry issue threads, review discussions, releases, and wikis into Gitea, converted honestly where the platforms differ.
- Pain Point
- Clones preserve commits but lose the issue and PR history where the real project knowledge lives.
- Outcome
- Issues arrive as native Gitea issues and PRs become labeled, searchable records with commits and merge status intact.
GitHub Backup on Unraid
Install from Community Applications, point it at the Gitea container you already run, and fold GitHub backups into your appdata routine.
- Pain Point
- Unraid users have the hardware and Gitea running, but wiring GitHub backups by hand means scripts and cron jobs.
- Outcome
- The CA template pre-wires ports, paths, and secrets so scheduled, auto-discovering backups run on the NAS you already manage.
Mirror GitLab Projects to Gitea
Point the source at gitlab.com or your own GitLab (beta) and keep projects, groups and subgroups mirrored into Gitea on a schedule.
- Pain Point
- Projects that live on GitLab were out of reach for a tool that only spoke GitHub, and hand-made pull mirrors do not notice new projects.
- Outcome
- GitLab projects are discovered through the API, mirrored with branches, tags, wiki and LFS, and kept in sync like any GitHub repository.
Back Up Codeberg and Forgejo Repositories
Use a Gitea or Forgejo instance, Codeberg included, as the source (beta), and Forgejo as a named destination for the other direction.
- Pain Point
- Code on Codeberg or on a second Gitea had no place in a GitHub-only backup routine, and Forgejo had to pretend to be Gitea.
- Outcome
- Any Gitea or Forgejo host can be the source, Forgejo is a destination in its own right, and each row remembers where it was mirrored.
Mirror Repositories to GitHub or GitLab
Make GitHub or GitLab the destination (beta): the push engine keeps a bare clone and pushes branches and tags with force and prune on every sync.
- Pain Point
- GitHub has no pull mirror API and GitLab keeps its own behind a paid tier, so a copy on a hosted service meant scripts and cron.
- Outcome
- Repositories are created on the target, overwritten to match the source every sync, and archived or deleted by cleanup through the host API.
Automate Mirrors with the API
Create an API key, add a repository and start a mirror from a script or a CI job, and poll status without opening the dashboard.
- Pain Point
- New repositories waited for the next scheduled import, and pipelines had no way to ask the mirror to catch up.
- Outcome
- A key in the x-api-key header drives every endpoint the UI uses, with expiry and revocation from the settings page.
Adopt Existing Gitea Mirrors
Reconcile compares Gitea with the database, adopts mirrors made by hand or by an older tool, and resets rows whose mirror is gone.
- Pain Point
- A mirror without a database row is invisible to sync and cleanup, and a restored database lists repositories that are already there.
- Outcome
- A dry run sorts the destination into four groups, and the two opt-in fixes bring rows and mirrors back in line without deleting anything.
Control Release Asset Storage
Keep release notes for every mirrored release but upload binaries only for the newest few, globally or per organization and repository.
- Pain Point
- A project that ships builds for five platforms every fortnight turns a release mirror into gigabytes of installers nobody will run.
- Outcome
- Two independent limits decide how many releases exist on Gitea and how many of those carry assets, and nothing already uploaded is removed.
Have a niche workflow?
Fork the project, open an issue, or drop a PR. These guides are community-made—just like the tooling behind them.
Contribute on GitHub