github-to-rithub/docs/keeping-a-github-mirror.md
caelum0x 8af41526c5 feat: github-to-rithub CLI — mirror GitHub repos to Rithub with dry-run/resume/report
Zero-dependency Node CLI that lists a user's GitHub repos and migrates
selected ones to Rithub via Rithub's own (Gitea) /repos/migrate API,
carrying code, branches, tags, issues, labels, milestones, releases and
wiki. Adds dry-run, a resumable state file, and JSON/Markdown reports.
Includes 3 honest migration guides (suspended-account recovery, GitHub
Actions -> Rithub CI, keeping a GitHub mirror).

Real-tested 2026-11-17: migrated 3 live public GitHub repos
(basic-rag, defi-social-app, house-price-prediction) to a new
github-migration-test org on rithub.dev; verified branches/clone over
the live Rithub API; confirmed --resume skip and existing-repo
collision skip both work for real. Fixed a real bug found during
testing: repeated --repo flags were overwriting each other instead of
accumulating.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 18:23:16 +03:00

3.9 KiB

Keeping a GitHub mirror (don't fully leave, insure against the risk)

You don't have to choose between GitHub and Rithub on day one. A common, lower-risk path: make Rithub your primary remote (where you push, where issues/PRs live day-to-day) while keeping GitHub as a secondary, read-only mirror — or the reverse, keep GitHub primary and keep a current Rithub copy as insurance against the suspension scenario in docs/github-suspended-account.md.

This tool is built for one-time (or periodically re-run) migrations, not continuous two-way sync — be clear about that going in. Here's how to actually run it as a mirror in practice.

Option A — periodic one-way sync, Rithub as insurance (lowest effort)

Re-run this tool on a schedule. --resume means repos already migrated are skipped fast, so a repeat run only does meaningful work for repos it hasn't seen (new repos) — it does not pull new commits into an already-migrated repo (see the limitation below).

# cron, weekly
export GITHUB_TOKEN=ghp_xxx
export RITHUB_TOKEN=xxxxxxxxxxxx
github-to-rithub migrate --github-user your-username --rithub-owner your-rithub-username --all --resume

Real limitation, stated plainly: once a repo is migrated, this CLI's --resume skips it forever — it checks "does this name already exist on Rithub", not "is it up to date". For an already-migrated repo to pick up new commits, either delete it on Rithub and re-run without --resume (loses any Rithub-side issue activity if people have been using it there), or use Option B instead, which Gitea itself keeps in sync.

Gitea/Rithub supports pull mirrors natively — a scheduled server-side git fetch from the source, independent of this CLI. This is the right tool for "keep a current copy without me doing anything":

  1. Migrate once with this CLI to get issues/releases/wiki across (a mirror alone only syncs git data, not GitHub's issue/PR metadata). A repo created as a pull mirror from scratch (instead of via this CLI's migrate) can set the mirror URL and credentials at creation time on the repo-migrate form itself, with "This repository will be a mirror" checked.
  2. To adjust an existing repo's sync interval via the API, PATCH /repos/{owner}/{repo} with mirror_interval (a Go duration string like "8h0m0s"; Gitea's own default is 8 hours). There is no separate /mirror sub-endpoint for pull mirrors — it's a field on the repo itself.
  3. To trigger an immediate sync instead of waiting for the interval, call POST /repos/{owner}/{repo}/mirror-sync.

Now git history stays current automatically. Issues/PRs opened after the initial migration will not sync (GitHub's issue API and Gitea's mirror feature don't talk to each other) — re-run this CLI's issue import manually if you need a fresher snapshot of those.

Option C — Rithub primary, GitHub as the read-only mirror

If you're moving your team's daily workflow to Rithub but still want a GitHub presence (open-source visibility, contributors who only have GitHub accounts), set up a push mirror the other direction: Rithub repo → Settings → Mirror Settings → "Push Mirror" → add the GitHub clone URL with a GitHub token that has push access (API equivalent: POST /repos/{owner}/{repo}/push_mirrors). Gitea pushes to GitHub on the configured interval; GitHub becomes the copy, not the source of truth. Treat the GitHub side as read-only for anyone collaborating through Rithub — pushing directly to GitHub in this setup will get silently overwritten on the next mirror sync.

Honest bottom line

There is no fully free, zero-maintenance, bidirectional sync between two independent git hosts with two independent issue trackers — anyone claiming otherwise is oversimplifying. Pick the one-directional relationship that matches which platform is actually your source of truth, and treat the other as a mirror you understand the sync limits of.