Skip to content

Commit cdcdb4b

Browse files
author
Onur
authored
Release: separate release checks workflow (openclaw#65552)
* Release: separate live cache validation * Docs: restore live validation secret details * Release: rename live validation to release checks * Release: document release check split rationale * Release: tone down workflow warning * Release: require full sha for release checks * CI: use larger runners for release checks * CI: keep release promotion on github runner * CI: document github-hosted release jobs * Release: allow sha validation-only preflight
1 parent f5447aa commit cdcdb4b

3 files changed

Lines changed: 203 additions & 45 deletions

File tree

‎.github/workflows/openclaw-npm-release.yml‎

Lines changed: 42 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ on:
44
workflow_dispatch:
55
inputs:
66
tag:
7-
description: Release tag to publish (for example v2026.3.22, v2026.3.22-beta.1, or fallback v2026.3.22-1)
7+
description: Release tag to publish, or a full 40-character main commit SHA for validation-only preflight (for example v2026.3.22 or 0123456789abcdef0123456789abcdef01234567)
88
required: true
99
type: string
1010
preflight_only:
@@ -40,23 +40,31 @@ env:
4040
PNPM_VERSION: "10.32.1"
4141

4242
jobs:
43+
# PLEASE DON'T ADD LONG-RUNNING OR FLAKY CHECKS TO THE npm RELEASE PATH.
44+
# KEEP THIS WORKFLOW SHORT AND DETERMINISTIC OR IT CAN GET STUCK AND JEOPARDIZE THE RELEASE.
45+
# RELEASE-TIME LIVE OR END-TO-END VALIDATION BELONGS IN openclaw-release-checks.yml.
4346
preflight_openclaw_npm:
4447
if: ${{ inputs.preflight_only && !inputs.promote_beta_to_latest }}
45-
runs-on: ubuntu-latest
48+
runs-on: blacksmith-16vcpu-ubuntu-2404
4649
permissions:
4750
contents: read
4851
steps:
49-
- name: Validate tag input format
52+
- name: Validate release ref input format
5053
env:
51-
RELEASE_TAG: ${{ inputs.tag }}
54+
RELEASE_REF: ${{ inputs.tag }}
55+
PREFLIGHT_ONLY: ${{ inputs.preflight_only }}
5256
RELEASE_NPM_DIST_TAG: ${{ inputs.npm_dist_tag }}
5357
run: |
5458
set -euo pipefail
55-
if [[ ! "${RELEASE_TAG}" =~ ^v[0-9]{4}\.[1-9][0-9]*\.[1-9][0-9]*((-beta\.[1-9][0-9]*)|(-[1-9][0-9]*))?$ ]]; then
56-
echo "Invalid release tag format: ${RELEASE_TAG}"
59+
if [[ ! "${RELEASE_REF}" =~ ^v[0-9]{4}\.[1-9][0-9]*\.[1-9][0-9]*((-beta\.[1-9][0-9]*)|(-[1-9][0-9]*))?$ ]] && [[ ! "${RELEASE_REF}" =~ ^[0-9a-fA-F]{40}$ ]]; then
60+
echo "Invalid release ref format: ${RELEASE_REF}"
5761
exit 1
5862
fi
59-
if [[ "${RELEASE_TAG}" == *"-beta."* && "${RELEASE_NPM_DIST_TAG}" != "beta" ]]; then
63+
if [[ "${RELEASE_REF}" =~ ^[0-9a-fA-F]{40}$ ]] && [[ "${PREFLIGHT_ONLY}" != "true" ]]; then
64+
echo "Full commit SHA input is only supported for validation-only preflight runs."
65+
exit 1
66+
fi
67+
if [[ "${RELEASE_REF}" == *"-beta."* && "${RELEASE_NPM_DIST_TAG}" != "beta" ]]; then
6068
echo "Beta prerelease tags must publish to npm dist-tag beta."
6169
exit 1
6270
fi
@@ -70,7 +78,7 @@ jobs:
7078
- name: Checkout
7179
uses: actions/checkout@v6
7280
with:
73-
ref: refs/tags/${{ inputs.tag }}
81+
ref: ${{ inputs.tag }}
7482
fetch-depth: 0
7583

7684
- name: Setup Node environment
@@ -110,50 +118,42 @@ jobs:
110118
- name: Build Control UI
111119
run: pnpm ui:build
112120

113-
- name: Validate release tag and package metadata
121+
- name: Validate release metadata
114122
if: ${{ inputs.preflight_run_id == '' }}
115123
env:
116124
OPENCLAW_NPM_RELEASE_SKIP_PACK_CHECK: "1"
117-
RELEASE_TAG: ${{ inputs.tag }}
125+
RELEASE_REF: ${{ inputs.tag }}
126+
PREFLIGHT_ONLY: ${{ inputs.preflight_only }}
118127
RELEASE_MAIN_REF: origin/main
119128
OPENCLAW_NPM_PUBLISH_TAG: ${{ inputs.npm_dist_tag }}
120129
run: |
121130
set -euo pipefail
122131
RELEASE_SHA=$(git rev-parse HEAD)
123-
export RELEASE_SHA RELEASE_TAG RELEASE_MAIN_REF
132+
export RELEASE_SHA RELEASE_MAIN_REF
124133
# Fetch the full main ref so merge-base ancestry checks keep working
125134
# for older tagged commits that are still contained in main.
126135
git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
136+
if [[ "${RELEASE_REF}" =~ ^[0-9a-fA-F]{40}$ ]]; then
137+
MAIN_SHA="$(git rev-parse origin/main)"
138+
if [[ "${RELEASE_SHA}" != "${MAIN_SHA}" ]]; then
139+
echo "Validation-only SHA mode only supports the current origin/main HEAD." >&2
140+
exit 1
141+
fi
142+
RELEASE_TAG="v$(node -p "require('./package.json').version")"
143+
export RELEASE_TAG
144+
echo "Validation-only SHA mode: using synthetic release tag ${RELEASE_TAG} for package metadata checks."
145+
else
146+
RELEASE_TAG="${RELEASE_REF}"
147+
export RELEASE_TAG
148+
fi
127149
pnpm release:openclaw:npm:check
128150
151+
# KEEP THIS LANE LIMITED TO FAST, REPEATABLE RELEASE READINESS CHECKS.
152+
# IF A CHECK CAN TAKE A LONG TIME, NEEDS LIVE CREDENTIALS, OR IS KNOWN TO BE FLAKY,
153+
# IT BELONGS IN openclaw-release-checks.yml INSTEAD OF BLOCKING npm PUBLISH.
129154
- name: Verify release contents
130155
run: pnpm release:check
131156

132-
- name: Validate live cache credentials
133-
if: ${{ github.ref == 'refs/heads/main' }}
134-
env:
135-
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
136-
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
137-
run: |
138-
set -euo pipefail
139-
if [[ -z "${OPENAI_API_KEY}" ]]; then
140-
echo "Missing OPENAI_API_KEY secret for release live cache validation." >&2
141-
exit 1
142-
fi
143-
if [[ -z "${ANTHROPIC_API_KEY}" ]]; then
144-
echo "Missing ANTHROPIC_API_KEY secret for release live cache validation." >&2
145-
exit 1
146-
fi
147-
148-
- name: Verify live prompt cache floors
149-
if: ${{ github.ref == 'refs/heads/main' }}
150-
env:
151-
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
152-
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
153-
OPENCLAW_LIVE_CACHE_TEST: "1"
154-
OPENCLAW_LIVE_TEST: "1"
155-
run: pnpm test:live:cache
156-
157157
- name: Pack prepared npm tarball
158158
id: packed_tarball
159159
env:
@@ -242,7 +242,7 @@ jobs:
242242

243243
validate_publish_request:
244244
if: ${{ !inputs.preflight_only && !inputs.promote_beta_to_latest }}
245-
runs-on: ubuntu-latest
245+
runs-on: blacksmith-16vcpu-ubuntu-2404
246246
permissions:
247247
contents: read
248248
steps:
@@ -267,7 +267,8 @@ jobs:
267267
fi
268268
269269
publish_openclaw_npm:
270-
# npm trusted publishing + provenance requires a GitHub-hosted runner.
270+
# KEEP THE REAL RELEASE/PUBLISH PATH ON A GITHUB-HOSTED RUNNER.
271+
# npm trusted publishing + provenance requires this to stay on ubuntu-latest.
271272
needs: [validate_publish_request]
272273
if: ${{ !inputs.preflight_only && !inputs.promote_beta_to_latest }}
273274
runs-on: ubuntu-latest
@@ -407,6 +408,9 @@ jobs:
407408
bash scripts/openclaw-npm-publish.sh --publish "${publish_target}"
408409
409410
promote_beta_to_latest:
411+
# KEEP THE MUTATING RELEASE PATH ON A GITHUB-HOSTED RUNNER TOO.
412+
# This job changes the public npm dist-tags, so we keep it aligned with the
413+
# real release path instead of moving it onto the larger Blacksmith runners.
410414
if: ${{ inputs.promote_beta_to_latest }}
411415
runs-on: ubuntu-latest
412416
environment: npm-release

‎.github/workflows/openclaw-release-checks.yml‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
name: OpenClaw Release Checks
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
ref:
7+
description: Existing release tag or current full 40-character main commit SHA to validate (for example v2026.4.12 or 0123456789abcdef0123456789abcdef01234567)
8+
required: true
9+
type: string
10+
11+
concurrency:
12+
group: openclaw-release-checks-${{ inputs.ref }}
13+
cancel-in-progress: false
14+
15+
env:
16+
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
17+
NODE_VERSION: "24.x"
18+
PNPM_VERSION: "10.32.1"
19+
20+
jobs:
21+
# THIS WORKFLOW EXISTS SO RELEASE-TIME LIVE CHECKS CAN RUN WITHOUT BLOCKING npm PUBLISH.
22+
# PUT THE SLOWER, EXTERNAL, OR SOMETIMES-FLAKY RELEASE CHECKS HERE INSTEAD OF
23+
# RECOUPLING THEM TO openclaw-npm-release.yml.
24+
validate_release_live_cache:
25+
runs-on: blacksmith-16vcpu-ubuntu-2404
26+
timeout-minutes: 60
27+
permissions:
28+
contents: read
29+
steps:
30+
- name: Require main workflow ref for release checks
31+
env:
32+
WORKFLOW_REF: ${{ github.ref }}
33+
run: |
34+
set -euo pipefail
35+
if [[ "${WORKFLOW_REF}" != "refs/heads/main" ]]; then
36+
echo "Release checks must be dispatched from main so the workflow logic and secrets stay canonical." >&2
37+
exit 1
38+
fi
39+
40+
- name: Validate ref input
41+
env:
42+
RELEASE_REF: ${{ inputs.ref }}
43+
run: |
44+
set -euo pipefail
45+
if [[ ! "${RELEASE_REF}" =~ ^v[0-9]{4}\.[1-9][0-9]*\.[1-9][0-9]*((-beta\.[1-9][0-9]*)|(-[1-9][0-9]*))?$ ]] && [[ ! "${RELEASE_REF}" =~ ^[0-9a-fA-F]{40}$ ]]; then
46+
echo "Expected an existing release tag or current full 40-character main commit SHA, got: ${RELEASE_REF}" >&2
47+
exit 1
48+
fi
49+
50+
- name: Checkout selected ref
51+
uses: actions/checkout@v6
52+
with:
53+
ref: ${{ inputs.ref }}
54+
fetch-depth: 0
55+
56+
- name: Resolve checked-out SHA
57+
id: ref
58+
run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
59+
60+
- name: Validate selected ref is on main
61+
env:
62+
RELEASE_REF: ${{ inputs.ref }}
63+
run: |
64+
set -euo pipefail
65+
git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
66+
if [[ "${RELEASE_REF}" =~ ^[0-9a-fA-F]{40}$ ]]; then
67+
MAIN_SHA="$(git rev-parse origin/main)"
68+
if [[ "$(git rev-parse HEAD)" != "${MAIN_SHA}" ]]; then
69+
echo "Commit SHA mode only supports the current origin/main HEAD. Use a release tag for older commits." >&2
70+
exit 1
71+
fi
72+
else
73+
git merge-base --is-ancestor HEAD origin/main
74+
fi
75+
76+
- name: Setup Node environment
77+
uses: ./.github/actions/setup-node-env
78+
with:
79+
node-version: ${{ env.NODE_VERSION }}
80+
pnpm-version: ${{ env.PNPM_VERSION }}
81+
install-bun: "true"
82+
use-sticky-disk: "false"
83+
84+
- name: Validate live cache credentials
85+
env:
86+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
87+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
88+
run: |
89+
set -euo pipefail
90+
if [[ -z "${OPENAI_API_KEY}" ]]; then
91+
echo "Missing OPENAI_API_KEY secret for release checks." >&2
92+
exit 1
93+
fi
94+
if [[ -z "${ANTHROPIC_API_KEY}" ]]; then
95+
echo "Missing ANTHROPIC_API_KEY secret for release checks." >&2
96+
exit 1
97+
fi
98+
99+
# KEEP RELEASE-TIME LIVE COVERAGE HERE SO OPERATORS CAN RUN IT ON DEMAND
100+
# WITHOUT MAKING THE PUBLISH PATH WAIT FOR A SLOW OR FLAKY EXTERNAL CHECK.
101+
- name: Verify live prompt cache floors
102+
env:
103+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
104+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
105+
OPENCLAW_LIVE_CACHE_TEST: "1"
106+
OPENCLAW_LIVE_TEST: "1"
107+
run: pnpm test:live:cache
108+
109+
- name: Summarize validated ref
110+
env:
111+
RELEASE_REF: ${{ inputs.ref }}
112+
RELEASE_SHA: ${{ steps.ref.outputs.sha }}
113+
run: |
114+
{
115+
echo "## Release checks"
116+
echo
117+
echo "- Requested ref: \`${RELEASE_REF}\`"
118+
echo "- Validated SHA: \`${RELEASE_SHA}\`"
119+
echo "- Check: \`pnpm test:live:cache\`"
120+
} >> "$GITHUB_STEP_SUMMARY"

‎docs/reference/RELEASING.md‎

Lines changed: 41 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,29 @@ OpenClaw has three public release lanes:
4141
`dist/*` release artifacts and Control UI bundle exist for the pack
4242
validation step
4343
- Run `pnpm release:check` before every tagged release
44-
- Main-branch npm preflight also runs
44+
- Release checks now run in a separate manual workflow:
45+
`OpenClaw Release Checks`
46+
- This split is intentional: keep the real npm release path short,
47+
deterministic, and artifact-focused, while slower live checks stay in their
48+
own lane so they do not stall or block publish
49+
- Release checks must be dispatched from the `main` workflow ref so the
50+
workflow logic and secrets stay canonical
51+
- That workflow accepts either an existing release tag or the current full
52+
40-character `main` commit SHA
53+
- In commit-SHA mode it only accepts the current `origin/main` HEAD; use a
54+
release tag for older release commits
55+
- `OpenClaw NPM Release` validation-only preflight also accepts the current
56+
full 40-character `main` commit SHA without requiring a pushed tag
57+
- That SHA path is validation-only and cannot be promoted into a real publish
58+
- In SHA mode the workflow synthesizes `v<package.json version>` only for the
59+
package metadata check; real publish still requires a real release tag
60+
- Both workflows keep the real publish and promotion path on GitHub-hosted
61+
runners, while the non-mutating validation path can use the larger
62+
Blacksmith Linux runners
63+
- That workflow runs
4564
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
46-
before packaging the tarball, using both `OPENAI_API_KEY` and
47-
`ANTHROPIC_API_KEY` workflow secrets
65+
using both `OPENAI_API_KEY` and `ANTHROPIC_API_KEY` workflow secrets
66+
- npm release preflight no longer waits on the separate release checks lane
4867
- Run `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
4968
(or the matching beta/correction tag) before approval
5069
- After npm publish, run
@@ -85,7 +104,8 @@ OpenClaw has three public release lanes:
85104
`OpenClaw NPM Release` accepts these operator-controlled inputs:
86105

87106
- `tag`: required release tag such as `v2026.4.2`, `v2026.4.2-1`, or
88-
`v2026.4.2-beta.1`
107+
`v2026.4.2-beta.1`; when `preflight_only=true`, it may also be the current
108+
full 40-character `main` commit SHA for validation-only preflight
89109
- `preflight_only`: `true` for validation/build/package only, `false` for the
90110
real publish path
91111
- `preflight_run_id`: required on the real publish path so the workflow reuses
@@ -94,10 +114,17 @@ OpenClaw has three public release lanes:
94114
- `promote_beta_to_latest`: `true` to skip publish and move an already-published
95115
stable `beta` build onto `latest`
96116

117+
`OpenClaw Release Checks` accepts these operator-controlled inputs:
118+
119+
- `ref`: existing release tag or the current full 40-character `main` commit
120+
SHA to validate
121+
97122
Rules:
98123

99124
- Stable and correction tags may publish to either `beta` or `latest`
100125
- Beta prerelease tags may publish only to `beta`
126+
- Full commit SHA input is allowed only when `preflight_only=true`
127+
- Release checks commit-SHA mode also requires the current `origin/main` HEAD
101128
- The real publish path must use the same `npm_dist_tag` used during preflight;
102129
the workflow verifies that metadata before publish continues
103130
- Promotion mode must use a stable or correction tag, `preflight_only=false`,
@@ -110,12 +137,18 @@ Rules:
110137
When cutting a stable npm release:
111138

112139
1. Run `OpenClaw NPM Release` with `preflight_only=true`
140+
- Before a tag exists, you may use the current full `main` commit SHA for a
141+
validation-only dry run of the preflight workflow
113142
2. Choose `npm_dist_tag=beta` for the normal beta-first flow, or `latest` only
114143
when you intentionally want a direct stable publish
115-
3. Save the successful `preflight_run_id`
116-
4. Run `OpenClaw NPM Release` again with `preflight_only=false`, the same
144+
3. Run `OpenClaw Release Checks` separately with the same tag or the
145+
full current `main` commit SHA when you want live prompt cache coverage
146+
- This is separate on purpose so live coverage stays available without
147+
recoupling long-running or flaky checks to the publish workflow
148+
4. Save the successful `preflight_run_id`
149+
5. Run `OpenClaw NPM Release` again with `preflight_only=false`, the same
117150
`tag`, the same `npm_dist_tag`, and the saved `preflight_run_id`
118-
5. If the release landed on `beta`, run `OpenClaw NPM Release` later with the
151+
6. If the release landed on `beta`, run `OpenClaw NPM Release` later with the
119152
same stable `tag`, `promote_beta_to_latest=true`, `preflight_only=false`,
120153
`preflight_run_id` empty, and `npm_dist_tag=beta` when you want to move that
121154
published build to `latest`
@@ -129,6 +162,7 @@ documented and operator-visible.
129162
## Public references
130163

131164
- [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml)
165+
- [`.github/workflows/openclaw-release-checks.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-release-checks.yml)
132166
- [`scripts/openclaw-npm-release-check.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/openclaw-npm-release-check.ts)
133167
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
134168
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)

0 commit comments

Comments
 (0)