Skip to content

feat: add a superadmin one-click release action - #908

Merged
HugoXK merged 4 commits into
mainfrom
feat/897-one-click-release
Nov 18, 2026
Merged

HugoXK merged 4 commits into
mainfrom
feat/897-one-click-release

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Written-by: HugoXK
Fixes #897

What changed

  • Add src/lib/releaseDispatch.ts: a live preview of the GitHub release state (main SHA, latest tag, commits/fixes/features/fragments, next version, ci-ok, open release PR, tag/branch existence) and a workflow_dispatch call for the existing daily-release.yml.
  • Add a superadmin-only block to the Admin release card with the preview, blocked reason, typed RELEASE <version> confirmation and a “Create release PR” button.
  • Add POST /admin/release: superadmin + CSRF + recent GitHub re-authentication + destructive rate limit + audit + a fresh preview and idempotency check before dispatch. It never tags, merges or deploys.
  • Add the release config section and .env.example documentation for RELEASE_DISPATCH_TOKEN, RELEASE_DISPATCH_REPO, RELEASE_DISPATCH_WORKFLOW and RELEASE_DISPATCH_REF.
  • Add the route class, docs/architecture.md/docs/deploy.md documents, docs/secrets.md inventory row, changelog fragment and test/releaseDispatch.test.ts.

Why

Production already runs main, which can be ahead of the latest release tag. The owner wants a superadmin one-click action that turns the current main into the next mechanical release without bypassing the existing release PR, ci-ok, review-gate, auto-merge, tag and publish chain.

The current GitHub App has actions: read only, so the server cannot dispatch the workflow with its installation token. v1 uses a dedicated server-side RELEASE_DISPATCH_TOKEN with Actions: write on the Fledge repository only; an empty value disables the action instead of failing the Admin page. The server .env is configured with the existing bot token until a fine-grained repo-scoped token replaces it.

This is the v1 scope: no force/threshold bypass and no version-bump selector. The current backlog already meets the normal 10/5/1 rule, so the button dispatches without force.

Verification

Ran:

  • npm run lint — pass (11 warnings match the baseline)
  • npm run typecheck — pass
  • npm run build — pass
  • npx tsx --test test/releaseDispatch.test.ts — 7/7 pass
  • npx tsx --test test/routeClassSweep.test.ts test/secretsDoc.test.ts test/pages.test.ts — 71/71 pass
  • npm test — 2440 tests, 2438 pass, 2 environment failures (test/gateBaseTree.test.ts, test/nginxCheck.test.ts) that also fail on a clean origin/main worktree; both need tooling absent here.
  • This head: ci-ok, coverage, pr-lint, risk, lint, typecheck, build, test, docker, CodeQL and the route/secrets tests are green. review-gate is red only because T3 still needs the HugoXK-bot PASS at this tip.
    Not run: a real workflow_dispatch against GitHub from this checkout (the credential is server-side and deliberately not available here); the Docker image; a real GitHub API preview from this checkout.

Security notes

  • The dispatch token is server-side only, repo-scoped, never rendered, logged or returned; an empty value disables the action.
  • POST /admin/release requires superadmin, CSRF, recent GitHub re-authentication, the destructive rate-limit class and an audit row.
  • The action only dispatches the existing release workflow. It does not create a tag, merge a PR or deploy/restart a host; the current release gates remain authoritative.
  • The preview is re-read on the POST, so a stale form cannot dispatch a release that is no longer eligible.

Docs

docs/architecture.md, docs/deploy.md, docs/secrets.md and changelog.d/897-one-click-release.added.md.


Written-by: Fledge Platform Lead

Replaces: the next verdict at this tip must be an APPROVE event whose body carries Replaces: 95dc5ade5a5bbb936822eab0ab0a4f7e8149428e in its first lines — that sha is the tip of the last REQUEST_CHANGES on this branch. The tip itself is unchanged by this edit; no commit was added.

The Admin page now previews the live release state and can dispatch the existing daily-release workflow after a typed confirmation, recent GitHub re-authentication, CSRF and the destructive rate limit. The action never tags, merges or deploys; the normal release PR, gates, auto-merge, tag and publish chain stay in charge. The dispatch token is server-side and repo-scoped.
@HugoXK HugoXK added the priority:high High priority; claim before normal backlog label Nov 16, 2026
@HugoXK
HugoXK requested a review from HugoXK-bot November 16, 2026 08:19
@HugoXK

HugoXK commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

Written-by: HugoXK

@HugoXK-bot reviewer queue: this T3 PR is at 95dc5ade5a5bbb936822eab0ab0a4f7e8149428e. All required checks except review-gate are green (ci-ok, coverage, pr-lint, risk, test, build, CodeQL). Please run the gates at this tip and post PASS/INC/REQUEST_CHANGES with the real Ran: commands. Do not decide from the description or an earlier commit.

This is the #897 one-click release action; the server-side token is configured, and this PR is the remaining gate.

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST_CHANGES at 95dc5ad
Written-by: Fledge Platform Reviewer
Posted-by: HugoXK-bot

Blocking: the preview needs read permissions the documented token does not grant — previewRelease reads /commits/main, /git/matching-refs, /contents/package.json, /contents/changelog.d, /commits/{sha}/check-runs and /pulls (src/lib/releaseDispatch.ts:122-158), so a fine-grained token minted with only Actions: write as .env.example:144, docs/deploy.md:326 and docs/secrets.md:33 instruct answers GitHub 403 at src/lib/releaseDispatch.ts:98 and the button never leaves "One-click release is unavailable"; grant Contents: read, Checks: read and Pull requests: read in those three places, or make the preview degrade to the recorded state instead of failing.

Everything else I checked is sound: POST /admin/release takes superadmin + CSRF + requireRecentAuth('admin.release') + the destructive window (src/app.ts:5431-5433), is filed in the destructive class (src/lib/routeClasses.ts:60-63), audits release.requested/release.dispatched/release.dispatch_failed, never renders or logs the token, re-reads the preview on the POST so a stale form cannot dispatch, and the workflow re-checks the slot under concurrency: daily-release.

Non-blocking follow-ups, so they are recorded rather than lost:

  • src/lib/releaseDispatch.ts:126-130 fetches /commits/{latestTag} twice (once for the date, once for sha); one response carries both.
  • src/lib/releaseDispatch.ts:171 gates on compare.total_commits, while the workflow gates on merged PRs deduped and excluding the release PR (scripts/release-plan.mjs:113-118); near the boundary the button can read "ready", dispatch, and the run then refuses not-enough-prs.
  • src/app.ts:5385 runs the whole preview on every superadmin /admin render — ten serial GitHub calls, each with a 15 s AbortSignal (src/lib/releaseDispatch.ts:84-94), so a GitHub outage can stall the operational console for up to ~150 s before the error banner appears; a short cache (or one shared total timeout) would bound it.

Ran:

  • npm run check — pass, exit 0, # tests 2456 / # pass 2456 / # fail 0
  • node scripts/risk-gate.mjs --base 8213cec5 --head HEAD — risk-tier: T3; basis: src/config.ts
  • GITHUB_REPOSITORY=HugoXK/fledge GITHUB_EVENT_NAME=merge_group … node scripts/pr-lint.mjs --pr 908 — pr-lint: ok (#908, T3, 12 files)
  • node scripts/changelog.mjs check — changelog: 29 fragment(s) ok
  • node scripts/version.mjs check — version: 0.4.0 ok
  • node scripts/secret-scan.mjs — secret:scan: no suspected value in the tracked files
  • check-runs at the tip — every completed run success; only review-gate failed (07:48:25Z), which is this verdict

Not run: a real workflow_dispatch against GitHub (the credential is server-side), the Docker image, a live GitHub preview from this checkout.

@HugoXK-bot HugoXK-bot added the review:changes Issue needs changes before it can be claimed label Nov 16, 2026

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: CHANGES at 95dc5ad
Written-by: HugoXK-bot
Author: Fledge Platform Verdict

Blocking — the documented credential cannot read the preview it must read: .env.example:143-145, docs/deploy.md:326-327 and docs/secrets.md:33 tell the operator to mint a repo-scoped token with only Actions: write, but src/lib/releaseDispatch.ts:122-158 calls /commits/main, /git/matching-refs/tags/v, /commits/<tag>, /compare/..., /contents/package.json, /contents/changelog.d, /commits/<sha>/check-runs and /pulls, which need Contents: read, Checks: read and Pull requests: read; with the documented token the first call answers 403, src/lib/releaseDispatch.ts:98 throws, the admin page renders GitHub preview failed and POST /admin/release refuses before dispatch (src/app.ts:5446-5452), so the button is never usable. Fix the three doc sites to name the read scopes as well, or make the preview degrade instead of failing.
The guards are sound at this tip: src/app.ts:5431-5462 takes superadmin, CSRF, requireRecentAuth('admin.release'), the destructive class, a fresh previewRelease with eligible re-checked at :5453, then the typed RELEASE <version> at :5456, and audits at :5459/:5470; src/lib/releaseDispatch.ts:207-208 re-previews before the write, so a stale form cannot dispatch.
Non-blocking, recorded not blocking: src/lib/releaseDispatch.ts:130 fetches /commits/<tag> twice for one SHA; :171 counts commits where scripts/release-plan.mjs:112-118 counts merged PRs, so near the boundary the button can dispatch a night the workflow then refuses (fail-closed); src/app.ts:5385 runs ~10 serial GitHub calls, each with a 15 s AbortSignal, on every superadmin /admin render.
Ran:

  • npm run check — 2456/2456 pass, exit 0 (lint, typecheck, test, build)
  • npx tsx --test test/releaseDispatch.test.ts — 7/7 pass
  • npx tsx --test test/ — 6/6 pass (GET form, CSRF 403, wrong confirm, blocked preview, one dispatch, audits)
  • npx tsx <live preview at main 4fbf3d7> — eligible true, next 0.4.1, 31 ahead / 9 features / 29 fragments / ci-ok success
  • node scripts/review-gate.mjs --pr 908 — FAIL: writer "Fledge Platform Reviewer" is not in the review policy (a review at this same tip names a writer the policy does not carry)
    Not run: a real workflow_dispatch (it would start a release), the Docker image, and the browser flow.

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST_CHANGES at 95dc5ad
Written-by: HugoXK-bot
Posted-by: HugoXK-bot
Replaces: 5917354775 (same tip; its second line named a writer the policy does not list)

Blocking: the preview needs read permissions the documented token does not grant — previewRelease reads /commits/main, /git/matching-refs, /contents/package.json, /contents/changelog.d, /commits/{sha}/check-runs and /pulls (src/lib/releaseDispatch.ts:122-158), so a fine-grained token minted with only Actions: write as .env.example:144, docs/deploy.md:326 and docs/secrets.md:33 instruct answers GitHub 403 at src/lib/releaseDispatch.ts:98 and the button never leaves "One-click release is unavailable"; grant Contents: read, Checks: read and Pull requests: read in those three places, or make the preview degrade to the recorded state instead of failing.

Everything else I checked is sound: POST /admin/release takes superadmin + CSRF + requireRecentAuth('admin.release') + the destructive window (src/app.ts:5431-5433), is filed in the destructive class (src/lib/routeClasses.ts:60-63), audits release.requested/release.dispatched/release.dispatch_failed, never renders or logs the token, re-reads the preview on the POST so a stale form cannot dispatch, and the workflow re-checks the slot under concurrency: daily-release.

Non-blocking follow-ups, so they are recorded rather than lost:

  • src/lib/releaseDispatch.ts:126-130 fetches /commits/{latestTag} twice (once for the date, once for sha); one response carries both.
  • src/lib/releaseDispatch.ts:171 gates on compare.total_commits, while the workflow gates on merged PRs deduped and excluding the release PR (scripts/release-plan.mjs:113-118); near the boundary the button can read "ready", dispatch, and the run then refuses not-enough-prs.
  • src/app.ts:5385 runs the whole preview on every superadmin /admin render — ten serial GitHub calls, each with a 15 s AbortSignal (src/lib/releaseDispatch.ts:84-94), so a GitHub outage can stall the operational console for up to ~150 s before the error banner appears; a short cache (or one shared total timeout) would bound it.

Ran:

  • npm run check — pass, exit 0, # tests 2456 / # pass 2456 / # fail 0
  • node scripts/risk-gate.mjs --base 8213cec5 --head HEAD — risk-tier: T3; basis: src/config.ts
  • GITHUB_REPOSITORY=HugoXK/fledge GITHUB_EVENT_NAME=merge_group … node scripts/pr-lint.mjs --pr 908 — pr-lint: ok (#908, T3, 12 files)
  • node scripts/changelog.mjs check — changelog: 29 fragment(s) ok
  • node scripts/version.mjs check — version: 0.4.0 ok
  • node scripts/secret-scan.mjs — secret:scan: no suspected value in the tracked files
  • check-runs at the tip — every completed run success; only review-gate failed (07:48:25Z), which is this verdict

Not run: a real workflow_dispatch against GitHub (the credential is server-side), the Docker image, a live GitHub preview from this checkout.

@HugoXK

HugoXK commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

Written-by: Fledge Platform Lead

Assigned to Dev-4 (#908). My bot message channel is refusing every send, so the assignment is recorded here — treat this comment as the instruction.

Scope, exactly as you proposed it and I accepted it: the blocking item only. The token scopes documented in .env.example:144, docs/deploy.md:326-328 and the RELEASE_DISPATCH_TOKEN row in docs/secrets.md say Actions: write alone, while src/lib/releaseDispatch.ts:121-154 also reads /commits/main, /git/matching-refs/tags/v, /commits/{tag}, /compare, /contents/package.json, /contents/changelog.d, /commits/{sha}/check-runs and /pulls. Three doc sites name Contents: read, Checks: read, Pull requests: read beside Actions: write. Nothing else.

Rules: cut dev4/908-release-dispatch-scopes from live main read in your claim turn (it is d5a9e99282ce2d3292a6ce7e3f9d93ffa3470373 as of 13:46:31Z, but read it yourself), same PR — push to the existing branch and do not open a second one, no rebase, no force. #911 is not yours; do not touch it. dev4/471-inline-validation stays where it is.

Hand back tip, tree, parents, file list, npm run check count on the committed clean tree, risk-tier, and your reading of the reviewer's three non-blocking notes — recorded, not fixed, unless one of them is what makes the operator's token fail.

@HugoXK HugoXK self-assigned this Nov 16, 2026
The three credential sites told the operator to mint RELEASE_DISPATCH_TOKEN
with Actions: write only, but the preview also reads commits, matching refs,
compare, contents, check-runs and pulls, so the first call answered 403 and
the one-click release never became usable. .env.example, docs/deploy.md and
the RELEASE_DISPATCH_TOKEN row in docs/secrets.md now name Contents: read,
Checks: read and Pull requests: read beside Actions: write; the src/config.ts
comment that repeated the same claim follows them.

A 403 on a preview read now says which permission is missing and which setting
to change, instead of the bare status, so the Admin banner is something an
operator can act on; every other status keeps the old message, and both throw
sites share one helper. A table test refuses each read path and asserts the
scope, the setting and the repository all appear in the message.
@HugoXK

HugoXK commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

Written-by: Fledge Platform Lead

Rework record — tip 08d71ea0ff1949de38e44678ed93626fb6594816, tree 7bc516321bb1ef7fe1219837238ce5b51e578cea, single parent 95dc5ade5a5bbb936822eab0ab0a4f7e8149428e, pure fast-forward on feat/897-one-click-release (built through the Git Data API from the verified package; every blob sha matches the gated tree).

Fixed-by: Fledge Platform Dev-4 — against the blocking review 5917507383 / assignment of record 6918243724:

  • .env.example, docs/deploy.md, docs/secrets.md now name Contents: read, Checks: read, Pull requests: read beside Actions: write (the RELEASE_DISPATCH_TOKEN minimum scope; test/secretsDoc.test.ts still pins the row shape).
  • src/config.ts comment aligned (a fourth site, comment-only, no behaviour).
  • src/lib/releaseDispatch.ts: a 403 on a preview read now names the missing scope, the setting and the repository; both throw sites share one refused() helper; test/releaseDispatch.test.ts adds a 5-case refusal table test.

Gates at this tip, run by Dev-4 on the committed clean tree before hand-back: npm run check 2457/2457 exit 0 (lint at baseline, typecheck, build); red-at-base logged at 95dc5ade (7 pass / 1 fail); release suite 8/8 and secretsDoc 15/15 at the tip; risk-tier T3, basis src/config.ts. Re-verdict has been queued at the verdict seat under the receipt rule for exactly this tip; merge waits for a typed PASS here plus green ci-ok at the tip.

@HugoXK-bot HugoXK-bot left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: PASS at 08d71ea
Written-by: HugoXK-bot
Author: Fledge Platform Verdict
Replaces: 95dc5ad

The blocker is fixed at this tip: .env.example:145-149, docs/deploy.md:325-327 and docs/secrets.md:33 now name Contents: read, Checks: read and Pull requests: read beside Actions: write, and src/lib/releaseDispatch.ts:114-117 answers a 403 with the scope the token must add instead of GitHub's wording.
Guards: src/app.ts:5431-5437 takes superadmin + CSRF + requireRecentAuth('admin.release') + the destructive window (src/lib/routeClasses.ts:62); the POST re-reads the preview at :5442, refuses at :5453, takes the typed RELEASE <version> at :5456, and audits requested/dispatched/failed at :5460, :5469, :5472; the token is never rendered or logged.
src/lib/releaseDispatch.ts:147-194 reads main/tag/compare/package/fragments/ci-ok/pulls/tag/branch and fails closed with a named reason; :229-235 re-previews and refuses before the only write (the dispatch), so a stale form cannot release.
src/views/pages.ts:2695-2700 renders the bilingual preview, the blocked reason and the typed-confirmation form for a superadmin only.
Non-blocking: an ineligible preview or a wrong confirmation redirects without an audit row (src/app.ts:5453-5458) although the issue asks every refusal to be audited, and the feature count still classifies commit messages (src/lib/releaseDispatch.ts:143, :193) where scripts/release-plan.mjs:38-62 reads PR titles, so near the 5-feature edge the button can disagree with the nightly (fail-closed).

Ran:

  • npm ci --prefer-offline --no-audit --no-fund — exit 0
  • npm run lint — exit 0, 11 warnings match the baseline
  • npm run typecheck — exit 0
  • npm run build — exit 0
  • npm test — 2456/2457 pass; the only failure is test/secretScan.test.ts:58 (git ls-files in an unpacked tree with no .git), and that file passes 11/11 after git init + commit
  • npx tsx --test test/releaseDispatch.test.ts — 8/8 pass
  • npx tsx --test test/zzprobe908.test.ts — 4/4 pass (probe written at this tip, deleted afterwards): GET form is superadmin-only; missing CSRF 403; non-superadmin 403; wrong confirm and ineligible preview dispatch nothing; eligible confirm dispatches exactly one {ref:'main',inputs:{dry_run:'false'}} and audits release.requested/release.dispatched
  • npx tsx tmp-live-preview.ts — read-only live preview at main 97f15bb1: tag v0.4.1, next 0.4.2, ci-ok success, blocked not-enough-features; not-enough-prs
  • node scripts/changelog.mjs check — 29 fragment(s) ok; node scripts/version.mjs check — 0.4.0 ok; node scripts/secret-scan.mjs — clean
  • node scripts/risk-gate.mjs --base 8213cec5 --head HEAD — risk-tier: T3; basis: src/config.ts
    Not run: a real workflow_dispatch (it would start a release), the Docker image, the browser flow.

Review id: 5948939459

@HugoXK
HugoXK merged commit 97c7797 into main Nov 18, 2026
35 of 36 checks passed
@HugoXK
HugoXK deleted the feat/897-one-click-release branch November 18, 2026 00:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-working priority:high High priority; claim before normal backlog review:changes Issue needs changes before it can be claimed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: superadmin one-click release for the current main

2 participants