Point every project URL at Forgejo, and say what mirrors where #1062

Merged
jaylouisw merged 1 commit from feat/forgejo-canonical into main 2026-11-08 14:07:05 +00:00
Owner

The project moved to Forgejo and the links did not follow: the README said to clone from
GitHub, the hardware-request button opened a GitHub issue form, SECURITY.md sent vulnerability
reports to a GitHub advisory page, package.json advertised a GitHub repository, and the generated
wiki linked to GitHub throughout. A stale URL fails no test, so all of it sat there looking fine
while sending contributors to a mirror.

What changed

  • scripts/canonical.js - the single definition of where the project lives, with the URL forms
    and the reasoned exceptions in one place. Change it there and the checker reports every file that
    has to follow.
  • scripts/check-canonical-urls.js - fails the build on drift, and runs in CI. It found three
    stale links plus two scripts still calling gh on its first run, all missed by a manual sweep.
  • scripts/forgejo-api.js - replaces the gh CLI in both triage scripts. gh is installed and
    authenticated on this workstation, so it would have answered about the GitHub mirror and reported
    a backlog nobody is working on. A missing token is now "cannot look" and exits 2, never 0.
  • Every doc link rewritten: clone, issues, source paths (/blob/ -> /src/branch/), wiki, badges,
    package.json repository/bugs/homepage, and the issue-template contact links.
  • docs/MIRRORING.md - what stays in sync and what cannot.

The sync question, answered

Syncable How
Commits, branches, tags Fully, one way Forgejo push mirror to GitHub
Pull requests No - bridge Bot mirrors refs/pull/<n>/head into Forgejo PRs, keyed on head SHA
Issues No - one tracker Forgejo is the tracker; double-tracking duplicates on every edit
CI/CD Forgejo only GitHub gets a courtesy subset at most

The rule: one writer, one reader. Forgejo writes, GitHub reads. Two-way mirroring races on every
force-push and neither platform can then be trusted about what the code is.

Two defects the guard found in itself

  • The pre-filter only looked for github.com, so a file whose only sin was a gh auth status
    instruction was skipped before the rule saw it.
  • It then flagged its own comment where I explained that rule.

And one in a script I wrote

scripts/cf-access-bypass.js called process.exit() while undici still held a socket open, which
trips a libuv assertion on Windows and reported exit 0 for a refused run - the same
silently-wrong-exit-code class it exists to prevent. Now it sets process.exitCode and lets Node
drain.

Test

test/canonical-urls.test.js - 34 assertions, including planting real drift in the working tree and
asserting the guard catches it, because this repo has already been bitten by an invariant that could
never fail.

102 suites, 4954 assertions, all passing.

Still blocked, and it is why this matters

git.jayw.uk sits behind Cloudflare Access, and a wildcard Access application covers
*.jayw.uk - even a nonsense hostname is redirected to the login page, which is why ha. and
plex. only work because they carry specific bypasses. So renewing the URLs does not yet help a
stranger: they still reach a login page, and GitHub remains the de-facto front door. One Access
policy (bypass for jaylouisw/packetforge*) fixes it, and scripts/cf-access-bypass.js is ready to
do it the moment a token with Access: Apps and Policies: Edit exists.

Closes #1061.

The project moved to Forgejo and the links did not follow: the README said to clone from GitHub, the hardware-request button opened a GitHub issue form, SECURITY.md sent vulnerability reports to a GitHub advisory page, package.json advertised a GitHub repository, and the generated wiki linked to GitHub throughout. A stale URL fails no test, so all of it sat there looking fine while sending contributors to a mirror. ## What changed - **`scripts/canonical.js`** - the single definition of where the project lives, with the URL forms and the reasoned exceptions in one place. Change it there and the checker reports every file that has to follow. - **`scripts/check-canonical-urls.js`** - fails the build on drift, and runs in CI. It found three stale links plus two scripts still calling `gh` on its first run, all missed by a manual sweep. - **`scripts/forgejo-api.js`** - replaces the `gh` CLI in both triage scripts. `gh` is installed and authenticated on this workstation, so it would have answered about the GitHub mirror and reported a backlog nobody is working on. A missing token is now "cannot look" and exits 2, never 0. - Every doc link rewritten: clone, issues, source paths (`/blob/` -> `/src/branch/`), wiki, badges, package.json repository/bugs/homepage, and the issue-template contact links. - **`docs/MIRRORING.md`** - what stays in sync and what cannot. ## The sync question, answered | | Syncable | How | |---|---|---| | Commits, branches, tags | Fully, **one way** | Forgejo push mirror to GitHub | | Pull requests | No - **bridge** | Bot mirrors `refs/pull/<n>/head` into Forgejo PRs, keyed on head SHA | | Issues | No - **one tracker** | Forgejo is the tracker; double-tracking duplicates on every edit | | CI/CD | Forgejo only | GitHub gets a courtesy subset at most | The rule: **one writer, one reader.** Forgejo writes, GitHub reads. Two-way mirroring races on every force-push and neither platform can then be trusted about what the code is. ## Two defects the guard found in itself - The pre-filter only looked for `github.com`, so a file whose only sin was a `gh auth status` instruction was skipped before the rule saw it. - It then flagged its own comment where I explained that rule. ## And one in a script I wrote `scripts/cf-access-bypass.js` called `process.exit()` while undici still held a socket open, which trips a libuv assertion on Windows and **reported exit 0 for a refused run** - the same silently-wrong-exit-code class it exists to prevent. Now it sets `process.exitCode` and lets Node drain. ## Test `test/canonical-urls.test.js` - 34 assertions, including planting real drift in the working tree and asserting the guard catches it, because this repo has already been bitten by an invariant that could never fail. **102 suites, 4954 assertions, all passing.** ## Still blocked, and it is why this matters `git.jayw.uk` sits behind Cloudflare Access, and a **wildcard** Access application covers `*.jayw.uk` - even a nonsense hostname is redirected to the login page, which is why `ha.` and `plex.` only work because they carry specific bypasses. So renewing the URLs does not yet help a stranger: they still reach a login page, and GitHub remains the de-facto front door. One Access policy (bypass for `jaylouisw/packetforge*`) fixes it, and `scripts/cf-access-bypass.js` is ready to do it the moment a token with `Access: Apps and Policies: Edit` exists. Closes #1061.
Point every project URL at Forgejo, and say what mirrors where
All checks were successful
CI / Test (Node 18) (pull_request) Successful in 1m29s
CI / Test (Node 20) (pull_request) Successful in 1m30s
CI / Server smoke test (pull_request) Successful in 28s
CI / Docker build (pull_request) Successful in 10s
CI / Test (Node 22) (pull_request) Successful in 1m33s
142451dde0
The project moved to Forgejo and the links did not follow. The README told people to clone from
GitHub, the hardware-request button opened a GitHub issue form, SECURITY.md sent vulnerability
reports to a GitHub advisory page, package.json advertised a GitHub repository, and the generated
wiki linked to GitHub throughout. None of those is where work happens, so the first instruction a
contributor followed took them somewhere else - and nothing failed when it happened, because a stale
URL looks like every other string in the repo.

Found while doing it: the GitHub repository is live, un-archived and current, with 30 open pull
requests and 988 open issues. Those PRs run CI there (the workflows are gated to run ON GitHub),
go green, and are invisible here. That is the cost of a move with no front door.

What changed:

- scripts/canonical.js is now the single definition of where the project lives, with the URL forms
  and the reasoned exceptions in one place. Change it there and the checker reports every file that
  has to follow.
- scripts/check-canonical-urls.js fails the build on drift, and runs in CI. It found three stale
  links plus two scripts still calling `gh` the first time it ran. It also asserts the README's
  clone URL and CI badge match the canonical base, because those are the two most-followed lines in
  the project.
- scripts/forgejo-api.js replaces the `gh` CLI in both triage scripts. `gh` either does not exist on
  Forgejo or - worse - is installed and authenticated and answers about the GitHub mirror, so triage
  silently reports a backlog nobody is working on. A missing token is now "cannot look" and exits 2,
  never "no open requests".
- Every doc link rewritten: clone, issues, source-file paths (/blob/ -> /src/branch/), wiki, badges,
  package.json repository/bugs/homepage, ISSUE_TEMPLATE contact links.

Two defects the tests caught in the guard itself: the pre-filter only looked for "github.com", so a
file whose only sin was `gh auth status` was skipped before the rule saw it; and the checker flagged
its own comment when I explained that rule.

docs/MIRRORING.md answers the sync question in full: git mirrors cleanly one way (Forgejo push
mirror to GitHub), pull requests cannot be mirrored and are bridged by head SHA, issues must not be
double-tracked, and CI is authoritative on Forgejo only. It also records the rule that keeps the two
from fighting - one writer, one reader - and the one thing that blocks all of it today: git.jayw.uk
is behind Cloudflare Access, so an anonymous visitor is redirected to a login page and cannot clone,
browse, or open an issue at all.

test/canonical-urls.test.js: 34 assertions, including planting real drift in the working tree and
asserting the guard catches it, since a guard nobody has seen fail might be checking nothing.

102 suites, 4954 assertions, all passing.
jaylouisw deleted branch feat/forgejo-canonical 2026-11-08 14:07:08 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1062
No description provided.