From d8326f2f70824d449fd1764d6306ab83c8165056 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 2 May 2026 07:36:14 +0100 Subject: [PATCH] docs: document release publish orchestration --- docs/ci.md | 8 ++++ docs/reference/RELEASING.md | 74 ++++++++++++++++++++++++++++++++++++- 2 files changed, 80 insertions(+), 2 deletions(-) diff --git a/docs/ci.md b/docs/ci.md index 8b7ec9b17f2..95cea47f0f7 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -141,6 +141,14 @@ dispatches `Plugin NPM Release` for all publishable plugin packages, dispatches `Plugin ClawHub Release` for the same release SHA, and only then dispatches `OpenClaw NPM Release` with the saved `preflight_run_id`. +```bash +gh workflow run openclaw-release-publish.yml \ + --ref release/YYYY.M.D \ + -f tag=vYYYY.M.D-beta.N \ + -f preflight_run_id= \ + -f npm_dist_tag=beta +``` + For pinned commit proof on a fast-moving branch, use the helper instead of `gh workflow run ... --ref main -f ref=`: diff --git a/docs/reference/RELEASING.md b/docs/reference/RELEASING.md index 8e681d9fea9..953c171e168 100644 --- a/docs/reference/RELEASING.md +++ b/docs/reference/RELEASING.md @@ -103,6 +103,12 @@ the maintainer-only release runbook. - Run `pnpm build && pnpm ui:build` before `pnpm release:check` so the expected `dist/*` release artifacts and Control UI bundle exist for the pack validation step +- Run `pnpm plugins:sync` after the root version bump and before tagging. It + updates publishable plugin package versions, OpenClaw peer/API compatibility + metadata, build metadata, and plugin changelog stubs to match the core + release version. `pnpm plugins:sync:check` is the non-mutating release guard; + the publish workflow fails before any registry mutation if this step was + forgotten. - Run the manual `Full Release Validation` workflow before release approval to kick off all pre-release test boxes from one entrypoint. It accepts a branch, tag, or full commit SHA, dispatches manual `CI`, and dispatches @@ -518,6 +524,56 @@ For package-candidate Telegram proof, enable `telegram_mode=mock-openai` or resolved `package-under-test` tarball into the Telegram lane; the standalone Telegram workflow still accepts a published npm spec for post-publish checks. +## Release publish automation + +`OpenClaw Release Publish` is the normal mutating publish entrypoint. It +orchestrates the trusted-publisher workflows in the order the release needs: + +1. Check out the release tag and resolve its commit SHA. +2. Verify the tag is reachable from `main` or `release/*`. +3. Run `pnpm plugins:sync:check`. +4. Dispatch `Plugin NPM Release` with `publish_scope=all-publishable` and + `ref=`. +5. Dispatch `Plugin ClawHub Release` with the same scope and SHA. +6. Dispatch `OpenClaw NPM Release` with the release tag, npm dist-tag, and + saved `preflight_run_id`. + +Beta publish example: + +```bash +gh workflow run openclaw-release-publish.yml \ + --ref release/YYYY.M.D \ + -f tag=vYYYY.M.D-beta.N \ + -f preflight_run_id= \ + -f npm_dist_tag=beta +``` + +Stable publish to the default beta dist-tag: + +```bash +gh workflow run openclaw-release-publish.yml \ + --ref release/YYYY.M.D \ + -f tag=vYYYY.M.D \ + -f preflight_run_id= \ + -f npm_dist_tag=beta +``` + +Stable promotion directly to `latest` is explicit: + +```bash +gh workflow run openclaw-release-publish.yml \ + --ref release/YYYY.M.D \ + -f tag=vYYYY.M.D \ + -f preflight_run_id= \ + -f npm_dist_tag=latest +``` + +Use the lower-level `Plugin NPM Release` and `Plugin ClawHub Release` workflows +only for focused repair or republish work. For a selected plugin repair, pass +`plugin_publish_scope=selected` and `plugins=@openclaw/name` to +`OpenClaw Release Publish`, or dispatch the child workflow directly when the +OpenClaw package must not be published. + ## NPM workflow inputs `OpenClaw NPM Release` accepts these operator-controlled inputs: @@ -531,6 +587,19 @@ Telegram workflow still accepts a published npm spec for post-publish checks. the prepared tarball from the successful preflight run - `npm_dist_tag`: npm target tag for the publish path; defaults to `beta` +`OpenClaw Release Publish` accepts these operator-controlled inputs: + +- `tag`: required release tag; must already exist +- `preflight_run_id`: successful `OpenClaw NPM Release` preflight run id; + required when `publish_openclaw_npm=true` +- `npm_dist_tag`: npm target tag for the OpenClaw package +- `plugin_publish_scope`: defaults to `all-publishable`; use `selected` only + for focused repair work +- `plugins`: comma-separated `@openclaw/*` package names when + `plugin_publish_scope=selected` +- `publish_openclaw_npm`: defaults to `true`; set `false` only when using the + workflow as a plugin-only repair orchestrator + `OpenClaw Release Checks` accepts these operator-controlled inputs: - `ref`: branch, tag, or full commit SHA to validate. Secret-bearing checks @@ -563,8 +632,9 @@ When cutting a stable npm release: 4. If you intentionally only need the deterministic normal test graph, run the manual `CI` workflow on the release ref instead 5. Save the successful `preflight_run_id` -6. Run `OpenClaw NPM Release` again with `preflight_only=false`, the same - `tag`, the same `npm_dist_tag`, and the saved `preflight_run_id` +6. Run `OpenClaw Release Publish` with the same `tag`, the same `npm_dist_tag`, + and the saved `preflight_run_id`; it publishes externalized plugins to npm + and ClawHub before promoting the OpenClaw npm package 7. If the release landed on `beta`, use the private `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` workflow to promote that stable version from `beta` to `latest`