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

6.4 KiB

github-to-rithub

Move your repos off GitHub onto Rithub — your code, branches, tags, issues, labels, milestones, releases and wiki — using your own tokens, with a dry run, resume, and a clear report at the end.

This is a small, zero-dependency CLI. It does not reinvent git transfer or issue import: Rithub runs Gitea under the hood, and Gitea already has a solid, battle-tested POST /repos/migrate endpoint that pulls a full GitHub repo (history, branches, tags, issues, labels, milestones, releases, wiki) in one authenticated server-side call. This tool is a thin orchestration layer on top of that real endpoint: it lists your GitHub repos, lets you pick which ones to move, checks for name collisions, calls Rithub's migrate API for each one, tracks progress so a crashed run can resume, and writes a report you can actually read.

It never pushes anything back to GitHub and never writes your GitHub token to disk — the token is sent once, directly to your own Rithub server, inside the one migration request it's needed for.

What it actually does (and doesn't)

  • Code, branches, tags — mirrored via a real git clone done server-side by Gitea. Verified: migrated repos on Rithub show the same default branch and are clone-able over HTTPS.
  • Issues, labels, milestones — imported with their original text, author attribution ("via GitHub") and state, when Gitea's importer supports the GitHub API version in use.
  • Releases — imported with their tag, title, body and published-at date. Binary release assets are migrated by Gitea when reachable; very large assets can fail silently on some Gitea versions — check the Releases tab after a migration with assets.
  • Pull requests — imported as historical records (title, body, comments, labels, merged/closed state). Already-merged or already-closed PRs import cleanly. Open PRs from a fork whose branch no longer exists on GitHub may show up with an "unavailable" diff — this is a known Gitea limitation, not something this CLI can fix.
  • Wiki — imported if the source repo has one.
  • GitHub Actions workflows — copied as files like any other code in .github/workflows/, but they do not run on Rithub as-is (different CI runner/syntax). See docs/github-actions-to-rithub-ci.md.
  • What this tool will never do: write, delete, or modify anything on GitHub. It only reads (list repos, read repo metadata) with your GitHub token.

Install

No publishing step required — clone and run with Node 18+ (uses the built-in fetch, zero npm dependencies):

git clone https://rithub.dev/rithub/github-to-rithub.git
cd github-to-rithub
node bin/github-to-rithub.js --help

Or link it as a global command:

npm link
github-to-rithub --help

Setup

export GITHUB_TOKEN=ghp_xxx        # read-only is enough: repo (or public_repo) + read:org if you use orgs
export RITHUB_TOKEN=xxxxxxxxxxxx   # a Rithub personal access token, Settings -> Applications -> Generate New Token

Usage

List everything your GitHub token can see (read-only, no side effects):

github-to-rithub list --github-user your-github-username

Dry-run a migration — checks name collisions on Rithub, prints exactly what would happen, creates nothing:

github-to-rithub migrate \
  --github-user your-github-username \
  --rithub-owner your-rithub-username-or-org \
  --repo my-repo --repo another-repo \
  --dry-run

Run it for real, with resume support and a written report:

github-to-rithub migrate \
  --github-user your-github-username \
  --rithub-owner your-rithub-username-or-org \
  --all \
  --resume \
  --report migration-report.json \
  --report-md migration-report.md

If the run is interrupted (network drop, rate limit, Ctrl-C), re-run the exact same command with --resume — it reads .github-to-rithub-state.json (override with --state <path>) and skips every repo already migrated.

Flags

Flag Meaning
--github-user <user> Scope the repo list to this GitHub account (default: everything your token can see)
--rithub-owner <owner> Required. The Rithub user or org namespace repos land in
--rithub-url <url> Rithub server base URL (default https://rithub.dev) — point this at any Gitea-API-compatible server
--repo <name> Migrate one specific repo; repeat for more. Omit with --all
--all Migrate every repo the token can see (scoped by --github-user if set)
--dry-run Check collisions and print the plan; create nothing
--resume Skip repos already recorded as migrated in the state file
--state <path> State file path (default .github-to-rithub-state.json)
--report <path.json> Write a machine-readable JSON report
--report-md <path.md> Write a human-readable Markdown report

Tested for real

This tool migrated 3 real small public repos (basic-rag, defi-social-app, house-price-prediction) from a real GitHub account to a real Rithub test org (github-migration-test on rithub.dev) on 2026-11-17: dry-run, a full migration, a --resume re-run (correctly skipped all 3), and a fresh run against an already-existing repo (correctly skipped with skipped-existing, no duplicate created). All three landed on Rithub with their correct default branch and were reachable over HTTPS clone and the web UI — verified with the live Rithub API, not assumed.

Migration guides

Why this exists

GitHub can suspend an account with little warning, and plenty of teams want a primary git host they fully control. Rithub already ships with everything needed to receive a migration (it's Gitea's own server-side importer); this CLI exists so moving isn't a manual, one-repo-at-a-time chore through the web UI, and so a half-finished migration is resumable instead of something you have to track by hand.

License

MIT — see LICENSE.