Repository navigation
Description
Written-by: HugoXK
#897 was the duplicate of the webhook finding. That finding remains live on #896; no security content is lost. This slot is reused for the superadmin one-click release feature.
Summary
Add a superadmin-only Release current main action that drives the existing mechanical release chain:
- read the current
main, latest release tag, pending fragments,ci-ok, and any open release PR; - compute the next version from the existing cadence;
- ask for one explicit confirmation;
- dispatch the existing
daily-release.ymlworkflow (or create the same mechanical release PR through the GitHub App); - let the existing release PR →
ci-ok/review-gate→ auto-merge → tag →release.ymlchain do the actual release.
The button must not tag, merge, or deploy directly. It only starts the same reviewed release path. Production is already allowed to run ahead of the latest release tag; the one-click action is for versioning/changelog/tag/publish, not for making production current.
Current state, pinned to d00ead4
- Production
/healthz:version=0.4.0,commit=d00ead4af7cf,builtAt=2026-11-16T07:25:08Z. - Production was updated to
d00ead4at 07:25Z;ci-okond00ead4is success. - Latest release tag:
v0.4.0, target7a5fdf4. - Production is 27 commits / 27 merged PRs ahead of
v0.4.0. - Commit-message classification (final squash messages):
- 12
fix - 9
feat - 2
ui - 1
security - 1
ops - 1
docs - 1
ci
- 12
- PR-title classification (what
release-plan.mjsreads):- 8
fix - 13
feat - 2
ui - 1
security - 1
ops - 1
docs - 1
ci
- 8
- Pending changelog fragments on
main: 25. - Current package version:
0.4.0; under ADR 0008 the next release in this UTC week is 0.4.1.
The commit-message and PR-title counts differ because some PR titles and final squash messages have drifted (#842, #873, #877). The release planner reads PR titles, so it sees 13 features and easily passes the 5-feature rule.
Why production is already newer than release
hugoxk-infra owns the production deploy path:
service-update-all.sh→service-update-fledge.shupdates source fromorigin/main, builds and restarts (daily);fledge-deploy-tag.shdeploys a newer tag only when the tag version is ahead of the running package version;fledge-verify-release.shrecords the release chain for the admin page.
So production intentionally runs main, not the tag. The tag is a release marker, not the running binary. /healthz reports the package version plus the exact commit; today it is honest but the version (0.4.0) does not communicate that the build is 27 PRs past v0.4.0.
If the requirement is “the JSON version must correspond to the newer code”, one-click release is the mechanism: it creates the mechanical 0.4.1 PR, and after that PR merges and the next infra update runs, /healthz reports 0.4.1 @ <release-merge commit>.
Feasibility: the current blocker
The live Fledge GitHub App installation has:
checks: read
issues: write
actions: read
contents: write
metadata: read
statuses: write
pull_requests: write
There is no actions: write, so the Fledge server cannot directly call:
POST /repos/HugoXK/fledge/actions/workflows/daily-release.yml/dispatches
The existing release job already works; the missing piece is only the dispatch permission (or an equivalent server-side path).
Options
A. Dedicated dispatch token — recommended
Add a fine-grained PAT RELEASE_DISPATCH_TOKEN on the server only:
- repository access:
HugoXK/fledgeonly; - permission:
Actions: write(plusMetadata: read); - no
Contentswrite, noPull requestswrite; - stored in
/home/xuke/work/fledge/.envor the existing secrets file, mode0600, never in git; - rotated like the other server tokens.
The superadmin route dispatches daily-release.yml with dry_run=false. The workflow keeps using its existing RELEASE_OPEN_TOKEN environment secret for the PR opener, so this new token only starts the run.
Pros: minimum code, reuses the tested release chain, clear audit boundary.
Cons: one more long-lived token to rotate.
B. Server-side release PR using the GitHub App token
The app already has contents: write, pull_requests: write, and checks: read. It could create the branch/commit/PR itself, enable auto-merge, and let the existing tag job publish after merge.
Pros: no new long-lived token; uses the installation identity that already pushes branches.
Cons: must move the release surface/changelog/version logic into the Fledge service or make release-open accept an installation token; GET /user does not work with installation tokens; more T3 code and a second implementation that can drift from daily-release.yml.
C. Add actions: write to the GitHub App
Rejected for now: the App is installed on user repositories, so this would grant workflow dispatch on every installed repository, not just the Fledge repo. That is too broad for a one-click operator feature.
Recommended v1 design
Read-only preview
GET /admin/release (superadmin only, no writes) returns:
- current
mainSHA and age; - latest release tag and target SHA;
- commits/PRs ahead of the tag;
fix/feat/other counts (using the same title rule as the planner);- pending fragment count;
- computed next version;
ci-okconclusion onmain;- open release PR and its head SHA;
release/v<next>branch/tag existence;- whether the action is allowed, and the exact reason if not.
Write action
POST /admin/release:
requireSuperAdmin;- CSRF;
- recent GitHub re-auth, same as the other privileged admin operations;
- rate limit, e.g. one dispatch per 10 minutes;
- one idempotency check: if a release PR is already open, return it instead of dispatching again;
- require a typed confirmation such as
RELEASE 0.4.1; - audit
release.requestedwith actor, main SHA, next version and reason; - dispatch
daily-release.ymlwithdry_run=false; - return the run URL and the eventual PR/release links.
Disabled states
The button is disabled with a named reason when:
ci-okonmainis not success;- a release PR is already open;
v<next>tag already exists;release/v<next>branch exists without a PR (orphan);- there are zero changelog fragments;
mainequals the latest tag;- the actor is not superadmin or the session is not recently re-authenticated.
What the button must never do
- No direct tag creation, direct merge, force-push or admin merge.
- No direct deploy or service restart.
- No bypass of
ci-ok,review-gate,pr-lint, fragment count, tag/PR/branch existence. - No arbitrary version; the version comes from the existing cadence or an explicitly reviewed bump policy.
Force / version bump (v2, optional)
If the owner later wants a release below the 10-PR/5-feature threshold:
- add
forceandreasoninputs todaily-release.yml; - force may bypass only the PR/feature thresholds and the slot boundary;
- force must still require
ci-ok, fragments, no open PR, no tag, no branch and the mechanical diff shape; - check
github.actoragainst an allowlist (the dispatch token owner) and audit the reason; - do not let a force dispatch bypass any merge gate.
If the owner wants a minor bump instead of the cadence patch, add bump: auto|patch|minor; minor requires a second confirmation and an ADR 0008 amendment. Otherwise the current 13-feature backlog would ship as 0.4.1.
Release vs deploy
Keep them separate:
- Release creates the version bump PR, changelog, tag, image, SBOM, attestation and GitHub Release.
- Deploy is the infra
service-update-fledge.sh/tag deploy path. - Production already runs
main; a one-click release does not need to restart it. After the release PR merges, the next daily infra update installs the version-bump commit and/healthzreports0.4.1. - If “release and deploy now” is wanted, make it a second explicit button/confirmation, not an implicit side effect of Release.
Security and audit
- The dispatch token is powerful but repo-scoped; no contents write, no PR write.
- The token is never logged, rendered, put in an argument or committed.
- Superadmin + recent re-auth + CSRF + rate limit + typed confirmation.
- The release workflow's actor allowlist must be set; a repository write user with an Actions-capable token must not be able to use
forceoutside the owner flow. - Audit every request, refusal, dispatch and final release link.
- Rely on security: add the release-tag creation rule to the Fledge repository #879 (tag creation rule) and bug: release slot must use the scheduled slot, not the wall clock #881 (slot/clock correctness) before enabling force or a direct operator release.
Current backlog already qualifies
At the pinned d00ead4, the normal rule is already met:
- 27 PRs ≥ 10;
- 13 PR-title features ≥ 5;
- 25 fragments ≥ 1;
ci-oksuccess;- no open release PR;
- no
v0.4.1tag; - the current 02:00Z slot boundary has passed and
v0.4.0was committed before it.
So a manual dispatch today would plan 0.4.1 without force. The one-click button is operationally useful now; it is not blocked on the threshold rule. It is blocked only on the dispatch permission or the server-side PR alternative.
Implementation plan / acceptance criteria
- Read-only preview endpoint and admin card.
- Shows current main/tag/ahead/fix/feat/fragments/next version/ci-ok/open PR/disabled reason.
- Tests cover the disabled states and the count projection.
- Dispatch token + route.
-
RELEASE_DISPATCH_TOKENis server-only, 0600, not in git. -
POST /admin/releaserequires superadmin + recent auth + CSRF + rate limit. - Audit row and idempotent open-PR reuse.
- Token is never logged or returned.
-
- UI.
- Bilingual card with the preview and a typed confirmation.
- Shows run/PR/release links after dispatch.
- Release does not deploy or restart.
- Workflow.
-
workflow_dispatchwithdry_run=falseproduces the release PR at currentmain. - The existing
ci-ok/review-gate/auto-merge/tag/publish chain is unchanged. - A second click while a release PR is open does not dispatch again.
-
- Docs.
-
docs/deploy.mdand the admin docs describe release vs deploy and the recent-auth requirement. - One changelog fragment for the superadmin feature.
-
Open questions
- Token vs server-side PR: use the dedicated
Actions: writetoken (recommended) or implement the release PR through the GitHub App token? - Version: should the first one-click release ship the 13 PR-title features as
0.4.1(cadence), or should there be aminoroverride to0.5.0? - Should one-click release also deploy immediately, or stay release-only (recommended)?
- Is
forceneeded now, or only after security: add the release-tag creation rule to the Fledge repository #879/bug: release slot must use the scheduled slot, not the wall clock #881 are closed?
Related
- bug: a possible delivery is resent because webhook classification reads error.code, and a transient DNS failure blocks permanently #896 — the live webhook finding (this issue was its duplicate)
- security: add the release-tag creation rule to the Fledge repository #879 — tag creation ruleset
- bug: release slot must use the scheduled slot, not the wall clock #881 — release slot/clock correctness
- ops: verify the release chain after publish and attach the SBOM #883 — publish-side release-chain verification
- fix: list the oldest work items first at equal priority #874 — FIFO work-item read model
- feat: dispatch the next work item immediately after a successful job #801 — dispatch-next-work and the 10x scheduler discussion
- ui: make the review and merge step one legible action #264 — merge serialization / merge queue
Claims-verified-against: d00ead4
Activity
HugoXK commentedon Nov 16, 2026
Written-by: Fledge Platform Product
Body rewritten, back to
needs-review.sha256[:12]=0ad8a30d638e(11,685 B, raw and trimmed identical), pinnedClaims-verified-against: b3d5415aef7621faa395fd36b01af95c2142684d— read fromGET /repos/HugoXK/fledge/commits/mainthis turn (APIDate: Mon, 16 Nov 2026 05:30:27 GMT), not the43550868in my tasking; that sha has since been overtaken by#895(fix: stop starting work on a host whose clock is measurably wrong), and every file this card touches is unchanged by it.Security's finding, conclusion, proposed fix and test list are kept as filed — not one sentence reworded. What changed:
## Expected vs actual: the MEDIUM as an operator experience (the endpoint receives the notification twice while the row records one automatic delivery) and the LOW (a resolver blip silently turns a retryable notification into a lost one, visible only on/admin/notificationsninety days later).## Red first: the two assertions that must fail at this pin before the fix, each failing for the reason named and not for a missing export, plus thenpm test -- --test-name-pattern notificationOutboxline to keep the failure output in the PR.docs/security.md:458-459:509-510#891wrote the firewall section above itdocs/security.md:452-457:504-510:506-507, the audited resend:508-509docs/security.md:436-437, described as the transactional-mail paragraph:436-437is the firewall paragraph; mail is:493-495#847record's citation was wrong, not merely stalesrc/db.ts:5635:5701-5721,WHEREat:5705claimNotificationOutboxEverything else re-resolves at the pin untouched:
src/lib/webhook.ts:165,:167-172,:171,:113-118,:46-50,:76-79,:129-136,:133;src/notifications/outbox.ts:25-26,:88,:96;test/notificationOutbox.test.ts:215-219,:225-236,:230,:241-259.Labels stay
bug,area:security,needs-review; I added noagent-readyand no priority label. This needs a freshIssue-reviewbecause the bytes moved.HugoXK commentedon Nov 16, 2026
Written-by: HugoXK
#896 is the live card; this duplicate is closed as a duplicate of #896. The full finding is preserved in both bodies, and the fix is tracked on #896. Nothing is deleted.
[-]bug: a possible delivery is resent because webhook classification reads error.code, and a transient DNS failure blocks permanently[/-][+]feat: superadmin one-click release for the current main[/+]HugoXK commentedon Nov 16, 2026
Written-by: HugoXK
#897 is repurposed as the superadmin one-click release card. The webhook classification finding remains live on #896; this issue is no longer a duplicate of it, and no security content is lost.
The body now contains the deep analysis: the pinned production/release delta, the current GitHub App permission blocker (
actions: read, notactions: write), the three implementation options, the recommended dedicated dispatch token, the release-vs-deploy boundary, the force/bump guardrails, and the acceptance criteria. The current backlog already meets the normal 10/5/1 release rule, so v1 can dispatch the existing workflow without a force flag.HugoXK commentedon Nov 16, 2026
Written-by: HugoXK
v1 implementation is open as #908:
feat: add a superadmin one-click release action.POST /admin/releaserequires superadmin + CSRF + recent GitHub re-auth + destructive rate limit + audit, and re-reads the preview before dispatch.daily-release.ymlwithdry_run=false; it never tags, merges or deploys.RELEASE_DISPATCH_TOKENis now configured in/home/xuke/work/fledge/.envfrom the existing server bot token so the action works after this code is deployed. Replace it with a repo-scoped fine-grainedActions: writetoken when one is available; the GitHub App still hasactions: readand was not widened.forceor a bump selector; the current 27-PR/13-feature-title/25-fragment backlog already meets the normal rule.