ci: add npm release workflow and CalVer checks by onutc · Pull Request #42414 · openclaw/openclaw

onutc · 2026-03-10T17:50:48Z

Summary

Problem: npm release steps were documented but not automated in GitHub Actions, and release-version validation depended on operators inferring current CalVer rules from docs and tag history.
Why it matters: tag-driven npm publishing reduces operator error, keeps stable vs beta tagging consistent, and blocks releases with mismatched or stale CalVer versions.
What changed: added a tag-triggered npm release workflow modeled on ~/offline/acpx, added a dedicated release-publish validation script plus tests, and updated the release checklist to document the automated publish path and the enforced versioning rules.
What did NOT change (scope boundary): Docker release workflow, GitHub release asset upload, macOS app packaging, and appcast publishing remain separate.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #
Related #

User-visible / Behavior Changes

Pushing a matching vYYYY.M.D or vYYYY.M.D-beta.N tag now triggers npm publishing from GitHub Actions.
Beta versions publish with the npm beta dist-tag; stable versions publish with the default latest path.
Release tags now fail validation if they do not match package.json, are not on main, or if the CalVer date is more than 2 UTC calendar days away from the actual release date.

Security Impact (required)

New permissions/capabilities? Yes
Secrets/tokens handling changed? No
New/changed network calls? Yes
Command/tool execution surface changed? No
Data access scope changed? No
If any Yes, explain risk + mitigation:
The workflow adds npm trusted publishing from GitHub Actions using id-token: write on the release job. Risk is limited to tag-triggered publishes, and the workflow gates publication on package metadata validation, exact tag/version match, main ancestry, unpublished-version checks, and the CalVer date window.

Repro + Verification

Environment

OS: macOS
Runtime/container: Node 22 / pnpm
Model/provider: N/A
Integration/channel (if any): GitHub Actions + npm publish path
Relevant config (redacted): current package version 2026.3.9

Steps

Inspect .github/workflows/release.yml.
Inspect scripts/release-publish-check.ts and test/release-publish-check.test.ts.
Run the targeted release checks locally.

Expected

Tag pushes matching current OpenClaw stable/beta CalVer formats publish to npm automatically.
Invalid tag formats, version mismatches, non-main tags, duplicate npm versions, and stale CalVer dates are rejected before publish.
Release docs describe the automated path instead of a manual npm publish happy path.

Actual

The workflow, validation script, tests, and docs now implement that behavior.

Evidence

Attach at least one:

Failing test/log before + passing after
Trace/log snippets
Screenshot/recording
Perf numbers (if relevant)

Evidence:

pnpm exec vitest run test/release-publish-check.test.ts
RELEASE_TAG=v2026.3.9 RELEASE_SHA=$(git rev-parse origin/main) RELEASE_MAIN_REF=origin/main pnpm release:publish:check
pnpm check

Human Verification (required)

What you personally verified (not just CI), and how:

Verified scenarios: the new CalVer parser accepts current stable/beta formats, rejects legacy tag formats, and enforces the 2-day UTC window; the release workflow publishes stable vs beta with the expected npm tag behavior.
Edge cases checked: zero-padded or legacy versions, invalid calendar dates, duplicate exact-version publish checks, and tags that do not match package.json or main ancestry.
What you did not verify: I did not run an actual npm publish or a full GitHub Actions release end-to-end.

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

Backward compatible? Yes
Config/env changes? No
Migration needed? No
If yes, exact upgrade steps:

Failure Recovery (if this breaks)

How to disable/revert this change quickly: revert the release workflow and the release-publish check script, or stop using tag-triggered npm publishes until fixed.
Files/config to restore: .github/workflows/release.yml, scripts/release-publish-check.ts, package.json, docs/reference/RELEASING.md
Known bad symptoms reviewers should watch for: valid release tags failing preflight unexpectedly, or npm publish triggering on an unsupported tag format.

Risks and Mitigations

Risk: the CalVer date window could reject a legitimate delayed release.
- Mitigation: the rule is explicit in docs and allows a 2-day UTC window rather than requiring same-day release.
Risk: trusted publishing could publish the wrong channel.
- Mitigation: the workflow derives beta vs latest directly from the validated version string and blocks legacy tag formats.

greptile-apps · 2026-03-10T17:52:54Z

Greptile Summary

This PR adds a ## Versioning section to docs/reference/RELEASING.md that explicitly documents the repo's CalVer release conventions (YYYY.M.D stable / YYYY.M.D-beta.N beta), npm dist-tag semantics, the no-zero-padding rule, and a historical note distinguishing legacy tag patterns from current guidance. No scripts, workflows, or runtime behavior are changed.

The new section is internally consistent with the rest of the document: the --tag beta publish step, the openclaw X.Y.Z GitHub release title convention, and the historical 2.0.0-beta2 troubleshooting heading all align with what the new section describes.
The beta.N counter semantics (i.e., when to increment N for multiple betas cut on the same calendar day) are implied by the placeholder but not explicitly stated — a minor gap, but unlikely to cause operator confusion in practice.
Overall this is a clean, well-scoped documentation improvement with no risk to release operations.

Confidence Score: 5/5

Docs-only change with no impact on release scripts, workflows, or runtime behavior — safe to merge.
The PR touches a single Markdown file and adds only explanatory text. All documented conventions are consistent with the existing checklist steps and examples already present in the file. No code, configuration, or automation is modified.
No files require special attention.

_{Last reviewed commit: efdf1cd}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0ca656c4e8

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

.github/workflows/release.yml

onutc · 2026-03-10T19:10:12Z

Landed via temp rebase onto main.

Gate: pnpm lint, pnpm build (with XDG_CACHE_HOME=/tmp/pnpm-cache on this machine so pnpm dlx could write its cache), and pnpm test
Source branch tip: 849c367
Merge commit: 8ba1b6e

Thanks @onutc!

@onutc

@onutc)

@onutc

@onutc)

@onutc

@onutc)

@onutc

@onutc)

@onutc

@onutc)

@onutc

@onutc)

@onutc

@onutc)

@onutc

@onutc)

@onutc

@onutc)

@onutc

@onutc) (cherry picked from commit 8ba1b6e)

@onutc

* fix(ci): stop serializing push workflow runs (cherry picked from commit 0a20c5c) * test: harden path resolution test helpers (cherry picked from commit 1ad47b8) * Fix launcher startup regressions (openclaw#48501) * Fix launcher startup regressions * Fix CI follow-up regressions * Fix review follow-ups * Fix workflow audit shell inputs * Handle require resolve gaxios misses (cherry picked from commit 313e5bb) * refactor(scripts): move container setup entrypoints (cherry picked from commit 46ccbac) * perf(ci): gate install smoke on changed-smoke (openclaw#52458) (cherry picked from commit 4bd90f2) * Docs: prototype generated plugin SDK reference (openclaw#51877) * Chore: unblock synced main checks * Docs: add plugin SDK docs implementation plan * Docs: scaffold plugin SDK reference phase 1 * Docs: mark plugin SDK reference surfaces unstable * Docs: prototype generated plugin SDK reference * docs(plugin-sdk): replace generated reference with api baseline * docs(plugin-sdk): drop generated reference plan * docs(plugin-sdk): align api baseline flow with config docs --------- Co-authored-by: Onur <[email protected]> Co-authored-by: Vincent Koc <[email protected]> (cherry picked from commit 4f1e12a) * fix(ci): harden docker builds and unblock config docs (cherry picked from commit 9f08af1) * Docs: add config drift baseline statefile (openclaw#45891) * Docs: add config drift statefile generator * Docs: generate config drift baseline * CI: move config docs drift runner into workflow sanity * Docs: emit config drift baseline json * Docs: commit config drift baseline json * Docs: wire config baseline into release checks * Config: fix baseline drift walker coverage * Docs: regenerate config drift baselines (cherry picked from commit cbec476) * Release: add plugin npm publish workflow (openclaw#47678) * Release: add plugin npm publish workflow * Release: make plugin publish scope explicit (cherry picked from commit d41c9ad) * build: default to Node 24 and keep Node 22 compat (cherry picked from commit deada7e) * ci(android): use explicit flavor debug tasks (cherry picked from commit 0c2e6fe) * ci: harden pnpm sticky cache on PRs (cherry picked from commit 29b36f8) * CI: add built plugin singleton smoke (openclaw#48710) (cherry picked from commit 5a2a4ab) * chore: add code owners for npm release paths (cherry picked from commit 5c9fae5) * test add extension plugin sdk boundary guards (cherry picked from commit 77fb258) * ci: tighten cache docs and node22 gate (cherry picked from commit 797b6fe) * ci: add npm release workflow and CalVer checks (openclaw#42414) (thanks @onutc) (cherry picked from commit 8ba1b6e) * CI: add CLI startup memory regression check (cherry picked from commit c0e0115) * Add bad-barnacle label to prevent barnacle closures. (openclaw#51945) (cherry picked from commit c449a0a) * ci: speed up scoped workflow lanes (cherry picked from commit d17490f) * ci: restore PR pnpm cache fallback (cherry picked from commit e1d0545) * CI: guard gateway watch against duplicate runtime regressions (openclaw#49048) (cherry picked from commit f036ed2) * fix: correct domain reference in docker setup script * fix: adapt cherry-picks for fork TS strictness * fix: adapt cherry-picked tests for fork structure - Dockerfile test: OPENCLAW_ → REMOTECLAW_ ARG names - ci-changed-scope test: add missing runChangedSmoke field - doc-baseline test: rename to e2e (needs dist/ build artifacts) - extension boundary test: update baselines and expectations for fork * fix: adjust ci-changed-scope test for fork's narrower skills regex --------- Co-authored-by: Vincent Koc <[email protected]> Co-authored-by: Peter Steinberger <[email protected]> Co-authored-by: Tak Hoffman <[email protected]> Co-authored-by: Bob <[email protected]> Co-authored-by: Onur <[email protected]> Co-authored-by: Altay <[email protected]> Co-authored-by: Ayaan Zaidi <[email protected]> Co-authored-by: Onur Solmaz <[email protected]> Co-authored-by: Harold Hunt <[email protected]>

openclaw-barnacle bot added docs Improvements or additions to documentation size: XS maintainer Maintainer-authored PR labels Mar 10, 2026

openclaw-barnacle bot added scripts Repository scripts and removed size: XS labels Mar 10, 2026

onutc changed the title ~~docs: clarify release versioning conventions~~ ci: add npm release workflow and CalVer checks Mar 10, 2026

openclaw-barnacle bot added the size: M label Mar 10, 2026

chatgpt-codex-connector bot reviewed Mar 10, 2026

View reviewed changes

.github/workflows/release.yml Outdated Show resolved Hide resolved

onutc self-assigned this Mar 10, 2026

onutc added 7 commits March 10, 2026 20:02

docs: clarify release versioning conventions

bad2f21

ci: add npm release workflow and CalVer checks

2c50b4a

ci: fetch full main history for release ancestry checks

10471ba

ci: rename openclaw npm release workflow

1fb2743

ci: remove old npm release workflow path

34d404a

ci: scope npm release naming to openclaw

0ace301

ci: remove old npm release check paths

849c367

onutc force-pushed the docs-release-versioning-conventions branch from 1ebee78 to 849c367 Compare March 10, 2026 19:09

onutc merged commit 8ba1b6e into openclaw:main Mar 10, 2026
9 checks passed

github-actions bot mentioned this pull request Mar 10, 2026

📡 Upstream Digest — 2026-03-10 20:25 UTC curtismercier/openclaw-mods#229

Open

frankekn pushed a commit to MoerAI/openclaw that referenced this pull request Mar 11, 2026

ci: add npm release workflow and CalVer checks (openclaw#42414) (thanks

038fc05

@onutc)

frankekn pushed a commit to Effet/openclaw that referenced this pull request Mar 11, 2026

ci: add npm release workflow and CalVer checks (openclaw#42414) (thanks

90d18e5

@onutc)

frankekn pushed a commit to ImLukeF/openclaw that referenced this pull request Mar 11, 2026

ci: add npm release workflow and CalVer checks (openclaw#42414) (thanks

c891b2a

@onutc)

Treedy2020 pushed a commit to Treedy2020/openclaw that referenced this pull request Mar 11, 2026

ci: add npm release workflow and CalVer checks (openclaw#42414) (thanks

8a51043

@onutc)

dhoman pushed a commit to dhoman/chrono-claw that referenced this pull request Mar 11, 2026

ci: add npm release workflow and CalVer checks (openclaw#42414) (thanks

e8248a9

@onutc)

ahelpercn pushed a commit to ahelpercn/openclaw that referenced this pull request Mar 12, 2026

ci: add npm release workflow and CalVer checks (openclaw#42414) (thanks

98f13dd

@onutc)

Ruijie-Ysp pushed a commit to Ruijie-Ysp/clawdbot that referenced this pull request Mar 12, 2026

ci: add npm release workflow and CalVer checks (openclaw#42414) (thanks

77fd7a7

@onutc)

github-actions bot mentioned this pull request Mar 12, 2026

上游更新: v2026.3.11 — 14 P0 + 32 P1 待合并 jiulingyun/openclaw-cn#499

Open

leozhengliu-pixel pushed a commit to leozhengliu-pixel/openclaw that referenced this pull request Mar 13, 2026

ci: add npm release workflow and CalVer checks (openclaw#42414) (thanks

e5de02b

@onutc)

senw-developers pushed a commit to senw-developers/va-openclaw that referenced this pull request Mar 17, 2026

ci: add npm release workflow and CalVer checks (openclaw#42414) (thanks

0d4b3ed

@onutc)

alexey-pelykh mentioned this pull request Mar 23, 2026

Cherry-pick: CI/workflow improvements (46 commits) remoteclaw/remoteclaw#1905

Closed

alexey-pelykh pushed a commit to remoteclaw/remoteclaw that referenced this pull request Mar 25, 2026

ci: add npm release workflow and CalVer checks (openclaw#42414) (thanks

3d5475b

@onutc) (cherry picked from commit 8ba1b6e)

alexey-pelykh mentioned this pull request Mar 25, 2026

Cherry-pick batch: CI/workflow improvements (46 commits) remoteclaw/remoteclaw#1997

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

ci: add npm release workflow and CalVer checks#42414

ci: add npm release workflow and CalVer checks#42414
onutc merged 7 commits intoopenclaw:mainfrom
onutc:docs-release-versioning-conventions

onutc commented Mar 10, 2026 •

edited

Loading

Uh oh!

greptile-apps bot commented Mar 10, 2026

Uh oh!

chatgpt-codex-connector bot left a comment

Uh oh!

Uh oh!

Uh oh!

onutc commented Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

onutc commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

User-visible / Behavior Changes

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Failure Recovery (if this breaks)

Risks and Mitigations

Uh oh!

greptile-apps bot commented Mar 10, 2026

Greptile Summary

Confidence Score: 5/5

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

onutc commented Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

onutc commented Mar 10, 2026 •

edited

Loading