# github-to-rithub Move your repos off GitHub onto [Rithub](https://rithub.dev) — 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](https://about.gitea.com/) 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): ```bash 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: ```bash npm link github-to-rithub --help ``` ## Setup ```bash 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): ```bash 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: ```bash 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: ```bash 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 `) and skips every repo already migrated. ### Flags | Flag | Meaning | | --- | --- | | `--github-user ` | Scope the repo list to this GitHub account (default: everything your token can see) | | `--rithub-owner ` | Required. The Rithub user or org namespace repos land in | | `--rithub-url ` | Rithub server base URL (default `https://rithub.dev`) — point this at any Gitea-API-compatible server | | `--repo ` | 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 ` | State file path (default `.github-to-rithub-state.json`) | | `--report ` | Write a machine-readable JSON report | | `--report-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 - [`docs/github-suspended-account.md`](docs/github-suspended-account.md) — what to do if your GitHub account gets suspended and you need your code out, fast. - [`docs/github-actions-to-rithub-ci.md`](docs/github-actions-to-rithub-ci.md) — converting GitHub Actions workflows to Rithub's Actions-compatible CI. - [`docs/keeping-a-github-mirror.md`](docs/keeping-a-github-mirror.md) — running Rithub as your primary remote while keeping a read-only GitHub mirror, instead of a one-time migration. ## 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`.