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>
107 lines
6.4 KiB
Markdown
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`.
|