crueber/walhub

Watch

Fork 0

Checks subsystem audit: live and fully wired, not dead infrastructure (statuses, wct_ tokens, checks page, merge gating) #504

New issue

Closed

opened 2026-09-13 23:27:23 +00:00 by crueber · 3 comments

crueber commented

2026-09-13 23:27:23 +00:00

Owner

Verdict: checks is a LIVE, fully-wired subsystem — not dead infrastructure

Investigated whether anything in walhub writes to or consumes the checks subsystem today (statuses, wct_ tokens, checks page, merge gating). Conclusion: every layer is composed, routed, and consumed on both the write and read paths. No dead code found. The only "quiet" aspect is that nothing inside walhub produces statuses — they arrive exclusively from external CI callers via the wct_ token API, which is by design (05 is the consumer half of an external-CI contract, the same shape as Forgejo statuses + Woodpecker).

Evidence (commit `8819057`)

Write path — external CI via wct_ tokens:

cmd/walhub/checks.go — chainChecks registers the wct_ credential in the server auth chain (checks.ClaimToken / ParseCIToken → unprivileged checks.CIPrincipalName principal), prefix-disjoint from wgt_/Bearer/Basic.
cmd/walhub/checks.go:37 — api.RegisterExposed(checks.ExposedTemplates...); internal/checks/exposed_test.go pins the discovery templates incl. /{owner}/{repo}/api/checks/statuses/{sha} (POST = the status writer) and the admin token-management pair …/api/checks/tokens, …/api/checks/tokens/{id}.
internal/checks/auth.go — bearer/Basic extraction, secret verification against the repo's token record, real 401 on malformed wct_ shapes.
internal/server/auth_extra_test.go:11 — server Seams test names checks' wct_ tokens as the seam's first consumer.

Composition:

cmd/walhub/collab.go:184-193 — newChecksService(st, ident, pullsSvc, reg, cfg.Git.Binary) wired at composition; collab.go:335-336 chains the handler onto the server.
cmd/walhub/notify.go:89-92 — wireNotifyFanout subscribes the notify fanout to checks.Notify/checks.Stream events (05 §8 failure/error fan-out); internal/notify/emit.go:88 (EmitCheck).

Merge gating (fail-closed consumer):

internal/pulls/checks.go:18-53 — ChecksGate seam; pulls.Service.checkRequiredChecksGate is fail-closed: a require_checks rule with no checks backend fails the merge.
internal/pulls/merge.go:174 — runMerge invokes checkRequiredChecksGate on every merge.
internal/pulls/pulls.go:180-182 — Checks field on the pulls service, satisfied by *checks.Service (asserted at cmd/walhub/checks.go:109).

UI consumption:

web/src/pages/Checks.jsx — the /:owner/:name/checks page (paged index, state pills, expandable per-context rows, state/context filters); live frames ride the repo collab stream and invalidate index + sha views. Exports the shared CheckPill.
web/src/pages/Repo.jsx:167 — "Checks" tab in the repo navigation.
web/src/pages/Settings.jsx:809-902 — admin-only CI-tokens tab (tab 5): list/create/revoke of wct_ tokens.
web/src/pages/Pull.jsx:584-764 — head-sha combined view + per-context rows, require_checks advisory union over policy rules matching the base branch, and "blocking merge: …" display of checksBlockers; merge flow invalidates checksKey().
web/src/pages/Commit.jsx:218-220 — per-commit checks toggle (CheckDetail.jsx).
web/sdk/src/checks.js — full SDK surface: combined, statuses, paged index (all no-store), plus CI-token admin calls, riding /{o}/{r}/api/checks….

What "in use" would require

Nothing in walhub itself. The write path is already open to external CI: create a wct_ token in repo Settings → CI tokens, then POST /{owner}/{repo}/api/checks/statuses/{sha} with Authorization: Bearer wct_…. "In use" on any real repo is purely an ops/CI-configuration step (point Woodpecker or a script at the endpoint) — there is no implementation prerequisite inside walhub. The only internal consumer that can create check data is that external POST; nothing else in the tree writes statuses.

Acceptance criteria

Verdict recorded: checks subsystem is live (composed, routed, consumed) — dead-infrastructure hypothesis rejected
Every layer verified with file:line evidence in the current tree
No code changes made (static investigation only)

## Verdict: checks is a LIVE, fully-wired subsystem — not dead infrastructure Investigated whether anything in walhub writes to or consumes the checks subsystem today (statuses, `wct_` tokens, checks page, merge gating). Conclusion: every layer is composed, routed, and consumed on both the write and read paths. No dead code found. The only "quiet" aspect is that nothing inside walhub *produces* statuses — they arrive exclusively from external CI callers via the `wct_` token API, which is by design (05 is the consumer half of an external-CI contract, the same shape as Forgejo statuses + Woodpecker). ## Evidence (commit 8819057) **Write path — external CI via `wct_` tokens:** - `cmd/walhub/checks.go` — `chainChecks` registers the `wct_` credential in the server auth chain (`checks.ClaimToken` / `ParseCIToken` → unprivileged `checks.CIPrincipalName` principal), prefix-disjoint from `wgt_`/`Bearer`/`Basic`. - `cmd/walhub/checks.go:37` — `api.RegisterExposed(checks.ExposedTemplates...)`; `internal/checks/exposed_test.go` pins the discovery templates incl. `/{owner}/{repo}/api/checks/statuses/{sha}` (POST = the status writer) and the admin token-management pair `…/api/checks/tokens`, `…/api/checks/tokens/{id}`. - `internal/checks/auth.go` — bearer/Basic extraction, secret verification against the repo's token record, real 401 on malformed `wct_` shapes. - `internal/server/auth_extra_test.go:11` — server Seams test names checks' `wct_` tokens as the seam's first consumer. **Composition:** - `cmd/walhub/collab.go:184-193` — `newChecksService(st, ident, pullsSvc, reg, cfg.Git.Binary)` wired at composition; `collab.go:335-336` chains the handler onto the server. - `cmd/walhub/notify.go:89-92` — `wireNotifyFanout` subscribes the notify fanout to `checks.Notify`/`checks.Stream` events (05 §8 failure/error fan-out); `internal/notify/emit.go:88` (`EmitCheck`). **Merge gating (fail-closed consumer):** - `internal/pulls/checks.go:18-53` — `ChecksGate` seam; `pulls.Service.checkRequiredChecksGate` is fail-closed: a `require_checks` rule with no checks backend fails the merge. - `internal/pulls/merge.go:174` — `runMerge` invokes `checkRequiredChecksGate` on every merge. - `internal/pulls/pulls.go:180-182` — `Checks` field on the pulls service, satisfied by `*checks.Service` (asserted at `cmd/walhub/checks.go:109`). **UI consumption:** - `web/src/pages/Checks.jsx` — the `/:owner/:name/checks` page (paged index, state pills, expandable per-context rows, state/context filters); live frames ride the repo collab stream and invalidate index + sha views. Exports the shared `CheckPill`. - `web/src/pages/Repo.jsx:167` — "Checks" tab in the repo navigation. - `web/src/pages/Settings.jsx:809-902` — admin-only CI-tokens tab (tab 5): list/create/revoke of `wct_` tokens. - `web/src/pages/Pull.jsx:584-764` — head-sha combined view + per-context rows, `require_checks` advisory union over policy rules matching the base branch, and "blocking merge: …" display of `checksBlockers`; merge flow invalidates `checksKey()`. - `web/src/pages/Commit.jsx:218-220` — per-commit checks toggle (CheckDetail.jsx). - `web/sdk/src/checks.js` — full SDK surface: combined, statuses, paged index (all no-store), plus CI-token admin calls, riding `/{o}/{r}/api/checks…`. ## What "in use" would require Nothing in walhub itself. The write path is already open to external CI: create a `wct_` token in repo Settings → CI tokens, then `POST /{owner}/{repo}/api/checks/statuses/{sha}` with `Authorization: Bearer wct_…`. "In use" on any real repo is purely an ops/CI-configuration step (point Woodpecker or a script at the endpoint) — there is no implementation prerequisite inside walhub. The only internal consumer that can create check data is that external POST; nothing else in the tree writes statuses. ## Acceptance criteria - [x] Verdict recorded: checks subsystem is live (composed, routed, consumed) — dead-infrastructure hypothesis rejected - [x] Every layer verified with file:line evidence in the current tree - [x] No code changes made (static investigation only)

crueber added the

pr/merge protection rules

pull requests

labels

2026-09-13 23:27:36 +00:00

crueber added this to the v1 milestone

2026-09-13 23:27:36 +00:00

crueber referenced this issue

2026-09-13 23:29:54 +00:00

Hide the repo Checks tab when no checks exist (reappear on first report) #505

crueber referenced this issue from a commit

2026-09-14 01:20:03 +00:00

Fix #504: record checks-subsystem audit verdict in 05 Decisions

crueber referenced this issue from a pull request that will close it,

2026-09-14 01:20:04 +00:00

Fix #504: record checks verdict #509

crueber commented

2026-09-14 01:20:07 +00:00

Author

Owner

Verdict recorded for review in PR #509 (#509): docs-only Decisions entry in docs/features/05_checks_statuses.md. Key claims spot-checked before recording — checks.ClaimToken wiring (cmd/walhub/checks.go:61-72), ExposedTemplates registration (cmd/walhub/checks.go:37), ChecksGate fail-closed (internal/pulls/checks.go:18-50), merge call site (internal/pulls/merge.go:174), composition (cmd/walhub/collab.go:193,336). No code changes.

Verdict recorded for review in PR #509 (https://git.packden.us/crueber/walhub/pulls/509): docs-only Decisions entry in docs/features/05_checks_statuses.md. Key claims spot-checked before recording — checks.ClaimToken wiring (cmd/walhub/checks.go:61-72), ExposedTemplates registration (cmd/walhub/checks.go:37), ChecksGate fail-closed (internal/pulls/checks.go:18-50), merge call site (internal/pulls/merge.go:174), composition (cmd/walhub/collab.go:193,336). No code changes.

crueber commented

2026-09-14 01:20:44 +00:00

Author

Owner

Review of PR #509 (branch fix/issue-504, commit c3af8ce) — docs-only verdict record for #504.

SCOPE: one file, one insertion — docs/features/05_checks_statuses.md Decisions entry. No code touched. Matches the issue acceptance criteria (verdict recorded, file:line evidence, no code changes).

VERDICT FIDELITY: entry accurately records the issue verdict — live/composed/routed/consumed on write+read paths, external-CI-by-design (nothing inside walhub produces statuses; wct_ token POST is the only writer), no dead code, static-investigation-only. No overclaim found.

SPOT-CHECKS (main checkout, independent):

Write path — cmd/walhub/checks.go: newChecksService (:36), api.RegisterExposed (:37), chainChecks (:61), checks.ClaimToken (:64) / ParseCIToken (:67). Confirmed.
Merge gating — internal/pulls/checks.go ChecksGate seam (:18-24), checkRequiredChecksGate (:38); fail-closed confirmed in source (no backend + require_checks rule -> ErrConflict refuse); call site internal/pulls/merge.go:174; Checks field internal/pulls/pulls.go:182. Confirmed.
UI consumption — web/src/pages/Checks.jsx and web/sdk/src/checks.js exist; Repo.jsx:168 Checks tab. Confirmed.

STYLE: Decisions-section format matches neighbors (bold lead + Forgejo #504 ref + rationale), appended after the #271 entry, before Explicitly-out-of-scope. AGENTS.md law 12 satisfied (decision appended with rationale in same change as the work it records; docs-only change needs no code companion).

MERGE HYGIENE: branch is exactly 1 commit ahead of main; hunk context matches main tip (applies cleanly). Main worktree left untouched (read-only review).

No findings blocking merge.

Review of PR #509 (branch fix/issue-504, commit c3af8ce) — docs-only verdict record for #504. SCOPE: one file, one insertion — docs/features/05_checks_statuses.md Decisions entry. No code touched. Matches the issue acceptance criteria (verdict recorded, file:line evidence, no code changes). VERDICT FIDELITY: entry accurately records the issue verdict — live/composed/routed/consumed on write+read paths, external-CI-by-design (nothing inside walhub produces statuses; wct_ token POST is the only writer), no dead code, static-investigation-only. No overclaim found. SPOT-CHECKS (main checkout, independent): 1. Write path — cmd/walhub/checks.go: newChecksService (:36), api.RegisterExposed (:37), chainChecks (:61), checks.ClaimToken (:64) / ParseCIToken (:67). Confirmed. 2. Merge gating — internal/pulls/checks.go ChecksGate seam (:18-24), checkRequiredChecksGate (:38); fail-closed confirmed in source (no backend + require_checks rule -> ErrConflict refuse); call site internal/pulls/merge.go:174; Checks field internal/pulls/pulls.go:182. Confirmed. 3. UI consumption — web/src/pages/Checks.jsx and web/sdk/src/checks.js exist; Repo.jsx:168 Checks tab. Confirmed. STYLE: Decisions-section format matches neighbors (bold lead + Forgejo #504 ref + rationale), appended after the #271 entry, before Explicitly-out-of-scope. AGENTS.md law 12 satisfied (decision appended with rationale in same change as the work it records; docs-only change needs no code companion). MERGE HYGIENE: branch is exactly 1 commit ahead of main; hunk context matches main tip (applies cleanly). Main worktree left untouched (read-only review). No findings blocking merge.

crueber closed this issue

2026-09-14 01:21:00 +00:00

crueber commented

2026-09-14 01:21:00 +00:00

Author

Owner

Recorded by PR #509 (review clean; verdict fidelity + independent spot-checks pass), merged. Closing.

crueber referenced this issue from a commit

2026-09-14 01:21:00 +00:00

Merge pull request 'Fix #504: record checks verdict' (#509) from fix/issue-504 into main

crueber referenced this issue

2026-09-14 18:02:25 +00:00