Mirror/gitea-mirror
1
0
Fork 0
mirror of https://github.com/RayLabsHQ/gitea-mirror.git synced 2025-12-06 11:36:44 +03:00
Code Issues Packages Projects Releases Wiki Activity

updated www articles

Browse Source
This commit is contained in:
Arunavo Ray
2025-10-22 23:47:26 +05:30
parent 5e37c3bb84
commit 3c808eb0c0
7 changed files with 240 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
www/src/layouts/UseCaseLayout.astro
View File

@@ -29,7 +29,7 @@ const {
<body class="min-h-screen bg-background text-foreground antialiased">
<Header client:load />
<main class="pt-24 pb-20">
<article class="use-case-content mx-auto max-w-3xl px-4 sm:px-6 lg:px-8">
<article class="use-case-content mx-auto max-w-4xl px-4 sm:px-6 lg:px-8">
<slot />
</article>
</main>

40
www/src/pages/use-cases/backup-github-repositories.mdx
View File

@@ -5,6 +5,8 @@ description: "Run a homelab-friendly playbook to mirror GitHub into self-hosted
canonical: "https://gitea-mirror.com/use-cases/backup-github-repositories/"
---
# Backup GitHub Repositories with Gitea Mirror
## Why homelabbers care
GitHub is great—right up until an outage, SSO change, or account lockout strands your projects. Gitea Mirror keeps a self-hosted copy of everything (history, metadata, LFS) so you can keep working locally. This playbook walks through the minimal Docker setup the project ships with and shows how to prove your backups actually work.
@@ -57,13 +59,25 @@ On the dashboard:
For broader coverage, switch the organization strategy to **Preserve structure** so Gitea mirrors your GitHub org layout automatically.
### 4. Schedule a recurring sync window
### 4. Turn on automatic syncs and cleanup
Under **Settings → Mirror Options**:
Open **Configuration → Automation** in the web UI.
- Set the global interval (for example 30 minutes) to keep backups fresh.
- If you only need nightly backups, add a schedule window such as `02:00-02:30`.
- Enable **Auto-discovery** so new repositories are picked up whenever they appear.
- Enable **Automatic syncing** and pick an interval that matches how fresh you want the mirror (start with `60 minutes`, shorten for active repos).
- Leave the scheduler enabled—auto-discovery ships with it, so new GitHub repositories and stars are pulled in on the next pass.
- If you want the mirror to tidy up when GitHub repos disappear, enable **Handle orphaned repositories** and keep the action on **Archive** so history stays intact.
<figure class="mt-8 flex flex-col items-center">
<img
src="/assets/configuration.png"
alt="Automation tab in Gitea Mirror showing the automatic syncing controls for GitHub backups."
class="w-full max-w-5xl rounded-xl border border-muted shadow-sm"
loading="lazy"
/>
<figcaption class="mt-3 text-sm text-muted-foreground text-center">
Configure the scheduler and cleanup policies from the Automation tab so GitHub mirrors stay fresh without manual cron jobs.
</figcaption>
</figure>
### 5. Prove the backup works
@@ -78,7 +92,7 @@ Treat the mirror like any other DR asset:
- The container exposes `/api/health`; add it to Uptime Kuma, Healthchecks.io, or Prometheus.
- Mirror failures surface in the activity log; consider exporting them through the `/api/events` endpoint.
- Disk usage lives under `Settings → Storage`; make sure the host volume has headroom for LFS blobs.
- Watch the `data/` volume on the host (e.g. `du -sh data/`) to make sure you have headroom for mirrored repos and LFS blobs.
## Hardening tips
@@ -90,3 +104,17 @@ Treat the mirror like any other DR asset:
- Promote the mirror to read-only users who do not need GitHub access.
- Layer on the [Helm](../deploy-with-helm-chart) or [Proxmox LXC](../proxmox-lxc-homelab) playbooks when you outgrow the single-node setup.
## FAQ
### Does Gitea Mirror copy issues, pull requests, releases, and LFS?
Yes. Enable Mirror metadata, Mirror releases, and LFS under Repository defaults. Pull requests are mirrored as enriched issues with linked branches and metadata.
### How often should I sync GitHub backups?
Most homelabs pick 30–120 minutes. Faster schedules improve RPO but use more GitHub API quota; adjust by org/repo if only a few projects are critical.
### Where are backups stored and how do I restore?
Repositories and the SQLite DB live under the `data/` directory (or your configured volume). Restore by cloning from Gitea or by moving the volume to a fresh deployment and signing back in.

86
www/src/pages/use-cases/github-backup-automation.mdx
View File

@@ -1,67 +1,93 @@
---
layout: ../../layouts/UseCaseLayout.astro
title: "Automate GitHub Backups"
description: "Replace fragile cron scripts with scheduled mirrors, health checks, and alerts that keep GitHub backups trustworthy."
description: "Replace fragile cron scripts with scheduled mirrors, health checks, and logging that keep GitHub backups trustworthy."
canonical: "https://gitea-mirror.com/use-cases/github-backup-automation/"
---
# Automate GitHub Backups
## Why automation beats cron
Shell scripts and `git clone --mirror` jobs work until they don’t—usually when GitHub rotates tokens, repositories rename, or metadata gets missed. Gitea Mirror centralizes scheduling, retries, and monitoring so your backups keep running while you sleep.
Shell scripts and `git clone --mirror` jobs work until they don’t—usually when GitHub rotates tokens, repositories rename, or metadata gets missed. Gitea Mirror bundles scheduling, auto-discovery, and repository cleanup so your backups keep running while you sleep.
## Requirements
- Gitea Mirror deployment with outbound HTTPS access
- GitHub PAT + Gitea token stored in the UI or environment
- Healthcheck endpoint (Healthchecks.io, Cronitor, Uptime Kuma) for alerts
- Optional: Mailer or webhook destinations for failure notifications
- GitHub PAT + Gitea token stored in the UI or supplied via environment variables
- A monitoring target that can poll HTTP endpoints (Healthchecks.io, Uptime Kuma, Prometheus, etc.)
## Step-by-step
### 1. Configure schedules centrally
### 1. Enable automatic syncing
1. Visit **Settings → Mirror Options**.
2. Set the global interval (e.g. `30 minutes`).
3. Use **Schedule windows** to run heavy syncs overnight (e.g. `02:00-05:00`).
4. Override intervals per org/repo when you need faster protection for a critical project.
1. Go to **Configuration → Automation**.
2. Toggle **Automatic syncing** on and choose an interval that matches your recovery point objective (start with `30 minutes` for active teams, stretch to `12 hours` for archives).
3. Confirm the scheduler is running by checking the **Last sync** and **Next sync** timestamps in the Automation card.
### 2. Turn on smart retries
### 2. Keep the repository list current
- Under **Advanced**, enable **Backoff retries** so failed syncs retry with exponential delay.
- Toggle **Stale sync alerts** to get warned when a repo hasn’t synced in your target window.
- Set the failure threshold (for example, alert after 3 consecutive failures).
- In **Configuration → Connections**, click **Import GitHub Data** so the dashboard knows about every repository, organization, and star you selected.
- Enable **Mirror starred repositories** if you want personal favorites backed up, and set the **Starred repos organization** for tidy storage in Gitea.
- Use the inline destination editor on the **Repositories** page when you need a repo to land in a different Gitea organization.
### 3. Wire in health monitoring
### 3. Configure repository cleanup (optional)
- Add a Healthchecks.io ping to the **Outgoing webhooks** field with `/api/health`.
- If you self-host Uptime Kuma, create an HTTP check against `http://<mirror-host>:4321/api/health`.
- Subscribe an email or webhook channel under **Notifications** for failure summaries.
- Still on **Configuration → Automation**, enable **Handle orphaned repositories automatically**.
- Leave the action on **Archive** to keep a read-only backup when a GitHub repo disappears, or switch to **Delete** if you require a strict mirror.
- Disable **Dry run** after your first test so the cleanup service can act on what it finds.
### 4. Manage credentials safely
### 4. Monitor scheduler health
- Store tokens in the built-in secret storage rather than `.env` files on disk.
- Turn on **Token expiry reminders** (set e.g. 30 days before the expiry) to rotate proactively.
- Use GitHub fine-grained PATs per org to minimize blast radius.
- Point your monitoring system at `http://<mirror-host>:4321/api/health` to track uptime.
- Review sync failures from the **Activity Log** page or export them via `/api/events` for long-term retention.
- Run `bun run manage-db check` during maintenance windows to verify background tasks, migrations, and queue state.
### 5. Document recovery steps
<figure class="mt-8 flex flex-col items-center">
<img
src="/assets/activity.png"
alt="Gitea Mirror activity log displaying recent GitHub backup jobs and their status."
class="w-full max-w-5xl rounded-xl border border-muted shadow-sm"
loading="lazy"
/>
<figcaption class="mt-3 text-sm text-muted-foreground text-center">
The Activity Log highlights successful syncs and failures so you can react before GitHub backups fall behind.
</figcaption>
</figure>
- Save the `docker compose`/Helm/Proxmox commands you used in your homelab wiki.
- Export the mirror configuration JSON (`/api/export`) monthly so you can rehydrate quickly.
- Note which repos are excluded and why; auditors will ask.
### 5. Harden credentials and runbooks
- Store GitHub and Gitea tokens via the Configuration UI—Gitea Mirror encrypts them at rest.
- Rotate tokens on a schedule and note expiry dates in your homelab runbook; the dashboard surfaces failures when credentials expire.
- Export the configuration JSON (`/api/export`) alongside your documentation so you can rebuild the mirror quickly if you need to redeploy.
## Validate automation
- Force a failure by revoking a PAT, confirm alerts fire, then restore the token.
- Force a failure by temporarily revoking a PAT; the next scheduler run should flag the repository in the Activity Log. Restore the token and trigger **Sync now** to confirm recovery.
- Run `bun run manage-db check` (or the UI health check) to ensure migrations and tasks are clean.
- Diff the last sync times via the dashboard CSV export.
- Export the repositories table or CSV download to confirm `Last mirrored` timestamps match your configured interval.
## Best practices
- Group repos by criticality so you can assign tighter schedules where it matters.
- Keep the mirror in the same timezone as your documentation to simplify scheduling.
- Tune the sync interval to balance freshness with GitHub rate limits; most homelabs sit between 30 and 120 minutes.
- Start with the cleanup action set to **Archive** until you are confident you will not remove something you still need.
- Pair automation with the [Preserve GitHub History](../preserve-github-history/) playbook to maintain context, not just code.
## Related playbooks
- [Backup GitHub Repositories](../backup-github-repositories/)
- [Run Gitea Mirror inside a Proxmox LXC](../proxmox-lxc-homelab/)
## FAQ
### What replaces my cron scripts?
The built-in scheduler handles intervals, retries, and discovery. It also powers cleanup for deleted upstream repos (Archive/Delete) once enabled.
### How do I get alerts if backups fail?
Monitor `/api/health` with Healthchecks.io or Uptime Kuma and review the Activity Log. You can export failures via `/api/events` for centralized logging.
### Will new repositories be discovered automatically?
Yes. After importing your GitHub data once, the scheduler’s discovery step keeps the inventory updated and mirrors new repositories on the next run.

54
www/src/pages/use-cases/preserve-github-history.mdx
View File

@@ -5,6 +5,8 @@ description: "Archive commits, issues, releases, and LFS assets into Gitea so ho
canonical: "https://gitea-mirror.com/use-cases/preserve-github-history/"
---
# Preserve GitHub History Forever
## Keep the entire story, not just the code
GitHub accounts get banned, repos go private, and owners rage-delete history. If you care about the full timeline—issues, releases, wiki—Gitea Mirror snapshots everything on a schedule so the story survives in your homelab.
@@ -20,29 +22,41 @@ GitHub accounts get banned, repos go private, and owners rage-delete history. If
### 1. Set archival-friendly defaults
In the admin UI under **Settings → Mirror Options**:
In **Configuration → Connections**, open **Repository defaults**:
- Enable **Mirror metadata**.
- Enable **Mirror releases** and **Mirror wiki**.
- Turn on **Include attachments** so release assets and issue uploads copy across.
- Enable **Mirror metadata** and choose the components you care about (issues, pull requests, labels, milestones, wiki).
- Enable **Mirror releases** and raise the **Latest releases** limit if you need a deeper history of release assets.
- Toggle **Git LFS (Large File Storage)** so binaries follow the repository, assuming LFS is enabled in your Gitea instance.
### 2. Create an "Archive" organization in Gitea
1. In Gitea, create an org like `github-archive` with read-only members.
2. Back in Gitea Mirror, edit each owner and set the destination to the archive org.
3. Enable **Lock mirrors** so accidental edits on the archive side are blocked.
1. In Gitea, create an org like `github-archive` and grant read-only access to everyone who needs the history.
2. Back in Gitea Mirror under **Configuration → Connections**, pick the **Preserve structure** strategy (or set a destination organization) so repos land in that archive org.
3. Tighten permissions in Gitea—disable pushes for regular users so the archive stays immutable while the service updates it via its token.
<figure class="mt-8 flex flex-col items-center">
<img
src="/assets/repositories.png"
alt="Repositories dashboard in Gitea Mirror showing archived GitHub projects synced into Gitea."
class="w-full max-w-5xl rounded-xl border border-muted shadow-sm"
loading="lazy"
/>
<figcaption class="mt-3 text-sm text-muted-foreground text-center">
Keep every GitHub project visible in the repositories dashboard while routing mirrors into a dedicated archive organization.
</figcaption>
</figure>
### 3. Choose retention & cadence
- Set the global interval to `1h` for active projects or `12h` for dormant ones.
- Configure **Snapshot retention** (for example `keep last 30`) so old mirror runs remain inspectable.
- Schedule a weekly full sync window during off-hours to re-check metadata drift.
- In **Configuration → Automation**, enable **Automatic syncing** and set the interval (`1h` keeps fast-moving repos current; `12h` is usually enough for archives).
- Turn on **Handle orphaned repositories automatically** and leave the action on **Archive** so anything deleted upstream is preserved locally but marked read-only.
- Bump the **Latest releases** limit or run an occasional manual **Sync now** for milestone projects to capture older release assets.
### 4. Record provenance
- Tag each archived repo in Gitea with the upstream URL and the first mirrored date.
- Enable **Mirror webhooks** to push sync summaries into Matrix/Discord for auditing.
- Export a CSV of repos quarterly as part of your homelab documentation.
- Add a README or label inside the archive organization that captures the upstream URL, first mirrored date, and token owner.
- Export a CSV from the **Repositories** view or hit `/api/events` quarterly so you retain a human-friendly change log.
- Store the configuration export (`/api/export`) alongside your disaster-recovery docs in case you need to rebuild the service.
### 5. Back up the backup
@@ -67,3 +81,17 @@ In the admin UI under **Settings → Mirror Options**:
- [Automate GitHub Backups](../github-backup-automation/)
- [Build a Starred Repo Collection](../starred-repos-collection/)
## FAQ
### Does this preserve issues, pull requests, and releases?
Yes—enable Mirror metadata and Mirror releases in Repository defaults. Pull requests copy as enriched issues, keeping discussion and labels.
### What happens if a GitHub repo is deleted or goes private?
Turn on Handle orphaned repositories automatically and use Archive to keep a read-only copy locally. Delete enforces a strict mirror, removing the repo.
### How much storage will I need long-term?
Plan for repo size plus attachments and LFS. Monitor the mirror’s `data/` volume growth and consider ZFS/BTRFS snapshots or object storage for older archives.

30
www/src/pages/use-cases/proxmox-lxc-homelab.mdx
View File

@@ -5,6 +5,8 @@ description: "Provision the community-maintained Proxmox VE LXC container for Gi
canonical: "https://gitea-mirror.com/use-cases/proxmox-lxc-homelab/"
---
# Run Gitea Mirror inside a Proxmox LXC
## Why run it on Proxmox
When most of your homelab lives in Proxmox VE, the community LXC script is the fastest path from zero to a managed Gitea Mirror node. It handles Bun, systemd, persistent storage, and future upgrades so you can focus on keeping Git backups fresh.
@@ -71,10 +73,36 @@ You should see `gitea-mirror.db` and a `repos/` directory. Data lives under `/op
2. Stop GitHub access temporarily and clone from the Gitea mirror to confirm the backup works.
3. Restore the snapshot on a different node to ensure the service boots cleanly with the preserved data volume.
<figure class="mt-8 flex flex-col items-center">
<img
src="/assets/dashboard_mobile.png"
alt="Mobile view of the Gitea Mirror dashboard running inside a Proxmox LXC container."
class="w-full max-w-sm rounded-xl border border-muted shadow-sm"
loading="lazy"
/>
<figcaption class="mt-3 text-sm text-muted-foreground text-center">
Even inside a lightweight LXC container, the dashboard stays responsive for quick health checks on the go.
</figcaption>
</figure>
## Troubleshooting
- **Port 4321 already used**: change `PORT` in `/opt/gitea-mirror.env` and restart with `systemctl restart gitea-mirror`.
- **Disk full**: extend the container disk in Proxmox, then run `pct resize <CTID> rootfs +5G`.
- **Token expired**: log in to the UI → Settings to update GitHub/Gitea credentials.
- **Token expired**: log in to the UI → Configuration to update GitHub/Gitea credentials.
Looking for a cluster-native deployment? Try the [Helm playbook](../deploy-with-helm-chart).
## FAQ
### What container size should I start with?
The script defaults to 2 vCPU, 2 GiB RAM, 6 GiB disk. Bump RAM for large orgs or many concurrent mirrors; you can resize disk later with `pct resize`.
### How do I upgrade the LXC deployment?
Re-run the community installer. It detects existing installs, backs up `/opt/gitea-mirror/data`, downloads the latest release, and restarts the service.
### How should I back up and restore?
Snapshot the container or back up `/opt/gitea-mirror/data`. Restore by attaching the volume to a fresh container and starting the service; your configuration is preserved.

46
www/src/pages/use-cases/starred-repos-collection.mdx
View File

@@ -5,6 +5,8 @@ description: "Mirror your starred GitHub projects into a dedicated Gitea library
canonical: "https://gitea-mirror.com/use-cases/starred-repos-collection/"
---
# Build a Starred Repo Collection
## Curate without losing projects
Stars are a personal library—but they vanish when creators delete repos or your account is rate limited. Gitea Mirror can automatically capture every starred repository into a dedicated Gitea organization, complete with issues and releases, so your inspiration lives on.
@@ -20,21 +22,33 @@ Stars are a personal library—but they vanish when creators delete repos or you
### 1. Enable starred owner tracking
1. In the onboarding wizard (or later under **Settings → Owners**), add your GitHub username.
2. Enable the **Include starred repositories** toggle.
3. Set the destination in Gitea to a dedicated org, e.g. `stars-jamie`.
1. In the onboarding wizard—or later under **Configuration → Connections**—add your GitHub username as an owner.
2. Enable **Mirror starred repositories** and set the **Starred repos organization** to a dedicated space such as `stars-jamie`.
3. Use the starred content selector to choose whether you want full metadata (issues, releases, PRs, wiki) or the lightweight code-only mode.
### 2. Categorize the collection
- Create sub-organizations in Gitea (e.g. `stars-iot`, `stars-ai`).
- Use Destination Overrides inside the dashboard to route specific stars into themed orgs.
- Use the inline destination editor on the **Repositories** page to route specific stars into themed orgs.
- Tag repos in Gitea with labels like `language:rust`, `topic:homelab` for quick filtering.
### 3. Schedule incremental updates
<figure class="mt-8 flex flex-col items-center">
<img
src="/assets/organisation.png"
alt="Organization view in Gitea Mirror highlighting starred GitHub repositories grouped in a dedicated Gitea org."
class="w-full max-w-5xl rounded-xl border border-muted shadow-sm"
loading="lazy"
/>
<figcaption class="mt-3 text-sm text-muted-foreground text-center">
Group starred GitHub repositories into curated Gitea organizations for easier browsing and long-term preservation.
</figcaption>
</figure>
- Set the star discovery interval to something light like `1h` so new stars import quickly.
- Use the **Starred sync window** (e.g. `00:00-00:30`) to avoid interfering with org backups.
- Turn on **Starred repo cleanup** if you want unstarred projects removed from the library.
### 3. Keep the collection fresh
- Enable **Automatic syncing** in **Configuration → Automation** and pick an interval around `1h` so new stars appear quickly.
- Leave the scheduler running—auto-discovery pulls in new stars on each pass without additional configuration.
- If you want unstarred projects archived or removed, enable **Handle orphaned repositories automatically** and choose **Archive** (recommended) or **Delete** for strict mirroring.
### 4. Showcase the library
@@ -47,7 +61,7 @@ Stars are a personal library—but they vanish when creators delete repos or you
1. Star a new repo on GitHub.
2. Wait for the star interval or click **Sync now** in the dashboard.
3. Confirm the repo appears in your `stars` org with issues/releases intact.
4. Unstar it on GitHub; if cleanup is enabled, confirm it disappears on the next sync.
4. Unstar it on GitHub; if cleanup is set to **Archive**, verify the mirror is renamed with an `archived-` prefix and marked read-only. If you chose **Delete**, confirm it disappears on the next sync.
## Nice-to-haves
@@ -59,3 +73,17 @@ Stars are a personal library—but they vanish when creators delete repos or you
- [Backup GitHub Repositories](../backup-github-repositories/)
- [Automate GitHub Backups](../github-backup-automation/)
## FAQ
### Can I mirror only the code or include metadata?
Yes. Use the starred content selector to choose code-only or include issues, releases, pull requests, and wikis.
### What happens when I unstar a repository?
Enable Handle orphaned repositories automatically and choose Archive (recommended) to preserve history read-only, or Delete for a strict mirror.
### Can others browse my collection safely?
Create a read-only Gitea user or org members with no write permissions, then share the organization URL behind HTTPS.

58
www/src/pages/use-cases/sync-github-to-self-hosted-gitea.mdx
View File

@@ -5,6 +5,8 @@ description: "Keep a homelab Gitea instance continuously updated with GitHub by
canonical: "https://gitea-mirror.com/use-cases/sync-github-to-self-hosted-gitea/"
---
# Sync GitHub to Your Self-Hosted Gitea
## Keep SaaS and self-hosted in lockstep
You may still collaborate on GitHub every day, yet want a LAN Gitea copy you control. Gitea Mirror bridges the two: it tracks owners, auto-discovers repos, mirrors metadata, and keeps a local instance only minutes behind upstream without hand-written cron jobs.
@@ -21,31 +23,41 @@ You may still collaborate on GitHub every day, yet want a LAN Gitea copy you con
### 1. Connect accounts in the admin wizard
1. Sign in at `http://<mirror-host>:4321`.
2. Open **Settings → Connections**.
2. Open **Configuration → Connections**.
3. Paste the GitHub PAT and choose the owners (user + orgs) you want mirrored.
4. Add your self-hosted Gitea URL and token; pick the destination org structure (typically **Preserve structure**).
### 2. Enable continuous discovery
### 2. Import the repository inventory
- Go to **Settings → Mirror Options** and toggle **Auto-discovery**.
- Set the discovery interval (for example `15 minutes`) so new repositories, forks, and transfers sync automatically.
- Optionally add a "Starred" owner to pull in personal favorites alongside org repos.
- In **Configuration → Connections**, click **Import GitHub Data** to pull in every repository, organization, and star you've selected.
- Enable **Mirror starred repositories** if you want personal favorites mirrored alongside org projects, and set a dedicated starred organization in Gitea.
- Auto-discovery runs whenever the scheduler is enabled, so new GitHub repositories will appear automatically after you turn on automatic syncing.
### 3. Configure sync cadence
Decide how far behind GitHub the mirror can lag:
- Head to **Configuration → Automation** and enable **Automatic syncing**.
- Pick an interval that matches your recovery point objective; `15–30 minutes` keeps an active GitHub org nearly live, while `2–4 hours` is fine for quieter repos.
- Leave the scheduler running so auto-discovery and repository cleanup keep working in the background.
- Global interval: start with `15 minutes` for active projects.
- Use **Custom intervals** on specific orgs/repositories if you need faster mirrors (as low as 5 minutes).
- Set a quiet window (e.g. `01:00-05:00`) for heavy metadata pulls to avoid daytime throttling.
<figure class="mt-8 flex flex-col items-center">
<img
src="/assets/dashboard.png"
alt="Gitea Mirror dashboard showing overall sync status for GitHub organizations and repositories."
class="w-full max-w-5xl rounded-xl border border-muted shadow-sm"
loading="lazy"
/>
<figcaption class="mt-3 text-sm text-muted-foreground text-center">
Monitor GitHub-to-Gitea sync health from the dashboard while the scheduler keeps repositories aligned automatically.
</figcaption>
</figure>
### 4. Mirror metadata and LFS
Under **Repository defaults**:
- Enable **Mirror metadata** so issues, labels, and milestones stay in sync.
- Enable **Mirror metadata** so issues, pull requests (as enriched issues), labels, milestones, and wikis stay in sync.
- Enable **Mirror LFS** if your repos store binaries; confirm your Gitea instance has LFS enabled.
- Turn on **Delete missing** only if you want Gitea to remove repos when they disappear upstream.
- If you want deleted GitHub repos archived or removed locally, enable **Handle orphaned repositories automatically** in the Automation tab and choose the action (Archive or Delete) that matches your retention policy.
### 5. Validate the local mirror
@@ -53,19 +65,33 @@ Under **Repository defaults**:
- In Gitea, verify commit history, tags, issues, and releases match GitHub.
- Run a quick diff: `git remote add gitea http://<gitea>/<owner>/<repo>.git && git fetch gitea` then `git log origin/main..gitea/main` — it should be empty.
## Monitoring & alerts
## Monitoring & health checks
- Check the **Activity** page for failed runs; set up Healthchecks.io/webhooks on the `/api/health` endpoint.
- Enable email notifications so administrators learn about repeated failures or token expiry.
- Export `/api/repos/:id/logs` periodically to archive sync history alongside the repos themselves.
- Watch the **Activity Log** for failed runs and retry jobs; filter by repository when you need to chase a single mirror.
- Point Healthchecks.io, Uptime Kuma, or Prometheus at `http://<mirror-host>:4321/api/health` to confirm the service stays responsive.
- Export `/api/repos/:id/logs` or the global `/api/events` endpoint periodically to archive sync history alongside the repositories themselves.
## Tips for smooth syncing
- Avoid running more than one mirror against the same Gitea target; let Gitea Mirror manage the schedule centrally.
- When restructuring orgs, pause auto-discovery, move repos in Gitea, then resume to prevent thrash.
- When restructuring orgs, temporarily disable automatic syncing, move repos in Gitea, then re-enable the scheduler to avoid churn.
- Rate limits cropping up? Move the mirror onto a different IP or configure GitHub fine-grained PATs per org.
## Related playbooks
- [Backup GitHub Repositories](../backup-github-repositories/) for the base Docker deployment
- [Run Gitea Mirror inside a Proxmox LXC](../proxmox-lxc-homelab/) if you want the mirror on a dedicated appliance
## FAQ
### How quickly can the mirror catch up to GitHub?
Intervals of 15–30 minutes keep most orgs near real-time. You can shorten for critical repos, but watch GitHub API rate limits.
### Can I mirror multiple GitHub users and organizations?
Yes. Add each owner in Configuration → Connections, then choose a destination strategy (Preserve structure or a specific org) for Gitea.
### Is it safe to store tokens in Gitea Mirror?
Tokens saved via the Configuration UI are encrypted at rest. Rotate them regularly and monitor dashboard alerts for expirations.