Skip to content

feat: superadmin one-click release for the current main #897

Open

Description

@HugoXK

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:

  1. read the current main, latest release tag, pending fragments, ci-ok, and any open release PR;
  2. compute the next version from the existing cadence;
  3. ask for one explicit confirmation;
  4. dispatch the existing daily-release.yml workflow (or create the same mechanical release PR through the GitHub App);
  5. let the existing release PR → ci-ok/review-gate → auto-merge → tag → release.yml chain 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 d00ead4 at 07:25Z; ci-ok on d00ead4 is success.
  • Latest release tag: v0.4.0, target 7a5fdf4.
  • 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
  • PR-title classification (what release-plan.mjs reads):
    • 8 fix
    • 13 feat
    • 2 ui
    • 1 security
    • 1 ops
    • 1 docs
    • 1 ci
  • 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.sh updates source from origin/main, builds and restarts (daily);
  • fledge-deploy-tag.sh deploys a newer tag only when the tag version is ahead of the running package version;
  • fledge-verify-release.sh records 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/fledge only;
  • permission: Actions: write (plus Metadata: read);
  • no Contents write, no Pull requests write;
  • stored in /home/xuke/work/fledge/.env or the existing secrets file, mode 0600, 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 main SHA 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-ok conclusion on main;
  • 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.requested with actor, main SHA, next version and reason;
  • dispatch daily-release.yml with dry_run=false;
  • return the run URL and the eventual PR/release links.

Disabled states

The button is disabled with a named reason when:

  • ci-ok on main is 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;
  • main equals 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 force and reason inputs to daily-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.actor against 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 /healthz reports 0.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

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-ok success;
  • no open release PR;
  • no v0.4.1 tag;
  • the current 02:00Z slot boundary has passed and v0.4.0 was 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

  1. 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.
  2. Dispatch token + route.
    • RELEASE_DISPATCH_TOKEN is server-only, 0600, not in git.
    • POST /admin/release requires superadmin + recent auth + CSRF + rate limit.
    • Audit row and idempotent open-PR reuse.
    • Token is never logged or returned.
  3. UI.
    • Bilingual card with the preview and a typed confirmation.
    • Shows run/PR/release links after dispatch.
    • Release does not deploy or restart.
  4. Workflow.
    • workflow_dispatch with dry_run=false produces the release PR at current main.
    • 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.
  5. Docs.
    • docs/deploy.md and the admin docs describe release vs deploy and the recent-auth requirement.
    • One changelog fragment for the superadmin feature.

Open questions

  1. Token vs server-side PR: use the dedicated Actions: write token (recommended) or implement the release PR through the GitHub App token?
  2. Version: should the first one-click release ship the 13 PR-title features as 0.4.1 (cadence), or should there be a minor override to 0.5.0?
  3. Should one-click release also deploy immediately, or stay release-only (recommended)?
  4. Is force needed 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

Claims-verified-against: d00ead4

Activity

  1. added
    bugSomething isn't working
    area:securitySecrets, authz, data exposure
    needs-reviewWaiting for the Fledge Platform Reviewer's issue review
    on Nov 16, 2026
  2. HugoXK commented on Nov 16, 2026

    @HugoXK
    OwnerAuthor

    Written-by: Fledge Platform Product

    Body rewritten, back to needs-review. sha256[:12] = 0ad8a30d638e (11,685 B, raw and trimmed identical), pinned Claims-verified-against: b3d5415aef7621faa395fd36b01af95c2142684d — read from GET /repos/HugoXK/fledge/commits/main this turn (API Date: Mon, 16 Nov 2026 05:30:27 GMT), not the 43550868 in 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:

    • Added ## 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/notifications ninety days later).
    • Added ## 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 the npm test -- --test-name-pattern notificationOutbox line to keep the failure output in the PR.
    • Corrected four dead anchors, tabulated in the body. This is the only substantive edit and it is a number-only edit:
    as filed at the pin note
    docs/security.md:458-459 :509-510 #891 wrote the firewall section above it
    docs/security.md:452-457 :504-510 retention is :506-507, the audited resend :508-509
    docs/security.md:436-437, described as the transactional-mail paragraph :436-437 is the firewall paragraph; mail is :493-495 the #847 record's citation was wrong, not merely stale
    src/db.ts:5635 :5701-5721, WHERE at :5705 claimNotificationOutbox

    Everything 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 no agent-ready and no priority label. This needs a fresh Issue-review because the bytes moved.

  3. HugoXK commented on Nov 16, 2026

    @HugoXK
    OwnerAuthor

    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.

  4. reopened this on Nov 16, 2026
  5. changed the title [-]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[/+] on Nov 16, 2026
  6. added
    area:deployDeploy, backup, logs, systemd
    area:uiViews, CSS, accessibility, i18n
    priority:ownerOwner-planned task; prioritize ahead of the Product backlog
    priority:highHigh priority; claim before normal backlog
    needs-humanNeeds an owner or operator decision/action
    and removed
    bugSomething isn't working
    area:securitySecrets, authz, data exposure
    needs-reviewWaiting for the Fledge Platform Reviewer's issue review
    on Nov 16, 2026
  7. HugoXK commented on Nov 16, 2026

    @HugoXK
    OwnerAuthor

    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, not actions: 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.

  8. HugoXK commented on Nov 16, 2026

    @HugoXK
    OwnerAuthor

    Written-by: HugoXK

    v1 implementation is open as #908: feat: add a superadmin one-click release action.

    • It previews the live main/tag/ahead/fix/feat/fragments/next version/ci-ok/open PR/tag/branch state.
    • POST /admin/release requires superadmin + CSRF + recent GitHub re-auth + destructive rate limit + audit, and re-reads the preview before dispatch.
    • It only dispatches the existing daily-release.yml with dry_run=false; it never tags, merges or deploys.
    • RELEASE_DISPATCH_TOKEN is now configured in /home/xuke/work/fledge/.env from the existing server bot token so the action works after this code is deployed. Replace it with a repo-scoped fine-grained Actions: write token when one is available; the GitHub App still has actions: read and was not widened.
    • v1 does not add force or a bump selector; the current 27-PR/13-feature-title/25-fragment backlog already meets the normal rule.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:deployDeploy, backup, logs, systemdarea:uiViews, CSS, accessibility, i18nenhancementNew feature or requestneeds-humanNeeds an owner or operator decision/actionpriority:highHigh priority; claim before normal backlogpriority:ownerOwner-planned task; prioritize ahead of the Product backlog

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions