docs: describe Rithub on its own terms across README, docs and CLI
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
8af41526c5
commit
4f2842a38b
14
README.md
14
README.md
@ -2,16 +2,16 @@
|
||||
|
||||
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.
|
||||
This is a small, zero-dependency CLI. It does not reinvent git transfer or issue import: Rithub 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.
|
||||
- **Code, branches, tags** — mirrored via a real `git` clone done server-side by Rithub. 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 Rithub'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 Rithub when reachable; very large assets can occasionally fail — 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 importer 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.
|
||||
@ -78,7 +78,7 @@ If the run is interrupted (network drop, rate limit, Ctrl-C), re-run the exact s
|
||||
| --- | --- |
|
||||
| `--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 |
|
||||
| `--rithub-url <url>` | Rithub server base URL (default `https://rithub.dev`) — point this at any Rithub-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 |
|
||||
@ -99,7 +99,7 @@ This tool migrated 3 real small public repos (`basic-rag`, `defi-social-app`, `h
|
||||
|
||||
## 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.
|
||||
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 (its 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
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
#!/usr/bin/env node
|
||||
// github-to-rithub — mirror GitHub repos to Rithub (or any Gitea-API
|
||||
// github-to-rithub — mirror GitHub repos to Rithub (or any Rithub-API
|
||||
// compatible server) using your own tokens. Zero dependencies.
|
||||
// See README.md for full usage.
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# 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.
|
||||
Rithub 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.
|
||||
|
||||
@ -15,20 +15,20 @@ curl -s -H "Authorization: token $RITHUB_TOKEN" \
|
||||
|
||||
## 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).
|
||||
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 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.
|
||||
Your workflows already live at `.github/workflows/*.yml` after migration — Rithub 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.
|
||||
- **`uses: actions/checkout@v4` and other hosted GitHub Marketplace actions.** Rithub 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`.** Rithub Actions provides its own equivalent token scoped to the Rithub 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 Rithub 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 Rithub-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
|
||||
|
||||
@ -15,21 +15,21 @@ 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.
|
||||
**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 Rithub 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":
|
||||
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.
|
||||
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"`; Rithub's 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.
|
||||
Now git history stays current automatically. Issues/PRs opened after the initial migration will not sync (GitHub's issue API and Rithub'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.
|
||||
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`). Rithub 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
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
{
|
||||
"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.",
|
||||
"description": "Mirror GitHub repositories (code, branches, tags, issues, releases) to a Rithub server using your own tokens. Dry-run, resume and a clear report.",
|
||||
"license": "MIT",
|
||||
"type": "module",
|
||||
"bin": {
|
||||
@ -18,7 +18,6 @@
|
||||
],
|
||||
"keywords": [
|
||||
"github",
|
||||
"gitea",
|
||||
"rithub",
|
||||
"migration",
|
||||
"mirror",
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
// 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
|
||||
// Rithub API client. Rithub exposes its REST surface at /api/v1 —
|
||||
// including its 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
|
||||
@ -40,9 +40,9 @@ export async function rithubRepoIsFree(baseUrl, token, owner, repo) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Calls Rithub/Gitea's real `POST /repos/migrate` endpoint. `githubToken`
|
||||
* Calls Rithub'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
|
||||
* body so Rithub's migration worker can read the source repo — it is
|
||||
* never written to disk by this CLI.
|
||||
* @param {string} baseUrl
|
||||
* @param {string} rithubToken
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user