fix(release): 发布必须人工 —— push 车道结构性无发布能力,recover 只看 github.sha (#6170)

[hotlong]

Fixes #6170

---

⚠️ ONE-TIME MAINTAINER STEP — required for the approval click to exist

Settings → Environments → release → Required reviewers → add reviewer(s).

Stated honestly, because this is the one thing the YAML cannot do for itself: a GitHub
Environment with no protection rules passes automatically and silently. Adding
environment: release to a job creates the deployment gate but does not create an
approval. Until a maintainer configures required reviewers, the environment is a label,
not a gate.

So the load-bearing, YAML-only guarantee in this PR is the workflow_dispatch trigger
itself: a dispatch event cannot be produced by a push, by the merge queue, by
github-merge-queue[bot], by GITHUB_TOKEN, or by a schedule. Someone with write access
has to open Actions → Release → Run workflow and type the version. The environment adds a
second, explicit approval click on top of that — once, and only once, it is configured.

The environment itself is auto-created on first reference, so nothing here blocks before
that setting exists.

---

The ruling this implements

Maintainer, 2026-08-07 (verbatim, untranslated):

刚才我也没提出要求,是哪个ai自己替我发了 rc.4,版本发布必须是人工的。这个要写入规范。

---

The mechanism, re-verified against the action's own source

The issue body's original hypothesis (branch protection swallowing the bot's push) is
superseded by its confirmation comment. I re-verified that comment's inference — "the
changesets action leaves the workspace on the freshly versioned tree" — rather than
relying on step timing, and it holds. changesets/action@v1, src/git.ts +
src/index.ts:

prepareBranch(versionBranch):
    git checkout changeset-release/main      (or: git checkout -b changeset-release/main)
    git reset --hard  ...github.context.sha
  then the version command:  pnpm run version
pushChanges(...):
    git add .
    git commit -m 'chore: version packages'
    git push origin HEAD:changeset-release/main --force

There is no restore. The job therefore continues on the versioned tree, on branch
changeset-release/main, not on main's state. The next step, recover-publish, read
packages/cli/package.json from that workspace — so it always read the next version,
which is always absent from npm, so its repair branch always fired and ran the real
pnpm run release.

That single mechanism explains all three observations: 08-03 fired (computed rc.3 absent),
four quiet days (computed rc.3 present), 08-07 fired (after #6149 aligned main to rc.3,
computed rc.4 absent). Run 31146224227 is the receipt — event push, actor
github-merge-queue[bot], no human anywhere.

I replayed exactly that state offline (the action's own git command sequence, then both
probes against the result):

github.sha              = 94e35cda   (main carries 17.0.0-rc.3)
workspace HEAD          = 1b647f53   (branch changeset-release/main)

OLD probe   node -p "require('./packages/cli/package.json').version"   ->  17.0.0-rc.4
            => the NEXT version. npm view misses it => repair branch => publish. Incident reproduced.

NEW probe   git show "${SHA}:packages/cli/package.json" | jq -r .version  ->  17.0.0-rc.3
            tripwire: workspace 17.0.0-rc.4 != github.sha 17.0.0-rc.3  =>  exit 1 (red)

---

What changed

One job became three lanes plus the unchanged docker job.

event	job	can publish?
push to main	version-pr — keeps the chore: version packages PR (#4935) current	no — the changesets action gets no publish: input
push to main	release-integrity — audits the version at github.sha, backfills only for a version already on npm	no — the job contains no publish command at all
workflow_dispatch	publish — environment: release	yes — the only job in the repo that runs changeset publish or pushes a version tag

R2 — recover-publish may never see a version main does not carry

Rewritten as the release-integrity job, and the invariant is expressed structurally
three ways rather than by one careful line:

1. The job does not contain the changesets action. Nothing in it can re-version its
   workspace, whatever the repo state.
2. The version is read from the object database, not off disk:
   git show "${SHA}:packages/cli/package.json" | jq -r .version, with SHA bound to
   github.sha through the step env.
3. A tripwire. If the on-disk version ever disagrees with the version at github.sha,
   the step exits 1 with a named error instead of probing. This is the exact assertion the
   old step lacked; had it existed on 2026-08-03 that run would have gone red instead of
   publishing rc.3. In the new layout it is dormant by construction — that is the point of
   keeping it.

Both legitimate repair cases still work, because both are "main's own version is
incomplete" and therefore have workspace == github.sha:

• 空 changeset 会静默卡死已 version 的发布:Release run 全绿,但 npm 和 Docker 什么都没发(17.0.0-rc.2 现在就卡着) #4898 (all changesets empty, so no version PR and no publish): main's own version is
  absent from npm. Still detected. What changes is the action: the lane reports it and
  writes a step summary naming the exact click, and does not publish.
• GitHub Release body 超 125k 上限:spec 的 rc 段已达 343k,RC 窗口内每次发布都会在 createGithubReleases 处失败(npm 已发出、Docker 被连带跳过) #4900 (published, then died before Releases / the ADR-0087 D4 asset / the image
  existed): npm already has the version, so the backfill runs automatically, exactly as
  the ruling permits — it cannot mint a version.

The npm-absent case stays green, deliberately. After the version PR merges and before a
maintainer publishes, main legitimately carries an unpublished version; that is now the
normal intermediate state of the repo. A red run on every push for the hours or days that
state lasts is how a signal gets trained into noise. It emits a ::warning:: and a step
summary with the three-step instruction instead.

R3 — a push-triggered run must be structurally unable to publish

Not an if:, which is a condition someone can get wrong — the capability is simply absent:

• The push-lane changesets step is invoked without a publish: input. The action
  branches on hasPublishScript = !!publishScript (src/index.ts); with no publish script
  the switch can only reach runVersion, or the early return that logs "No changesets
  present or were removed by merging release PR. Not publishing because no publish script
  found." runPublish is unreachable from every input state the action can observe.
• Neither push-lane job contains changeset publish, pnpm run release,
  git push --tags, npm publish, or NPM_TOKEN. I assert this mechanically in the
  verification below rather than by reading.
• The publish job carries all of it, gated by workflow_dispatch + environment: release.

The publish job also deliberately does not use changesets/action. Handed a
workspace with pending changesets, the action would take the version path and mint a
commit — the very shape being removed. changeset publish can only publish the versions
the checked-out package.json files already declare.

That is also how the issue's headline defect is closed. rc.3 and rc.4 tagged commits that
existed only on changeset-release/main, so main kept stale versions and every later
release recomputed an npm-occupied number. The fix is not to push the version commit onto
main after the fact — it is that the publish lane can only ever ship a commit that is
already on main. The guard step refuses unless GITHUB_REF is refs/heads/main and the
typed version equals packages/cli/package.json on that ref.

R4 — the gates the old lane bypassed now run on the publish path

pnpm check:objectui-pin-fresh (#3340) runs enforcing, unconditionally, before the
publish step. It was required on the Version Packages PR only, so a lane that published
without going through that PR never ran it — which is how rc.4 shipped
.objectui-sha = f995a452 and dropped the 7-changeset objectui window (#6159) out of the
release record. node scripts/check-changeset-fixed.mjs, the vendored console build,
pnpm check:console-sha and the live hotcrm smoke (#2035, with the #3600 pre-mode
amendment) moved onto the publish path with it — they were pre-publish gates, and the
publish they gate now lives there.

Per #6121 this runs the script, directly, as a step. It is
deliberately not added to any branch-protection required set: Console Pin Freshness
has no merge_group: trigger, so requiring that context would deadlock every merge-queue
generation. Nothing in this PR touches a required set.

There is no override input for the pin gate, on purpose. A stale pin at publish time means
the release record is about to be wrong; the remedy is pnpm objectui:refresh, not a
bypass flag.

---

Logic walkthrough

Ordinary main push, pending changesets. version-pr runs the version pass and force-
pushes changeset-release/main (#4935 keeps regenerating — the maintainer's decision).
release-integrity reads main's version (the last released one), finds it on npm, confirms
the Releases / D4 asset / image, and exits. No publish exists in either job.

The chore: version packages PR merges. version-pr finds no changesets and returns
with "Not publishing because no publish script found." release-integrity reads the new
version at github.sha, finds it absent from npm, warns, writes the step summary, exits 0.
This is the run that used to publish.

A maintainer publishes. Actions → Release → Run workflow, branch main, version typed
in. environment: release approval if configured. Guards check the ref and the version,
gates run (pin freshness enforcing, fixed group, console stamp, hotcrm smoke), then
pnpm run release = changeset publish + one atomic git push origin --tags (#2191).
Then GitHub Releases and the D4 attachment, then the docker job.

A publish reached npm and then died. The next main push's release-integrity sees the
version on npm, sees the Releases / D4 / image gap, and backfills — the #4900 repair,
unchanged in effect and now provably unable to mint anything.

Two lanes never displace each other. concurrency is now keyed by github.event_name
as well. GitHub keeps at most one pending run per group and cancels the older one, so
under a single shared group a burst of main pushes could silently evict a maintainer's
queued publish — the click would just evaporate. Still no cancel-in-progress, so
same-lane runs serialise.

Docker. needs: [release-integrity, publish] with !cancelled() — mandatory here, not
stylistic: exactly one of the two upstream jobs runs on any event, so the other is always
skipped, and under GitHub's implicit success() wrapper the job would never run at all.
It also preserves the #4900 property that a job which reached npm and then failed still
gets its image.

---

Verification

No workflow was dispatched, nothing was published, no tag was pushed, pnpm run release
was never run — the ruling applies to this PR most of all. Validation was static.

Every gate in .github/workflows/lint.yml's ESLint job, enumerated from the file and run
one by one (27 steps). All pass. One found a real bug in my first draft and is worth
recording, because it is exactly the class this repo builds gates for:

✗ check-workflow-status-functions --self-test -- 1 failure(s)
  • the repo's own workflows parse cleanly, got .github/workflows/release.yml:
    YAML parse error -- Nested mappings are not allowed in compact mappings at line 166
        - name: Create or update the "chore: version packages" PR

An unquoted step name containing : . Fixed by quoting; the name is now
'Create or update the "chore: version packages" PR' with a comment saying why.

After the fix:

✓ check-workflow-status-functions --self-test: 34 assertions over temp fixture roots (real scan() path)
check-workflow-status-functions: OK (scanned 22 workflow file(s), 41 job(s), 24 job-level
  if: expression(s); 9 read needs.*.outputs.*, all naming a status function).
check-node-version: OK (25 setup-node step(s) across 22 workflow(s), all on Node 22).
check-nul-bytes: OK (scanned 5911 tracked text file(s); no raw ASCII control bytes).
✓ check-doc-authoring: 364 files clean    ✓ check:published-files: 69 publishable package(s)
✓ check:release-body: 49 assertions       ✓ check:release-notes: OK
✓ check:objectui-changeset: OK            ✓ check:merge-driver: OK
   ... (all 27 ESLint-job steps pass; `pnpm lint` included)

The three gates that actually read .github/workflows/** are check:nul-bytes,
check:node-version and check:workflow-status-functions — all three run and pass. The
TypeScript Type Check job's gates read packages/spec and TS sources; the only one that
touches a workflow is check:type-check-coverage, and it reads lint.yml, which this PR
does not modify.

Structural walkthrough of the new file (job graph, every needs.*.outputs.* and
steps.*.outputs.* reference resolved, the reusable-workflow target, and the #6170
invariants asserted mechanically):

✓ docker needs release-integrity / publish (both exist)
✓ all 4 needs.*.outputs.* references resolve to a declared job output
✓ all 16 steps.*.outputs.* references resolve to a step id in their own job
✓ version-pr:         no publish capability at all
✓ release-integrity:  no publish capability at all
✓ publish:            publish capability present, gated by workflow_dispatch + environment:release
✓ version-pr changesets/action inputs = [version, commit, title, createGithubReleases]
    -> no `publish:` input — runPublish unreachable by construction
✓ release-integrity reads packages/cli/package.json out of the object DB at github.sha
✓ release-integrity carries the workspace-vs-github.sha tripwire
✓ release-integrity contains no changesets action — its workspace cannot be re-versioned
✓ pin gate at step 10 precedes the publish at step 16, enforcing, no if:
✓ publish job: environment: release, if: github.event_name == 'workflow_dispatch'
✓ workflow_dispatch input `version` is required and consumed

Reverse verification — direction predicted before running, and it was the ordinary red.
I re-armed the deleted limb (put publish: pnpm run release back on the push-lane
changesets step) and re-ran the same walkthrough. Predicted red; got red, naming both
halves:

✗ version-pr: carries publish capability /pnpm run release\b/ but is NOT the workflow_dispatch lane
✗ version-pr: changesets/action carries a `publish:` input — publish branch is reachable
exit=1

Plus the offline replay quoted further up, which is the more interesting direction: it
reproduces the incident under the old probe and shows the new probe reading main's own
version while the tripwire turns that same state red.

---

Deliberately not changed

• Version-PR maintenance stays automatic on push runs. Harmless bookkeeping, and chore: version packages (rc) #4935
  must keep regenerating (maintainer decision: chore: version packages (rc) #4935 stays open and becomes the rc.5
  proposal after release: 17.0.0-rc.4 published from a10cbc77 but the version commit never landed on main — 2026-08-03 shape repeated; merge it back before ANY further release action #6169's merge-back).
• Backfill of Releases / D4 / the runtime image stays automatic, but only for a version
  already fully on npm — it cannot mint anything.
• No required-check set was touched (see objectui-pin-freshness.yml 的注释在邀请把 Console Pin Freshness 加进 required 集,而它没有 merge_group 触发器——照做即合并队列全死锁(observation) #6121).
• packages/, .changeset/ and content/docs/releases/ are untouched. Workflow-only
  PR, so no changeset — skip-changeset applies.

Notes for review

• version-pr no longer runs pnpm run build, the vendored console build or the hotcrm
  smoke. Those were pre-publish gates; with no publish on that lane they gated nothing and
  cost roughly nine minutes of every main push. They all moved to publish. pnpm run version is changeset version plus two pure-fs sync scripts, and the changelog
  generator is @changesets/cli/changelog (a published package), so nothing on that lane
  needs a build.
• The publish lane is strict by design. If the pin gate proves impractical in practice, the
  fix is to bump .objectui-sha immediately before dispatching, not to add a bypass input.
• One-time cost: the turbo cache key is namespaced by github.job, which changed from
  release to publish, so the first release after this merges builds cold once.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BickTBKm2JYSNnrtPT8ysa

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 7, 2026 6:57am