---
name: release-openclaw-ci
description: "Run, watch, debug, and summarize OpenClaw full release CI, release checks, live provider gates, install/update proofs, and release-secret preflights."
---

# OpenClaw Release CI

Use this with `$release-openclaw-maintainer` and `$openclaw-testing` when a release candidate needs full validation, install/update proof, live provider checks, or CI recovery.

## Guardrails

- No version bump, tag, npm publish, GitHub release, or release promotion without explicit operator approval.
- After compaction, resume, or new steering, rewrite the effective goal and
  current phase from the latest explicit operator instruction. Do not merge old
  scope back into the active release.
- Hold the release scope once a release branch or Code SHA exists. Validate and
  ship that exact release; do not turn moving `main` into a second work queue.
- Record **C (candidate), Q (test qualification), P (admission/aggregate/verifier/publisher),
  rerun group, profile, effective soak, and context/transport refs**. New
  candidate test qualification defaults to Q=C, including the complete workflow,
  reusable workflow, local action, script, planner, contract, and coverage closure.
  Code SHA and Release SHA remain lifecycle roles, not extra workflow identities.
- The candidate helper accepts an absent release tag or an existing lightweight
  or annotated tag resolving to the exact candidate SHA. A conflicting tag or
  failed remote lookup stops validation; never move a tag to recover.
- Freeze C/Q and independently select trusted P on main or a protected
  publication tag. C/Q need not be an ancestor of P. Missing candidate contracts
  require a deliberate backport; never silently substitute newer main tooling.
- Apply a release firebreak after the Code SHA is frozen. Admit only confirmed
  product defects, wrong or unverifiable package bytes, security
  defects, or failures that make publication impossible. Queue other findings
  for postpublish confidence or the next beta. Dependency advisories are never
  firebreak admissions: record them as release evidence and queue the bump on
  `main` after publication; only known malware stops publication.
- Frozen CI children use Q's Node shard planner and measured
  costs, while discovering and executing tests from the candidate checkout.
  Hosted full-release plans split measured rows above 12 minutes; preserve file
  coverage, worker limits, and complete timing generations. An indivisible
  over-budget owner must be split rather than increasing the release budget.
  After the child completes, closeout runs `scripts/ci-shard-timings-refresh.mts`
  for that exact run and commits generated costs; do not hand-edit measurements.
- Candidate tests run their own frozen Q closure; admitted P owns FRV's aggregate
  decision and checked-in waiver policy. Main-only checks and
  future-main scenarios are not implicit release requirements. Fixing a frozen
  qualification harness means a new C/Q, with newly bound evidence. A P-only
  admission/aggregate/verifier/publisher repair can keep C/Q and their original evidence.
- Protected lightweight `release-publish/<12sha>-<provenance-run>` tags identify
  P, not Q. The suffix records tag-creation provenance, not the current parent.
  Publication helpers retain their `--workflow-sha <P>` argument; the FRV helper's
  `--workflow-sha` instead selects Q and must equal C on the candidate route.
- Touch `main` only for an operator-requested change or the smallest critical
  main-owned blocker that prevents this release and cannot be handled from the
  release branch. Main's CI health never gates a release. If a release-tooling
  landing is blocked by `main` failures it does not cause, prove on a clean
  `main` checkout that the failure already exists there, record it in the PR
  body, and merge; during an active release an admin merge is allowed for that
  exact case. A separate lane fixes red `main` in parallel, off the release's
  critical path.
- Land tooling-only fixes on `main` with the `release-fast-lane` label added
  before the push (see [Release tooling fast lane](#release-tooling-fast-lane)): `openclaw/ci-gate`
  then runs lint, types, guards, dependencies, docs, and the changed Node rows
  only. Land through the [native maintainer workflow](../openclaw-pr-maintainer/references/landing.md).
  That workflow owns review and landing requirements, including the advisory
  ClawSweeper policy; the label changes only CI selection.
- `OPENCLAW_RELEASE_RUNNER_GROUP` optionally routes validation parents and workers
  and the Release Publish parent plus its publish children to reserved capacity
  with unchanged labels; credentialed publish and approval jobs stay on default
  GitHub-hosted labels. Configure eligible runners and repo
  access first; unset preserves ordinary routing. Shared workers inherit the
  caller group; PR/main CI and unrelated scheduled work remain outside it.
- Check the nightly parent for the Code SHA before dispatching a fresh main validation; it seals per-child receipts that exact-target dispatches adopt when inputs match. The nightly runs this explicit trusted-main helper route (`--sha <main-sha> --workflow-sha <main-sha> --trusted-workflow-ref main`), so its parent runs on a `release-ci/<sha12>-<id>` branch, not `main`.
- FRV must conclude success under pinned P's
  [checked-in waiver policy](../../../docs/reference/full-release-validation/evidence.md#release-tooling-waivers);
  all other required lanes must pass. See
  [Publication requirements](#publication-requirements). Stable tags require stable/full
  evidence, soak, and blocking performance. Beta-profile evidence cannot qualify
  stable. Soak and performance cannot be waived. All-group
  qualification requires all nine Linux/Windows/macOS Gateway install/upgrade
  combinations. Preserve first failures, identity, and complete evidence.
- Native macOS, Windows, Linux, and Android publication is independent of
  npm/ClawHub, GitHub finalization, and main closeout. Each platform retains
  its own signing, qualification, artifact, and updater requirements; report
  pending platforms accurately and repair native-only failures in parallel.
- Do not set GitHub secrets from unvalidated 1Password candidates. If a candidate returns 401/403, leave the existing secret alone and report the exact missing provider.
- Use `$one-password` for secret reads/writes: one persistent tmux session, targeted items only, no secret output.
- Watch one parent run with `pnpm frv watch --run <parent>` (see [Watch](#watch)).
  Avoid broad `gh run view` polling loops; REST quota is easy to burn.
- Fetch logs only for failed or currently-blocking jobs. If quota is low, stop polling and wait for reset.
- Treat live-provider flakes separately from code failures: prove key validity, provider HTTP status, retry evidence, and exact failing lane before editing code.
- When diagnosing a live-provider failure, a model-list response proves
  authentication, not billing or inference entitlement. Confirm the credential
  with a real completion probe before treating it as valid. Fix the credential
  first; do not add an alternate auth path merely to bypass a failed release
  credential.
- Full Release Validation separates exact-child dispatch, Release Decision,
  and Diagnostic Drain. With `fail_fast=false`, it makes zero child
  cancellation calls; Diagnostic Drain follows every selected child to
  terminal unless the collector itself is cancelled or loses GitHub API
  access. With
  `fail_fast=true`, Release Decision may cancel only the exact still-active
  child that owns a blocking failure.
- Same-parent continuation requires the original root to have been dispatched
  with `fail_fast=false`. The controller verifies that exact logged input
  before any rerun mutation.
- A parent that produced its own sealed candidate artifacts cannot be continued:
  GitHub reruns make those prior-attempt artifacts unavailable. Keep the
  candidate and qualification SHAs frozen, supersede that parent, and start a fresh
  all-group Full Release Validation.
- After dispatch, one immutable execution-plan artifact records the original
  parent attempt, exact child tuples and titles, selected coverage, gates, and
  reuse identity. The same bytes are saved under an exact run-ID cache key.
  Decision, Drain, manifest writing, evidence validation, and final verification
  consume the artifact for their current attempt. A collector retry restores
  the cached plan, validates it, re-uploads its artifact, and adopts the same
  children; missing plan state is an orchestration failure, not permission to
  reconstruct the plan or redispatch.
- Reused evidence is not trusted merely because plan sealing found it. Release
  Decision repeats the sealed target SHA, evidence SHA, policy, changed paths,
  selected run, root run, source manifest, trusted tooling identity, and
  exact-child checks before returning `passed`.
- Parent retries select the newest Decision and Drain artifacts independently;
  both must bind the same immutable plan even when their source attempts differ.
- Child retries are part of the same immutable plan only when the child run ID,
  workflow path, ref, Q SHA, dispatch title, event, target, candidate, and
  validation inputs remain exact. Newer child attempts replace matching jobs;
  jobs absent from a newer attempt carry forward. A duplicate job identity,
  missing attempt, regressed attempt, or changed tuple fails closed. `frv status`
  and `continue` allow up to 60 seconds of read-only reconciliation when GitHub
  temporarily returns duplicate jobs in the newest retry attempt. The run tuple
  and attempt stay pinned; persistent duplicates and older-attempt conflicts
  remain errors.
- Use `pnpm frv status|watch|rerun --job|rerun --child|continue --failed|verify` for attempt-aware recovery.
  The controller is stateless: the immutable execution plan, exact GitHub run
  attempts, Diagnostic Drain, and final manifest are the only authorities. It
  never writes a tag, package, registry entry, release candidate, or
  publication.
- Post-merge controller proof must use the reviewed landed SHA on protected
  `main` through the non-release `FRV Proof Broker` and `FRV Proof Fixture`.
  Dispatch the broker with the merged pull request number and exact landed
  commit. The broker must require that pull request's merge commit to match the
  landed commit, prove the landed commit is identical to or an ancestor of its
  trusted workflow SHA, and repeat authority, merge, and ancestry checks
  immediately before rerunning the fixture.
  Require the exact fixed no-op fixture run to advance from its intentional
  attempt-one failure to an attempt-two pass. The broker must emit its receipt
  without creating a release candidate, release artifact, publication,
  repository ref, replacement parent, or other workflow mutation. This is the
  hosted GitHub targeted-job rerun proof; focused controller tests own immutable
  plan eligibility, green-attempt preservation, same-parent collection, and
  strict-verifier invocation. Never use a real Full Release Validation run for
  this proof. See
  [Full Release Validation](/reference/full-release-validation#post-merge-continuation-proof).
- Use one release operator, one `frv watch`, and at most one
  investigator for the current failed surface. Do not build audit-review-plan
  trees around a single workflow transition.
- For regular beta/stable releases, Code SHA may already contain final notes
  and serve as Release SHA. One successful fresh full parent may qualify both
  roles and their exact publication bytes. If notes change afterward, a later
  Release SHA may reuse product evidence only when its complete delta from
  Code SHA changes the selected `CHANGELOG/YYYY.M.PATCH.md` and optionally
  `CHANGELOG.md` and `CHANGELOG/records/YYYY.M.PATCH.md`, with no other paths,
  renames, or deletions; its changed bytes still need qualification.
- Extended-stable validates one exact branch tip; it does not reuse the regular
  Code-SHA/Release-SHA evidence model.
- In a sparse worktree or Testbox source sync, first confirm `package.json`,
  `pnpm-lock.yaml`, and every source path the selected check reads. If any are
  absent, that checkout cannot validate a release dependency or Docker lane:
  stop and use the repo remote changed gate or a full task worktree. When the
  inputs are present and a release fix changes `package.json` or
  `pnpm-lock.yaml`, rebuild only the task-owned disposable box with
  `CI=true pnpm install --frozen-lockfile`, then run an explicit
  `require.resolve()` probe before Docker or focused tests. The CI flag permits
  pnpm to recreate a prewarmed modules directory without an interactive
  confirmation. Do not weaken the lockfile or label sparse-checkout failures
  as product/Docker failures.
- If the candidate is rebased or its base SHA changes after warmup, stop the
  task-owned box and warm a fresh one before testing. Testbox source sync is
  relative to the warmed source tree; continuing can mix an old base file with
  a new candidate diff and produce false lockfile or Docker failures.
- Reused Testboxes are checked against their recorded source after their first successful run.
  Source-only edits may reuse the lease; base, dependency, wrapper, or Testbox
  workflow drift requires a fresh lease. Do not set
  `OPENCLAW_TESTBOX_ALLOW_STALE=1` for release evidence.
- For a committed release candidate with the supported capsule-aware wrapper,
  run `node scripts/crabbox-wrapper.mjs run --blacksmith-ref main -- <command>`
  from that candidate's checkout when using Testbox. The capsule preserves
  candidate source and frozen dependencies while `main` supplies current
  admission limits. If the candidate lacks that wrapper contract, use the
  exact-target release-validation route below with separate Validation and
  Tooling SHAs. Do not dispatch candidate Testbox workflow refs or borrow
  another checkout's wrapper.

## Keep FRV off the idle path

Optimize time to the next **passing** Full Release Validation. Remote FRV is
usually the long pole; use its runtime for diagnosis, repairs, review, and
focused proof. This is scheduling guidance, not a new checklist, approval step,
or demand for certainty before dispatch. Existing release gates still apply.

- **Start remote qualification promptly.** Favor starting remote FRV while
  useful local checks run alongside it, rather than finishing those checks
  first. If the remote run passes, that overlap saves an entire cycle; if local
  work finds a defect, the run can be superseded through the existing recovery
  path. Uncertainty alone is not a reason to leave remote validation idle.
- **Repair as failures arrive.** Use the watcher to spot failures and start
  diagnosis and fixes while other lanes drain. Prioritize known non-flake
  failures over optional confidence checks. Use independent repair lanes when
  helpful, and integrate fixes as they become ready rather than waiting for
  the final diagnostic report to start work.
- **Aim to be ready when diagnostics finish.** Ideally, fixes for the drained
  failures are already on the branch, with focused proof and review done, by
  drain completion. This is an overlap goal, not a deadline or another gate.
  If a repair takes longer, keep working it; avoid filling the gap with
  redundant checks or process overhead.
- **Fix the whole known set before the next FRV.** Include fixes for every
  known non-flake failure affecting the next run, whether in the candidate,
  qualification harness, or trusted tooling. The waste to avoid is knowingly
  launching another full cycle with failure B still unfixed after fixing A.
  This does not mean proving there are no undiscovered failures or resolving
  unrelated issues before running again.
- **Use retries strategically.** An eligible targeted retry can run while
  unrelated diagnostics continue. Use the existing
  [retry budget](#run-identity-and-retry-budget) for flakes or repaired external
  prerequisites and retain valid green evidence. A repeat of an unchanged
  deterministic failure buys little; fix it instead. When a fresh parent is
  needed, include the known fixes and get it running without optional delays.

## Deferred CI recovery

Release validation does not pause CI or supporting workflows. The legacy
`OPENCLAW_RELEASE_PRIORITY_RUN` variable is ignored by current workflow
admission, and `pnpm frv prioritize --run` is retired. Use
`pnpm frv prioritize --restore <record>` to recover runs deferred by older
workflow revisions and clear their variable.
Keep the required publication proofs and soak gates intact.

## Continuous release readiness

The scheduled main validation (every 3 hours at :07 UTC) seals a direct-root manifest and per-child receipts for the exact main SHA.
For a same-day cut, land the release train on `main` (version and changelog) before the next scheduled run,
then cut `release/YYYY.M.PATCH` at that run's SHA so the Code SHA equals the validated SHA.
Per-child adoption matches exact target SHA, role, and dispatch inputs minus `dispatch_id`:
`productPerformance` is adopted because its inputs are context-free and match.
A stable candidate dispatched with `--target-ref release/YYYY.M.PATCH` resolves
`coveragePolicy=npm-stable-v1` and `ci_release_scope=npm-stable`, versus `full` scope on `main`.
`normalCi`, plugin prerelease, and release checks are re-dispatched because their inputs add
`target_context_ref`, plugin prerelease and release checks add `allow_frozen_target_scenario_omissions=true`, and scope differs.
Whole-parent adoption requires byte-identical manifest `validationInputs`, including `validationPurpose`,
`publicationSelectionJson`, `targetContextRef`, `targetVersion`, `allowUnreleasedChangelog`, and `coveragePolicy`;
a `main-qualification` nightly is never adopted wholesale by a `publish`-purpose stable candidate.
Purpose/context-crossing adoption is a verifier policy follow-up.

## Release tooling fast lane

Add the `release-fast-lane` label to a pull request before the push that should
use it; PR CI reads labels from the triggering event, and label events do not
start CI. For an already-pushed head, `gh pr ready --undo` then `gh pr ready`
re-triggers PR CI with the current labels. The label narrows `openclaw/ci-gate`
only on a canonical pull request whose changed paths are all release tooling:
`.github/workflows/**`, `scripts/**`, `test/scripts/**`,
`.agents/skills/release-*/**`, `docs/reference/RELEASING.md`, or independently
checked documentation. Admitted runs keep `security-fast`, `check-shard` (lint,
prod/test types, guards, dependencies, npm lock), `check-docs` when docs
changed, and the changed Node rows; the compact packing-policy full-plan proof
for planner edits is relaxed to those rows. Contracts, baseline ratchets,
bundled protocol, Bun launcher, additional checks, build artifacts (unless a
changed row needs `dist`), Control UI, Windows, macOS, iOS, Android, i18n, and
skills lanes are skipped and listed under "Release fast lane" in the preflight
step summary. A declined label (out-of-scope path, global Node input, fork,
push, dispatch, docs-only) logs a warning and leaves ordinary selection
untouched. The gate stays complete: every selected lane must pass, and hourly
full main CI covers the merged result. The label narrows only the CI gate: fork
heads are declined, and the [native maintainer workflow](../openclaw-pr-maintainer/references/landing.md)
still owns review and landing requirements.

## Run identity and retry budget

Record C, Q/ref, P/ref, target context ref, parent run id,
attempt, and phase before watching or recovering Full Release Validation. Keep
Code SHA and Release SHA as lifecycle roles in the ledger; they may name the
same commit. Record the
immutable Release Publish parent receipt separately from the tag's recorded source.

For the core and plugin npm mutations