Redirect to GitHub with a meta refresh

A browser extension redirects github.com to cgithub with declarative net
requests. Its rules match our HTTP redirects back to github.com too, so
those bounce straight back here and loop forever. A meta refresh makes
cgithub the initiator origin instead, which the extension's rules can
exclude, and its delay leaves a page the user can stop on.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 30 insertions, 0 deletions

diff --git a/README.md b/README.md
index 3bcf017..a625116 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,36 @@ $ pnpm run deploy
 
 The worker name and other settings live in `wrangler.jsonc`.
 
+## Browser extension redirects
+
+Pages cgithub can't render (marketing pages, code search, anything unrouted) are
+redirected back to github.com. A browser extension that rewrites github.com URLs
+to a cgithub instance with `declarativeNetRequest` will match those redirects
+too and send the request straight back, looping forever.
+
+To avoid this, cgithub never answers with an HTTP redirect: it serves a small
+page that navigates to github.com with a two-second `<meta http-equiv="refresh">`.
+Because that navigation is initiated by the cgithub origin, the extension can
+let it through with `excludedInitiatorDomains`; without that, the user at least
+lands on a page they can stop on, with a link, instead of an endless loop.
+
+A rule that redirects to a cgithub instance should therefore look like this:
+
+```jsonc
+{
+  "action": {
+    "type": "redirect",
+    "redirect": { "transform": { "host": "cgithub.example" } },
+  },
+  "condition": {
+    "urlFilter": "||github.com",
+    "resourceTypes": ["main_frame"],
+    // So cgithub's own meta refresh to github.com isn't redirected back here.
+    "excludedInitiatorDomains": ["cgithub.example"],
+  },
+}
+```
+
 ## Disclosures
 
 AI coding assistants, in particular Claude, are used in the development process.