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>
This commit is contained in:
commit
8af41526c5
5
.gitignore
vendored
Normal file
5
.gitignore
vendored
Normal file
@ -0,0 +1,5 @@
|
||||
node_modules/
|
||||
*.log
|
||||
.github-to-rithub-state.json
|
||||
*-state.json
|
||||
.env
|
||||
21
LICENSE
Normal file
21
LICENSE
Normal file
@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 Rithub
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
106
README.md
Normal file
106
README.md
Normal file
@ -0,0 +1,106 @@
|
||||
# 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`.
|
||||
169
bin/github-to-rithub.js
Normal file
169
bin/github-to-rithub.js
Normal file
@ -0,0 +1,169 @@
|
||||
#!/usr/bin/env node
|
||||
// github-to-rithub — mirror GitHub repos to Rithub (or any Gitea-API
|
||||
// compatible server) using your own tokens. Zero dependencies.
|
||||
// See README.md for full usage.
|
||||
|
||||
import { writeFile } from "node:fs/promises";
|
||||
import { listGithubRepos, getGithubRepo } from "../src/github.js";
|
||||
import { getRithubAuthedUser, rithubRepoIsFree, migrateRepo } from "../src/rithub.js";
|
||||
import { resolveStatePath, loadState, saveState, markCompleted, markFailed, isAlreadyDone } from "../src/state.js";
|
||||
import { buildReport, formatReportMarkdown } from "../src/report.js";
|
||||
|
||||
function parseArgs(argv) {
|
||||
const args = { _: [] };
|
||||
for (let i = 0; i < argv.length; i += 1) {
|
||||
const token = argv[i];
|
||||
if (token.startsWith("--")) {
|
||||
const key = token.slice(2);
|
||||
const next = argv[i + 1];
|
||||
if (next === undefined || next.startsWith("--")) {
|
||||
args[key] = true;
|
||||
} else if (key in args) {
|
||||
args[key] = [...(Array.isArray(args[key]) ? args[key] : [args[key]]), next];
|
||||
i += 1;
|
||||
} else {
|
||||
args[key] = next;
|
||||
i += 1;
|
||||
}
|
||||
} else {
|
||||
args._.push(token);
|
||||
}
|
||||
}
|
||||
return args;
|
||||
}
|
||||
|
||||
function requireEnv(name) {
|
||||
const value = process.env[name];
|
||||
if (!value) {
|
||||
console.error(`Missing required environment variable: ${name}`);
|
||||
process.exit(1);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function printUsage() {
|
||||
console.log(`github-to-rithub — move your repos from GitHub to Rithub
|
||||
|
||||
Usage:
|
||||
github-to-rithub list --github-user <user>
|
||||
github-to-rithub migrate --github-user <user> --rithub-owner <owner> [--repo <name> ...] [--all]
|
||||
[--rithub-url https://rithub.dev] [--dry-run] [--resume] [--state <path>]
|
||||
[--report <path.json>] [--report-md <path.md>]
|
||||
|
||||
Environment:
|
||||
GITHUB_TOKEN GitHub personal access token (read scope is enough: repo, read:org)
|
||||
RITHUB_TOKEN Rithub personal access token for the target account/org
|
||||
|
||||
Commands:
|
||||
list List the repos your GitHub token can see (no writes anywhere).
|
||||
migrate Migrate selected repos to Rithub via Rithub's own /repos/migrate API.
|
||||
`);
|
||||
}
|
||||
|
||||
async function cmdList(args) {
|
||||
const githubToken = requireEnv("GITHUB_TOKEN");
|
||||
const repos = await listGithubRepos(githubToken);
|
||||
for (const repo of repos) {
|
||||
console.log(`${repo.full_name}\t${repo.private ? "private" : "public"}\t${repo.html_url}`);
|
||||
}
|
||||
console.log(`\n${repos.length} repo(s) visible to this token.`);
|
||||
}
|
||||
|
||||
function selectRepos(allRepos, args) {
|
||||
if (args.all) return allRepos;
|
||||
const requested = Array.isArray(args.repo) ? args.repo : args.repo ? [args.repo] : [];
|
||||
if (requested.length === 0) {
|
||||
console.error("Pass --repo <name> one or more times, or --all. Refusing to migrate nothing/everything by accident.");
|
||||
process.exit(1);
|
||||
}
|
||||
return allRepos.filter((repo) => requested.includes(repo.name) || requested.includes(repo.full_name));
|
||||
}
|
||||
|
||||
async function migrateOne({ repo, args, githubToken, rithubToken, rithubUrl, rithubOwner, state }) {
|
||||
const fullName = repo.full_name;
|
||||
if (args.resume && isAlreadyDone(state, fullName)) {
|
||||
return { repo: fullName, status: "skipped-already-done" };
|
||||
}
|
||||
|
||||
const targetName = repo.name;
|
||||
const free = await rithubRepoIsFree(rithubUrl, rithubToken, rithubOwner, targetName);
|
||||
if (!free) {
|
||||
return { repo: fullName, status: "skipped-existing", rithubUrl: `${rithubUrl}/${rithubOwner}/${targetName}` };
|
||||
}
|
||||
|
||||
if (args["dry-run"]) {
|
||||
return { repo: fullName, status: "dry-run", rithubUrl: `${rithubUrl}/${rithubOwner}/${targetName} (not created)` };
|
||||
}
|
||||
|
||||
try {
|
||||
const detail = await getGithubRepo(repo.owner.login, repo.name, githubToken);
|
||||
await migrateRepo(rithubUrl, rithubToken, {
|
||||
cloneUrl: detail.clone_url,
|
||||
githubToken,
|
||||
repoOwner: rithubOwner,
|
||||
repoName: targetName,
|
||||
isPrivate: detail.private,
|
||||
description: detail.description,
|
||||
});
|
||||
return { repo: fullName, status: "migrated", rithubUrl: `${rithubUrl}/${rithubOwner}/${targetName}` };
|
||||
} catch (error) {
|
||||
return { repo: fullName, status: "failed", error: error instanceof Error ? error.message : String(error) };
|
||||
}
|
||||
}
|
||||
|
||||
async function cmdMigrate(args) {
|
||||
const githubToken = requireEnv("GITHUB_TOKEN");
|
||||
const rithubToken = requireEnv("RITHUB_TOKEN");
|
||||
const rithubUrl = String(args["rithub-url"] || "https://rithub.dev").replace(/\/$/, "");
|
||||
const rithubOwner = args["rithub-owner"];
|
||||
if (!rithubOwner) {
|
||||
console.error("Pass --rithub-owner <account or org on Rithub>");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const authedUser = await getRithubAuthedUser(rithubUrl, rithubToken);
|
||||
console.log(`Authenticated to ${rithubUrl} as ${authedUser.login}. Target namespace: ${rithubOwner}.`);
|
||||
|
||||
const githubUser = args["github-user"];
|
||||
const allRepos = await listGithubRepos(githubToken);
|
||||
const scoped = githubUser ? allRepos.filter((r) => r.owner.login === githubUser) : allRepos;
|
||||
const selected = selectRepos(scoped, args);
|
||||
|
||||
const statePath = resolveStatePath(args.state);
|
||||
let state = await loadState(statePath);
|
||||
|
||||
console.log(`\nMigrating ${selected.length} repo(s) from GitHub to ${rithubUrl}/${rithubOwner} ${args["dry-run"] ? "(DRY RUN)" : ""}`);
|
||||
|
||||
const startedAt = new Date().toISOString();
|
||||
const results = [];
|
||||
for (const repo of selected) {
|
||||
console.log(`-> ${repo.full_name}`);
|
||||
const result = await migrateOne({ repo, args, githubToken, rithubToken, rithubUrl, rithubOwner, state });
|
||||
results.push(result);
|
||||
console.log(` ${result.status}${result.rithubUrl ? " " + result.rithubUrl : ""}${result.error ? " " + result.error : ""}`);
|
||||
if (result.status === "migrated") state = markCompleted(state, repo.full_name, { rithubUrl: result.rithubUrl });
|
||||
if (result.status === "failed") state = markFailed(state, repo.full_name, result.error);
|
||||
if (!args["dry-run"]) await saveState(statePath, state);
|
||||
}
|
||||
const finishedAt = new Date().toISOString();
|
||||
|
||||
const report = buildReport({ startedAt, finishedAt, baseUrl: rithubUrl, rithubOwner, results });
|
||||
console.log(`\n${JSON.stringify(report.totals, null, 2)}`);
|
||||
|
||||
if (args.report) await writeFile(args.report, JSON.stringify(report, null, 2));
|
||||
if (args["report-md"]) await writeFile(args["report-md"], formatReportMarkdown(report));
|
||||
}
|
||||
|
||||
async function main() {
|
||||
const args = parseArgs(process.argv.slice(2));
|
||||
const command = args._[0];
|
||||
if (command === "list") return cmdList(args);
|
||||
if (command === "migrate") return cmdMigrate(args);
|
||||
printUsage();
|
||||
process.exit(command ? 1 : 0);
|
||||
}
|
||||
|
||||
main().catch((error) => {
|
||||
console.error(error instanceof Error ? error.message : error);
|
||||
process.exit(1);
|
||||
});
|
||||
36
docs/github-actions-to-rithub-ci.md
Normal file
36
docs/github-actions-to-rithub-ci.md
Normal file
@ -0,0 +1,36 @@
|
||||
# GitHub Actions → Rithub CI
|
||||
|
||||
Rithub runs Gitea under the hood, and Gitea Actions is deliberately built to be close to GitHub Actions syntax (it executes the same workflow YAML format via `act`-compatible runners). That means most simple workflows need small, mechanical changes, not a rewrite — but "close to" is not "identical", and you should verify this against your own runner, not take it on faith.
|
||||
|
||||
This CLI copies your `.github/workflows/*.yml` files over as part of the normal code migration (they're just files in the repo), but it does **not** rewrite them, enable Actions on the target repo, or register a runner for you. Those are separate, deliberate steps below.
|
||||
|
||||
## Step 1 — confirm Rithub Actions is actually enabled on your target server
|
||||
|
||||
Check with your Rithub admin (or, if you're self-hosting, your own `app.ini`) whether Actions is turned on, and whether a runner is registered and online. Without a registered runner, workflows will queue forever and silently never run — this is the single most common "CI doesn't work after migration" cause, and it has nothing to do with your YAML.
|
||||
|
||||
```bash
|
||||
curl -s -H "Authorization: token $RITHUB_TOKEN" \
|
||||
https://rithub.dev/api/v1/repos/<owner>/<repo>/actions/tasks
|
||||
```
|
||||
|
||||
## Step 2 — enable Actions on the migrated repo
|
||||
|
||||
Repo migration does not automatically flip on Actions for the new repo. In the repo's Settings on Rithub, enable "Actions" under Units/Features (or via the API: `PATCH /repos/{owner}/{repo}` with `"has_actions": true`, depending on your Rithub/Gitea version).
|
||||
|
||||
## Step 3 — move your workflow files
|
||||
|
||||
Your workflows already live at `.github/workflows/*.yml` after migration — Gitea Actions reads from the exact same path, so most of the time there's nothing to move.
|
||||
|
||||
## Step 4 — fix the real differences
|
||||
|
||||
These are the differences that actually bite in practice, not a hypothetical list:
|
||||
|
||||
- **`uses: actions/checkout@v4` and other hosted GitHub Marketplace actions.** Gitea Actions can run many of these unmodified if your runner has network access to github.com (it fetches the action's repo directly), but this depends on your runner's network policy. If your Rithub instance has outbound network restricted, mirror the specific actions you depend on into your own org and reference them by your own path instead.
|
||||
- **`secrets.GITHUB_TOKEN`.** Gitea Actions provides its own equivalent token scoped to the Gitea API, not GitHub's. Any step that calls `api.github.com` directly needs a real Rithub token in a new repo secret instead.
|
||||
- **GitHub-specific context values** (`github.event.pull_request.*` shapes can differ slightly, some newer GitHub context fields don't exist yet in a given Gitea version). Test the exact trigger you depend on (`push`, `pull_request`, `release`) rather than assuming parity.
|
||||
- **Marketplace actions that call GitHub-only APIs** (e.g., posting a GitHub Checks run, commenting via the GitHub API) will fail or silently no-op on Rithub — they're calling the wrong platform's API by design. Replace with the Gitea-API equivalent or drop the step.
|
||||
- **Runner labels** (`runs-on: ubuntu-latest`) only work if a runner registered on your Rithub instance actually advertises that label. Check what your runner offers; don't assume GitHub's hosted runner image.
|
||||
|
||||
## Step 5 — verify, don't assume
|
||||
|
||||
Push a trivial commit and watch the Actions tab on the migrated repo run end-to-end at least once before you rely on it. A workflow that "looks right" in the YAML but references an unreachable action or a runner label nobody registered will fail or hang silently.
|
||||
33
docs/github-suspended-account.md
Normal file
33
docs/github-suspended-account.md
Normal file
@ -0,0 +1,33 @@
|
||||
# My GitHub account got suspended — how do I get my code out?
|
||||
|
||||
This is the scenario this tool exists for. A real, documented risk of depending on any single platform: GitHub can suspend or restrict an account (ToS flags, automated abuse detection, a disputed DMCA claim, billing disputes) and your repos — including private ones — become inaccessible until it's resolved, which can take days to weeks, sometimes longer, with GitHub Support as your only channel.
|
||||
|
||||
## If your account is suspended right now
|
||||
|
||||
If you're already locked out, this tool can't help directly — it needs a working GitHub token, and a suspended account's tokens stop working too. Your real options, honestly:
|
||||
|
||||
1. **Open a GitHub Support ticket immediately** (support.github.com) — this is the only path back into a suspended account. There's no API workaround.
|
||||
2. **Check if a teammate/org co-owner still has access.** Organization repos survive an individual member's suspension; only the member's own access is cut. If you're in an org, a co-owner can export immediately.
|
||||
3. **Check for existing local clones.** If you or any collaborator has a local `git clone`, you have 100% of the git history (commits, branches, tags) already — you're only missing GitHub-native metadata (issues, PR discussion threads, releases' non-git parts). That's enough to keep working.
|
||||
4. **If you have an old personal access token that still works** (tokens occasionally outlive a fresh suspension for a short window, though this isn't guaranteed and shouldn't be relied on), run this tool immediately with it before it's revoked too.
|
||||
|
||||
## The real fix: don't wait until you're locked out
|
||||
|
||||
Run this tool *before* you need it, on a recurring basis, while your GitHub account is healthy:
|
||||
|
||||
```bash
|
||||
export GITHUB_TOKEN=ghp_xxx
|
||||
export RITHUB_TOKEN=xxxxxxxxxxxx
|
||||
github-to-rithub migrate --github-user your-username --rithub-owner your-rithub-username --all --resume
|
||||
```
|
||||
|
||||
Re-running the same command periodically (a weekly cron job, say) keeps a Rithub copy current for anything you've added or changed on GitHub — see `docs/keeping-a-github-mirror.md` for the lower-effort "mirror, don't migrate" version of this if you want to keep using GitHub day-to-day while insuring against exactly this scenario.
|
||||
|
||||
## What actually gets preserved vs. lost in a true worst-case (no token, no local clone, no co-owner)
|
||||
|
||||
Be honest with yourself about this before it happens:
|
||||
|
||||
- **Preserved by GitHub itself, independent of your account:** nothing automatically. GitHub does not email you a backup.
|
||||
- **Lost if your account and every collaborator's access and every local clone are all gone:** everything — there is no recovery path except GitHub Support reinstating the account.
|
||||
|
||||
This is exactly why the right time to run this tool is today, not after an incident.
|
||||
36
docs/keeping-a-github-mirror.md
Normal file
36
docs/keeping-a-github-mirror.md
Normal file
@ -0,0 +1,36 @@
|
||||
# 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).
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
## Option B — a real git mirror, kept current automatically (recommended for "insurance" use)
|
||||
|
||||
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.
|
||||
28
package.json
Normal file
28
package.json
Normal file
@ -0,0 +1,28 @@
|
||||
{
|
||||
"name": "github-to-rithub",
|
||||
"version": "0.1.0",
|
||||
"description": "Mirror GitHub repositories (code, branches, tags, issues, releases) to a Rithub (Gitea-API-compatible) server using your own tokens. Dry-run, resume and a clear report.",
|
||||
"license": "MIT",
|
||||
"type": "module",
|
||||
"bin": {
|
||||
"github-to-rithub": "bin/github-to-rithub.js"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=18"
|
||||
},
|
||||
"files": [
|
||||
"bin",
|
||||
"src",
|
||||
"README.md",
|
||||
"LICENSE"
|
||||
],
|
||||
"keywords": [
|
||||
"github",
|
||||
"gitea",
|
||||
"rithub",
|
||||
"migration",
|
||||
"mirror",
|
||||
"export",
|
||||
"backup"
|
||||
]
|
||||
}
|
||||
57
src/github.js
Normal file
57
src/github.js
Normal file
@ -0,0 +1,57 @@
|
||||
// Read-only GitHub REST API client. This tool never writes to GitHub —
|
||||
// it only lists/reads repos so it can hand their clone URL + your token
|
||||
// to Rithub's own migration endpoint.
|
||||
|
||||
const GITHUB_API = "https://api.github.com";
|
||||
|
||||
function githubHeaders(token) {
|
||||
const headers = {
|
||||
Accept: "application/vnd.github+json",
|
||||
"X-GitHub-Api-Version": "2022-11-28",
|
||||
"User-Agent": "github-to-rithub-cli",
|
||||
};
|
||||
if (token) headers.Authorization = `Bearer ${token}`;
|
||||
return headers;
|
||||
}
|
||||
|
||||
async function githubRequest(path, token) {
|
||||
const res = await fetch(`${GITHUB_API}${path}`, { headers: githubHeaders(token) });
|
||||
if (!res.ok) {
|
||||
const body = await res.text().catch(() => "");
|
||||
throw new Error(`GitHub API ${path} -> ${res.status} ${res.statusText}: ${body.slice(0, 300)}`);
|
||||
}
|
||||
return res.json();
|
||||
}
|
||||
|
||||
// Lists every repo the token's user owns (public + private), paginated.
|
||||
export async function listGithubRepos(token, { affiliation = "owner" } = {}) {
|
||||
const repos = [];
|
||||
let page = 1;
|
||||
for (;;) {
|
||||
const batch = await githubRequest(
|
||||
`/user/repos?per_page=100&page=${page}&affiliation=${affiliation}&sort=full_name`,
|
||||
token,
|
||||
);
|
||||
repos.push(...batch);
|
||||
if (batch.length < 100) break;
|
||||
page += 1;
|
||||
}
|
||||
return repos;
|
||||
}
|
||||
|
||||
export async function getGithubRepo(owner, repo, token) {
|
||||
return githubRequest(`/repos/${owner}/${repo}`, token);
|
||||
}
|
||||
|
||||
// Rough counts used only for the pre-flight report (not for the actual
|
||||
// migration — Rithub's own migrate endpoint re-fetches everything itself).
|
||||
export async function getGithubRepoCounts(owner, repo, token) {
|
||||
const [issues, releases] = await Promise.all([
|
||||
githubRequest(`/repos/${owner}/${repo}/issues?state=all&per_page=1`, token).catch(() => []),
|
||||
githubRequest(`/repos/${owner}/${repo}/releases?per_page=1`, token).catch(() => []),
|
||||
]);
|
||||
return {
|
||||
hasIssues: Array.isArray(issues) && issues.length > 0,
|
||||
hasReleases: Array.isArray(releases) && releases.length > 0,
|
||||
};
|
||||
}
|
||||
50
src/report.js
Normal file
50
src/report.js
Normal file
@ -0,0 +1,50 @@
|
||||
// Builds the human-readable + machine-readable migration report.
|
||||
|
||||
export function buildReport({ startedAt, finishedAt, baseUrl, rithubOwner, results }) {
|
||||
const succeeded = results.filter((r) => r.status === "migrated");
|
||||
const skippedExisting = results.filter((r) => r.status === "skipped-existing");
|
||||
const skippedDryRun = results.filter((r) => r.status === "dry-run");
|
||||
const skippedResume = results.filter((r) => r.status === "skipped-already-done");
|
||||
const failed = results.filter((r) => r.status === "failed");
|
||||
|
||||
return {
|
||||
startedAt,
|
||||
finishedAt,
|
||||
baseUrl,
|
||||
rithubOwner,
|
||||
totals: {
|
||||
requested: results.length,
|
||||
migrated: succeeded.length,
|
||||
skippedExisting: skippedExisting.length,
|
||||
skippedDryRun: skippedDryRun.length,
|
||||
skippedAlreadyDone: skippedResume.length,
|
||||
failed: failed.length,
|
||||
},
|
||||
results,
|
||||
};
|
||||
}
|
||||
|
||||
export function formatReportMarkdown(report) {
|
||||
const lines = [];
|
||||
lines.push(`# github-to-rithub migration report`);
|
||||
lines.push("");
|
||||
lines.push(`- Started: ${report.startedAt}`);
|
||||
lines.push(`- Finished: ${report.finishedAt}`);
|
||||
lines.push(`- Rithub server: ${report.baseUrl}`);
|
||||
lines.push(`- Target owner: ${report.rithubOwner}`);
|
||||
lines.push("");
|
||||
lines.push(
|
||||
`**Totals:** ${report.totals.migrated} migrated, ${report.totals.skippedExisting} already existed, ` +
|
||||
`${report.totals.skippedAlreadyDone} skipped (resume), ${report.totals.skippedDryRun} dry-run, ` +
|
||||
`${report.totals.failed} failed (out of ${report.totals.requested} requested).`,
|
||||
);
|
||||
lines.push("");
|
||||
lines.push(`| Repo | Status | Rithub URL / error |`);
|
||||
lines.push(`| --- | --- | --- |`);
|
||||
for (const r of report.results) {
|
||||
const detail = r.rithubUrl || r.error || "-";
|
||||
lines.push(`| ${r.repo} | ${r.status} | ${detail} |`);
|
||||
}
|
||||
lines.push("");
|
||||
return lines.join("\n");
|
||||
}
|
||||
81
src/rithub.js
Normal file
81
src/rithub.js
Normal file
@ -0,0 +1,81 @@
|
||||
// Rithub API client. Rithub runs Gitea's server under the hood, so it
|
||||
// exposes the same REST surface at /api/v1 — including Gitea's own
|
||||
// built-in repo-migration endpoint, which already knows how to pull
|
||||
// code + branches + tags + issues + labels + milestones + releases +
|
||||
// wiki from a GitHub repo in one call when given a GitHub token. This
|
||||
// module is a thin, typed wrapper around that real endpoint — it does
|
||||
// not reimplement git transfer or issue import itself.
|
||||
|
||||
function rithubHeaders(token) {
|
||||
return {
|
||||
Authorization: `token ${token}`,
|
||||
"Content-Type": "application/json",
|
||||
Accept: "application/json",
|
||||
};
|
||||
}
|
||||
|
||||
async function rithubRequest(baseUrl, token, method, path, body) {
|
||||
const res = await fetch(`${baseUrl}/api/v1${path}`, {
|
||||
method,
|
||||
headers: rithubHeaders(token),
|
||||
body: body ? JSON.stringify(body) : undefined,
|
||||
});
|
||||
const text = await res.text();
|
||||
const json = text ? JSON.parse(text) : null;
|
||||
return { ok: res.ok, status: res.status, json };
|
||||
}
|
||||
|
||||
// Resolves the authenticated Rithub user (used to confirm the token
|
||||
// before running anything destructive).
|
||||
export async function getRithubAuthedUser(baseUrl, token) {
|
||||
const { ok, status, json } = await rithubRequest(baseUrl, token, "GET", "/user");
|
||||
if (!ok) throw new Error(`Rithub auth check failed (${status}): ${JSON.stringify(json)}`);
|
||||
return json;
|
||||
}
|
||||
|
||||
// Returns true if `owner/repo` does not exist yet on Rithub.
|
||||
export async function rithubRepoIsFree(baseUrl, token, owner, repo) {
|
||||
const { status } = await rithubRequest(baseUrl, token, "GET", `/repos/${owner}/${repo}`);
|
||||
return status === 404;
|
||||
}
|
||||
|
||||
/**
|
||||
* Calls Rithub/Gitea's real `POST /repos/migrate` endpoint. `githubToken`
|
||||
* is the caller's own GitHub token, forwarded only in this one request
|
||||
* body so Gitea's migration worker can read the source repo — it is
|
||||
* never written to disk by this CLI.
|
||||
* @param {string} baseUrl
|
||||
* @param {string} rithubToken
|
||||
* @param {{cloneUrl: string, githubToken: string, repoOwner: string, repoName: string, isPrivate: boolean}} opts
|
||||
*/
|
||||
export async function migrateRepo(baseUrl, rithubToken, opts) {
|
||||
const body = {
|
||||
clone_addr: opts.cloneUrl,
|
||||
auth_token: opts.githubToken,
|
||||
service: "github",
|
||||
repo_owner: opts.repoOwner,
|
||||
repo_name: opts.repoName,
|
||||
mirror: false,
|
||||
private: opts.isPrivate,
|
||||
description: opts.description || "",
|
||||
issues: true,
|
||||
pull_requests: true,
|
||||
releases: true,
|
||||
labels: true,
|
||||
milestones: true,
|
||||
wiki: true,
|
||||
lfs: false,
|
||||
};
|
||||
const { ok, status, json } = await rithubRequest(baseUrl, rithubToken, "POST", "/repos/migrate", body);
|
||||
if (!ok) {
|
||||
const message = (json && (json.message || JSON.stringify(json))) || `HTTP ${status}`;
|
||||
throw new Error(`Rithub migrate failed for ${opts.repoOwner}/${opts.repoName}: ${message}`);
|
||||
}
|
||||
return json;
|
||||
}
|
||||
|
||||
export async function getRithubRepo(baseUrl, token, owner, repo) {
|
||||
const { ok, status, json } = await rithubRequest(baseUrl, token, "GET", `/repos/${owner}/${repo}`);
|
||||
if (!ok) throw new Error(`Rithub repo lookup failed (${status})`);
|
||||
return json;
|
||||
}
|
||||
46
src/state.js
Normal file
46
src/state.js
Normal file
@ -0,0 +1,46 @@
|
||||
// Resume support: a small JSON file next to the CLI invocation (or at a
|
||||
// path you pass with --state) that records which repos already migrated
|
||||
// successfully, so a re-run skips them instead of re-importing.
|
||||
|
||||
import { readFile, writeFile, mkdir } from "node:fs/promises";
|
||||
import { dirname } from "node:path";
|
||||
|
||||
const DEFAULT_STATE_PATH = ".github-to-rithub-state.json";
|
||||
|
||||
export function resolveStatePath(customPath) {
|
||||
return customPath || DEFAULT_STATE_PATH;
|
||||
}
|
||||
|
||||
export async function loadState(path) {
|
||||
try {
|
||||
const raw = await readFile(path, "utf8");
|
||||
return JSON.parse(raw);
|
||||
} catch (error) {
|
||||
if (error.code === "ENOENT") return { completed: {}, failed: {} };
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
export async function saveState(path, state) {
|
||||
await mkdir(dirname(path) === "." ? "." : dirname(path), { recursive: true });
|
||||
await writeFile(path, JSON.stringify(state, null, 2));
|
||||
}
|
||||
|
||||
export function markCompleted(state, repoFullName, result) {
|
||||
return {
|
||||
...state,
|
||||
completed: { ...state.completed, [repoFullName]: { at: new Date().toISOString(), ...result } },
|
||||
failed: Object.fromEntries(Object.entries(state.failed).filter(([key]) => key !== repoFullName)),
|
||||
};
|
||||
}
|
||||
|
||||
export function markFailed(state, repoFullName, errorMessage) {
|
||||
return {
|
||||
...state,
|
||||
failed: { ...state.failed, [repoFullName]: { at: new Date().toISOString(), error: errorMessage } },
|
||||
};
|
||||
}
|
||||
|
||||
export function isAlreadyDone(state, repoFullName) {
|
||||
return Boolean(state.completed[repoFullName]);
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user