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

107 lines
6.4 KiB
Markdown

# 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 <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
- [`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`.