Control app: design
This text is LLM generated.
Status: proposal, revised 2026-09-25 after an independent fact-check.
Configured-session chat uses the existing ACP drawer through the service bridge.
The pinned attach contract documented in service/README.md has no since-cursor
replay contract; the bridge forwards ACP frames unchanged and stores no replay.
The UI therefore never silently reconnects: close/error shows “Session ended”
and explains that a new conversation needs the session server restarted.
The listener admits one client and session/new returns its existing session;
there is no fresh-conversation control or retry of a consumed destination.
Prior text remains visibly ended, separated by provider even when another
attachment fails; it is not evidence of recovered agent context. An unsent draft
must be cleared or copied before changing providers.
Tracks cgwalters-bot/cgwalters-bot#8 and builds on the review-workflow part of the pivot plan (gist). Each Decision is a recommendation for cgwalters to accept or overrule. The questions for him are at the end.
Revision: the board is the backend (2026-09-25)
cgwalters decided against a new items repository: "the app can be public
but yes we may have some private repos so we don't want to leak that. I
think the backend could again be a project/issues/gist". So, for now,
this replaces §1 (the items repository, its format, review-items, the
board mirror and the migration). Auth, hosting, CSP, rendering and deploys
(§2, §3) stand as written; the GitHub app comes first, Forgejo later.
- No data in the app. The code is public. Everything about items is fetched at runtime with your token, so nothing private reaches the source, the build, logs or a public store. Test fixtures are synthetic.
- The queue is the Workstream board: items with Status "Needs human", grouped by Priority, with Why, Org, Branch and Gist, plus the item's issue or PR and any gist for long context.
- Reads are REST, not GraphQL.
GET /orgs/{o}/projectsV2/{n}/itemstakesfields=<ids>andq=status:"Needs human", sendsaccess-control-allow-origin: *and ETags (checked 2026-09-25). Polls are conditional requests, so an unchanged board costs no rate budget.
Answers, and why the bot can trust them (revised 2026-09-26)
The bot's existing rule is that only the cgwalters login carries intent.
Answers must therefore be something only that login can create. A comment
is the simplest option: GitHub records its author.
The first version answered board draft items, which have no comments and
whose edits are unattributed (DraftIssue and ProjectV2Item expose only
a creator and updatedAt, with no edit history). So the app wrote the
answer into the draft's public body and saved an unlisted gist under his
account as a receipt for the bot to verify, with Q#n question ids and
timing rules to reject replayed or stale answers. cgwalters found that
weird, and it was: all of it existed only because drafts can't carry
authorship. It is gone. Instead:
-
Every board item that isn't an upstream issue or PR is an issue in the public repository
cgwalters-forge/tracker. The bot no longer creates draft items (except archivedbot-state:ones, which the app never shows). Larger efforts are parent issues there with sub-issues. -
A question for him is a tracker issue labelled
question, assigned to him, with board Status "Needs human". When the item it blocks is a tracker issue, the question is a sub-issue of it. Its body:Blocks: https://github.com/cgwalters-forge/tracker/issues/12 Context, any number of lines. Q: Which prefix? Options: A) org.example B) io.example Recommended: A, because it is already registeredThe first line always names the blocked board item (a tracker issue, or an upstream issue or PR, which can't have sub-issues). An upstream URL is written in backticks,
Blocks: `https://github.com/o/r/pull/7`: a bare URL in a public issue adds a "mentioned this" entry to the upstream timeline, a code span doesn't. Options and the recommendation may be absent (an action, or an open question); when there is a recommendation, it is always option A.Options:andRecommended:count only after theQ:line and outside fenced code blocks, and each option is exactly one line, lettered from A, at least two; if a list doesn't follow that format, the app reports it rather than guessing at a wrapped option. -
He answers with a normal comment on it, and his login is what authenticates it. If he picks an option, the comment's first line is exactly that letter, optionally followed by his own text; otherwise it is only his text. There is no command, question id, receipt or timing rule: a question issue asks one thing, and a new question is a new issue. The bot acts, then closes the issue with a one-line comment saying what it did.
- The app never copies option text from the bot into the comment, so a confused bot can't put words under his name.
- It refuses free text with a line that is a bot command (
/promote,/draft,/ready, after trimming whitespace):bot-practs on/promoteon any line of his comments, so "ok" followed by a/promoteline in an answer would promote a fork PR. Backticks or other wording get around it on purpose. It also refuses free text whose first line is a single letter, because it would be read as a pick.
-
Only open question issues in the tracker, opened by the bot and assigned to him, get an answer box (reviews and chores are below).
postAnswerreads the issue fresh and refuses anything else before writing, and also a picked letter that the question's body no longer offers. Upstream issues and PRs are never answered from the app, not even with a confirmation: a bare "B" on an upstream PR is noise to its maintainers. A Needs-human upstream item shows its Why and a link to act on GitHub, and its decisions live in tracker questions whoseBlocks:line names it. -
The queue follows the issues. A question he commented on after the bot's last comment shows as answered and moves to the end until the bot acts; one the bot closed shows as done. A question is nested under the entry for the item it blocks (its parent issue, else its
Blocks:URL) when that item is in the queue, including a forge PR entry that folded in the item's Draft board item. A parent ranks and groups by its most urgent open question when that outranks it, keeping its own priority on its pill. Parents show theirsub_issues_summaryprogress, and opening one lists its sub-issues (GET /repos/{o}/{r}/issues/{n}/sub_issues, read only for tracker issues whose summary is non-zero). Deciding "answered" reads a question's comments, conditionally, only when the board changed, and after the queue is on screen, at most FETCH_CONCURRENCY at a time.
What the bot checks (in homegit, not in this repository): the comment
is by cgwalters and was not edited by anyone else (people with write
access can edit others' comments, so check userContentEdits editors, as
bot-pr does for PR bodies), on an open question issue in the tracker
that is assigned to him.
Reviews and chores: every Needs human item has an ask (2026-09-26)
cgwalters opened an upstream Needs human item (bootc-dev/bootc#2256)
and the app said "Nothing to answer here": its Why held two asks, to
re-approve a PR at a new head and to rerun two CI legs that lost their
runner, and neither was a question. So every Needs human item now gets
a tracker issue per ask, of one of three kinds, told apart by exactly one
label: question (as above), review or chore. Each is an open issue
in the tracker, opened by the bot, assigned to him, with the same
Blocks: first line and sub-issue rule. He finishes any of them with a
comment on it; only his login counts, and the bot then acts and closes
it.
- A review has
Ask: <one line>and, per PR,Review: `https://github.com/OWNER/REPO/pull/N` at <40-hex head>. The app opens that PR in its review pane, including an upstream PR he is asked to approve. The pane offers a review form for any PR an open review ask names, besides the bot's own forge PRs. Any other PR without an ask still gets no review form, so a crafted link can't turn the page into a one-click approval. The pane shows the head the bot asked about and warns when the PR has moved since: a review is always of the head shown, and when that isn't the one asked about he must confirm reviewing the new head first, in its own question. On a PR the form is there only because of the ask, the ask is read fresh before anything is sent (still an open review ask of the bot's, assigned to him, naming this PR at the head shown), not trusted from the board snapshot. After an approval or change request, the app comments on the review ask (Approved `OWNER/REPO#N` at `<sha>`: `<review URL>`) so the bot sees it; the PR and URL are in code spans, since bare in a public issue they would put a "mentioned this" entry on the upstream PR. A plain comment review settles nothing and posts nothing. If a review POST loses its response, returns a server error, or returns unreadable JSON, its outcome is unknown: check GitHub before trying again. The error lists earlier confirmed reviews separately; only a definite rejection says the failed review was not sent. - A chore has
Ask: <one line>and zero or moreRerun: `https://github.com/OWNER/REPO/actions/runs/ID`lines. With reruns, the app lists each run's failed jobs (GET .../actions/runs/{id}and.../jobs?filter=latest) with a "Rerun failed jobs" button. That writes upstream with his token, so it is strict: the URL must parse exactly as a run (not a job or an attempt), the chore is read fresh and must still name exactly that URL (anyRerun:line it can't read disables them all), the run is read fresh and must be that run in that repository, completed, failed (failure, cancelled, timed out or a startup failure) with failed jobs in its latest attempt; he confirms, and only then the app callsPOST .../actions/runs/{id}/rerun-failed-jobs, built from the parsed URL's parts, and comments "Reran the failed jobs of <run URL>".cancelledcounts as failed: jobs that lost their runner end up in that state. The confirmation names the commit the run is on, and warns when that is older than the current head of the PR the chore blocks. One rerun per run is in flight at a time, even across re-renders. A 4xx answer means nothing happened; a network or server error after sending may not, so the app says it may or may not have gone out and offers no blind retry. - Any other chore, or a review or rerun the app can't read, shows its Ask text and a comment box, with the same refusal of bot command lines as an answer (the letter-first-line rule is only for questions).
- No Needs human item says "nothing to do". An upstream or tracker
Needs human item shows its open asks (nested by parent or
Blocks:) as actions. One with none is a bot bug, flagged as such in the queue and the item view ("the bot left this without an ask"), with its Why and links.
Auth changes
The relay and the cgwalters-review App stay as in §3; v0 ships the
client side (see "Hosting v0" below). With answers as issue comments,
the App doesn't need Gists permission; Contents write is not needed until PR
review (v2).
Resolved (2026-09-30): the board was owned by the cgwalters-bot
user, and GitHub Apps have no account-level Projects permission
(discussion),
so it moved to the cgwalters-forge org
(cgwalters-forge/tracker#144), where an App with Projects write can
update it. App user tokens
reach only repositories where the App is installed, including the tracker
and the forge; upstream repositories don't need write access now that
answers never go there.
Plan, revised: v0 is the GitHub queue, the item view and answers, as
above, in development mode. Next come the relay, the bot's answer check
in homegit, and the App (created by you, with its secret installed by you
on forge). PR review (§6 v2) and Forgejo follow.
Direction (2026-09-26)
cgwalters' stated goal, recorded as direction rather than a committed design; a separate design pass will follow:
- The app should feel more like the github.com interface: a queue, news, and an agent chat. The queue and a news pane (recently merged changes to the bot, its runner and this app, with harness changes marked) exist now; chat does not.
- The long-term target is that the coordinator itself runs from a
scheduled GitHub Actions workflow, and he can type into the UI and get
an interactive session with it, driven over ACP (the Agent Client
Protocol; the proposed
bot-harness, in cgwalters-forge/cgwalters-devspace-sandbox#4, is an ACP client).
Hosting v0: GitHub Pages and a pasted token (2026-09-26)
cgwalters asked for something usable now rather than after the relay and
the tailnet host, so v0 is published on GitHub Pages
(https://cgwalters-forge.github.io/review/) by a workflow on every
merge to main, and you sign in by pasting a personal access token. This
replaces the relay client and the loopback-only development mode above;
the tailnet host, the cgwalters-review App and the relay (§3) remain
the target, and would replace only src/github/auth.ts.
Since 2026-11-12 (tracker#1456, review#320) this is the serverless default:
the Pages app needs no service. It reads the pass's publications and the
Actions run lists from GitHub, and acts through GitHub as the operator:
writes, workflow_dispatch, and job plans that the hosted pass dispatches.
The supported sign-in is a pasted fine-grained token, read-only unless an
action needs more. The OAuth device flow stays off: its endpoints send no
CORS headers (§2), so a static page can't use it without a relay.
- The token stays in the browser: sessionStorage by default, or
localStorage if you tick "remember". It is sent only to
api.github.com: the client refuses any other URL, and the CSP'sconnect-srcallows no other origin. The page names the scopes it needs, and warns when a classic token lacks one. - Nothing is baked in. The site is the code only. Everything shown is read with your token, so it shows nothing your token can't read, and private repositories appear only if it reaches them.
- CSP is a meta tag, since Pages sends no headers:
connect-src https://api.github.com,script-src 'self', no inline script or eval, Trusted Types. A meta tag can't carryframe-ancestors, so the app refuses to run in a frame. There are no third-party scripts: markdown-it and DOMPurify are bundled.
What this gives up, compared with §3:
- The bot deploys. "Deploy only commits you approved" doesn't hold: cgwalters let the bot merge and deploy this repository without his review, and a merged change could read a pasted token. Use a token that expires soon, and only the scopes listed.
- A shared origin. Every Pages site of the cgwalters-forge
organization is served from
cgwalters-forge.github.io, and they can read each other's storage: the token, and the response cache below, which holds whatever the token read, private repositories included. No other site exists there; don't add one while tokens or the cache live here. A custom domain would give the app an origin of its own. - A long-lived credential in the browser, rather than the relay's short-lived access tokens.
Persistent cache (2026-09-26)
Every GitHub read is a conditional GET, and the board alone is about 1.1 MB in two pages that take GitHub 3 to 4 seconds to answer, 304 or not. So the app keeps its responses across reloads and renders from them first (stale-while-revalidate):
- One cache (
src/github/cache.ts): a map in memory in front of an IndexedDB store (idbstore.ts). IndexedDB rather than localStorage: the board alone would crowd localStorage's 5 MB, and bodies are stored as parsed values with no JSON string round trip. Each entry keeps its URL, ETag or Last-Modified, the parsed body and when GitHub last sent or confirmed it; metadata and bodies are separate stores, so a 304 rewrites a few fields, not the megabyte. - On load, the queue (the board, the forge's PRs, their verdicts and
which questions are answered, under whatever filter is chosen, since
filters only narrow the entries), a PR's details, the news and the ops
view are rendered from the cache by the same loaders over a cache-only client,
and marked "cached · N min ago" until GitHub has answered. Then every
entry is revalidated with
If-None-MatchorIf-Modified-Since; a 304 only refreshes its time. The first render already carries its labels, and the fresh answer replaces it in place: the queue with the same rows, a PR only if it differs. (The board is REST with ETags, so it revalidates like everything else; only the forge's search has no validators and is always re-read.) A finished workflow run's jobs never change. If every job in the cached run attempt has completed, the ops view uses that copy without revalidating it, even if it comes from an earlier session. This depends on the copy's content, not on comparing the browser's clock with GitHub's. - Writes invalidate. A successful write drops every cached response
under the issue or PR it wrote to (its
/issues/Nand/pulls/Ntrees) and all searches, before and after it is sent, and a read that was in flight during it isn't stored. The approve and answer guards read the PR or issue withsend, which never reads or fills the cache, so an approval is always checked against the head on GitHub. - Bounds: about 50 MB, least recently used first. The cap counts characters of JSON, so the space used on disk is only roughly that, and it is enforced when an entry is written and when the app loads. Entries GitHub hasn't confirmed for 7 days are deleted when the app loads, and never served in between.
- Whose cache. Entries are keyed by the signed-in login, and the
store records that login and a SHA-256 hash of the token it was last
used with, never the token. A reload with the same token renders at
once; a different token waits for
GET /user, keeps the cache if the login is the same (a rotated token) and wipes it otherwise. Signing out deletes the database, and so does GitHub rejecting the token with a 401 from any read or write, whether at load or mid-session (if a token is revoked or expires while the tab is open). The app then stops and asks for a new token. Another tab of the app releases the database when that happens. - Only with "remember". A remembered token is on disk anyway, so its cache may be too. Without "remember" the token lasts as long as the tab, and so does the cache: it stays in memory, and each such load deletes any database an earlier remembered sign-in left. That gives up the fast reload for tokens that aren't remembered, in exchange for leaving nothing behind after the tab closes, as the sign-in page promises. Keeping a session's cache in IndexedDB and deleting it on the next load would have left private data on disk until then, possibly forever.
- Without storage (blocked site data, some private modes, a full disk) every store operation fails quietly and the cache is memory only, as it was before.
Summary
- Static site?
- Forgejo: yes. Its OAuth2 provider accepts public clients with PKCE, and
its token endpoint honours the instance's
[cors]settings. - GitHub: everything except the OAuth code exchange. That still requires
the client secret, and
github.com/login/*has no CORS; GitHub's single-page-app work is Paused. So GitHub needs a small stateless relay. - Both are served tailnet-only from
forgewithtailscale serve.
- Forgejo: yes. Its OAuth2 provider accepts public clients with PKCE, and
its token endpoint honours the instance's
- Auth.
- GitHub: a dedicated GitHub App,
cgwalters-review, used only through user-to-server tokens. They expire after 8 hours, are limited to where the app is installed, and are attributed to you. The relay is a token-mediating backend (RFC 10017 §6.2) that keeps the refresh token in a sealed HttpOnly cookie. - Forgejo: an OAuth2 application with scoped grants.
- The bot's own app,
cgwaltersbot, is never involved.
- GitHub: a dedicated GitHub App,
- Shape.
- A shared item-format library, plus two thin client-side apps, one for GitHub and one for Forgejo. Both are strict TypeScript.
- The relay and the bot's
review-itemsCLI are Rust. - The served code is deployed only from commits you approved, and the bot can't touch what's served.
- Sign-off.
- GitHub: API only. New commits reuse each original tree, followed by a compare-and-swap ref update.
- Forgejo: no commit-creation API. The browser uses isomorphic-git with a pre-push head check, or the relay does the rewrite server-side.
- Prior art. Nothing does this already. We borrow ideas from Gerrit NoteDb, Backlog.md, Sveltia CMS and ReviewStack.
1. Source of truth
Replaced by the revision at the top: the Workstream board and tracker issues are the backend. The earlier proposal, an items repository of markdown files mirrored to the board, is in git history.
2. Static-site feasibility
| GitHub | Forgejo (your instance) | |
|---|---|---|
| REST API from a browser | Yes. api.github.com sends access-control-allow-origin: * and exposes ETag and the rate-limit headers (curl, 2026-09-25) |
Yes, with [cors] ENABLED=true (cors.go; /api always allows Authorization, per routers/api/shared/middleware.go) |
| PKCE | S256 only, since 2025-07-14 | S256 and plain, required for public clients (AuthorizeOAuth in routers/web/auth/oauth.go) |
| Code exchange without the secret | No. client_secret is required even with PKCE (docs); GitHub "does not distinguish between public and confidential clients" |
Yes for apps not marked confidential (the secret is checked only for ConfidentialClient) |
| CORS on the token endpoint | No. Preflight and POST to /login/oauth/access_token and /login/device/code return no Access-Control-* (curl). In #15752, staff said CORS on the token endpoint is not supported yet. roadmap#1153, "Single page app support for GitHub Apps [Preview]", was labelled Paused on 2026-08-13, and its plan caps SPA refresh tokens at possibly ~24h |
Yes, when [cors] is enabled. optionsCorsHandler() wraps /login/oauth/access_token (web.go). Its allowed headers are only [cors] HEADERS, so send client_id in the body, not Basic auth |
| Rewriting commits | Git Data API | No API: every git/* route is read-only except notes. Needs git smart HTTP with [repository] ACCESS_CONTROL_ALLOW_ORIGIN |
Verdict:
- Forgejo is fully static. It needs a public OAuth2 client with PKCE,
plus the
[cors]and git-HTTP CORS settings. Sveltia CMS and Decap CMS do exactly this. - GitHub is static plus a stateless relay for the code exchange and
refresh. It's the pattern used by
prose/gatekeeper,
sveltia-cms-auth,
utterances-oauth,
Giscus and
ReviewStack
(Netlify's proxy, or a PAT).
- GitHub's best practices concede a public client would have to ship its secret.
- Fallback with no server: a pasted fine-grained PAT, which is fine for the v0 read-only queue.
Hosting: tailnet only.
- One origin on
forgeviatailscale serve, with the MagicDNS HTTPS certificate:https://forge.<tailnet>.ts.net/review/. All your devices, the phone included, are on the tailnet. - Public exposure (Funnel, GitHub Pages) is out of scope. If it were ever
wanted: Pages can't set response headers, so the CSP would go in a
<meta>tag, whereframe-ancestorsdoesn't work. - Why HTTPS:
- service workers,
Securecookies andcrypto.randomUUIDneed a secure context; - GitHub callbacks other than loopback should be HTTPS.
- S256 PKCE by itself could work over plain HTTP with a pure-JS SHA-256
and
crypto.getRandomValues, which isn't restricted to secure contexts (MDN).
- service workers,
- Note: Tailscale certificates come from Let's Encrypt, so
forge.<tailnet>.ts.netappears in public Certificate Transparency logs. That reveals the name, not access.
3. Auth
GitHub: which token
| Fine-grained PAT | OAuth App token | GitHub App user token (chosen) | |
|---|---|---|---|
| Reach | Selected repos of one owner | All you can reach, by coarse scope | The intersection of what you can reach and where the app is installed (docs), plus implicit read of public resources (docs) |
| Permissions | Fine-grained | Coarse | The intersection of your permissions and the app's |
| Lifetime | Up to a year | Until revoked | 8h, refreshable for 6 months, refresh token rotated on use (docs) |
| Attribution | You | You | You, with the app's badge (docs) |
Decision: a dedicated GitHub App, cgwalters-review, for user tokens only.
- It's separate from the bot's
cgwaltersbot, so a compromise of the bot's key can't act as you. It never uses a private key. - Its rate budget is your user's 5,000 requests an hour, shared with your
other tokens (
gh, PATs, other apps acting as you) (docs). Conditional requests that return 304 are free when they're authorised (docs).
Create the cgwalters-review app
Settings → Developer settings → GitHub Apps → New GitHub App, owned by your user account (docs).
- Callback URLs (up to 10;
docs):
https://forge.<tailnet>.ts.net/review/auth/github/callback- For development,
http://127.0.0.1:8787/auth/github/callback. Loopback is documented only for OAuth apps, so if the form rejects it, use a second tailnet name. - A purely static variant has no callback today. That waits on roadmap#1153.
- Wildcard matching for callback URLs: leave it off. It's new (August 2026) and off by default for new apps, and GitHub advises enabling it only when necessary (changelog).
- Expire user authorization tokens: on.
- Request user authorization (OAuth) during installation: off. The relay
always passes
redirect_uri, and with this on GitHub sends users to the first callback. - Enable Device Flow: off. GitHub's best practices say "Don't enable device flow without reason": it doesn't need a redirect URI, so it can be used for phishing. Revisit if a CLI ever needs it.
- Webhooks: off. Setup URL: none.
- Repository permissions:
- Contents: read and write;
- Pull requests: read and write;
- Issues: read and write;
- Checks: read;
- Commit statuses: read;
- Metadata: read.
- Workflows: off by default. Rewriting commits that touch
.github/workflowsneeds it, so sign those off withdco-signoffinstead, unless you decide otherwise.
- Organization and account permissions: none. The bot syncs the board mirror, not this app.
- Where can this app be installed:
- Any account is needed: a private app owned by a user "can only be
installed on the account that owns the app"
(docs),
and it must go on
cgwalters-forgetoo. - A public app gets an install page at
github.com/apps/cgwalters-review. It isn't listed in the Marketplace. - Others installing it gain nothing: their tokens reach only their own resources, and the relay is tailnet-only.
- Any account is needed: a private app owned by a user "can only be
installed on the account that owns the app"
(docs),
and it must go on
- Install with selected repositories:
- On your account: only the forks you publish take-overs from.
- On
cgwalters-forge: the items repository plus the forks under review. New forks appear daily, so choosing "all repositories" there is the pragmatic alternative. The bot can already write there; the extra power a stolen token adds is acting as you (e.g./promote). See the open questions. - bootc-dev and composefs only if you want the app to act upstream as you. Reading them is implicit.
- Afterwards: generate a client secret and install it on
forgeas a systemd credential of the relay's user (see Deployment). Don't generate a private key.
Does PKCE let a public client skip the secret? No, not on GitHub as of 2026-09-25.
- The web-flow exchange and refresh both list
client_secretas required. The only exception is refreshing a device-flow token. - There's no CORS on the token endpoint, and the SPA feature is Paused.
- The relay still sends S256 PKCE, as GitHub recommends.
The relay: a token-mediating backend
A single Rust binary (axum, reqwest) on the same origin as the static files. RFC 10017 (BCP 212, OAuth 2.0 for Browser-Based Applications) calls this pattern a token-mediating backend (§6.2). It is a confidential client that hands the application access tokens.
§6.2's trade-off: it "is less secure than a BFF". Injected script can't get at the refresh token or the session cookie, but it can steal the current access token, or "request a fresh token from the token-mediating backend" (§5.1.4). So the deciding defence is that no attacker-controlled script runs on the origin. That's why deployment and CSP below are not optional.
Endpoints:
GET /auth/github/start:- generates
stateand a PKCE verifier, and seals them into a cookie:HttpOnly; Secure; SameSite=Lax; Path=/review/auth/github/callback; Max-Age=600; - it must be Lax: the callback is a cross-site top-level navigation from github.com, which would drop a Strict cookie;
- then redirects to
github.com/login/oauth/authorize.
- generates
GET /auth/github/callback: checksstateand exchanges the code with the secret and verifier. It sets the session cookie, sealed with AES-GCM under a key from a systemd credential:HttpOnly; Secure; SameSite=Strict; Path=/review/auth. The cookie holds:- the refresh token and its expiry;
- the current access token and its expiry.
POST /auth/github/token:- requires a matching
Originand a custom header (the CSRF defence §6.2.3.3 asks for on this endpoint); - returns the sealed access token if it has more than 10 minutes left, and only refreshes near expiry;
- GitHub rotates refresh tokens on every use, so concurrent refreshes would log you out. The relay single-flights refreshes per session (an in-process lock keyed by a hash of the cookie; nothing persistent), and the browser serialises its own calls across tabs with the Web Locks API.
- requires a matching
POST /auth/logout:- clears the cookie;
- revokes with
DELETE /applications/{client_id}/grant, which takes a valid access token in the body, so it refreshes first if needed.
The relay has no database and doesn't log tokens. Rotating the sealing key
signs everyone out. The same code handles /auth/forgejo/* for relay-mode
Forgejo.
Forgejo: the equivalent setup
ConfidentialClient is a per-application setting, so relay mode and static
mode need two OAuth2 applications, created under Settings → Applications
(docs):
| App | Confidential | Redirect URI |
|---|---|---|
cgwalters-review (relay mode) |
yes | https://forge.<tailnet>.ts.net/review/auth/forgejo/callback |
cgwalters-review-static |
no (PKCE mandatory) | https://forge.<tailnet>.ts.net/review/forgejo/ |
-
For development, public clients match
http://127.0.0.1redirects on any port. It must be the IP literal, notlocalhost(ContainsRedirectURIin models/auth/oauth2.go). -
Scopes: request
write:repository write:issue read:user.- The docs say "Scopes are not implemented for OAuth2 tokens", but the code
applies grant scopes that are valid token scopes to the token
(
grantAdditionalScopesinservices/auth/method/oauth2.go, tested intests/integration/oauth_test.go). Verify on your version. - Changing the scopes later requires revoking the existing grant
first. Otherwise authorize fails with "a grant exists with different
scope" (
routers/web/auth/oauth.go).
- The docs say "Scopes are not implemented for OAuth2 tokens", but the code
applies grant scopes that are valid token scopes to the token
(
-
Refresh:
INVALIDATE_REFRESH_TOKENSdefaults to true in code (modules/setting/oauth2.go), althoughapp.example.inishowsfalse.- Reusing a refresh token fails with "token was already used", so two tabs refreshing at once log you out.
- Same remedy as on GitHub: cache the access token (1h by default) and refresh near expiry under a Web Locks single-flight.
-
app.ini:[cors] ENABLED = true ALLOW_DOMAIN = https://forge.<tailnet>.ts.net ; HEADERS keeps its default (Content-Type,User-Agent). If-None-Match is ; useless: Forgejo's JSON API sends no ETags (only raw and media files do). [repository] ; git smart HTTP from the browser, only for rewording and sign-off ACCESS_CONTROL_ALLOW_ORIGIN = https://forge.<tailnet>.ts.net- Caveat: with
[service] REQUIRE_SIGNIN_VIEW = true, the sign-in check runs before the git-HTTP CORS handler (routers/web/githttp.go). The unauthenticated preflight then gets a 401 and browser git fails. In that case, use the relay's server-side rewrite (§4).
- Caveat: with
-
Tokens: Forgejo has no installation-scoped app tokens. Since v15, a PAT can be limited to repositories (v15 release), which is the no-OAuth fallback.
Browser hygiene
- Where tokens live:
- Access tokens are kept in memory only.
- In static Forgejo mode the refresh token has to be readable by
JavaScript. It goes in
sessionStorage, so closing the tab signs you out. - Nothing credential-like goes in
localStorage. IndexedDB holds only caches and unsent drafts.
- CSP, sent as a header by the relay or static server:
default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self' https://api.github.com https://<forgejo>; img-src 'self' data: https://avatars.githubusercontent.com; frame-ancestors 'none'; base-uri 'none'; form-action 'self', plusrequire-trusted-types-for 'script'. There are no third-party scripts or fonts. - Rendering untrusted text: everything shown is untrusted.
- Markdown goes through markdown-it with
html: false, which also refusesjavascript:anddata:text/htmllinks, then DOMPurify. - Diffs and commit messages are rendered as text nodes.
- Markdown goes through markdown-it with
Deployment and supply chain
The relay will mint a token acting as you for any script running on its origin (§6.2 above). So the served code is the security boundary:
- Deploy only commits you approved.
forgedeploys only tags signed by your key, checked withgit verify-tagagainst your key, asbin/git-verify-tag-with-keydoes. It builds from the tag, with lockfile installs only. - The bot never deploys. On
forge, the served files, the relay binary and its systemd credentials (client secrets, the sealing key) belong to a dedicatedreviewuser. They're unreadable and unwritable by the bot's user, and the bot has no sudo there. - The bot may open PRs on this repository like any other, and you review them. Dependencies are pinned and few (Preact, markdown-it, DOMPurify, isomorphic-git).
4. Architecture
Two thin apps, one shared library
Decision: no general forge abstraction. Separate GitHub and Forgejo apps are fine, and simpler. The layout:
packages/items/ item format: parse, edit, round-trip (TypeScript)
packages/ui/ queue + item components (Preact), fed plain item data
apps/github/ GitHub client: REST + one GraphQL mutation, relay auth
apps/forgejo/ Forgejo client: REST + isomorphic-git, static or relay auth
relay/ review-relay (Rust)
crates/items/ item format + review-items CLI (Rust)
spec/ format spec fixtures, run by both test suites
- Each app owns its API calls and flows, with no common interface to satisfy.
- What's shared is data: the item model, plus the queue components that render it.
- The Forgejo app starts as a copy-and-adapt of the GitHub app's PR views. Shared code is extracted only once it's clearly identical.
Technology.
- Browser: strict TypeScript + Preact, bundled by Vite.
- Relay and CLI: Rust, where secrets and the bot's loop live.
- Why not Rust/WASM for the browser (Leptos, Dioxus)? Rust has mature
markdown (comrak, pulldown-cmark) and sanitising (ammonia). The gap is
elsewhere:
- isomorphic-git for Forgejo: gitoxide builds for wasm32 only as plumbing crates, with no browser transport;
- an editor (CodeMirror 6);
- bundle size on a phone.
- The restricted front matter removes the need for a format-preserving YAML library on either side.
API use
| Operation | GitHub app | Forgejo app |
|---|---|---|
| Poll items repo | GET commits/{branch} with If-None-Match (304 is free) |
GET branches/{branch}, comparing the commit id (no ETags) |
| Read items | git/trees/{sha}?recursive=1, git/blobs/{sha}; blobs cached forever by sha |
same paths |
| Answer or edit | PUT contents/{path} with sha; retry on 409, 422 and 5xx |
same, and 5xx expected on a race |
| PR, commits, diff | pulls/{n}, pulls/{n}/commits, Accept: application/vnd.github.diff |
pulls/{n}, pulls/{n}/commits, pulls/{n}.diff |
| Edit PR body | PATCH pulls/{n} after rereading and comparing (no precondition) |
same |
| Reword and sign-off | POST git/commits per commit, then GraphQL updateRefs with beforeOid (compare-and-swap; REST PATCH git/refs takes only sha and force) |
isomorphic-git: fetch the branch, rebuild the commits, push with force, and use onPrePush to cancel unless remoteRef.oid === expectedHead. force alone isn't a lease: the old value sent is whatever the server advertised at push time |
/promote |
issue comment | issue comment |
Polling:
- The items repo is polled every 30 seconds while the tab is visible. Linked PRs are polled every 2 minutes, and whenever you open one.
- The app reads
X-RateLimit-Remainingand backs off below 10% of the shared budget. - Forgejo has no built-in API rate limiter.
UI flows
- Queue: items needing you (
needs-human,draft, unanswered questions,triage), grouped by priority and ordered byrank. Options answer in one tap, as in the prototype. - Answer, or approve triage: one
PUTwriting only inside the answer markers, or thestatusline. The card shows "sent" at once, and "acted on" once the bot'sActed-on:commit arrives. - PR review:
- the rendered, editable description;
- the commit stack, with per-commit diffs (ReviewStack-style navigation);
- the CI summary;
- each commit message editable in place, with a "Sign off" toggle that
appends your
Signed-off-byfromreview.yaml(in the items repo).
- Rewrite and sign off:
- the app shows each message before and after, and checks that every tree is reused;
- it writes new commits: author unchanged, committer you;
- then a compare-and-swap ref update against the head you reviewed. If the bot pushed meanwhile, the update fails and your edits stay as drafts.
- GitHub doesn't sign commits with a custom committer. Projects that require signed commits go through the CLI.
- Sign off and promote: step 4, then a
/promotecomment.bot-pr promoteand its D6 sign-off gate do the rest.
Also from issue #8, placed in the plan:
- Take-over (v2.1): rewrite with your identity and the project's trailer
policy, drop the bot-meta section, and push to
cgwalters/R, which needs the app installed on that fork. Then open the compare link for you to create the PR. The item is markedworkflow: manual. - Per-project trailer policy (v2.1):
policy.yamlin the items repository, mapping a repo to "bot posts" or "take-over" and a trailer style. It's in git, and reviewed like everything else. - Small code edits (v2.2):
- GitHub: blob → tree → commit;
- Forgejo: the contents API (which supports
signoff). - Anything larger goes to the jj-based
bot-reviewCLI from the pivot plan.
Offline
- A service worker caches the app shell. Blobs you've viewed stay readable from IndexedDB, which is a pure cache.
- Answers written offline are kept as unsent drafts. They're submitted with the same preconditions once you're back online.
- There's no sync engine: git and the forge are the sync layer. For real offline work, clone the items repo.
5. Prior art
| Project | What it is | Verdict |
|---|---|---|
| Gerrit NoteDb | Review state as commits on refs/changes/XX/N/meta, with the state in footers (Patch-set:, Label:, Status:; ChangeNoteFooters.java) |
Borrow: state changes are commits with trailers, on a normal branch |
| Backlog.md | Markdown tasks with front matter, a CLI/TUI, and a local web server. Active (v1.53.0, 2026-09-24) | Loosely modelled on it; not compatible with its tooling. Its <!-- AC:BEGIN --> markers inspired our answer markers |
| git-appraise | Reviews as JSON lines in git notes, merged with cat_sort_uniq. Dormant since 2023-08, not archived |
Borrow the append-only idea. Notes are invisible on both forges |
| git-bug | An operation-based CRDT in JSON blobs under refs/bugs/, with a GraphQL server UI. The Forgejo bridge is a draft (#1628). Active (v0.11.0) |
Not a base: hidden refs, JSON, needs a server |
| Radicle | Collaborative objects (issues, patches, reviews) under refs/cobs/, on its own peer-to-peer network |
Borrow the patch/revision/verdict vocabulary |
| Sapling ReviewStack | A static React UI over GitHub GraphQL with per-commit stack review. It writes comments, reviews and labels, but can't rewrite commits. MIT, GitHub only | Borrow its UX. Proof that a static review UI works |
| Sveltia CMS | A static app committing markdown via the GitHub and Forgejo APIs, with serverless PKCE on Forgejo | Borrow its auth approach |
| Pages CMS | A Next.js app with Postgres | Ignore: it has a lookaside DB |
| Utterances, Giscus | Issues or discussions as the store. Utterances uses a Cloudflare worker; Giscus a GitHub App, with optional caching | Ignore: the forge becomes the database |
Decision: build new and small, borrowing the pieces above.
6. Plan
- v0: static read-only queue (GitHub).
- Format spec and fixtures.
review-items importof the board and the prototype.- The GitHub app reading the items repo with a read-only PAT.
- Deployed on
forgefrom a tag you signed.
- v1: answers, triage, and Forgejo read-only.
- The relay and
cgwalters-review; writes with preconditions. review-items answeredwith the push-actor check;review-items set/sync-board.- The board becomes a mirror.
- A read-only Forgejo app over an items repo on your instance, which proves the shared library early.
- The relay and
- Spikes before v2:
updateRefswithbeforeOidusing a user token.- Cross-fork tree reuse: a commit in
cgwalters/Rbuilt from trees ofcgwalters-forge/R, which relies on the shared fork network. - The GitHub activity API's retention and pagination on a busy repository.
- v2: PR review and sign-off on GitHub. v2.1 adds take-over and trailer policy; v2.2 adds small code edits.
- v3: Forgejo writes. OAuth (static or relay), and rewrites with
isomorphic-git. Fallback: the relay does the rewrite server-side, with
a real git clone on
forgeusing your token. The token is held only for that request and never stored. This is needed anyway underREQUIRE_SIGNIN_VIEW.
First PRs:
spec: Define the work item format:docs/items-format.mdandspec/fixtures/(parse, round-trip, one-line-edit, answer-block edits).items: Add item parser and review-items CLI: the Rust crate with data-driven fixture tests;import,list,set.items: Import the Workstream board and the prototype queue: run once into the items repository, reviewed as one commit.web: Add read-only GitHub queue:packages/items(TypeScript, same fixtures),packages/ui,apps/github, CSP, and CI (typecheck, tests,cargo test).relay: Add GitHub App token relay: sealed cookies, PKCE, single-flight refresh, the systemd unit for thereviewuser, and a signed-tag deploy script.items: Verify answers by push actor:review-items answered, with fixtures for forged-author and rebased-on-top cases.
Later (not in scope)
Codespace-on-devspace mode: trying a change live, browsing all of the code, and talking to an agent about it, on a devspace. Recorded here only as a direction. This design stays a lightweight client-side app.
Open questions for cgwalters
-
Installs of
cgwalters-review.- Is "Any account" acceptable? It gives the app a public install page, but it's unlisted in the Marketplace.
- On
cgwalters-forge: selected repositories (you add each new fork), or all repositories? - Workflows stays off unless you want it.
- Install on bootc-dev and composefs?
-
Your existing app,
cgwaltersbot.- Confirm it stays the bot's identity only, never used for review.
- Who owns it (your user or an org), and what's its install setting?
- Are expiring user tokens on?
This doesn't block the control app, but it matters for D1/D2 of the pivot plan. For
cgwalters-reviewI need its client ID, and the secret installed by you onforgeas thereviewuser's credential, never through the bot. -
forge.- Its MagicDNS name.
- Is the name appearing in Certificate Transparency logs acceptable?
- Can a dedicated
reviewuser own the deployment, with the bot's user unable to read or write it? - Which key signs deploy tags?
-
Sign-off identity: the exact
Signed-off-byname and email. -
Your Forgejo.
- Its version, and whether
REQUIRE_SIGNIN_VIEWis on. - Are the
[cors]and git-HTTP CORS settings acceptable? - Static mode, or relay mode (the default)?
- Its version, and whether