---
layout: ../../layouts/UseCaseLayout.astro
title: "Sync GitHub to Your Self-Hosted Gitea"
description: "Keep a homelab Gitea instance continuously updated with GitHub by using Gitea Mirror's discovery, scheduling, and metadata sync."
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.

## Requirements

- Gitea Mirror deployed (Docker, Proxmox LXC, or Helm)
- GitHub PAT with `repo` enabled (add the `read:org` checkbox under `admin:org` to mirror organizations; leave write/admin unchecked)
- Gitea API token for the target account/org
- Stable connectivity between the mirror host and both GitHub + Gitea

## Step-by-step

### 1. Connect accounts in the admin wizard

1. Sign in at `http://<mirror-host>:4321`.
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. Import the repository inventory

- 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

- 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.

<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

In **Configuration → Connections → Content & Data**:

- 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.
- 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

- Select a repository in the dashboard and use the **Sync Repository** action.
- 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 & health checks

- 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, 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.